Google is committed to advancing racial equity for Black communities. See how.

fuchsia.hardware.display.controller

PROTOCOLS

DisplayControllerImpl

Defined in fuchsia.hardware.display.controller/display-controller.fidl

The client guarantees that check_configuration and apply_configuration are always made from a single thread. The client makes no other threading guarantees.

ApplyConfiguration

Applies the configuration.

All configurations passed to this function will be derived from configurations which have been successfully validated, with the only differences either being omitted layers or different image handles. To account for any layers which are not present, the driver must use the z_index values of the present layers to configure them as if the whole configuration was present.

Unlike with check_configuration, displays included in the configuration are not guaranteed to include any layers. Both omitted displays and displays with no layers can either be turned off or set to display a blank screen, but for displays with no layers there is a strong preference to display a blank screen instead of turn them off. In either case, the driver must drop all references to old images and invoke the vsync callback after doing so.

The driver must not retain references to the configuration after this function returns.

Request

NameType
display_config vector<DisplayConfig>

Response

NameType

CheckConfiguration

Validates the given configuration.

The configuration may not include all displays. Omitted displays should be treated as whichever of off or displaying a blank screen results in a more permissive validation.

All displays in a configuration will have at least one layer. The layers will be arranged in increasing z-order, and their z_index fields will be set consecutively.

Whether or not the driver can accept the configuration cannot depend on the particular image handles, as it must always be possible to present a new image in place of another image with a matching configuration. It also cannot depend on the cursor position, as that can be updated without another call to check_configuration.

display_cfg_result should be set to a CONFIG_DISPLAY_* error if the combination of display modes is not supported.

layer_cfg_result points to an array of arrays. The primary length is display_count, the secondary lengths are the corresponding display_cfg's layer_count. If display_cfg_result is CONFIG_DISPLAY_OK, any errors in layer configuration should be returned as a CLIENT* flag in the corresponding layer_cfg_result entry.

The driver must not retain references to the configuration after this function returns. TODO: Fix me...

Request

NameType
display_config vector<DisplayConfig>

Response

NameType
display_cfg_result uint32
layer_cfg_result vector<uint32>

GetSingleBufferFramebuffer

Request

NameType

Response

NameType
res zx/status
vmo handle<vmo>
stride uint32

GetSysmemConnection

Request

NameType
sysmem_handle handle<channel>

Response

NameType
s zx/status

ImportImage

Imports an image from a buffer collection into the driver. The driver should set image->handle.

Request

NameType
image Image
collection ZxUnownedHandle
index uint32

Response

NameType
s zx/status

ImportVmoImage

Imports a VMO backed image into the driver. The driver should set image->handle. The driver does not own the vmo handle passed to this function.

Request

NameType
image Image
vmo handle<vmo>
offset uint64

Response

NameType
s zx/status

ReleaseImage

Releases any driver state associated with the given image. The client guarantees that any images passed to apply_config will not be released until a vsync occurs with a more recent image.

Request

NameType
image Image

Response

NameType

SetBufferCollectionConstraints

Request

NameType
config Image
collection ZxUnownedHandle

Response

NameType
s zx/status

SetDisplayControllerInterface

The function will only be called once, and it will be called before any other functions are called.

Request

NameType
intf DisplayControllerInterface

Response

NameType

SetEld

Set ELD for one display.

This method is called independently from the CheckConfiguration and ApplyConfiguration methods. The display_id may be unconfigured at the time this method is called. raw_eld is the ELD raw data formatted according to the HDA specification version 1.0a section 7.3.3.34.1. https://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/high-definition-audio-specification.pdf The driver must not retain references to the ELD after this function returns.

Request

NameType
display_id uint64
raw_eld vector<uint8>

Response

NameType

DisplayControllerInterface

Defined in fuchsia.hardware.display.controller/display-controller.fidl

The client will not make any ZX_PROTOCOL_DISPLAY_CONTROLLER_IMPL calls into the device during these callbacks.

GetAudioFormat

Request

NameType
display_id uint64
fmt_idx uint32

Response

NameType
s zx/status
fmt fuchsia.hardware.audiotypes/AudioTypesAudioStreamFormatRange

OnDisplayVsync

|timestamp| is the ZX_CLOCK_MONOTONIC timestamp at which the vsync occurred. |handles| points to an array of image handles of each framebuffer being displayed, in increasing z-order.

The driver must call this function for all vsync events, even if the display has no images displayed.

Request

NameType
display_id uint64
timestamp zx/time
handle vector<uint64>

Response

NameType

OnDisplaysChanged

Callbacks which are invoked when displays are added or removed. |added_display_list| and |removed_display_list| point to arrays of the display ids which were added and removed. If |added_display_count| or |removed_display_count| is 0, the corresponding array can be NULL.

The driver must be done accessing any images which were on the removed displays.

The driver should call this function when the callback is registered if any displays are present.

Request

