fuchsia.hardware.display

PROTOCOLS

Controller

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

Interface for accessing the display hardware.

A display configuration can be separated into two parts: the layer layout and the layer contents. The layout includes all parts of a configuration other than the image handles. The active configuration is composed of the most recently applied layout and an active image from each layer - see SetLayerImage for details on how the active image is defined. Note the requirement that each layer has an active image. Whenever a new active configuration is available, it is immediately given to the hardware. This allows the layout and each layer's contents to advance independently when possible.

Performing illegal actions on the interface will result in the interface being closed.

AcknowledgeVsync

Request

Name	Type
cookie	uint64

ApplyConfig

Request

<EMPTY>

ApplyConfig2

Applies any pending changes to the current configuration. This will not apply pending changes to layers which are not on any display.

For each event in signal_fences, once the pending configuration is applied to and contents are displayed on all the displays in its displays bitmap, the fence signal will be signaled immediately.

Arguments

display_ids: Lists all display IDs which are used on the incoming configuration. Each display ID represents the corresponding bit in the display field of signal_fences.

signal_fences: Stores all fence events that will be signaled once the configuration is applied and display scopes of each event. See the definition of DisplayFences for details.

Error handling

 If the input is invalid, for example:
     - `signal_fences` contains invalid events
     - `display` has bits referring to display ID `INVALID_DISP_ID`.
 or the pending configuration cannot be applied, this call will
 silently fail, so the client should ensure its configuration is
 valid with CheckConfig().

Request

Name	Type
display_ids	vector<uint64>[32]
signal_fences	vector<DisplayFence>[32]

CheckConfig

Request

Name	Type
discard	bool

Response

Name	Type
res	ConfigResult
ops	vector<ClientCompositionOp>

CreateLayer

Request

<EMPTY>

Response

Name	Type
res	zx/status
layer_id	uint64

DestroyLayer

Request

Name	Type
layer_id	uint64

EnableVsync

Request

Name	Type
enable	bool

GetSingleBufferFramebuffer

Request

<EMPTY>

Response

Name	Type
res	zx/status
vmo	handle<vmo>?
stride	uint32

ImportBufferCollection

Request

Name	Type
collection_id	uint64
collection_token	fuchsia.sysmem/BufferCollectionToken

Response

Name	Type
res	zx/status

ImportEvent

Imports an event into the driver and associates it with the given id.

It is illegal for id to be equal to INVALID_DISP_ID, and it is undefined to import one event with two different ids or to import two different events with the same id (note that ids map well to koids).

If a client is reusing events, they must clear the signal before referencing the id again.

Request

Name	Type
event	handle<event>
id	uint64

ImportGammaTable

Import a gamma table for display calibration.

Each array is a quantized representation of the gamma curve for a single color channel. An input luminance in [0.0, 1.0] is mapped to an index between 0-255, and the value in the array is used as the output luminance. Rounding behavior is hardware-specific, and most often it will floor(input * 255.0), requiring an input luminance of 1.0 to get the max output luminance.

It is an error to use output luminances outside of [0.0, 1.0]. Hardware drivers may either clamp such values or disconnect a client that provides invalid tables.

Request

Name	Type
gamma_table_id	uint64
r	float32[256]
g	float32[256]
b	float32[256]

ImportImage

Request

Name	Type
image_config	ImageConfig
collection_id	uint64
index	uint32

Response

Name	Type
res	zx/status
image_id	uint64

ImportImageForCapture

Imports a buffer collection backed VMO into the display controller. The VMO will be used by display controller to capture the image being displayed. Returns ZX_OK along with an image_id. image_id must be used by the client to start capture and/or release resources allocated for capture. Returns ZX_ERR_NOT_SUPPORTED if controller does not support capture

Request

Name	Type
image_config	ImageConfig
collection_id	uint64
index	uint32

Response

Name	Type
result	Controller_ImportImageForCapture_Result

ImportVmoImage

Request

Name	Type
image_config	ImageConfig
vmo	handle<vmo>
offset	int32

Response

Name	Type
res	zx/status
image_id	uint64

IsCaptureSupported

Returns true if Capture is supported on the platform.

Request

<EMPTY>

Response

Name	Type
result	Controller_IsCaptureSupported_Result

OnClientOwnershipChange

Response

Name	Type
has_ownership	bool

OnDisplaysChanged

Response

Name	Type
added	vector<Info>
removed	vector<uint64>

OnVsync

Response

Name	Type
display_id	uint64
timestamp	uint64
images	vector<uint64>
cookie	uint64

ReleaseBufferCollection

Request

Name	Type
collection_id	uint64

ReleaseCapture

Releases resources allocated for capture. Returns ZX_ERR_NOT_SUPPORTED if controller does not support capture

