Add apis to access primary and gainmap compressed data

Also,
- fixed few api names for consistency.
- moved lib version macro to public interface
- documented version semantics inconsistencies

.github/workflows/cmake_linux.yml

@@ -43,6 +43,14 @@ jobs:
             cxx: clang++
             cmake-opts: '-DUHDR_BUILD_TESTS=1 -DUHDR_ENABLE_LOGS=1 -DUHDR_BUILD_DEPS=1 -DUHDR_SANITIZE_OPTIONS=address'
 
+          # <Ubuntu-latest Platform, Release Build, Clang toolchain, Ninja generator, Build Fuzzers, Sanitizer Address>
+          - name: "ubuntu latest clang rel ninja fuzzers sanitize address"
+            os: ubuntu-latest
+            build_type: Release
+            cc: clang
+            cxx: clang++
+            cmake-opts: '-DUHDR_BUILD_TESTS=1 -DUHDR_BUILD_FUZZERS=1 -DUHDR_SANITIZE_OPTIONS=address'
+
           # <Ubuntu-latest Platform, Release Build, GCC toolchain, Ninja generator, Static linking>
           - name: "ubuntu latest gcc rel ninja static"
             os: ubuntu-latest

examples/ultrahdr_app.cpp

@@ -758,7 +758,7 @@ bool UltraHdrAppInput::decode() {
   }
   RET_IF_ERR(uhdr_dec_probe(handle))
   if (mGainMapMetadataCfgFile != nullptr) {
-    uhdr_gainmap_metadata_t* metadata = uhdr_dec_get_gain_map_metadata(handle);
+    uhdr_gainmap_metadata_t* metadata = uhdr_dec_get_gainmap_metadata(handle);
     if (!writeGainMapMetadataToFile(metadata)) {
       std::cerr << "failed to write gainmap metadata to file: " << mGainMapMetadataCfgFile
                 << std::endl;

fuzzer/ultrahdr_dec_fuzzer.cpp

@@ -69,10 +69,12 @@ void UltraHdrDecFuzzer::process() {
     uhdr_dec_get_gainmap_height(dec_handle);
     uhdr_dec_get_exif(dec_handle);
     uhdr_dec_get_icc(dec_handle);
-    uhdr_dec_get_gain_map_metadata(dec_handle);
+    uhdr_dec_get_base_image(dec_handle);
+    uhdr_dec_get_gainmap_image(dec_handle);
+    uhdr_dec_get_gainmap_metadata(dec_handle);
     uhdr_decode(dec_handle);
     uhdr_get_decoded_image(dec_handle);
-    uhdr_get_gain_map_image(dec_handle);
+    uhdr_get_decoded_gainmap_image(dec_handle);
     uhdr_release_decoder(dec_handle);
   }
 }

lib/include/ultrahdr/ultrahdrcommon.h

@@ -132,9 +132,6 @@
     }                                         \
   }
 
-// This needs to be kept in sync with version in CMakeLists.txt
-#define UHDR_LIB_VERSION "v1.1.1"
-
 #if defined(_MSC_VER)
 #define FORCE_INLINE __forceinline
 #define INLINE __inline
