jpegxl_sys\metadata/
gain_map.rs

1/*
2This file is part of jpegxl-sys.
3
4jpegxl-sys is free software: you can redistribute it and/or modify
5it under the terms of the GNU General Public License as published by
6the Free Software Foundation, either version 3 of the License, or
7(at your option) any later version.
8
9jpegxl-sys is distributed in the hope that it will be useful,
10but WITHOUT ANY WARRANTY; without even the implied warranty of
11MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12GNU General Public License for more details.
13
14You should have received a copy of the GNU General Public License
15along with jpegxl-sys.  If not, see <https://www.gnu.org/licenses/>.
16*/
17
18//! Utility functions to manipulate jhgm (gain map) boxes.
19
20use crate::{color::color_encoding::JxlColorEncoding, common::types::JxlBool};
21
22/// Gain map bundle
23///
24/// This structure is used to serialize gain map data to and from an input
25/// buffer. It holds pointers to sections within the buffer, and different parts
26/// of the gain map data such as metadata, ICC profile data, and the gain map
27/// itself.
28///
29/// The pointers in this structure do not take ownership of the memory they point
30/// to. Instead, they reference specific locations within the provided buffer. It
31/// is the caller's responsibility to ensure that the buffer remains valid and is
32/// not deallocated as long as these pointers are in use. The structure should be
33/// considered as providing a view into the buffer, not as an owner of the data.
34#[repr(C)]
35#[derive(Debug, Clone)]
36pub struct JxlGainMapBundle {
37    /// Version number of the gain map bundle.
38    pub jhgm_version: u8,
39    /// Size of the gain map metadata in bytes.
40    pub gain_map_metadata_size: u16,
41    /// Pointer to the gain map metadata, which is a binary
42    /// blob following ISO 21496-1. This pointer references data within the input
43    /// buffer.
44    pub gain_map_metadata: *const u8,
45    /// Indicates whether a color encoding is present.
46    pub has_color_encoding: JxlBool,
47    /// If `has_color_encoding` is true, this field contains the
48    /// uncompressed color encoding data.
49    pub color_encoding: JxlColorEncoding,
50    /// Size of the alternative ICC profile in bytes (compressed
51    /// size).
52    pub alt_icc_size: u32,
53    /// Pointer to the compressed ICC profile. This pointer references
54    /// data within the input buffer.
55    pub alt_icc: *const u8,
56    /// Size of the gain map in bytes.
57    pub gain_map_size: u32,
58    /// Pointer to the gain map data, which is a JPEG XL naked
59    /// codestream. This pointer references data within the input buffer.
60    pub gain_map: *const u8,
61}
62
63extern "C-unwind" {
64    /// Calculates the total size required to serialize the gain map bundle into a
65    /// binary buffer. This function accounts for all the necessary space to
66    /// serialize fields such as gain map metadata, color encoding, compressed ICC
67    /// profile data, and the gain map itself.
68    ///
69    /// # Parameters
70    /// - `map_bundle`: A reference to the [`JxlGainMapBundle`] containing all
71    ///   necessary data to compute the size.
72    /// - `bundle_size`: A mutable reference to a `usize` where the size in bytes
73    ///   required to serialize the bundle will be stored.
74    ///
75    /// # Returns
76    /// - A boolean indicating whether setting the size was successful.
77    pub fn JxlGainMapGetBundleSize(
78        map_bundle: *const JxlGainMapBundle,
79        bundle_size: *mut usize,
80    ) -> JxlBool;
81
82    /// Serializes the gain map bundle into a preallocated buffer. The function
83    /// ensures that all parts of the bundle such as metadata, color encoding,
84    /// compressed ICC profile, and the gain map are correctly encoded into the
85    /// buffer. First call [`JxlGainMapGetBundleSize`] to get the size needed for
86    /// the buffer.
87    ///
88    /// # Parameters
89    /// - `map_bundle`: A pointer to the [`JxlGainMapBundle`] to serialize.
90    /// - `output_buffer`: A pointer to the buffer where the serialized data
91    ///   will be written.
92    /// - `output_buffer_size`: The size of the output buffer in bytes. Must be
93    ///   large enough to hold the entire serialized data.
94    /// - `bytes_written`: A mutable reference to a `usize` where the number of bytes
95    ///   written to the output buffer will be stored.
96    ///
97    /// # Returns
98    /// - A boolean indicating whether writing the bundle was successful.
99    pub fn JxlGainMapWriteBundle(
100        map_bundle: *const JxlGainMapBundle,
101        output_buffer: *mut u8,
102        output_buffer_size: usize,
103        bytes_written: *mut usize,
104    ) -> JxlBool;
105
106    /// Deserializes a gain map bundle from a provided buffer and populates a
107    /// [`JxlGainMapBundle`] structure with the data extracted. This function assumes
108    /// the buffer contains a valid serialized gain map bundle. After successful
109    /// execution, the [`JxlGainMapBundle`] structure will reference three different
110    /// sections within the buffer:
111    ///  - `gain_map_metadata`
112    ///  - `alt_icc`
113    ///  - `gain_map`
114    ///
115    /// These sections will be accompanied by their respective sizes. Users must
116    /// ensure that the buffer remains valid as long as these pointers are in use.
117    ///
118    /// # Parameters
119    /// - `map_bundle`: Pointer to a preallocated [`JxlGainMapBundle`] where
120    ///   the deserialized data will be stored.
121    /// - `input_buffer`: Pointer to the buffer containing the serialized gain
122    ///   map bundle data.
123    /// - `input_buffer_size`: The size of the input buffer in bytes.
124    /// - `bytes_read`: The number of bytes read from the input buffer.
125    ///
126    /// # Returns
127    /// - A boolean indicating whether reading the bundle was successful.
128    pub fn JxlGainMapReadBundle(
129        map_bundle: *mut JxlGainMapBundle,
130        input_buffer: *const u8,
131        input_buffer_size: usize,
132        bytes_read: *mut usize,
133    ) -> JxlBool;
134}
jpegxl_sys\metadata/gain_map.rs

jpegxl_sys\metadata/
gain_map.rs
