/*
* Copyright (C) 2016 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.graphics.composer@2.1;
import android.hardware.graphics.common@1.0;
import IComposerCallback;
interface IComposerClient {
/** Display attributes queryable through getDisplayAttribute. */
enum Attribute : int32_t {
INVALID = 0,
/** Dimensions in pixels */
WIDTH = 1,
HEIGHT = 2,
/** Vsync period in nanoseconds */
VSYNC_PERIOD = 3,
/**
* Dots per thousand inches (DPI * 1000). Scaling by 1000 allows these
* numbers to be stored in an int32_t without losing too much
* precision. If the DPI for a configuration is unavailable or is
* considered unreliable, the device may return UNSUPPORTED instead.
*/
DPI_X = 4,
DPI_Y = 5,
};
/** Display requests returned by getDisplayRequests. */
enum DisplayRequest : uint32_t {
/**
* Instructs the client to provide a new client target buffer, even if
* no layers are marked for client composition.
*/
FLIP_CLIENT_TARGET = 1 << 0,
/**
* Instructs the client to write the result of client composition
* directly into the virtual display output buffer. If any of the
* layers are not marked as Composition::CLIENT or the given display
* is not a virtual display, this request has no effect.
*/
WRITE_CLIENT_TARGET_TO_OUTPUT = 1 << 1,
};
/** Layer requests returned from getDisplayRequests. */
enum LayerRequest : uint32_t {
/**
* The client must clear its target with transparent pixels where
* this layer would be. The client may ignore this request if the
* layer must be blended.
*/
CLEAR_CLIENT_TARGET = 1 << 0,
};
/** Power modes for use with setPowerMode. */
enum PowerMode : int32_t {
/** The display is fully off (blanked). */
OFF = 0,
/**
* These are optional low power modes. getDozeSupport may be called to
* determine whether a given display supports these modes.
*/
/**
* The display is turned on and configured in a low power state that
* is suitable for presenting ambient information to the user,
* possibly with lower fidelity than ON, but with greater efficiency.
*/
DOZE = 1,
/**
* The display is configured as in DOZE 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 in a low power state 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
* doze functionality. In this case, the device is free to take over
* the display and manage it autonomously to implement a low power
* always-on display.
*/
DOZE_SUSPEND = 3,
/** The display is fully on. */
ON = 2,
};
/** Vsync values passed to setVsyncEnabled. */
enum Vsync : int32_t {
INVALID = 0,
/** Enable vsync. */
ENABLE = 1,
/** Disable vsync. */
DISABLE = 2,
};
/** Blend modes, settable per layer. */
enum BlendMode : int32_t {
INVALID = 0,
/** colorOut = colorSrc */
NONE = 1,
/** colorOut = colorSrc + colorDst * (1 - alphaSrc) */
PREMULTIPLIED = 2,
/** colorOut = colorSrc * alphaSrc + colorDst * (1 - alphaSrc) */
COVERAGE = 3,
};
/** Possible composition types for a given layer. */
enum Composition : int32_t {
INVALID = 0,
/**
* The client must composite this layer into the client target buffer
* (provided to the device through setClientTarget).
*
* The device must not request any composition type changes for layers
* of this type.
*/
CLIENT = 1,
/**
* The device must handle the composition of this layer through a
* hardware overlay or other similar means.
*
* Upon validateDisplay, the device may request a change from this
* type to CLIENT.
*/
DEVICE = 2,
/**
* The device must render this layer using the color set through
* setLayerColor. If this functionality is not supported on a layer
* that the client sets to SOLID_COLOR, the device must request that
* the composition type of that layer is changed to CLIENT upon the
* next call to validateDisplay.
*
* Upon validateDisplay, the device may request a change from this
* type to CLIENT.
*/
SOLID_COLOR = 3,
/**
* Similar to DEVICE, but the position of this layer may also be set
* asynchronously through setCursorPosition. If this functionality is
* not supported on a layer that the client sets to CURSOR, the device
* must request that the composition type of that layer is changed to
* CLIENT upon the next call to validateDisplay.
*
* Upon validateDisplay, the device may request a change from this
* type to either DEVICE or CLIENT. Changing to DEVICE will prevent
* the use of setCursorPosition but still permit the device to
* composite the layer.
*/
CURSOR = 4,
/**
* The device must handle the composition of this layer, as well as
* its buffer updates and content synchronization. Only supported on
* devices which provide Capability::SIDEBAND_STREAM.
*
* Upon validateDisplay, the device may request a change from this
* type to either DEVICE or CLIENT, but it is unlikely that content
* will display correctly in these cases.
*/
SIDEBAND = 5,
};
/** Display types returned by getDisplayType. */
enum DisplayType : int32_t {
INVALID = 0,
/**
* All physical displays, including both internal displays and
* hotpluggable external displays.
*/
PHYSICAL = 1,
/** Virtual displays created by createVirtualDisplay. */
VIRTUAL = 2,
};
/** Special index values (always negative) for command queue commands. */
enum HandleIndex : int32_t {
/** No handle */
EMPTY = -1,
/** Use cached handle */
CACHED = -2,
};
struct Rect {
int32_t left;
int32_t top;
int32_t right;
int32_t bottom;
};
struct FRect {
float left;
float top;
float right;
float bottom;
};
struct Color {
uint8_t r;
uint8_t g;
uint8_t b;
uint8_t a;
};
/**
* Provides a IComposerCallback object for the device to call.
*
* This function must be called only once.
*
* @param callback is the IComposerCallback object.
*/
@entry
@callflow(next="*")
registerCallback(IComposerCallback callback);
/**
* 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.
*
* @return count is the maximum number of virtual displays supported.
*/
@callflow(next="*")
getMaxVirtualDisplayCount() generates (uint32_t count);
/**
* 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.
*
* @param width is the width in pixels.
* @param height is the height in pixels.
* @param formatHint is the default output buffer format selected by
* the consumer.
* @param outputBufferSlotCount is the number of output buffer slots to be
* reserved.
* @return 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.
* @return display is the newly-created virtual display.
* @return format is the format of the buffer the device will produce.
*/
@callflow(next="*")
createVirtualDisplay(uint32_t width,
uint32_t height,
PixelFormat formatHint,
uint32_t outputBufferSlotCount)
generates (Error error,
Display display,
PixelFormat format);
/**
* 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.
*
* @param display is the virtual display to destroy.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_PARAMETER when the display handle which was passed in does
* not refer to a virtual display.
*/
@callflow(next="*")
destroyVirtualDisplay(Display display) generates (Error error);
/**
* Creates a new layer on the given display.
*
* @param display is the display on which to create the layer.
* @param bufferSlotCount is the number of buffer slot to be reserved.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* NO_RESOURCES when the device was unable to create a layer this
* time.
* @return layer is the handle of the new layer.
*/
@callflow(next="*")
createLayer(Display display,
uint32_t bufferSlotCount)
generates (Error error,
Layer layer);
/**
* Destroys the given layer.
*
* @param display is the display on which the layer was created.
* @param layer is the layer to destroy.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_LAYER when an invalid layer handle was passed in.
*/
@callflow(next="*")
destroyLayer(Display display, Layer layer) generates (Error error);
/**
* 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.
*
* @param display is the display to which the active config is queried.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_CONFIG when no configuration is currently active.
* @return config is the currently active display configuration.
*/
@callflow(next="*")
getActiveConfig(Display display) generates (Error error, Config config);
/**
* 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.
*
* @param display is the display to query.
* @param width is the client target width in pixels.
* @param height is the client target height in pixels.
* @param format is the client target format.
* @param dataspace is the client target dataspace, as described in
* setLayerDataspace.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* UNSUPPORTED when the given configuration is not supported.
*/
@callflow(next="*")
getClientTargetSupport(Display display,
uint32_t width,
uint32_t height,
PixelFormat format,
Dataspace dataspace)
generates (Error error);
/**
* Returns the color modes supported on this display.
*
* All devices must support at least ColorMode::NATIVE.
*
* @param display is the display to query.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* @return modes is an array of color modes.
*/
@callflow(next="*")
getColorModes(Display display)
generates (Error error,
vec<ColorMode> modes);
/**
* Returns a display attribute value for a particular display
* configuration.
*
* @param display is the display to query.
* @param config is the display configuration for which to return
* attribute values.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_CONFIG when config does not name a valid configuration for
* this display.
* BAD_PARAMETER when attribute is unrecognized.
* UNSUPPORTED when attribute cannot be queried for the config.
* @return value is the value of the attribute.
*/
@callflow(next="*")
getDisplayAttribute(Display display,
Config config,
Attribute attribute)
generates (Error error,
int32_t value);
/**
* Returns handles for all of the valid display configurations on this
* display.
*
* @param display is the display to query.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* @return configs is an array of configuration handles.
*/
@callflow(next="*")
getDisplayConfigs(Display display)
generates (Error error,
vec<Config> configs);
/**
* Returns a human-readable version of the display's name.
*
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* @return name is the name of the display.
*/
@callflow(next="*")
getDisplayName(Display display) generates (Error error, string name);
/**
* Returns whether the given display is a physical or virtual display.
*
* @param display is the display to query.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* @return type is the type of the display.
*/
@callflow(next="*")
getDisplayType(Display display) generates (Error error, DisplayType type);
/**
* 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.
*
* @param display is the display to query.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* @return support is true only when the display supports doze modes.
*/
@callflow(next="*")
getDozeSupport(Display display) generates (Error error, bool 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.
*
* @param display is the display to query.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* @return types is an array of HDR types, may have 0 elements if the
* display is not HDR-capable.
* @return maxLuminance is the desired content maximum luminance for this
* display in cd/m^2.
* @return maxAverageLuminance - the desired content maximum frame-average
* luminance for this display in cd/m^2.
* @return minLuminance is the desired content minimum luminance for this
* display in cd/m^2.
*/
@callflow(next="*")
getHdrCapabilities(Display display)
generates (Error error,
vec<Hdr> types,
float maxLuminance,
float maxAverageLuminance,
float minLuminance);
/**
* Set the number of client target slots to be reserved.
*
* @param display is the display to which the slots are reserved.
* @param clientTargetSlotCount is the slot count for client targets.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* NO_RESOURCES when unable to reserve the slots.
*/
@callflow(next="*")
setClientTargetSlotCount(Display display,
uint32_t clientTargetSlotCount)
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.
*
* @param display is the display to which the active config is set.
* @param config is the new display configuration.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_CONFIG when the configuration handle passed in is not valid
* for this display.
*/
@callflow(next="*")
setActiveConfig(Display display, Config config) 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.
*
* @param display is the display to which the color mode is set.
* @param mode is the mode to set to.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_PARAMETER when mode is not a valid color mode.
* UNSUPPORTED when mode is not supported on this display.
*/
@callflow(next="*")
setColorMode(Display display, ColorMode 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.
*
* @param display is the display to which the power mode is set.
* @param mode is the new power mode.
* @return 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.
*/
@callflow(next="*")
setPowerMode(Display display, PowerMode mode) 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.
*
* @param display is the display to which the vsync mode is set.
* @param enabled indicates whether to enable or disable vsync
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_PARAMETER when enabled was an invalid value.
*/
@callflow(next="*")
setVsyncEnabled(Display display, Vsync enabled) generates (Error error);
/**
* Sets the input command message queue.
*
* @param descriptor is the descriptor of the input command message queue.
* @return error is NONE upon success. Otherwise,
* NO_RESOURCES when failed to set the queue temporarily.
*/
@callflow(next="*")
setInputCommandQueue(fmq_sync<uint32_t> descriptor)
generates (Error error);
/**
* Gets the output command message queue.
*
* This function must only be called inside executeCommands closure.
*
* @return error is NONE upon success. Otherwise,
* NO_RESOURCES when failed to get the queue temporarily.
* @return descriptor is the descriptor of the output command queue.
*/
@callflow(next="*")
getOutputCommandQueue()
generates (Error error,
fmq_sync<uint32_t> descriptor);
/**
* 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.
*
* @param inLength is the length of input commands.
* @param inHandles is an array of handles referenced by the input
* commands.
* @return 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.
* @param outQueueChanged indicates whether the output command message
* queue has changed.
* @param outLength is the length of output commands.
* @param outHandles is an array of handles referenced by the output
* commands.
*/
@callflow(next="*")
executeCommands(uint32_t inLength,
vec<handle> inHandles)
generates (Error error,
bool outQueueChanged,
uint32_t outLength,
vec<handle> outHandles);
/**
* SELECT_DISPLAY has this pseudo prototype
*
* selectDisplay(Display display);
*
* Selects the current display implied by all other commands.
*
* @param display is the newly selected display.
*
*
* SELECT_LAYER has this pseudo prototype
*
* selectLayer(Layer layer);
*
* Selects the current layer implied by all implicit layer commands.
*
* @param layer is the newly selected layer.
*
*
* SET_ERROR has this pseudo prototype
*
* setError(uint32_t location, Error error);
*
* Indicates an error generated by a command.
*
* @param location is the offset of the command in the input command
* message queue.
* @param error is the error generated by the 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.
*
* @param layers is an array of layer handles.
* @param types is an array of composition types, each corresponding to
* an element of layers.
*
*
* 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.
*
* @param displayRequestMask is the display requests for the current
* validated state.
* @param layers is an array of layers which all have at least one
* request.
* @param layerRequestMasks is the requests corresponding to each element
* of layers.
*
*
* 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.
*
* @param presentFenceIndex is an index into outHandles array.
*
*
* 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).
*
* @param layers is an array of layer handles.
* @param releaseFenceIndices are indices into outHandles array, each
* corresponding to an element of layers.
*
*
* 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
*
* @param matrix is a 4x4 transform matrix (16 floats) as described above.
* @param hint is a hint value which may be used instead of the given
* matrix unless it is ColorTransform::ARBITRARY.
*
*
* 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.
*
* @param targetSlot is the client target buffer slot to use.
* @param targetIndex is an index into inHandles for the new target
* buffer.
* @param acquireFenceIndex is an index into inHandles for a sync fence
* file descriptor as described above.
* @param dataspace is the dataspace of the buffer, as described in
* setLayerDataspace.
* @param damage is the surface damage region.
*
*
* 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.
*
* @param bufferSlot is the new output buffer.
* @param bufferIndex is the new output buffer.
* @param releaseFenceIndex is a sync fence file descriptor as described
* above.
*
*
* 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.
*
* @param layer is the layer to which the position is set.
* @param x is the new x coordinate (in pixels from the left of the
* screen).
* @param y is the new y coordinate (in pixels from the top of the
* screen).
*
*
* 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).
*
* @param layer is the layer to which the buffer is set.
* @param bufferSlot is the buffer slot to use.
* @param bufferIndex is the buffer handle to set.
* @param acquireFenceIndex is a sync fence file descriptor as described above.
*
*
* 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.
*
* @param layer is the layer to which the damage region is set.
* @param damage is the new surface damage region.
*
*
* SET_LAYER_BLEND_MODE has this pseudo prototype
*
* setLayerBlendMode(BlendMode mode)
*
* Sets the blend mode of the given layer.
*
* @param mode is the new blend mode.
*
*
* 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.
*
* @param color is the new color.
*
*
* 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.
*
* @param type is the new composition type.
*
*
* 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.
*
* @param dataspace is the new dataspace.
*
*
* 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.
*
* @param frame is the new display frame.
*
*
* 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.
*
* @param alpha is the plane alpha value to apply.
*
*
* 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.
*
* @param streamIndex is the new sideband stream.
*
*
* 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);
*
* @param crop is the new source crop.
*
*
* SET_LAYER_TRANSFORM has this pseudo prototype
*
* Sets the transform (rotation/flip) of the given layer.
*
* setLayerTransform(Transform transform);
*
* @param transform is the new 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.
*
* @param visible is the new visible region, in screen space.
*
*
* 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.
*
* @param z is the new Z order.
*/
enum Command : int32_t {
LENGTH_MASK = 0xffff,
OPCODE_SHIFT = 16,
OPCODE_MASK = 0xffff << OPCODE_SHIFT,
/** special commands */
SELECT_DISPLAY = 0x000 << OPCODE_SHIFT,
SELECT_LAYER = 0x001 << OPCODE_SHIFT,
/** value commands (for return values) */
SET_ERROR = 0x100 << OPCODE_SHIFT,
SET_CHANGED_COMPOSITION_TYPES = 0x101 << OPCODE_SHIFT,
SET_DISPLAY_REQUESTS = 0x102 << OPCODE_SHIFT,
SET_PRESENT_FENCE = 0x103 << OPCODE_SHIFT,
SET_RELEASE_FENCES = 0x104 << OPCODE_SHIFT,
/** display commands */
SET_COLOR_TRANSFORM = 0x200 << OPCODE_SHIFT,
SET_CLIENT_TARGET = 0x201 << OPCODE_SHIFT,
SET_OUTPUT_BUFFER = 0x202 << OPCODE_SHIFT,
VALIDATE_DISPLAY = 0x203 << OPCODE_SHIFT,
ACCEPT_DISPLAY_CHANGES = 0x204 << OPCODE_SHIFT,
PRESENT_DISPLAY = 0x205 << OPCODE_SHIFT,
PRESENT_OR_VALIDATE_DISPLAY = 0x206 << OPCODE_SHIFT,
/** layer commands (VALIDATE_DISPLAY not required) */
SET_LAYER_CURSOR_POSITION = 0x300 << OPCODE_SHIFT,
SET_LAYER_BUFFER = 0x301 << OPCODE_SHIFT,
SET_LAYER_SURFACE_DAMAGE = 0x302 << OPCODE_SHIFT,
/** layer state commands (VALIDATE_DISPLAY required) */
SET_LAYER_BLEND_MODE = 0x400 << OPCODE_SHIFT,
SET_LAYER_COLOR = 0x401 << OPCODE_SHIFT,
SET_LAYER_COMPOSITION_TYPE = 0x402 << OPCODE_SHIFT,
SET_LAYER_DATASPACE = 0x403 << OPCODE_SHIFT,
SET_LAYER_DISPLAY_FRAME = 0x404 << OPCODE_SHIFT,
SET_LAYER_PLANE_ALPHA = 0x405 << OPCODE_SHIFT,
SET_LAYER_SIDEBAND_STREAM = 0x406 << OPCODE_SHIFT,
SET_LAYER_SOURCE_CROP = 0x407 << OPCODE_SHIFT,
SET_LAYER_TRANSFORM = 0x408 << OPCODE_SHIFT,
SET_LAYER_VISIBLE_REGION = 0x409 << OPCODE_SHIFT,
SET_LAYER_Z_ORDER = 0x40a << OPCODE_SHIFT,
SET_PRESENT_OR_VALIDATE_DISPLAY_RESULT = 0x40b << OPCODE_SHIFT,
/** 0x800 - 0xfff are reserved for vendor extensions */
/** 0x1000 - 0xffff are reserved */
};
};