Source code
Revision control
Copy as Markdown
Other Tools
/* Copyright (c) the JPEG XL Project Authors. All rights reserved.
*
* Use of this source code is governed by a BSD-style
* license that can be found in the LICENSE file.
*/
/** @addtogroup libjxl_metadata
* @{
* @file gain_map.h
* @brief Utility functions to manipulate jhgm (gain map) boxes.
*/
#ifndef JXL_GAIN_MAP_H_
#define JXL_GAIN_MAP_H_
#include <jxl/color_encoding.h>
#include <jxl/jxl_export.h>
#include <jxl/types.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* Gain map bundle
*
* This structure is used to serialize gain map data to and from an input
* buffer. It holds pointers to sections within the buffer, and different parts
* of the gain map data such as metadata, ICC profile data, and the gain map
* itself.
*
* The pointers in this structure do not take ownership of the memory they point
* to. Instead, they reference specific locations within the provided buffer. It
* is the caller's responsibility to ensure that the buffer remains valid and is
* not deallocated as long as these pointers are in use. The structure should be
* considered as providing a view into the buffer, not as an owner of the data.
*/
typedef struct {
/** Version number of the gain map bundle. */
uint8_t jhgm_version;
/** Size of the gain map metadata in bytes. */
uint16_t gain_map_metadata_size;
/** Pointer to the gain map metadata, which is a binary
* blob following ISO 21496-1. This pointer references data within the input
* buffer. */
const uint8_t* gain_map_metadata;
/** Indicates whether a color encoding is present. */
JXL_BOOL has_color_encoding;
/** If has_color_encoding is true, this field contains the
* uncompressed color encoding data. */
JxlColorEncoding color_encoding;
/** Size of the alternative ICC profile in bytes (compressed
* size). */
uint32_t alt_icc_size;
/** Pointer to the compressed ICC profile. This pointer references
* data within the input buffer. */
const uint8_t* alt_icc;
/** Size of the gain map in bytes. */
uint32_t gain_map_size;
/** Pointer to the gain map data, which is a JPEG XL naked
* codestream. This pointer references data within the input buffer.*/
const uint8_t* gain_map;
} JxlGainMapBundle;
/**
* Calculates the total size required to serialize the gain map bundle into a
* binary buffer. This function accounts for all the necessary space to
* serialize fields such as gain map metadata, color encoding, compressed ICC
* profile data, and the gain map itself.
*
* @param[in] map_bundle Pointer to the JxlGainMapBundle containing all
* necessary data to compute the size.
* @param[out] bundle_size The size in bytes required to serialize the bundle.
* @return Whether setting the size was successful.
*/
JXL_EXPORT JXL_BOOL JxlGainMapGetBundleSize(const JxlGainMapBundle* map_bundle,
size_t* bundle_size);
/**
* Serializes the gain map bundle into a preallocated buffer. The function
* ensures that all parts of the bundle such as metadata, color encoding,
* compressed ICC profile, and the gain map are correctly encoded into the
* buffer. First call `JxlGainMapGetBundleSize` to get the size needed for
* the buffer.
*
* @param[in] map_bundle Pointer to the `JxlGainMapBundle` to serialize.
* @param[out] output_buffer Pointer to the buffer where the serialized data
* will be written.
* @param[in] output_buffer_size The size of the output buffer in bytes. Must be
* large enough to hold the entire serialized data.
* @param[out] bytes_written The number of bytes written to the output buffer.
* @return Whether writing the bundle was successful.
*/
JXL_EXPORT JXL_BOOL JxlGainMapWriteBundle(const JxlGainMapBundle* map_bundle,
uint8_t* output_buffer,
size_t output_buffer_size,
size_t* bytes_written);
/**
* Deserializes a gain map bundle from a provided buffer and populates a
* `JxlGainMapBundle` structure with the data extracted. This function assumes
* the buffer contains a valid serialized gain map bundle. After successful
* execution, the `JxlGainMapBundle` structure will reference three different
* sections within the buffer:
* - gain_map_metadata
* - alt_icc
* - gain_map
* These sections will be accompanied by their respective sizes. Users must
* ensure that the buffer remains valid as long as these pointers are in use.
* @param[in,out] map_bundle Pointer to a preallocated `JxlGainMapBundle` where
* the deserialized data will be stored.
* @param[in] input_buffer Pointer to the buffer containing the serialized gain
* map bundle data.
* @param[in] input_buffer_size The size of the input buffer in bytes.
* @param[out] bytes_read The number of bytes read from the input buffer.
* @return Whether reading the bundle was successful.
*/
JXL_EXPORT JXL_BOOL JxlGainMapReadBundle(JxlGainMapBundle* map_bundle,
const uint8_t* input_buffer,
size_t input_buffer_size,
size_t* bytes_read);
#ifdef __cplusplus
}
#endif
#endif /* JXL_GAIN_MAP_H_ */
/** @} */