android.hardware.graphics.composer@2.1
IComposerClient
interface IComposerClient
Properties
Attribute
enum Attribute: int32_t
Display attributes queryable through getDisplayAttribute.
Details | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Members |
|
DisplayRequest
enum DisplayRequest: uint32_t
Display requests returned by getDisplayRequests.
Details | |||||
---|---|---|---|---|---|
Members |
|
LayerRequest
enum LayerRequest: uint32_t
Layer requests returned from getDisplayRequests.
Details | |||
---|---|---|---|
Members |
|
PowerMode
enum PowerMode: int32_t
Power modes for use with setPowerMode.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Members |
|
Vsync
enum Vsync: int32_t
Vsync values passed to setVsyncEnabled.
Details | |||||||
---|---|---|---|---|---|---|---|
Members |
|
BlendMode
enum BlendMode: int32_t
Blend modes, settable per layer.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Members |
|
Composition
enum Composition: int32_t
Possible composition types for a given layer.
Details | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Members |
|
DisplayType
enum DisplayType: int32_t
Display types returned by getDisplayType.
Details | |||||||
---|---|---|---|---|---|---|---|
Members |
|
HandleIndex
enum HandleIndex: int32_t
Special index values(always negative)for command queue commands.
Details | |||||
---|---|---|---|---|---|
Members |
|
Command
enum Command: int32_t
SELECT_DISPLAY has this pseudo prototype
selectDisplay(Display display);
Selects the current display implied by all other commands.
SELECT_LAYER has this pseudo prototype
selectLayer(Layer layer);
Selects the current layer implied by all implicit layer commands.
SET_ERROR has this pseudo prototype
setError(uint32_t location, Error error);
Indicates an error generated by a command.
SET_CHANGED_COMPOSITION_TYPES has this pseudo prototype
setChangedCompositionTypes(vec<Layer>layers, vec<Composition>types);
Sets the layers for which the device requires a different composition type than had been set prior to the last call to VALIDATE_DISPLAY.The client must either update its state with these types and call ACCEPT_DISPLAY_CHANGES, or must set new types and attempt to validate the display again.
SET_DISPLAY_REQUESTS has this pseudo prototype
setDisplayRequests(uint32_t displayRequestMask, vec<Layer>layers, vec<uint32_t>layerRequestMasks);
Sets the display requests and the layer requests required for the last validated configuration.
Display requests provide information about how the client must handle the client target.Layer requests provide information about how the client must handle an individual layer.
SET_PRESENT_FENCE has this pseudo prototype
setPresentFence(int32_t presentFenceIndex);
Sets the present fence as a result of PRESENT_DISPLAY.For physical displays, this fence must be signaled at the vsync when the result of composition of this frame starts to appear(for video-mode panels)or starts to transfer to panel memory(for command-mode panels). For virtual displays, this fence must be signaled when writes to the output buffer have completed and it is safe to read from it.
SET_RELEASE_FENCES has this pseudo prototype
setReleaseFences(vec<Layer>layers, vec<int32_t>releaseFenceIndices);
Sets the release fences for device layers on this display which will receive new buffer contents this frame.
A release fence is a file descriptor referring to a sync fence object which must be signaled after the device has finished reading from the buffer presented in the prior frame.This indicates that it is safe to start writing to the buffer again.If a given layer's fence is not returned from this function, it must be assumed that the buffer presented on the previous frame is ready to be written.
The fences returned by this function must be unique for each layer(even if they point to the same underlying sync object).
SET_COLOR_TRANSFORM has this pseudo prototype
setColorTransform(float[16]matrix, ColorTransform hint);
Sets a color transform which will be applied after composition.
If hint is not ColorTransform::ARBITRARY, then the device may use the hint to apply the desired color transform instead of using the color matrix directly.
If the device is not capable of either using the hint or the matrix to apply the desired color transform, it must force all layers to client composition during VALIDATE_DISPLAY.
If IComposer::Capability::SKIP_CLIENT_COLOR_TRANSFORM is present, then the client must never apply the color transform during client composition, even if all layers are being composed by the client.
The matrix provided is an affine color transformation of the following form:
|r.r r.g r.b 0| |g.r g.g g.b 0| |b.r b.g b.b 0| |Tr Tg Tb 1|
This matrix must be provided in row-major form:
{r.r, r.g, r.b, 0, g.r, ...}.
Given a matrix of this form and an input color[R_in, G_in, B_in], the output color[R_out, G_out, B_out]will be:
R_out = R_in * r.r + G_in * g.r + B_in * b.r + Tr G_out = R_in * r.g + G_in * g.g + B_in * b.g + Tg B_out = R_in * r.b + G_in * g.b + B_in * b.b + Tb
SET_CLIENT_TARGET has this pseudo prototype
setClientTarget(uint32_t targetSlot, int32_t targetIndex, int32_t acquireFenceIndex, Dataspace dataspace, vec<Rect>damage);
Sets the buffer handle which will receive the output of client composition.Layers marked as Composition::CLIENT must be composited into this buffer prior to the call to PRESENT_DISPLAY, and layers not marked as Composition::CLIENT must be composited with this buffer by the device.
The buffer handle provided may be empty if no layers are being composited by the client.This must not result in an error(unless an invalid display handle is also provided).
Also provides a file descriptor referring to an acquire sync fence object, which must be signaled when it is safe to read from the client target buffer.If it is already safe to read from this buffer, an empty handle may be passed instead.
For more about dataspaces, see SET_LAYER_DATASPACE.
The damage parameter describes a surface damage region as defined in the description of SET_LAYER_SURFACE_DAMAGE.
Will be called before PRESENT_DISPLAY if any of the layers are marked as Composition::CLIENT.If no layers are so marked, then it is not necessary to call this function.It is not necessary to call validateDisplay after changing the target through this function.
SET_OUTPUT_BUFFER has this pseudo prototype
setOutputBuffer(uint32_t bufferSlot, int32_t bufferIndex, int32_t releaseFenceIndex);
Sets the output buffer for a virtual display.That is, the buffer to which the composition result will be written.
Also provides a file descriptor referring to a release sync fence object, which must be signaled when it is safe to write to the output buffer.If it is already safe to write to the output buffer, an empty handle may be passed instead.
Must be called at least once before PRESENT_DISPLAY, but does not have any interaction with layer state or display validation.
VALIDATE_DISPLAY has this pseudo prototype
validateDisplay();
Instructs the device to inspect all of the layer state and determine if there are any composition type changes necessary before presenting the display.Permitted changes are described in the definition of Composition above.
ACCEPT_DISPLAY_CHANGES has this pseudo prototype
acceptDisplayChanges();
Accepts the changes required by the device from the previous validateDisplay call(which may be queried using getChangedCompositionTypes)and revalidates the display.This function is equivalent to requesting the changed types from getChangedCompositionTypes, setting those types on the corresponding layers, and then calling validateDisplay again.
After this call it must be valid to present this display.Calling this after validateDisplay returns 0 changes must succeed with NONE, but must have no other effect.
PRESENT_DISPLAY has this pseudo prototype
presentDisplay();
Presents the current display contents on the screen(or in the case of virtual displays, into the output buffer).
Prior to calling this function, the display must be successfully validated with validateDisplay.Note that setLayerBuffer and setLayerSurfaceDamage specifically do not count as layer state, so if there are no other changes to the layer state(or to the buffer's properties as described in setLayerBuffer), then it is safe to call this function without first validating the display.
SET_LAYER_CURSOR_POSITION has this pseudo prototype
setLayerCursorPosition(int32_t x, int32_t y);
Asynchronously sets the position of a cursor layer.
Prior to validateDisplay, a layer may be marked as Composition::CURSOR.If validation succeeds(i.e ., the device does not request a composition change for that layer), then once a buffer has been set for the layer and it has been presented, its position may be set by this function at any time between presentDisplay and any subsequent validateDisplay calls for this display.
Once validateDisplay is called, this function must not be called again until the validate/present sequence is completed.
May be called from any thread so long as it is not interleaved with the validate/present sequence as described above.
SET_LAYER_BUFFER has this pseudo prototype
setLayerBuffer(uint32_t bufferSlot, int32_t bufferIndex, int32_t acquireFenceIndex);
Sets the buffer handle to be displayed for this layer.If the buffer properties set at allocation time(width, height, format, and usage)have not changed since the previous frame, it is not necessary to call validateDisplay before calling presentDisplay unless new state needs to be validated in the interim.
Also provides a file descriptor referring to an acquire sync fence object, which must be signaled when it is safe to read from the given buffer.If it is already safe to read from the buffer, an empty handle may be passed instead.
This function must return NONE and have no other effect if called for a layer with a composition type of Composition::SOLID_COLOR(because it has no buffer)or Composition::SIDEBAND or Composition::CLIENT(because synchronization and buffer updates for these layers are handled elsewhere).
SET_LAYER_SURFACE_DAMAGE has this pseudo prototype
setLayerSurfaceDamage(vec<Rect>damage);
Provides the region of the source buffer which has been modified since the last frame.This region does not need to be validated before calling presentDisplay.
Once set through this function, the damage region remains the same until a subsequent call to this function.
If damage is non-empty, then it may be assumed that any portion of the source buffer not covered by one of the rects has not been modified this frame.If damage is empty, then the whole source buffer must be treated as if it has been modified.
If the layer's contents are not modified relative to the prior frame, damage must contain exactly one empty rect([ 0, 0, 0, 0 ]).
The damage rects are relative to the pre-transformed buffer, and their origin is the top-left corner.They must not exceed the dimensions of the latched buffer.
SET_LAYER_BLEND_MODE has this pseudo prototype
setLayerBlendMode(BlendMode mode)
Sets the blend mode of the given layer.
SET_LAYER_COLOR has this pseudo prototype
setLayerColor(Color 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.
SET_LAYER_COMPOSITION_TYPE has this pseudo prototype
setLayerCompositionType(Composition type);
Sets the desired composition type of the given layer.During validateDisplay, the device may request changes to the composition types of any of the layers as described in the definition of Composition above.
SET_LAYER_DATASPACE has this pseudo prototype
setLayerDataspace(Dataspace dataspace);
Sets the dataspace that the current buffer on this layer is in.
The dataspace provides more information about how to interpret the buffer contents, such as the encoding standard and color transform.
See the values of Dataspace for more information.
SET_LAYER_DISPLAY_FRAME has this pseudo prototype
setLayerDisplayFrame(Rect frame);
Sets the display frame(the portion of the display covered by a layer)of the given layer.This frame must not exceed the display dimensions.
SET_LAYER_PLANE_ALPHA has this pseudo prototype
setLayerPlaneAlpha(float alpha);
Sets an alpha value(a floating point value in the range[0.0, 1.0 ])which will be applied to the whole layer.It can be conceptualized as a preprocessing step which applies the following function:if(blendMode == BlendMode::PREMULTIPLIED)out.rgb = in.rgb * planeAlpha out.a = in.a * planeAlpha
If the device does not support this operation on a layer which is marked Composition::DEVICE, it must request a composition type change to Composition::CLIENT upon the next validateDisplay call.
SET_LAYER_SIDEBAND_STREAM has this pseudo prototype
setLayerSidebandStream(int32_t streamIndex)
Sets the sideband stream for this layer.If the composition type of the given layer is not Composition::SIDEBAND, this call must succeed and have no other effect.
SET_LAYER_SOURCE_CROP has this pseudo prototype
setLayerSourceCrop(FRect crop);
Sets the source crop(the portion of the source buffer which will fill the display frame)of the given layer.This crop rectangle must not exceed the dimensions of the latched buffer.
If the device is not capable of supporting a true float source crop(i.e ., it will truncate or round the floats to integers), it must set this layer to Composition::CLIENT when crop is non-integral for the most accurate rendering.
If the device cannot support float source crops, but still wants to handle the layer, it must use the following code(or similar)to convert to an integer crop:intCrop.left =(int)ceilf(crop.left); intCrop.top =(int)ceilf(crop.top); intCrop.right =(int)floorf(crop.right); intCrop.bottom =(int)floorf(crop.bottom);
SET_LAYER_TRANSFORM has this pseudo prototype
Sets the transform(rotation/flip)of the given layer.
setLayerTransform(Transform transform);
SET_LAYER_VISIBLE_REGION has this pseudo prototype
setLayerVisibleRegion(vec<Rect>visible);
Specifies the portion of the layer that is visible, including portions under translucent areas of other layers.The region is in screen space, and must not exceed the dimensions of the screen.
SET_LAYER_Z_ORDER has this pseudo prototype
setLayerZOrder(uint32_t z);
Sets the desired Z order(height)of the given layer.A layer with a greater Z value occludes a layer with a lesser Z value.
Details | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Members |
|
Rect
struct Rect {int32_t left; int32_t top; int32_t right; int32_t bottom}
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Members |
|
FRect
struct FRect {float left; float top; float right; float bottom}
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Members |
|
Color
struct Color {uint8_t r; uint8_t g; uint8_t b; uint8_t a}
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Members |
|
Methods
registerCallback
registerCallback (IComposerCallback callback)
Provides a IComposerCallback object for the device to call.
This function must be called only once.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Annotations |
|
getMaxVirtualDisplayCount
getMaxVirtualDisplayCount () generates (uint32_t count)
Returns the maximum number of virtual displays supported by this device(which may be 0). The client must not attempt to create more than this many virtual displays on this device.This number must not change for the lifetime of the device.
Details | |||
---|---|---|---|
Generates |
|
||
Annotations |
|
createVirtualDisplay
createVirtualDisplay (uint32_t width, uint32_t height, PixelFormat formatHint, uint32_t outputBufferSlotCount) generates (Error error, Display display, PixelFormat format)
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 |
|
||||||||
Generates |
|
||||||||
Annotations |
|
destroyVirtualDisplay
destroyVirtualDisplay (Display display) generates (Error error)
Destroys a virtual display.After this call all resources consumed by this display may be freed by the device and any operations performed on this display must fail.
Details | |||
---|---|---|---|
Parameters |
|
||
Generates |
|
||
Annotations |
|
createLayer
createLayer (Display display, uint32_t bufferSlotCount) generates (Error error, Layer layer)
Creates a new layer on the given display.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
destroyLayer
destroyLayer (Display display, Layer layer) generates (Error error)
Destroys the given layer.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
getActiveConfig
getActiveConfig (Display display) generates (Error error, Config config)
Retrieves which display configuration is currently active.
If no display configuration is currently active, this function must return BAD_CONFIG.It is the responsibility of the client to call setActiveConfig with a valid configuration before attempting to present anything on the display.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
getClientTargetSupport
getClientTargetSupport (Display display, uint32_t width, uint32_t height, PixelFormat format, Dataspace dataspace) generates (Error error)
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 |
|
||||||||||
Generates |
|
||||||||||
Annotations |
|
getColorModes
getColorModes (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 |
|
||||
Generates |
|
||||
Annotations |
|
getDisplayAttribute
getDisplayAttribute (Display display, Config config, Attribute attribute) generates (Error error, int32_t value)
Returns a display attribute value for a particular display configuration.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
||||||
Generates |
|
||||||
Annotations |
|
getDisplayConfigs
getDisplayConfigs (Display display) generates (Error error, vec<Config> configs)
Returns handles for all of the valid display configurations on this display.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
getDisplayName
getDisplayName (Display display) generates (Error error, string name)
Returns a human-readable version of the display's name.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
getDisplayType
getDisplayType (Display display) generates (Error error, DisplayType type)
Returns whether the given display is a physical or virtual display.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
getDozeSupport
getDozeSupport (Display display) generates (Error error, bool support)
Returns whether the given display supports PowerMode::DOZE and PowerMode::DOZE_SUSPEND.DOZE_SUSPEND may not provide any benefit over DOZE(see the definition of PowerMode for more information), but if both DOZE and DOZE_SUSPEND are no different from PowerMode::ON, the device must not claim support.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
getHdrCapabilities
getHdrCapabilities (Display display) generates (Error error, vec<Hdr> types, float maxLuminance, float maxAverageLuminance, float minLuminance)
Returns the high dynamic range(HDR)capabilities of the given display, which are invariant with regard to the active configuration.
Displays which are not HDR-capable must return no types.
Details | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Parameters |
|
||||||||||
Generates |
|
||||||||||
Annotations |
|
setClientTargetSlotCount
setClientTargetSlotCount (Display display, uint32_t clientTargetSlotCount) generates (Error error)
Set the number of client target slots to be reserved.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
setActiveConfig
setActiveConfig (Display display, Config config) generates (Error error)
Sets the active configuration for this display.Upon returning, the given display configuration must be active and remain so until either this function is called again or the display is disconnected.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
setColorMode
setColorMode (Display display, ColorMode mode) generates (Error error)
Sets the color mode of the given display.
Upon returning from this function, the color mode change must have fully taken effect.
All devices must support at least ColorMode::NATIVE, and displays are assumed to be in this mode upon hotplug.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
setPowerMode
setPowerMode (Display display, PowerMode mode) generates (Error error)
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 |
|
||||
Generates |
|
||||
Annotations |
|
setVsyncEnabled
setVsyncEnabled (Display display, Vsync enabled) generates (Error error)
Enables or disables the vsync signal for the given display.Virtual displays never generate vsync callbacks, and any attempt to enable vsync for a virtual display though this function must succeed and have no other effect.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Generates |
|
||||
Annotations |
|
setInputCommandQueue
setInputCommandQueue (fmq_sync<uint32_t> descriptor) generates (Error error)
Sets the input command message queue.
Details | |||
---|---|---|---|
Parameters |
|
||
Generates |
|
||
Annotations |
|
getOutputCommandQueue
getOutputCommandQueue () generates (Error error, fmq_sync<uint32_t> descriptor)
Gets the output command message queue.
This function must only be called inside executeCommands closure.
Details | |||||
---|---|---|---|---|---|
Generates |
|
||||
Annotations |
|
executeCommands
executeCommands (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 |
|
||||||||
Generates |
|
||||||||
Annotations |
|