1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.graphics.composer@2.3; 18 19 import android.hardware.graphics.common@1.1::RenderIntent; 20 import android.hardware.graphics.common@1.2::PixelFormat; 21 import android.hardware.graphics.common@1.2::ColorMode; 22 import android.hardware.graphics.common@1.2::Dataspace; 23 import android.hardware.graphics.common@1.2::Hdr; 24 import android.hardware.graphics.composer@2.1::IComposerClient.Command; 25 import @2.2::IComposerClient; 26 import @2.1::Display; 27 import @2.1::Error; 28 29 interface IComposerClient extends @2.2::IComposerClient { 30 31 /** 32 * Required capabilities which are supported by the display. The 33 * particular set of supported capabilities for a given display may be 34 * retrieved using getDisplayCapabilities. 35 */ 36 enum DisplayCapability : uint32_t { 37 INVALID = 0, 38 39 /** 40 * Indicates that the display must apply a color transform even when 41 * either the client or the device has chosen that all layers should 42 * be composed by the client. This prevents the client from applying 43 * the color transform during its composition step. 44 * If getDisplayCapabilities is supported, the global capability 45 * SKIP_CLIENT_COLOR_TRANSFORM is ignored. 46 * If getDisplayCapabilities is not supported, and the global capability 47 * SKIP_CLIENT_COLOR_TRANSFORM is returned by getCapabilities, 48 * then all displays must be treated as having 49 * SKIP_CLIENT_COLOR_TRANSFORM. 50 */ 51 SKIP_CLIENT_COLOR_TRANSFORM = 1, 52 53 /** 54 * Indicates that the display supports PowerMode::DOZE and 55 * PowerMode::DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit 56 * over DOZE (see the definition of PowerMode for more information), 57 * but if both DOZE and DOZE_SUSPEND are no different from 58 * PowerMode::ON, the device must not claim support. 59 * Must be returned by getDisplayCapabilities when getDozeSupport 60 * indicates the display supports PowerMode::DOZE and 61 * PowerMode::DOZE_SUSPEND. 62 */ 63 DOZE = 2, 64 65 /** 66 * Indicates that the display supports brightness operations. 67 */ 68 BRIGHTNESS = 3, 69 }; 70 71 /** 72 * PerFrameMetadataKey 73 * 74 * A set of PerFrameMetadataKey pertains specifically to blob-formatted 75 * metadata (as opposed to float-valued metadata). 76 * The list of keys that represent blobs are: 77 * 1. HDR10_PLUS_SEI 78 */ 79 enum PerFrameMetadataKey : @2.2::IComposerClient.PerFrameMetadataKey { 80 /**HDR10+ metadata 81 * Specifies a metadata blob adhering to 82 * the ST2094-40 SEI message spec, Version 1.0 83 */ 84 HDR10_PLUS_SEI, 85 }; 86 87 /** 88 * PerFrameMetadata 89 * This struct encapsulates float-valued 90 * metadata - key must not be in the list 91 * of keys representing blob-formatted metadata 92 * (see PerFrameMetadataKey) 93 */ 94 struct PerFrameMetadata { 95 PerFrameMetadataKey key; 96 float value; 97 }; 98 99 /** 100 * PerFrameMetadataBlob 101 * This struct encapsulates blob 102 * metadata - key must be one of the list of keys 103 * associated with blob-type metadata key 104 * and the blob must adhere to the format specified by 105 * that key (See PerFrameMetadataKey). 106 */ 107 struct PerFrameMetadataBlob { 108 PerFrameMetadataKey key; 109 vec<uint8_t> blob; 110 }; 111 112 enum Command : @2.2::IComposerClient.Command { 113 /** 114 * SET_LAYER_COLOR_TRANSFORM has this pseudo prototype 115 * 116 * setLayerColorTransform(float[16] matrix); 117 * 118 * This command has the following binary layout in bytes: 119 * 120 * 0 - 16 * 4: matrix 121 * 122 * Sets a matrix for color transform which will be applied on this layer 123 * before composition. 124 * 125 * If the device is not capable of apply the matrix on this layer, it must force 126 * this layer to client composition during VALIDATE_DISPLAY. 127 * 128 * The matrix provided is an affine color transformation of the following 129 * form: 130 * 131 * |r.r r.g r.b 0| 132 * |g.r g.g g.b 0| 133 * |b.r b.g b.b 0| 134 * |Tr Tg Tb 1| 135 * 136 * This matrix must be provided in row-major form: 137 * 138 * {r.r, r.g, r.b, 0, g.r, ...}. 139 * 140 * Given a matrix of this form and an input color [R_in, G_in, B_in], 141 * the input color must first be converted to linear space 142 * [R_linear, G_linear, B_linear], then the output linear color 143 * [R_out_linear, G_out_linear, B_out_linear] will be: 144 * 145 * R_out_linear = R_linear * r.r + G_linear * g.r + B_linear * b.r + Tr 146 * G_out_linear = R_linear * r.g + G_linear * g.g + B_linear * b.g + Tg 147 * B_out_linear = R_linear * r.b + G_linear * g.b + B_linear * b.b + Tb 148 * 149 * [R_out_linear, G_out_linear, B_out_linear] must then be converted to 150 * gamma space: [R_out, G_out, B_out] before blending. 151 * 152 * @param matrix is a 4x4 transform matrix (16 floats) as described above. 153 */ 154 SET_LAYER_COLOR_TRANSFORM = 0x40d << @2.1::IComposerClient.Command:OPCODE_SHIFT, 155 156 /* SET_LAYER_PER_FRAME_METADATA_BLOBS has this pseudo prototype 157 * 158 * setLayerPerFrameMetadataBlobs(Display display, Layer layer, 159 * vec<PerFrameMetadataBlob> metadata); 160 * 161 * This command sends metadata that may be used for tone-mapping the 162 * associated layer. The metadata structure follows a {key, blob} 163 * format (see the PerFrameMetadataBlob struct). All keys must be 164 * returned by a prior call to getPerFrameMetadataKeys and must 165 * be part of the list of keys associated with blob-type metadata 166 * (see PerFrameMetadataKey). 167 * 168 * This method may be called every frame. 169 */ 170 SET_LAYER_PER_FRAME_METADATA_BLOBS = 0x304 << @2.1::IComposerClient.Command:OPCODE_SHIFT, 171 }; 172 173 /** 174 * Returns the port and data that describe a physical display. The port is 175 * a unique number that identifies a physical connector (e.g. eDP, HDMI) 176 * for display output. The data blob is parsed to determine its format, 177 * typically EDID 1.3 as specified in VESA E-EDID Standard Release A 178 * Revision 1. 179 * 180 * @param display is the display to query. 181 * @return error is NONE upon success. Otherwise, 182 * BAD_DISPLAY when an invalid display handle was passed in. 183 * UNSUPPORTED when identification data is unavailable. 184 * @return port is the connector to which the display is connected. 185 * @return data is the EDID 1.3 blob identifying the display. 186 */ 187 @callflow(next="*") 188 getDisplayIdentificationData(Display display) 189 generates (Error error, 190 uint8_t port, 191 vec<uint8_t> data); 192 /** 193 * getReadbackBufferAttributes_2_3 194 * Returns the format which should be used when allocating a buffer for use by 195 * device readback as well as the dataspace in which its contents must be 196 * interpreted. 197 * 198 * The width and height of this buffer must be those of the currently-active 199 * display configuration, and the usage flags must consist of the following: 200 * BufferUsage::CPU_READ | BufferUsage::GPU_TEXTURE | 201 * BufferUsage::COMPOSER_OUTPUT 202 * 203 * The format and dataspace provided must be sufficient such that if a 204 * correctly-configured buffer is passed into setReadbackBuffer, filled by 205 * the device, and then displayed by the client as a full-screen buffer, the 206 * output of the display remains the same (subject to the note about protected 207 * content in the description of setReadbackBuffer). 208 * 209 * If the active configuration or color mode of this display has changed 210 * since a previous call to this function, it must be called again prior to 211 * setting a readback buffer such that the returned format and dataspace will 212 * be updated accordingly. 213 * 214 * Parameters: 215 * @param display - the display on which to create the layer. 216 * 217 * @return format - the format the client should use when allocating a device 218 * readback buffer 219 * @return dataspace - the dataspace to use when interpreting the 220 * contents of a device readback buffer 221 * @return error is NONE upon success. Otherwise, 222 * BAD_DISPLAY when an invalid display handle was passed in. 223 * UNSUPPORTED if not supported on underlying HAL 224 * 225 * See also: 226 * setReadbackBuffer 227 * getReadbackBufferFence 228 */ 229 getReadbackBufferAttributes_2_3(Display display) 230 generates (Error error, 231 PixelFormat format, 232 Dataspace dataspace); 233 234 /** 235 * getClientTargetSupport_2_3 236 * Returns whether a client target with the given properties can be 237 * handled by the device. 238 * 239 * This function must return true for a client target with width and 240 * height equal to the active display configuration dimensions, 241 * PixelFormat::RGBA_8888, and Dataspace::UNKNOWN. It is not required to 242 * return true for any other configuration. 243 * 244 * @param display is the display to query. 245 * @param width is the client target width in pixels. 246 * @param height is the client target height in pixels. 247 * @param format is the client target format. 248 * @param dataspace is the client target dataspace, as described in 249 * setLayerDataspace. 250 * @return error is NONE upon success. Otherwise, 251 * BAD_DISPLAY when an invalid display handle was passed in. 252 * UNSUPPORTED when the given configuration is not supported. 253 */ 254 @callflow(next="*") 255 getClientTargetSupport_2_3(Display display, 256 uint32_t width, 257 uint32_t height, 258 PixelFormat format, 259 Dataspace dataspace) 260 generates (Error error); 261 262 enum FormatColorComponent : uint8_t { 263 /* The first component (eg, for RGBA_8888, this is R) */ 264 FORMAT_COMPONENT_0 = 1 << 0, 265 /* The second component (eg, for RGBA_8888, this is G) */ 266 FORMAT_COMPONENT_1 = 1 << 1, 267 /* The third component (eg, for RGBA_8888, this is B) */ 268 FORMAT_COMPONENT_2 = 1 << 2, 269 /* The fourth component (eg, for RGBA_8888, this is A) */ 270 FORMAT_COMPONENT_3 = 1 << 3, 271 }; 272 273 /** 274 * Query for what types of color sampling the hardware supports. 275 * 276 * @param display is the display where the samples are collected. 277 * @return error is NONE upon success. Otherwise, 278 * BAD_DISPLAY when an invalid display was passed in, or 279 * UNSUPPORTED when there is no efficient way to sample. 280 * @return format The format of the sampled pixels. 281 * @return dataspace The dataspace of the sampled pixels. 282 * @return componentMask The mask of which components can be sampled. 283 */ 284 getDisplayedContentSamplingAttributes(Display display) 285 generates (Error error, 286 PixelFormat format, 287 Dataspace dataspace, 288 bitfield<FormatColorComponent> componentMask); 289 290 /** DisplayedContentSampling values passed to setDisplayedContentSamplingEnabled. */ 291 enum DisplayedContentSampling : int32_t { 292 INVALID = 0, 293 294 /** Enable content sampling. */ 295 ENABLE = 1, 296 297 /** Disable content sampling. */ 298 DISABLE = 2, 299 }; 300 301 /** 302 * Enables or disables the collection of color content statistics 303 * on this display. 304 * 305 * Sampling occurs on the contents of the final composition on this display 306 * (i.e., the contents presented on screen). Samples should be collected after all 307 * color transforms have been applied. 308 * 309 * Sampling support is optional, and is set to DISABLE by default. 310 * On each call to ENABLE, all collected statistics must be reset. 311 * 312 * Sample data can be queried via getDisplayedContentSample(). 313 * 314 * @param display is the display to which the sampling mode is set. 315 * @param enabled indicates whether to enable or disable sampling. 316 * @param componentMask The mask of which components should be sampled. If zero, all supported 317 * components are to be enabled. 318 * @param maxFrames is the maximum number of frames that should be stored before discard. 319 * The sample represents the most-recently posted frames. 320 * @return error is NONE upon success. Otherwise, 321 * BAD_DISPLAY when an invalid display handle was passed in, 322 * BAD_PARAMETER when enabled was an invalid value, or 323 * NO_RESOURCES when the requested ringbuffer size via maxFrames was 324 * not available. 325 * UNSUPPORTED when there is no efficient way to sample. 326 */ 327 setDisplayedContentSamplingEnabled( 328 Display display, DisplayedContentSampling enable, 329 bitfield<FormatColorComponent> componentMask, uint64_t maxFrames) 330 generates (Error error); 331 332 /** 333 * Collects the results of display content color sampling for display. 334 * 335 * Collection of data can occur whether the sampling is in ENABLE or 336 * DISABLE state. 337 * 338 * @param display is the display to which the sampling is collected. 339 * @param maxFrames is the maximum number of frames that should be represented in the sample. 340 * The sample represents the most-recently posted frames. 341 * If maxFrames is 0, all frames are to be represented by the sample. 342 * @param timestamp is the timestamp after which any frames were posted that should be 343 * included in the sample. Timestamp is CLOCK_MONOTONIC. 344 * If timestamp is 0, do not filter from the sample by time. 345 * @return error is NONE upon success. Otherwise, 346 * BAD_DISPLAY when an invalid display was passed in, or 347 * UNSUPPORTED when there is no efficient way to sample, or 348 * BAD_PARAMETER when the component is not supported by the hardware. 349 * @return frameCount The number of frames represented by this sample. 350 * @return sampleComponent0 is a histogram counting how many times a pixel of a given value 351 * was displayed onscreen for FORMAT_COMPONENT_0. 352 * The buckets of the histogram are evenly weighted, the number of buckets 353 * is device specific. 354 * eg, for RGBA_8888, if sampleComponent0 is {10, 6, 4, 1} this means that 355 * 10 red pixels were displayed onscreen in range 0x00->0x3F, 6 red pixels 356 * were displayed onscreen in range 0x40->0x7F, etc. 357 * @return sampleComponent1 is the same sample definition as sampleComponent0, 358 * but for FORMAT_COMPONENT_1. 359 * @return sampleComponent2 is the same sample definition as sampleComponent0, 360 * but for FORMAT_COMPONENT_2. 361 * @return sampleComponent3 is the same sample definition as sampleComponent0, 362 * but for FORMAT_COMPONENT_3. 363 */ 364 getDisplayedContentSample(Display display, uint64_t maxFrames, uint64_t timestamp) 365 generates (Error error, 366 uint64_t frameCount, 367 vec<uint64_t> sampleComponent0, 368 vec<uint64_t> sampleComponent1, 369 vec<uint64_t> sampleComponent2, 370 vec<uint64_t> sampleComponent3); 371 372 /** 373 * Executes commands from the input command message queue. Return values 374 * generated by the input commands are written to the output command 375 * message queue in the form of value commands. 376 * 377 * @param inLength is the length of input commands. 378 * @param inHandles is an array of handles referenced by the input 379 * commands. 380 * @return error is NONE upon success. Otherwise, 381 * BAD_PARAMETER when inLength is not equal to the length of 382 * commands in the input command message queue. 383 * NO_RESOURCES when the output command message queue was not 384 * properly drained. 385 * @param outQueueChanged indicates whether the output command message 386 * queue has changed. 387 * @param outLength is the length of output commands. 388 * @param outHandles is an array of handles referenced by the output 389 * commands. 390 */ 391 executeCommands_2_3(uint32_t inLength, 392 vec<handle> inHandles) 393 generates (Error error, 394 bool outQueueChanged, 395 uint32_t outLength, 396 vec<handle> outHandles); 397 398 /** 399 * Returns the render intents supported by the specified display and color 400 * mode. 401 * 402 * For SDR color modes, RenderIntent::COLORIMETRIC must be supported. For 403 * HDR color modes, RenderIntent::TONE_MAP_COLORIMETRIC must be supported. 404 * 405 * @param display is the display to query. 406 * @param mode is the color mode to query. 407 * @return error is NONE upon success. Otherwise, 408 * BAD_DISPLAY when an invalid display handle was passed in. 409 * BAD_PARAMETER when an invalid color mode was passed in. 410 * @return intents is an array of render intents. 411 */ 412 getRenderIntents_2_3(Display display, ColorMode mode) 413 generates (Error error, 414 vec<RenderIntent> intents); 415 416 /** 417 * Returns the color modes supported on this display. 418 * 419 * All devices must support at least ColorMode::NATIVE. 420 * 421 * @param display is the display to query. 422 * @return error is NONE upon success. Otherwise, 423 * BAD_DISPLAY when an invalid display handle was passed in. 424 * @return modes is an array of color modes. 425 */ 426 getColorModes_2_3(Display display) 427 generates (Error error, 428 vec<ColorMode> modes); 429 430 /** 431 * Sets the color mode and render intent of the given display. 432 * 433 * The color mode and render intent change must take effect on next 434 * presentDisplay. 435 * 436 * All devices must support at least ColorMode::NATIVE and 437 * RenderIntent::COLORIMETRIC, and displays are assumed to be in this mode 438 * upon hotplug. 439 * 440 * @param display is the display to which the color mode is set. 441 * @param mode is the color mode to set to. 442 * @param intent is the render intent to set to. 443 * @return error is NONE upon success. Otherwise, 444 * BAD_DISPLAY when an invalid display handle was passed in. 445 * BAD_PARAMETER when mode or intent is invalid 446 * UNSUPPORTED when mode or intent is not supported on this 447 * display. 448 */ 449 setColorMode_2_3(Display display, ColorMode mode, RenderIntent intent) 450 generates (Error error); 451 452 /** 453 * Provides a list of supported capabilities (as described in the 454 * definition of DisplayCapability above). This list must not change after 455 * initialization. 456 * 457 * @return error is NONE upon success. Otherwise, 458 * BAD_DISPLAY when an invalid display handle was passed in. 459 * @return capabilities is a list of supported capabilities. 460 */ 461 getDisplayCapabilities(Display display) 462 generates (Error error, 463 vec<DisplayCapability> capabilities); 464 465 /** 466 * Returns the PerFrameMetadataKeys that are supported by this device. 467 * 468 * @param display is the display on which to create the layer. 469 * @return keys is the vector of PerFrameMetadataKey keys that are 470 * supported by this device. 471 * @return error is NONE upon success. Otherwise, 472 * UNSUPPORTED if not supported on underlying HAL 473 */ 474 getPerFrameMetadataKeys_2_3(Display display) 475 generates (Error error, 476 vec<PerFrameMetadataKey> keys); 477 478 /** 479 * Returns the high dynamic range (HDR) capabilities of the given display, 480 * which are invariant with regard to the active configuration. 481 * 482 * Displays which are not HDR-capable must return no types. 483 * 484 * @param display is the display to query. 485 * @return error is NONE upon success. Otherwise, 486 * BAD_DISPLAY when an invalid display handle was passed in. 487 * @return types is an array of HDR types, may have 0 elements if the 488 * display is not HDR-capable. 489 * @return maxLuminance is the desired content maximum luminance for this 490 * display in cd/m^2. 491 * @return maxAverageLuminance - the desired content maximum frame-average 492 * luminance for this display in cd/m^2. 493 * @return minLuminance is the desired content minimum luminance for this 494 * display in cd/m^2. 495 */ 496 @callflow(next="*") 497 getHdrCapabilities_2_3(Display display) 498 generates (Error error, 499 vec<Hdr> types, 500 float maxLuminance, 501 float maxAverageLuminance, 502 float minLuminance); 503 504 /** 505 * Use getDisplayCapabilities instead. If brightness is supported, must return 506 * DisplayCapability::BRIGHTNESS as one of the display capabilities via getDisplayCapabilities. 507 * Only use getDisplayCapabilities as the source of truth to query brightness support. 508 * 509 * Gets whether brightness operations are supported on a display. 510 * 511 * @param display 512 * The display. 513 * 514 * @return error is NONE upon success. Otherwise, 515 * BAD_DISPLAY when the display is invalid, or 516 * BAD_PARAMETER when the output parameter is invalid. 517 * @return support 518 * Whether brightness operations are supported on the display. 519 */ 520 getDisplayBrightnessSupport(Display display) generates (Error error, bool support); 521 522 /** 523 * Sets the brightness of a display. 524 * 525 * Ideally, the brightness change should take effect in the next frame post (so that it can be 526 * aligned with color transforms). 527 * 528 * @param display 529 * The display whose brightness is set. 530 * @param brightness 531 * A number between 0.0f (minimum brightness) and 1.0f (maximum brightness), or -1.0 to 532 * turn the backlight off. 533 * 534 * @return error is NONE upon success. Otherwise, 535 * BAD_DISPLAY when the display is invalid, or 536 * UNSUPPORTED when brightness operations are not supported, or 537 * BAD_PARAMETER when the brightness is invalid, or 538 * NO_RESOURCES when the brightness cannot be applied. 539 */ 540 setDisplayBrightness(Display display, float brightness) generates (Error error); 541 }; 542