Request

Name	Type
image_id	uint64

Response

Name	Type
result	Controller_ReleaseCapture_Result

ReleaseEvent

Releases the event imported with the given id.

If any images are currently using the given event, the event will still be waited up or signaled as appropriate before its resources are released. It is an error to reuse an ID while the active config has references to it.

Request

Name	Type
id	uint64

ReleaseGammaTable

Release an imported gamma table.

Subsequent calls to SetDisplayGammaTable cannot reference this table. It is legal to re-use the gamma_table_id after making this call. Releasing a table while it is set on a display is safe, and will not modify the output of the display.

Request

Name	Type
gamma_table_id	uint64

ReleaseImage

Request

Name	Type
image_id	uint64

SetBufferCollectionConstraints

Request

Name	Type
collection_id	uint64
config	ImageConfig

Response

Name	Type
res	zx/status

SetDisplayColorConversion

Request

Name	Type
display_id	uint64
preoffsets	float32[3]
coefficients	float32[9]
postoffsets	float32[3]

SetDisplayGammaTable

Set the gamma correction table for a display.

gamma_table_id must be a table registered with ImportGammaTable. It is safe to release a gamma table after using it here, and will not modify display output.

Request

Name	Type
display_id	uint64
gamma_table_id	uint64

SetDisplayLayers

Request

Name	Type
display_id	uint64
layer_ids	vector<uint64>

SetDisplayMode

Request

Name	Type
display_id	uint64
mode	Mode

SetLayerColorConfig

Request

Name	Type
layer_id	uint64
pixel_format	uint32
color_bytes	vector<uint8>

SetLayerCursorConfig

Request

Name	Type
layer_id	uint64
image_config	ImageConfig

SetLayerCursorPosition

Request

Name	Type
layer_id	uint64
x	int32
y	int32

SetLayerImage

Request

Name	Type
layer_id	uint64
image_id	uint64
wait_event_id	uint64
signal_event_id	uint64

SetLayerPrimaryAlpha

Request

Name	Type
layer_id	uint64
mode	AlphaMode
val	float32

SetLayerPrimaryConfig

Request

Name	Type
layer_id	uint64
image_config	ImageConfig

SetLayerPrimaryPosition

Request

Name	Type
layer_id	uint64
transform	Transform
src_frame	Frame
dest_frame	Frame

SetMinimumRgb

Set the minimum value of rgb channels. Valid range [0 255] inclusive. Returns ZX_ERR_NOT_SUPPORTED when the display hardware does not support this feature. This API is meant to address backlight bleeding that may occur on some hardware that have a specific type of panel and hardware assembly. The evolution of this API is highly hardware and product dependant and therefore as products evolve, this API may change or support for this API may become non-existent. Therefore, this API should be used with caution.

Request

Name	Type
minimum_rgb	uint8

Response

Name	Type
result	Controller_SetMinimumRgb_Result

SetVirtconMode

Request

Name	Type
mode	uint8

StartCapture

Starts capture. Client must provide a valid signal_event_id and image_id. signal_event_id must have been imported into the driver using ImportEvent FIDL API. Image_id is the id from ImportImageForCapture. The client will get notified once capture is complete via signal_event_id. Returns ZX_ERR_NOT_SUPPORTED if controller does not support capture

Request

Name	Type
signal_event_id	uint64
image_id	uint64

Response

Name	Type
result	Controller_StartCapture_Result

Provider

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

Provider for display controllers.

The driver supports two simultaneous clients - a primary client and a virtcon client. In some cases, the provider service may provide access to only one or the other; if the client tries to open the other then ZX_ERR_NOT_SUPPORTED will be returned.

OpenController

Open a primary client. device should be a handle to one endpoint of a channel that (on success) will become an open connection to a new instance of a display client device. A protocol request controller provides an interface to the Controller for the new device. Closing the connection to device will also close the controller interface. If the display device already has a primary controller then this method will return ZX_ERR_ALREADY_BOUND.

Request

Name	Type
device	handle<channel>
controller	request<Controller>

Response

Name	Type
s	zx/status

OpenVirtconController

Open a virtcon client. device should be a handle to one endpoint of a channel that (on success) will become an open connection to a new instance of a display client device. A protocol request controller provides an interface to the Controller for the new device. Closing the connection to device will also close the controller interface. If the display device already has a virtcon controller then this method will return ZX_ERR_ALREADY_BOUND.

Request

Name	Type
device	handle<channel>
controller	request<Controller>

Response

Name	Type
s	zx/status

STRUCTS

ClientCompositionOp

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

