ultrahdr_api.h

/*
 * Copyright 2024 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/** \file ultrahdr_api.h
 *
 *  \brief
 *  Describes the encoder or decoder algorithm interface to applications.
 */

#ifndef ULTRAHDR_API_H
#define ULTRAHDR_API_H

#include <stddef.h>

#if defined(_WIN32) || defined(__CYGWIN__)
#if defined(UHDR_BUILDING_SHARED_LIBRARY)
#define UHDR_API __declspec(dllexport)
#elif defined(UHDR_USING_SHARED_LIBRARY)
#define UHDR_API __declspec(dllimport)
#else
#define UHDR_API
#endif
#elif defined(__GNUC__) && (__GNUC__ >= 4) && \
    (defined(UHDR_BUILDING_SHARED_LIBRARY) || defined(UHDR_USING_SHARED_LIBRARY))
#define UHDR_API __attribute__((visibility("default")))
#else
#define UHDR_API
#endif

#ifdef __cplusplus
#define UHDR_EXTERN extern "C" UHDR_API
#else
#define UHDR_EXTERN extern UHDR_API
#endif

/*
 * A Note on version numbering:
 * Over the course of development multiple changes were made to the interface that are not entirely
 * backward compatible. Some APIs were renamed for consistency and better readability. New APIs were
 * introduced to allow configuration of encoding/decoding parameters. As per convention, breaking
 * backward compatibility MUST be indicated with a major version update, introducing new APIs /
 * features MUST be indicated with a minor version update and bug fixes MUST be indicated with a
 * patch version update. This convention however, is not followed. Below table summarizes these
 * details:
 *
 * source version    ultrahdr_api.h                 Details
 *                   version string
 * --------------    --------------              -------------
 *   1.0.0           Not available               This version did not have a public API. Apps,
 *                                               directly included the project header files.
 *   1.1.0           Not available               ultrahdr_api.h is introduced in this release. The
 *                                               API header file did not advertise any version
 *                                               string.
 *   1.1.1           Not available               The API header file did not advertise any version
 *                                               string. Some bug fixes and introduced one new API
 *                                               which warrants a minor version update. But
 *                                               indicated as a patch update.
 *   1.2.0           1.2.0                       Some bug fixes, introduced new API and renamed
 *                                               existing API which warrants a major version update.
 *                                               But indicated as a minor update.
 *   1.3.0           1.3.0                       Some bug fixes, introduced new API.
 */

// This needs to be kept in sync with version in CMakeLists.txt
#define UHDR_LIB_VER_MAJOR 1
#define UHDR_LIB_VER_MINOR 3
#define UHDR_LIB_VER_PATCH 0

#define UHDR_LIB_VERSION \
  ((UHDR_LIB_VER_MAJOR * 10000) + (UHDR_LIB_VER_MINOR * 100) + UHDR_LIB_VER_PATCH)

#define XSTR(s) STR(s)
#define STR(s) #s
#define UHDR_LIB_VERSION_STR \
  XSTR(UHDR_LIB_VER_MAJOR) "." XSTR(UHDR_LIB_VER_MINOR) "." XSTR(UHDR_LIB_VER_PATCH)

// ===============================================================================================
// Enum Definitions
// ===============================================================================================

/*!\brief List of supported image formats */
typedef enum uhdr_img_fmt {
  UHDR_IMG_FMT_UNSPECIFIED = -1,   /**< Unspecified */
  UHDR_IMG_FMT_24bppYCbCrP010 = 0, /**< 10-bit-per component 4:2:0 YCbCr semiplanar format.
                               Each chroma and luma component has 16 allocated bits in
                               little-endian configuration with 10 MSB of actual data.*/
  UHDR_IMG_FMT_12bppYCbCr420 = 1,  /**< 8-bit-per component 4:2:0 YCbCr planar format */
  UHDR_IMG_FMT_8bppYCbCr400 = 2,   /**< 8-bit-per component Monochrome format */
  UHDR_IMG_FMT_32bppRGBA8888 =
      3, /**< 32 bits per pixel RGBA color format, with 8-bit red, green, blue
        and alpha components. Using 32-bit little-endian representation,
        colors stored as Red 7:0, Green 15:8, Blue 23:16, Alpha 31:24. */
  UHDR_IMG_FMT_64bppRGBAHalfFloat =
      4, /**< 64 bits per pixel, 16 bits per channel, half-precision floating point RGBA color
            format. colors stored as Red 15:0, Green 31:16, Blue 47:32, Alpha 63:48. In a pixel
            even though each channel has storage space of 16 bits, the nominal range is expected to
            be [0.0..(10000/203)] */
  UHDR_IMG_FMT_32bppRGBA1010102 = 5, /**< 32 bits per pixel RGBA color format, with 10-bit red,
                                    green,   blue, and 2-bit alpha components. Using 32-bit
                                    little-endian   representation, colors stored as Red 9:0, Green
                                    19:10, Blue   29:20, and Alpha 31:30. */
  UHDR_IMG_FMT_24bppYCbCr444 = 6,    /**< 8-bit-per component 4:4:4 YCbCr planar format */
  UHDR_IMG_FMT_16bppYCbCr422 = 7,    /**< 8-bit-per component 4:2:2 YCbCr planar format */
  UHDR_IMG_FMT_16bppYCbCr440 = 8,    /**< 8-bit-per component 4:4:0 YCbCr planar format */
  UHDR_IMG_FMT_12bppYCbCr411 = 9,    /**< 8-bit-per component 4:1:1 YCbCr planar format */
  UHDR_IMG_FMT_10bppYCbCr410 = 10,   /**< 8-bit-per component 4:1:0 YCbCr planar format */
  UHDR_IMG_FMT_24bppRGB888 = 11,     /**< 8-bit-per component RGB interleaved format */
  UHDR_IMG_FMT_30bppYCbCr444 = 12,   /**< 10-bit-per component 4:4:4 YCbCr planar format */
} uhdr_img_fmt_t;                    /**< alias for enum uhdr_img_fmt */

