tequilaOS/platform_hardware_interfaces
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
platform_hardware_interfaces/graphics/composer/2.1/IComposerClient.hal
Peiyong Lin 849c980804 [composer] Remove implication. 
The spec of setLayerDataspace never specifies the types of layer it should be
call on, however, the spec has the implication that this method will only work
for layers with buffer, which is mis-leading. This patch changes the wording of
setLayerDataspace spec, removes the implication. Note that this change won't
break backward compatability.

BUG: 126713799
Test: N/A
Change-Id: I97f22469897cb687dcb64a3d419bcb48a3668e5a
2019-02-28 17:00:30 -08:00

1144 lines
45 KiB
Text
Raw Blame History

/*
* 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 of the layer.
*
* The dataspace provides more information about how to interpret the buffer
* or solid color, 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 */
};
};
Reference in a new issue View git blame Copy permalink