@@ -381,6 +378,10 @@ struct uhdr_decoder_private : uhdr_codec_private {
   uhdr_mem_block_t m_exif_block;
   std::vector<uint8_t> m_icc;
   uhdr_mem_block_t m_icc_block;
+  std::vector<uint8_t> m_base_img;
+  uhdr_mem_block_t m_base_img_block;
+  std::vector<uint8_t> m_gainmap_img;
+  uhdr_mem_block_t m_gainmap_img_block;
   uhdr_gainmap_metadata_t m_metadata;
   uhdr_error_info_t m_probe_call_status;
   uhdr_error_info_t m_decode_call_status;

lib/src/jpegencoderhelper.cpp

@@ -203,7 +203,7 @@ uhdr_error_info_t JpegEncoderHelper::encode(const uint8_t* planes[3], const size
     if (isGainMapImg) {
       char comment[255];
       snprintf(comment, sizeof comment,
-               "Source: google libuhdr %s, Coder: libjpeg v%d, Attrib: GainMap Image",
+               "Source: google libuhdr v%s, Coder: libjpeg v%d, Attrib: GainMap Image",
                UHDR_LIB_VERSION, JPEG_LIB_VERSION);
       jpeg_write_marker(&cinfo, JPEG_COM, reinterpret_cast<JOCTET*>(comment), strlen(comment));
     }

lib/src/ultrahdr_api.cpp

@@ -1445,6 +1445,14 @@ uhdr_error_info_t uhdr_dec_probe(uhdr_codec_private_t* dec) {
     handle->m_icc = std::move(primary_image.iccData);
     handle->m_icc_block.data = handle->m_icc.data();
     handle->m_icc_block.data_sz = handle->m_icc_block.capacity = handle->m_icc.size();
+    handle->m_base_img = std::move(primary_image.imgData);
+    handle->m_base_img_block.data = handle->m_base_img.data();
+    handle->m_base_img_block.data_sz = handle->m_base_img_block.capacity =
+        handle->m_base_img.size();
+    handle->m_gainmap_img = std::move(gainmap_image.imgData);
+    handle->m_gainmap_img_block.data = handle->m_gainmap_img.data();
+    handle->m_gainmap_img_block.data_sz = handle->m_gainmap_img_block.capacity =
+        handle->m_gainmap_img.size();
   }
 
   return status;
@@ -1528,7 +1536,33 @@ uhdr_mem_block_t* uhdr_dec_get_icc(uhdr_codec_private_t* dec) {
   return &handle->m_icc_block;
 }
 
-uhdr_gainmap_metadata_t* uhdr_dec_get_gain_map_metadata(uhdr_codec_private_t* dec) {
+uhdr_mem_block_t* uhdr_dec_get_base_image(uhdr_codec_private_t* dec) {
+  if (dynamic_cast<uhdr_decoder_private*>(dec) == nullptr) {
+    return nullptr;
+  }
+
+  uhdr_decoder_private* handle = dynamic_cast<uhdr_decoder_private*>(dec);
+  if (!handle->m_probed || handle->m_probe_call_status.error_code != UHDR_CODEC_OK) {
+    return nullptr;
+  }
+
+  return &handle->m_base_img_block;
+}
+
+uhdr_mem_block_t* uhdr_dec_get_gainmap_image(uhdr_codec_private_t* dec) {
+  if (dynamic_cast<uhdr_decoder_private*>(dec) == nullptr) {
+    return nullptr;
+  }
+
+  uhdr_decoder_private* handle = dynamic_cast<uhdr_decoder_private*>(dec);
+  if (!handle->m_probed || handle->m_probe_call_status.error_code != UHDR_CODEC_OK) {
+    return nullptr;
+  }
+
+  return &handle->m_gainmap_img_block;
+}
+
+uhdr_gainmap_metadata_t* uhdr_dec_get_gainmap_metadata(uhdr_codec_private_t* dec) {
   if (dynamic_cast<uhdr_decoder_private*>(dec) == nullptr) {
     return nullptr;
   }
@@ -1622,7 +1656,7 @@ uhdr_raw_image_t* uhdr_get_decoded_image(uhdr_codec_private_t* dec) {
   return handle->m_decoded_img_buffer.get();
 }
 
-uhdr_raw_image_t* uhdr_get_gain_map_image(uhdr_codec_private_t* dec) {
+uhdr_raw_image_t* uhdr_get_decoded_gainmap_image(uhdr_codec_private_t* dec) {
   if (dynamic_cast<uhdr_decoder_private*>(dec) == nullptr) {
     return nullptr;
   }
@@ -1665,6 +1699,10 @@ void uhdr_reset_decoder(uhdr_codec_private_t* dec) {
     memset(&handle->m_exif_block, 0, sizeof handle->m_exif_block);
     handle->m_icc.clear();
     memset(&handle->m_icc_block, 0, sizeof handle->m_icc_block);
+    handle->m_base_img.clear();
+    memset(&handle->m_base_img_block, 0, sizeof handle->m_base_img_block);
+    handle->m_gainmap_img.clear();
+    memset(&handle->m_gainmap_img_block, 0, sizeof handle->m_gainmap_img_block);
     memset(&handle->m_metadata, 0, sizeof handle->m_metadata);
     handle->m_probe_call_status = g_no_error;
     handle->m_decode_call_status = g_no_error;

ultrahdr_api.h

@@ -44,6 +44,32 @@
 #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.
+ */
+// This needs to be kept in sync with version in CMakeLists.txt
+#define UHDR_LIB_VERSION "1.1.1"
+
 // ===============================================================================================
 // Enum Definitions
 // ===============================================================================================
@@ -361,20 +387,20 @@ uhdr_enc_set_using_multi_channel_gainmap(uhdr_codec_private_t* enc, int use_mult
 
 /*!\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, gain_map_scale_factor = 2 implies gainmap_image_width =
+ * 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 4.
  * NOTE: This has no effect on base image rendition. Base image is signalled in full resolution
  * always.
  *
  * \param[in]  enc  encoder instance.
- * \param[in]  gain_map_scale_factor  gain map scale factor. Any integer in range (0, 128]
+ * \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 gain_map_scale_factor);
+                                                                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.
@@ -669,13 +695,31 @@ UHDR_EXTERN uhdr_mem_block_t* uhdr_dec_get_exif(uhdr_codec_private_t* dec);
  */
 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_gain_map_metadata(uhdr_codec_private_t* dec);
+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
@@ -722,7 +766,7 @@ UHDR_EXTERN uhdr_raw_image_t* uhdr_get_decoded_image(uhdr_codec_private_t* dec);
  *
  * \return nullptr if decoded process call is unsuccessful, raw image descriptor otherwise
  */
-UHDR_EXTERN uhdr_raw_image_t* uhdr_get_gain_map_image(uhdr_codec_private_t* dec);
+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