/*!\brief List of supported color gamuts */
typedef enum uhdr_color_gamut {
  UHDR_CG_UNSPECIFIED = -1, /**< Unspecified */
  UHDR_CG_BT_709 = 0,       /**< BT.709 */
  UHDR_CG_DISPLAY_P3 = 1,   /**< Display P3 */
  UHDR_CG_BT_2100 = 2,      /**< BT.2100 */
} uhdr_color_gamut_t;       /**< alias for enum uhdr_color_gamut */

/*!\brief List of supported color transfers */
typedef enum uhdr_color_transfer {
  UHDR_CT_UNSPECIFIED = -1, /**< Unspecified */
  UHDR_CT_LINEAR = 0,       /**< Linear */
  UHDR_CT_HLG = 1,          /**< Hybrid log gamma */
  UHDR_CT_PQ = 2,           /**< Perceptual Quantizer */
  UHDR_CT_SRGB = 3,         /**< Gamma */
} uhdr_color_transfer_t;    /**< alias for enum uhdr_color_transfer */

/*!\brief List of supported color ranges */
typedef enum uhdr_color_range {
  UHDR_CR_UNSPECIFIED = -1,  /**< Unspecified */
  UHDR_CR_LIMITED_RANGE = 0, /**< Y {[16..235], UV [16..240]} * pow(2, (bpc - 8)) */
  UHDR_CR_FULL_RANGE = 1,    /**< YUV/RGB {[0..255]} * pow(2, (bpc - 8)) */
} uhdr_color_range_t;        /**< alias for enum uhdr_color_range */

/*!\brief List of supported codecs */
typedef enum uhdr_codec {
  UHDR_CODEC_JPG,  /**< Compress {Hdr, Sdr rendition} to an {Sdr rendition + Gain Map} using jpeg */
  UHDR_CODEC_HEIF, /**< Compress {Hdr, Sdr rendition} to an {Sdr rendition + Gain Map} using heif */
  UHDR_CODEC_AVIF, /**< Compress {Hdr, Sdr rendition} to an {Sdr rendition + Gain Map} using avif */
} uhdr_codec_t;    /**< alias for enum uhdr_codec */

/*!\brief Image identifiers in gain map technology */
typedef enum uhdr_img_label {
  UHDR_HDR_IMG,      /**< Hdr rendition image */
  UHDR_SDR_IMG,      /**< Sdr rendition image */
  UHDR_BASE_IMG,     /**< Base rendition image */
  UHDR_GAIN_MAP_IMG, /**< Gain map image */
} uhdr_img_label_t;  /**< alias for enum uhdr_img_label */

/*!\brief uhdr encoder usage parameter */
typedef enum uhdr_enc_preset {
  UHDR_USAGE_REALTIME,     /**< tune encoder settings for performance */
  UHDR_USAGE_BEST_QUALITY, /**< tune encoder settings for quality */
} uhdr_enc_preset_t;       /**< alias for enum uhdr_enc_preset */

