1 /*
2 ** SPDX-License-Identifier: BSD-3-Clause
3 ** Copyright Contributors to the OpenEXR Project.
4 */
5 
6 #ifndef OPENEXR_CORE_CODING_H
7 #define OPENEXR_CORE_CODING_H
8 
9 #include <stdint.h>
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 /** @file */
16 
17 /**
18  * Enum for use in a custom allocator in the encode/decode pipelines
19  * (that is, so the implementor knows whether to allocate on which
20  * device based on the buffer disposition).
21  */
22 typedef enum exr_transcoding_pipeline_buffer_id
23 {
24     EXR_TRANSCODE_BUFFER_PACKED,
25     EXR_TRANSCODE_BUFFER_UNPACKED,
26     EXR_TRANSCODE_BUFFER_COMPRESSED,
27     EXR_TRANSCODE_BUFFER_SCRATCH1,
28     EXR_TRANSCODE_BUFFER_SCRATCH2,
29     EXR_TRANSCODE_BUFFER_PACKED_SAMPLES,
30     EXR_TRANSCODE_BUFFER_SAMPLES
31 } exr_transcoding_pipeline_buffer_id_t;
32 
33 /** @brief Struct for negotiating buffers when decoding/encoding
34  * chunks of data.
35  *
36  * This is generic and meant to negotiate exr data bi-directionally,
37  * in that the same structure is used for both decoding and encoding
38  * chunks for read and write, respectively.
39  *
40  * The first half of the structure will be filled by the library, and
41  * the caller is expected to fill the second half appropriately.
42  */
43 typedef struct
44 {
45     /**************************************************
46      * Elements below are populated by the library when
47      * decoding is initialized/updated and must be left
48      * untouched when using the default decoder routines.
49      **************************************************/
50 
51     /** Channel name.
52      *
53      * This is provided as a convenient reference. Do not free, this
54      * refers to the internal data structure in the context.
55      */
56     const char* channel_name;
57 
58     /** Number of lines for this channel in this chunk.
59      *
60      * May be 0 or less than overall image height based on sampling
61      * (i.e. when in 4:2:0 type sampling)
62      */
63     int32_t height;
64 
65     /** Width in pixel count.
66      *
67      * May be 0 or less than overall image width based on sampling
68      * (i.e. 4:2:2 will have some channels have fewer values).
69      */
70     int32_t width;
71 
72     /** Horizontal subsampling information. */
73     int32_t x_samples;
74     /** Vertical subsampling information. */
75     int32_t y_samples;
76 
77     /** Linear flag from channel definition (used by b44). */
78     uint8_t p_linear;
79 
80     /** How many bytes per pixel this channel consumes (2 for float16,
81      * 4 for float32/uint32).
82      */
83     int8_t bytes_per_element;
84 
85     /** Small form of exr_pixel_type_t enum (EXR_PIXEL_UINT/HALF/FLOAT). */
86     uint16_t data_type;
87 
88     /**************************************************
89      * Elements below must be edited by the caller
90      * to control encoding/decoding.
91      **************************************************/
92 
93     /** How many bytes per pixel the input is or output should be
94      * (2 for float16, 4 for float32/uint32). Defaults to same
95      * size as input.
96      */
97     int16_t user_bytes_per_element;
98 
99     /** Small form of exr_pixel_type_t enum
100      * (EXR_PIXEL_UINT/HALF/FLOAT). Defaults to same type as input.
101      */
102     uint16_t user_data_type;
103 
104     /** Increment to get to next pixel.
105      *
106      * This is in bytes. Must be specified when the decode pointer is
107      * specified (and always for encode).
108      *
109      * This is useful for implementing transcoding generically of
110      * planar or interleaved data. For planar data, where the layout
111      * is RRRRRGGGGGBBBBB, you can pass in 1 * bytes per component.
112      */
113 
114     int32_t user_pixel_stride;
115 
116     /** When \c lines > 1 for a chunk, this is the increment used to get
117      * from beginning of line to beginning of next line.
118      *
119      * This is in bytes. Must be specified when the decode pointer is
120      * specified (and always for encode).
121      */
122     int32_t user_line_stride;
123 
124     /** This data member has different requirements reading vs
125      * writing. When reading, if this is left as `NULL`, the channel
126      * will be skipped during read and not filled in.  During a write
127      * operation, this pointer is considered const and not
128      * modified. To make this more clear, a union is used here.
129      */
130     union
131     {
132         uint8_t*       decode_to_ptr;
133         const uint8_t* encode_from_ptr;
134     };
135 } exr_coding_channel_info_t;
136 
137 #ifdef __cplusplus
138 } /* extern "C" */
139 #endif
140 
141 #endif /* OPENEXR_CORE_CODING_H */
142