/*
* 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.3;
import android.hardware.graphics.common@1.1::RenderIntent;
import android.hardware.graphics.common@1.2::PixelFormat;
import android.hardware.graphics.common@1.2::ColorMode;
import android.hardware.graphics.common@1.2::Dataspace;
import android.hardware.graphics.common@1.2::Hdr;
import android.hardware.graphics.composer@2.1::IComposerClient.Command;
import @2.2::IComposerClient;
import @2.1::Display;
import @2.1::Error;
interface IComposerClient extends @2.2::IComposerClient {
/**
* Required capabilities which are supported by the display. The
* particular set of supported capabilities for a given display may be
* retrieved using getDisplayCapabilities.
*/
enum DisplayCapability : uint32_t {
INVALID = 0,
/**
* Indicates that the display must apply a color transform even when
* either the client or the device has chosen that all layers should
* be composed by the client. This prevents the client from applying
* the color transform during its composition step.
* If getDisplayCapabilities is supported, the global capability
* SKIP_CLIENT_COLOR_TRANSFORM is ignored.
* If getDisplayCapabilities is not supported, and the global capability
* SKIP_CLIENT_COLOR_TRANSFORM is returned by getCapabilities,
* then all displays must be treated as having
* SKIP_CLIENT_COLOR_TRANSFORM.
*/
SKIP_CLIENT_COLOR_TRANSFORM = 1,
/**
* Indicates that the 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.
* Must be returned by getDisplayCapabilities when getDozeSupport
* indicates the display supports PowerMode::DOZE and
* PowerMode::DOZE_SUSPEND.
*/
DOZE = 2,
/**
* Indicates that the display supports brightness operations.
*/
BRIGHTNESS = 3,
};
/**
* PerFrameMetadataKey
*
* A set of PerFrameMetadataKey pertains specifically to blob-formatted
* metadata (as opposed to float-valued metadata).
* The list of keys that represent blobs are:
* 1. HDR10_PLUS_SEI
*/
enum PerFrameMetadataKey : @2.2::IComposerClient.PerFrameMetadataKey {
/**HDR10+ metadata
* Specifies a metadata blob adhering to
* the ST2094-40 SEI message spec, Version 1.0
*/
HDR10_PLUS_SEI,
};
/**
* PerFrameMetadata
* This struct encapsulates float-valued
* metadata - key must not be in the list
* of keys representing blob-formatted metadata
* (see PerFrameMetadataKey)
*/
struct PerFrameMetadata {
PerFrameMetadataKey key;
float value;
};
/**
* PerFrameMetadataBlob
* This struct encapsulates blob
* metadata - key must be one of the list of keys
* associated with blob-type metadata key
* and the blob must adhere to the format specified by
* that key (See PerFrameMetadataKey).
*/
struct PerFrameMetadataBlob {
PerFrameMetadataKey key;
vec<uint8_t> blob;
};
enum Command : @2.2::IComposerClient.Command {
/**
* SET_LAYER_COLOR_TRANSFORM has this pseudo prototype
*
* setLayerColorTransform(float[16] matrix);
*
* This command has the following binary layout in bytes:
*
* 0 - 16 * 4: matrix
*
* Sets a matrix for color transform which will be applied on this layer
* before composition.
*
* If the device is not capable of apply the matrix on this layer, it must force
* this layer to client composition during VALIDATE_DISPLAY.
*
* 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 input color must first be converted to linear space
* [R_linear, G_linear, B_linear], then the output linear color
* [R_out_linear, G_out_linear, B_out_linear] will be:
*
* R_out_linear = R_linear * r.r + G_linear * g.r + B_linear * b.r + Tr
* G_out_linear = R_linear * r.g + G_linear * g.g + B_linear * b.g + Tg
* B_out_linear = R_linear * r.b + G_linear * g.b + B_linear * b.b + Tb
*
* [R_out_linear, G_out_linear, B_out_linear] must then be converted to
* gamma space: [R_out, G_out, B_out] before blending.
*
* @param matrix is a 4x4 transform matrix (16 floats) as described above.
*/
SET_LAYER_COLOR_TRANSFORM = 0x40d << @2.1::IComposerClient.Command:OPCODE_SHIFT,
/* SET_LAYER_PER_FRAME_METADATA_BLOBS has this pseudo prototype
*
* setLayerPerFrameMetadataBlobs(Display display, Layer layer,
* vec<PerFrameMetadataBlob> metadata);
*
* This command sends metadata that may be used for tone-mapping the
* associated layer. The metadata structure follows a {key, blob}
* format (see the PerFrameMetadataBlob struct). All keys must be
* returned by a prior call to getPerFrameMetadataKeys and must
* be part of the list of keys associated with blob-type metadata
* (see PerFrameMetadataKey).
*
* This method may be called every frame.
*/
SET_LAYER_PER_FRAME_METADATA_BLOBS = 0x304 << @2.1::IComposerClient.Command:OPCODE_SHIFT,
};
/**
* Returns the port and data that describe a physical display. The port is
* a unique number that identifies a physical connector (e.g. eDP, HDMI)
* for display output. The data blob is parsed to determine its format,
* typically EDID 1.3 as specified in VESA E-EDID Standard Release A
* Revision 1.
*
* @param display is the display to query.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* UNSUPPORTED when identification data is unavailable.
* @return port is the connector to which the display is connected.
* @return data is the EDID 1.3 blob identifying the display.
*/
@callflow(next="*")
getDisplayIdentificationData(Display display)
generates (Error error,
uint8_t port,
vec<uint8_t> data);
/**
* getReadbackBufferAttributes_2_3
* 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 must 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 will
* 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_2_3(Display display)
generates (Error error,
PixelFormat format,
Dataspace dataspace);
/**
* getClientTargetSupport_2_3
* 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_3(Display display,
uint32_t width,
uint32_t height,
PixelFormat format,
Dataspace dataspace)
generates (Error error);
enum FormatColorComponent : uint8_t {
/* The first component (eg, for RGBA_8888, this is R) */
FORMAT_COMPONENT_0 = 1 << 0,
/* The second component (eg, for RGBA_8888, this is G) */
FORMAT_COMPONENT_1 = 1 << 1,
/* The third component (eg, for RGBA_8888, this is B) */
FORMAT_COMPONENT_2 = 1 << 2,
/* The fourth component (eg, for RGBA_8888, this is A) */
FORMAT_COMPONENT_3 = 1 << 3,
};
/**
* Query for what types of color sampling the hardware supports.
*
* @param display is the display where the samples are collected.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display was passed in, or
* UNSUPPORTED when there is no efficient way to sample.
* @return format The format of the sampled pixels.
* @return dataspace The dataspace of the sampled pixels.
* @return componentMask The mask of which components can be sampled.
*/
getDisplayedContentSamplingAttributes(Display display)
generates (Error error,
PixelFormat format,
Dataspace dataspace,
bitfield<FormatColorComponent> componentMask);
/** DisplayedContentSampling values passed to setDisplayedContentSamplingEnabled. */
enum DisplayedContentSampling : int32_t {
INVALID = 0,
/** Enable content sampling. */
ENABLE = 1,
/** Disable content sampling. */
DISABLE = 2,
};
/**
* Enables or disables the collection of color content statistics
* on this display.
*
* Sampling occurs on the contents of the final composition on this display
* (i.e., the contents presented on screen). Samples should be collected after all
* color transforms have been applied.
*
* Sampling support is optional, and is set to DISABLE by default.
* On each call to ENABLE, all collected statistics must be reset.
*
* Sample data can be queried via getDisplayedContentSample().
*
* @param display is the display to which the sampling mode is set.
* @param enabled indicates whether to enable or disable sampling.
* @param componentMask The mask of which components should be sampled. If zero, all supported
* components are to be enabled.
* @param maxFrames is the maximum number of frames that should be stored before discard.
* The sample represents the most-recently posted frames.
* @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, or
* NO_RESOURCES when the requested ringbuffer size via maxFrames was
* not available.
* UNSUPPORTED when there is no efficient way to sample.
*/
setDisplayedContentSamplingEnabled(
Display display, DisplayedContentSampling enable,
bitfield<FormatColorComponent> componentMask, uint64_t maxFrames)
generates (Error error);
/**
* Collects the results of display content color sampling for display.
*
* Collection of data can occur whether the sampling is in ENABLE or
* DISABLE state.
*
* @param display is the display to which the sampling is collected.
* @param maxFrames is the maximum number of frames that should be represented in the sample.
* The sample represents the most-recently posted frames.
* If maxFrames is 0, all frames are to be represented by the sample.
* @param timestamp is the timestamp after which any frames were posted that should be
* included in the sample. Timestamp is CLOCK_MONOTONIC.
* If timestamp is 0, do not filter from the sample by time.
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display was passed in, or
* UNSUPPORTED when there is no efficient way to sample, or
* BAD_PARAMETER when the component is not supported by the hardware.
* @return frameCount The number of frames represented by this sample.
* @return sampleComponent0 is a histogram counting how many times a pixel of a given value
* was displayed onscreen for FORMAT_COMPONENT_0.
* The buckets of the histogram are evenly weighted, the number of buckets
* is device specific.
* eg, for RGBA_8888, if sampleComponent0 is {10, 6, 4, 1} this means that
* 10 red pixels were displayed onscreen in range 0x00->0x3F, 6 red pixels
* were displayed onscreen in range 0x40->0x7F, etc.
* @return sampleComponent1 is the same sample definition as sampleComponent0,
* but for FORMAT_COMPONENT_1.
* @return sampleComponent2 is the same sample definition as sampleComponent0,
* but for FORMAT_COMPONENT_2.
* @return sampleComponent3 is the same sample definition as sampleComponent0,
* but for FORMAT_COMPONENT_3.
*/
getDisplayedContentSample(Display display, uint64_t maxFrames, uint64_t timestamp)
generates (Error error,
uint64_t frameCount,
vec<uint64_t> sampleComponent0,
vec<uint64_t> sampleComponent1,
vec<uint64_t> sampleComponent2,
vec<uint64_t> sampleComponent3);
/**
* 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_3(uint32_t inLength,
vec<handle> inHandles)
generates (Error error,
bool outQueueChanged,
uint32_t outLength,
vec<handle> outHandles);
/**
* 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_2_3(Display display, ColorMode mode)
generates (Error error,
vec<RenderIntent> intents);
/**
* 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_3(Display display)
generates (Error error,
vec<ColorMode> modes);
/**
* 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_3(Display display, ColorMode mode, RenderIntent intent)
generates (Error error);
/**
* Provides a list of supported capabilities (as described in the
* definition of DisplayCapability above). This list must not change after
* initialization.
*
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when an invalid display handle was passed in.
* @return capabilities is a list of supported capabilities.
*/
getDisplayCapabilities(Display display)
generates (Error error,
vec<DisplayCapability> capabilities);
/**
* 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_2_3(Display display)
generates (Error error,
vec<PerFrameMetadataKey> keys);
/**
* 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_2_3(Display display)
generates (Error error,
vec<Hdr> types,
float maxLuminance,
float maxAverageLuminance,
float minLuminance);
/**
* Use getDisplayCapabilities instead. If brightness is supported, must return
* DisplayCapability::BRIGHTNESS as one of the display capabilities via getDisplayCapabilities.
* Only use getDisplayCapabilities as the source of truth to query brightness support.
*
* Gets whether brightness operations are supported on a display.
*
* @param display
* The display.
*
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when the display is invalid, or
* BAD_PARAMETER when the output parameter is invalid.
* @return support
* Whether brightness operations are supported on the display.
*/
getDisplayBrightnessSupport(Display display) generates (Error error, bool support);
/**
* Sets the brightness of a display.
*
* Ideally, the brightness change should take effect in the next frame post (so that it can be
* aligned with color transforms).
*
* @param display
* The display whose brightness is set.
* @param brightness
* A number between 0.0f (minimum brightness) and 1.0f (maximum brightness), or -1.0 to
* turn the backlight off.
*
* @return error is NONE upon success. Otherwise,
* BAD_DISPLAY when the display is invalid, or
* UNSUPPORTED when brightness operations are not supported, or
* BAD_PARAMETER when the brightness is invalid, or
* NO_RESOURCES when the brightness cannot be applied.
*/
setDisplayBrightness(Display display, float brightness) generates (Error error);
};