/*!\brief Algorithm return codes */
typedef enum uhdr_codec_err {

  /*!\brief Operation completed without error */
  UHDR_CODEC_OK,

  /*!\brief Generic codec error, refer detail field for more information */
  UHDR_CODEC_ERROR,

  /*!\brief Unknown error, refer detail field for more information */
  UHDR_CODEC_UNKNOWN_ERROR,

  /*!\brief An application-supplied parameter is not valid. */
  UHDR_CODEC_INVALID_PARAM,

  /*!\brief Memory operation failed */
  UHDR_CODEC_MEM_ERROR,

  /*!\brief An application-invoked operation is not valid */
  UHDR_CODEC_INVALID_OPERATION,

  /*!\brief The library does not implement a feature required for the operation */
  UHDR_CODEC_UNSUPPORTED_FEATURE,

  /*!\brief Not for usage, indicates end of list */
  UHDR_CODEC_LIST_END,

} uhdr_codec_err_t; /**< alias for enum uhdr_codec_err */

/*!\brief List of supported mirror directions. */
typedef enum uhdr_mirror_direction {
  UHDR_MIRROR_VERTICAL,    /**< flip image over x axis */
  UHDR_MIRROR_HORIZONTAL,  /**< flip image over y axis */
} uhdr_mirror_direction_t; /**< alias for enum uhdr_mirror_direction */

// ===============================================================================================
// Structure Definitions
// ===============================================================================================

/*!\brief Detailed return status */
typedef struct uhdr_error_info {
  uhdr_codec_err_t error_code; /**< error code */
  int has_detail;              /**< has detailed error logs. 0 - no, else - yes */
  char detail[256];            /**< error logs */
} uhdr_error_info_t;           /**< alias for struct uhdr_error_info */

/**\brief Raw Image Descriptor */
typedef struct uhdr_raw_image {
  /* Color Aspects: Color model, primaries, transfer, range */
  uhdr_img_fmt_t fmt;       /**< Image Format */
  uhdr_color_gamut_t cg;    /**< Color Gamut */
  uhdr_color_transfer_t ct; /**< Color Transfer */
  uhdr_color_range_t range; /**< Color Range */

  /* Image storage dimensions */
  unsigned int w; /**< Stored image width */
  unsigned int h; /**< Stored image height */

  /* Image data pointers. */
#define UHDR_PLANE_PACKED 0 /**< To be used for all packed formats */
#define UHDR_PLANE_Y 0      /**< Y (Luminance) plane */
#define UHDR_PLANE_U 1      /**< U (Chroma) plane */
#define UHDR_PLANE_UV 1     /**< UV (Chroma plane interleaved) To be used for semi planar format */
#define UHDR_PLANE_V 2      /**< V (Chroma) plane */
  void* planes[3];          /**< pointer to the top left pixel for each plane */
  unsigned int stride[3];   /**< stride in pixels between rows for each plane */
} uhdr_raw_image_t;         /**< alias for struct uhdr_raw_image */

/**\brief Compressed Image Descriptor */
typedef struct uhdr_compressed_image {
  void* data;               /**< Pointer to a block of data to decode */
  size_t data_sz;           /**< size of the data buffer */
  size_t capacity;          /**< maximum size of the data buffer */
  uhdr_color_gamut_t cg;    /**< Color Gamut */
  uhdr_color_transfer_t ct; /**< Color Transfer */
  uhdr_color_range_t range; /**< Color Range */
} uhdr_compressed_image_t;  /**< alias for struct uhdr_compressed_image */

/**\brief Buffer Descriptor */
typedef struct uhdr_mem_block {
  void* data;       /**< Pointer to a block of data to decode */
  size_t data_sz;   /**< size of the data buffer */
  size_t capacity;  /**< maximum size of the data buffer */
} uhdr_mem_block_t; /**< alias for struct uhdr_mem_block */

/**\brief Gain map metadata. */
typedef struct uhdr_gainmap_metadata {
  float max_content_boost[3]; /**< Value to control how much brighter an image can get, when shown
                              on an HDR display, relative to the SDR rendition. This is constant for
                              a given image. Value MUST be in linear scale. */
  float min_content_boost[3]; /**< Value to control how much darker an image can get, when shown on
                              an HDR display, relative to the SDR rendition. This is constant for a
                              given image. Value MUST be in linear scale. */
  float gamma[3];             /**< Encoding Gamma of the gainmap image. */
  float offset_sdr[3];    /**< The offset to apply to the SDR pixel values during gainmap generation
                          and application. */
  float offset_hdr[3];    /**< The offset to apply to the HDR pixel values during gainmap generation
                          and application. */
  float hdr_capacity_min; /**< Minimum display boost value for which the map is applied completely.
                             Value MUST be in linear scale. */
  float hdr_capacity_max; /**< Maximum display boost value for which the map is applied completely.
                             Value MUST be in linear scale. */
  int use_base_cg;         /**< Is gainmap application space same as base image color space */
} uhdr_gainmap_metadata_t; /**< alias for struct uhdr_gainmap_metadata */

/**\brief ultrahdr codec context opaque descriptor */
typedef struct uhdr_codec_private uhdr_codec_private_t;

