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