HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
openexr_attr.h
Go to the documentation of this file.
1 /*
2 ** SPDX-License-Identifier: BSD-3-Clause
3 ** Copyright Contributors to the OpenEXR Project.
4 */
5 
6 #ifndef OPENEXR_ATTR_H
7 #define OPENEXR_ATTR_H
8 
9 #include "openexr_context.h"
10 
11 #include <stddef.h>
12 #include <stdint.h>
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 /** @file */
19 
20 /**
21  * @defgroup AttributeTypes Attribute/metadata value types and struct declarations
22  *
23  * @brief These are a group of enum values defining valid values for
24  * some attributes and then associated structs for other types.
25  *
26  * Some of these types will be directly representable/storable in
27  * the file, some not. There is some overlap here with Imath, and they
28  * should be kept in the same order for compatibility. However do note
29  * that these are just the raw data, and no useful functions are
30  * declared at this layer, that is what Imath is for.
31  *
32  * @{
33  */
34 
35 /** Enum declaring allowed values for \c uint8_t value stored in built-in compression type. */
36 typedef enum
37 {
48  EXR_COMPRESSION_LAST_TYPE /**< Invalid value, provided for range checking. */
50 
51 /** Enum declaring allowed values for \c uint8_t value stored in built-in env map type. */
52 typedef enum
53 {
56  EXR_ENVMAP_LAST_TYPE /**< Invalid value, provided for range checking. */
57 } exr_envmap_t;
58 
59 /** Enum declaring allowed values for \c uint8_t value stored in \c lineOrder type. */
60 typedef enum
61 {
65  EXR_LINEORDER_LAST_TYPE /**< Invalid value, provided for range checking. */
67 
68 /** Enum declaring allowed values for part type. */
69 typedef enum
70 {
71  EXR_STORAGE_SCANLINE = 0, /**< Corresponds to type of \c scanlineimage. */
72  EXR_STORAGE_TILED, /**< Corresponds to type of \c tiledimage. */
73  EXR_STORAGE_DEEP_SCANLINE, /**< Corresponds to type of \c deepscanline. */
74  EXR_STORAGE_DEEP_TILED, /**< Corresponds to type of \c deeptile. */
75  EXR_STORAGE_LAST_TYPE, /**< Invalid value, provided for range checking. */
76  EXR_STORAGE_UNKNOWN /**< An unknown type, provided for future proofing. */
78 
79 /** @brief Enum representing what type of tile information is contained. */
80 typedef enum
81 {
82  EXR_TILE_ONE_LEVEL = 0, /**< Single level of image data. */
83  EXR_TILE_MIPMAP_LEVELS = 1, /**< Mipmapped image data. */
84  EXR_TILE_RIPMAP_LEVELS = 2, /**< Ripmapped image data. */
85  EXR_TILE_LAST_TYPE /**< Invalid value, provided for range checking. */
87 
88 /** @brief Enum representing how to scale positions between levels. */
89 typedef enum
90 {
95 
96 /** @brief Enum capturing the underlying data type on a channel. */
97 typedef enum
98 {
104 
105 /** Enum declaring allowed values for \c uint8_t value stored in \c deepImageState type. */
106 typedef enum
107 {
112  EXR_DIS_LAST_TYPE /**< Invalid value, provided for range checking. */
114 
115 /* /////////////////////////////////////// */
116 /* First set of structs are data where we can read directly with no allocation needed... */
117 
118 /* Most are naturally aligned, but force some of these
119  * structs to be tightly packed
120  */
121 #pragma pack(push, 1)
122 
123 /** @brief Struct to hold color chromaticities to interpret the tristimulus color values in the image data. */
124 typedef struct
125 {
126  float red_x;
127  float red_y;
128  float green_x;
129  float green_y;
130  float blue_x;
131  float blue_y;
132  float white_x;
133  float white_y;
135 
136 /** @brief Struct to hold keycode information. */
137 typedef struct
138 {
139  int32_t film_mfc_code;
140  int32_t film_type;
141  int32_t prefix;
142  int32_t count;
143  int32_t perf_offset;
147 
148 /** @brief struct to hold a 32-bit floating-point 3x3 matrix. */
149 typedef struct
150 {
151  float m[9];
153 
154 /** @brief struct to hold a 64-bit floating-point 3x3 matrix. */
155 typedef struct
156 {
157  double m[9];
159 
160 /** @brief Struct to hold a 32-bit floating-point 4x4 matrix. */
161 typedef struct
162 {
163  float m[16];
165 
166 /** @brief Struct to hold a 64-bit floating-point 4x4 matrix. */
167 typedef struct
168 {
169  double m[16];
171 
172 /** @brief Struct to hold an integer ratio value. */
173 typedef struct
174 {
175  int32_t num;
176  uint32_t denom;
178 
179 /** @brief Struct to hold timecode information. */
180 typedef struct
181 {
182  uint32_t time_and_flags;
183  uint32_t user_data;
185 
186 /** @brief Struct to hold a 2-element integer vector. */
187 typedef struct
188 {
189  int32_t x, y;
191 
192 /** @brief Struct to hold a 2-element 32-bit float vector. */
193 typedef struct
194 {
195  float x, y;
197 
198 /** @brief Struct to hold a 2-element 64-bit float vector. */
199 typedef struct
200 {
201  double x, y;
203 
204 /** @brief Struct to hold a 3-element integer vector. */
205 typedef struct
206 {
207  int32_t x, y, z;
209 
210 /** @brief Struct to hold a 3-element 32-bit float vector. */
211 typedef struct
212 {
213  float x, y, z;
215 
216 /** @brief Struct to hold a 3-element 64-bit float vector. */
217 typedef struct
218 {
219  double x, y, z;
221 
222 /** @brief Struct to hold an integer box/region definition. */
223 typedef struct
224 {
228 
229 /** @brief Struct to hold a floating-point box/region definition. */
230 typedef struct
231 {
235 
236 /** @brief Struct holding base tiledesc attribute type defined in spec
237  *
238  * NB: This is in a tightly packed area so it can be read directly, be
239  * careful it doesn't become padded to the next \c uint32_t boundary.
240  */
241 typedef struct
242 {
243  uint32_t x_size;
244  uint32_t y_size;
247 
248 /** @brief Macro to access type of tiling from packed structure. */
249 #define EXR_GET_TILE_LEVEL_MODE(tiledesc) \
250  ((exr_tile_level_mode_t) (((tiledesc).level_and_round) & 0xF))
251 /** @brief Macro to access the rounding mode of tiling from packed structure. */
252 #define EXR_GET_TILE_ROUND_MODE(tiledesc) \
253  ((exr_tile_round_mode_t) ((((tiledesc).level_and_round) >> 4) & 0xF))
254 /** @brief Macro to pack the tiling type and rounding mode into packed structure. */
255 #define EXR_PACK_TILE_LEVEL_ROUND(lvl, mode) \
256  ((uint8_t) ((((uint8_t) ((mode) & 0xF) << 4)) | ((uint8_t) ((lvl) & 0xF))))
257 
258 #pragma pack(pop)
259 
260 /* /////////////////////////////////////// */
261 /* Now structs that involve heap allocation to store data. */
262 
263 /** Storage for a string. */
264 typedef struct
265 {
266  int32_t length;
267  /** If this is non-zero, the string owns the data, if 0, is a const ref to a static string. */
268  int32_t alloc_size;
269 
270  const char* str;
272 
273 /** Storage for a string vector. */
274 typedef struct
275 {
276  int32_t n_strings;
277  /** If this is non-zero, the string vector owns the data, if 0, is a const ref. */
278  int32_t alloc_size;
279 
282 
283 /** Float vector storage struct. */
284 typedef struct
285 {
286  int32_t length;
287  /** If this is non-zero, the float vector owns the data, if 0, is a const ref. */
288  int32_t alloc_size;
289 
290  const float* arr;
292 
293 /** Hint for lossy compression methods about how to treat values
294  * (logarithmic or linear), meaning a human sees values like R, G, B,
295  * luminance difference between 0.1 and 0.2 as about the same as 1.0
296  * to 2.0 (logarithmic), where chroma coordinates are closer to linear
297  * (0.1 and 0.2 is about the same difference as 1.0 and 1.1).
298  */
299 typedef enum
300 {
304 
305 /** Individual channel information. */
306 typedef struct
307 {
309  /** Data representation for these pixels: uint, half, float. */
311  /** Possible values are 0 and 1 per docs exr_perceptual_treatment_t. */
312  uint8_t p_linear;
313  uint8_t reserved[3];
314  int32_t x_sampling;
315  int32_t y_sampling;
317 
318 /** List of channel information (sorted alphabetically). */
319 typedef struct
320 {
323 
326 
327 /** @brief Struct to define attributes of an embedded preview image. */
328 typedef struct
329 {
330  uint32_t width;
331  uint32_t height;
332  /** If this is non-zero, the preview owns the data, if 0, is a const ref. */
333  size_t alloc_size;
334 
335  const uint8_t* rgba;
337 
338 /** Custom storage structure for opaque data.
339  *
340  * Handlers for opaque types can be registered, then when a
341  * non-builtin type is encountered with a registered handler, the
342  * function pointers to unpack/pack it will be set up.
343  *
344  * @sa exr_register_attr_type_handler
345  */
346 typedef struct
347 {
348  int32_t size;
349  int32_t unpacked_size;
350  /** If this is non-zero, the struct owns the data, if 0, is a const ref. */
352  uint8_t pad[4];
353 
354  void* packed_data;
355 
356  /** When an application wants to have custom data, they can store
357  * an unpacked form here which will be requested to be destroyed
358  * upon destruction of the attribute.
359  */
361 
362  /** An application can register an attribute handler which then
363  * fills in these function pointers. This allows a user to delay
364  * the expansion of the custom type until access is desired, and
365  * similarly, to delay the packing of the data until write time.
366  */
367  exr_result_t (*unpack_func_ptr) (
368  exr_context_t ctxt,
369  const void* data,
370  int32_t attrsize,
371  int32_t* outsize,
372  void** outbuffer);
373  exr_result_t (*pack_func_ptr) (
374  exr_context_t ctxt,
375  const void* data,
376  int32_t datasize,
377  int32_t* outsize,
378  void* outbuffer);
379  void (*destroy_unpacked_func_ptr) (
380  exr_context_t ctxt, void* data, int32_t attrsize);
382 
383 /* /////////////////////////////////////// */
384 
385 /** @brief Built-in/native attribute type enum.
386  *
387  * This will enable us to do a tagged type struct to generically store
388  * attributes.
389  */
390 typedef enum
391 {
393  0, /**< Type indicating an error or uninitialized attribute. */
394  EXR_ATTR_BOX2I, /**< Integer region definition. @see exr_attr_box2i_t. */
395  EXR_ATTR_BOX2F, /**< Float region definition. @see exr_attr_box2f_t. */
396  EXR_ATTR_CHLIST, /**< Definition of channels in file @see exr_chlist_entry. */
397  EXR_ATTR_CHROMATICITIES, /**< Values to specify color space of colors in file @see exr_attr_chromaticities_t. */
398  EXR_ATTR_COMPRESSION, /**< ``uint8_t`` declaring compression present. */
399  EXR_ATTR_DOUBLE, /**< Double precision floating point number. */
400  EXR_ATTR_ENVMAP, /**< ``uint8_t`` declaring environment map type. */
401  EXR_ATTR_FLOAT, /**< Normal (4 byte) precision floating point number. */
402  EXR_ATTR_FLOAT_VECTOR, /**< List of normal (4 byte) precision floating point numbers. */
403  EXR_ATTR_INT, /**< 32-bit signed integer value. */
404  EXR_ATTR_KEYCODE, /**< Struct recording keycode @see exr_attr_keycode_t. */
405  EXR_ATTR_LINEORDER, /**< ``uint8_t`` declaring scanline ordering. */
406  EXR_ATTR_M33F, /**< 9 32-bit floats representing a 3x3 matrix. */
407  EXR_ATTR_M33D, /**< 9 64-bit floats representing a 3x3 matrix. */
408  EXR_ATTR_M44F, /**< 16 32-bit floats representing a 4x4 matrix. */
409  EXR_ATTR_M44D, /**< 16 64-bit floats representing a 4x4 matrix. */
410  EXR_ATTR_PREVIEW, /**< 2 ``unsigned ints`` followed by 4 x w x h ``uint8_t`` image. */
411  EXR_ATTR_RATIONAL, /**< \c int followed by ``unsigned int`` */
412  EXR_ATTR_STRING, /**< ``int`` (length) followed by char string data. */
413  EXR_ATTR_STRING_VECTOR, /**< 0 or more text strings (int + string). number is based on attribute size. */
414  EXR_ATTR_TILEDESC, /**< 2 ``unsigned ints`` ``xSize``, ``ySize`` followed by mode. */
415  EXR_ATTR_TIMECODE, /**< 2 ``unsigned ints`` time and flags, user data. */
416  EXR_ATTR_V2I, /**< Pair of 32-bit integers. */
417  EXR_ATTR_V2F, /**< Pair of 32-bit floats. */
418  EXR_ATTR_V2D, /**< Pair of 64-bit floats. */
419  EXR_ATTR_V3I, /**< Set of 3 32-bit integers. */
420  EXR_ATTR_V3F, /**< Set of 3 32-bit floats. */
421  EXR_ATTR_V3D, /**< Set of 3 64-bit floats. */
422  EXR_ATTR_DEEP_IMAGE_STATE, /**< ``uint8_t`` declaring deep image state. */
423  EXR_ATTR_OPAQUE, /**< User/unknown provided type. */
426 
427 /** @brief Storage, name and type information for an attribute.
428  *
429  * Attributes (metadata) for the file cause a surprising amount of
430  * overhead. It is not uncommon for a production-grade EXR to have
431  * many attributes. As such, the attribute struct is designed in a
432  * slightly more complicated manner. It is optimized to have the
433  * storage for that attribute: the struct itself, the name, the type,
434  * and the data all allocated as one block. Further, the type and
435  * standard names may use a static string to avoid allocating space
436  * for those as necessary with the pointers pointing to static strings
437  * (not to be freed). Finally, small values are optimized for.
438  */
439 typedef struct
440 {
441  /** Name of the attribute. */
442  const char* name;
443  /** String type name of the attribute. */
444  const char* type_name;
445  /** Length of name string (short flag is 31 max, long allows 255). */
446  uint8_t name_length;
447  /** Length of type string (short flag is 31 max, long allows 255). */
449 
450  uint8_t pad[2];
451 
452  /** Enum of the attribute type. */
454 
455  /** Union of pointers of different types that can be used to type
456  * pun to an appropriate type for builtins. Do note that while
457  * this looks like a big thing, it is only the size of a single
458  * pointer. These are all pointers into some other data block
459  * storing the value you want, with the exception of the pod types
460  * which are just put in place (i.e. small value optimization).
461  *
462  * The attribute type \c type should directly correlate to one
463  * of these entries.
464  */
465  union
466  {
467  // NB: not pointers for POD types
468  uint8_t uc;
469  double d;
470  float f;
471  int32_t i;
472 
496  uint8_t* rawptr;
497  };
499 
500 /** @} */
501 
502 #ifdef __cplusplus
503 } /* extern "C" */
504 #endif
505 
506 #endif /* OPENEXR_ATTR_H */
exr_attr_timecode_t * timecode
Definition: openexr_attr.h:488
exr_attr_v2f_t max
Definition: openexr_attr.h:233
exr_attr_v2f_t * v2f
Definition: openexr_attr.h:490
Struct to hold a floating-point box/region definition.
Definition: openexr_attr.h:230
uint8_t name_length
Definition: openexr_attr.h:446
Struct to hold an integer box/region definition.
Definition: openexr_attr.h:223
const char * str
Definition: openexr_attr.h:270
Struct holding base tiledesc attribute type defined in spec.
Definition: openexr_attr.h:241
exr_attr_v3f_t * v3f
Definition: openexr_attr.h:493
exr_pixel_type_t pixel_type
Definition: openexr_attr.h:310
void
Definition: png.h:1083
GLboolean * data
Definition: glcorearb.h:131
exr_attr_v2f_t min
Definition: openexr_attr.h:232
Struct to hold an integer ratio value.
Definition: openexr_attr.h:173
exr_attr_m33f_t * m33f
Definition: openexr_attr.h:479
exr_attr_float_vector_t * floatvector
Definition: openexr_attr.h:478
Struct to hold a 3-element integer vector.
Definition: openexr_attr.h:205
exr_perceptual_treatment_t
Definition: openexr_attr.h:299
Struct to hold a 3-element 32-bit float vector.
Definition: openexr_attr.h:211
GLint y
Definition: glcorearb.h:103
Struct to hold a 64-bit floating-point 4x4 matrix.
Definition: openexr_attr.h:167
exr_lineorder_t
Definition: openexr_attr.h:60
void pad(T &out, int n)
Definition: ImfXdr.h:407
const exr_attr_string_t * strings
Definition: openexr_attr.h:280
uint8_t p_linear
Definition: openexr_attr.h:312
uint8_t type_name_length
Definition: openexr_attr.h:448
const char * name
Definition: openexr_attr.h:442
exr_attr_v2i_t * v2i
Definition: openexr_attr.h:489
uint8_t * rawptr
Definition: openexr_attr.h:496
Struct to hold a 32-bit floating-point 4x4 matrix.
Definition: openexr_attr.h:161
const uint8_t * rgba
Definition: openexr_attr.h:335
exr_attr_v3i_t * v3i
Definition: openexr_attr.h:492
exr_attr_tiledesc_t * tiledesc
Definition: openexr_attr.h:487
exr_attr_preview_t * preview
Definition: openexr_attr.h:483
exr_attr_m44d_t * m44d
Definition: openexr_attr.h:482
int32_t exr_result_t
exr_deep_image_state_t
Definition: openexr_attr.h:106
exr_tile_level_mode_t
Enum representing what type of tile information is contained.
Definition: openexr_attr.h:80
struct _priv_exr_context_t * exr_context_t
struct to hold a 64-bit floating-point 3x3 matrix.
Definition: openexr_attr.h:155
exr_attr_v2i_t max
Definition: openexr_attr.h:226
exr_attr_keycode_t * keycode
Definition: openexr_attr.h:477
const exr_attr_chlist_entry_t * entries
Definition: openexr_attr.h:324
Struct to hold a 2-element 64-bit float vector.
Definition: openexr_attr.h:199
exr_attr_m33d_t * m33d
Definition: openexr_attr.h:480
GLint GLenum GLint x
Definition: glcorearb.h:409
exr_attr_string_vector_t * stringvector
Definition: openexr_attr.h:486
exr_attr_box2i_t * box2i
Definition: openexr_attr.h:473
exr_compression_t
Definition: openexr_attr.h:36
exr_attr_m44f_t * m44f
Definition: openexr_attr.h:481
exr_attr_chlist_t * chlist
Definition: openexr_attr.h:475
exr_attr_string_t * string
Definition: openexr_attr.h:485
Struct to define attributes of an embedded preview image.
Definition: openexr_attr.h:328
struct to hold a 32-bit floating-point 3x3 matrix.
Definition: openexr_attr.h:149
exr_tile_round_mode_t
Enum representing how to scale positions between levels.
Definition: openexr_attr.h:89
exr_attr_box2f_t * box2f
Definition: openexr_attr.h:474
exr_storage_t
Definition: openexr_attr.h:69
exr_attr_rational_t * rational
Definition: openexr_attr.h:484
exr_envmap_t
Definition: openexr_attr.h:52
exr_attr_v2d_t * v2d
Definition: openexr_attr.h:491
Struct to hold timecode information.
Definition: openexr_attr.h:180
int32_t x_sampling
Definition: openexr_attr.h:314
Storage, name and type information for an attribute.
Definition: openexr_attr.h:439
Struct to hold a 2-element integer vector.
Definition: openexr_attr.h:187
Struct to hold a 2-element 32-bit float vector.
Definition: openexr_attr.h:193
int32_t y_sampling
Definition: openexr_attr.h:315
exr_attr_v2i_t min
Definition: openexr_attr.h:225
exr_attr_v3d_t * v3d
Definition: openexr_attr.h:494
exr_attr_chromaticities_t * chromaticities
Definition: openexr_attr.h:476
Struct to hold keycode information.
Definition: openexr_attr.h:137
Struct to hold color chromaticities to interpret the tristimulus color values in the image data...
Definition: openexr_attr.h:124
const char * type_name
Definition: openexr_attr.h:444
Definition: openexr_attr.h:306
exr_attribute_type_t type
Definition: openexr_attr.h:453
exr_attribute_type_t
Built-in/native attribute type enum.
Definition: openexr_attr.h:390
exr_attr_string_t name
Definition: openexr_attr.h:308
exr_pixel_type_t
Enum capturing the underlying data type on a channel.
Definition: openexr_attr.h:97
Struct to hold a 3-element 64-bit float vector.
Definition: openexr_attr.h:217
exr_attr_opaquedata_t * opaque
Definition: openexr_attr.h:495