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 #if defined(_WIN32) || defined(__CYGWIN__) 27 #if defined(UHDR_BUILDING_SHARED_LIBRARY) 28 #define UHDR_API __declspec(dllexport) 29 #elif defined(UHDR_USING_SHARED_LIBRARY) 30 #define UHDR_API __declspec(dllimport) 31 #else 32 #define UHDR_API 33 #endif 34 #elif defined(__GNUC__) && (__GNUC__ >= 4) && \ 35 (defined(UHDR_BUILDING_SHARED_LIBRARY) || defined(UHDR_USING_SHARED_LIBRARY)) 36 #define UHDR_API __attribute__((visibility("default"))) 37 #else 38 #define UHDR_API 39 #endif 40 41 #ifdef __cplusplus 42 #define UHDR_EXTERN extern "C" UHDR_API 43 #else 44 #define UHDR_EXTERN extern UHDR_API 45 #endif 46 47 // =============================================================================================== 48 // Enum Definitions 49 // =============================================================================================== 50 51 /*!\brief List of supported image formats */ 52 typedef enum uhdr_img_fmt { 53 UHDR_IMG_FMT_UNSPECIFIED = -1, /**< Unspecified */ 54 UHDR_IMG_FMT_24bppYCbCrP010 = 0, /**< 10-bit-per component 4:2:0 YCbCr semiplanar format. 55 Each chroma and luma component has 16 allocated bits in 56 little-endian configuration with 10 MSB of actual data.*/ 57 UHDR_IMG_FMT_12bppYCbCr420 = 1, /**< 8-bit-per component 4:2:0 YCbCr planar format */ 58 UHDR_IMG_FMT_8bppYCbCr400 = 2, /**< 8-bit-per component Monochrome format */ 59 UHDR_IMG_FMT_32bppRGBA8888 = 60 3, /**< 32 bits per pixel RGBA color format, with 8-bit red, green, blue 61 and alpha components. Using 32-bit little-endian representation, 62 colors stored as Red 7:0, Green 15:8, Blue 23:16, Alpha 31:24. */ 63 UHDR_IMG_FMT_64bppRGBAHalfFloat = 4, /**< 64 bits per pixel RGBA color format, with 16-bit signed 64 floating point red, green, blue, and alpha components */ 65 UHDR_IMG_FMT_32bppRGBA1010102 = 5, /**< 32 bits per pixel RGBA color format, with 10-bit red, 66 green, blue, and 2-bit alpha components. Using 32-bit 67 little-endian representation, colors stored as Red 9:0, Green 68 19:10, Blue 29:20, and Alpha 31:30. */ 69 70 UHDR_IMG_FMT_24bppYCbCr444 = 6, /**< 8-bit-per component 4:4:4 YCbCr planar format */ 71 UHDR_IMG_FMT_16bppYCbCr422 = 7, /**< 8-bit-per component 4:2:2 YCbCr planar format */ 72 UHDR_IMG_FMT_16bppYCbCr440 = 8, /**< 8-bit-per component 4:4:0 YCbCr planar format */ 73 UHDR_IMG_FMT_12bppYCbCr411 = 9, /**< 8-bit-per component 4:1:1 YCbCr planar format */ 74 UHDR_IMG_FMT_10bppYCbCr410 = 10, /**< 8-bit-per component 4:1:0 YCbCr planar format */ 75 UHDR_IMG_FMT_24bppRGB888 = 11, /**< 8-bit-per component RGB interleaved format */ 76 } uhdr_img_fmt_t; /**< alias for enum uhdr_img_fmt */ 77 78 /*!\brief List of supported color gamuts */ 79 typedef enum uhdr_color_gamut { 80 UHDR_CG_UNSPECIFIED = -1, /**< Unspecified */ 81 UHDR_CG_BT_709 = 0, /**< BT.709 */ 82 UHDR_CG_DISPLAY_P3 = 1, /**< Display P3 */ 83 UHDR_CG_BT_2100 = 2, /**< BT.2100 */ 84 } uhdr_color_gamut_t; /**< alias for enum uhdr_color_gamut */ 85 86 /*!\brief List of supported color transfers */ 87 typedef enum uhdr_color_transfer { 88 UHDR_CT_UNSPECIFIED = -1, /**< Unspecified */ 89 UHDR_CT_LINEAR = 0, /**< Linear */ 90 UHDR_CT_HLG = 1, /**< Hybrid log gamma */ 91 UHDR_CT_PQ = 2, /**< Perceptual Quantizer */ 92 UHDR_CT_SRGB = 3, /**< Gamma */ 93 } uhdr_color_transfer_t; /**< alias for enum uhdr_color_transfer */ 94 95 /*!\brief List of supported color ranges */ 96 typedef enum uhdr_color_range { 97 UHDR_CR_UNSPECIFIED = -1, /**< Unspecified */ 98 UHDR_CR_LIMITED_RANGE = 0, /**< Y {[16..235], UV [16..240]} * pow(2, (bpc - 8)) */ 99 UHDR_CR_FULL_RANGE = 1, /**< YUV/RGB {[0..255]} * pow(2, (bpc - 8)) */ 100 } uhdr_color_range_t; /**< alias for enum uhdr_color_range */ 101 102 /*!\brief List of supported codecs */ 103 typedef enum uhdr_codec { 104 UHDR_CODEC_JPG, /**< Compress {Hdr, Sdr rendition} to an {Sdr rendition + Gain Map} using 105 jpeg */ 106 } uhdr_codec_t; /**< alias for enum uhdr_codec */ 107 108 /*!\brief Image identifiers in gain map technology */ 109 typedef enum uhdr_img_label { 110 UHDR_HDR_IMG, /**< Hdr rendition image */ 111 UHDR_SDR_IMG, /**< Sdr rendition image */ 112 UHDR_BASE_IMG, /**< Base rendition image */ 113 UHDR_GAIN_MAP_IMG, /**< Gain map image */ 114 } uhdr_img_label_t; /**< alias for enum uhdr_img_label */ 115 116 /*!\brief Algorithm return codes */ 117 typedef enum uhdr_codec_err { 118 119 /*!\brief Operation completed without error */ 120 UHDR_CODEC_OK, 121 122 /*!\brief Unspecified error */ 123 UHDR_CODEC_UNKNOWN_ERROR, 124 125 /*!\brief An application-supplied parameter is not valid. */ 126 UHDR_CODEC_INVALID_PARAM, 127 128 /*!\brief Memory operation failed */ 129 UHDR_CODEC_MEM_ERROR, 130 131 /*!\brief An application-invoked operation is not valid. */ 132 UHDR_CODEC_INVALID_OPERATION, 133 134 /*!\brief The library does not implement a feature required for the operation */ 135 UHDR_CODEC_UNSUPPORTED_FEATURE, 136 137 /*!\brief An iterator reached the end of list. */ 138 UHDR_CODEC_LIST_END, 139 140 } uhdr_codec_err_t; /**< alias for enum uhdr_codec_err */ 141 142 // =============================================================================================== 143 // Structure Definitions 144 // =============================================================================================== 145 146 /*!\brief Detailed return status */ 147 typedef struct uhdr_error_info { 148 uhdr_codec_err_t error_code; 149 int has_detail; 150 char detail[256]; 151 } uhdr_error_info_t; /**< alias for struct uhdr_error_info */ 152 153 /**\brief Raw Image Descriptor */ 154 typedef struct uhdr_raw_image { 155 /* Color model, primaries, transfer, range */ 156 uhdr_img_fmt_t fmt; /**< Image Format */ 157 uhdr_color_gamut_t cg; /**< Color Gamut */ 158 uhdr_color_transfer_t ct; /**< Color Transfer */ 159 uhdr_color_range_t range; /**< Color Range */ 160 161 /* Image storage dimensions */ 162 unsigned int w; /**< Stored image width */ 163 unsigned int h; /**< Stored image height */ 164 165 /* Image data pointers. */ 166 #define UHDR_PLANE_PACKED 0 /**< To be used for all packed formats */ 167 #define UHDR_PLANE_Y 0 /**< Y (Luminance) plane */ 168 #define UHDR_PLANE_U 1 /**< U (Chroma) plane */ 169 #define UHDR_PLANE_UV 1 /**< UV (Chroma plane interleaved) To be used for semi planar format */ 170 #define UHDR_PLANE_V 2 /**< V (Chroma) plane */ 171 void* planes[3]; /**< pointer to the top left pixel for each plane */ 172 unsigned int stride[3]; /**< stride in pixels between rows for each plane */ 173 } uhdr_raw_image_t; /**< alias for struct uhdr_raw_image */ 174 175 /**\brief Compressed Image Descriptor */ 176 typedef struct uhdr_compressed_image { 177 void* data; /**< Pointer to a block of data to decode */ 178 unsigned int data_sz; /**< size of the data buffer */ 179 unsigned int capacity; /**< maximum size of the data buffer */ 180 uhdr_color_gamut_t cg; /**< Color Gamut */ 181 uhdr_color_transfer_t ct; /**< Color Transfer */ 182 uhdr_color_range_t range; /**< Color Range */ 183 } uhdr_compressed_image_t; /**< alias for struct uhdr_compressed_image */ 184 185 /**\brief Buffer Descriptor */ 186 typedef struct uhdr_mem_block { 187 void* data; /**< Pointer to a block of data to decode */ 188 unsigned int data_sz; /**< size of the data buffer */ 189 unsigned int capacity; /**< maximum size of the data buffer */ 190 } uhdr_mem_block_t; /**< alias for struct uhdr_mem_block */ 191 192 /**\brief Gain map metadata. 193 * Note: all values stored in linear space. This differs from the metadata encoded in XMP, where 194 * max_content_boost (aka gainMapMax), min_content_boost (aka gainMapMin), hdr_capacity_min, and 195 * hdr_capacity_max are stored in log2 space. 196 */ 197 typedef struct uhdr_gainmap_metadata { 198 float max_content_boost; /**< Max Content Boost for the map */ 199 float min_content_boost; /**< Min Content Boost for the map */ 200 float gamma; /**< Gamma of the map data */ 201 float offset_sdr; /**< Offset for SDR data in map calculations */ 202 float offset_hdr; /**< Offset for HDR data in map calculations */ 203 float hdr_capacity_min; /**< Min HDR capacity values for interpolating the Gain Map */ 204 float hdr_capacity_max; /**< Max HDR capacity value for interpolating the Gain Map */ 205 } uhdr_gainmap_metadata_t; /**< alias for struct uhdr_gainmap_metadata */ 206 207 /**\brief ultrahdr codec context opaque descriptor */ 208 typedef struct uhdr_codec_private uhdr_codec_private_t; 209 210 // =============================================================================================== 211 // Function Declarations 212 // =============================================================================================== 213 214 // =============================================================================================== 215 // Encoder APIs 216 // =============================================================================================== 217 218 /*!\brief Create a new encoder instance. The instance is initialized with default settings. 219 * To override the settings use uhdr_enc_set_*() 220 * 221 * \return nullptr if there was an error allocating memory else a fresh opaque encoder handle 222 */ 223 UHDR_EXTERN uhdr_codec_private_t* uhdr_create_encoder(void); 224 225 /*!\brief Release encoder instance. 226 * Frees all allocated storage associated with encoder instance. 227 * 228 * \param[in] enc encoder instance. 229 * 230 * \return none 231 */ 232 UHDR_EXTERN void uhdr_release_encoder(uhdr_codec_private_t* enc); 233 234 /*!\brief Add raw image descriptor to encoder context. The function goes through all the fields of 235 * the image descriptor and checks for their sanity. If no anomalies are seen then the image is 236 * added to internal list. Repeated calls to this function will replace the old entry with the 237 * current. 238 * 239 * \param[in] enc encoder instance. 240 * \param[in] img image descriptor. 241 * \param[in] intent UHDR_HDR_IMG for hdr intent and UHDR_SDR_IMG for sdr intent. 242 * 243 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 244 * #UHDR_CODEC_INVALID_PARAM otherwise. 245 */ 246 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_raw_image(uhdr_codec_private_t* enc, 247 uhdr_raw_image_t* img, 248 uhdr_img_label_t intent); 249 250 /*!\brief Add compressed image descriptor to encoder context. The function goes through all the 251 * fields of the image descriptor and checks for their sanity. If no anomalies are seen then the 252 * image is added to internal list. Repeated calls to this function will replace the old entry with 253 * the current. 254 * 255 * If both uhdr_enc_add_raw_image() and uhdr_enc_add_compressed_image() are called during a session 256 * for the same intent, it is assumed that raw image descriptor and compressed image descriptor are 257 * relatable via compress <-> decompress process. 258 * 259 * \param[in] enc encoder instance. 260 * \param[in] img image descriptor. 261 * \param[in] intent UHDR_HDR_IMG for hdr intent, 262 * UHDR_SDR_IMG for sdr intent, 263 * UHDR_BASE_IMG for base image intent 264 * 265 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 266 * #UHDR_CODEC_INVALID_PARAM otherwise. 267 */ 268 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_compressed_image(uhdr_codec_private_t* enc, 269 uhdr_compressed_image_t* img, 270 uhdr_img_label_t intent); 271 272 /*!\brief Add gain map image descriptor and gainmap metadata info to encoder context. The function 273 * internally goes through all the fields of the image descriptor and checks for their sanity. If no 274 * anomalies are seen then the image is added to internal list. Repeated calls to this function will 275 * replace the old entry with the current. 276 * 277 * \param[in] enc encoder instance. 278 * \param[in] img gain map image desciptor. 279 * \param[in] metadata gainmap metadata descriptor 280 * 281 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 282 * #UHDR_CODEC_INVALID_PARAM otherwise. 283 */ 284 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_gainmap_image(uhdr_codec_private_t* enc, 285 uhdr_compressed_image_t* img, 286 uhdr_gainmap_metadata_t* metadata); 287 288 /*!\brief Set quality for compression 289 * 290 * \param[in] enc encoder instance. 291 * \param[in] quality quality factor. 292 * \param[in] intent UHDR_BASE_IMG for base image and UHDR_GAIN_MAP_IMG for gain map image. 293 * 294 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 295 * #UHDR_CODEC_INVALID_PARAM otherwise. 296 */ 297 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_quality(uhdr_codec_private_t* enc, int quality, 298 uhdr_img_label_t intent); 299 300 /*!\brief Set Exif data that needs to be inserted in the output compressed stream 301 * 302 * \param[in] enc encoder instance. 303 * \param[in] img exif data descriptor. 304 * 305 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 306 * #UHDR_CODEC_INVALID_PARAM otherwise. 307 */ 308 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_exif_data(uhdr_codec_private_t* enc, 309 uhdr_mem_block_t* exif); 310 311 /*!\brief Set output image compression format. 312 * 313 * \param[in] enc encoder instance. 314 * \param[in] media_type output image compression format. 315 * 316 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 317 * #UHDR_CODEC_INVALID_PARAM otherwise. 318 */ 319 UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_output_format(uhdr_codec_private_t* enc, 320 uhdr_codec_t media_type); 321 322 /*!\brief Encode process call 323 * After initializing the encoder context, call to this function will submit data for encoding. If 324 * the call is successful, the encoded output is stored internally and is accessible via 325 * uhdr_get_encoded_stream(). 326 * 327 * The basic usage of uhdr encoder is as follows: 328 * - The program creates an instance of an encoder using, 329 * - uhdr_create_encoder(). 330 * - The program registers input images to the encoder using, 331 * - uhdr_enc_set_raw_image(ctxt, img, UHDR_HDR_IMG) 332 * - uhdr_enc_set_raw_image(ctxt, img, UHDR_SDR_IMG) 333 * - The program overrides the default settings using uhdr_enc_set_*() functions 334 * - If the application wants to control the compression level 335 * - uhdr_enc_set_quality() 336 * - If the application wants to insert exif data 337 * - uhdr_enc_set_exif_data() 338 * - If the application wants to control target compression format 339 * - uhdr_enc_set_output_format() 340 * - The program calls uhdr_encode() to encode data. This call would initiate the process of 341 * computing gain map from hdr intent and sdr intent. The sdr intent and gain map image are 342 * compressed at the set quality using the codec of choice. 343 * - On success, the program can access the encoded output with uhdr_get_encoded_stream(). 344 * - The program finishes the encoding with uhdr_release_encoder(). 345 * 346 * The library allows setting Hdr and/or Sdr intent in compressed format, 347 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_HDR_IMG) 348 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_SDR_IMG) 349 * In this mode, the compressed image(s) are first decoded to raw image(s). These raw image(s) go 350 * through the aforth mentioned gain map computation and encoding process. In this case, the usage 351 * shall be like this: 352 * - uhdr_create_encoder() 353 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_HDR_IMG) 354 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_SDR_IMG) 355 * - uhdr_encode() 356 * - uhdr_get_encoded_stream() 357 * - uhdr_release_encoder() 358 * If the set compressed image media type of intent UHDR_SDR_IMG and output media type are 359 * identical, then this image is directly used for primary image. No re-encode of raw image is done. 360 * This implies base image quality setting is un-used. Only gain map image is encoded at the set 361 * quality using codec of choice. On the other hand, if the set compressed image media type and 362 * output media type are different, then transcoding is done. 363 * 364 * The library also allows directly setting base and gain map image in compressed format, 365 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_BASE_IMG) 366 * - uhdr_enc_set_gainmap_image(ctxt, img, metadata) 367 * In this mode, gain map computation is by-passed. The input images are transcoded (if necessary), 368 * combined and sent back. 369 * 370 * It is possible to create a uhdr image solely from Hdr intent. In this case, the usage shall look 371 * like this: 372 * - uhdr_create_encoder() 373 * - uhdr_enc_set_raw_image(ctxt, img, UHDR_HDR_IMG) 374 * - uhdr_enc_set_quality() // optional 375 * - uhdr_enc_set_exif_data() // optional 376 * - uhdr_enc_set_output_format() // optional 377 * - uhdr_encode() 378 * - uhdr_get_encoded_stream() 379 * - uhdr_release_encoder() 380 * In this mode, the Sdr rendition is created from Hdr intent by tone-mapping. The tone-mapped sdr 381 * image and hdr image go through the aforth mentioned gain map computation and encoding process to 382 * create uhdr image. 383 * 384 * In all modes, Exif data is inserted if requested. 385 * 386 * \param[in] enc encoder instance. 387 * 388 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise. 389 */ 390 UHDR_EXTERN uhdr_error_info_t uhdr_encode(uhdr_codec_private_t* enc); 391 392 /*!\brief Get encoded ultra hdr stream 393 * 394 * \param[in] enc encoder instance. 395 * 396 * \return nullptr if encode process call is unsuccessful, uhdr image descriptor otherwise 397 */ 398 UHDR_EXTERN uhdr_compressed_image_t* uhdr_get_encoded_stream(uhdr_codec_private_t* enc); 399 400 /*!\brief Reset encoder instance. 401 * Clears all previous settings and resets to default state and ready for re-initialization 402 * 403 * \param[in] enc encoder instance. 404 * 405 * \return none 406 */ 407 UHDR_EXTERN void uhdr_reset_encoder(uhdr_codec_private_t* enc); 408 409 // =============================================================================================== 410 // Decoder APIs 411 // =============================================================================================== 412 413 /*!\brief check if it is a valid ultrahdr image. 414 * 415 * @param[in] data pointer to input compressed stream 416 * @param[in] size size of compressed stream 417 * 418 * @returns 1 if the input data has a primary image, gain map image and gain map metadata. 0 419 * otherwise. 420 */ 421 UHDR_EXTERN int is_uhdr_image(void* data, int size); 422 423 /*!\brief Create a new decoder instance. The instance is initialized with default settings. 424 * To override the settings use uhdr_dec_set_*() 425 * 426 * \return nullptr if there was an error allocating memory else a fresh opaque decoder handle 427 */ 428 UHDR_EXTERN uhdr_codec_private_t* uhdr_create_decoder(void); 429 430 /*!\brief Release decoder instance. 431 * Frees all allocated storage associated with decoder instance. 432 * 433 * \param[in] dec decoder instance. 434 * 435 * \return none 436 */ 437 UHDR_EXTERN void uhdr_release_decoder(uhdr_codec_private_t* dec); 438 439 /*!\brief Add compressed image descriptor to decoder context. The function goes through all the 440 * fields of the image descriptor and checks for their sanity. If no anomalies are seen then the 441 * image is added to internal list. Repeated calls to this function will replace the old entry with 442 * the current. 443 * 444 * \param[in] dec decoder instance. 445 * \param[in] img image descriptor. 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_dec_set_image(uhdr_codec_private_t* dec, 451 uhdr_compressed_image_t* img); 452 453 /*!\brief Set output image format 454 * 455 * \param[in] dec decoder instance. 456 * \param[in] fmt output image format. 457 * 458 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 459 * #UHDR_CODEC_INVALID_PARAM otherwise. 460 */ 461 UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_img_format(uhdr_codec_private_t* dec, 462 uhdr_img_fmt_t fmt); 463 464 /*!\brief Set output color transfer 465 * 466 * \param[in] dec decoder instance. 467 * \param[in] ct output color transfer 468 * 469 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 470 * #UHDR_CODEC_INVALID_PARAM otherwise. 471 */ 472 UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_color_transfer(uhdr_codec_private_t* dec, 473 uhdr_color_transfer_t ct); 474 475 /*!\brief Set output max display boost 476 * 477 * \param[in] dec decoder instance. 478 * \param[in] display_boost max display boost 479 * 480 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, 481 * #UHDR_CODEC_INVALID_PARAM otherwise. 482 */ 483 UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_max_display_boost(uhdr_codec_private_t* dec, 484 float display_boost); 485 486 /*!\brief This function parses the bitstream that is registered with the decoder context and makes 487 * image information available to the client via uhdr_dec_get_() functions. It does not decompress 488 * the image. That is done by uhdr_decode(). 489 * 490 * \param[in] dec decoder instance. 491 * 492 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise. 493 */ 494 UHDR_EXTERN uhdr_error_info_t uhdr_dec_probe(uhdr_codec_private_t* dec); 495 496 /*!\brief Get base image width 497 * 498 * \param[in] dec decoder instance. 499 * 500 * \return -1 if probe call is unsuccessful, base image width otherwise 501 */ 502 UHDR_EXTERN int uhdr_dec_get_image_width(uhdr_codec_private_t* dec); 503 504 /*!\brief Get base image height 505 * 506 * \param[in] dec decoder instance. 507 * 508 * \return -1 if probe call is unsuccessful, base image height otherwise 509 */ 510 UHDR_EXTERN int uhdr_dec_get_image_height(uhdr_codec_private_t* dec); 511 512 /*!\brief Get gainmap image width 513 * 514 * \param[in] dec decoder instance. 515 * 516 * \return -1 if probe call is unsuccessful, gain map image width otherwise 517 */ 518 UHDR_EXTERN int uhdr_dec_get_gainmap_width(uhdr_codec_private_t* dec); 519 520 /*!\brief Get gainmap image height 521 * 522 * \param[in] dec decoder instance. 523 * 524 * \return -1 if probe call is unsuccessful, gain map image height otherwise 525 */ 526 UHDR_EXTERN int uhdr_dec_get_gainmap_height(uhdr_codec_private_t* dec); 527 528 /*!\brief Get exif information 529 * 530 * \param[in] dec decoder instance. 531 * 532 * \return nullptr if probe call is unsuccessful, memory block with exif data otherwise 533 */ 534 UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_exif(uhdr_codec_private_t* dec); 535 536 /*!\brief Get icc information 537 * 538 * \param[in] dec decoder instance. 539 * 540 * \return nullptr if probe call is unsuccessful, memory block with icc data otherwise 541 */ 542 UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_icc(uhdr_codec_private_t* dec); 543 544 /*!\brief Get gain map metadata 545 * 546 * \param[in] dec decoder instance. 547 * 548 * \return nullptr if probe process call is unsuccessful, gainmap metadata descriptor otherwise 549 */ 550 UHDR_EXTERN uhdr_gainmap_metadata_t* uhdr_dec_get_gain_map_metadata(uhdr_codec_private_t* dec); 551 552 /*!\brief Decode process call 553 * After initializing the decoder context, call to this function will submit data for decoding. If 554 * the call is successful, the decoded output is stored internally and is accessible via 555 * uhdr_get_decoded_image(). 556 * 557 * The basic usage of uhdr decoder is as follows: 558 * - The program creates an instance of a decoder using, 559 * - uhdr_create_decoder(). 560 * - The program registers input images to the decoder using, 561 * - uhdr_dec_set_image(ctxt, img) 562 * - The program overrides the default settings using uhdr_dec_set_*() functions. 563 * - If the application wants to control the output image format, 564 * - uhdr_dec_set_out_img_format() 565 * - If the application wants to control the output transfer characteristics, 566 * - uhdr_dec_set_out_color_transfer() 567 * - If the application wants to control the output display boost, 568 * - uhdr_dec_set_out_max_display_boost() 569 * - The program calls uhdr_decode() to decode uhdr stream. This call would initiate the process 570 * of decoding base image and gain map image. These two are combined to give the final rendition 571 * image. 572 * - The program can access the decoded output with uhdr_get_decoded_image(). 573 * - The program finishes the decoding with uhdr_release_decoder(). 574 * 575 * \param[in] dec decoder 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_decode(uhdr_codec_private_t* dec); 580 581 /*!\brief Get final rendition image 582 * 583 * \param[in] dec decoder instance. 584 * 585 * \return nullptr if decoded process call is unsuccessful, raw image descriptor otherwise 586 */ 587 UHDR_EXTERN uhdr_raw_image_t* uhdr_get_decoded_image(uhdr_codec_private_t* dec); 588 589 /*!\brief Get gain map image 590 * 591 * \param[in] dec decoder instance. 592 * 593 * \return nullptr if decoded process call is unsuccessful, raw image descriptor otherwise 594 */ 595 UHDR_EXTERN uhdr_raw_image_t* uhdr_get_gain_map_image(uhdr_codec_private_t* dec); 596 597 /*!\brief Reset decoder instance. 598 * Clears all previous settings and resets to default state and ready for re-initialization 599 * 600 * \param[in] dec decoder instance. 601 * 602 * \return none 603 */ 604 UHDR_EXTERN void uhdr_reset_decoder(uhdr_codec_private_t* dec); 605 606 #endif // ULTRAHDR_API_H 607