1 /* 2 * Copyright (c) 2014 - 2015, 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 38 #include "layer_stack.h" 39 #include "sdm_types.h" 40 41 namespace sdm { 42 43 /*! @brief This enum represents display device types where contents can be rendered. 44 45 @sa CoreInterface::CreateDisplay 46 @sa CoreInterface::IsDisplaySupported 47 */ 48 enum DisplayType { 49 kPrimary, //!< Main physical display which is attached to the handheld device. 50 kHDMI, //!< HDMI physical display which is generally detachable. 51 kVirtual, //!< Contents would be rendered into the output buffer provided by the client 52 //!< e.g. wireless display. 53 kDisplayMax, 54 }; 55 56 /*! @brief This enum represents states of a display device. 57 58 @sa DisplayInterface::GetDisplayState 59 @sa DisplayInterface::SetDisplayState 60 */ 61 enum DisplayState { 62 kStateOff, //!< Display is OFF. Contents are not rendered in this state. Client will not 63 //!< receive VSync events in this state. This is default state as well. 64 65 kStateOn, //!< Display is ON. Contents are rendered in this state. 66 67 kStateDoze, //!< Display is ON and it is configured in a low power state. 68 69 kStateDozeSuspend, 70 //!< Display is ON in a low power state and continue showing its current 71 //!< contents indefinitely until the mode changes. 72 73 kStateStandby, //!< Display is OFF. Client will continue to receive VSync events in this state 74 //!< if VSync is enabled. Contents are not rendered in this state. 75 }; 76 77 /*! @brief This structure defines configuration for fixed properties of a display device. 78 79 @sa DisplayInterface::GetConfig 80 @sa DisplayInterface::SetConfig 81 */ 82 struct DisplayConfigFixedInfo { 83 bool underscan = false; //!< If display support CE underscan. 84 bool secure = false; //!< If this display is capable of handling secure content. 85 }; 86 87 /*! @brief This structure defines configuration for variable properties of a display device. 88 89 @sa DisplayInterface::GetConfig 90 @sa DisplayInterface::SetConfig 91 */ 92 struct DisplayConfigVariableInfo { 93 uint32_t x_pixels = 0; //!< Total number of pixels in X-direction on the display panel. 94 uint32_t y_pixels = 0; //!< Total number of pixels in Y-direction on the display panel. 95 float x_dpi = 0.0f; //!< Dots per inch in X-direction. 96 float y_dpi = 0.0f; //!< Dots per inch in Y-direction. 97 uint32_t fps = 0; //!< Frame rate per second. 98 uint32_t vsync_period_ns = 0; //!< VSync period in nanoseconds. 99 }; 100 101 /*! @brief Event data associated with VSync event. 102 103 @sa DisplayEventHandler::VSync 104 */ 105 struct DisplayEventVSync { 106 int64_t timestamp = 0; //!< System monotonic clock timestamp in nanoseconds. 107 }; 108 109 /*! @brief Display device event handler implemented by the client. 110 111 @details This class declares prototype for display device event handler methods which must be 112 implemented by the client. Display device will use these methods to notify events to the client. 113 Client must post heavy-weight event handling to a separate thread and unblock display manager 114 thread instantly. 115 116 @sa CoreInterface::CreateDisplay 117 */ 118 class DisplayEventHandler { 119 public: 120 /*! @brief Event handler for VSync event. 121 122 @details This event is dispatched on every vertical synchronization. The event is disabled by 123 default. 124 125 @param[in] vsync \link DisplayEventVSync \endlink 126 127 @return \link DisplayError \endlink 128 129 @sa DisplayInterface::GetDisplayState 130 @sa DisplayInterface::SetDisplayState 131 */ 132 virtual DisplayError VSync(const DisplayEventVSync &vsync) = 0; 133 134 /*! @brief Event handler for Refresh event. 135 136 @details This event is dispatched to trigger a screen refresh. Client must call Prepare() and 137 Commit() in response to it from a separate thread. There is no data associated with this 138 event. 139 140 @return \link DisplayError \endlink 141 142 @sa DisplayInterface::Prepare 143 @sa DisplayInterface::Commit 144 */ 145 virtual DisplayError Refresh() = 0; 146 147 protected: ~DisplayEventHandler()148 virtual ~DisplayEventHandler() { } 149 }; 150 151 struct PPDisplayAPIPayload; 152 struct PPPendingParams; 153 154 /*! @brief Display device interface. 155 156 @details This class defines display device interface. It contains methods which client shall use 157 to configure or submit layers for composition on the display device. This interface is created 158 during display device creation and remains valid until destroyed. 159 160 @sa CoreInterface::CreateDisplay 161 @sa CoreInterface::DestroyDisplay 162 */ 163 class DisplayInterface { 164 public: 165 /*! @brief Method to determine hardware capability to compose layers associated with given frame. 166 167 @details Client shall send all layers associated with a frame targeted for current display 168 using this method and check the layers which can be handled completely in display manager. 169 170 Client shall mark composition type for one of the layer as kCompositionGPUTarget; the GPU 171 composed output would be rendered at the specified layer if some of the layers are not handled 172 by SDM. 173 174 Display manager will set each layer as kCompositionGPU or kCompositionSDE upon return. Client 175 shall render all the layers marked as kCompositionGPU using GPU. 176 177 This method can be called multiple times but only last call prevails. This method must be 178 followed by Commit(). 179 180 @param[inout] layer_stack \link LayerStack \endlink 181 182 @return \link DisplayError \endlink 183 184 @sa Commit 185 */ 186 virtual DisplayError Prepare(LayerStack *layer_stack) = 0; 187 188 /*! @brief Method to commit layers of a frame submitted in a former call to Prepare(). 189 190 @details Client shall call this method to submit layers for final composition. The composed 191 output would be displayed on the panel or written in output buffer. 192 193 Client must ensure that layer stack is same as previous call to Prepare. 194 195 This method shall be called only once for each frame. 196 197 In the event of an error as well, this call will cause any fences returned in the previous call 198 to Commit() to eventually become signaled, so the client's wait on fences can be released to 199 prevent deadlocks. 200 201 @param[in] layer_stack \link LayerStack \endlink 202 203 @return \link DisplayError \endlink 204 205 @sa Prepare 206 */ 207 virtual DisplayError Commit(LayerStack *layer_stack) = 0; 208 209 /*! @brief Method to flush any pending buffers/fences submitted previously via Commit() call. 210 211 @details Client shall call this method to request the Display manager to release all buffers and 212 respective fences currently in use. This operation may result in a blank display on the panel 213 until a new frame is submitted for composition. 214 215 @return \link DisplayError \endlink 216 217 @sa Prepare 218 @sa Commit 219 */ 220 virtual DisplayError Flush() = 0; 221 222 /*! @brief Method to get current state of the display device. 223 224 @param[out] state \link DisplayState \endlink 225 226 @return \link DisplayError \endlink 227 228 @sa SetDisplayState 229 */ 230 virtual DisplayError GetDisplayState(DisplayState *state) = 0; 231 232 /*! @brief Method to get number of configurations(variable properties) supported on the display 233 device. 234 235 @param[out] count Number of modes supported; mode index starts with 0. 236 237 @return \link DisplayError \endlink 238 */ 239 virtual DisplayError GetNumVariableInfoConfigs(uint32_t *count) = 0; 240 241 /*! @brief Method to get configuration for fixed properties of the display device. 242 243 @param[out] fixed_info \link DisplayConfigFixedInfo \endlink 244 245 @return \link DisplayError \endlink 246 */ 247 virtual DisplayError GetConfig(DisplayConfigFixedInfo *fixed_info) = 0; 248 249 /*! @brief Method to get configuration for variable properties of the display device. 250 251 @param[in] index index of the mode 252 @param[out] variable_info \link DisplayConfigVariableInfo \endlink 253 254 @return \link DisplayError \endlink 255 */ 256 virtual DisplayError GetConfig(uint32_t index, DisplayConfigVariableInfo *variable_info) = 0; 257 258 /*! @brief Method to get index of active configuration of the display device. 259 260 @param[out] index index of the mode corresponding to variable properties. 261 262 @return \link DisplayError \endlink 263 */ 264 virtual DisplayError GetActiveConfig(uint32_t *index) = 0; 265 266 /*! @brief Method to get VSync event state. Default event state is disabled. 267 268 @param[out] enabled vsync state 269 270 @return \link DisplayError \endlink 271 */ 272 virtual DisplayError GetVSyncState(bool *enabled) = 0; 273 274 /*! @brief Method to set current state of the display device. 275 276 @param[in] state \link DisplayState \endlink 277 278 @return \link DisplayError \endlink 279 280 @sa SetDisplayState 281 */ 282 virtual DisplayError SetDisplayState(DisplayState state) = 0; 283 284 /*! @brief Method to set active configuration for variable properties of the display device. 285 286 @param[in] variable_info \link DisplayConfigVariableInfo \endlink 287 288 @return \link DisplayError \endlink 289 */ 290 virtual DisplayError SetActiveConfig(DisplayConfigVariableInfo *variable_info) = 0; 291 292 /*! @brief Method to set active configuration for variable properties of the display device. 293 294 @param[in] index index of the mode corresponding to variable properties. 295 296 @return \link DisplayError \endlink 297 */ 298 virtual DisplayError SetActiveConfig(uint32_t index) = 0; 299 300 /*! @brief Method to set VSync event state. Default event state is disabled. 301 302 @param[out] enabled vsync state 303 304 @return \link DisplayError \endlink 305 */ 306 virtual DisplayError SetVSyncState(bool enable) = 0; 307 308 /*! @brief Method to set idle timeout value. Idle fallback is disabled with timeout value 0. 309 310 @param[in] timeout value in milliseconds. 311 312 @return \link void \endlink 313 */ 314 virtual void SetIdleTimeoutMs(uint32_t timeout_ms) = 0; 315 316 /*! @brief Method to set maximum number of mixer stages for each display. 317 318 @param[in] max_mixer_stages maximum number of mixer stages. 319 320 @return \link DisplayError \endlink 321 */ 322 virtual DisplayError SetMaxMixerStages(uint32_t max_mixer_stages) = 0; 323 324 /*! @brief Method to control partial update feature for each display. 325 326 @param[in] enable partial update feature control flag 327 @param[out] pending whether the operation is completed or pending for completion 328 329 @return \link DisplayError \endlink 330 */ 331 virtual DisplayError ControlPartialUpdate(bool enable, uint32_t *pending) = 0; 332 333 /*! @brief Method to set the mode of the primary display. 334 335 @param[in] mode the new display mode. 336 337 @return \link DisplayError \endlink 338 */ 339 virtual DisplayError SetDisplayMode(uint32_t mode) = 0; 340 341 /*! @brief Method to determine whether scaling for a custom resolution is valid. 342 343 @return \link DisplayError \endlink 344 */ 345 virtual DisplayError IsScalingValid(const LayerRect &crop, const LayerRect &dst, 346 bool rotate90) = 0; 347 348 /*! @brief Method to get the min and max refresh rate of a display. 349 350 @param[out] min and max refresh rate. 351 352 @return \link DisplayError \endlink 353 */ 354 virtual DisplayError GetRefreshRateRange(uint32_t *min_refresh_rate, 355 uint32_t *max_refresh_rate) = 0; 356 357 /*! @brief Method to set the refresh rate of a display. 358 359 @param[in] new refresh rate of the display. 360 361 @return \link DisplayError \endlink 362 */ 363 virtual DisplayError SetRefreshRate(uint32_t refresh_rate) = 0; 364 365 /*! @brief Method to query whether scanning is support for the HDMI display. 366 367 @return \link DisplayError \endlink 368 */ 369 virtual bool IsUnderscanSupported() = 0; 370 371 /*! @brief Method to set brightness of the primary display. 372 373 @param[in] level the new backlight level. 374 375 @return \link DisplayError \endlink 376 */ 377 virtual DisplayError SetPanelBrightness(int level) = 0; 378 379 /*! @brief Method to notify display about change in min HDCP encryption level. 380 381 @param[in] min_enc_level minimum encryption level value. 382 383 @return \link DisplayError \endlink 384 */ 385 virtual DisplayError OnMinHdcpEncryptionLevelChange(uint32_t min_enc_level) = 0; 386 387 /*! @brief Method to route display API requests to color service. 388 389 @param[in] in_payload \link PPDisplayAPIPayload \endlink 390 @param[out] out_payload \link PPDisplayPayload \endlink 391 @param[out] pending_action \link PPPendingParams \endlink 392 393 @return \link DisplayError \endlink 394 */ 395 virtual DisplayError ColorSVCRequestRoute(const PPDisplayAPIPayload &in_payload, 396 PPDisplayAPIPayload *out_payload, 397 PPPendingParams *pending_action) = 0; 398 399 /*! @brief Method to request applying default display mode. 400 401 @return \link DisplayError \endlink 402 */ 403 virtual DisplayError ApplyDefaultDisplayMode() = 0; 404 405 /*! @brief Method to set the position of the hw cursor. 406 407 @param[in] x \link x position \endlink 408 @param[in] y \link y position \endlink 409 410 @return \link DisplayError \endlink 411 */ 412 virtual DisplayError SetCursorPosition(int x, int y) = 0; 413 414 /*! @brief Method to get the brightness level of the display 415 416 @param[out] level brightness level 417 418 @return \link DisplayError \endlink 419 */ 420 virtual DisplayError GetPanelBrightness(int *level) = 0; 421 422 protected: ~DisplayInterface()423 virtual ~DisplayInterface() { } 424 }; 425 426 } // namespace sdm 427 428 #endif // __DISPLAY_INTERFACE_H__ 429 430