// ===============================================================================================
// Function Declarations
// ===============================================================================================

// ===============================================================================================
// Encoder APIs
// ===============================================================================================

/*!\brief Create a new encoder instance. The instance is initialized with default settings.
 * To override the settings use uhdr_enc_set_*()
 *
 * \return  nullptr if there was an error allocating memory else a fresh opaque encoder handle
 */
UHDR_EXTERN uhdr_codec_private_t* uhdr_create_encoder(void);

/*!\brief Release encoder instance.
 * Frees all allocated storage associated with encoder instance.
 *
 * \param[in]  enc  encoder instance.
 *
 * \return none
 */
UHDR_EXTERN void uhdr_release_encoder(uhdr_codec_private_t* enc);

/*!\brief Add raw image descriptor to encoder context. The function goes through all the fields of
 * the image descriptor and checks for their sanity. If no anomalies are seen then the image is
 * added to internal list. Repeated calls to this function will replace the old entry with the
 * current.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  img  image descriptor.
 * \param[in]  intent  UHDR_HDR_IMG for hdr intent and UHDR_SDR_IMG for sdr intent.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_raw_image(uhdr_codec_private_t* enc,
                                                     uhdr_raw_image_t* img,
                                                     uhdr_img_label_t intent);

/*!\brief Add compressed image descriptor to encoder context. The function goes through all the
 * fields of the image descriptor and checks for their sanity. If no anomalies are seen then the
 * image is added to internal list. Repeated calls to this function will replace the old entry with
 * the current.
 *
 * If both uhdr_enc_add_raw_image() and uhdr_enc_add_compressed_image() are called during a session
 * for the same intent, it is assumed that raw image descriptor and compressed image descriptor are
 * relatable via compress <-> decompress process.
 *
 * The compressed image descriptors has fields cg, ct and range. Certain media formats are capable
 * of storing color standard, color transfer and color range characteristics in the bitstream (for
 * example heif, avif, ...). Other formats may not support this (jpeg, ...). These fields serve as
 * an additional source for conveying this information. If the user is unaware of the color aspects
 * of the image, #UHDR_CG_UNSPECIFIED, #UHDR_CT_UNSPECIFIED, #UHDR_CR_UNSPECIFIED can be used. If
 * color aspects are present inside the bitstream and supplied via these fields both are expected to
 * be identical.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  img  image descriptor.
 * \param[in]  intent  UHDR_HDR_IMG for hdr intent,
 *                     UHDR_SDR_IMG for sdr intent,
 *                     UHDR_BASE_IMG for base image intent
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_compressed_image(uhdr_codec_private_t* enc,
                                                            uhdr_compressed_image_t* img,
                                                            uhdr_img_label_t intent);

/*!\brief Add gain map image descriptor and gainmap metadata info that was used to generate the
 * aforth gainmap image to encoder context. The function internally goes through all the fields of
 * the image descriptor and checks for their sanity. If no anomalies are seen then the image is
 * added to internal list. Repeated calls to this function will replace the old entry with the
 * current.
 *
 * NOTE: There are apis that allow configuration of gainmap info separately. For instance
 * #uhdr_enc_set_gainmap_gamma, #uhdr_enc_set_gainmap_scale_factor, ... They have no effect on the
 * information that is configured via this api. The information configured here is treated as
 * immutable and used as-is in encoding scenario where gainmap computations are intended to be
 * by-passed.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  img  gain map image desciptor.
 * \param[in]  metadata  gainmap metadata descriptor
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_gainmap_image(uhdr_codec_private_t* enc,
                                                         uhdr_compressed_image_t* img,
                                                         uhdr_gainmap_metadata_t* metadata);

/*!\brief Set quality factor for compressing base image and/or gainmap image. Default configured
 * quality factor of base image and gainmap image are 95 and 95 respectively.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  quality  quality factor. Any integer in range [0 - 100].
 * \param[in]  intent  #UHDR_BASE_IMG for base image and #UHDR_GAIN_MAP_IMG for gain map image.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_quality(uhdr_codec_private_t* enc, int quality,
                                                   uhdr_img_label_t intent);

/*!\brief Set Exif data that needs to be inserted in the output compressed stream. This function
 * does not generate or validate exif data on its own. It merely copies the supplied information
 * into the bitstream.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  exif  exif data memory block.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_exif_data(uhdr_codec_private_t* enc,
                                                     uhdr_mem_block_t* exif);

/*!\brief Enable/Disable multi-channel gainmap. By default multi-channel gainmap is enabled.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  use_multi_channel_gainmap  enable/disable multichannel gain map.
 *                                        0 - single-channel gainmap is enabled,
 *                                        otherwise - multi-channel gainmap is enabled.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t
uhdr_enc_set_using_multi_channel_gainmap(uhdr_codec_private_t* enc, int use_multi_channel_gainmap);

/*!\brief Set gain map scaling factor. The encoding process allows signalling a downscaled gainmap
 * image instead of full resolution. This setting controls the factor by which the renditions are
 * downscaled. For instance, gainmap_scale_factor = 2 implies gainmap_image_width =
 * primary_image_width / 2 and gainmap image height = primary_image_height / 2.
 * Default gain map scaling factor is 1.
 * NOTE: This has no effect on base image rendition. Base image is signalled in full resolution
 * always.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  gainmap_scale_factor  gain map scale factor. Any integer in range (0, 128]
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_gainmap_scale_factor(uhdr_codec_private_t* enc,
                                                                int gainmap_scale_factor);

/*!\brief Set encoding gamma of gainmap image. For multi-channel gainmap image, set gamma is used
 * for gamma correction of all planes separately. Default gamma value is 1.0.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  gamma  gamma of gainmap image. Any positive real number.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_gainmap_gamma(uhdr_codec_private_t* enc, float gamma);

/*!\brief Set min max content boost. This configuration is treated as a recommendation by the
 * library. It is entirely possible for the library to use a different set of values. Value MUST be
 * in linear scale.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  min_boost min content boost. Any positive real number.
 * \param[in]  max_boost max content boost. Any positive real number >= min_boost.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_min_max_content_boost(uhdr_codec_private_t* enc,
                                                                 float min_boost, float max_boost);

/*!\brief Set target display peak brightness in nits. This is used for configuring #hdr_capacity_max
 * of gainmap metadata. This value determines the weight by which the gain map coefficients are
 * scaled during decode. If this is not configured, then default peak luminance of HDR intent's
 * color transfer under test is used. For #UHDR_CT_HLG, this corresponds to 1000 nits and for
 * #UHDR_CT_LINEAR and #UHDR_CT_PQ, this corresponds to 10000 nits.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  nits  target display peak brightness in nits. Any positive real number in range
 *                   [203, 10000].
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_target_display_peak_brightness(uhdr_codec_private_t* enc,
                                                                          float nits);

/*!\brief Set encoding preset. Tunes the encoder configurations for performance or quality. Default
 * configuration is #UHDR_USAGE_BEST_QUALITY.
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  preset  encoding preset. #UHDR_USAGE_REALTIME - Tune settings for best performance
 *                                      #UHDR_USAGE_BEST_QUALITY - Tune settings for best quality
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_preset(uhdr_codec_private_t* enc,
                                                  uhdr_enc_preset_t preset);

/*!\brief Set output image compression format. Selects the compression format for encoding base
 * image and gainmap image. Default configuration is #UHDR_CODEC_JPG
 *
 * \param[in]  enc  encoder instance.
 * \param[in]  media_type  output image compression format. Supported values are #UHDR_CODEC_JPG
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enc_set_output_format(uhdr_codec_private_t* enc,
                                                         uhdr_codec_t media_type);

/*!\brief Encode process call
 * After initializing the encoder context, call to this function will submit data for encoding. If
 * the call is successful, the encoded output is stored internally and is accessible via
 * uhdr_get_encoded_stream().
 *
 * The basic usage of uhdr encoder is as follows:
 * - The program creates an instance of an encoder using,
 *   - uhdr_create_encoder().
 * - The program registers input images to the encoder using,
 *   - uhdr_enc_set_raw_image(ctxt, img, UHDR_HDR_IMG)
 *   - uhdr_enc_set_raw_image(ctxt, img, UHDR_SDR_IMG)
 * - The program overrides the default settings using uhdr_enc_set_*() functions
 * - If the application wants to control the compression level
 *   - uhdr_enc_set_quality()
 * - If the application wants to insert exif data
 *   - uhdr_enc_set_exif_data()
 * - If the application wants to set gainmap scale factor
 *   - uhdr_enc_set_gainmap_scale_factor()
 * - If the application wants to enable multi channel gain map
 *   - uhdr_enc_set_using_multi_channel_gainmap()
 * - If the application wants to set gainmap image gamma
 *   - uhdr_enc_set_gainmap_gamma()
 * - If the application wants to recommend min max content boost
 *   - uhdr_enc_set_min_max_content_boost()
 * - If the application wants to set target display peak brightness
 *   - uhdr_enc_set_target_display_peak_brightness()
 * - If the application wants to set encoding preset
 *   - uhdr_enc_set_preset()
 * - If the application wants to control target compression format
 *   - uhdr_enc_set_output_format()
 * - The program calls uhdr_encode() to encode data. This call would initiate the process of
 * computing gain map from hdr intent and sdr intent. The sdr intent and gain map image are
 * compressed at the set quality using the codec of choice.
 * - On success, the program can access the encoded output with uhdr_get_encoded_stream().
 * - The program finishes the encoding with uhdr_release_encoder().
 *
 * The library allows setting Hdr and/or Sdr intent in compressed format,
 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_HDR_IMG)
 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_SDR_IMG)
 * In this mode, the compressed image(s) are first decoded to raw image(s). These raw image(s) go
 * through the aforth mentioned gain map computation and encoding process. In this case, the usage
 * shall be like this:
 * - uhdr_create_encoder()
 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_HDR_IMG)
 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_SDR_IMG)
 * - uhdr_encode()
 * - uhdr_get_encoded_stream()
 * - uhdr_release_encoder()
 * If the set compressed image media type of intent UHDR_SDR_IMG and output media type are
 * identical, then this image is directly used for primary image. No re-encode of raw image is done.
 * This implies base image quality setting is un-used. Only gain map image is encoded at the set
 * quality using codec of choice. On the other hand, if the set compressed image media type and
 * output media type are different, then transcoding is done.
 *
 * The library also allows directly setting base and gain map image in compressed format,
 * - uhdr_enc_set_compressed_image(ctxt, img, UHDR_BASE_IMG)
 * - uhdr_enc_set_gainmap_image(ctxt, img, metadata)
 * In this mode, gain map computation is by-passed. The input images are transcoded (if necessary),
 * combined and sent back.
 *
 * It is possible to create a uhdr image solely from Hdr intent. In this case, the usage shall look
 * like this:
 * - uhdr_create_encoder()
 * - uhdr_enc_set_raw_image(ctxt, img, UHDR_HDR_IMG)
 * - uhdr_enc_set_quality() // optional
 * - uhdr_enc_set_exif_data() // optional
 * - uhdr_enc_set_output_format() // optional
 * - uhdr_enc_set_gainmap_scale_factor() // optional
 * - uhdr_enc_set_using_multi_channel_gainmap() // optional
 * - uhdr_enc_set_gainmap_gamma() // optional
 * - uhdr_enc_set_min_max_content_boost() // optional
 * - uhdr_enc_set_target_display_peak_brightness() // optional
 * - uhdr_encode()
 * - uhdr_get_encoded_stream()
 * - uhdr_release_encoder()
 * In this mode, the Sdr rendition is created from Hdr intent by tone-mapping. The tone-mapped sdr
 * image and hdr image go through the aforth mentioned gain map computation and encoding process to
 * create uhdr image.
 *
 * In all modes, Exif data is inserted if requested.
 *
 * \param[in]  enc  encoder instance.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_encode(uhdr_codec_private_t* enc);

/*!\brief Get encoded ultra hdr stream
 *
 * \param[in]  enc  encoder instance.
 *
 * \return nullptr if encode process call is unsuccessful, uhdr image descriptor otherwise
 */
