D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
include
/
OpenEXR
/
Filename :
openexr_attr.h
back
Copy
/* ** SPDX-License-Identifier: BSD-3-Clause ** Copyright Contributors to the OpenEXR Project. */ #ifndef OPENEXR_ATTR_H #define OPENEXR_ATTR_H #include "openexr_context.h" #include <stddef.h> #include <stdint.h> #ifdef __cplusplus extern "C" { #endif /** @file */ /** * @defgroup AttributeTypes Attribute/metadata value types and struct declarations * * @brief These are a group of enum values defining valid values for * some attributes and then associated structs for other types. * * Some of these types will be directly representable/storable in * the file, some not. There is some overlap here with Imath, and they * should be kept in the same order for compatibility. However do note * that these are just the raw data, and no useful functions are * declared at this layer, that is what Imath is for. * * @{ */ /** Enum declaring allowed values for \c uint8_t value stored in built-in compression type. */ typedef enum { EXR_COMPRESSION_NONE = 0, EXR_COMPRESSION_RLE = 1, EXR_COMPRESSION_ZIPS = 2, EXR_COMPRESSION_ZIP = 3, EXR_COMPRESSION_PIZ = 4, EXR_COMPRESSION_PXR24 = 5, EXR_COMPRESSION_B44 = 6, EXR_COMPRESSION_B44A = 7, EXR_COMPRESSION_DWAA = 8, EXR_COMPRESSION_DWAB = 9, EXR_COMPRESSION_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_compression_t; /** Enum declaring allowed values for \c uint8_t value stored in built-in env map type. */ typedef enum { EXR_ENVMAP_LATLONG = 0, EXR_ENVMAP_CUBE = 1, EXR_ENVMAP_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_envmap_t; /** Enum declaring allowed values for \c uint8_t value stored in \c lineOrder type. */ typedef enum { EXR_LINEORDER_INCREASING_Y = 0, EXR_LINEORDER_DECREASING_Y = 1, EXR_LINEORDER_RANDOM_Y = 2, EXR_LINEORDER_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_lineorder_t; /** Enum declaring allowed values for part type. */ typedef enum { EXR_STORAGE_SCANLINE = 0, /**< Corresponds to type of \c scanlineimage. */ EXR_STORAGE_TILED, /**< Corresponds to type of \c tiledimage. */ EXR_STORAGE_DEEP_SCANLINE, /**< Corresponds to type of \c deepscanline. */ EXR_STORAGE_DEEP_TILED, /**< Corresponds to type of \c deeptile. */ EXR_STORAGE_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_storage_t; /** @brief Enum representing what type of tile information is contained. */ typedef enum { EXR_TILE_ONE_LEVEL = 0, /**< Single level of image data. */ EXR_TILE_MIPMAP_LEVELS = 1, /**< Mipmapped image data. */ EXR_TILE_RIPMAP_LEVELS = 2, /**< Ripmapped image data. */ EXR_TILE_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_tile_level_mode_t; /** @brief Enum representing how to scale positions between levels. */ typedef enum { EXR_TILE_ROUND_DOWN = 0, EXR_TILE_ROUND_UP = 1, EXR_TILE_ROUND_LAST_TYPE } exr_tile_round_mode_t; /** @brief Enum capturing the underlying data type on a channel. */ typedef enum { EXR_PIXEL_UINT = 0, EXR_PIXEL_HALF = 1, EXR_PIXEL_FLOAT = 2, EXR_PIXEL_LAST_TYPE } exr_pixel_type_t; /* /////////////////////////////////////// */ /* First set of structs are data where we can read directly with no allocation needed... */ /* Most are naturally aligned, but force some of these * structs to be tightly packed */ #pragma pack(push, 1) /** @brief Struct to hold color chromaticities to interpret the tristimulus color values in the image data. */ typedef struct { float red_x; float red_y; float green_x; float green_y; float blue_x; float blue_y; float white_x; float white_y; } exr_attr_chromaticities_t; /** @brief Struct to hold keycode information. */ typedef struct { int32_t film_mfc_code; int32_t film_type; int32_t prefix; int32_t count; int32_t perf_offset; int32_t perfs_per_frame; int32_t perfs_per_count; } exr_attr_keycode_t; /** @brief struct to hold a 32-bit floating-point 3x3 matrix. */ typedef struct { float m[9]; } exr_attr_m33f_t; /** @brief struct to hold a 64-bit floating-point 3x3 matrix. */ typedef struct { double m[9]; } exr_attr_m33d_t; /** @brief Struct to hold a 32-bit floating-point 4x4 matrix. */ typedef struct { float m[16]; } exr_attr_m44f_t; /** @brief Struct to hold a 64-bit floating-point 4x4 matrix. */ typedef struct { double m[16]; } exr_attr_m44d_t; /** @brief Struct to hold an integer ratio value. */ typedef struct { int32_t num; uint32_t denom; } exr_attr_rational_t; /** @brief Struct to hold timecode information. */ typedef struct { uint32_t time_and_flags; uint32_t user_data; } exr_attr_timecode_t; /** @brief Struct to hold a 2-element integer vector. */ typedef struct { union { struct { int32_t x, y; }; int32_t arr[2]; }; } exr_attr_v2i_t; /** @brief Struct to hold a 2-element 32-bit float vector. */ typedef struct { union { struct { float x, y; }; float arr[2]; }; } exr_attr_v2f_t; /** @brief Struct to hold a 2-element 64-bit float vector. */ typedef struct { union { struct { double x, y; }; double arr[2]; }; } exr_attr_v2d_t; /** @brief Struct to hold a 3-element integer vector. */ typedef struct { union { struct { int32_t x, y, z; }; int32_t arr[3]; }; } exr_attr_v3i_t; /** @brief Struct to hold a 3-element 32-bit float vector. */ typedef struct { union { struct { float x, y, z; }; float arr[3]; }; } exr_attr_v3f_t; /** @brief Struct to hold a 3-element 64-bit float vector. */ typedef struct { union { struct { double x, y, z; }; double arr[3]; }; } exr_attr_v3d_t; /** @brief Struct to hold an integer box/region definition. */ typedef struct { exr_attr_v2i_t min; exr_attr_v2i_t max; } exr_attr_box2i_t; /** @brief Struct to hold a floating-point box/region definition. */ typedef struct { exr_attr_v2f_t min; exr_attr_v2f_t max; } exr_attr_box2f_t; /** @brief Struct holding base tiledesc attribute type defined in spec * * NB: This is in a tightly packed area so it can be read directly, be * careful it doesn't become padded to the next \c uint32_t boundary. */ typedef struct { uint32_t x_size; uint32_t y_size; uint8_t level_and_round; } exr_attr_tiledesc_t; /** @brief Macro to access type of tiling from packed structure. */ #define EXR_GET_TILE_LEVEL_MODE(tiledesc) \ ((exr_tile_level_mode_t) (((tiledesc).level_and_round) & 0xF)) /** @brief Macro to access the rounding mode of tiling from packed structure. */ #define EXR_GET_TILE_ROUND_MODE(tiledesc) \ ((exr_tile_round_mode_t) ((((tiledesc).level_and_round) >> 4) & 0xF)) /** @brief Macro to pack the tiling type and rounding mode into packed structure. */ #define EXR_PACK_TILE_LEVEL_ROUND(lvl, mode) \ ((uint8_t) ((((uint8_t) ((mode) &0xF) << 4)) | ((uint8_t) ((lvl) &0xF)))) #pragma pack(pop) /* /////////////////////////////////////// */ /* Now structs that involve heap allocation to store data. */ /** Storage for a string. */ typedef struct { int32_t length; /** If this is non-zero, the string owns the data, if 0, is a const ref to a static string. */ int32_t alloc_size; const char* str; } exr_attr_string_t; /** Storage for a string vector. */ typedef struct { int32_t n_strings; /** If this is non-zero, the string vector owns the data, if 0, is a const ref. */ int32_t alloc_size; const exr_attr_string_t* strings; } exr_attr_string_vector_t; /** Float vector storage struct. */ typedef struct { int32_t length; /** If this is non-zero, the float vector owns the data, if 0, is a const ref. */ int32_t alloc_size; const float* arr; } exr_attr_float_vector_t; /** Hint for lossy compression methods about how to treat values * (logarithmic or linear), meaning a human sees values like R, G, B, * luminance difference between 0.1 and 0.2 as about the same as 1.0 * to 2.0 (logarithmic), where chroma coordinates are closer to linear * (0.1 and 0.2 is about the same difference as 1.0 and 1.1). */ typedef enum { EXR_PERCEPTUALLY_LOGARITHMIC = 0, EXR_PERCEPTUALLY_LINEAR = 1 } exr_perceptual_treatment_t; /** Individual channel information. */ typedef struct { exr_attr_string_t name; /** Data representation for these pixels: uint, half, float. */ exr_pixel_type_t pixel_type; /** Possible values are 0 and 1 per docs exr_perceptual_treatment_t. */ uint8_t p_linear; uint8_t reserved[3]; int32_t x_sampling; int32_t y_sampling; } exr_attr_chlist_entry_t; /** List of channel information (sorted alphabetically). */ typedef struct { int num_channels; int num_alloced; const exr_attr_chlist_entry_t* entries; } exr_attr_chlist_t; /** @brief Struct to define attributes of an embedded preview image. */ typedef struct { uint32_t width; uint32_t height; /** If this is non-zero, the preview owns the data, if 0, is a const ref. */ size_t alloc_size; const uint8_t* rgba; } exr_attr_preview_t; /** Custom storage structure for opaque data. * * Handlers for opaque types can be registered, then when a * non-builtin type is encountered with a registered handler, the * function pointers to unpack/pack it will be set up. * * @sa exr_register_attr_type_handler */ typedef struct { int32_t size; int32_t unpacked_size; /** If this is non-zero, the struct owns the data, if 0, is a const ref. */ int32_t packed_alloc_size; uint8_t pad[4]; void* packed_data; /** When an application wants to have custom data, they can store * an unpacked form here which will be requested to be destroyed * upon destruction of the attribute. */ void* unpacked_data; /** An application can register an attribute handler which then * fills in these function pointers. This allows a user to delay * the expansion of the custom type until access is desired, and * similarly, to delay the packing of the data until write time. */ exr_result_t (*unpack_func_ptr) ( exr_context_t ctxt, const void* data, int32_t attrsize, int32_t* outsize, void** outbuffer); exr_result_t (*pack_func_ptr) ( exr_context_t ctxt, const void* data, int32_t datasize, int32_t* outsize, void* outbuffer); void (*destroy_unpacked_func_ptr) ( exr_context_t ctxt, void* data, int32_t attrsize); } exr_attr_opaquedata_t; /* /////////////////////////////////////// */ /** @brief Built-in/native attribute type enum. * * This will enable us to do a tagged type struct to generically store * attributes. */ typedef enum { EXR_ATTR_UNKNOWN = 0, /**< Type indicating an error or uninitialized attribute. */ EXR_ATTR_BOX2I, /**< Integer region definition. @see exr_attr_box2i_t. */ EXR_ATTR_BOX2F, /**< Float region definition. @see exr_attr_box2f_t. */ EXR_ATTR_CHLIST, /**< Definition of channels in file @see exr_chlist_entry. */ EXR_ATTR_CHROMATICITIES, /**< Values to specify color space of colors in file @see exr_attr_chromaticities_t. */ EXR_ATTR_COMPRESSION, /**< ``uint8_t`` declaring compression present. */ EXR_ATTR_DOUBLE, /**< Double precision floating point number. */ EXR_ATTR_ENVMAP, /**< ``uint8_t`` declaring environment map type. */ EXR_ATTR_FLOAT, /**< Normal (4 byte) precision floating point number. */ EXR_ATTR_FLOAT_VECTOR, /**< List of normal (4 byte) precision floating point numbers. */ EXR_ATTR_INT, /**< 32-bit signed integer value. */ EXR_ATTR_KEYCODE, /**< Struct recording keycode @see exr_attr_keycode_t. */ EXR_ATTR_LINEORDER, /**< ``uint8_t`` declaring scanline ordering. */ EXR_ATTR_M33F, /**< 9 32-bit floats representing a 3x3 matrix. */ EXR_ATTR_M33D, /**< 9 64-bit floats representing a 3x3 matrix. */ EXR_ATTR_M44F, /**< 16 32-bit floats representing a 4x4 matrix. */ EXR_ATTR_M44D, /**< 16 64-bit floats representing a 4x4 matrix. */ EXR_ATTR_PREVIEW, /**< 2 ``unsigned ints`` followed by 4 x w x h ``uint8_t`` image. */ EXR_ATTR_RATIONAL, /**< \c int followed by ``unsigned int`` */ EXR_ATTR_STRING, /**< ``int`` (length) followed by char string data. */ EXR_ATTR_STRING_VECTOR, /**< 0 or more text strings (int + string). number is based on attribute size. */ EXR_ATTR_TILEDESC, /**< 2 ``unsigned ints`` ``xSize``, ``ySize`` followed by mode. */ EXR_ATTR_TIMECODE, /**< 2 ``unsigned ints`` time and flags, user data. */ EXR_ATTR_V2I, /**< Pair of 32-bit integers. */ EXR_ATTR_V2F, /**< Pair of 32-bit floats. */ EXR_ATTR_V2D, /**< Pair of 64-bit floats. */ EXR_ATTR_V3I, /**< Set of 3 32-bit integers. */ EXR_ATTR_V3F, /**< Set of 3 32-bit floats. */ EXR_ATTR_V3D, /**< Set of 3 64-bit floats. */ EXR_ATTR_OPAQUE, /**< User/unknown provided type. */ EXR_ATTR_LAST_KNOWN_TYPE } exr_attribute_type_t; /** @brief Storage, name and type information for an attribute. * * Attributes (metadata) for the file cause a surprising amount of * overhead. It is not uncommon for a production-grade EXR to have * many attributes. As such, the attribute struct is designed in a * slightly more complicated manner. It is optimized to have the * storage for that attribute: the struct itself, the name, the type, * and the data all allocated as one block. Further, the type and * standard names may use a static string to avoid allocating space * for those as necessary with the pointers pointing to static strings * (not to be freed). Finally, small values are optimized for. */ typedef struct { /** Name of the attribute. */ const char* name; /** String type name of the attribute. */ const char* type_name; /** Length of name string (short flag is 31 max, long allows 255). */ uint8_t name_length; /** Length of type string (short flag is 31 max, long allows 255). */ uint8_t type_name_length; uint8_t pad[2]; /** Enum of the attribute type. */ exr_attribute_type_t type; /** Union of pointers of different types that can be used to type * pun to an appropriate type for builtins. Do note that while * this looks like a big thing, it is only the size of a single * pointer. These are all pointers into some other data block * storing the value you want, with the exception of the pod types * which are just put in place (i.e. small value optimization). * * The attribute type \c type should directly correlate to one * of these entries. */ union { // NB: not pointers for POD types uint8_t uc; double d; float f; int32_t i; exr_attr_box2i_t* box2i; exr_attr_box2f_t* box2f; exr_attr_chlist_t* chlist; exr_attr_chromaticities_t* chromaticities; exr_attr_keycode_t* keycode; exr_attr_float_vector_t* floatvector; exr_attr_m33f_t* m33f; exr_attr_m33d_t* m33d; exr_attr_m44f_t* m44f; exr_attr_m44d_t* m44d; exr_attr_preview_t* preview; exr_attr_rational_t* rational; exr_attr_string_t* string; exr_attr_string_vector_t* stringvector; exr_attr_tiledesc_t* tiledesc; exr_attr_timecode_t* timecode; exr_attr_v2i_t* v2i; exr_attr_v2f_t* v2f; exr_attr_v2d_t* v2d; exr_attr_v3i_t* v3i; exr_attr_v3f_t* v3f; exr_attr_v3d_t* v3d; exr_attr_opaquedata_t* opaque; uint8_t* rawptr; }; } exr_attribute_t; /** @} */ #ifdef __cplusplus } /* extern "C" */ #endif #endif /* OPENEXR_ATTR_H */