IComposerClient

Display attributes queryable through getDisplayAttribute.

Display requests returned by getDisplayRequests.

Layer requests returned from getDisplayRequests.

Power modes for use with setPowerMode.

Vsync values passed to setVsyncEnabled.

Blend modes, settable per layer.

Possible composition types for a given layer.

Display types returned by getDisplayType.

Special index values(always negative)for command queue commands.

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.

Provides a IComposerCallback object for the device to call.

This function must be called only once.

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.

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.

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.

Creates a new layer on the given display.

Destroys the given layer.

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.

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.

Returns the color modes supported on this display.

All devices must support at least ColorMode::NATIVE.

Returns a display attribute value for a particular display configuration.

Returns handles for all of the valid display configurations on this display.

Returns a human-readable version of the display's name.

Returns whether the given display is a physical or virtual display.

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.

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.

Set the number of client target slots to be reserved.

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.

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.

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.

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.

Sets the input command message queue.

Gets the output command message queue.

This function must only be called inside executeCommands closure.

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.