UHDR_EXTERN uhdr_compressed_image_t* uhdr_get_encoded_stream(uhdr_codec_private_t* enc);

/*!\brief Reset encoder instance.
 * Clears all previous settings and resets to default state and ready for re-initialization and
 * usage
 *
 * \param[in]  enc  encoder instance.
 *
 * \return none
 */
UHDR_EXTERN void uhdr_reset_encoder(uhdr_codec_private_t* enc);

// ===============================================================================================
// Decoder APIs
// ===============================================================================================

/*!\brief check if it is a valid ultrahdr image.
 *
 * @param[in]  data  pointer to input compressed stream
 * @param[in]  size  size of compressed stream
 *
 * @returns 1 if the input data has a primary image, gain map image and gain map metadata. 0 if any
 *          errors are encountered during parsing process or if the image does not have primary
 *          image or gainmap image or gainmap metadata
 */
UHDR_EXTERN int is_uhdr_image(void* data, int size);

/*!\brief Create a new decoder instance. The instance is initialized with default settings.
 * To override the settings use uhdr_dec_set_*()
 *
 * \return  nullptr if there was an error allocating memory else a fresh opaque decoder handle
 */
UHDR_EXTERN uhdr_codec_private_t* uhdr_create_decoder(void);

/*!\brief Release decoder instance.
 * Frees all allocated storage associated with decoder instance.
 *
 * \param[in]  dec  decoder instance.
 *
 * \return none
 */
