| /* |
| * 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); |
| }; |