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.2; 18 19 import android.hardware.graphics.common@1.1::ColorMode; 20 import android.hardware.graphics.common@1.1::Dataspace; 21 import android.hardware.graphics.common@1.1::PixelFormat; 22 import android.hardware.graphics.common@1.1::RenderIntent; 23 import @2.1::IComposerClient; 24 import @2.1::Display; 25 import @2.1::Error; 26 import @2.1::IComposerClient; 27 28 interface IComposerClient extends @2.1::IComposerClient { 29 30 enum PowerMode : @2.1::IComposerClient.PowerMode { 31 /** 32 * The display is configured as in ON but may stop applying display 33 * updates from the client. This is effectively a hint to the device 34 * that drawing to the display has been suspended and that the the 35 * device must remain on and continue displaying its current contents 36 * indefinitely until the power mode changes. 37 * 38 * This mode may also be used as a signal to enable hardware-based 39 * functionality to take over the display and manage it autonomously 40 * to implement a low power always-on display. 41 */ 42 ON_SUSPEND = 4 43 }; 44 45 /** 46 * Following enums define keys for metadata defined by SMPTE ST 2086:2014 47 * and CTA 861.3. 48 */ 49 enum PerFrameMetadataKey : int32_t { 50 /** SMPTE ST 2084:2014. 51 * Coordinates defined in CIE 1931 xy chromaticity space 52 */ 53 /** SMPTE ST 2084:2014 */ 54 DISPLAY_RED_PRIMARY_X, 55 /** SMPTE ST 2084:2014 */ 56 DISPLAY_RED_PRIMARY_Y, 57 /** SMPTE ST 2084:2014 */ 58 DISPLAY_GREEN_PRIMARY_X, 59 /** SMPTE ST 2084:2014 */ 60 DISPLAY_GREEN_PRIMARY_Y, 61 /** SMPTE ST 2084:2014 */ 62 DISPLAY_BLUE_PRIMARY_X, 63 /** SMPTE ST 2084:2014 */ 64 DISPLAY_BLUE_PRIMARY_Y, 65 /** SMPTE ST 2084:2014 */ 66 WHITE_POINT_X, 67 /** SMPTE ST 2084:2014 */ 68 WHITE_POINT_Y, 69 /** SMPTE ST 2084:2014. 70 * Units: nits 71 * max as defined by ST 2048: 10,000 nits 72 */ 73 MAX_LUMINANCE, 74 /** SMPTE ST 2084:2014 */ 75 MIN_LUMINANCE, 76 /** CTA 861.3 */ 77 MAX_CONTENT_LIGHT_LEVEL, 78 /** CTA 861.3 */ 79 MAX_FRAME_AVERAGE_LIGHT_LEVEL, 80 }; 81 82 struct PerFrameMetadata { 83 PerFrameMetadataKey key; 84 float value; 85 }; 86 87 struct FloatColor { 88 float r; 89 float g; 90 float b; 91 float a; 92 }; 93 94 enum Command : @2.1::IComposerClient.Command { 95 /** 96 * SET_LAYER_PER_FRAME_METADATA has this pseudo prototype 97 * 98 * setLayerPerFrameMetadata(Display display, Layer layer, 99 * vec<PerFrameMetadata> data); 100 * 101 * Sets the PerFrameMetadata for the display. This metadata must be used 102 * by the implementation to better tone map content to that display. 103 * 104 * This is a method that may be called every frame. Thus it's 105 * implemented using buffered transport. 106 * SET_LAYER_PER_FRAME_METADATA is the command used by the buffered transport 107 * mechanism. 108 */ 109 SET_LAYER_PER_FRAME_METADATA = 0x303 << @2.1::IComposerClient.Command:OPCODE_SHIFT, 110 111 /** 112 * SET_LAYER_COLOR has this pseudo prototype 113 * 114 * setLayerColor(FloatColor color); 115 * 116 * Sets the color of the given layer. If the composition type of the layer 117 * is not Composition::SOLID_COLOR, this call must succeed and have no 118 * other effect. 119 * 120 * @param color is the new color using float type. 121 */ 122 SET_LAYER_FLOAT_COLOR = 0x40c << @2.1::IComposerClient.Command:OPCODE_SHIFT, 123 }; 124 125 /** 126 * Returns the PerFrameMetadataKeys that are supported by this device. 127 * 128 * @param display is the display on which to create the layer. 129 * @return keys is the vector of PerFrameMetadataKey keys that are 130 * supported by this device. 131 * @return error is NONE upon success. Otherwise, 132 * UNSUPPORTED if not supported on underlying HAL 133 */ 134 getPerFrameMetadataKeys(Display display) 135 generates (Error error, 136 vec<PerFrameMetadataKey> keys); 137 138 /** 139 * getReadbackBufferAttributes 140 * Returns the format which should be used when allocating a buffer for use by 141 * device readback as well as the dataspace in which its contents should be 142 * interpreted. 143 * 144 * The width and height of this buffer must be those of the currently-active 145 * display configuration, and the usage flags must consist of the following: 146 * BufferUsage::CPU_READ | BufferUsage::GPU_TEXTURE | 147 * BufferUsage::COMPOSER_OUTPUT 148 * 149 * The format and dataspace provided must be sufficient such that if a 150 * correctly-configured buffer is passed into setReadbackBuffer, filled by 151 * the device, and then displayed by the client as a full-screen buffer, the 152 * output of the display remains the same (subject to the note about protected 153 * content in the description of setReadbackBuffer). 154 * 155 * If the active configuration or color mode of this display has changed 156 * since a previous call to this function, it must be called again prior to 157 * setting a readback buffer such that the returned format and dataspace can 158 * be updated accordingly. 159 * 160 * Parameters: 161 * @param display - the display on which to create the layer. 162 * 163 * @return format - the format the client should use when allocating a device 164 * readback buffer 165 * @return dataspace - the dataspace to use when interpreting the 166 * contents of a device readback buffer 167 * @return error is NONE upon success. Otherwise, 168 * BAD_DISPLAY when an invalid display handle was passed in. 169 * UNSUPPORTED if not supported on underlying HAL 170 * 171 * See also: 172 * setReadbackBuffer 173 * getReadbackBufferFence 174 */ 175 getReadbackBufferAttributes(Display display) 176 generates (Error error, 177 PixelFormat format, 178 Dataspace dataspace); 179 180 /** 181 * getReadbackBufferFence 182 * Returns an acquire sync fence file descriptor which must signal when the 183 * buffer provided to setReadbackBuffer has been filled by the device and is 184 * safe for the client to read. 185 * 186 * If it is already safe to read from this buffer, -1 may be returned instead. 187 * The client takes ownership of this file descriptor and is responsible for 188 * closing it when it is no longer needed. 189 * 190 * This function must be called immediately after the composition cycle being 191 * captured into the readback buffer. The complete ordering of a readback buffer 192 * capture is as follows: 193 * 194 * getReadbackBufferAttributes 195 * // Readback buffer is allocated 196 * // Many frames may pass 197 * 198 * setReadbackBuffer 199 * validateDisplay 200 * presentDisplay 201 * getReadbackBufferFence 202 * // Implicitly wait on the acquire fence before accessing the buffer 203 * 204 * Parameters: 205 * @param display - the display on which to create the layer. 206 * 207 * @return acquireFence - a sync fence file descriptor as described above; pointer 208 * must be non-NULL 209 * @return error - is HWC2_ERROR_NONE or one of the following errors: 210 * BAD_DISPLAY - an invalid display handle was passed in 211 * NO_RESOURCES - the readback operation was successful, but 212 * resulted in a different validate result than would 213 * have occurred without readback 214 * UNSUPPORTED - the readback operation was unsuccessful because of 215 * resource constraints, the presence of protected 216 * content, or other reasons; -1 must be returned for 217 * acquireFence 218 * 219 * See also: 220 * getReadbackBufferAttributes 221 * setReadbackBuffer 222 */ 223 getReadbackBufferFence(Display display) 224 generates (Error error, 225 handle acquireFence); 226 227 /** 228 * setReadbackBuffer 229 * Sets the readback buffer to be filled with the contents of the next 230 * composition performed for this display (i.e., the contents present at the 231 * time of the next validateDisplay/presentDisplay cycle). 232 * 233 * This buffer must have been allocated as described in 234 * getReadbackBufferAttributes and is in the dataspace provided by the same. 235 * 236 * If there is hardware protected content on the display at the time of the next 237 * composition, the area of the readback buffer covered by such content must be 238 * completely black. Any areas of the buffer not covered by such content may 239 * optionally be black as well. 240 * 241 * The release fence file descriptor provided works identically to the one 242 * described for setOutputBuffer. 243 * 244 * This function must not be called between any call to validateDisplay and a 245 * subsequent call to presentDisplay. 246 * 247 * Parameters: 248 * @param display - the display on which to create the layer. 249 * @param buffer - the new readback buffer 250 * @param releaseFence - a sync fence file descriptor as described in setOutputBuffer 251 * 252 * @return error - is HWC2_ERROR_NONE or one of the following errors: 253 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in 254 * HWC2_ERROR_BAD_PARAMETER - the new readback buffer handle was invalid 255 * 256 * See also: 257 * getReadbackBufferAttributes 258 * getReadbackBufferFence 259 */ 260 setReadbackBuffer(Display display, handle buffer, handle releaseFence) generates (Error error); 261 262 /** 263 * createVirtualDisplay_2_2 264 * Creates a new virtual display with the given width and height. The 265 * format passed into this function is the default format requested by the 266 * consumer of the virtual display output buffers. 267 * 268 * The display must be assumed to be on from the time the first frame is 269 * presented until the display is destroyed. 270 * 271 * @param width is the width in pixels. 272 * @param height is the height in pixels. 273 * @param formatHint is the default output buffer format selected by 274 * the consumer. 275 * @param outputBufferSlotCount is the number of output buffer slots to be 276 * reserved. 277 * @return error is NONE upon success. Otherwise, 278 * UNSUPPORTED when the width or height is too large for the 279 * device to be able to create a virtual display. 280 * NO_RESOURCES when the device is unable to create a new virtual 281 * display at this time. 282 * @return display is the newly-created virtual display. 283 * @return format is the format of the buffer the device will produce. 284 */ 285 @callflow(next="*") 286 createVirtualDisplay_2_2(uint32_t width, 287 uint32_t height, 288 PixelFormat formatHint, 289 uint32_t outputBufferSlotCount) 290 generates (Error error, 291 Display display, 292 PixelFormat format); 293 294 /** 295 * getClientTargetSupport_2_2 296 * Returns whether a client target with the given properties can be 297 * handled by the device. 298 * 299 * This function must return true for a client target with width and 300 * height equal to the active display configuration dimensions, 301 * PixelFormat::RGBA_8888, and Dataspace::UNKNOWN. It is not required to 302 * return true for any other configuration. 303 * 304 * @param display is the display to query. 305 * @param width is the client target width in pixels. 306 * @param height is the client target height in pixels. 307 * @param format is the client target format. 308 * @param dataspace is the client target dataspace, as described in 309 * setLayerDataspace. 310 * @return error is NONE upon success. Otherwise, 311 * BAD_DISPLAY when an invalid display handle was passed in. 312 * UNSUPPORTED when the given configuration is not supported. 313 */ 314 @callflow(next="*") 315 getClientTargetSupport_2_2(Display display, 316 uint32_t width, 317 uint32_t height, 318 PixelFormat format, 319 Dataspace dataspace) 320 generates (Error error); 321 /** 322 * setPowerMode_2_2 323 * Sets the power mode of the given display. The transition must be 324 * complete when this function returns. It is valid to call this function 325 * multiple times with the same power mode. 326 * 327 * All displays must support PowerMode::ON and PowerMode::OFF. Whether a 328 * display supports PowerMode::DOZE or PowerMode::DOZE_SUSPEND may be 329 * queried using getDozeSupport. 330 * 331 * @param display is the display to which the power mode is set. 332 * @param mode is the new power mode. 333 * @return error is NONE upon success. Otherwise, 334 * BAD_DISPLAY when an invalid display handle was passed in. 335 * BAD_PARAMETER when mode was not a valid power mode. 336 * UNSUPPORTED when mode is not supported on this display. 337 */ 338 setPowerMode_2_2(Display display, PowerMode mode) generates (Error error); 339 340 /** 341 * Returns the color modes supported on this display. 342 * 343 * All devices must support at least ColorMode::NATIVE. 344 * 345 * @param display is the display to query. 346 * @return error is NONE upon success. Otherwise, 347 * BAD_DISPLAY when an invalid display handle was passed in. 348 * @return modes is an array of color modes. 349 */ 350 getColorModes_2_2(Display display) 351 generates (Error error, 352 vec<ColorMode> modes); 353 354 /** 355 * Returns the render intents supported by the specified display and color 356 * mode. 357 * 358 * For SDR color modes, RenderIntent::COLORIMETRIC must be supported. For 359 * HDR color modes, RenderIntent::TONE_MAP_COLORIMETRIC must be supported. 360 * 361 * @param display is the display to query. 362 * @param mode is the color mode to query. 363 * @return error is NONE upon success. Otherwise, 364 * BAD_DISPLAY when an invalid display handle was passed in. 365 * BAD_PARAMETER when an invalid color mode was passed in. 366 * @return intents is an array of render intents. 367 */ 368 getRenderIntents(Display display, ColorMode mode) 369 generates (Error error, 370 vec<RenderIntent> intents); 371 372 /** 373 * Sets the color mode and render intent of the given display. 374 * 375 * The color mode and render intent change must take effect on next 376 * presentDisplay. 377 * 378 * All devices must support at least ColorMode::NATIVE and 379 * RenderIntent::COLORIMETRIC, and displays are assumed to be in this mode 380 * upon hotplug. 381 * 382 * @param display is the display to which the color mode is set. 383 * @param mode is the color mode to set to. 384 * @param intent is the render intent to set to. 385 * @return error is NONE upon success. Otherwise, 386 * BAD_DISPLAY when an invalid display handle was passed in. 387 * BAD_PARAMETER when mode or intent is invalid 388 * UNSUPPORTED when mode or intent is not supported on this 389 * display. 390 */ 391 setColorMode_2_2(Display display, ColorMode mode, RenderIntent intent) 392 generates (Error error); 393 394 /* 395 * By default, layer dataspaces are mapped to the current color mode 396 * colorimetrically with a few exceptions. 397 * 398 * When the layer dataspace is a legacy dataspace (see 399 * common (at) 1.1::Dataspace) and the display render intent is 400 * RenderIntent::ENHANCE, the pixel values can go through an 401 * implementation-defined saturation transform before being mapped to the 402 * current color mode colorimetrically. 403 * 404 * Colors that are out of the gamut of the current color mode are 405 * hard-clipped. 406 */ 407 408 /** 409 * Returns the saturation matrix of the specified legacy dataspace. 410 * 411 * The saturation matrix can be used to approximate the legacy dataspace 412 * saturation transform. It is to be applied on linear pixel values like 413 * this: 414 * 415 * (in GLSL) 416 * linearSrgb = saturationMatrix * linearSrgb; 417 * 418 * @param dataspace must be Dataspace::SRGB_LINEAR. 419 * @return error is NONE upon success. Otherwise, 420 * BAD_PARAMETER when an invalid dataspace was passed in. 421 * @return matrix is the 4x4 column-major matrix used to approximate the 422 * legacy dataspace saturation operation. The last row must be 423 * [0.0, 0.0, 0.0, 1.0]. 424 */ 425 getDataspaceSaturationMatrix(Dataspace dataspace) 426 generates (Error error, 427 float[4][4] matrix); 428 429 /** 430 * Executes commands from the input command message queue. Return values 431 * generated by the input commands are written to the output command 432 * message queue in the form of value commands. 433 * 434 * @param inLength is the length of input commands. 435 * @param inHandles is an array of handles referenced by the input 436 * commands. 437 * @return error is NONE upon success. Otherwise, 438 * BAD_PARAMETER when inLength is not equal to the length of 439 * commands in the input command message queue. 440 * NO_RESOURCES when the output command message queue was not 441 * properly drained. 442 * @param outQueueChanged indicates whether the output command message 443 * queue has changed. 444 * @param outLength is the length of output commands. 445 * @param outHandles is an array of handles referenced by the output 446 * commands. 447 */ 448 executeCommands_2_2(uint32_t inLength, 449 vec<handle> inHandles) 450 generates (Error error, 451 bool outQueueChanged, 452 uint32_t outLength, 453 vec<handle> outHandles); 454 }; 455
