1 /* 2 * Copyright (c) 2014 - 2017, The Linux Foundation. All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without modification, are permitted 5 * provided that the following conditions are met: 6 * * Redistributions of source code must retain the above copyright notice, this list of 7 * conditions and the following disclaimer. 8 * * Redistributions in binary form must reproduce the above copyright notice, this list of 9 * conditions and the following disclaimer in the documentation and/or other materials provided 10 * with the distribution. 11 * * Neither the name of The Linux Foundation nor the names of its contributors may be used to 12 * endorse or promote products derived from this software without specific prior written 13 * permission. 14 * 15 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 16 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 17 * NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 19 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 20 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 21 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 22 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 23 */ 24 25 /*! @file display_interface.h 26 @brief Interface file for display device which represents a physical panel or an output buffer 27 where contents can be rendered. 28 29 @details Display device is used to send layer buffers for composition and get them rendered onto 30 the target device. Each display device represents a unique display target which may be either a 31 physical panel or an output buffer.. 32 */ 33 #ifndef __DISPLAY_INTERFACE_H__ 34 #define __DISPLAY_INTERFACE_H__ 35 36 #include <stdint.h> 37 #include <string> 38 #include <vector> 39 40 #include "layer_stack.h" 41 #include "sdm_types.h" 42 43 namespace sdm { 44 45 /*! @brief This enum represents display device types where contents can be rendered. 46 47 @sa CoreInterface::CreateDisplay 48 @sa CoreInterface::IsDisplaySupported 49 */ 50 enum DisplayType { 51 kPrimary, //!< Main physical display which is attached to the handheld device. 52 kHDMI, //!< HDMI physical display which is generally detachable. 53 kVirtual, //!< Contents would be rendered into the output buffer provided by the client 54 //!< e.g. wireless display. 55 kDisplayMax, 56 }; 57 58 /*! @brief This enum represents states of a display device. 59 60 @sa DisplayInterface::GetDisplayState 61 @sa DisplayInterface::SetDisplayState 62 */ 63 enum DisplayState { 64 kStateOff, //!< Display is OFF. Contents are not rendered in this state. Client will not 65 //!< receive VSync events in this state. This is default state as well. 66 67 kStateOn, //!< Display is ON. Contents are rendered in this state. 68 69 kStateDoze, //!< Display is ON and it is configured in a low power state. 70 71 kStateDozeSuspend, 72 //!< Display is ON in a low power state and continue showing its current 73 //!< contents indefinitely until the mode changes. 74 75 kStateStandby, //!< Display is OFF. Client will continue to receive VSync events in this state 76 //!< if VSync is enabled. Contents are not rendered in this state. 77 }; 78 79 /*! @brief This enum represents flags to override detail enhancer parameters. 80 81 @sa DisplayInterface::SetDetailEnhancerData 82 */ 83 enum DetailEnhancerOverrideFlags { 84 kOverrideDEEnable = 0x1, // Specifies to enable detail enhancer 85 kOverrideDESharpen1 = 0x2, // Specifies user defined Sharpening/smooth for noise 86 kOverrideDESharpen2 = 0x4, // Specifies user defined Sharpening/smooth for signal 87 kOverrideDEClip = 0x8, // Specifies user defined DE clip shift 88 kOverrideDELimit = 0x10, // Specifies user defined DE limit value 89 kOverrideDEThrQuiet = 0x20, // Specifies user defined DE quiet threshold 90 kOverrideDEThrDieout = 0x40, // Specifies user defined DE dieout threshold 91 kOverrideDEThrLow = 0x80, // Specifies user defined DE low threshold 92 kOverrideDEThrHigh = 0x100, // Specifies user defined DE high threshold 93 kOverrideDEFilterConfig = 0x200, // Specifies user defined scaling filter config 94 kOverrideDEMax = 0xFFFFFFFF, 95 }; 96 97 /*! @brief This enum represents Y/RGB scaling filter configuration. 98 99 @sa DisplayInterface::SetDetailEnhancerData 100 */ 101 enum ScalingFilterConfig { 102 kFilterEdgeDirected, 103 kFilterCircular, 104 kFilterSeparable, 105 kFilterBilinear, 106 kFilterMax, 107 }; 108 109 /*! @brief This enum represents the quality level of the content. 110 111 @sa DisplayInterface::SetDetailEnhancerData 112 */ 113 enum ContentQuality { 114 kContentQualityUnknown, // Default: high artifact and noise 115 kContentQualityLow, // Low quality content, high artifact and noise, 116 kContentQualityMedium, // Medium quality, medium artifact and noise, 117 kContentQualityHigh, // High quality content, low artifact and noise 118 kContentQualityMax, 119 }; 120 121 /*! @brief This enum represents the display port. 122 123 @sa DisplayInterface::GetDisplayPort 124 */ 125 enum DisplayPort { 126 kPortDefault, 127 kPortDSI, // Display is connected to DSI port. 128 kPortDTV, // Display is connected to DTV port 129 kPortWriteBack, // Display is connected to writeback port 130 kPortLVDS, // Display is connected to LVDS port 131 kPortEDP, // Display is connected to EDP port 132 kPortDP, // Display is connected to DP port. 133 }; 134 135 /*! @brief This structure defines configuration for fixed properties of a display device. 136 137 @sa DisplayInterface::GetConfig 138 @sa DisplayInterface::SetConfig 139 */ 140 struct DisplayConfigFixedInfo { 141 bool underscan = false; //!< If display support CE underscan. 142 bool secure = false; //!< If this display is capable of handling secure content. 143 bool is_cmdmode = false; //!< If panel is command mode panel. 144 bool hdr_supported = false; //!< if HDR is enabled 145 uint32_t max_luminance = 0; //!< From Panel's peak luminance 146 uint32_t average_luminance = 0; //!< From Panel's average luminance 147 uint32_t min_luminance = 0; //!< From Panel's blackness level 148 }; 149 150 /*! @brief This structure defines configuration for variable properties of a display device. 151 152 @sa DisplayInterface::GetConfig 153 @sa DisplayInterface::SetConfig 154 */ 155 struct DisplayConfigVariableInfo { 156 uint32_t x_pixels = 0; //!< Total number of pixels in X-direction on the display panel. 157 uint32_t y_pixels = 0; //!< Total number of pixels in Y-direction on the display panel. 158 float x_dpi = 0.0f; //!< Dots per inch in X-direction. 159 float y_dpi = 0.0f; //!< Dots per inch in Y-direction. 160 uint32_t fps = 0; //!< Frame rate per second. 161 uint32_t vsync_period_ns = 0; //!< VSync period in nanoseconds. 162 bool is_yuv = false; //!< If the display output is in YUV format. 163 }; 164 165 /*! @brief Event data associated with VSync event. 166 167 @sa DisplayEventHandler::VSync 168 */ 169 struct DisplayEventVSync { 170 int64_t timestamp = 0; //!< System monotonic clock timestamp in nanoseconds. 171 }; 172 173 /*! @brief The structure defines the user input for detail enhancer module. 174 175 @sa DisplayInterface::SetDetailEnhancerData 176 */ 177 struct DisplayDetailEnhancerData { 178 uint32_t override_flags = 0; // flags to specify which data to be set. 179 uint16_t enable = 0; // Detail enchancer enable 180 int16_t sharpen_level1 = 0; // Sharpening/smooth strenght for noise 181 int16_t sharpen_level2 = 0; // Sharpening/smooth strenght for signal 182 uint16_t clip = 0; // DE clip shift 183 uint16_t limit = 0; // DE limit value 184 uint16_t thr_quiet = 0; // DE quiet threshold 185 uint16_t thr_dieout = 0; // DE dieout threshold 186 uint16_t thr_low = 0; // DE low threshold 187 uint16_t thr_high = 0; // DE high threshold 188 int32_t sharp_factor = 50; // sharp_factor specifies sharpness/smoothness level, 189 // range -100..100 positive for sharpness and negative for 190 // smoothness 191 ContentQuality quality_level = kContentQualityUnknown; 192 // Specifies context quality level 193 ScalingFilterConfig filter_config = kFilterEdgeDirected; 194 // Y/RGB filter configuration 195 }; 196 197 /*! @brief Display device event handler implemented by the client. 198 199 @details This class declares prototype for display device event handler methods which must be 200 implemented by the client. Display device will use these methods to notify events to the client. 201 Client must post heavy-weight event handling to a separate thread and unblock display manager 202 thread instantly. 203 204 @sa CoreInterface::CreateDisplay 205 */ 206 class DisplayEventHandler { 207 public: 208 /*! @brief Event handler for VSync event. 209 210 @details This event is dispatched on every vertical synchronization. The event is disabled by 211 default. 212 213 @param[in] vsync \link DisplayEventVSync \endlink 214 215 @return \link DisplayError \endlink 216 217 @sa DisplayInterface::GetDisplayState 218 @sa DisplayInterface::SetDisplayState 219 */ 220 virtual DisplayError VSync(const DisplayEventVSync &vsync) = 0; 221 222 /*! @brief Event handler for Refresh event. 223 224 @details This event is dispatched to trigger a screen refresh. Client must call Prepare() and 225 Commit() in response to it from a separate thread. There is no data associated with this 226 event. 227 228 @return \link DisplayError \endlink 229 230 @sa DisplayInterface::Prepare 231 @sa DisplayInterface::Commit 232 */ 233 virtual DisplayError Refresh() = 0; 234 235 /*! @brief Event handler for CEC messages. 236 237 @details This event is dispatched to send CEC messages to the CEC HAL. 238 239 @param[in] message message to be sent 240 241 @return \link DisplayError \endlink 242 */ 243 virtual DisplayError CECMessage(char *message) = 0; 244 245 protected: ~DisplayEventHandler()246 virtual ~DisplayEventHandler() { } 247 }; 248 249 struct PPDisplayAPIPayload; 250 struct PPPendingParams; 251 252 /*! @brief Display device interface. 253 254 @details This class defines display device interface. It contains methods which client shall use 255 to configure or submit layers for composition on the display device. This interface is created 256 during display device creation and remains valid until destroyed. 257 258 @sa CoreInterface::CreateDisplay 259 @sa CoreInterface::DestroyDisplay 260 */ 261 class DisplayInterface { 262 public: 263 /*! @brief Method to determine hardware capability to compose layers associated with given frame. 264 265 @details Client shall send all layers associated with a frame targeted for current display 266 using this method and check the layers which can be handled completely in display manager. 267 268 Client shall mark composition type for one of the layer as kCompositionGPUTarget; the GPU 269 composed output would be rendered at the specified layer if some of the layers are not handled 270 by SDM. 271 272 Display manager will set each layer as kCompositionGPU or kCompositionSDE upon return. Client 273 shall render all the layers marked as kCompositionGPU using GPU. 274 275 This method can be called multiple times but only last call prevails. This method must be 276 followed by Commit(). 277 278 @param[inout] layer_stack \link LayerStack \endlink 279 280 @return \link DisplayError \endlink 281 282 @sa Commit 283 */ 284 virtual DisplayError Prepare(LayerStack *layer_stack) = 0; 285 286 /*! @brief Method to commit layers of a frame submitted in a former call to Prepare(). 287 288 @details Client shall call this method to submit layers for final composition. The composed 289 output would be displayed on the panel or written in output buffer. 290 291 Client must ensure that layer stack is same as previous call to Prepare. 292 293 This method shall be called only once for each frame. 294 295 In the event of an error as well, this call will cause any fences returned in the previous call 296 to Commit() to eventually become signaled, so the client's wait on fences can be released to 297 prevent deadlocks. 298 299 @param[in] layer_stack \link LayerStack \endlink 300 301 @return \link DisplayError \endlink 302 303 @sa Prepare 304 */ 305 virtual DisplayError Commit(LayerStack *layer_stack) = 0; 306 307 /*! @brief Method to flush any pending buffers/fences submitted previously via Commit() call. 308 309 @details Client shall call this method to request the Display manager to release all buffers and 310 respective fences currently in use. This operation may result in a blank display on the panel 311 until a new frame is submitted for composition. 312 313 @return \link DisplayError \endlink 314 315 @sa Prepare 316 @sa Commit 317 */ 318 virtual DisplayError Flush() = 0; 319 320 /*! @brief Method to get current state of the display device. 321 322 @param[out] state \link DisplayState \endlink 323 324 @return \link DisplayError \endlink 325 326 @sa SetDisplayState 327 */ 328 virtual DisplayError GetDisplayState(DisplayState *state) = 0; 329 330 /*! @brief Method to get number of configurations(variable properties) supported on the display 331 device. 332 333 @param[out] count Number of modes supported; mode index starts with 0. 334 335 @return \link DisplayError \endlink 336 */ 337 virtual DisplayError GetNumVariableInfoConfigs(uint32_t *count) = 0; 338 339 /*! @brief Method to get configuration for fixed properties of the display device. 340 341 @param[out] fixed_info \link DisplayConfigFixedInfo \endlink 342 343 @return \link DisplayError \endlink 344 */ 345 virtual DisplayError GetConfig(DisplayConfigFixedInfo *fixed_info) = 0; 346 347 /*! @brief Method to get configuration for variable properties of the display device. 348 349 @param[in] index index of the mode 350 @param[out] variable_info \link DisplayConfigVariableInfo \endlink 351 352 @return \link DisplayError \endlink 353 */ 354 virtual DisplayError GetConfig(uint32_t index, DisplayConfigVariableInfo *variable_info) = 0; 355 356 /*! @brief Method to get index of active configuration of the display device. 357 358 @param[out] index index of the mode corresponding to variable properties. 359 360 @return \link DisplayError \endlink 361 */ 362 virtual DisplayError GetActiveConfig(uint32_t *index) = 0; 363 364 /*! @brief Method to get VSync event state. Default event state is disabled. 365 366 @param[out] enabled vsync state 367 368 @return \link DisplayError \endlink 369 */ 370 virtual DisplayError GetVSyncState(bool *enabled) = 0; 371 372 /*! @brief Method to set current state of the display device. 373 374 @param[in] state \link DisplayState \endlink 375 376 @return \link DisplayError \endlink 377 378 @sa SetDisplayState 379 */ 380 virtual DisplayError SetDisplayState(DisplayState state) = 0; 381 382 /*! @brief Method to set active configuration for variable properties of the display device. 383 384 @param[in] variable_info \link DisplayConfigVariableInfo \endlink 385 386 @return \link DisplayError \endlink 387 */ 388 virtual DisplayError SetActiveConfig(DisplayConfigVariableInfo *variable_info) = 0; 389 390 /*! @brief Method to set active configuration for variable properties of the display device. 391 392 @param[in] index index of the mode corresponding to variable properties. 393 394 @return \link DisplayError \endlink 395 */ 396 virtual DisplayError SetActiveConfig(uint32_t index) = 0; 397 398 /*! @brief Method to set VSync event state. Default event state is disabled. 399 400 @param[out] enabled vsync state 401 402 @return \link DisplayError \endlink 403 */ 404 virtual DisplayError SetVSyncState(bool enable) = 0; 405 406 /*! @brief Method to set idle timeout value. Idle fallback is disabled with timeout value 0. 407 408 @param[in] timeout value in milliseconds. 409 410 @return \link void \endlink 411 */ 412 virtual void SetIdleTimeoutMs(uint32_t timeout_ms) = 0; 413 414 /*! @brief Method to set maximum number of mixer stages for each display. 415 416 @param[in] max_mixer_stages maximum number of mixer stages. 417 418 @return \link DisplayError \endlink 419 */ 420 virtual DisplayError SetMaxMixerStages(uint32_t max_mixer_stages) = 0; 421 422 /*! @brief Method to control partial update feature for each display. 423 424 @param[in] enable partial update feature control flag 425 @param[out] pending whether the operation is completed or pending for completion 426 427 @return \link DisplayError \endlink 428 */ 429 virtual DisplayError ControlPartialUpdate(bool enable, uint32_t *pending) = 0; 430 431 /*! @brief Method to disable partial update for at least 1 frame. 432 @return \link DisplayError \endlink 433 */ 434 virtual DisplayError DisablePartialUpdateOneFrame() = 0; 435 436 /*! @brief Method to set the mode of the primary display. 437 438 @param[in] mode the new display mode. 439 440 @return \link DisplayError \endlink 441 */ 442 virtual DisplayError SetDisplayMode(uint32_t mode) = 0; 443 444 /*! @brief Method to get the min and max refresh rate of a display. 445 446 @param[out] min and max refresh rate. 447 448 @return \link DisplayError \endlink 449 */ 450 virtual DisplayError GetRefreshRateRange(uint32_t *min_refresh_rate, 451 uint32_t *max_refresh_rate) = 0; 452 453 /*! @brief Method to set the refresh rate of a display. 454 455 @param[in] new refresh rate of the display. 456 457 @return \link DisplayError \endlink 458 */ 459 virtual DisplayError SetRefreshRate(uint32_t refresh_rate) = 0; 460 461 /*! @brief Method to query whether scanning is support for the HDMI display. 462 463 @return \link DisplayError \endlink 464 */ 465 virtual bool IsUnderscanSupported() = 0; 466 467 /*! @brief Method to set brightness of the primary display. 468 469 @param[in] level the new backlight level. 470 471 @return \link DisplayError \endlink 472 */ 473 virtual DisplayError SetPanelBrightness(int level) = 0; 474 475 /*! @brief Method to notify display about change in min HDCP encryption level. 476 477 @param[in] min_enc_level minimum encryption level value. 478 479 @return \link DisplayError \endlink 480 */ 481 virtual DisplayError OnMinHdcpEncryptionLevelChange(uint32_t min_enc_level) = 0; 482 483 /*! @brief Method to route display API requests to color service. 484 485 @param[in] in_payload \link PPDisplayAPIPayload \endlink 486 @param[out] out_payload \link PPDisplayPayload \endlink 487 @param[out] pending_action \link PPPendingParams \endlink 488 489 @return \link DisplayError \endlink 490 */ 491 virtual DisplayError ColorSVCRequestRoute(const PPDisplayAPIPayload &in_payload, 492 PPDisplayAPIPayload *out_payload, 493 PPPendingParams *pending_action) = 0; 494 495 /*! @brief Method to request the number of color modes supported. 496 497 @param[out] mode_count Number of modes 498 499 @return \link DisplayError \endlink 500 */ 501 virtual DisplayError GetColorModeCount(uint32_t *mode_count) = 0; 502 503 /*! @brief Method to request the information of supported color modes. 504 505 @param[inout] mode_count Number of updated modes 506 @param[out] vector of mode strings 507 508 @return \link DisplayError \endlink 509 */ 510 virtual DisplayError GetColorModes(uint32_t *mode_count, 511 std::vector<std::string> *color_modes) = 0; 512 513 /*! @brief Method to set the color mode 514 515 @param[in] mode_name Mode name which needs to be set 516 517 @return \link DisplayError \endlink 518 */ 519 virtual DisplayError SetColorMode(const std::string &color_mode) = 0; 520 521 /*! @brief Method to set the color transform 522 523 @param[in] length Mode name which needs to be set 524 @param[in] color_transform 4x4 Matrix for color transform 525 526 @return \link DisplayError \endlink 527 */ 528 virtual DisplayError SetColorTransform(const uint32_t length, const double *color_transform) = 0; 529 530 /*! @brief Method to request applying default display mode. 531 532 @return \link DisplayError \endlink 533 */ 534 virtual DisplayError ApplyDefaultDisplayMode() = 0; 535 536 /*! @brief Method to set the position of the hw cursor. 537 538 @param[in] x \link x position \endlink 539 @param[in] y \link y position \endlink 540 541 @return \link DisplayError \endlink 542 */ 543 virtual DisplayError SetCursorPosition(int x, int y) = 0; 544 545 /*! @brief Method to get the brightness level of the display 546 547 @param[out] level brightness level 548 549 @return \link DisplayError \endlink 550 */ 551 virtual DisplayError GetPanelBrightness(int *level) = 0; 552 553 /*! @brief Method to set layer mixer resolution. 554 555 @param[in] width layer mixer width 556 @param[in] height layer mixer height 557 558 @return \link DisplayError \endlink 559 */ 560 virtual DisplayError SetMixerResolution(uint32_t width, uint32_t height) = 0; 561 562 /*! @brief Method to get layer mixer resolution. 563 564 @param[out] width layer mixer width 565 @param[out] height layer mixer height 566 567 @return \link DisplayError \endlink 568 */ 569 virtual DisplayError GetMixerResolution(uint32_t *width, uint32_t *height) = 0; 570 571 /*! @brief Method to set frame buffer configuration. 572 573 @param[in] variable_info \link DisplayConfigVariableInfo \endlink 574 575 @return \link DisplayError \endlink 576 */ 577 virtual DisplayError SetFrameBufferConfig(const DisplayConfigVariableInfo &variable_info) = 0; 578 579 /*! @brief Method to get frame buffer configuration. 580 581 @param[out] variable_info \link DisplayConfigVariableInfo \endlink 582 583 @return \link DisplayError \endlink 584 */ 585 virtual DisplayError GetFrameBufferConfig(DisplayConfigVariableInfo *variable_info) = 0; 586 587 /*! @brief Method to set detail enhancement data. 588 589 @param[in] de_data \link DisplayDetailEnhancerData \endlink 590 591 @return \link DisplayError \endlink 592 */ 593 virtual DisplayError SetDetailEnhancerData(const DisplayDetailEnhancerData &de_data) = 0; 594 595 /*! @brief Method to get display port information. 596 597 @param[out] port \link DisplayPort \endlink 598 599 @return \link DisplayError \endlink 600 */ 601 virtual DisplayError GetDisplayPort(DisplayPort *port) = 0; 602 603 /*! @brief Method to query whether it is Primrary device. 604 605 @return true if this interface is primary. 606 */ 607 virtual bool IsPrimaryDisplay() = 0; 608 609 /*! @brief Method to toggle composition types handling by SDM. 610 611 @details Client shall call this method to request SDM to enable/disable a specific type of 612 layer composition. If client disables a composition type, SDM will not handle any of the layer 613 composition using the disabled method in a draw cycle. On lack of resources to handle all 614 layers using other enabled composition methods, Prepare() will return an error. 615 616 Request to toggle composition type is applied from subsequent draw cycles. 617 618 Default state of all defined composition types is enabled. 619 620 @param[in] composition_type \link LayerComposition \endlink 621 @param[in] enable \link enable composition type \endlink 622 623 @return \link DisplayError \endlink 624 625 @sa Prepare 626 */ 627 virtual DisplayError SetCompositionState(LayerComposition composition_type, bool enable) = 0; 628 629 protected: ~DisplayInterface()630 virtual ~DisplayInterface() { } 631 }; 632 633 } // namespace sdm 634 635 #endif // __DISPLAY_INTERFACE_H__ 636 637