UHDR_EXTERN void uhdr_release_decoder(uhdr_codec_private_t* dec);

/*!\brief Add compressed image descriptor to decoder context. The function goes through all the
 * fields of the image descriptor and checks for their sanity. If no anomalies are seen then the
 * image is added to internal list. Repeated calls to this function will replace the old entry with
 * the current.
 *
 * \param[in]  dec  decoder instance.
 * \param[in]  img  image descriptor.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_image(uhdr_codec_private_t* dec,
                                                 uhdr_compressed_image_t* img);

/*!\brief Set output image color format
 *
 * \param[in]  dec  decoder instance.
 * \param[in]  fmt  output image color format. Supported values are
 *                  #UHDR_IMG_FMT_64bppRGBAHalfFloat, #UHDR_IMG_FMT_32bppRGBA1010102,
 *                  #UHDR_IMG_FMT_32bppRGBA8888
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_img_format(uhdr_codec_private_t* dec,
                                                          uhdr_img_fmt_t fmt);

/*!\brief Set output image color transfer characteristics. It should be noted that not all
 * combinations of output color format and output transfer function are supported. #UHDR_CT_SRGB
 * output color transfer shall be paired with #UHDR_IMG_FMT_32bppRGBA8888 only. #UHDR_CT_HLG,
 * #UHDR_CT_PQ shall be paired with #UHDR_IMG_FMT_32bppRGBA1010102. #UHDR_CT_LINEAR shall be paired
 * with #UHDR_IMG_FMT_64bppRGBAHalfFloat.
 *
 * \param[in]  dec  decoder instance.
 * \param[in]  ct  output color transfer
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_color_transfer(uhdr_codec_private_t* dec,
                                                              uhdr_color_transfer_t ct);

/*!\brief Set output display's HDR capacity. Value MUST be in linear scale. This value determines
 * the weight by which the gain map coefficients are scaled. If no value is configured, no weight is
 * applied to gainmap image.
 *
 * \param[in]  dec  decoder instance.
 * \param[in]  display_boost  hdr capacity of target display. Any real number >= 1.0f
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds,
 *                           #UHDR_CODEC_INVALID_PARAM otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_dec_set_out_max_display_boost(uhdr_codec_private_t* dec,
                                                                 float display_boost);

/*!\brief This function parses the bitstream that is registered with the decoder context and makes
 * image information available to the client via uhdr_dec_get_() functions. It does not decompress
 * the image. That is done by uhdr_decode().
 *
 * \param[in]  dec  decoder instance.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_dec_probe(uhdr_codec_private_t* dec);

/*!\brief Get base image width
 *
 * \param[in]  dec  decoder instance.
 *
 * \return -1 if probe call is unsuccessful, base image width otherwise
 */
