sdk/fidl/fuchsia.hardware.display.types/layer.fidl

// Copyright 2023 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.hardware.display.types;

using fuchsia.images2;

// Rotations are applied counter-clockwise, and are applied before reflections.  Note: this doesn't
// affect the output region on the physical display; use the layer's `dest_frame` for that.  In
// other words, if you have a 600x300 image that you want to rotate 90 degrees without changing the
// aspect ratio, you need to use `ROT_90`, and also use a `dest_frame` of 300x600.
//
// The reflection enums refer to the axis across which reflection occurs.  For example, `REFLECT_X`
// means a reflection across the X-axis.  In other words: bottom becomes top.
type Transform = strict enum : uint8 {
    IDENTITY = 0;
    REFLECT_X = 1;
    REFLECT_Y = 2;
    ROT_90 = 3;
    ROT_180 = 4;
    ROT_270 = 5;
    ROT_90_REFLECT_X = 6;
    ROT_90_REFLECT_Y = 7;
};

type AlphaMode = strict enum : uint8 {
    /// Alpha is disabled for the plane (default).
    DISABLE = 0;
    /// Plane alpha is premultiplied.
    PREMULTIPLIED = 1;
    /// Hardware should multiply the alpha and color channels when blending.
    HW_MULTIPLY = 2;
};

type Frame = struct {
    /// (x_pos, y_pos) specifies the position of the upper-left corner
    /// of the frame.
    x_pos uint32;
    y_pos uint32;
    width uint32;
    height uint32;
};

type ClientCompositionOpcode = strict enum : uint8 {
    /// The client should convert the corresponding layer to a primary layer.
    CLIENT_USE_PRIMARY = 0;
    /// The client should compose all layers with CLIENT_MERGE_BASE and CLIENT_MERGE_SRC
    /// into a new, single primary layer at the CLIENT_MERGE_BASE layer's z-order. The
    /// driver must accept a fullscreen layer with the default pixel format, but may
    /// accept other layer parameters.
    ///
    /// CLIENT_MERGE_BASE will only be set on one layer per display.
    CLIENT_MERGE_BASE = 1;
    /// See CLIENT_MERGE_BASE.
    CLIENT_MERGE_SRC = 2;
    /// The client should provide a new image produced by scaling the source image
    /// such that the dimensions of the new image's src_frame and dest_frame are
    /// equal to the dimensions of the current image's dest_frame.
    CLIENT_FRAME_SCALE = 3;
    /// The client should provide a new image produced by clipping the source image
    /// to the region specified by src_frame.
    CLIENT_SRC_FRAME = 4;
    /// The client should provide a new image produced by applying the desired
    /// transformation, so that TRANSFORM_IDENTITY can be specified.
    CLIENT_TRANSFORM = 5;
    /// The client should apply the color conversion itself.
    CLIENT_COLOR_CONVERSION = 6;
    /// The client should apply the alpha itself.
    CLIENT_ALPHA = 7;
};

type PrimaryLayer = struct {
    image_metadata ImageMetadata;

    /// If `alpha_mode` is `AlphaMode.DISABLE`, the layer is opaque and
    /// `alpha_layer_val` is ignored.
    ///
    /// If `alpha_mode` is `AlphaMode.PREMULTIPLIED` or `HW_MULTIPLY`, the
    /// alpha used when blending is determined by the product of
    /// `alpha_layer_val` and any per-pixel alpha.
    ///
    /// Additionally, if `alpha_mode` is `AlphaMode.PREMULTIPLIED`, then the
    /// hardware must premultiply the color channel with `alpha_layer_val`
    /// before blending.
    ///
    /// `alpha_layer_val` must be in the range [0, 1].
    alpha_mode AlphaMode;
    alpha_layer_val float32;

    transform Transform;

    /// The source frame, where (0,0) is the top-left corner of the image. The
    /// client guarantees that src_frame lies entirely within the image.
    src_frame Frame;

    /// The destination frame, where (0,0) is the top-left corner of the
    /// composed output. The client guarantees that dest_frame lies entirely
    /// within the composed output.
    dest_frame Frame;
};

type ColorLayer = struct {
    /// The format of `color` bytes.
    format fuchsia.images2.PixelFormat;

    /// The color to use for the layer. The color is little-endian, and is
    /// guaranteed to be of the exact size of one pixel in `format`.
    color vector<uint8>:MAX;
};

type LayerConfig = strict union {
    1: primary PrimaryLayer;
    2: color ColorLayer;
};

type Layer = struct {
    /// z_index of the layer. See
    /// [`fuchsia.hardware.display.engine/Engine.CheckConfiguration`] and
    /// [`fuchsia.hardware.display.engine/Engine.ApplyConfiguration`].
    z_index uint32;
    cfg LayerConfig;
};