NameType
added_display vector<AddedDisplayArgs>
removed_display vector<uint64>

Response

NameType
display_info vector<AddedDisplayInfo>

STRUCTS

AddedDisplayArgs

Defined in fuchsia.hardware.display.controller/display-controller.fidl

A structure containing information a connected display.

NameTypeDescriptionDefault
display_id uint64 No default
edid_present bool

A flag indicating whether or not the display has a valid edid.

If true, the device should expose an ZX_PROTOCOL_I2C_IMPL device through get_protocol, in addition to the ZX_PROTOCOL_DISPLAY_CONTROLLER_IMPL protocol. Note that the i2c device will be called from the on_displays_changed callback, so care should be taken to avoid deadlocks or double-locking.

If no edid is present, then the meaning of display_config's mode structure is undefined, and drivers should ignore it in check_configuration and apply_configuration.

No default
panel Panel No default
pixel_format vector<uint32>

A list of pixel formats supported by the display. The first entry is the preferred pixel format.

No default
cursor_info vector<CursorInfo>

A list of cursor configurations most likely to be accepted by the driver. Can be null if cursor_count is 0.

The driver may reject some of these configurations in some circumstances, and it may accept other configurations, but at least one of these configurations should be valid at most times.

No default

AddedDisplayInfo

Defined in fuchsia.hardware.display.controller/display-controller.fidl

Out parameters will be populated before on_displays_changed returns.

NameTypeDescriptionDefault
is_hdmi_out bool No default
is_standard_srgb_out bool No default
audio_format_count uint32 No default
manufacturer_id string[4]

All strings are null-terminated. |manufacturer_id| is guaranteed to have length 3, all other strings may be empty.

No default
manufacturer_name string

non-null

No default
monitor_name string[14]

null-terminated

No default
monitor_serial string[14]

null-terminated

No default
horizontal_size_mm uint32 No default
vertical_size_mm uint32 No default

ColorLayer

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescriptionDefault
format ZxPixelFormat No default
color vector<uint8>

The color to use for the layer. The color is little-endian, and is guaranteed to be of the appropriate size.

No default

CursorInfo

Defined in fuchsia.hardware.display.controller/display-controller.fidl

Info about valid cursor configurations.

NameTypeDescriptionDefault
width uint32

The width and height of the cursor configuration, in pixels.

No default
height uint32 No default
format ZxPixelFormat No default

CursorLayer

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescriptionDefault
image Image No default
x_pos int32

The position of the top-left corner of the cursor's image. When being applied to a display, the cursor is guaranteed to have at least one pixel of overlap with the display.

No default
y_pos int32 No default

DisplayConfig

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescriptionDefault
display_id uint64

the display id to which the configuration applies

No default
mode DisplayMode No default
cc_flags uint32

Bitmask of COLOR_CONVERSION_* flags

No default
cc_preoffsets float32[3]

Color conversion is applied to each pixel according to the formula:

(cc_coefficients * (pixel + cc_preoffsets)) + cc_postoffsets

where pixel is a column vector consisting of the pixel's 3 components.

No default
cc_coefficients [3] No default
cc_postoffsets float32[3] No default
layer vector<Layer> No default
gamma_table_present bool

Flag to indicate valid gamma table

No default
apply_gamma_table bool

Flag to indicate whether display driver should re-apply gamma correction table to hardware

No default
gamma_red vector<float32>

Gamma Table (Red, Green and Blue)

No default
gamma_green vector<float32> No default
gamma_blue vector<float32> No default

DisplayMode

Defined in fuchsia.hardware.display.controller/display-controller.fidl

The video parameters which specify the display mode.

NameTypeDescriptionDefault
pixel_clock_10khz uint32 No default
h_addressable uint32 No default
h_front_porch uint32 No default
h_sync_pulse uint32 No default
h_blanking uint32 No default
v_addressable uint32 No default
v_front_porch uint32 No default
v_sync_pulse uint32 No default
v_blanking uint32 No default
flags uint32

A bitmask of MODE_FLAG_* values

No default

DisplayParams

Defined in fuchsia.hardware.display.controller/display-controller.fidl

A fallback structure to convey display information without an edid.

NameTypeDescriptionDefault
width uint32 No default
height uint32 No default
refresh_rate_e2 uint32 No default

Frame

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescriptionDefault
x_pos uint32

(|x_pos|, |y_pos|) specifies the position of the upper-left corner of the frame.

No default
y_pos uint32 No default
width uint32 No default
height uint32 No default

Image

Defined in fuchsia.hardware.display.controller/display-controller.fidl

A structure containing information about an image.

NameTypeDescriptionDefault
width uint32

The width and height of the image in pixels.

No default
height uint32 No default
pixel_format ZxPixelFormat

The pixel format of the image.

No default
type uint32

The type conveys information about what is providing the pixel data. If this is not IMAGE_TYPE_SIMPLE, it is up to the driver and buffer producer to agree on the meaning of the value through some mechanism outside the scope of this API.

