1/* 2 * Copyright (C) 2016 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 17package android.hardware.graphics.composer@2.1; 18 19import android.hardware.graphics.common@1.0; 20import IComposerCallback; 21 22interface IComposerClient { 23 /** Display attributes queryable through getDisplayAttribute. */ 24 enum Attribute : int32_t { 25 INVALID = 0, 26 27 /** Dimensions in pixels */ 28 WIDTH = 1, 29 HEIGHT = 2, 30 31 /** Vsync period in nanoseconds */ 32 VSYNC_PERIOD = 3, 33 34 /** 35 * Dots per thousand inches (DPI * 1000). Scaling by 1000 allows these 36 * numbers to be stored in an int32_t without losing too much 37 * precision. If the DPI for a configuration is unavailable or is 38 * considered unreliable, the device may return UNSUPPORTED instead. 39 */ 40 DPI_X = 4, 41 DPI_Y = 5, 42 }; 43 44 /** Display requests returned by getDisplayRequests. */ 45 enum DisplayRequest : uint32_t { 46 /** 47 * Instructs the client to provide a new client target buffer, even if 48 * no layers are marked for client composition. 49 */ 50 FLIP_CLIENT_TARGET = 1 << 0, 51 52 /** 53 * Instructs the client to write the result of client composition 54 * directly into the virtual display output buffer. If any of the 55 * layers are not marked as Composition::CLIENT or the given display 56 * is not a virtual display, this request has no effect. 57 */ 58 WRITE_CLIENT_TARGET_TO_OUTPUT = 1 << 1, 59 }; 60 61 /** Layer requests returned from getDisplayRequests. */ 62 enum LayerRequest : uint32_t { 63 /** 64 * The client must clear its target with transparent pixels where 65 * this layer would be. The client may ignore this request if the 66 * layer must be blended. 67 */ 68 CLEAR_CLIENT_TARGET = 1 << 0, 69 }; 70 71 /** Power modes for use with setPowerMode. */ 72 enum PowerMode : int32_t { 73 /** The display is fully off (blanked). */ 74 OFF = 0, 75 76 /** 77 * These are optional low power modes. getDozeSupport may be called to 78 * determine whether a given display supports these modes. 79 */ 80 81 /** 82 * The display is turned on and configured in a low power state that 83 * is suitable for presenting ambient information to the user, 84 * possibly with lower fidelity than ON, but with greater efficiency. 85 */ 86 DOZE = 1, 87 88 /** 89 * The display is configured as in DOZE but may stop applying display 90 * updates from the client. This is effectively a hint to the device 91 * that drawing to the display has been suspended and that the the 92 * device must remain on in a low power state and continue 93 * displaying its current contents indefinitely until the power mode 94 * changes. 95 * 96 * This mode may also be used as a signal to enable hardware-based 97 * doze functionality. In this case, the device is free to take over 98 * the display and manage it autonomously to implement a low power 99 * always-on display. 100 */ 101 DOZE_SUSPEND = 3, 102 103 /** The display is fully on. */ 104 ON = 2, 105 }; 106 107 /** Vsync values passed to setVsyncEnabled. */ 108 enum Vsync : int32_t { 109 INVALID = 0, 110 111 /** Enable vsync. */ 112 ENABLE = 1, 113 114 /** Disable vsync. */ 115 DISABLE = 2, 116 }; 117 118 /** Blend modes, settable per layer. */ 119 enum BlendMode : int32_t { 120 INVALID = 0, 121 122 /** colorOut = colorSrc */ 123 NONE = 1, 124 125 /** colorOut = colorSrc + colorDst * (1 - alphaSrc) */ 126 PREMULTIPLIED = 2, 127 128 /** colorOut = colorSrc * alphaSrc + colorDst * (1 - alphaSrc) */ 129 COVERAGE = 3, 130 }; 131 132 /** Possible composition types for a given layer. */ 133 enum Composition : int32_t { 134 INVALID = 0, 135 136 /** 137 * The client must composite this layer into the client target buffer 138 * (provided to the device through setClientTarget). 139 * 140 * The device must not request any composition type changes for layers 141 * of this type. 142 */ 143 CLIENT = 1, 144 145 /** 146 * The device must handle the composition of this layer through a 147 * hardware overlay or other similar means. 148 * 149 * Upon validateDisplay, the device may request a change from this 150 * type to CLIENT. 151 */ 152 DEVICE = 2, 153 154 /** 155 * The device must render this layer using the color set through 156 * setLayerColor. If this functionality is not supported on a layer 157 * that the client sets to SOLID_COLOR, the device must request that 158 * the composition type of that layer is changed to CLIENT upon the 159 * next call to validateDisplay. 160 * 161 * Upon validateDisplay, the device may request a change from this 162 * type to CLIENT. 163 */ 164 SOLID_COLOR = 3, 165 166 /** 167 * Similar to DEVICE, but the position of this layer may also be set 168 * asynchronously through setCursorPosition. If this functionality is 169 * not supported on a layer that the client sets to CURSOR, the device 170 * must request that the composition type of that layer is changed to 171 * CLIENT upon the next call to validateDisplay. 172 * 173 * Upon validateDisplay, the device may request a change from this 174 * type to either DEVICE or CLIENT. Changing to DEVICE will prevent 175 * the use of setCursorPosition but still permit the device to 176 * composite the layer. 177 */ 178 CURSOR = 4, 179 180 /** 181 * The device must handle the composition of this layer, as well as 182 * its buffer updates and content synchronization. Only supported on 183 * devices which provide Capability::SIDEBAND_STREAM. 184 * 185 * Upon validateDisplay, the device may request a change from this 186 * type to either DEVICE or CLIENT, but it is unlikely that content 187 * will display correctly in these cases. 188 */ 189 SIDEBAND = 5, 190 }; 191 192 /** Display types returned by getDisplayType. */ 193 enum DisplayType : int32_t { 194 INVALID = 0, 195 196 /** 197 * All physical displays, including both internal displays and 198 * hotpluggable external displays. 199 */ 200 PHYSICAL = 1, 201 202 /** Virtual displays created by createVirtualDisplay. */ 203 VIRTUAL = 2, 204 }; 205 206 /** Special index values (always negative) for command queue commands. */ 207 enum HandleIndex : int32_t { 208 /** No handle */ 209 EMPTY = -1, 210 211 /** Use cached handle */ 212 CACHED = -2, 213 }; 214 215 struct Rect { 216 int32_t left; 217 int32_t top; 218 int32_t right; 219 int32_t bottom; 220 }; 221 222 struct FRect { 223 float left; 224 float top; 225 float right; 226 float bottom; 227 }; 228 229 struct Color { 230 uint8_t r; 231 uint8_t g; 232 uint8_t b; 233 uint8_t a; 234 }; 235 236 /** 237 * Provides a IComposerCallback object for the device to call. 238 * 239 * This function must be called only once. 240 * 241 * @param callback is the IComposerCallback object. 242 */ 243 @entry 244 @callflow(next="*") 245 registerCallback(IComposerCallback callback); 246 247 /** 248 * Returns the maximum number of virtual displays supported by this device 249 * (which may be 0). The client must not attempt to create more than this 250 * many virtual displays on this device. This number must not change for 251 * the lifetime of the device. 252 * 253 * @return count is the maximum number of virtual displays supported. 254 */ 255 @callflow(next="*") 256 getMaxVirtualDisplayCount() generates (uint32_t count); 257 258 /** 259 * Creates a new virtual display with the given width and height. The 260 * format passed into this function is the default format requested by the 261 * consumer of the virtual display output buffers. 262 * 263 * The display must be assumed to be on from the time the first frame is 264 * presented until the display is destroyed. 265 * 266 * @param width is the width in pixels. 267 * @param height is the height in pixels. 268 * @param formatHint is the default output buffer format selected by 269 * the consumer. 270 * @param outputBufferSlotCount is the number of output buffer slots to be 271 * reserved. 272 * @return error is NONE upon success. Otherwise, 273 * UNSUPPORTED when the width or height is too large for the 274 * device to be able to create a virtual display. 275 * NO_RESOURCES when the device is unable to create a new virtual 276 * display at this time. 277 * @return display is the newly-created virtual display. 278 * @return format is the format of the buffer the device will produce. 279 */ 280 @callflow(next="*") 281 createVirtualDisplay(uint32_t width, 282 uint32_t height, 283 PixelFormat formatHint, 284 uint32_t outputBufferSlotCount) 285 generates (Error error, 286 Display display, 287 PixelFormat format); 288 289 /** 290 * Destroys a virtual display. After this call all resources consumed by 291 * this display may be freed by the device and any operations performed on 292 * this display must fail. 293 * 294 * @param display is the virtual display to destroy. 295 * @return error is NONE upon success. Otherwise, 296 * BAD_DISPLAY when an invalid display handle was passed in. 297 * BAD_PARAMETER when the display handle which was passed in does 298 * not refer to a virtual display. 299 */ 300 @callflow(next="*") 301 destroyVirtualDisplay(Display display) generates (Error error); 302 303 /** 304 * Creates a new layer on the given display. 305 * 306 * @param display is the display on which to create the layer. 307 * @param bufferSlotCount is the number of buffer slot to be reserved. 308 * @return error is NONE upon success. Otherwise, 309 * BAD_DISPLAY when an invalid display handle was passed in. 310 * NO_RESOURCES when the device was unable to create a layer this 311 * time. 312 * @return layer is the handle of the new layer. 313 */ 314 @callflow(next="*") 315 createLayer(Display display, 316 uint32_t bufferSlotCount) 317 generates (Error error, 318 Layer layer); 319 320 /** 321 * Destroys the given layer. 322 * 323 * @param display is the display on which the layer was created. 324 * @param layer is the layer to destroy. 325 * @return error is NONE upon success. Otherwise, 326 * BAD_DISPLAY when an invalid display handle was passed in. 327 * BAD_LAYER when an invalid layer handle was passed in. 328 */ 329 @callflow(next="*") 330 destroyLayer(Display display, Layer layer) generates (Error error); 331 332 /** 333 * Retrieves which display configuration is currently active. 334 * 335 * If no display configuration is currently active, this function must 336 * return BAD_CONFIG. It is the responsibility of the client to call 337 * setActiveConfig with a valid configuration before attempting to present 338 * anything on the display. 339 * 340 * @param display is the display to which the active config is queried. 341 * @return error is NONE upon success. Otherwise, 342 * BAD_DISPLAY when an invalid display handle was passed in. 343 * BAD_CONFIG when no configuration is currently active. 344 * @return config is the currently active display configuration. 345 */ 346 @callflow(next="*") 347 getActiveConfig(Display display) generates (Error error, Config config); 348 349 /** 350 * Returns whether a client target with the given properties can be 351 * handled by the device. 352 * 353 * This function must return true for a client target with width and 354 * height equal to the active display configuration dimensions, 355 * PixelFormat::RGBA_8888, and Dataspace::UNKNOWN. It is not required to 356 * return true for any other configuration. 357 * 358 * @param display is the display to query. 359 * @param width is the client target width in pixels. 360 * @param height is the client target height in pixels. 361 * @param format is the client target format. 362 * @param dataspace is the client target dataspace, as described in 363 * setLayerDataspace. 364 * @return error is NONE upon success. Otherwise, 365 * BAD_DISPLAY when an invalid display handle was passed in. 366 * UNSUPPORTED when the given configuration is not supported. 367 */ 368 @callflow(next="*") 369 getClientTargetSupport(Display display, 370 uint32_t width, 371 uint32_t height, 372 PixelFormat format, 373 Dataspace dataspace) 374 generates (Error error); 375 376 /** 377 * Returns the color modes supported on this display. 378 * 379 * All devices must support at least ColorMode::NATIVE. 380 * 381 * @param display is the display to query. 382 * @return error is NONE upon success. Otherwise, 383 * BAD_DISPLAY when an invalid display handle was passed in. 384 * @return modes is an array of color modes. 385 */ 386 @callflow(next="*") 387 getColorModes(Display display) 388 generates (Error error, 389 vec<ColorMode> modes); 390 391 /** 392 * Returns a display attribute value for a particular display 393 * configuration. 394 * 395 * @param display is the display to query. 396 * @param config is the display configuration for which to return 397 * attribute values. 398 * @return error is NONE upon success. Otherwise, 399 * BAD_DISPLAY when an invalid display handle was passed in. 400 * BAD_CONFIG when config does not name a valid configuration for 401 * this display. 402 * BAD_PARAMETER when attribute is unrecognized. 403 * UNSUPPORTED when attribute cannot be queried for the config. 404 * @return value is the value of the attribute. 405 */ 406 @callflow(next="*") 407 getDisplayAttribute(Display display, 408 Config config, 409 Attribute attribute) 410 generates (Error error, 411 int32_t value); 412 413 /** 414 * Returns handles for all of the valid display configurations on this 415 * display. 416 * 417 * @param display is the display to query. 418 * @return error is NONE upon success. Otherwise, 419 * BAD_DISPLAY when an invalid display handle was passed in. 420 * @return configs is an array of configuration handles. 421 */ 422 @callflow(next="*") 423 getDisplayConfigs(Display display) 424 generates (Error error, 425 vec<Config> configs); 426 427 /** 428 * Returns a human-readable version of the display's name. 429 * 430 * @return error is NONE upon success. Otherwise, 431 * BAD_DISPLAY when an invalid display handle was passed in. 432 * @return name is the name of the display. 433 */ 434 @callflow(next="*") 435 getDisplayName(Display display) generates (Error error, string name); 436 437 /** 438 * Returns whether the given display is a physical or virtual display. 439 * 440 * @param display is the display to query. 441 * @return error is NONE upon success. Otherwise, 442 * BAD_DISPLAY when an invalid display handle was passed in. 443 * @return type is the type of the display. 444 */ 445 @callflow(next="*") 446 getDisplayType(Display display) generates (Error error, DisplayType type); 447 448 /** 449 * Returns whether the given display supports PowerMode::DOZE and 450 * PowerMode::DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit over 451 * DOZE (see the definition of PowerMode for more information), but if 452 * both DOZE and DOZE_SUSPEND are no different from PowerMode::ON, the 453 * device must not claim support. 454 * 455 * @param display is the display to query. 456 * @return error is NONE upon success. Otherwise, 457 * BAD_DISPLAY when an invalid display handle was passed in. 458 * @return support is true only when the display supports doze modes. 459 */ 460 @callflow(next="*") 461 getDozeSupport(Display display) generates (Error error, bool support); 462 463 /** 464 * Returns the high dynamic range (HDR) capabilities of the given display, 465 * which are invariant with regard to the active configuration. 466 * 467 * Displays which are not HDR-capable must return no types. 468 * 469 * @param display is the display to query. 470 * @return error is NONE upon success. Otherwise, 471 * BAD_DISPLAY when an invalid display handle was passed in. 472 * @return types is an array of HDR types, may have 0 elements if the 473 * display is not HDR-capable. 474 * @return maxLuminance is the desired content maximum luminance for this 475 * display in cd/m^2. 476 * @return maxAverageLuminance - the desired content maximum frame-average 477 * luminance for this display in cd/m^2. 478 * @return minLuminance is the desired content minimum luminance for this 479 * display in cd/m^2. 480 */ 481 @callflow(next="*") 482 getHdrCapabilities(Display display) 483 generates (Error error, 484 vec<Hdr> types, 485 float maxLuminance, 486 float maxAverageLuminance, 487 float minLuminance); 488 489 /** 490 * Set the number of client target slots to be reserved. 491 * 492 * @param display is the display to which the slots are reserved. 493 * @param clientTargetSlotCount is the slot count for client targets. 494 * @return error is NONE upon success. Otherwise, 495 * BAD_DISPLAY when an invalid display handle was passed in. 496 * NO_RESOURCES when unable to reserve the slots. 497 */ 498 @callflow(next="*") 499 setClientTargetSlotCount(Display display, 500 uint32_t clientTargetSlotCount) 501 generates (Error error); 502 503 /** 504 * Sets the active configuration for this display. Upon returning, the 505 * given display configuration must be active and remain so until either 506 * this function is called again or the display is disconnected. 507 * 508 * @param display is the display to which the active config is set. 509 * @param config is the new display configuration. 510 * @return error is NONE upon success. Otherwise, 511 * BAD_DISPLAY when an invalid display handle was passed in. 512 * BAD_CONFIG when the configuration handle passed in is not valid 513 * for this display. 514 */ 515 @callflow(next="*") 516 setActiveConfig(Display display, Config config) generates (Error error); 517 518 /** 519 * Sets the color mode of the given display. 520 * 521 * Upon returning from this function, the color mode change must have 522 * fully taken effect. 523 * 524 * All devices must support at least ColorMode::NATIVE, and displays are 525 * assumed to be in this mode upon hotplug. 526 * 527 * @param display is the display to which the color mode is set. 528 * @param mode is the mode to set to. 529 * @return error is NONE upon success. Otherwise, 530 * BAD_DISPLAY when an invalid display handle was passed in. 531 * BAD_PARAMETER when mode is not a valid color mode. 532 * UNSUPPORTED when mode is not supported on this display. 533 */ 534 @callflow(next="*") 535 setColorMode(Display display, ColorMode mode) generates (Error error); 536 537 /** 538 * Sets the power mode of the given display. The transition must be 539 * complete when this function returns. It is valid to call this function 540 * multiple times with the same power mode. 541 * 542 * All displays must support PowerMode::ON and PowerMode::OFF. Whether a 543 * display supports PowerMode::DOZE or PowerMode::DOZE_SUSPEND may be 544 * queried using getDozeSupport. 545 * 546 * @param display is the display to which the power mode is set. 547 * @param mode is the new power mode. 548 * @return error is NONE upon success. Otherwise, 549 * BAD_DISPLAY when an invalid display handle was passed in. 550 * BAD_PARAMETER when mode was not a valid power mode. 551 * UNSUPPORTED when mode is not supported on this display. 552 */ 553 @callflow(next="*") 554 setPowerMode(Display display, PowerMode mode) generates (Error error); 555 556 /** 557 * Enables or disables the vsync signal for the given display. Virtual 558 * displays never generate vsync callbacks, and any attempt to enable 559 * vsync for a virtual display though this function must succeed and have 560 * no other effect. 561 * 562 * @param display is the display to which the vsync mode is set. 563 * @param enabled indicates whether to enable or disable vsync 564 * @return error is NONE upon success. Otherwise, 565 * BAD_DISPLAY when an invalid display handle was passed in. 566 * BAD_PARAMETER when enabled was an invalid value. 567 */ 568 @callflow(next="*") 569 setVsyncEnabled(Display display, Vsync enabled) generates (Error error); 570 571 /** 572 * Sets the input command message queue. 573 * 574 * @param descriptor is the descriptor of the input command message queue. 575 * @return error is NONE upon success. Otherwise, 576 * NO_RESOURCES when failed to set the queue temporarily. 577 */ 578 @callflow(next="*") 579 setInputCommandQueue(fmq_sync<uint32_t> descriptor) 580 generates (Error error); 581 582 /** 583 * Gets the output command message queue. 584 * 585 * This function must only be called inside executeCommands closure. 586 * 587 * @return error is NONE upon success. Otherwise, 588 * NO_RESOURCES when failed to get the queue temporarily. 589 * @return descriptor is the descriptor of the output command queue. 590 */ 591 @callflow(next="*") 592 getOutputCommandQueue() 593 generates (Error error, 594 fmq_sync<uint32_t> descriptor); 595 596 /** 597 * Executes commands from the input command message queue. Return values 598 * generated by the input commands are written to the output command 599 * message queue in the form of value commands. 600 * 601 * @param inLength is the length of input commands. 602 * @param inHandles is an array of handles referenced by the input 603 * commands. 604 * @return error is NONE upon success. Otherwise, 605 * BAD_PARAMETER when inLength is not equal to the length of 606 * commands in the input command message queue. 607 * NO_RESOURCES when the output command message queue was not 608 * properly drained. 609 * @param outQueueChanged indicates whether the output command message 610 * queue has changed. 611 * @param outLength is the length of output commands. 612 * @param outHandles is an array of handles referenced by the output 613 * commands. 614 */ 615 @callflow(next="*") 616 executeCommands(uint32_t inLength, 617 vec<handle> inHandles) 618 generates (Error error, 619 bool outQueueChanged, 620 uint32_t outLength, 621 vec<handle> outHandles); 622 623 /** 624 * SELECT_DISPLAY has this pseudo prototype 625 * 626 * selectDisplay(Display display); 627 * 628 * Selects the current display implied by all other commands. 629 * 630 * @param display is the newly selected display. 631 * 632 * 633 * SELECT_LAYER has this pseudo prototype 634 * 635 * selectLayer(Layer layer); 636 * 637 * Selects the current layer implied by all implicit layer commands. 638 * 639 * @param layer is the newly selected layer. 640 * 641 * 642 * SET_ERROR has this pseudo prototype 643 * 644 * setError(uint32_t location, Error error); 645 * 646 * Indicates an error generated by a command. 647 * 648 * @param location is the offset of the command in the input command 649 * message queue. 650 * @param error is the error generated by the command. 651 * 652 * 653 * SET_CHANGED_COMPOSITION_TYPES has this pseudo prototype 654 * 655 * setChangedCompositionTypes(vec<Layer> layers, 656 * vec<Composition> types); 657 * 658 * Sets the layers for which the device requires a different composition 659 * type than had been set prior to the last call to VALIDATE_DISPLAY. The 660 * client must either update its state with these types and call 661 * ACCEPT_DISPLAY_CHANGES, or must set new types and attempt to validate 662 * the display again. 663 * 664 * @param layers is an array of layer handles. 665 * @param types is an array of composition types, each corresponding to 666 * an element of layers. 667 * 668 * 669 * SET_DISPLAY_REQUESTS has this pseudo prototype 670 * 671 * setDisplayRequests(uint32_t displayRequestMask, 672 * vec<Layer> layers, 673 * vec<uint32_t> layerRequestMasks); 674 * 675 * Sets the display requests and the layer requests required for the last 676 * validated configuration. 677 * 678 * Display requests provide information about how the client must handle 679 * the client target. Layer requests provide information about how the 680 * client must handle an individual layer. 681 * 682 * @param displayRequestMask is the display requests for the current 683 * validated state. 684 * @param layers is an array of layers which all have at least one 685 * request. 686 * @param layerRequestMasks is the requests corresponding to each element 687 * of layers. 688 * 689 * 690 * SET_PRESENT_FENCE has this pseudo prototype 691 * 692 * setPresentFence(int32_t presentFenceIndex); 693 * 694 * Sets the present fence as a result of PRESENT_DISPLAY. For physical 695 * displays, this fence must be signaled at the vsync when the result 696 * of composition of this frame starts to appear (for video-mode panels) 697 * or starts to transfer to panel memory (for command-mode panels). For 698 * virtual displays, this fence must be signaled when writes to the output 699 * buffer have completed and it is safe to read from it. 700 * 701 * @param presentFenceIndex is an index into outHandles array. 702 * 703 * 704 * SET_RELEASE_FENCES has this pseudo prototype 705 * 706 * setReleaseFences(vec<Layer> layers, 707 * vec<int32_t> releaseFenceIndices); 708 * 709 * Sets the release fences for device layers on this display which will 710 * receive new buffer contents this frame. 711 * 712 * A release fence is a file descriptor referring to a sync fence object 713 * which must be signaled after the device has finished reading from the 714 * buffer presented in the prior frame. This indicates that it is safe to 715 * start writing to the buffer again. If a given layer's fence is not 716 * returned from this function, it must be assumed that the buffer 717 * presented on the previous frame is ready to be written. 718 * 719 * The fences returned by this function must be unique for each layer 720 * (even if they point to the same underlying sync object). 721 * 722 * @param layers is an array of layer handles. 723 * @param releaseFenceIndices are indices into outHandles array, each 724 * corresponding to an element of layers. 725 * 726 * 727 * SET_COLOR_TRANSFORM has this pseudo prototype 728 * 729 * setColorTransform(float[16] matrix, 730 * ColorTransform hint); 731 * 732 * Sets a color transform which will be applied after composition. 733 * 734 * If hint is not ColorTransform::ARBITRARY, then the device may use the 735 * hint to apply the desired color transform instead of using the color 736 * matrix directly. 737 * 738 * If the device is not capable of either using the hint or the matrix to 739 * apply the desired color transform, it must force all layers to client 740 * composition during VALIDATE_DISPLAY. 741 * 742 * If IComposer::Capability::SKIP_CLIENT_COLOR_TRANSFORM is present, then 743 * the client must never apply the color transform during client 744 * composition, even if all layers are being composed by the client. 745 * 746 * The matrix provided is an affine color transformation of the following 747 * form: 748 * 749 * |r.r r.g r.b 0| 750 * |g.r g.g g.b 0| 751 * |b.r b.g b.b 0| 752 * |Tr Tg Tb 1| 753 * 754 * This matrix must be provided in row-major form: 755 * 756 * {r.r, r.g, r.b, 0, g.r, ...}. 757 * 758 * Given a matrix of this form and an input color [R_in, G_in, B_in], the 759 * output color [R_out, G_out, B_out] will be: 760 * 761 * R_out = R_in * r.r + G_in * g.r + B_in * b.r + Tr 762 * G_out = R_in * r.g + G_in * g.g + B_in * b.g + Tg 763 * B_out = R_in * r.b + G_in * g.b + B_in * b.b + Tb 764 * 765 * @param matrix is a 4x4 transform matrix (16 floats) as described above. 766 * @param hint is a hint value which may be used instead of the given 767 * matrix unless it is ColorTransform::ARBITRARY. 768 * 769 * 770 * SET_CLIENT_TARGET has this pseudo prototype 771 * 772 * setClientTarget(uint32_t targetSlot, 773 * int32_t targetIndex, 774 * int32_t acquireFenceIndex, 775 * Dataspace dataspace, 776 * vec<Rect> damage); 777 * 778 * Sets the buffer handle which will receive the output of client 779 * composition. Layers marked as Composition::CLIENT must be composited 780 * into this buffer prior to the call to PRESENT_DISPLAY, and layers not 781 * marked as Composition::CLIENT must be composited with this buffer by 782 * the device. 783 * 784 * The buffer handle provided may be empty if no layers are being 785 * composited by the client. This must not result in an error (unless an 786 * invalid display handle is also provided). 787 * 788 * Also provides a file descriptor referring to an acquire sync fence 789 * object, which must be signaled when it is safe to read from the client 790 * target buffer. If it is already safe to read from this buffer, an 791 * empty handle may be passed instead. 792 * 793 * For more about dataspaces, see SET_LAYER_DATASPACE. 794 * 795 * The damage parameter describes a surface damage region as defined in 796 * the description of SET_LAYER_SURFACE_DAMAGE. 797 * 798 * Will be called before PRESENT_DISPLAY if any of the layers are marked 799 * as Composition::CLIENT. If no layers are so marked, then it is not 800 * necessary to call this function. It is not necessary to call 801 * validateDisplay after changing the target through this function. 802 * 803 * @param targetSlot is the client target buffer slot to use. 804 * @param targetIndex is an index into inHandles for the new target 805 * buffer. 806 * @param acquireFenceIndex is an index into inHandles for a sync fence 807 * file descriptor as described above. 808 * @param dataspace is the dataspace of the buffer, as described in 809 * setLayerDataspace. 810 * @param damage is the surface damage region. 811 * 812 * 813 * SET_OUTPUT_BUFFER has this pseudo prototype 814 * 815 * setOutputBuffer(uint32_t bufferSlot, 816 * int32_t bufferIndex, 817 * int32_t releaseFenceIndex); 818 * 819 * Sets the output buffer for a virtual display. That is, the buffer to 820 * which the composition result will be written. 821 * 822 * Also provides a file descriptor referring to a release sync fence 823 * object, which must be signaled when it is safe to write to the output 824 * buffer. If it is already safe to write to the output buffer, an empty 825 * handle may be passed instead. 826 * 827 * Must be called at least once before PRESENT_DISPLAY, but does not have 828 * any interaction with layer state or display validation. 829 * 830 * @param bufferSlot is the new output buffer. 831 * @param bufferIndex is the new output buffer. 832 * @param releaseFenceIndex is a sync fence file descriptor as described 833 * above. 834 * 835 * 836 * VALIDATE_DISPLAY has this pseudo prototype 837 * 838 * validateDisplay(); 839 * 840 * Instructs the device to inspect all of the layer state and determine if 841 * there are any composition type changes necessary before presenting the 842 * display. Permitted changes are described in the definition of 843 * Composition above. 844 * 845 * 846 * ACCEPT_DISPLAY_CHANGES has this pseudo prototype 847 * 848 * acceptDisplayChanges(); 849 * 850 * Accepts the changes required by the device from the previous 851 * validateDisplay call (which may be queried using 852 * getChangedCompositionTypes) and revalidates the display. This function 853 * is equivalent to requesting the changed types from 854 * getChangedCompositionTypes, setting those types on the corresponding 855 * layers, and then calling validateDisplay again. 856 * 857 * After this call it must be valid to present this display. Calling this 858 * after validateDisplay returns 0 changes must succeed with NONE, but 859 * must have no other effect. 860 * 861 * 862 * PRESENT_DISPLAY has this pseudo prototype 863 * 864 * presentDisplay(); 865 * 866 * Presents the current display contents on the screen (or in the case of 867 * virtual displays, into the output buffer). 868 * 869 * Prior to calling this function, the display must be successfully 870 * validated with validateDisplay. Note that setLayerBuffer and 871 * setLayerSurfaceDamage specifically do not count as layer state, so if 872 * there are no other changes to the layer state (or to the buffer's 873 * properties as described in setLayerBuffer), then it is safe to call 874 * this function without first validating the display. 875 * 876 * 877 * SET_LAYER_CURSOR_POSITION has this pseudo prototype 878 * 879 * setLayerCursorPosition(int32_t x, int32_t y); 880 * 881 * Asynchronously sets the position of a cursor layer. 882 * 883 * Prior to validateDisplay, a layer may be marked as Composition::CURSOR. 884 * If validation succeeds (i.e., the device does not request a composition 885 * change for that layer), then once a buffer has been set for the layer 886 * and it has been presented, its position may be set by this function at 887 * any time between presentDisplay and any subsequent validateDisplay 888 * calls for this display. 889 * 890 * Once validateDisplay is called, this function must not be called again 891 * until the validate/present sequence is completed. 892 * 893 * May be called from any thread so long as it is not interleaved with the 894 * validate/present sequence as described above. 895 * 896 * @param layer is the layer to which the position is set. 897 * @param x is the new x coordinate (in pixels from the left of the 898 * screen). 899 * @param y is the new y coordinate (in pixels from the top of the 900 * screen). 901 * 902 * 903 * SET_LAYER_BUFFER has this pseudo prototype 904 * 905 * setLayerBuffer(uint32_t bufferSlot, 906 * int32_t bufferIndex, 907 * int32_t acquireFenceIndex); 908 * 909 * Sets the buffer handle to be displayed for this layer. If the buffer 910 * properties set at allocation time (width, height, format, and usage) 911 * have not changed since the previous frame, it is not necessary to call 912 * validateDisplay before calling presentDisplay unless new state needs to 913 * be validated in the interim. 914 * 915 * Also provides a file descriptor referring to an acquire sync fence 916 * object, which must be signaled when it is safe to read from the given 917 * buffer. If it is already safe to read from the buffer, an empty handle 918 * may be passed instead. 919 * 920 * This function must return NONE and have no other effect if called for a 921 * layer with a composition type of Composition::SOLID_COLOR (because it 922 * has no buffer) or Composition::SIDEBAND or Composition::CLIENT (because 923 * synchronization and buffer updates for these layers are handled 924 * elsewhere). 925 * 926 * @param layer is the layer to which the buffer is set. 927 * @param bufferSlot is the buffer slot to use. 928 * @param bufferIndex is the buffer handle to set. 929 * @param acquireFenceIndex is a sync fence file descriptor as described above. 930 * 931 * 932 * SET_LAYER_SURFACE_DAMAGE has this pseudo prototype 933 * 934 * setLayerSurfaceDamage(vec<Rect> damage); 935 * 936 * Provides the region of the source buffer which has been modified since 937 * the last frame. This region does not need to be validated before 938 * calling presentDisplay. 939 * 940 * Once set through this function, the damage region remains the same 941 * until a subsequent call to this function. 942 * 943 * If damage is non-empty, then it may be assumed that any portion of the 944 * source buffer not covered by one of the rects has not been modified 945 * this frame. If damage is empty, then the whole source buffer must be 946 * treated as if it has been modified. 947 * 948 * If the layer's contents are not modified relative to the prior frame, 949 * damage must contain exactly one empty rect([0, 0, 0, 0]). 950 * 951 * The damage rects are relative to the pre-transformed buffer, and their 952 * origin is the top-left corner. They must not exceed the dimensions of 953 * the latched buffer. 954 * 955 * @param layer is the layer to which the damage region is set. 956 * @param damage is the new surface damage region. 957 * 958 * 959 * SET_LAYER_BLEND_MODE has this pseudo prototype 960 * 961 * setLayerBlendMode(BlendMode mode) 962 * 963 * Sets the blend mode of the given layer. 964 * 965 * @param mode is the new blend mode. 966 * 967 * 968 * SET_LAYER_COLOR has this pseudo prototype 969 * 970 * setLayerColor(Color color); 971 * 972 * Sets the color of the given layer. If the composition type of the layer 973 * is not Composition::SOLID_COLOR, this call must succeed and have no 974 * other effect. 975 * 976 * @param color is the new color. 977 * 978 * 979 * SET_LAYER_COMPOSITION_TYPE has this pseudo prototype 980 * 981 * setLayerCompositionType(Composition type); 982 * 983 * Sets the desired composition type of the given layer. During 984 * validateDisplay, the device may request changes to the composition 985 * types of any of the layers as described in the definition of 986 * Composition above. 987 * 988 * @param type is the new composition type. 989 * 990 * 991 * SET_LAYER_DATASPACE has this pseudo prototype 992 * 993 * setLayerDataspace(Dataspace dataspace); 994 * 995 * Sets the dataspace that the current buffer on this layer is in. 996 * 997 * The dataspace provides more information about how to interpret the 998 * buffer contents, such as the encoding standard and color transform. 999 * 1000 * See the values of Dataspace for more information. 1001 * 1002 * @param dataspace is the new dataspace. 1003 * 1004 * 1005 * SET_LAYER_DISPLAY_FRAME has this pseudo prototype 1006 * 1007 * setLayerDisplayFrame(Rect frame); 1008 * 1009 * Sets the display frame (the portion of the display covered by a layer) 1010 * of the given layer. This frame must not exceed the display dimensions. 1011 * 1012 * @param frame is the new display frame. 1013 * 1014 * 1015 * SET_LAYER_PLANE_ALPHA has this pseudo prototype 1016 * 1017 * setLayerPlaneAlpha(float alpha); 1018 * 1019 * Sets an alpha value (a floating point value in the range [0.0, 1.0]) 1020 * which will be applied to the whole layer. It can be conceptualized as a 1021 * preprocessing step which applies the following function: 1022 * if (blendMode == BlendMode::PREMULTIPLIED) 1023 * out.rgb = in.rgb * planeAlpha 1024 * out.a = in.a * planeAlpha 1025 * 1026 * If the device does not support this operation on a layer which is 1027 * marked Composition::DEVICE, it must request a composition type change 1028 * to Composition::CLIENT upon the next validateDisplay call. 1029 * 1030 * @param alpha is the plane alpha value to apply. 1031 * 1032 * 1033 * SET_LAYER_SIDEBAND_STREAM has this pseudo prototype 1034 * 1035 * setLayerSidebandStream(int32_t streamIndex) 1036 * 1037 * Sets the sideband stream for this layer. If the composition type of the 1038 * given layer is not Composition::SIDEBAND, this call must succeed and 1039 * have no other effect. 1040 * 1041 * @param streamIndex is the new sideband stream. 1042 * 1043 * 1044 * SET_LAYER_SOURCE_CROP has this pseudo prototype 1045 * 1046 * setLayerSourceCrop(FRect crop); 1047 * 1048 * Sets the source crop (the portion of the source buffer which will fill 1049 * the display frame) of the given layer. This crop rectangle must not 1050 * exceed the dimensions of the latched buffer. 1051 * 1052 * If the device is not capable of supporting a true float source crop 1053 * (i.e., it will truncate or round the floats to integers), it must set 1054 * this layer to Composition::CLIENT when crop is non-integral for the 1055 * most accurate rendering. 1056 * 1057 * If the device cannot support float source crops, but still wants to 1058 * handle the layer, it must use the following code (or similar) to 1059 * convert to an integer crop: 1060 * intCrop.left = (int) ceilf(crop.left); 1061 * intCrop.top = (int) ceilf(crop.top); 1062 * intCrop.right = (int) floorf(crop.right); 1063 * intCrop.bottom = (int) floorf(crop.bottom); 1064 * 1065 * @param crop is the new source crop. 1066 * 1067 * 1068 * SET_LAYER_TRANSFORM has this pseudo prototype 1069 * 1070 * Sets the transform (rotation/flip) of the given layer. 1071 * 1072 * setLayerTransform(Transform transform); 1073 * 1074 * @param transform is the new transform. 1075 * 1076 * 1077 * SET_LAYER_VISIBLE_REGION has this pseudo prototype 1078 * 1079 * setLayerVisibleRegion(vec<Rect> visible); 1080 * 1081 * Specifies the portion of the layer that is visible, including portions 1082 * under translucent areas of other layers. The region is in screen space, 1083 * and must not exceed the dimensions of the screen. 1084 * 1085 * @param visible is the new visible region, in screen space. 1086 * 1087 * 1088 * SET_LAYER_Z_ORDER has this pseudo prototype 1089 * 1090 * setLayerZOrder(uint32_t z); 1091 * 1092 * Sets the desired Z order (height) of the given layer. A layer with a 1093 * greater Z value occludes a layer with a lesser Z value. 1094 * 1095 * @param z is the new Z order. 1096 */ 1097 enum Command : int32_t { 1098 LENGTH_MASK = 0xffff, 1099 OPCODE_SHIFT = 16, 1100 OPCODE_MASK = 0xffff << OPCODE_SHIFT, 1101 1102 /** special commands */ 1103 SELECT_DISPLAY = 0x000 << OPCODE_SHIFT, 1104 SELECT_LAYER = 0x001 << OPCODE_SHIFT, 1105 1106 /** value commands (for return values) */ 1107 SET_ERROR = 0x100 << OPCODE_SHIFT, 1108 SET_CHANGED_COMPOSITION_TYPES = 0x101 << OPCODE_SHIFT, 1109 SET_DISPLAY_REQUESTS = 0x102 << OPCODE_SHIFT, 1110 SET_PRESENT_FENCE = 0x103 << OPCODE_SHIFT, 1111 SET_RELEASE_FENCES = 0x104 << OPCODE_SHIFT, 1112 1113 /** display commands */ 1114 SET_COLOR_TRANSFORM = 0x200 << OPCODE_SHIFT, 1115 SET_CLIENT_TARGET = 0x201 << OPCODE_SHIFT, 1116 SET_OUTPUT_BUFFER = 0x202 << OPCODE_SHIFT, 1117 VALIDATE_DISPLAY = 0x203 << OPCODE_SHIFT, 1118 ACCEPT_DISPLAY_CHANGES = 0x204 << OPCODE_SHIFT, 1119 PRESENT_DISPLAY = 0x205 << OPCODE_SHIFT, 1120 PRESENT_OR_VALIDATE_DISPLAY = 0x206 << OPCODE_SHIFT, 1121 1122 /** layer commands (VALIDATE_DISPLAY not required) */ 1123 SET_LAYER_CURSOR_POSITION = 0x300 << OPCODE_SHIFT, 1124 SET_LAYER_BUFFER = 0x301 << OPCODE_SHIFT, 1125 SET_LAYER_SURFACE_DAMAGE = 0x302 << OPCODE_SHIFT, 1126 1127 /** layer state commands (VALIDATE_DISPLAY required) */ 1128 SET_LAYER_BLEND_MODE = 0x400 << OPCODE_SHIFT, 1129 SET_LAYER_COLOR = 0x401 << OPCODE_SHIFT, 1130 SET_LAYER_COMPOSITION_TYPE = 0x402 << OPCODE_SHIFT, 1131 SET_LAYER_DATASPACE = 0x403 << OPCODE_SHIFT, 1132 SET_LAYER_DISPLAY_FRAME = 0x404 << OPCODE_SHIFT, 1133 SET_LAYER_PLANE_ALPHA = 0x405 << OPCODE_SHIFT, 1134 SET_LAYER_SIDEBAND_STREAM = 0x406 << OPCODE_SHIFT, 1135 SET_LAYER_SOURCE_CROP = 0x407 << OPCODE_SHIFT, 1136 SET_LAYER_TRANSFORM = 0x408 << OPCODE_SHIFT, 1137 SET_LAYER_VISIBLE_REGION = 0x409 << OPCODE_SHIFT, 1138 SET_LAYER_Z_ORDER = 0x40a << OPCODE_SHIFT, 1139 SET_PRESENT_OR_VALIDATE_DISPLAY_RESULT = 0x40b << OPCODE_SHIFT, 1140 1141 /* 0x800 - 0xfff are reserved for vendor extensions */ 1142 /* 0x1000 - 0xffff are reserved */ 1143 }; 1144}; 1145