Field	Type	Description	Default
display_id	uint64	display_id and layer_id uniquely identify the subject of the opcode.	No default
layer_id	uint64	layer_id is 0 for whole-display issues like unsupported color conversion and gamma tables.	No default
opcode	ClientCompositionOpcode		No default

Controller_ImportImageForCapture_Response

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

Field	Type	Description	Default
image_id	uint64		No default

Controller_IsCaptureSupported_Response

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

Field	Type	Description	Default
supported	bool		No default

Controller_ReleaseCapture_Response

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

<EMPTY>

Controller_SetMinimumRgb_Response

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

<EMPTY>

Controller_StartCapture_Response

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

<EMPTY>

CursorInfo

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

Field	Type	Description	Default
width	uint32		No default
height	uint32		No default
pixel_format	uint32		No default

DisplayFence resource

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

Field	Type	Description	Default
event	handle<event>	The internal event object to signal.	No default
displays	uint64	A bitmap indicating the scope of displays the event will affect. Each bit in displays represents a display in an array defined elsewhere (e.g. for ApplyConfig2(), the array is display_ids.)	No default

Frame

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

Field	Type	Description	Default
x_pos	uint32		No default
y_pos	uint32		No default
width	uint32		No default
height	uint32		No default

ImageConfig

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

Field	Type	Description	Default
width	uint32		No default
height	uint32		No default
pixel_format	uint32		No default
type	uint32		TYPE_SIMPLE

Info

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

Field	Type	Description	Default
id	uint64		No default
modes	vector<Mode>		No default
pixel_format	vector<uint32>		No default
cursor_configs	vector<CursorInfo>		No default
manufacturer_name	string[128]		No default
monitor_name	string[128]		No default
monitor_serial	string[128]		No default
horizontal_size_mm	uint32	Physical horizontal size in millimeters. If this value is not available, set to a best guess value and set the flag	No default
vertical_size_mm	uint32	Physical vertical size in millimeters If this value is not available, set to a best guess value and set the flag	No default
using_fallback_size	bool	This flag is set if fallback horizontal and vertical sizes were used as opposed to actual values reported by the display.	No default

Mode

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

Field	Type	Description	Default
horizontal_resolution	uint32		No default
vertical_resolution	uint32		No default
refresh_rate_e2	uint32		No default
flags	uint32		No default

ENUMS

AlphaMode strict

Type: uint8

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

Name	Value	Description
DISABLE	0
PREMULTIPLIED	1
HW_MULTIPLY	2

ClientCompositionOpcode strict

Type: uint8

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

Name	Value	Description
CLIENT_USE_PRIMARY	0
CLIENT_MERGE_BASE	1
CLIENT_MERGE_SRC	2
CLIENT_FRAME_SCALE	3
CLIENT_SRC_FRAME	4
CLIENT_TRANSFORM	5
CLIENT_COLOR_CONVERSION	6
CLIENT_ALPHA	7
CLIENT_GAMMA	8

ConfigResult strict

Type: uint32

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

Name	Value	Description
OK	0
INVALID_CONFIG	1
UNSUPPORTED_CONFIG	2
TOO_MANY_DISPLAYS	3
UNSUPPORTED_DISPLAY_MODES	4

Transform strict

Type: uint8

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

Name	Value	Description
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

VirtconMode strict

Type: uint8

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

Name	Value	Description
INACTIVE	0
FALLBACK	1
FORCED	2

UNIONS

Controller_ImportImageForCapture_Result strict

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

Ordinal
Variant	Type	Description
1	response	Controller_ImportImageForCapture_Response
2	err	zx/status

Controller_IsCaptureSupported_Result strict

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

Ordinal
Variant	Type	Description
1	response	Controller_IsCaptureSupported_Response
2	err	zx/status

Controller_ReleaseCapture_Result strict

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

Ordinal
Variant	Type	Description
1	response	Controller_ReleaseCapture_Response
2	err	zx/status

Controller_SetMinimumRgb_Result strict

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

Ordinal
Variant	Type	Description
1	response	Controller_SetMinimumRgb_Response
2	err	zx/status

Controller_StartCapture_Result strict

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

Ordinal
Variant	Type	Description
1	response	Controller_StartCapture_Response
2	err	zx/status

CONSTANTS

Name	Value	Type	Description
APPLY_CONFIG_MAX_DISPLAYS	32	uint64	Maximum number of displays supported in an ApplyConfig2() call.
APPLY_CONFIG_MAX_SIGNAL_FENCES	32	uint64	Maximum number of signal_fences supported in an ApplyConfig2() call.
IDENTIFIER_MAX_LEN	128	uint32
INVALID_DISP_ID	0	uint64
MODE_INTERLACED	1	int32
TYPE_CAPTURE	10	uint32
TYPE_SIMPLE	0	uint32