No default
handle uint64

A driver-defined handle to the image. Each handle must be unique.

No default

Layer

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescriptionDefault
type LayerType No default
z_index uint32

z_index of the layer. See |check_configuration| and |apply_configuration|.

No default
cfg LayerConfig No default

PrimaryLayer

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescriptionDefault
image Image No default
alpha_mode Alpha

An ALPHA_* constant.

If |alpha_mode| == ALPHA_DISABLED, the layer is opaque and alpha_layer_val is ignored.

If |alpha_mode| == PREMULTIPLIED or HW_MULTIPLY and |alpha_layer_val| is NaN, the alpha used when blending is determined by the per-pixel alpha channel.

If |alpha_mode| == PREMULTIPLIED or HW_MULTIPLY and |alpha_layer_val| is not NaN, the alpha used when blending is the product of alpha_layer_val and any per-pixel alpha. Additionally, if alpha_mode == PREMULTIPLIED, then the hardware must premultiply the color channel with alpha_layer_val before blending.

If alpha_layer_val is not NaN, it will be in the range [0, 1].

No default
alpha_layer_val float32 No default
transform_mode FrameTransform No default
src_frame Frame

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.

No default
dest_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.

No default

ENUMS

Alpha strict

Type: uint8

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameValueDescription
DISABLE 0
PREMULTIPLIED 1
HW_MULTIPLY 2

Client strict

Type: uint32

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameValueDescription
USE_PRIMARY 1

The client should convert the corresponding layer to a primary layer.

MERGE_BASE 2

The client should compose all layers with MERGE_BASE and MERGE_SRC into a new, single primary layer at the MERGE_BASE layer's z-order. The driver must accept a fullscreen layer with the default pixel format, but may accept other layer parameters.

MERGE_BASE should only be set on one layer per display. If it is set on multiple layers, the client will arbitrarily pick one and change the rest to MERGE_SRC.

MERGE_SRC 4
FRAME_SCALE 8

The client should pre-scale the image so that src_frame's dimensions are equal to dest_frame's dimensions.

SRC_FRAME 16

The client should pre-clip the image so that src_frame's dimensions are equal to the image's dimensions.

TRANSFORM 32

The client should pre-apply the transformation so TRANSFORM_IDENTITY can be used.

COLOR_CONVERSION 64

The client should apply the color conversion.

ALPHA 128

The client should apply the alpha transformation itself.

GAMMA 256

The client cannot control the display gamma, and must accept the uncalibrated output. Clients are expected to produce linear buffers, and as such they cannot perform software gamma correction.

ColorConversion strict

Type: uint32

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameValueDescription
PREOFFSET 1

If set, use the 0 vector for the color conversion preoffset

COEFFICIENTS 2

If set, use the identity matrix for the color conversion coefficients

POSTOFFSET 4

If set, use the 0 vector for the color conversion postoffset

ConfigDisplay strict

Type: uint32

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameValueDescription
OK 0

The display mode configuration is valid. Note that this is distinct from whether or not the layer configuration is valid.

TOO_MANY 1

Error indicating that the hardware cannot simultaneously support the requested number of displays.

UNSUPPORTED_MODES 2

Error indicating that the hardware cannot simultaneously support the given set of display modes. To support a mode, the display must be able to display a single layer with width and height equal to the requested mode and the preferred pixel format.

FrameTransform strict

Type: uint32

Defined in fuchsia.hardware.display.controller/display-controller.fidl

Rotations are applied counter-clockwise, and are applied before reflections.

NameValueDescription
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

ImageType strict

Type: uint32

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameValueDescription
SIMPLE 0

The image is linear and VMO backed.

CAPTURE 10

The image is used for capture

LayerType strict

Type: uint32

Defined in fuchsia.hardware.display.controller/display-controller.fidl

Types of layers.

NameValueDescription
PRIMARY 0
CURSOR 1
COLOR 2

ModeFlag strict

Type: uint32

Defined in fuchsia.hardware.display.controller/display-controller.fidl

constants for display_config's mode_flags field

NameValueDescription
VSYNC_POSITIVE 1
HSYNC_POSITIVE 2
INTERLACED 4
ALTERNATING_VBLANK 8
DOUBLE_CLOCKED 16

UNIONS

LayerConfig strict

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescription
primary PrimaryLayer
cursor CursorLayer
color ColorLayer

Panel strict

Defined in fuchsia.hardware.display.controller/display-controller.fidl

NameTypeDescription
i2c_bus_id uint32

The bus_id to use to read this display's edid from the device's i2c protocol.

params DisplayParams

The display's parameters if an edid is not present.

CONSTANTS

NameValueTypeDescription
INVALID_DISPLAY_ID 0 uint32
INVALID_ID 0 uint32

TYPE ALIASES

NameValueDescription
ZxPixelFormat uint32
ZxUnownedHandle uint32