1 /* 2 * Copyright 2024 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 /** \file ultrahdr_api.h 18 * 19 * \brief 20 * Describes the encoder or decoder algorithm interface to applications. 21 */ 22 23 #ifndef ULTRAHDR_API_H 24 #define ULTRAHDR_API_H 25 26 #include <stddef.h> 27 28 #if defined(_WIN32) || defined(__CYGWIN__) 29 #if defined(UHDR_BUILDING_SHARED_LIBRARY) 30 #define UHDR_API __declspec(dllexport) 31 #elif defined(UHDR_USING_SHARED_LIBRARY) 32 #define UHDR_API __declspec(dllimport) 33 #else 34 #define UHDR_API 35 #endif 36 #elif defined(__GNUC__) && (__GNUC__ >= 4) && \ 37 (defined(UHDR_BUILDING_SHARED_LIBRARY) || defined(UHDR_USING_SHARED_LIBRARY)) 38 #define UHDR_API __attribute__((visibility("default"))) 39 #else 40 #define UHDR_API 41 #endif 42 43 #ifdef __cplusplus 44 #define UHDR_EXTERN extern "C" UHDR_API 45 #else 46 #define UHDR_EXTERN extern UHDR_API 47 #endif 48 49 /* 50 * A Note on version numbering: 51 * Over the course of development multiple changes were made to the interface that are not entirely 52 * backward compatible. Some APIs were renamed for consistency and better readability. New APIs were 53 * introduced to allow configuration of encoding/decoding parameters. As per convention, breaking 54 * backward compatibility MUST be indicated with a major version update, introducing new APIs / 55 * features MUST be indicated with a minor version update and bug fixes MUST be indicated with a 56 * patch version update. This convention however, is not followed. Below table summarizes these 57 * details: 58 * 59 * source version ultrahdr_api.h Details 60 * version string 61 * -------------- -------------- ------------- 62 * 1.0.0 Not available This version did not have a public API. Apps, 63 * directly included the project header files. 64 * 1.1.0 Not available ultrahdr_api.h is introduced in this release. The 65 * API header file did not advertise any version 66 * string. 67 * 1.1.1 Not available The API header file did not advertise any version 68 * string. Some bug fixes and introduced one new API 69 * which warrants a minor version update. But 70 * indicated as a patch update. 71 * 1.2.0 1.2.0 Some bug fixes, introduced new API and renamed 72 * existing API which warrants a major version update. 73 * But indicated as a minor update. 74 * 1.3.0 1.3.0 Some bug fixes, introduced new API. 75 * 1.4.0 1.4.0 quality improvements, bug fixes, added new features 76 * and api update. 77 */ 78 79 // This needs to be kept in sync with version in CMakeLists.txt 80 #define UHDR_LIB_VER_MAJOR 1 81 #define UHDR_LIB_VER_MINOR 4 82 #define UHDR_LIB_VER_PATCH 0 83 84 #define UHDR_LIB_VERSION \ 85 ((UHDR_LIB_VER_MAJOR * 10000) + (UHDR_LIB_VER_MINOR * 100) + UHDR_LIB_VER_PATCH) 86 87 #define XSTR(s) STR(s) 88 #define STR(s) #s 89 #define UHDR_LIB_VERSION_STR \ 90 XSTR(UHDR_LIB_VER_MAJOR) "." XSTR(UHDR_LIB_VER_MINOR) "." XSTR(UHDR_LIB_VER_PATCH) 91 92 // =============================================================================================== 93 // Enum Definitions 94 // =============================================================================================== 95 96 /*!\brief List of supported image formats */ 97 typedef enum uhdr_img_fmt { 98 UHDR_IMG_FMT_UNSPECIFIED = -1, /**< Unspecified */ 99 UHDR_IMG_FMT_24bppYCbCrP010 = 0, /**< 10-bit-per component 4:2:0 YCbCr semiplanar format. 100 Each chroma and luma component has 16 allocated bits in 101 little-endian configuration with 10 MSB of actual data.*/ 102 UHDR_IMG_FMT_12bppYCbCr420 = 1, /**< 8-bit-per component 4:2:0 YCbCr planar format */ 103 UHDR_IMG_FMT_8bppYCbCr400 = 2, /**< 8-bit-per component Monochrome format */ 104 UHDR_IMG_FMT_32bppRGBA8888 = 105 3, /**< 32 bits per pixel RGBA color format, with 8-bit red, green, blue 106 and alpha components. Using 32-bit little-endian representation, 107 colors stored as Red 7:0, Green 15:8, Blue 23:16, Alpha 31:24. */ 108 UHDR_IMG_FMT_64bppRGBAHalfFloat = 109 4, /**< 64 bits per pixel, 16 bits per channel, half-precision floating point RGBA color 110 format. colors stored as Red 15:0, Green 31:16, Blue 47:32, Alpha 63:48. In a pixel 111 even though each channel has storage space of 16 bits, the nominal range is expected to 112 be [0.0..(10000/203)] */ 113 UHDR_IMG_FMT_32bppRGBA1010102 = 5, /**< 32 bits per pixel RGBA color format, with 10-bit red, 114 green, blue, and 2-bit alpha components. Using 32-bit 115 little-endian representation, colors stored as Red 9:0, Green 116 19:10, Blue 29:20, and Alpha 31:30. */ 117 UHDR_IMG_FMT_24bppYCbCr444 = 6, /**< 8-bit-per component 4:4:4 YCbCr planar format */ 118 UHDR_IMG_FMT_16bppYCbCr422 = 7, /**< 8-bit-per component 4:2:2 YCbCr planar format */ 119 UHDR_IMG_FMT_16bppYCbCr440 = 8, /**< 8-bit-per component 4:4:0 YCbCr planar format */ 120 UHDR_IMG_FMT_12bppYCbCr411 = 9, /**< 8-bit-per component 4:1:1 YCbCr planar format */ 121 UHDR_IMG_FMT_10bppYCbCr410 = 10, /**< 8-bit-per component 4:1:0 YCbCr planar format */ 122 UHDR_IMG_FMT_24bppRGB888 = 11, /**< 8-bit-per component RGB interleaved format */ 123 UHDR_IMG_FMT_30bppYCbCr444 = 12, /**< 10-bit-per component 4:4:4 YCbCr planar format */ 124 } uhdr_img_fmt_t; /**< alias for enum uhdr_img_fmt */ 125 126 /*!\brief List of supported color gamuts */ 127 typedef enum uhdr_color_gamut { 128 UHDR_CG_UNSPECIFIED = -1, /**< Unspecified */ 129 UHDR_CG_BT_709 = 0, /**< BT.709 */ 130 UHDR_CG_DISPLAY_P3 = 1, /**< Display P3 */ 131 UHDR_CG_BT_2100 = 2, /**< BT.2100 */ 132 } uhdr_color_gamut_t; /**< alias for enum uhdr_color_gamut */ 133 134 /*!\brief List of supported color transfers */ 135 typedef enum uhdr_color_transfer { 136 UHDR_CT_UNSPECIFIED = -1, /**< Unspecified */ 137 UHDR_CT_LINEAR = 0, /**< Linear */ 138 UHDR_CT_HLG = 1, /**< Hybrid log gamma */ 139 UHDR_CT_PQ = 2, /**< Perceptual Quantizer */ 140 UHDR_CT_SRGB = 3, /**< Gamma */ 141 } uhdr_color_transfer_t; /**< alias for enum uhdr_color_transfer */ 142 143 /*!\brief List of supported color ranges */ 144 typedef enum uhdr_color_range { 145 UHDR_CR_UNSPECIFIED = -1, /**< Unspecified */ 146 UHDR_CR_LIMITED_RANGE = 0, /**< Y {[16..235], UV [16..240]} * pow(2, (bpc - 8)) */ 147 UHDR_CR_FULL_RANGE = 1, /**< YUV/RGB {[0..255]} * pow(2, (bpc - 8)) */ 148 } uhdr_color_range_t; /**< alias for enum uhdr_color_range */ 149 150 /*!\brief List of supported codecs */ 151 typedef enum uhdr_codec { 152 UHDR_CODEC_JPG, /**< Compress {Hdr, Sdr rendition} to an {Sdr rendition + Gain Map} using jpeg */ 153 UHDR_CODEC_HEIF, /**< Compress {Hdr, Sdr rendition} to an {Sdr rendition + Gain Map} using heif */ 154 UHDR_CODEC_AVIF, /**< Compress {Hdr, Sdr rendition} to an {Sdr rendition + Gain Map} using avif */ 155 } uhdr_codec_t; /**< alias for enum uhdr_codec */ 156 157 /*!\brief Image identifiers in gain map technology */ 158 typedef enum uhdr_img_label { 159 UHDR_HDR_IMG, /**< Hdr rendition image */ 160 UHDR_SDR_IMG, /**< Sdr rendition image */ 161 UHDR_BASE_IMG, /**< Base rendition image */ 162 UHDR_GAIN_MAP_IMG, /**< Gain map image */ 163 } uhdr_img_label_t; /**< alias for enum uhdr_img_label */ 164 165 /*!\brief uhdr encoder usage parameter */ 166 typedef enum uhdr_enc_preset { 167 UHDR_USAGE_REALTIME, /**< tune encoder settings for performance */ 168 UHDR_USAGE_BEST_QUALITY, /**< tune encoder settings for quality */ 169 } uhdr_enc_preset_t; /**< alias for enum uhdr_enc_preset */ 170 171 /*!\brief Algorithm return codes */ 172 typedef enum uhdr_codec_err { 173 174 /*!\brief Operation completed without error */ 175 UHDR_CODEC_OK, 176 177 /*!\brief Generic codec error, refer detail field for more information */ 178 UHDR_CODEC_ERROR, 179 180 /*!\brief Unknown error, refer detail field for more information */ 181 UHDR_CODEC_UNKNOWN_ERROR, 182 183 /*!\brief An application-supplied parameter is not valid. */ 184 UHDR_CODEC_INVALID_PARAM, 185 186 /*!\brief Memory operation failed */ 187 UHDR_CODEC_MEM_ERROR, 188 189 /*!\brief An application-invoked operation is not valid */ 190 UHDR_CODEC_INVALID_OPERATION, 191 192 /*!\brief The library does not implement a feature required for the operation */ 193 UHDR_CODEC_UNSUPPORTED_FEATURE, 194 195 /*!\brief Not for usage, indicates end of list */ 196 UHDR_CODEC_LIST_END, 197 198 } uhdr_codec_err_t; /**< alias for enum uhdr_codec_err */ 199 200 /*!\brief List of supported mirror directions. */ 201 typedef enum uhdr_mirror_direction { 202 UHDR_MIRROR_VERTICAL, /**< flip image over x axis */ 203 UHDR_MIRROR_HORIZONTAL, /**< flip image over y axis */ 204 } uhdr_mirror_direction_t; /**< alias for enum uhdr_mirror_direction */ 205 206 // =============================================================================================== 207 // Structure Definitions 208 // =============================================================================================== 209 210 /*!\brief Detailed return status */ 211 typedef struct uhdr_error_info { 212 uhdr_codec_err_t error_code; /**< error code */ 213 int has_detail; /**< has detailed error logs. 0 - no, else - yes */ 214 char detail[256]; /**< error logs */ 215 } uhdr_error_info_t; /**< alias for struct uhdr_error_info */ 216 217 /**\brief Raw Image Descriptor */ 218 typedef struct uhdr_raw_image { 219 /* Color Aspects: Color model, primaries, transfer, range */ 220 uhdr_img_fmt_t fmt; /**< Image Format */ 221 uhdr_color_gamut_t cg; /**< Color Gamut */ 222 uhdr_color_transfer_t ct; /**< Color Transfer */ 223 uhdr_color_range_t range; /**< Color Range */ 224 225 /* Image storage dimensions */ 226 unsigned int w; /**< Stored image width */ 227 unsigned int h; /**< Stored image height */ 228 229 /* Image data pointers. */ 230 #define UHDR_PLANE_PACKED 0 /**< To be used for all packed formats */ 231 #define UHDR_PLANE_Y 0 /**< Y (Luminance) plane */ 232 #define UHDR_PLANE_U 1 /**< U (Chroma) plane */ 233 #define UHDR_PLANE_UV 1 /**< UV (Chroma plane interleaved) To be used for semi planar format */ 234 #define UHDR_PLANE_V 2 /**< V (Chroma) plane */ 235 void* planes[3]; /**< pointer to the top left pixel for each plane */ 236 unsigned int stride[3]; /**< stride in pixels between rows for each plane */ 237 } uhdr_raw_image_t; /**< alias for struct uhdr_raw_image */ 238 239 /**\brief Compressed Image Descriptor */ 240 typedef struct uhdr_compressed_image { 241 void* data; /**< Pointer to a block of data to decode */ 242 size_t data_sz; /**< size of the data buffer */ 243 size_t capacity; /**< maximum size of the data buffer */ 244 uhdr_color_gamut_t cg; /**< Color Gamut */ 245 uhdr_color_transfer_t ct; /**< Color Transfer */ 246 uhdr_color_range_t range; /**< Color Range */ 247 } uhdr_compressed_image_t; /**< alias for struct uhdr_compressed_image */ 248 249 /**\brief Buffer Descriptor */ 250 typedef struct uhdr_mem_block { 251 void* data; /**< Pointer to a block of data to decode */ 252 size_t data_sz; /**< size of the data buffer */ 253 size_t capacity; /**< maximum size of the data buffer */ 254 } uhdr_mem_block_t; /**< alias for struct uhdr_mem_block */ 255 256 /**\brief Gain map metadata. */ 257 typedef struct uhdr_gainmap_metadata { 258 float max_content_boost[3]; /**< Value to control how much brighter an image can get, when shown 259 on an HDR display, relative to the SDR rendition. This is constant for 260 a given image. Value MUST be in linear scale. */ 261 float min_content_boost[3]; /**< Value to control how much darker an image can get, when shown on 262 an HDR display, relative to the SDR rendition. This is constant for a 263 given image. Value MUST be in linear scale. */ 264 float gamma[3]; /**< Encoding Gamma of the gainmap image. */ 265 float offset_sdr[3]; /**< The offset to apply to the SDR pixel values during gainmap generation 266 and application. */ 267 float offset_hdr[3]; /**< The offset to apply to the HDR pixel values during gainmap generation 268 and application. */ 269 float hdr_capacity_min; /**< Minimum display boost value for which the map is applied completely. 270 Value MUST be in linear scale. */ 271 float hdr_capacity_max; /**< Maximum display boost value for which the map is applied completely. 272 Value MUST be in linear scale. */ 273 int use_base_cg; /**< Is gainmap application space same as base image color space */ 274 } uhdr_gainmap_metadata_t; /**< alias for struct uhdr_gainmap_metadata */ 275 276 /**\brief ultrahdr codec context opaque descriptor */ 277 typedef struct uhdr_codec_private uhdr_codec_private_t; 278 279 // =============================================================================================== 280 // Function Declarations 281 // =============================================================================================== 282 283 // =============================================================================================== 284 // Encoder APIs 285 // =============================================================================================== 286 287 /*!\brief Create a new encoder instance. The instance is initialized with default settings. 288 * To override the settings use uhdr_enc_set_*() 289 * 290 * \return nullptr if there was an error allocating memory else a fresh opaque encoder handle 291 */ 292 UHDR_EXTERN uhdr_codec_private_t* uhdr_create_encoder(void); 293 294 /*!\brief Release encoder instance. 295 * Frees all allocated storage associated with encoder instance. 296 * 297 * \param[in] enc encoder instance. 298 * 299 * \return none 300 */ 301 UHDR_EXTERN void uhdr_release_encoder(uhdr_codec_private_t* enc); 302 303 /*!\brief Add raw image descriptor to encoder context. The function goes through all the fields of 304 * the image descriptor and checks for their sanity. If no anomalies are seen then the image is 305 * added to internal list. Repeated calls to this function will replace the old entry with the 306 * current. 307 * 308 * \param[in] enc encoder instance. 309 * \param[in] img image descriptor. 310 * \param[in] intent UHDR_HDR_IMG for hdr intent and UHDR_SDR_IMG for sdr intent. 311 * 312 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 313 * #UHDR_CODEC_INVALID_PARAM otherwise. 314 */ 315 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_raw_image(uhdr_codec_private_t* enc, 316 uhdr_raw_image_t* img, 317 uhdr_img_label_t intent); 318 319 /*!\brief Add compressed image descriptor to encoder context. The function goes through all the 320 * fields of the image descriptor and checks for their sanity. If no anomalies are seen then the 321 * image is added to internal list. Repeated calls to this function will replace the old entry with 322 * the current. 323 * 324 * If both uhdr_enc_add_raw_image() and uhdr_enc_add_compressed_image() are called during a session 325 * for the same intent, it is assumed that raw image descriptor and compressed image descriptor are 326 * relatable via compress <-> decompress process. 327 * 328 * The compressed image descriptors has fields cg, ct and range. Certain media formats are capable 329 * of storing color standard, color transfer and color range characteristics in the bitstream (for 330 * example heif, avif, ...). Other formats may not support this (jpeg, ...). These fields serve as 331 * an additional source for conveying this information. If the user is unaware of the color aspects 332 * of the image, #UHDR_CG_UNSPECIFIED, #UHDR_CT_UNSPECIFIED, #UHDR_CR_UNSPECIFIED can be used. If 333 * color aspects are present inside the bitstream and supplied via these fields both are expected to 334 * be identical. 335 * 336 * \param[in] enc encoder instance. 337 * \param[in] img image descriptor. 338 * \param[in] intent UHDR_HDR_IMG for hdr intent, 339 * UHDR_SDR_IMG for sdr intent, 340 * UHDR_BASE_IMG for base image intent 341 * 342 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 343 * #UHDR_CODEC_INVALID_PARAM otherwise. 344 */ 345 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_compressed_image(uhdr_codec_private_t* enc, 346 uhdr_compressed_image_t* img, 347 uhdr_img_label_t intent); 348 349 /*!\brief Add gain map image descriptor and gainmap metadata info that was used to generate the 350 * aforth gainmap image to encoder context. The function internally goes through all the fields of 351 * the image descriptor and checks for their sanity. If no anomalies are seen then the image is 352 * added to internal list. Repeated calls to this function will replace the old entry with the 353 * current. 354 * 355 * NOTE: There are apis that allow configuration of gainmap info separately. For instance 356 * #uhdr_enc_set_gainmap_gamma, #uhdr_enc_set_gainmap_scale_factor, ... They have no effect on the 357 * information that is configured via this api. The information configured here is treated as 358 * immutable and used as-is in encoding scenario where gainmap computations are intended to be 359 * by-passed. 360 * 361 * \param[in] enc encoder instance. 362 * \param[in] img gain map image desciptor. 363 * \param[in] metadata gainmap metadata descriptor 364 * 365 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 366 * #UHDR_CODEC_INVALID_PARAM otherwise. 367 */ 368 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_gainmap_image(uhdr_codec_private_t* enc, 369 uhdr_compressed_image_t* img, 370 uhdr_gainmap_metadata_t* metadata); 371 372 /*!\brief Set quality factor for compressing base image and/or gainmap image. Default configured 373 * quality factor of base image and gainmap image are 95 and 95 respectively. 374 * 375 * \param[in] enc encoder instance. 376 * \param[in] quality quality factor. Any integer in range [0 - 100]. 377 * \param[in] intent #UHDR_BASE_IMG for base image and #UHDR_GAIN_MAP_IMG for gain map image. 378 * 379 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 380 * #UHDR_CODEC_INVALID_PARAM otherwise. 381 */ 382 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_quality(uhdr_codec_private_t* enc, int quality, 383 uhdr_img_label_t intent); 384 385 /*!\brief Set Exif data that needs to be inserted in the output compressed stream. This function 386 * does not generate or validate exif data on its own. It merely copies the supplied information 387 * into the bitstream. 388 * 389 * \param[in] enc encoder instance. 390 * \param[in] exif exif data memory block. 391 * 392 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 393 * #UHDR_CODEC_INVALID_PARAM otherwise. 394 */ 395 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_exif_data(uhdr_codec_private_t* enc, 396 uhdr_mem_block_t* exif); 397 398 /*!\brief Enable/Disable multi-channel gainmap. By default multi-channel gainmap is enabled. 399 * 400 * \param[in] enc encoder instance. 401 * \param[in] use_multi_channel_gainmap enable/disable multichannel gain map. 402 * 0 - single-channel gainmap is enabled, 403 * otherwise - multi-channel gainmap is enabled. 404 * 405 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 406 * #UHDR_CODEC_INVALID_PARAM otherwise. 407 */ 408 UHDR_EXTERN uhdr_error_info_t 409 uhdr_enc_set_using_multi_channel_gainmap(uhdr_codec_private_t* enc, int use_multi_channel_gainmap); 410 411 /*!\brief Set gain map scaling factor. The encoding process allows signalling a downscaled gainmap 412 * image instead of full resolution. This setting controls the factor by which the renditions are 413 * downscaled. For instance, gainmap_scale_factor = 2 implies gainmap_image_width = 414 * primary_image_width / 2 and gainmap image height = primary_image_height / 2. 415 * Default gain map scaling factor is 1. 416 * NOTE: This has no effect on base image rendition. Base image is signalled in full resolution 417 * always. 418 * 419 * \param[in] enc encoder instance. 420 * \param[in] gainmap_scale_factor gain map scale factor. Any integer in range (0, 128] 421 * 422 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 423 * #UHDR_CODEC_INVALID_PARAM otherwise. 424 */ 425 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_gainmap_scale_factor(uhdr_codec_private_t* enc, 426 int gainmap_scale_factor); 427 428 /*!\brief Set encoding gamma of gainmap image. For multi-channel gainmap image, set gamma is used 429 * for gamma correction of all planes separately. Default gamma value is 1.0. 430 * 431 * \param[in] enc encoder instance. 432 * \param[in] gamma gamma of gainmap image. Any positive real number. 433 * 434 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 435 * #UHDR_CODEC_INVALID_PARAM otherwise. 436 */ 437 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_gainmap_gamma(uhdr_codec_private_t* enc, float gamma); 438 439 /*!\brief Set min max content boost. This configuration is treated as a recommendation by the 440 * library. It is entirely possible for the library to use a different set of values. Value MUST be 441 * in linear scale. 442 * 443 * \param[in] enc encoder instance. 444 * \param[in] min_boost min content boost. Any positive real number. 445 * \param[in] max_boost max content boost. Any positive real number >= min_boost. 446 * 447 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 448 * #UHDR_CODEC_INVALID_PARAM otherwise. 449 */ 450 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_min_max_content_boost(uhdr_codec_private_t* enc, 451 float min_boost, float max_boost); 452 453 /*!\brief Set target display peak brightness in nits. This is used for configuring #hdr_capacity_max 454 * of gainmap metadata. This value determines the weight by which the gain map coefficients are 455 * scaled during decode. If this is not configured, then default peak luminance of HDR intent's 456 * color transfer under test is used. For #UHDR_CT_HLG, this corresponds to 1000 nits and for 457 * #UHDR_CT_LINEAR and #UHDR_CT_PQ, this corresponds to 10000 nits. 458 * 459 * \param[in] enc encoder instance. 460 * \param[in] nits target display peak brightness in nits. Any positive real number in range 461 * [203, 10000]. 462 * 463 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 464 * #UHDR_CODEC_INVALID_PARAM otherwise. 465 */ 466 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_target_display_peak_brightness(uhdr_codec_private_t* enc, 467 float nits); 468 469 /*!\brief Set encoding preset. Tunes the encoder configurations for performance or quality. Default 470 * configuration is #UHDR_USAGE_BEST_QUALITY. 471 * 472 * \param[in] enc encoder instance. 473 * \param[in] preset encoding preset. #UHDR_USAGE_REALTIME - Tune settings for best performance 474 * #UHDR_USAGE_BEST_QUALITY - Tune settings for best quality 475 * 476 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 477 * #UHDR_CODEC_INVALID_PARAM otherwise. 478 */ 479 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_preset(uhdr_codec_private_t* enc, 480 uhdr_enc_preset_t preset); 481 482 /*!\brief Set output image compression format. Selects the compression format for encoding base 483 * image and gainmap image. Default configuration is #UHDR_CODEC_JPG 484 * 485 * \param[in] enc encoder instance. 486 * \param[in] media_type output image compression format. Supported values are #UHDR_CODEC_JPG 487 * 488 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 489 * #UHDR_CODEC_INVALID_PARAM otherwise. 490 */ 491 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_output_format(uhdr_codec_private_t* enc, 492 uhdr_codec_t media_type); 493 494 /*!\brief Encode process call 495 * After initializing the encoder context, call to this function will submit data for encoding. If 496 * the call is successful, the encoded output is stored internally and is accessible via 497 * uhdr_get_encoded_stream(). 498 * 499 * The basic usage of uhdr encoder is as follows: 500 * - The program creates an instance of an encoder using, 501 * - uhdr_create_encoder(). 502 * - The program registers input images to the encoder using, 503 * - uhdr_enc_set_raw_image(ctxt, img, UHDR_HDR_IMG) 504 * - uhdr_enc_set_raw_image(ctxt, img, UHDR_SDR_IMG) 505 * - The program overrides the default settings using uhdr_enc_set_*() functions 506 * - If the application wants to control the compression level 507 * - uhdr_enc_set_quality() 508 * - If the application wants to insert exif data 509 * - uhdr_enc_set_exif_data() 510 * - If the application wants to set gainmap scale factor 511 * - uhdr_enc_set_gainmap_scale_factor() 512 * - If the application wants to enable multi channel gain map 513 * - uhdr_enc_set_using_multi_channel_gainmap() 514 * - If the application wants to set gainmap image gamma 515 * - uhdr_enc_set_gainmap_gamma() 516 * - If the application wants to recommend min max content boost 517 * - uhdr_enc_set_min_max_content_boost() 518 * - If the application wants to set target display peak brightness 519 * - uhdr_enc_set_target_display_peak_brightness() 520 * - If the application wants to set encoding preset 521 * - uhdr_enc_set_preset() 522 * - If the application wants to control target compression format 523 * - uhdr_enc_set_output_format() 524 * - The program calls uhdr_encode() to encode data. This call would initiate the process of 525 * computing gain map from hdr intent and sdr intent. The sdr intent and gain map image are 526 * compressed at the set quality using the codec of choice. 527 * - On success, the program can access the encoded output with uhdr_get_encoded_stream(). 528 * - The program finishes the encoding with uhdr_release_encoder(). 529 * 530 * The library allows setting Hdr and/or Sdr intent in compressed format, 531 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_HDR_IMG) 532 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_SDR_IMG) 533 * In this mode, the compressed image(s) are first decoded to raw image(s). These raw image(s) go 534 * through the aforth mentioned gain map computation and encoding process. In this case, the usage 535 * shall be like this: 536 * - uhdr_create_encoder() 537 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_HDR_IMG) 538 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_SDR_IMG) 539 * - uhdr_encode() 540 * - uhdr_get_encoded_stream() 541 * - uhdr_release_encoder() 542 * If the set compressed image media type of intent UHDR_SDR_IMG and output media type are 543 * identical, then this image is directly used for primary image. No re-encode of raw image is done. 544 * This implies base image quality setting is un-used. Only gain map image is encoded at the set 545 * quality using codec of choice. On the other hand, if the set compressed image media type and 546 * output media type are different, then transcoding is done. 547 * 548 * The library also allows directly setting base and gain map image in compressed format, 549 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_BASE_IMG) 550 * - uhdr_enc_set_gainmap_image(ctxt, img, metadata) 551 * In this mode, gain map computation is by-passed. The input images are transcoded (if necessary), 552 * combined and sent back. 553 * 554 * It is possible to create a uhdr image solely from Hdr intent. In this case, the usage shall look 555 * like this: 556 * - uhdr_create_encoder() 557 * - uhdr_enc_set_raw_image(ctxt, img, UHDR_HDR_IMG) 558 * - uhdr_enc_set_quality() // optional 559 * - uhdr_enc_set_exif_data() // optional 560 * - uhdr_enc_set_output_format() // optional 561 * - uhdr_enc_set_gainmap_scale_factor() // optional 562 * - uhdr_enc_set_using_multi_channel_gainmap() // optional 563 * - uhdr_enc_set_gainmap_gamma() // optional 564 * - uhdr_enc_set_min_max_content_boost() // optional 565 * - uhdr_enc_set_target_display_peak_brightness() // optional 566 * - uhdr_encode() 567 * - uhdr_get_encoded_stream() 568 * - uhdr_release_encoder() 569 * In this mode, the Sdr rendition is created from Hdr intent by tone-mapping. The tone-mapped sdr 570 * image and hdr image go through the aforth mentioned gain map computation and encoding process to 571 * create uhdr image. 572 * 573 * In all modes, Exif data is inserted if requested. 574 * 575 * \param[in] enc encoder instance. 576 * 577 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise. 578 */ 579 UHDR_EXTERN uhdr_error_info_t uhdr_encode(uhdr_codec_private_t* enc); 580 581 /*!\brief Get encoded ultra hdr stream 582 * 583 * \param[in] enc encoder instance. 584 * 585 * \return nullptr if encode process call is unsuccessful, uhdr image descriptor otherwise 586 */ 587 UHDR_EXTERN uhdr_compressed_image_t* uhdr_get_encoded_stream(uhdr_codec_private_t* enc); 588 589 /*!\brief Reset encoder instance. 590 * Clears all previous settings and resets to default state and ready for re-initialization and 591 * usage 592 * 593 * \param[in] enc encoder instance. 594 * 595 * \return none 596 */ 597 UHDR_EXTERN void uhdr_reset_encoder(uhdr_codec_private_t* enc); 598 599 // =============================================================================================== 600 // Decoder APIs 601 // =============================================================================================== 602 603 /*!\brief check if it is a valid ultrahdr image. 604 * 605 * @param[in] data pointer to input compressed stream 606 * @param[in] size size of compressed stream 607 * 608 * @returns 1 if the input data has a primary image, gain map image and gain map metadata. 0 if any 609 * errors are encountered during parsing process or if the image does not have primary 610 * image or gainmap image or gainmap metadata 611 */ 612 UHDR_EXTERN int is_uhdr_image(void* data, int size); 613 614 /*!\brief Create a new decoder instance. The instance is initialized with default settings. 615 * To override the settings use uhdr_dec_set_*() 616 * 617 * \return nullptr if there was an error allocating memory else a fresh opaque decoder handle 618 */ 619 UHDR_EXTERN uhdr_codec_private_t* uhdr_create_decoder(void); 620 621 /*!\brief Release decoder instance. 622 * Frees all allocated storage associated with decoder instance. 623 * 624 * \param[in] dec decoder instance. 625 * 626 * \return none 627 */ 628 UHDR_EXTERN void uhdr_release_decoder(uhdr_codec_private_t* dec); 629 630 /*!\brief Add compressed image descriptor to decoder context. The function goes through all the 631 * fields of the image descriptor and checks for their sanity. If no anomalies are seen then the 632 * image is added to internal list. Repeated calls to this function will replace the old entry with 633 * the current. 634 * 635 * \param[in] dec decoder instance. 636 * \param[in] img image descriptor. 637 * 638 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 639 * #UHDR_CODEC_INVALID_PARAM otherwise. 640 */ 641 UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_image(uhdr_codec_private_t* dec, 642 uhdr_compressed_image_t* img); 643 644 /*!\brief Set output image color format 645 * 646 * \param[in] dec decoder instance. 647 * \param[in] fmt output image color format. Supported values are 648 * #UHDR_IMG_FMT_64bppRGBAHalfFloat, #UHDR_IMG_FMT_32bppRGBA1010102, 649 * #UHDR_IMG_FMT_32bppRGBA8888 650 * 651 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 652 * #UHDR_CODEC_INVALID_PARAM otherwise. 653 */ 654 UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_img_format(uhdr_codec_private_t* dec, 655 uhdr_img_fmt_t fmt); 656 657 /*!\brief Set output image color transfer characteristics. It should be noted that not all 658 * combinations of output color format and output transfer function are supported. #UHDR_CT_SRGB 659 * output color transfer shall be paired with #UHDR_IMG_FMT_32bppRGBA8888 only. #UHDR_CT_HLG, 660 * #UHDR_CT_PQ shall be paired with #UHDR_IMG_FMT_32bppRGBA1010102. #UHDR_CT_LINEAR shall be paired 661 * with #UHDR_IMG_FMT_64bppRGBAHalfFloat. 662 * 663 * \param[in] dec decoder instance. 664 * \param[in] ct output color transfer 665 * 666 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 667 * #UHDR_CODEC_INVALID_PARAM otherwise. 668 */ 669 UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_color_transfer(uhdr_codec_private_t* dec, 670 uhdr_color_transfer_t ct); 671 672 /*!\brief Set output display's HDR capacity. Value MUST be in linear scale. This value determines 673 * the weight by which the gain map coefficients are scaled. If no value is configured, no weight is 674 * applied to gainmap image. 675 * 676 * \param[in] dec decoder instance. 677 * \param[in] display_boost hdr capacity of target display. Any real number >= 1.0f 678 * 679 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 680 * #UHDR_CODEC_INVALID_PARAM otherwise. 681 */ 682 UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_max_display_boost(uhdr_codec_private_t* dec, 683 float display_boost); 684 685 /*!\brief This function parses the bitstream that is registered with the decoder context and makes 686 * image information available to the client via uhdr_dec_get_() functions. It does not decompress 687 * the image. That is done by uhdr_decode(). 688 * 689 * \param[in] dec decoder instance. 690 * 691 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise. 692 */ 693 UHDR_EXTERN uhdr_error_info_t uhdr_dec_probe(uhdr_codec_private_t* dec); 694 695 /*!\brief Get base image width 696 * 697 * \param[in] dec decoder instance. 698 * 699 * \return -1 if probe call is unsuccessful, base image width otherwise 700 */ 701 UHDR_EXTERN int uhdr_dec_get_image_width(uhdr_codec_private_t* dec); 702 703 /*!\brief Get base image height 704 * 705 * \param[in] dec decoder instance. 706 * 707 * \return -1 if probe call is unsuccessful, base image height otherwise 708 */ 709 UHDR_EXTERN int uhdr_dec_get_image_height(uhdr_codec_private_t* dec); 710 711 /*!\brief Get gainmap image width 712 * 713 * \param[in] dec decoder instance. 714 * 715 * \return -1 if probe call is unsuccessful, gain map image width otherwise 716 */ 717 UHDR_EXTERN int uhdr_dec_get_gainmap_width(uhdr_codec_private_t* dec); 718 719 /*!\brief Get gainmap image height 720 * 721 * \param[in] dec decoder instance. 722 * 723 * \return -1 if probe call is unsuccessful, gain map image height otherwise 724 */ 725 UHDR_EXTERN int uhdr_dec_get_gainmap_height(uhdr_codec_private_t* dec); 726 727 /*!\brief Get exif information 728 * 729 * \param[in] dec decoder instance. 730 * 731 * \return nullptr if probe call is unsuccessful, memory block with exif data otherwise 732 */ 733 UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_exif(uhdr_codec_private_t* dec); 734 735 /*!\brief Get icc information 736 * 737 * \param[in] dec decoder instance. 738 * 739 * \return nullptr if probe call is unsuccessful, memory block with icc data otherwise 740 */ 741 UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_icc(uhdr_codec_private_t* dec); 742 743 /*!\brief Get base image (compressed) 744 * 745 * \param[in] dec decoder instance. 746 * 747 * \return nullptr if probe process call is unsuccessful, memory block with base image data 748 * otherwise 749 */ 750 UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_base_image(uhdr_codec_private_t* dec); 751 752 /*!\brief Get gain map image (compressed) 753 * 754 * \param[in] dec decoder instance. 755 * 756 * \return nullptr if probe process call is unsuccessful, memory block with gainmap image data 757 * otherwise 758 */ 759 UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_gainmap_image(uhdr_codec_private_t* dec); 760 761 /*!\brief Get gain map metadata 762 * 763 * \param[in] dec decoder instance. 764 * 765 * \return nullptr if probe process call is unsuccessful, gainmap metadata descriptor otherwise 766 */ 767 UHDR_EXTERN uhdr_gainmap_metadata_t* uhdr_dec_get_gainmap_metadata(uhdr_codec_private_t* dec); 768 769 /*!\brief Decode process call 770 * After initializing the decoder context, call to this function will submit data for decoding. If 771 * the call is successful, the decoded output is stored internally and is accessible via 772 * uhdr_get_decoded_image(). 773 * 774 * The basic usage of uhdr decoder is as follows: 775 * - The program creates an instance of a decoder using, 776 * - uhdr_create_decoder(). 777 * - The program registers input images to the decoder using, 778 * - uhdr_dec_set_image(ctxt, img) 779 * - The program overrides the default settings using uhdr_dec_set_*() functions. 780 * - If the application wants to control the output image format, 781 * - uhdr_dec_set_out_img_format() 782 * - If the application wants to control the output transfer characteristics, 783 * - uhdr_dec_set_out_color_transfer() 784 * - If the application wants to control the output display boost, 785 * - uhdr_dec_set_out_max_display_boost() 786 * - If the application wants to enable/disable gpu acceleration, 787 * - uhdr_enable_gpu_acceleration() 788 * - The program calls uhdr_decode() to decode uhdr stream. This call would initiate the process 789 * of decoding base image and gain map image. These two are combined to give the final rendition 790 * image. 791 * - The program can access the decoded output with uhdr_get_decoded_image(). 792 * - The program finishes the decoding with uhdr_release_decoder(). 793 * 794 * \param[in] dec decoder instance. 795 * 796 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise. 797 */ 798 UHDR_EXTERN uhdr_error_info_t uhdr_decode(uhdr_codec_private_t* dec); 799 800 /*!\brief Get final rendition image 801 * 802 * \param[in] dec decoder instance. 803 * 804 * \return nullptr if decoded process call is unsuccessful, raw image descriptor otherwise 805 */ 806 UHDR_EXTERN uhdr_raw_image_t* uhdr_get_decoded_image(uhdr_codec_private_t* dec); 807 808 /*!\brief Get gain map image 809 * 810 * \param[in] dec decoder instance. 811 * 812 * \return nullptr if decoded process call is unsuccessful, raw image descriptor otherwise 813 */ 814 UHDR_EXTERN uhdr_raw_image_t* uhdr_get_decoded_gainmap_image(uhdr_codec_private_t* dec); 815 816 /*!\brief Reset decoder instance. 817 * Clears all previous settings and resets to default state and ready for re-initialization and 818 * usage 819 * 820 * \param[in] dec decoder instance. 821 * 822 * \return none 823 */ 824 UHDR_EXTERN void uhdr_reset_decoder(uhdr_codec_private_t* dec); 825 826 // =============================================================================================== 827 // Common APIs 828 // =============================================================================================== 829 830 /*!\brief Enable/Disable GPU acceleration. 831 * If enabled, certain operations (if possible) of uhdr encode/decode will be offloaded to GPU. 832 * NOTE: It is entirely possible for this API to have no effect on the encode/decode operation 833 * 834 * \param[in] codec codec instance. 835 * \param[in] enable enable enable/disbale gpu acceleration 836 * 837 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM 838 * otherwise. 839 */ 840 UHDR_EXTERN uhdr_error_info_t uhdr_enable_gpu_acceleration(uhdr_codec_private_t* codec, int enable); 841 842 /*!\brief Add image editing operations (pre-encode or post-decode). 843 * Below functions list the set of edits supported. Program can set any combination of these during 844 * initialization. Once the encode/decode process call is made, before encoding or after decoding 845 * the edits are applied in the order of configuration. 846 */ 847 848 /*!\brief Add mirror effect 849 * 850 * \param[in] codec codec instance. 851 * \param[in] direction mirror directions. #UHDR_MIRROR_VERTICAL for vertical mirroring 852 * #UHDR_MIRROR_HORIZONTAL for horizontal mirroing 853 * 854 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM 855 * otherwise. 856 */ 857 UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_mirror(uhdr_codec_private_t* codec, 858 uhdr_mirror_direction_t direction); 859 860 /*!\brief Add rotate effect 861 * 862 * \param[in] codec codec instance. 863 * \param[in] degrees clockwise degrees. 90 - rotate clockwise by 90 degrees 864 * 180 - rotate clockwise by 180 degrees 865 * 270 - rotate clockwise by 270 degrees 866 * 867 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM 868 * otherwise. 869 */ 870 UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_rotate(uhdr_codec_private_t* codec, int degrees); 871 872 /*!\brief Add crop effect 873 * 874 * \param[in] codec codec instance. 875 * \param[in] left crop coordinate left in pixels. 876 * \param[in] right crop coordinate right in pixels. 877 * \param[in] top crop coordinate top in pixels. 878 * \param[in] bottom crop coordinate bottom in pixels. 879 * 880 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM 881 * otherwise. 882 */ 883 UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_crop(uhdr_codec_private_t* codec, int left, int right, 884 int top, int bottom); 885 886 /*!\brief Add resize effect 887 * 888 * \param[in] codec codec instance. 889 * \param[in] width target width. 890 * \param[in] height target height. 891 * 892 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM 893 * otherwise. 894 */ 895 UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_resize(uhdr_codec_private_t* codec, int width, 896 int height); 897 898 #endif // ULTRAHDR_API_H 899