1 /* 2 * Copyright (C) 2020 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 17 #ifndef DISPLAYCOLOR_H_ 18 #define DISPLAYCOLOR_H_ 19 20 #include <android/hardware/graphics/common/1.1/types.h> 21 #include <android/hardware/graphics/common/1.2/types.h> 22 23 #include <functional> 24 #include <memory> 25 #include <optional> 26 #include <string> 27 28 namespace displaycolor { 29 30 namespace hwc { 31 using android::hardware::graphics::common::V1_1::RenderIntent; 32 using android::hardware::graphics::common::V1_2::ColorMode; 33 using android::hardware::graphics::common::V1_2::Dataspace; 34 using android::hardware::graphics::common::V1_2::PixelFormat; 35 } // namespace hwc 36 37 /** 38 * hwc/displaycolor interface history 39 * 40 * 7.0.0.2022-03-22 Interface refactor 41 * 6.2.0.2022-05-18 Get calibrated serial number. 42 * 6.1.0.2022-04-29 dim solid color layer 43 * 6.0.0.2022-02-22 Get whether dimming in linear. 44 * 5.0.0.2022-02-17 Add layer dim ratio. 45 * 4.0.0.2021-12-20 Get pixel format and dataspace of blending stage. 46 * 3.0.0.2021-11-18 calibration info intf 47 * 2.0.0.2021-08-27 pass brightness table for hdr10+ 48 * 1.0.0.2021-08-25 Initial release 49 */ 50 51 constexpr struct DisplayColorIntfVer { 52 uint16_t major; // increase it for new functionalities 53 uint16_t minor; // for bug fix and cause binary incompatible 54 uint16_t patch; // for bug fix and binary compatible 55 56 bool operator==(const DisplayColorIntfVer &rhs) const { 57 return major == rhs.major && 58 minor == rhs.minor && 59 patch == rhs.patch; 60 } 61 62 bool operator!=(const DisplayColorIntfVer &rhs) const { 63 return !operator==(rhs); 64 } 65 CompatibleDisplayColorIntfVer66 bool Compatible(const DisplayColorIntfVer &rhs) const { 67 return major == rhs.major && 68 minor == rhs.minor; 69 } 70 71 } kInterfaceVersion { 72 7, 73 0, 74 0, 75 }; 76 77 /// A map associating supported RenderIntents for each supported ColorMode 78 using ColorModesMap = std::map<hwc::ColorMode, std::vector<hwc::RenderIntent>>; 79 80 /// Image data bit depths. 81 enum class BitDepth { kEight, kTen }; 82 83 // deprecated by 'int64_t display_id' TODO: remove after all clients upgrade to 84 // display_id 85 /// Display type used to get pipeline or update display scene. 86 enum DisplayType { 87 /// builtin primary display 88 DISPLAY_PRIMARY = 0, 89 /// builtin secondary display 90 DISPLAY_SECONDARY = 1, 91 /// external display 92 DISPLAY_EXTERNAL = 2, 93 /// number of display 94 DISPLAY_MAX = 3, 95 }; 96 97 enum BrightnessMode { 98 BM_NOMINAL = 0, 99 BM_HBM = 1, 100 BM_MAX = 2, 101 BM_INVALID = BM_MAX, 102 }; 103 104 enum class HdrLayerState { 105 /// No HDR layer on screen 106 kHdrNone, 107 /// One or more small HDR layer(s), < 50% display size, take it as portrait mode. 108 kHdrSmall, 109 /// At least one large HDR layer, >= 50% display size, take it as full screen mode. 110 kHdrLarge, 111 }; 112 113 struct DisplayBrightnessRange { 114 // inclusive lower bound 115 float nits_min{}; 116 // inclusive upper bound 117 float nits_max{}; 118 119 // inclusive lower bound 120 uint32_t dbv_min{}; 121 // inclusive upper bound 122 uint32_t dbv_max{}; 123 124 bool brightness_min_exclusive; 125 float brightness_min{}; 126 // inclusive upper bound 127 float brightness_max{}; 128 IsValidDisplayBrightnessRange129 bool IsValid() const { 130 // Criteria 131 // 1. max >= min 132 // 2. float min >= 0 133 return nits_min >= 0 && brightness_min >= 0 && nits_max >= nits_min && dbv_max >= dbv_min && 134 brightness_max >= brightness_min; 135 } 136 }; 137 typedef std::map<BrightnessMode, DisplayBrightnessRange> BrightnessRangeMap; 138 139 class IBrightnessTable { 140 public: ~IBrightnessTable()141 virtual ~IBrightnessTable(){}; 142 143 virtual std::optional<std::reference_wrapper<const DisplayBrightnessRange>> GetBrightnessRange( 144 BrightnessMode bm) const = 0; 145 virtual std::optional<float> BrightnessToNits(float brightness, BrightnessMode &bm) const = 0; 146 virtual std::optional<uint32_t> NitsToDbv(BrightnessMode bm, float nits) const = 0; 147 virtual std::optional<float> DbvToNits(BrightnessMode bm, uint32_t dbv) const = 0; 148 virtual std::optional<float> NitsToBrightness(float nits) const = 0; 149 virtual std::optional<float> DbvToBrightness(uint32_t dbv) const = 0; 150 }; 151 152 /** 153 * @brief This structure holds data imported from HWC. 154 */ 155 struct DisplayInfo { 156 // deprecated by display_id 157 DisplayType display_type{DISPLAY_MAX}; 158 int64_t display_id{-1}; 159 std::string panel_name; 160 std::string panel_serial; 161 162 // If brightness table exists in pb file, it will overwrite values in brightness_ranges 163 BrightnessRangeMap brightness_ranges; 164 }; 165 166 struct Color { 167 uint8_t r{}; 168 uint8_t g{}; 169 uint8_t b{}; 170 uint8_t a{}; 171 172 bool operator==(const Color &rhs) const { 173 return r == rhs.r && 174 g == rhs.g && 175 b == rhs.b && 176 a == rhs.a; 177 } 178 }; 179 180 struct LayerColorData { 181 bool operator==(const LayerColorData &rhs) const { 182 return dataspace == rhs.dataspace && matrix == rhs.matrix && 183 static_metadata == rhs.static_metadata && 184 dynamic_metadata == rhs.dynamic_metadata && 185 dim_ratio == rhs.dim_ratio && 186 is_solid_color_layer == rhs.is_solid_color_layer && 187 (!is_solid_color_layer || solid_color == rhs.solid_color) && 188 enabled == rhs.enabled; 189 } 190 191 bool operator!=(const LayerColorData &rhs) const { 192 return !operator==(rhs); 193 } 194 195 /** 196 * @brief HDR static metadata. 197 * 198 * See HWC v2.2 (IComposerClient::PerFrameMetadataKey) 199 * for more information. 200 */ 201 struct HdrStaticMetadata { 202 private: 203 std::array<int32_t, 13> data; 204 205 public: 206 HdrStaticMetadata() = default; HdrStaticMetadataLayerColorData::HdrStaticMetadata207 HdrStaticMetadata(const HdrStaticMetadata &other) 208 : data(other.data), is_valid(other.is_valid) {} 209 HdrStaticMetadata(const HdrStaticMetadata &&other) = delete; 210 HdrStaticMetadata &operator=(const HdrStaticMetadata &other) { 211 data = other.data; 212 is_valid = other.is_valid; 213 return *this; 214 } 215 HdrStaticMetadata &operator=(HdrStaticMetadata &&other) = delete; 216 ~HdrStaticMetadata() = default; 217 218 bool operator==(const HdrStaticMetadata &rhs) const { 219 return data == rhs.data && is_valid == rhs.is_valid; 220 } 221 bool operator!=(const HdrStaticMetadata &rhs) const { 222 return !operator==(rhs); 223 } 224 225 /// Indicator for whether the data in this struct should be used. 226 bool is_valid = false; 227 /// This device's display's peak luminance, in nits. 228 int32_t &device_max_luminance = data[0]; 229 230 // Mastering display properties 231 int32_t &display_red_primary_x = data[1]; 232 int32_t &display_red_primary_y = data[2]; 233 int32_t &display_green_primary_x = data[3]; 234 int32_t &display_green_primary_y = data[4]; 235 int32_t &display_blue_primary_x = data[5]; 236 int32_t &display_blue_primary_y = data[6]; 237 int32_t &white_point_x = data[7]; 238 int32_t &white_point_y = data[8]; 239 int32_t &max_luminance = data[9]; 240 int32_t &min_luminance = data[10]; 241 242 // Content properties 243 int32_t &max_content_light_level = data[11]; 244 int32_t &max_frame_average_light_level = data[12]; 245 }; 246 247 /** 248 * @brief HDR dynamic metadata. 249 * 250 * The members defined here are a subset of metadata define in 251 * SMPTE ST 2094-40:2016. 252 * Also see module videoapi information. 253 */ 254 struct HdrDynamicMetadata { 255 bool operator==(const HdrDynamicMetadata &rhs) const { 256 return is_valid == rhs.is_valid && 257 display_maximum_luminance == rhs.display_maximum_luminance && 258 maxscl == rhs.maxscl && 259 maxrgb_percentages == rhs.maxrgb_percentages && 260 maxrgb_percentiles == rhs.maxrgb_percentiles && 261 tm_flag == rhs.tm_flag && tm_knee_x == rhs.tm_knee_x && 262 tm_knee_y == rhs.tm_knee_y && 263 bezier_curve_anchors == rhs.bezier_curve_anchors; 264 } 265 bool operator!=(const HdrDynamicMetadata &rhs) const { 266 return !operator==(rhs); 267 } 268 269 /// Indicator for whether the data in this struct should be used. 270 bool is_valid = false; 271 272 uint32_t display_maximum_luminance{}; 273 std::array<uint32_t, 3> maxscl; 274 std::vector<uint8_t> maxrgb_percentages; 275 std::vector<uint32_t> maxrgb_percentiles; 276 uint16_t tm_flag{}; 277 uint16_t tm_knee_x{}; 278 uint16_t tm_knee_y{}; 279 std::vector<uint16_t> bezier_curve_anchors; 280 }; 281 282 /// This layer's dataspace (color gamut, transfer function, and range). 283 hwc::Dataspace dataspace = hwc::Dataspace::UNKNOWN; 284 /// Color transform for this layer. See SET_LAYER_COLOR_TRANSFORM HWC v2.3. 285 // clang-format off 286 std::array<float, 16> matrix { 287 1.0, 0.0, 0.0, 0.0, 288 0.0, 1.0, 0.0, 0.0, 289 0.0, 0.0, 1.0, 0.0, 290 0.0, 0.0, 0.0, 1.0 291 }; 292 // clang-format on 293 /** 294 * @brief This layer's HDR static metadata. Only applicable when dataspace 295 * indicates this is an HDR layer. 296 */ 297 HdrStaticMetadata static_metadata; 298 /** 299 * @brief This layer's HDR dynamic metadata. Only applicable when dataspace 300 * indicates this is an HDR layer. 301 */ 302 HdrDynamicMetadata dynamic_metadata; 303 304 /** 305 * @brief the layer's luminance dim ratio 306 */ 307 float dim_ratio = 1.0f; 308 309 /** 310 * @brief is layer solid color 311 */ 312 bool is_solid_color_layer{}; 313 314 /** 315 * @brief color for solid color layer 316 */ 317 Color solid_color; 318 319 /** 320 * @brief indicates if the layer is client target 321 * 322 */ 323 bool is_client_target = false; 324 325 /** 326 * @brief indicates if this layer data has enabled. Do not compute the 327 * colordata if its false. true by default for backward compatibility. 328 */ 329 bool enabled = true; 330 }; 331 332 /** 333 * @brief DisplayScene holds all the information required for libdisplaycolor to 334 * return correct data. 335 */ 336 struct DisplayScene { 337 bool operator==(const DisplayScene &rhs) const { 338 return layer_data == rhs.layer_data && 339 dpu_bit_depth == rhs.dpu_bit_depth && 340 color_mode == rhs.color_mode && 341 render_intent == rhs.render_intent && 342 matrix == rhs.matrix && 343 force_hdr == rhs.force_hdr && 344 bm == rhs.bm && 345 lhbm_on == rhs.lhbm_on && 346 dbv == rhs.dbv && 347 refresh_rate == rhs.refresh_rate && 348 operation_rate == rhs.operation_rate && 349 hdr_layer_state == rhs.hdr_layer_state; 350 } 351 bool operator!=(const DisplayScene &rhs) const { 352 return !(*this == rhs); 353 } 354 355 /// A vector of layer color data. 356 std::vector<LayerColorData> layer_data; 357 /// The bit depth the DPU is currently outputting 358 BitDepth dpu_bit_depth = BitDepth::kTen; 359 /// The current ColorMode (typically set by SurfaceFlinger) 360 hwc::ColorMode color_mode = hwc::ColorMode::NATIVE; 361 /// The current RenderIntent (typically set by SurfaceFlinger) 362 hwc::RenderIntent render_intent = hwc::RenderIntent::COLORIMETRIC; 363 /// Color transform for this layer. See SET_COLOR_TRANSFORM HWC v2.1. 364 // clang-format off 365 std::array<float, 16> matrix { 366 1.0, 0.0, 0.0, 0.0, 367 0.0, 1.0, 0.0, 0.0, 368 0.0, 0.0, 1.0, 0.0, 369 0.0, 0.0, 0.0, 1.0 370 }; 371 // clang-format on 372 /// When this bit is set, process hdr layers and the layer matrix even if 373 //it's in native color mode. 374 bool force_hdr = false; 375 376 /// display brightness mode 377 BrightnessMode bm = BrightnessMode::BM_NOMINAL; 378 379 /// dbv level 380 uint32_t dbv = 0; 381 382 /// lhbm status 383 bool lhbm_on = false; 384 385 /// refresh rate 386 float refresh_rate = 60.0f; 387 388 /// operation rate to switch between hs/ns mode 389 uint32_t operation_rate = 120; 390 391 /// hdr layer state on screen 392 HdrLayerState hdr_layer_state = HdrLayerState::kHdrNone; 393 }; 394 395 struct CalibrationInfo { 396 bool factory_cal_loaded = false; 397 bool golden_cal_loaded = false; 398 bool common_cal_loaded = false; 399 bool dev_cal_loaded = false; 400 }; 401 402 /// An interface specifying functions that are HW-agnostic. 403 class IDisplayColorGeneric { 404 public: 405 /// A generic stage in the display pipeline. 406 template <typename T> 407 struct DisplayStage { 408 using ConfigType = T; 409 410 std::function<void(void)> data_applied_notifier = nullptr; NotifyDataAppliedDisplayStage411 void NotifyDataApplied() const { 412 if (data_applied_notifier) { 413 data_applied_notifier(); 414 } 415 } 416 417 bool enable = false; 418 /// A flag indicating if the data has been changed in last Update call. 419 // It should be set when enable is changed from false to true. 420 bool dirty = false; 421 422 const ConfigType *config = nullptr; 423 }; 424 425 /// A collection of stages. For example, It could be pre-blending stages 426 //(per-channel) or post-blending stages. 427 template <typename ... IStageData> 428 struct IStageDataCollection : public IStageData ... { ~IStageDataCollectionIStageDataCollection429 virtual ~IStageDataCollection() {} 430 }; 431 432 /// Interface for accessing data for panel 433 class IPanel { 434 public: 435 /// Get the adjusted dbv for panel. 436 virtual uint32_t GetAdjustedBrightnessLevel() const = 0; 437 ~IPanel()438 virtual ~IPanel() {} 439 }; 440 ~IDisplayColorGeneric()441 virtual ~IDisplayColorGeneric() {} 442 443 /** 444 * @brief Update display color data. This function is expected to be called 445 * in the context of HWC::validateDisplay, if the display scene has changed. 446 * 447 * @param display The display relating to the scene. 448 * @param scene Display scene data to use during the update. 449 * @return OK if successful, error otherwise. 450 */ 451 //deprecated by the 'int64_t display' version 452 virtual int Update(const DisplayType display, const DisplayScene &scene) = 0; 453 virtual int Update(const int64_t display, const DisplayScene &scene) = 0; 454 455 /** 456 * @brief Update display color data. This function is expected to be called 457 * in the context of HWC::presentDisplay, if the display scene has changed 458 * since the Update call for HWC::validateDisplay. 459 * 460 * @param display The display relating to the scene. 461 * @param scene Display scene data to use during the update. 462 * @return OK if successful, error otherwise. 463 */ 464 //deprecated by the 'int64_t display' version 465 virtual int UpdatePresent(const DisplayType display, const DisplayScene &scene) = 0; 466 virtual int UpdatePresent(const int64_t display, const DisplayScene &scene) = 0; 467 468 /** 469 * @brief Check if refresh rate regamma compensation is enabled. 470 * 471 * @return true for yes. 472 */ 473 //deprecated by the 'int64_t display' version 474 virtual bool IsRrCompensationEnabled(const DisplayType display) = 0; 475 virtual bool IsRrCompensationEnabled(const int64_t display) = 0; 476 477 /** 478 * @brief Get calibration information for each profiles. 479 * @param display The display to get the calibration information. 480 */ 481 //deprecated by the 'int64_t display' version 482 virtual const CalibrationInfo &GetCalibrationInfo(const DisplayType display) const = 0; 483 virtual const CalibrationInfo &GetCalibrationInfo(const int64_t display) const = 0; 484 485 /** 486 * @brief Get a map of supported ColorModes, and supported RenderIntents for 487 * each ColorMode. 488 * @param display The display to get the color modes and render intents. 489 */ 490 //deprecated by the 'int64_t display' version 491 virtual const ColorModesMap &ColorModesAndRenderIntents(const DisplayType display) const = 0; 492 virtual const ColorModesMap &ColorModesAndRenderIntents(const int64_t display) const = 0; 493 494 /** 495 * @brief Get pixel format and dataspace of blending stage. 496 * @param display to read the properties. 497 * @param pixel_format Pixel format of blending stage 498 * @param dataspace Dataspace of blending stage 499 * @return OK if successful, error otherwise. 500 */ 501 //deprecated by the 'int64_t display' version 502 virtual int GetBlendingProperty(const DisplayType display, 503 hwc::PixelFormat &pixel_format, 504 hwc::Dataspace &dataspace, 505 bool &dimming_linear) const = 0; 506 virtual int GetBlendingProperty(const int64_t display, 507 hwc::PixelFormat &pixel_format, 508 hwc::Dataspace &dataspace, 509 bool &dimming_linear) const = 0; 510 511 /** 512 * @brief Get the serial number for the panel used during calibration. 513 * @param display to get the calibrated serial number. 514 * @return The calibrated serial number. 515 */ 516 //deprecated by the 'int64_t display' version 517 virtual const std::string& GetCalibratedSerialNumber(DisplayType display) const = 0; 518 virtual const std::string& GetCalibratedSerialNumber(const int64_t display) const = 0; 519 520 /** 521 * @brief Get brightness table to do brightness conversion between {normalized brightness, nits, 522 * dbv}. 523 * @param display Reserved field to choose display type. 524 * @param table Return brightness table if successful, nullptr if the table is not valid. 525 * @return OK if successful, error otherwise. 526 */ 527 //deprecated by the 'int64_t display' version 528 virtual int GetBrightnessTable(DisplayType display, 529 std::unique_ptr<const IBrightnessTable> &table) const = 0; 530 virtual int GetBrightnessTable(const int64_t display, 531 std::unique_ptr<const IBrightnessTable> &table) const = 0; 532 533 /** 534 * @brief Add a display for color pipeline configuration. 535 * @param display_info info of this display 536 * @return OK if successful, error otherwise. 537 */ 538 virtual int AddDisplay(const DisplayInfo &display_info) = 0; 539 540 /** 541 * @brief Remove a display and release its resources. 542 */ 543 virtual void RemoveDisplay(const int64_t display) = 0; 544 545 /** 546 * @brief request a Update call. For example, a debug command has changed 547 * the displaycolor internal states and need to apply to next frame update. 548 */ 549 virtual bool CheckUpdateNeeded(const int64_t display) = 0; 550 }; 551 552 extern "C" { 553 const DisplayColorIntfVer *GetInterfaceVersion(); 554 } 555 556 } // namespace displaycolor 557 558 #endif // DISPLAYCOLOR_H_ 559