/* * 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 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 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 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 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 inHandles) generates (Error error, bool outQueueChanged, uint32_t outLength, vec outHandles); };