/*
* Copyright (C) 2018 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.2;
import android.hardware.graphics.common@1.1::ColorMode;
import android.hardware.graphics.common@1.1::Dataspace;
import android.hardware.graphics.common@1.1::PixelFormat;
import android.hardware.graphics.common@1.1::RenderIntent;
import @2.1::IComposerClient;
import @2.1::Display;
import @2.1::Error;
import @2.1::IComposerClient;
interface IComposerClient extends @2.1::IComposerClient {
enum PowerMode : @2.1::IComposerClient.PowerMode {
/**
* The display is configured as in ON but may stop applying display
* updates from the client. This is effectively a hint to the device
* that drawing to the display has been suspended and that the the
* device must remain on and continue displaying its current contents
* indefinitely until the power mode changes.
*
* This mode may also be used as a signal to enable hardware-based
* functionality to take over the display and manage it autonomously
* to implement a low power always-on display.
*/
ON_SUSPEND = 4
};
/**
* Following enums define keys for metadata defined by SMPTE ST 2086:2014
* and CTA 861.3.
*/
enum PerFrameMetadataKey : int32_t {
/** SMPTE ST 2084:2014.
* Coordinates defined in CIE 1931 xy chromaticity space
*/
/** SMPTE ST 2084:2014 */
DISPLAY_RED_PRIMARY_X,
/** SMPTE ST 2084:2014 */
DISPLAY_RED_PRIMARY_Y,
/** SMPTE ST 2084:2014 */
DISPLAY_GREEN_PRIMARY_X,
/** SMPTE ST 2084:2014 */
DISPLAY_GREEN_PRIMARY_Y,
/** SMPTE ST 2084:2014 */
DISPLAY_BLUE_PRIMARY_X,
/** SMPTE ST 2084:2014 */
DISPLAY_BLUE_PRIMARY_Y,
/** SMPTE ST 2084:2014 */
WHITE_POINT_X,
/** SMPTE ST 2084:2014 */
WHITE_POINT_Y,
/** SMPTE ST 2084:2014.
* Units: nits
* max as defined by ST 2048: 10,000 nits
*/
MAX_LUMINANCE,
/** SMPTE ST 2084:2014 */
MIN_LUMINANCE,
/** CTA 861.3 */
MAX_CONTENT_LIGHT_LEVEL,
/** CTA 861.3 */
MAX_FRAME_AVERAGE_LIGHT_LEVEL,
};
struct PerFrameMetadata {
PerFrameMetadataKey key;
float value;
};
struct FloatColor {
float r;
float g;
float b;
float a;
};
enum Command : @2.1::IComposerClient.Command {
/**
* SET_LAYER_PER_FRAME_METADATA has this pseudo prototype
*
* setLayerPerFrameMetadata(Display display, Layer layer,
* vec<PerFrameMetadata> data);
*
* Sets the PerFrameMetadata for the display. This metadata must be used
* by the implementation to better tone map content to that display.
*
* This is a method that may be called every frame. Thus it's
* implemented using buffered transport.
* SET_LAYER_PER_FRAME_METADATA is the command used by the buffered transport
* mechanism.
*/
SET_LAYER_PER_FRAME_METADATA = 0x303 << @2.1::IComposerClient.Command:OPCODE_SHIFT,
/**
* SET_LAYER_COLOR has this pseudo prototype
*
* setLayerColor(FloatColor color);
*
* Sets the color of the given layer. If the composition type of the layer
* is not Composition::SOLID_COLOR, this call must succeed and have no
* other effect.
*
* @param color is the new color using float type.
*/
SET_LAYER_FLOAT_COLOR = 0x40c << @2.1::IComposerClient.Command:OPCODE_SHIFT,
};
/**
* Returns the PerFrameMetadataKeys that are supported by this device.
*
* @param display is the display on which to create the layer.
* @return keys is the vector of PerFrameMetadataKey keys that are
* supported by this device.
* @return error is NONE upon success. Otherwise,
* UNSUPPORTED if not supported on underlying HAL
*/
getPerFrameMetadataKeys(Display display)
generates (Error error,
vec<PerFrameMetadataKey> keys);
/**
* getReadbackBufferAttributes
* Returns the format which should be used when allocating a buffer for use by
* device readback as well as the dataspace in which its contents should be
* interpreted.
*
* The width and height of this buffer must be those of the currently-active
* display configuration, and the usage flags must consist of the following:
* BufferUsage::CPU_READ | BufferUsage::GPU_TEXTURE |
* BufferUsage::COMPOSER_OUTPUT
*
* The format and dataspace provided must be sufficient such that if a
* correctly-configured buffer is passed into setReadbackBuffer, filled by
* the device, and then displayed by the client as a full-screen buffer, the
* output of the display remains the same (subject to the note about protected
* content in the description of setReadbackBuffer).
*
* If the active configuration or color mode of this display has changed
* since a previous call to this function, it must be called again prior to
* setting a readback buffer such that the returned format and dataspace can
* be updated accordingly.
*
* Parameters:
* @param display - the display on which to create the layer.
*
* @return format - the format the client should use when allocating a device
* readback buffer
* @return dataspace - the dataspace to use when interpreting the
* contents of a device readback buffer
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* UNSUPPORTED if not supported on underlying HAL
*
* See also:
* setReadbackBuffer
* getReadbackBufferFence
*/
getReadbackBufferAttributes(Display display)
generates (Error error,
PixelFormat format,
Dataspace dataspace);
/**
* getReadbackBufferFence
* Returns an acquire sync fence file descriptor which must signal when the
* buffer provided to setReadbackBuffer has been filled by the device and is
* safe for the client to read.
*
* If it is already safe to read from this buffer, -1 may be returned instead.
* The client takes ownership of this file descriptor and is responsible for
* closing it when it is no longer needed.
*
* This function must be called immediately after the composition cycle being
* captured into the readback buffer. The complete ordering of a readback buffer
* capture is as follows:
*
* getReadbackBufferAttributes
* // Readback buffer is allocated
* // Many frames may pass
*
* setReadbackBuffer
* validateDisplay
* presentDisplay
* getReadbackBufferFence
* // Implicitly wait on the acquire fence before accessing the buffer
*
* Parameters:
* @param display - the display on which to create the layer.
*
* @return acquireFence - a sync fence file descriptor as described above; pointer
* must be non-NULL
* @return error - is HWC2_ERROR_NONE or one of the following errors:
* BAD_DISPLAY - an invalid display handle was passed in
* NO_RESOURCES - the readback operation was successful, but
* resulted in a different validate result than would
* have occurred without readback
* UNSUPPORTED - the readback operation was unsuccessful because of
* resource constraints, the presence of protected
* content, or other reasons; -1 must be returned for
* acquireFence
*
* See also:
* getReadbackBufferAttributes
* setReadbackBuffer
*/
getReadbackBufferFence(Display display)
generates (Error error,
handle acquireFence);
/**
* setReadbackBuffer
* Sets the readback buffer to be filled with the contents of the next
* composition performed for this display (i.e., the contents present at the
* time of the next validateDisplay/presentDisplay cycle).
*
* This buffer must have been allocated as described in
* getReadbackBufferAttributes and is in the dataspace provided by the same.
*
* If there is hardware protected content on the display at the time of the next
* composition, the area of the readback buffer covered by such content must be
* completely black. Any areas of the buffer not covered by such content may
* optionally be black as well.
*
* The release fence file descriptor provided works identically to the one
* described for setOutputBuffer.
*
* This function must not be called between any call to validateDisplay and a
* subsequent call to presentDisplay.
*
* Parameters:
* @param display - the display on which to create the layer.
* @param buffer - the new readback buffer
* @param releaseFence - a sync fence file descriptor as described in setOutputBuffer
*
* @return error - is HWC2_ERROR_NONE or one of the following errors:
* HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
* HWC2_ERROR_BAD_PARAMETER - the new readback buffer handle was invalid
*
* See also:
* getReadbackBufferAttributes
* getReadbackBufferFence
*/
setReadbackBuffer(Display display, handle buffer, handle releaseFence) generates (Error error);
/**
* createVirtualDisplay_2_2
* Creates a new virtual display with the given width and height. The
* format passed into this function is the default format requested by the
* consumer of the virtual display output buffers.
*
* The display must be assumed to be on from the time the first frame is
* presented until the display is destroyed.
*
* @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_2_2(uint32_t width,
uint32_t height,
PixelFormat formatHint,
uint32_t outputBufferSlotCount)
generates (Error error,
Display display,
PixelFormat format);
/**
* getClientTargetSupport_2_2
* Returns whether a client target with the given properties can be
* handled by the device.
*
* This function must return true for a client target with width and
* height equal to the active display configuration dimensions,
* PixelFormat::RGBA_8888, and Dataspace::UNKNOWN. It is not required to
* return true for any other configuration.
*
* @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_2_2(Display display,
uint32_t width,
uint32_t height,
PixelFormat format,
Dataspace dataspace)
generates (Error error);
/**
* setPowerMode_2_2
* Sets the power mode of the given display. The transition must be
* complete when this function returns. It is valid to call this function
* multiple times with the same power mode.
*
* All displays must support PowerMode::ON and PowerMode::OFF. Whether a
* display supports PowerMode::DOZE or PowerMode::DOZE_SUSPEND may be
* queried using getDozeSupport.
*
* @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.
*/
setPowerMode_2_2(Display display, PowerMode mode) 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.
*/
getColorModes_2_2(Display display)
generates (Error error,
vec<ColorMode> modes);
/**
* Returns the render intents supported by the specified display and color
* mode.
*
* For SDR color modes, RenderIntent::COLORIMETRIC must be supported. For
* HDR color modes, RenderIntent::TONE_MAP_COLORIMETRIC must be supported.
*
* @param display is the display to query.
* @param mode is the color mode to query.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_PARAMETER when an invalid color mode was passed in.
* @return intents is an array of render intents.
*/
getRenderIntents(Display display, ColorMode mode)
generates (Error error,
vec<RenderIntent> intents);
/**
* Sets the color mode and render intent of the given display.
*
* The color mode and render intent change must take effect on next
* presentDisplay.
*
* All devices must support at least ColorMode::NATIVE and
* RenderIntent::COLORIMETRIC, and displays are assumed to be in this mode
* upon hotplug.
*
* @param display is the display to which the color mode is set.
* @param mode is the color mode to set to.
* @param intent is the render intent to set to.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* BAD_PARAMETER when mode or intent is invalid
* UNSUPPORTED when mode or intent is not supported on this
* display.
*/
setColorMode_2_2(Display display, ColorMode mode, RenderIntent intent)
generates (Error error);
/*
* By default, layer dataspaces are mapped to the current color mode
* colorimetrically with a few exceptions.
*
* When the layer dataspace is a legacy dataspace (see
* common@1.1::Dataspace) and the display render intent is
* RenderIntent::ENHANCE, the pixel values can go through an
* implementation-defined saturation transform before being mapped to the
* current color mode colorimetrically.
*
* Colors that are out of the gamut of the current color mode are
* hard-clipped.
*/
/**
* Returns the saturation matrix of the specified legacy dataspace.
*
* The saturation matrix can be used to approximate the legacy dataspace
* saturation transform. It is to be applied on linear pixel values like
* this:
*
* (in GLSL)
* linearSrgb = saturationMatrix * linearSrgb;
*
* @param dataspace must be Dataspace::SRGB_LINEAR.
* @return error is NONE upon success. Otherwise,
* BAD_PARAMETER when an invalid dataspace was passed in.
* @return matrix is the 4x4 column-major matrix used to approximate the
* legacy dataspace saturation operation. The last row must be
* [0.0, 0.0, 0.0, 1.0].
*/
getDataspaceSaturationMatrix(Dataspace dataspace)
generates (Error error,
float[4][4] matrix);
/**
* 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.
*/
executeCommands_2_2(uint32_t inLength,
vec<handle> inHandles)
generates (Error error,
bool outQueueChanged,
uint32_t outLength,
vec<handle> outHandles);
};