gain_map.h (5260B)
1 /* Copyright (c) the JPEG XL Project Authors. All rights reserved. 2 * 3 * Use of this source code is governed by a BSD-style 4 * license that can be found in the LICENSE file. 5 */ 6 7 /** @addtogroup libjxl_metadata 8 * @{ 9 * @file gain_map.h 10 * @brief Utility functions to manipulate jhgm (gain map) boxes. 11 */ 12 13 #ifndef JXL_GAIN_MAP_H_ 14 #define JXL_GAIN_MAP_H_ 15 16 #include <jxl/color_encoding.h> 17 #include <jxl/jxl_export.h> 18 #include <jxl/types.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** 25 * Gain map bundle 26 * 27 * This structure is used to serialize gain map data to and from an input 28 * buffer. It holds pointers to sections within the buffer, and different parts 29 * of the gain map data such as metadata, ICC profile data, and the gain map 30 * itself. 31 * 32 * The pointers in this structure do not take ownership of the memory they point 33 * to. Instead, they reference specific locations within the provided buffer. It 34 * is the caller's responsibility to ensure that the buffer remains valid and is 35 * not deallocated as long as these pointers are in use. The structure should be 36 * considered as providing a view into the buffer, not as an owner of the data. 37 */ 38 typedef struct { 39 /** Version number of the gain map bundle. */ 40 uint8_t jhgm_version; 41 /** Size of the gain map metadata in bytes. */ 42 uint16_t gain_map_metadata_size; 43 /** Pointer to the gain map metadata, which is a binary 44 * blob following ISO 21496-1. This pointer references data within the input 45 * buffer. */ 46 const uint8_t* gain_map_metadata; 47 /** Indicates whether a color encoding is present. */ 48 JXL_BOOL has_color_encoding; 49 /** If has_color_encoding is true, this field contains the 50 * uncompressed color encoding data. */ 51 JxlColorEncoding color_encoding; 52 /** Size of the alternative ICC profile in bytes (compressed 53 * size). */ 54 uint32_t alt_icc_size; 55 /** Pointer to the compressed ICC profile. This pointer references 56 * data within the input buffer. */ 57 const uint8_t* alt_icc; 58 /** Size of the gain map in bytes. */ 59 uint32_t gain_map_size; 60 /** Pointer to the gain map data, which is a JPEG XL naked 61 * codestream. This pointer references data within the input buffer.*/ 62 const uint8_t* gain_map; 63 } JxlGainMapBundle; 64 65 /** 66 * Calculates the total size required to serialize the gain map bundle into a 67 * binary buffer. This function accounts for all the necessary space to 68 * serialize fields such as gain map metadata, color encoding, compressed ICC 69 * profile data, and the gain map itself. 70 * 71 * @param[in] map_bundle Pointer to the JxlGainMapBundle containing all 72 * necessary data to compute the size. 73 * @param[out] bundle_size The size in bytes required to serialize the bundle. 74 * @return Whether setting the size was successful. 75 */ 76 JXL_EXPORT JXL_BOOL JxlGainMapGetBundleSize(const JxlGainMapBundle* map_bundle, 77 size_t* bundle_size); 78 79 /** 80 * Serializes the gain map bundle into a preallocated buffer. The function 81 * ensures that all parts of the bundle such as metadata, color encoding, 82 * compressed ICC profile, and the gain map are correctly encoded into the 83 * buffer. First call `JxlGainMapGetBundleSize` to get the size needed for 84 * the buffer. 85 * 86 * @param[in] map_bundle Pointer to the `JxlGainMapBundle` to serialize. 87 * @param[out] output_buffer Pointer to the buffer where the serialized data 88 * will be written. 89 * @param[in] output_buffer_size The size of the output buffer in bytes. Must be 90 * large enough to hold the entire serialized data. 91 * @param[out] bytes_written The number of bytes written to the output buffer. 92 * @return Whether writing the bundle was successful. 93 */ 94 JXL_EXPORT JXL_BOOL JxlGainMapWriteBundle(const JxlGainMapBundle* map_bundle, 95 uint8_t* output_buffer, 96 size_t output_buffer_size, 97 size_t* bytes_written); 98 99 /** 100 * Deserializes a gain map bundle from a provided buffer and populates a 101 * `JxlGainMapBundle` structure with the data extracted. This function assumes 102 * the buffer contains a valid serialized gain map bundle. After successful 103 * execution, the `JxlGainMapBundle` structure will reference three different 104 * sections within the buffer: 105 * - gain_map_metadata 106 * - alt_icc 107 * - gain_map 108 * These sections will be accompanied by their respective sizes. Users must 109 * ensure that the buffer remains valid as long as these pointers are in use. 110 * @param[in,out] map_bundle Pointer to a preallocated `JxlGainMapBundle` where 111 * the deserialized data will be stored. 112 * @param[in] input_buffer Pointer to the buffer containing the serialized gain 113 * map bundle data. 114 * @param[in] input_buffer_size The size of the input buffer in bytes. 115 * @param[out] bytes_read The number of bytes read from the input buffer. 116 * @return Whether reading the bundle was successful. 117 */ 118 JXL_EXPORT JXL_BOOL JxlGainMapReadBundle(JxlGainMapBundle* map_bundle, 119 const uint8_t* input_buffer, 120 size_t input_buffer_size, 121 size_t* bytes_read); 122 123 #ifdef __cplusplus 124 } 125 #endif 126 127 #endif /* JXL_GAIN_MAP_H_ */ 128 129 /** @} */