1 /* 2 * Copyright (c) 2014 - 2016, 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 }; 144 145 /*! @brief This structure defines configuration for variable properties of a display device. 146 147 @sa DisplayInterface::GetConfig 148 @sa DisplayInterface::SetConfig 149 */ 150 struct DisplayConfigVariableInfo { 151 uint32_t x_pixels = 0; //!< Total number of pixels in X-direction on the display panel. 152 uint32_t y_pixels = 0; //!< Total number of pixels in Y-direction on the display panel. 153 float x_dpi = 0.0f; //!< Dots per inch in X-direction. 154 float y_dpi = 0.0f; //!< Dots per inch in Y-direction. 155 uint32_t fps = 0; //!< Frame rate per second. 156 uint32_t vsync_period_ns = 0; //!< VSync period in nanoseconds. 157 bool is_yuv = false; //!< If the display output is in YUV format. 158 }; 159 160 /*! @brief Event data associated with VSync event. 161 162 @sa DisplayEventHandler::VSync 163 */ 164 struct DisplayEventVSync { 165 int64_t timestamp = 0; //!< System monotonic clock timestamp in nanoseconds. 166 }; 167 168 /*! @brief The structure defines the user input for detail enhancer module. 169 170 @sa DisplayInterface::SetDetailEnhancerData 171 */ 172 struct DisplayDetailEnhancerData { 173 uint32_t override_flags = 0; // flags to specify which data to be set. 174 uint16_t enable = 0; // Detail enchancer enable 175 int16_t sharpen_level1 = 0; // Sharpening/smooth strenght for noise 176 int16_t sharpen_level2 = 0; // Sharpening/smooth strenght for signal 177 uint16_t clip = 0; // DE clip shift 178 uint16_t limit = 0; // DE limit value 179 uint16_t thr_quiet = 0; // DE quiet threshold 180 uint16_t thr_dieout = 0; // DE dieout threshold 181 uint16_t thr_low = 0; // DE low threshold 182 uint16_t thr_high = 0; // DE high threshold 183 int32_t sharp_factor = 50; // sharp_factor specifies sharpness/smoothness level, 184 // range -100..100 positive for sharpness and negative for 185 // smoothness 186 ContentQuality quality_level = kContentQualityUnknown; 187 // Specifies context quality level 188 ScalingFilterConfig filter_config = kFilterEdgeDirected; 189 // Y/RGB filter configuration 190 }; 191 192 /*! @brief Display device event handler implemented by the client. 193 194 @details This class declares prototype for display device event handler methods which must be 195 implemented by the client. Display device will use these methods to notify events to the client. 196 Client must post heavy-weight event handling to a separate thread and unblock display manager 197 thread instantly. 198 199 @sa CoreInterface::CreateDisplay 200 */ 201 class DisplayEventHandler { 202 public: 203 /*! @brief Event handler for VSync event. 204 205 @details This event is dispatched on every vertical synchronization. The event is disabled by 206 default. 207 208 @param[in] vsync \link DisplayEventVSync \endlink 209 210 @return \link DisplayError \endlink 211 212 @sa DisplayInterface::GetDisplayState 213 @sa DisplayInterface::SetDisplayState 214 */ 215 virtual DisplayError VSync(const DisplayEventVSync &vsync) = 0; 216 217 /*! @brief Event handler for Refresh event. 218 219 @details This event is dispatched to trigger a screen refresh. Client must call Prepare() and 220 Commit() in response to it from a separate thread. There is no data associated with this 221 event. 222 223 @return \link DisplayError \endlink 224 225 @sa DisplayInterface::Prepare 226 @sa DisplayInterface::Commit 227 */ 228 virtual DisplayError Refresh() = 0; 229 230 /*! @brief Event handler for CEC messages. 231 232 @details This event is dispatched to send CEC messages to the CEC HAL. 233 234 @param[in] message message to be sent 235 236 @return \link DisplayError \endlink 237 */ 238 virtual DisplayError CECMessage(char *message) = 0; 239 240 protected: 241 virtual ~DisplayEventHandler() { } 242 }; 243 244 struct PPDisplayAPIPayload; 245 struct PPPendingParams; 246 247 /*! @brief Display device interface. 248 249 @details This class defines display device interface. It contains methods which client shall use 250 to configure or submit layers for composition on the display device. This interface is created 251 during display device creation and remains valid until destroyed. 252 253 @sa CoreInterface::CreateDisplay 254 @sa CoreInterface::DestroyDisplay 255 */ 256 class DisplayInterface { 257 public: 258 /*! @brief Method to determine hardware capability to compose layers associated with given frame. 259 260 @details Client shall send all layers associated with a frame targeted for current display 261 using this method and check the layers which can be handled completely in display manager. 262 263 Client shall mark composition type for one of the layer as kCompositionGPUTarget; the GPU 264 composed output would be rendered at the specified layer if some of the layers are not handled 265 by SDM. 266 267 Display manager will set each layer as kCompositionGPU or kCompositionSDE upon return. Client 268 shall render all the layers marked as kCompositionGPU using GPU. 269 270 This method can be called multiple times but only last call prevails. This method must be 271 followed by Commit(). 272 273 @param[inout] layer_stack \link LayerStack \endlink 274 275 @return \link DisplayError \endlink 276 277 @sa Commit 278 */ 279 virtual DisplayError Prepare(LayerStack *layer_stack) = 0; 280 281 /*! @brief Method to commit layers of a frame submitted in a former call to Prepare(). 282 283 @details Client shall call this method to submit layers for final composition. The composed 284 output would be displayed on the panel or written in output buffer. 285 286 Client must ensure that layer stack is same as previous call to Prepare. 287 288 This method shall be called only once for each frame. 289 290 In the event of an error as well, this call will cause any fences returned in the previous call 291 to Commit() to eventually become signaled, so the client's wait on fences can be released to 292 prevent deadlocks. 293 294 @param[in] layer_stack \link LayerStack \endlink 295 296 @return \link DisplayError \endlink 297 298 @sa Prepare 299 */ 300 virtual DisplayError Commit(LayerStack *layer_stack) = 0; 301 302 /*! @brief Method to flush any pending buffers/fences submitted previously via Commit() call. 303 304 @details Client shall call this method to request the Display manager to release all buffers and 305 respective fences currently in use. This operation may result in a blank display on the panel 306 until a new frame is submitted for composition. 307 308 @return \link DisplayError \endlink 309 310 @sa Prepare 311 @sa Commit 312 */ 313 virtual DisplayError Flush() = 0; 314 315 /*! @brief Method to get current state of the display device. 316 317 @param[out] state \link DisplayState \endlink 318 319 @return \link DisplayError \endlink 320 321 @sa SetDisplayState 322 */ 323 virtual DisplayError GetDisplayState(DisplayState *state) = 0; 324 325 /*! @brief Method to get number of configurations(variable properties) supported on the display 326 device. 327 328 @param[out] count Number of modes supported; mode index starts with 0. 329 330 @return \link DisplayError \endlink 331 */ 332 virtual DisplayError GetNumVariableInfoConfigs(uint32_t *count) = 0; 333 334 /*! @brief Method to get configuration for fixed properties of the display device. 335 336 @param[out] fixed_info \link DisplayConfigFixedInfo \endlink 337 338 @return \link DisplayError \endlink 339 */ 340 virtual DisplayError GetConfig(DisplayConfigFixedInfo *fixed_info) = 0; 341 342 /*! @brief Method to get configuration for variable properties of the display device. 343 344 @param[in] index index of the mode 345 @param[out] variable_info \link DisplayConfigVariableInfo \endlink 346 347 @return \link DisplayError \endlink 348 */ 349 virtual DisplayError GetConfig(uint32_t index, DisplayConfigVariableInfo *variable_info) = 0; 350 351 /*! @brief Method to get index of active configuration of the display device. 352 353 @param[out] index index of the mode corresponding to variable properties. 354 355 @return \link DisplayError \endlink 356 */ 357 virtual DisplayError GetActiveConfig(uint32_t *index) = 0; 358 359 /*! @brief Method to get VSync event state. Default event state is disabled. 360 361 @param[out] enabled vsync state 362 363 @return \link DisplayError \endlink 364 */ 365 virtual DisplayError GetVSyncState(bool *enabled) = 0; 366 367 /*! @brief Method to set current state of the display device. 368 369 @param[in] state \link DisplayState \endlink 370 371 @return \link DisplayError \endlink 372 373 @sa SetDisplayState 374 */ 375 virtual DisplayError SetDisplayState(DisplayState state) = 0; 376 377 /*! @brief Method to set active configuration for variable properties of the display device. 378 379 @param[in] variable_info \link DisplayConfigVariableInfo \endlink 380 381 @return \link DisplayError \endlink 382 */ 383 virtual DisplayError SetActiveConfig(DisplayConfigVariableInfo *variable_info) = 0; 384 385 /*! @brief Method to set active configuration for variable properties of the display device. 386 387 @param[in] index index of the mode corresponding to variable properties. 388 389 @return \link DisplayError \endlink 390 */ 391 virtual DisplayError SetActiveConfig(uint32_t index) = 0; 392 393 /*! @brief Method to set VSync event state. Default event state is disabled. 394 395 @param[out] enabled vsync state 396 397 @return \link DisplayError \endlink 398 */ 399 virtual DisplayError SetVSyncState(bool enable) = 0; 400 401 /*! @brief Method to set idle timeout value. Idle fallback is disabled with timeout value 0. 402 403 @param[in] timeout value in milliseconds. 404 405 @return \link void \endlink 406 */ 407 virtual void SetIdleTimeoutMs(uint32_t timeout_ms) = 0; 408 409 /*! @brief Method to set maximum number of mixer stages for each display. 410 411 @param[in] max_mixer_stages maximum number of mixer stages. 412 413 @return \link DisplayError \endlink 414 */ 415 virtual DisplayError SetMaxMixerStages(uint32_t max_mixer_stages) = 0; 416 417 /*! @brief Method to control partial update feature for each display. 418 419 @param[in] enable partial update feature control flag 420 @param[out] pending whether the operation is completed or pending for completion 421 422 @return \link DisplayError \endlink 423 */ 424 virtual DisplayError ControlPartialUpdate(bool enable, uint32_t *pending) = 0; 425 426 /*! @brief Method to disable partial update for at least 1 frame. 427 @return \link DisplayError \endlink 428 */ 429 virtual DisplayError DisablePartialUpdateOneFrame() = 0; 430 431 /*! @brief Method to set the mode of the primary display. 432 433 @param[in] mode the new display mode. 434 435 @return \link DisplayError \endlink 436 */ 437 virtual DisplayError SetDisplayMode(uint32_t mode) = 0; 438 439 /*! @brief Method to get the min and max refresh rate of a display. 440 441 @param[out] min and max refresh rate. 442 443 @return \link DisplayError \endlink 444 */ 445 virtual DisplayError GetRefreshRateRange(uint32_t *min_refresh_rate, 446 uint32_t *max_refresh_rate) = 0; 447 448 /*! @brief Method to set the refresh rate of a display. 449 450 @param[in] new refresh rate of the display. 451 452 @return \link DisplayError \endlink 453 */ 454 virtual DisplayError SetRefreshRate(uint32_t refresh_rate) = 0; 455 456 /*! @brief Method to query whether scanning is support for the HDMI display. 457 458 @return \link DisplayError \endlink 459 */ 460 virtual bool IsUnderscanSupported() = 0; 461 462 /*! @brief Method to set brightness of the primary display. 463 464 @param[in] level the new backlight level. 465 466 @return \link DisplayError \endlink 467 */ 468 virtual DisplayError SetPanelBrightness(int level) = 0; 469 470 /*! @brief Method to notify display about change in min HDCP encryption level. 471 472 @param[in] min_enc_level minimum encryption level value. 473 474 @return \link DisplayError \endlink 475 */ 476 virtual DisplayError OnMinHdcpEncryptionLevelChange(uint32_t min_enc_level) = 0; 477 478 /*! @brief Method to route display API requests to color service. 479 480 @param[in] in_payload \link PPDisplayAPIPayload \endlink 481 @param[out] out_payload \link PPDisplayPayload \endlink 482 @param[out] pending_action \link PPPendingParams \endlink 483 484 @return \link DisplayError \endlink 485 */ 486 virtual DisplayError ColorSVCRequestRoute(const PPDisplayAPIPayload &in_payload, 487 PPDisplayAPIPayload *out_payload, 488 PPPendingParams *pending_action) = 0; 489 490 /*! @brief Method to request the number of color modes supported. 491 492 @param[out] mode_count Number of modes 493 494 @return \link DisplayError \endlink 495 */ 496 virtual DisplayError GetColorModeCount(uint32_t *mode_count) = 0; 497 498 /*! @brief Method to request the information of supported color modes. 499 500 @param[inout] mode_count Number of updated modes 501 @param[out] vector of mode strings 502 503 @return \link DisplayError \endlink 504 */ 505 virtual DisplayError GetColorModes(uint32_t *mode_count, 506 std::vector<std::string> *color_modes) = 0; 507 508 /*! @brief Method to set the color mode 509 510 @param[in] mode_name Mode name which needs to be set 511 512 @return \link DisplayError \endlink 513 */ 514 virtual DisplayError SetColorMode(const std::string &color_mode) = 0; 515 516 /*! @brief Method to set the color transform 517 518 @param[in] length Mode name which needs to be set 519 @param[in] color_transform 4x4 Matrix for color transform 520 521 @return \link DisplayError \endlink 522 */ 523 virtual DisplayError SetColorTransform(const uint32_t length, const double *color_transform) = 0; 524 525 /*! @brief Method to request applying default display mode. 526 527 @return \link DisplayError \endlink 528 */ 529 virtual DisplayError ApplyDefaultDisplayMode() = 0; 530 531 /*! @brief Method to set the position of the hw cursor. 532 533 @param[in] x \link x position \endlink 534 @param[in] y \link y position \endlink 535 536 @return \link DisplayError \endlink 537 */ 538 virtual DisplayError SetCursorPosition(int x, int y) = 0; 539 540 /*! @brief Method to get the brightness level of the display 541 542 @param[out] level brightness level 543 544 @return \link DisplayError \endlink 545 */ 546 virtual DisplayError GetPanelBrightness(int *level) = 0; 547 548 /*! @brief Method to set layer mixer resolution. 549 550 @param[in] width layer mixer width 551 @param[in] height layer mixer height 552 553 @return \link DisplayError \endlink 554 */ 555 virtual DisplayError SetMixerResolution(uint32_t width, uint32_t height) = 0; 556 557 /*! @brief Method to get layer mixer resolution. 558 559 @param[out] width layer mixer width 560 @param[out] height layer mixer height 561 562 @return \link DisplayError \endlink 563 */ 564 virtual DisplayError GetMixerResolution(uint32_t *width, uint32_t *height) = 0; 565 566 /*! @brief Method to set frame buffer configuration. 567 568 @param[in] variable_info \link DisplayConfigVariableInfo \endlink 569 570 @return \link DisplayError \endlink 571 */ 572 virtual DisplayError SetFrameBufferConfig(const DisplayConfigVariableInfo &variable_info) = 0; 573 574 /*! @brief Method to get frame buffer configuration. 575 576 @param[out] variable_info \link DisplayConfigVariableInfo \endlink 577 578 @return \link DisplayError \endlink 579 */ 580 virtual DisplayError GetFrameBufferConfig(DisplayConfigVariableInfo *variable_info) = 0; 581 582 /*! @brief Method to set detail enhancement data. 583 584 @param[in] de_data \link DisplayDetailEnhancerData \endlink 585 586 @return \link DisplayError \endlink 587 */ 588 virtual DisplayError SetDetailEnhancerData(const DisplayDetailEnhancerData &de_data) = 0; 589 590 /*! @brief Method to get display port information. 591 592 @param[out] port \link DisplayPort \endlink 593 594 @return \link DisplayError \endlink 595 */ 596 virtual DisplayError GetDisplayPort(DisplayPort *port) = 0; 597 598 /*! @brief Method to query whether it is Primrary device. 599 600 @return \link Bool \endlink 601 */ 602 virtual bool IsPrimaryDisplay() = 0; 603 604 protected: 605 virtual ~DisplayInterface() { } 606 }; 607 608 } // namespace sdm 609 610 #endif // __DISPLAY_INTERFACE_H__ 611 612