UHDR_EXTERN int uhdr_dec_get_image_width(uhdr_codec_private_t* dec);

/*!\brief Get base image height
 *
 * \param[in]  dec  decoder instance.
 *
 * \return -1 if probe call is unsuccessful, base image height otherwise
 */
UHDR_EXTERN int uhdr_dec_get_image_height(uhdr_codec_private_t* dec);

/*!\brief Get gainmap image width
 *
 * \param[in]  dec  decoder instance.
 *
 * \return -1 if probe call is unsuccessful, gain map image width otherwise
 */
UHDR_EXTERN int uhdr_dec_get_gainmap_width(uhdr_codec_private_t* dec);

/*!\brief Get gainmap image height
 *
 * \param[in]  dec  decoder instance.
 *
 * \return -1 if probe call is unsuccessful, gain map image height otherwise
 */
UHDR_EXTERN int uhdr_dec_get_gainmap_height(uhdr_codec_private_t* dec);

/*!\brief Get exif information
 *
 * \param[in]  dec  decoder instance.
 *
 * \return nullptr if probe call is unsuccessful, memory block with exif data otherwise
 */
UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_exif(uhdr_codec_private_t* dec);

/*!\brief Get icc information
 *
 * \param[in]  dec  decoder instance.
 *
 * \return nullptr if probe call is unsuccessful, memory block with icc data otherwise
 */
UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_icc(uhdr_codec_private_t* dec);

/*!\brief Get base image (compressed)
 *
 * \param[in]  dec  decoder instance.
 *
 * \return nullptr if probe process call is unsuccessful, memory block with base image data
 * otherwise
 */
UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_base_image(uhdr_codec_private_t* dec);

/*!\brief Get gain map image (compressed)
 *
 * \param[in]  dec  decoder instance.
 *
 * \return nullptr if probe process call is unsuccessful, memory block with gainmap image data
 * otherwise
 */
UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_gainmap_image(uhdr_codec_private_t* dec);

/*!\brief Get gain map metadata
 *
 * \param[in]  dec  decoder instance.
 *
 * \return nullptr if probe process call is unsuccessful, gainmap metadata descriptor otherwise
 */
UHDR_EXTERN uhdr_gainmap_metadata_t* uhdr_dec_get_gainmap_metadata(uhdr_codec_private_t* dec);

