openexr_attr.h

Go to the documentation of this file.

/*
** 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 */