Package: android.hardware.graphics.composer@2.2

IComposerClient

interface IComposerClient extends @2.1::IComposerClient

Properties

PowerMode

enum PowerMode: @2.1::IComposerClient.PowerMode
Details
Members
ON_SUSPEND = 4
The display is configured as in ON but may stop applying display updates from the client.This is effectively a hint to the device that drawing to the display has been suspended and that the the device must remain on and continue displaying its current contents indefinitely until the power mode changes.
This mode may also be used as a signal to enable hardware-based functionality to take over the display and manage it autonomously to implement a low power always-on display.

PerFrameMetadataKey

enum PerFrameMetadataKey: int32_t

Following enums define keys for metadata defined by SMPTE ST 2086:2014 and CTA 861.3.

Details
Members
/**
SMPTE ST 2084:2014.Coordinates defined in CIE 1931 xy chromaticity space
DISPLAY_RED_PRIMARY_Y
SMPTE ST 2084:2014
DISPLAY_GREEN_PRIMARY_X
SMPTE ST 2084:2014
DISPLAY_GREEN_PRIMARY_Y
SMPTE ST 2084:2014
DISPLAY_BLUE_PRIMARY_X
SMPTE ST 2084:2014
DISPLAY_BLUE_PRIMARY_Y
SMPTE ST 2084:2014
WHITE_POINT_X
SMPTE ST 2084:2014
WHITE_POINT_Y
SMPTE ST 2084:2014
MAX_LUMINANCE
SMPTE ST 2084:2014.Units:nits max as defined by ST 2048:10, 000 nits
MIN_LUMINANCE
SMPTE ST 2084:2014
MAX_CONTENT_LIGHT_LEVEL
CTA 861.3
MAX_FRAME_AVERAGE_LIGHT_LEVEL
CTA 861.3

Command

enum Command: @2.1::IComposerClient.Command
Details
Members
SET_LAYER_PER_FRAME_METADATA = 0x303 << @ 2.1 :: IComposerClient . Command : OPCODE_SHIFT
SET_LAYER_PER_FRAME_METADATA has this pseudo prototype
setLayerPerFrameMetadata(Display display, Layer layer, vec<PerFrameMetadata>data);
Sets the PerFrameMetadata for the display.This metadata must be used by the implementation to better tone map content to that display.
This is a method that may be called every frame.Thus it's implemented using buffered transport.SET_LAYER_PER_FRAME_METADATA is the command used by the buffered transport mechanism.
SET_LAYER_FLOAT_COLOR = 0x40c << @ 2.1 :: IComposerClient . Command : OPCODE_SHIFT
SET_LAYER_COLOR has this pseudo prototype
setLayerColor(FloatColor color);
Sets the color of the given layer.If the composition type of the layer is not Composition::SOLID_COLOR, this call must succeed and have no other effect.

PerFrameMetadata

struct PerFrameMetadata {PerFrameMetadataKey key; float value}
Details
Members
key
value

FloatColor

struct FloatColor {float r; float g; float b; float a}
Details
Members
r
g
b
a

Methods

getPerFrameMetadataKeys

getPerFrameMetadataKeys (Display display)
generates (Error error, vec<PerFrameMetadataKey> keys)

Returns the PerFrameMetadataKeys that are supported by this device.

Details
Parameters
display
is the display on which to create the layer.
Generates
error
is NONE upon success.Otherwise, UNSUPPORTED if not supported on underlying HAL
keys
is the vector of PerFrameMetadataKey keys that are supported by this device.

getReadbackBufferAttributes

getReadbackBufferAttributes (Display display)
generates (Error error, PixelFormat format, Dataspace dataspace)

getReadbackBufferAttributes Returns the format which should be used when allocating a buffer for use by device readback as well as the dataspace in which its contents should be interpreted.

The width and height of this buffer must be those of the currently-active display configuration, and the usage flags must consist of the following:BufferUsage::CPU_READ | BufferUsage::GPU_TEXTURE | BufferUsage::COMPOSER_OUTPUT

The format and dataspace provided must be sufficient such that if a correctly-configured buffer is passed into setReadbackBuffer, filled by the device, and then displayed by the client as a full-screen buffer, the output of the display remains the same(subject to the note about protected content in the description of setReadbackBuffer).

If the active configuration or color mode of this display has changed since a previous call to this function, it must be called again prior to setting a readback buffer such that the returned format and dataspace can be updated accordingly.

Parameters:See also:setReadbackBuffer getReadbackBufferFence

Details
Parameters
display
- the display on which to create the layer.
Generates
error
is NONE upon success.Otherwise, BAD_DISPLAY when an invalid display handle was passed in.UNSUPPORTED if not supported on underlying HAL
format
- the format the client should use when allocating a device readback buffer
dataspace
- the dataspace to use when interpreting the contents of a device readback buffer

getReadbackBufferFence

getReadbackBufferFence (Display display)
generates (Error error, handle acquireFence)

getReadbackBufferFence Returns an acquire sync fence file descriptor which must signal when the buffer provided to setReadbackBuffer has been filled by the device and is safe for the client to read.

If it is already safe to read from this buffer, -1 may be returned instead.The client takes ownership of this file descriptor and is responsible for closing it when it is no longer needed.

This function must be called immediately after the composition cycle being captured into the readback buffer.The complete ordering of a readback buffer capture is as follows:

getReadbackBufferAttributes//Readback buffer is allocated//Many frames may pass

setReadbackBuffer validateDisplay presentDisplay getReadbackBufferFence//Implicitly wait on the acquire fence before accessing the buffer

Parameters:See also:getReadbackBufferAttributes setReadbackBuffer

Details
Parameters
display
- the display on which to create the layer.
Generates
error
- is HWC2_ERROR_NONE or one of the following errors:BAD_DISPLAY - an invalid display handle was passed in NO_RESOURCES - the readback operation was successful, but resulted in a different validate result than would have occurred without readback UNSUPPORTED - the readback operation was unsuccessful because of resource constraints, the presence of protected content, or other reasons;-1 must be returned for acquireFence
acquireFence
- a sync fence file descriptor as described above;pointer must be non-NULL

setReadbackBuffer

setReadbackBuffer (Display display, handle buffer, handle releaseFence)
generates (Error error)

setReadbackBuffer Sets the readback buffer to be filled with the contents of the next composition performed for this display(i.e ., the contents present at the time of the next validateDisplay/presentDisplay cycle).

This buffer must have been allocated as described in getReadbackBufferAttributes and is in the dataspace provided by the same.

If there is hardware protected content on the display at the time of the next composition, the area of the readback buffer covered by such content must be completely black.Any areas of the buffer not covered by such content may optionally be black as well.

The release fence file descriptor provided works identically to the one described for setOutputBuffer.

This function must not be called between any call to validateDisplay and a subsequent call to presentDisplay.

Parameters:See also:getReadbackBufferAttributes getReadbackBufferFence

Details
Parameters
display
- the display on which to create the layer.
buffer
- the new readback buffer
releaseFence
- a sync fence file descriptor as described in setOutputBuffer
Generates
error
- is HWC2_ERROR_NONE or one of the following errors:HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in HWC2_ERROR_BAD_PARAMETER - the new readback buffer handle was invalid

createVirtualDisplay_2_2

createVirtualDisplay_2_2 (uint32_t width, uint32_t height, PixelFormat formatHint, uint32_t outputBufferSlotCount)
generates (Error error, Display display, PixelFormat format)

createVirtualDisplay_2_2 Creates a new virtual display with the given width and height.The format passed into this function is the default format requested by the consumer of the virtual display output buffers.

The display must be assumed to be on from the time the first frame is presented until the display is destroyed.

Details
Parameters
width
is the width in pixels.
height
is the height in pixels.
formatHint
is the default output buffer format selected by the consumer.
outputBufferSlotCount
is the number of output buffer slots to be reserved.
Generates
error
is NONE upon success.Otherwise, UNSUPPORTED when the width or height is too large for the device to be able to create a virtual display.NO_RESOURCES when the device is unable to create a new virtual display at this time.
display
is the newly-created virtual display.
format
is the format of the buffer the device will produce.
Annotations
callflow
next="*"

getClientTargetSupport_2_2

getClientTargetSupport_2_2 (Display display, uint32_t width, uint32_t height, PixelFormat format, Dataspace dataspace)
generates (Error error)

getClientTargetSupport_2_2 Returns whether a client target with the given properties can be handled by the device.

This function must return true for a client target with width and height equal to the active display configuration dimensions, PixelFormat::RGBA_8888, and Dataspace::UNKNOWN.It is not required to return true for any other configuration.

Details
Parameters
display
is the display to query.
width
is the client target width in pixels.
height
is the client target height in pixels.
format
is the client target format.
dataspace
is the client target dataspace, as described in setLayerDataspace.
Generates
error
is NONE upon success.Otherwise, BAD_DISPLAY when an invalid display handle was passed in.UNSUPPORTED when the given configuration is not supported.
Annotations
callflow
next="*"

setPowerMode_2_2

setPowerMode_2_2 (Display display, PowerMode mode)
generates (Error error)

setPowerMode_2_2 Sets the power mode of the given display.The transition must be complete when this function returns.It is valid to call this function multiple times with the same power mode.

All displays must support PowerMode::ON and PowerMode::OFF.Whether a display supports PowerMode::DOZE or PowerMode::DOZE_SUSPEND may be queried using getDozeSupport.

Details
Parameters
display
is the display to which the power mode is set.
mode
is the new power mode.
Generates
error
is NONE upon success.Otherwise, BAD_DISPLAY when an invalid display handle was passed in.BAD_PARAMETER when mode was not a valid power mode.UNSUPPORTED when mode is not supported on this display.

getColorModes_2_2

getColorModes_2_2 (Display display)
generates (Error error, vec<ColorMode> modes)

Returns the color modes supported on this display.

All devices must support at least ColorMode::NATIVE.

Details
Parameters
display
is the display to query.
Generates
error
is NONE upon success.Otherwise, BAD_DISPLAY when an invalid display handle was passed in.
modes
is an array of color modes.

getRenderIntents

getRenderIntents (Display display, ColorMode mode)
generates (Error error, vec<RenderIntent> intents)

Returns the render intents supported by the specified display and color mode.

For SDR color modes, RenderIntent::COLORIMETRIC must be supported.For HDR color modes, RenderIntent::TONE_MAP_COLORIMETRIC must be supported.

Details
Parameters
display
is the display to query.
mode
is the color mode to query.
Generates
error
is NONE upon success.Otherwise, BAD_DISPLAY when an invalid display handle was passed in.BAD_PARAMETER when an invalid color mode was passed in.
intents
is an array of render intents.

setColorMode_2_2

setColorMode_2_2 (Display display, ColorMode mode, RenderIntent intent)
generates (Error error)

Sets the color mode and render intent of the given display.

The color mode and render intent change must take effect on next presentDisplay.

All devices must support at least ColorMode::NATIVE and RenderIntent::COLORIMETRIC, and displays are assumed to be in this mode upon hotplug.

Details
Parameters
display
is the display to which the color mode is set.
mode
is the color mode to set to.
intent
is the render intent to set to.
Generates
error
is NONE upon success.Otherwise, BAD_DISPLAY when an invalid display handle was passed in.BAD_PARAMETER when mode or intent is invalid UNSUPPORTED when mode or intent is not supported on this display.

getDataspaceSaturationMatrix

getDataspaceSaturationMatrix (Dataspace dataspace)
generates (Error error, float[4][4] matrix)

Returns the saturation matrix of the specified legacy dataspace.

The saturation matrix can be used to approximate the legacy dataspace saturation transform.It is to be applied on linear pixel values like this:

(in GLSL)linearSrgb = saturationMatrix * linearSrgb;

Details
Parameters
dataspace
must be Dataspace::SRGB_LINEAR.
Generates
error
is NONE upon success.Otherwise, BAD_PARAMETER when an invalid dataspace was passed in.
matrix
is the 4x4 column-major matrix used to approximate the legacy dataspace saturation operation.The last row must be[0.0, 0.0, 0.0, 1.0].

executeCommands_2_2

executeCommands_2_2 (uint32_t inLength, vec<handle> inHandles)
generates (Error error, bool outQueueChanged, uint32_t outLength, vec<handle> outHandles)

Executes commands from the input command message queue.Return values generated by the input commands are written to the output command message queue in the form of value commands.

Details
Parameters
inLength
is the length of input commands.
inHandles
is an array of handles referenced by the input commands.
Generates
error
is NONE upon success.Otherwise, BAD_PARAMETER when inLength is not equal to the length of commands in the input command message queue.NO_RESOURCES when the output command message queue was not properly drained.
outQueueChanged
outLength
outHandles