/*!\brief Decode process call
 * After initializing the decoder context, call to this function will submit data for decoding. If
 * the call is successful, the decoded output is stored internally and is accessible via
 * uhdr_get_decoded_image().
 *
 * The basic usage of uhdr decoder is as follows:
 * - The program creates an instance of a decoder using,
 *   - uhdr_create_decoder().
 * - The program registers input images to the decoder using,
 *   - uhdr_dec_set_image(ctxt, img)
 * - The program overrides the default settings using uhdr_dec_set_*() functions.
 * - If the application wants to control the output image format,
 *   - uhdr_dec_set_out_img_format()
 * - If the application wants to control the output transfer characteristics,
 *   - uhdr_dec_set_out_color_transfer()
 * - If the application wants to control the output display boost,
 *   - uhdr_dec_set_out_max_display_boost()
 * - If the application wants to enable/disable gpu acceleration,
 *   - uhdr_enable_gpu_acceleration()
 * - The program calls uhdr_decode() to decode uhdr stream. This call would initiate the process
 * of decoding base image and gain map image. These two are combined to give the final rendition
 * image.
 * - The program can access the decoded output with uhdr_get_decoded_image().
 * - The program finishes the decoding with uhdr_release_decoder().
 *
 * \param[in]  dec  decoder instance.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, uhdr_codec_err_t otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_decode(uhdr_codec_private_t* dec);

/*!\brief Get final rendition image
 *
 * \param[in]  dec  decoder instance.
 *
 * \return nullptr if decoded process call is unsuccessful, raw image descriptor otherwise
 */
UHDR_EXTERN uhdr_raw_image_t* uhdr_get_decoded_image(uhdr_codec_private_t* dec);

/*!\brief Get gain map image
 *
 * \param[in]  dec  decoder instance.
 *
 * \return nullptr if decoded process call is unsuccessful, raw image descriptor otherwise
 */
UHDR_EXTERN uhdr_raw_image_t* uhdr_get_decoded_gainmap_image(uhdr_codec_private_t* dec);

/*!\brief Reset decoder instance.
 * Clears all previous settings and resets to default state and ready for re-initialization and
 * usage
 *
 * \param[in]  dec  decoder instance.
 *
 * \return none
 */
UHDR_EXTERN void uhdr_reset_decoder(uhdr_codec_private_t* dec);

// ===============================================================================================
// Common APIs
// ===============================================================================================

/*!\brief Enable/Disable GPU acceleration.
 * If enabled, certain operations (if possible) of uhdr encode/decode will be offloaded to GPU.
 * NOTE: It is entirely possible for this API to have no effect on the encode/decode operation
 *
 * \param[in]  codec  codec instance.
 * \param[in]  enable  enable enable/disbale gpu acceleration
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM
 * otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_enable_gpu_acceleration(uhdr_codec_private_t* codec, int enable);

/*!\brief Add image editing operations (pre-encode or post-decode).
 * Below functions list the set of edits supported. Program can set any combination of these during
 * initialization. Once the encode/decode process call is made, before encoding or after decoding
 * the edits are applied in the order of configuration.
 */

/*!\brief Add mirror effect
 *
 * \param[in]  codec  codec instance.
 * \param[in]  direction  mirror directions. #UHDR_MIRROR_VERTICAL for vertical mirroring
 *                                           #UHDR_MIRROR_HORIZONTAL for horizontal mirroing
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM
 * otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_mirror(uhdr_codec_private_t* codec,
                                                     uhdr_mirror_direction_t direction);

/*!\brief Add rotate effect
 *
 * \param[in]  codec  codec instance.
 * \param[in]  degrees  clockwise degrees. 90 - rotate clockwise by 90 degrees
 *                                         180 - rotate clockwise by 180 degrees
 *                                         270 - rotate clockwise by 270 degrees
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM
 * otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_rotate(uhdr_codec_private_t* codec, int degrees);

/*!\brief Add crop effect
 *
 * \param[in]  codec  codec instance.
 * \param[in]  left  crop coordinate left in pixels.
 * \param[in]  right  crop coordinate right in pixels.
 * \param[in]  top  crop coordinate top in pixels.
 * \param[in]  bottom  crop coordinate bottom in pixels.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM
 * otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_crop(uhdr_codec_private_t* codec, int left, int right,
                                                   int top, int bottom);

/*!\brief Add resize effect
 *
 * \param[in]  codec  codec instance.
 * \param[in]  width  target width.
 * \param[in]  height  target height.
 *
 * \return uhdr_error_info_t #UHDR_CODEC_OK if operation succeeds, #UHDR_CODEC_INVALID_PARAM
 * otherwise.
 */
UHDR_EXTERN uhdr_error_info_t uhdr_add_effect_resize(uhdr_codec_private_t* codec, int width,
                                                     int height);

#endif  // ULTRAHDR_API_H