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