diff --git a/docs/OpenEXRCoreAPI.rst b/docs/OpenEXRCoreAPI.rst index 33d494023..7aabfa195 100644 --- a/docs/OpenEXRCoreAPI.rst +++ b/docs/OpenEXRCoreAPI.rst @@ -88,6 +88,7 @@ a sorted order, or the order within which they appear in the file. One example might be to retrieve the data window: .. code-block:: + :linenos: exr_attr_box2i_t datawindow; exr_result_t rv = exr_get_data_window(ctxt, 0, &datawindow); @@ -172,6 +173,12 @@ would result from unpacking that chunk, and it’s raw position on disk. Reference --------- +Basic Types +^^^^^^^^^^^ + +.. doxygentypedef:: exr_result_t + + Basic Enumerated Types ^^^^^^^^^^^^^^^^^^^^^^ @@ -189,6 +196,9 @@ Basic Enumerated Types Global State ^^^^^^^^^^^^ +.. doxygentypedef:: exr_memory_allocation_func_t +.. doxygentypedef:: exr_memory_free_func_t + .. doxygenfunction:: exr_get_library_version .. doxygenfunction:: exr_set_default_maximum_image_size .. doxygenfunction:: exr_get_default_maximum_image_size @@ -236,12 +246,17 @@ Open for Write Close ^^^^^ +.. doxygentypedef:: exr_destroy_stream_func_ptr_t + .. doxygenfunction:: exr_finish Context ^^^^^^^ +.. doxygentypedef:: exr_context_t +.. doxygentypedef:: exr_const_context_t + .. doxygenstruct:: _exr_context_initializer :members: .. doxygentypedef:: exr_context_initializer_t @@ -266,6 +281,8 @@ Decoding Encoding ^^^^^^^^ +.. doxygenenum:: transcoding_pipeline_buffer_id + .. doxygenstruct:: _exr_encode_pipeline :members: .. doxygentypedef:: exr_encode_pipeline_t @@ -283,6 +300,8 @@ Encoding Attribute Values ^^^^^^^^^^^^^^^^ + + .. doxygenstruct:: exr_attr_chromaticities_t :members: :undoc-members: @@ -297,6 +316,86 @@ Attribute Values :members: :undoc-members: +.. doxygenstruct:: exr_attr_v2i_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_v2f_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_v2d_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_v3i_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_v3f_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_v3d_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_m33f_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_m33d_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_m44f_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_m44d_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_box2i_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_box2f_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_string_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_string_vector_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_float_vector_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_chlist_entry_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_chlist_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_preview_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_tiledesc_t + :members: + :undoc-members: + +.. doxygenstruct:: exr_attr_timecode_t + :members: + :undoc-members: + .. doxygenstruct:: exr_attr_opaquedata_t :members: :undoc-members: @@ -304,6 +403,9 @@ Attribute Values Reading ^^^^^^^ +.. doxygentypedef:: exr_read_func_ptr_t +.. doxygentypedef:: exr_query_size_func_ptr_t + .. doxygenfunction:: exr_get_count .. doxygenfunction:: exr_get_name .. doxygenfunction:: exr_get_storage @@ -368,6 +470,8 @@ Reading Writing ^^^^^^^ +.. doxygentypedef:: exr_write_func_ptr_t + .. doxygenfunction:: exr_add_part .. doxygenfunction:: exr_add_channel @@ -421,6 +525,8 @@ Error Handling .. doxygenenum:: exr_error_code_t +.. doxygentypedef:: exr_error_handler_cb_t + .. doxygenfunction:: exr_get_default_error_message .. doxygenfunction:: exr_get_error_code_as_string diff --git a/docs/index.rst b/docs/index.rst index 859129bf4..98fb08d94 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,5 @@ -.. Imath documentation master file, created by - sphinx-quickstart on Wed Apr 24 15:19:01 2019. - -OpenEXR Technical Documentation -=============================== +OpenEXR |version| Technical Documentation +========================================= .. sidebar:: OpenEXR diff --git a/src/lib/Iex/IexBaseExc.cpp b/src/lib/Iex/IexBaseExc.cpp index 8ecb5431e..3b60c3175 100644 --- a/src/lib/Iex/IexBaseExc.cpp +++ b/src/lib/Iex/IexBaseExc.cpp @@ -191,6 +191,8 @@ BaseExc::stackTrace () const noexcept return _stackTrace; } +/// @cond Doxygen_Suppress + DEFINE_EXC_EXP_IMPL (IEX_EXPORT, ArgExc, BaseExc) DEFINE_EXC_EXP_IMPL (IEX_EXPORT, LogicExc, BaseExc) DEFINE_EXC_EXP_IMPL (IEX_EXPORT, InputExc, BaseExc) @@ -363,6 +365,8 @@ DEFINE_EXC_EXP_IMPL (IEX_EXPORT, DivzeroExc, MathExc) DEFINE_EXC_EXP_IMPL (IEX_EXPORT, InexactExc, MathExc) DEFINE_EXC_EXP_IMPL (IEX_EXPORT, InvalidFpOpExc, MathExc) +/// @endcond Doxygen_Suppress + IEX_INTERNAL_NAMESPACE_SOURCE_EXIT diff --git a/src/lib/Iex/IexExport.h b/src/lib/Iex/IexExport.h index 966784077..b07625f11 100644 --- a/src/lib/Iex/IexExport.h +++ b/src/lib/Iex/IexExport.h @@ -33,7 +33,5 @@ #endif // OPENEXR_DLL -/// @} - #endif // #ifndef INCLUDED_IEXEXPORT_H diff --git a/src/lib/OpenEXRCore/internal_attr.h b/src/lib/OpenEXRCore/internal_attr.h index 105de18f4..71ccd0add 100644 --- a/src/lib/OpenEXRCore/internal_attr.h +++ b/src/lib/OpenEXRCore/internal_attr.h @@ -44,25 +44,25 @@ int internal_exr_is_standard_type (const char* typen); typedef struct exr_attribute_list { - int num_attributes; /**< number of attribute entries in the list */ - int num_alloced; /**< allocation count. if > 0, attribute list owns pointer */ - exr_attribute_t** entries; /**< creation order list of attributes */ + int num_attributes; /**< Number of attribute entries in the list */ + int num_alloced; /**< Allocation count. if > 0, attribute list owns pointer */ + exr_attribute_t** entries; /**< Creation order list of attributes */ exr_attribute_t** - sorted_entries; /**< sorted order list of attributes for fast lookup */ + sorted_entries; /**< Sorted order list of attributes for fast lookup */ } exr_attribute_list_t; -/** Initializes a list to an empty attribute list */ +/** Initialize a list to an empty attribute list */ exr_result_t exr_attr_list_init (exr_context_t ctxt, exr_attribute_list_t* l); -/** Frees memory for all the owned attributes in the list as well as the list itself */ +/** Free memory for all the owned attributes in the list as well as the list itself */ exr_result_t exr_attr_list_destroy (exr_context_t ctxt, exr_attribute_list_t* l); -/** Computes the number of bytes required to store this attribute list in a file */ +/** Compute the number of bytes required to store this attribute list in a file */ exr_result_t exr_attr_list_compute_size ( exr_context_t ctxt, exr_attribute_list_t* l, uint64_t* out); -/** Finds an attribute in the list by name */ +/** Find an attribute in the list by name */ exr_result_t exr_attr_list_find_by_name ( exr_const_context_t ctxt, exr_attribute_list_t* l, diff --git a/src/lib/OpenEXRCore/openexr_attr.h b/src/lib/OpenEXRCore/openexr_attr.h index b5c5b7b57..eaef19b3a 100644 --- a/src/lib/OpenEXRCore/openexr_attr.h +++ b/src/lib/OpenEXRCore/openexr_attr.h @@ -15,13 +15,15 @@ extern "C" { #endif +/** @file */ + /** - * @defgroup AttributeTypes Attribute / metadata value types and struct declarations + * @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 + * 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 @@ -30,7 +32,7 @@ extern "C" { * @{ */ -/** enum declaring allowed values for uint8_t value stored in built-in compression type */ +/** Enum declaring allowed values for \c uint8_t value stored in built-in compression type. */ typedef enum { EXR_COMPRESSION_NONE = 0, @@ -43,46 +45,46 @@ typedef enum EXR_COMPRESSION_B44A = 7, EXR_COMPRESSION_DWAA = 8, EXR_COMPRESSION_DWAB = 9, - EXR_COMPRESSION_LAST_TYPE /**< invalid value, provided for range checking */ + EXR_COMPRESSION_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_compression_t; -/** enum declaring allowed values for uint8_t value stored in built-in env map type */ +/** 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_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_envmap_t; -/** enum declaring allowed values for uint8_t value stored in lineOrder type */ +/** 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_LAST_TYPE /**< Invalid value, provided for range checking. */ } exr_lineorder_t; -/** enum declaring allowed values for part type */ +/** Enum declaring allowed values for part type. */ typedef enum { - EXR_STORAGE_SCANLINE = 0, /**< corresponds to type of 'scanlineimage' */ - EXR_STORAGE_TILED, /**< corresponds to type of 'tiledimage' */ - EXR_STORAGE_DEEP_SCANLINE, /**< corresponds to type of 'deepscanline' */ - EXR_STORAGE_DEEP_TILED, /**< corresponds to type of 'deeptile' */ - EXR_STORAGE_LAST_TYPE /**< invalid value, provided for range checking */ + 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 */ +/** @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 /**< guard / out of range type */ + 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 */ +/** @brief Enum representing how to scale positions between levels. */ typedef enum { EXR_TILE_ROUND_DOWN = 0, @@ -90,7 +92,7 @@ typedef enum EXR_TILE_ROUND_LAST_TYPE } exr_tile_round_mode_t; -/** @brief Enum capturing the underlying data type on a channel */ +/** @brief Enum capturing the underlying data type on a channel. */ typedef enum { EXR_PIXEL_UINT = 0, @@ -103,10 +105,11 @@ typedef enum /* 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 */ + * 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 */ +/** @brief Struct to hold color chromaticities to interpret the tristimulus color values in the image data. */ typedef struct { float red_x; @@ -119,7 +122,7 @@ typedef struct float white_y; } exr_attr_chromaticities_t; -/** @brief struct to hold keycode information */ +/** @brief Struct to hold keycode information. */ typedef struct { int32_t film_mfc_code; @@ -131,45 +134,45 @@ typedef struct int32_t perfs_per_count; } exr_attr_keycode_t; -/** @brief struct to hold a 32-bit floating-point 3x3 matrix */ +/** @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 */ +/** @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 */ +/** @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 */ +/** @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 */ +/** @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 */ +/** @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 */ +/** @brief Struct to hold a 2-element integer vector. */ typedef struct { union @@ -182,7 +185,7 @@ typedef struct }; } exr_attr_v2i_t; -/** @brief struct to hold a 2-element 32-bit float vector */ +/** @brief Struct to hold a 2-element 32-bit float vector. */ typedef struct { union @@ -195,7 +198,7 @@ typedef struct }; } exr_attr_v2f_t; -/** @brief struct to hold a 2-element 64-bit float vector */ +/** @brief Struct to hold a 2-element 64-bit float vector. */ typedef struct { union @@ -208,7 +211,7 @@ typedef struct }; } exr_attr_v2d_t; -/** @brief struct to hold a 3-element integer vector */ +/** @brief Struct to hold a 3-element integer vector. */ typedef struct { union @@ -221,7 +224,7 @@ typedef struct }; } exr_attr_v3i_t; -/** @brief struct to hold a 3-element 32-bit float vector */ +/** @brief Struct to hold a 3-element 32-bit float vector. */ typedef struct { union @@ -234,7 +237,7 @@ typedef struct }; } exr_attr_v3f_t; -/** @brief struct to hold a 3-element 64-bit float vector */ +/** @brief Struct to hold a 3-element 64-bit float vector. */ typedef struct { union @@ -247,14 +250,14 @@ typedef struct }; } exr_attr_v3d_t; -/** @brief struct to hold an integer box / region definition */ +/** @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 */ +/** @brief Struct to hold a floating-point box/region definition. */ typedef struct { exr_attr_v2f_t min; @@ -263,8 +266,8 @@ typedef struct /** @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 uint32_t boundary + * 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 { @@ -273,13 +276,13 @@ typedef struct uint8_t level_and_round; } exr_attr_tiledesc_t; -/** @brief macro to access type of tiling from packed structure */ +/** @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 */ +/** @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 */ +/** @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)))) @@ -288,31 +291,31 @@ typedef struct /* /////////////////////////////////////// */ /* Now structs that involve heap allocation to store data. */ -/** Storage for a string */ +/** 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 */ + /** 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 */ +/** 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 */ + /** 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 */ +/** 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 */ + /** If this is non-zero, the float vector owns the data, if 0, is a const ref. */ int32_t alloc_size; const float* arr; @@ -322,7 +325,7 @@ typedef struct * (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) + * (0.1 and 0.2 is about the same difference as 1.0 and 1.1). */ typedef enum { @@ -330,20 +333,20 @@ typedef enum EXR_PERCEPTUALLY_LINEAR = 1 } exr_perceptual_treatment_t; -/** Individual channel information*/ +/** Individual channel information. */ typedef struct { exr_attr_string_t name; - /** Data representation for these pixels: uint, half, float */ + /** Data representation for these pixels: uint, half, float. */ exr_pixel_type_t pixel_type; - /** Possible values are 0 and 1 per docs \ref exr_perceptual_treatment_t */ + /** 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) */ +/** List of channel information (sorted alphabetically). */ typedef struct { int num_channels; @@ -352,22 +355,22 @@ typedef struct const exr_attr_chlist_entry_t* entries; } exr_attr_chlist_t; -/** @brief Struct to define attributes of an embedded preview image */ +/** @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 */ + /** 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 +/** 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. + * function pointers to unpack/pack it will be set up. * * @sa exr_register_attr_type_handler */ @@ -375,20 +378,23 @@ 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 */ + /** 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 */ + /** 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 */ + /** 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, @@ -407,7 +413,7 @@ typedef struct /* /////////////////////////////////////// */ -/** @brief built-in / native attribute type enum +/** @brief Built-in/native attribute type enum. * * This will enable us to do a tagged type struct to generically store * attributes. @@ -415,40 +421,40 @@ typedef struct typedef enum { EXR_ATTR_UNKNOWN = - 0, /**< type indicating an error or uninitialized attribute */ - EXR_ATTR_BOX2I, /**< integer region definition. @see exr_box2i */ - EXR_ATTR_BOX2F, /**< float region definition. @see exr_box2f */ - 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, /**< a normal (4 byte) precision floating point number */ - EXR_ATTR_FLOAT_VECTOR, /**< a list of normal (4 byte) precision floating point numbers */ - EXR_ATTR_INT, /**< a 32-bit signed integer value */ - EXR_ATTR_KEYCODE, /**< structure 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, /**< 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 */ + 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. +/** @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 @@ -462,30 +468,30 @@ typedef enum */ typedef struct { - /** name of the attribute */ + /** Name of the attribute. */ const char* name; - /** string type name of the attribute */ + /** String type name of the attribute. */ const char* type_name; - /** length of name string (short flag is 31 max, long allows 255) */ + /** 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) */ + /** 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 */ + /** 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 \ref type should directly correlate to one of - * these entries - */ + * 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 diff --git a/src/lib/OpenEXRCore/openexr_base.h b/src/lib/OpenEXRCore/openexr_base.h index b45522662..7d21bad60 100644 --- a/src/lib/OpenEXRCore/openexr_base.h +++ b/src/lib/OpenEXRCore/openexr_base.h @@ -14,8 +14,12 @@ extern "C" { #endif +/** @file */ + /** @brief Retrieve the current library version. The @p extra string is for - * custom installs, and is a static string, do not free the returned pointer */ + * custom installs, and is a static string, do not free the returned + * pointer. + */ EXR_EXPORT void exr_get_library_version (int* maj, int* min, int* patch, const char** extra); @@ -25,11 +29,11 @@ exr_get_library_version (int* maj, int* min, int* patch, const char** extra); */ /** @brief Limit the size of image allowed to be parsed or created by - * the library + * the library. * * This is used as a safety check against corrupt files, but can also * serve to avoid potential issues on machines which have very - * constrained RAM + * constrained RAM. * * These values are among the only globals in the core layer of * OpenEXR. The intended use is for applications to define a global @@ -56,14 +60,14 @@ exr_get_library_version (int* maj, int* min, int* patch, const char** extra); */ EXR_EXPORT void exr_set_default_maximum_image_size (int w, int h); -/** @brief Retrieve the global default maximum image size +/** @brief Retrieve the global default maximum image size. * * This function does not fail. */ EXR_EXPORT void exr_get_default_maximum_image_size (int* w, int* h); /** @brief Limit the size of an image tile allowed to be parsed or - * created by the library + * created by the library. * * Similar to image size, this places constraints on the maximum tile * size as a safety check against bad file data @@ -87,7 +91,7 @@ EXR_EXPORT void exr_get_default_maximum_image_size (int* w, int* h); * 1. negative values are ignored. * * 2. if either value has a positive (non-zero) value, and the other - * has 0, the positive value is preferred. + * has 0, the positive value is preferred. * * 3. If both are positive (non-zero), the minimum value is used. * @@ -103,7 +107,7 @@ EXR_EXPORT void exr_set_default_maximum_tile_size (int w, int h); */ EXR_EXPORT void exr_get_default_maximum_tile_size (int* w, int* h); -/** @brief function pointer used to hold a malloc-like routine +/** @brief Function pointer used to hold a malloc-like routine. * * Providing these to a context will override what memory is used to * allocate the context itself, as well as any allocations which @@ -112,7 +116,7 @@ EXR_EXPORT void exr_get_default_maximum_tile_size (int* w, int* h); * internal allocations performed by the library. * * This function is expected to allocate and return a new memory - * handle, or NULL if allocation failed (which the library will then + * handle, or `NULL` if allocation failed (which the library will then * handle and return an out-of-memory error). * * If one is provided, both should be provided. @@ -120,7 +124,7 @@ EXR_EXPORT void exr_get_default_maximum_tile_size (int* w, int* h); */ typedef void* (*exr_memory_allocation_func_t) (size_t bytes); -/** @brief function pointer used to hold a free-like routine +/** @brief Function pointer used to hold a free-like routine. * * Providing these to a context will override what memory is used to * allocate the context itself, as well as any allocations which @@ -136,14 +140,16 @@ typedef void* (*exr_memory_allocation_func_t) (size_t bytes); */ typedef void (*exr_memory_free_func_t) (void* ptr); -/** @brief Allows the user to override default allocator used internal allocations necessary for - * files, attributes, and other temporary memory. +/** @brief Allow the user to override default allocator used internal + * allocations necessary for files, attributes, and other temporary + * memory. * * These routines may be overridden when creating a specific context, * however this provides global defaults such that the default can be * applied. * - * If either pointer is 0, the appropriate malloc/free routine will be substituted. + * If either pointer is 0, the appropriate malloc/free routine will be + * substituted. * * This function does not fail. */ diff --git a/src/lib/OpenEXRCore/openexr_chunkio.h b/src/lib/OpenEXRCore/openexr_chunkio.h index 61ac2ae35..35ed11b96 100644 --- a/src/lib/OpenEXRCore/openexr_chunkio.h +++ b/src/lib/OpenEXRCore/openexr_chunkio.h @@ -14,8 +14,10 @@ extern "C" { #endif +/** @file */ + /** - * Structure describing raw data information about a chunk. + * Struct describing raw data information about a chunk. * * A chunk is the generic term for a pixel data block in an EXR file, * as described in the OpenEXR File Layout documentation. This is @@ -25,15 +27,15 @@ typedef struct { int32_t idx; - /** for tiles, this is the tilex; for scans it is the x */ + /** For tiles, this is the tilex; for scans it is the x. */ int32_t start_x; - /** for tiles, this is the tiley; for scans it is the scanline y */ + /** For tiles, this is the tiley; for scans it is the scanline y. */ int32_t start_y; - int32_t height; /**< for this chunk */ - int32_t width; /**< for this chunk */ + int32_t height; /**< For this chunk. */ + int32_t width; /**< For this chunk. */ - uint8_t level_x; /**< for tiled files */ - uint8_t level_y; /**< for tiled files */ + uint8_t level_x; /**< For tiled files. */ + uint8_t level_y; /**< For tiled files. */ uint8_t type; uint8_t compression; @@ -60,10 +62,10 @@ exr_result_t exr_read_tile_chunk_info ( int levely, exr_chunk_info_t* cinfo); -/** Read the packed data block for a chunk +/** Read the packed data block for a chunk. * * This assumes that the buffer pointed to by @p packed_data is - * large enough to hold the chunk block info packed_size bytes + * large enough to hold the chunk block info packed_size bytes. */ EXR_EXPORT exr_result_t exr_read_chunk ( @@ -76,7 +78,7 @@ exr_result_t exr_read_chunk ( * Read chunk for deep data. * * This allows one to read the packed data, the sample count data, or both. - * \ref exr_read_chunk also works to read deep data packed data, + * \c exr_read_chunk also works to read deep data packed data, * but this is a routine to get the sample count table and the packed * data in one go, or if you want to pre-read the sample count data, * you can get just that buffer. @@ -91,16 +93,16 @@ exr_result_t exr_read_deep_chunk ( /**************************************/ -/** Initialize a \ref exr_chunk_info_t structure when encoding scanline +/** Initialize a \c exr_chunk_info_t structure when encoding scanline * data (similar to read but does not do anything with a chunk - * table) + * table). */ EXR_EXPORT exr_result_t exr_write_scanline_chunk_info ( exr_context_t ctxt, int part_index, int y, exr_chunk_info_t* cinfo); -/** Initialize a \ref chunk_info_t structure when encoding tiled data - * (similar to read but does not do anything with a chunk table) +/** Initialize a \c exr_chunk_info_t structure when encoding tiled data + * (similar to read but does not do anything with a chunk table). */ EXR_EXPORT exr_result_t exr_write_tile_chunk_info ( @@ -113,7 +115,7 @@ exr_result_t exr_write_tile_chunk_info ( exr_chunk_info_t* cinfo); /** - * @p y must the appropriate starting y for the specified chunk + * @p y must the appropriate starting y for the specified chunk. */ EXR_EXPORT exr_result_t exr_write_scanline_chunk ( @@ -124,7 +126,7 @@ exr_result_t exr_write_scanline_chunk ( uint64_t packed_size); /** - * @p y must the appropriate starting y for the specified chunk + * @p y must the appropriate starting y for the specified chunk. */ EXR_EXPORT exr_result_t exr_write_deep_scanline_chunk ( diff --git a/src/lib/OpenEXRCore/openexr_coding.h b/src/lib/OpenEXRCore/openexr_coding.h index b5484b94f..9cc1ac5e3 100644 --- a/src/lib/OpenEXRCore/openexr_coding.h +++ b/src/lib/OpenEXRCore/openexr_coding.h @@ -12,10 +12,12 @@ extern "C" { #endif +/** @file */ + /** - * Enum for use in a custom allocator in the encode / decode pipelines - * (i.e. so the implementor knows whether to allocate on which device - * based on the buffer disposition) + * Enum for use in a custom allocator in the encode/decode pipelines + * (that is, so the implementor knows whether to allocate on which + * device based on the buffer disposition). */ enum transcoding_pipeline_buffer_id { @@ -28,8 +30,8 @@ enum transcoding_pipeline_buffer_id EXR_TRANSCODE_BUFFER_SAMPLES }; -/** @brief Structure for negotiating buffers when decoding / encoding - * chunks of data +/** @brief Struct for negotiating buffers when decoding/encoding + * chunks of data. * * This is generic and meant to negotiate exr data bi-directionally, * in that the same structure is used for both decoding and encoding @@ -42,73 +44,76 @@ typedef struct { /************************************************** * Elements below are populated by the library when - * decoding is initialized / updated and must be left - * untouched when using the default decoder routines + * decoding is initialized/updated and must be left + * untouched when using the default decoder routines. **************************************************/ - /** channel name + /** Channel name. * * This is provided as a convenient reference. Do not free, this * refers to the internal data structure in the context. */ const char* channel_name; - /** number of lines for this channel in this chunk + /** Number of lines for this channel in this chunk. * * May be 0 or less than overall image height based on sampling * (i.e. when in 4:2:0 type sampling) */ int32_t height; - /** width in pixel count + /** Width in pixel count. * * May be 0 or less than overall image width based on sampling - * (i.e. 4:2:2 will have some channels have fewer values) + * (i.e. 4:2:2 will have some channels have fewer values). */ int32_t width; - /** horizontal subsampling information */ + /** Horizontal subsampling information. */ int32_t x_samples; - /** vertical subsampling information */ + /** Vertical subsampling information. */ int32_t y_samples; - /** linear flag from channel definition (used by b44)*/ + /** Linear flag from channel definition (used by b44). */ uint8_t p_linear; - /** - * how many bytes per pixel this channel consumes (i.e. 2 for - * float16, 4 for float32 / uint32) + + /** How many bytes per pixel this channel consumes (2 for float16, + * 4 for float32/uint32). */ int8_t bytes_per_element; - /** small form of exr_pixel_type_t enum (EXR_PIXEL_UINT/HALF/FLOAT) */ + + /** Small form of exr_pixel_type_t enum (EXR_PIXEL_UINT/HALF/FLOAT). */ uint16_t data_type; /************************************************** * Elements below must be edited by the caller - * to control encoding / decoding + * to control encoding/decoding. **************************************************/ - /** - * how many bytes per pixel the input is or output should be - * (i.e. 2 for float16, 4 for float32 / uint32). Defaults to same - * size as input + /** How many bytes per pixel the input is or output should be + * (2 for float16, 4 for float32/uint32). Defaults to same + * size as input. */ int16_t user_bytes_per_element; - /** small form of exr_pixel_type_t enum - * (EXR_PIXEL_UINT/HALF/FLOAT). Defaults to same type as input */ + + /** Small form of exr_pixel_type_t enum + * (EXR_PIXEL_UINT/HALF/FLOAT). Defaults to same type as input. + */ uint16_t user_data_type; - /** increment to get to next pixel + /** Increment to get to next pixel. * * This is in bytes. Must be specified when the decode pointer is * specified (and always for encode). * * This is useful for implementing transcoding generically of * planar or interleaved data. For planar data, where the layout - * is RRRRRGGGGGBBBBB, you can pass in 1 * bytes per component + * is RRRRRGGGGGBBBBB, you can pass in 1 * bytes per component. */ + int32_t user_pixel_stride; - /** - * When lines > 1 for a chunk, this is the increment used to get + + /** When \c lines > 1 for a chunk, this is the increment used to get * from beginning of line to beginning of next line. * * This is in bytes. Must be specified when the decode pointer is @@ -116,9 +121,8 @@ typedef struct */ int32_t user_line_stride; - /** - * This data member has different requirements reading vs - * writing. When reading, if this is left as NULL, the channel + /** This data member has different requirements reading vs + * writing. When reading, if this is left as `NULL`, the channel * will be skipped during read and not filled in. During a write * operation, this pointer is considered const and not * modified. To make this more clear, a union is used here. diff --git a/src/lib/OpenEXRCore/openexr_conf.h b/src/lib/OpenEXRCore/openexr_conf.h index f86ba9044..441eaf080 100644 --- a/src/lib/OpenEXRCore/openexr_conf.h +++ b/src/lib/OpenEXRCore/openexr_conf.h @@ -15,7 +15,7 @@ // are we making a DLL under windows (might be msvc or mingw or others) #if defined(OPENEXR_DLL) -// when building as a DLL for windows, typical dllexport / import case +// when building as a DLL for windows, typical dllexport/import case // where we need to switch depending on whether we are compiling // internally or not # if defined(OPENEXRCORE_EXPORTS) @@ -32,7 +32,7 @@ /* * MSVC does have printf format checks, but it is not in the form of a - * function attribute, so just skip for non-GCC / clang builds + * function attribute, so just skip for non-GCC/clang builds */ #if defined(__GNUC__) || defined(__clang__) # define EXR_PRINTF_FUNC_ATTRIBUTE __attribute__ ((format (printf, 3, 4))) diff --git a/src/lib/OpenEXRCore/openexr_context.h b/src/lib/OpenEXRCore/openexr_context.h index 39389896d..378a3fee9 100644 --- a/src/lib/OpenEXRCore/openexr_context.h +++ b/src/lib/OpenEXRCore/openexr_context.h @@ -17,6 +17,8 @@ extern "C" { #endif +/** @file */ + /** * @defgroup Context Context related definitions * @@ -34,14 +36,14 @@ extern "C" { * version portability, and all accesses to relevant data should * happen using provided functions. This handle serves as a container * and identifier for all the metadata and parts associated with a - * file and/or stream + * file and/or stream. */ typedef struct _priv_exr_context_t* exr_context_t; typedef const struct _priv_exr_context_t* exr_const_context_t; /** - * @defgroup ContextFunctions OpenEXR Context Stream / File Functions + * @defgroup ContextFunctions OpenEXR Context Stream/File Functions * * @brief These are a group of function interfaces used to customize * the error handling, memory allocations, or I/O behavior of an @@ -76,11 +78,10 @@ typedef void (*exr_error_handler_cb_t) ( * * Generic callback to clean up user data for custom streams. * This is called when the file is closed and expected not to - * error + * error. * - * @param failed - indicates the write operation failed, the - * implementor may wish to cleanup temporary - * files + * @param failed Indicates the write operation failed, the + * implementor may wish to cleanup temporary files */ typedef void (*exr_destroy_stream_func_ptr_t) ( exr_const_context_t ctxt, void* userdata, int failed); @@ -101,10 +102,10 @@ typedef int64_t (*exr_query_size_func_ptr_t) ( /** @brief Read custom function pointer * * Used to read data from a custom output. Expects similar semantics to - * pread or ReadFile with overlapped data under win32 + * pread or ReadFile with overlapped data under win32. * * It is required that this provides thread-safe concurrent access to - * the same file. If the stream / input layer you are providing does + * the same file. If the stream/input layer you are providing does * not have this guarantee, your are responsible for providing * appropriate serialization of requests. * @@ -118,9 +119,9 @@ typedef int64_t (*exr_query_size_func_ptr_t) ( * * While this should mean that the header will be read in 'stream' * order (no seeks required), no guarantee is made beyond that to - * retrieve image / deep data in order. So if the backing file is + * retrieve image/deep data in order. So if the backing file is * truly a stream, it is up to the provider to implement appropriate - * caching of data to give the appearance of being able to seek / read + * caching of data to give the appearance of being able to seek/read * atomically. */ typedef int64_t (*exr_read_func_ptr_t) ( @@ -134,26 +135,26 @@ typedef int64_t (*exr_read_func_ptr_t) ( /** Write custom function pointer * * Used to write data to a custom output. Expects similar semantics to - * pwrite or WriteFile with overlapped data under win32 + * pwrite or WriteFile with overlapped data under win32. * * It is required that this provides thread-safe concurrent access to * the same file. While it is unlikely that multiple threads will * be used to write data for compressed forms, it is possible. * * A file should be expected to be accessed in the following pattern: - * - upon open, the header and part information attributes is constructed + * - upon open, the header and part information attributes is constructed. * * - when the write_header routine is called, the header becomes immutable * and is written to the file. This computes the space to store the chunk - * offsets, but does not yet write the values + * offsets, but does not yet write the values. * * - Image chunks are written to the file, and appear in the order * they are written, not in the ordering that is required by the * chunk offset table (unless written in that order). This may vary * slightly if the size of the chunks is not directly known and - * tight packing of data is necessary + * tight packing of data is necessary. * - * - at file close, the chunk offset tables are written to the file + * - at file close, the chunk offset tables are written to the file. */ typedef int64_t (*exr_write_func_ptr_t) ( exr_const_context_t ctxt, @@ -163,17 +164,19 @@ typedef int64_t (*exr_write_func_ptr_t) ( uint64_t offset, exr_stream_error_func_ptr_t error_cb); -/** @brief struct used to pass function pointers into the context +/** @brief Struct used to pass function pointers into the context * initialization routines. * - * This partly exists to avoid the chicken and egg issue around creating the storage needed for the context on systems which want to override the malloc / free routines. + * This partly exists to avoid the chicken and egg issue around + * creating the storage needed for the context on systems which want + * to override the malloc/free routines. * - * However, it also serves to make a tidier / simpler set of functions + * However, it also serves to make a tidier/simpler set of functions * to create and start processing exr files. * - * The size member is required for version portability + * The size member is required for version portability. * - * It can be initialized using \ref EXR_DEFAULT_CONTEXT_INITIALIZER + * It can be initialized using \c EXR_DEFAULT_CONTEXT_INITIALIZER. * * \code{.c} * exr_context_initializer_t myctxtinit = DEFAULT_CONTEXT_INITIALIZER; @@ -184,7 +187,7 @@ typedef int64_t (*exr_write_func_ptr_t) ( */ typedef struct _exr_context_initializer { - /** @brief size member to tag initializer for version stability. + /** @brief Size member to tag initializer for version stability. * * This should be initialized to the size of the current * structure. This allows EXR to add functions or other @@ -194,33 +197,37 @@ typedef struct _exr_context_initializer /** @brief Error callback function pointer * - * The error callback is allowed to be null, and will use a default print which outputs to stderr + * The error callback is allowed to be `NULL`, and will use a + * default print which outputs to \c stderr. * * @sa exr_error_handler_cb_t */ exr_error_handler_cb_t error_handler_fn; - /** custom allocator, if null, will use malloc. @sa exr_memory_allocation_func_t */ + /** Custom allocator, if `NULL`, will use malloc. @sa exr_memory_allocation_func_t */ exr_memory_allocation_func_t alloc_fn; - /** custom deallocator, if null, will use free. @sa exr_memory_free_func_t */ + + /** Custom deallocator, if `NULL`, will use free. @sa exr_memory_free_func_t */ exr_memory_free_func_t free_fn; - /** passed to custom read, size, write, destroy functions below. Up to user to manage this pointer */ + /** Blind data passed to custom read, size, write, destroy + * functions below. Up to user to manage this pointer. + */ void* user_data; - /** @brief custom read routine. + /** @brief Custom read routine. * * This is only used during read or update contexts. If this is * provided, it is expected that the caller has previously made - * the stream available, and placed whatever stream / file data - * into \ref user_data above. + * the stream available, and placed whatever stream/file data + * into \c user_data above. * - * If this is NULL, and the context requested is for reading an + * If this is `NULL`, and the context requested is for reading an * exr file, an internal implementation is provided for reading * from normal filesystem files, and the filename provided is * attempted to be opened as such. * - * Expected to be NULL for a write-only operation, but is ignored + * Expected to be `NULL` for a write-only operation, but is ignored * if it is provided. * * For update contexts, both read and write functions must be @@ -230,28 +237,28 @@ typedef struct _exr_context_initializer */ exr_read_func_ptr_t read_fn; - /** @brief custom size query routine. + /** @brief Custom size query routine. * * Used to provide validation when reading header values. If this * is not provided, but a custom read routine is provided, this * will disable some of the validation checks when parsing the * image header. * - * Expected to be NULL for a write-only operation, but is ignored + * Expected to be `NULL` for a write-only operation, but is ignored * if it is provided. * * @sa exr_query_size_func_ptr_t */ exr_query_size_func_ptr_t size_fn; - /** @brief custom write routine. + /** @brief Custom write routine. * * This is only used during write or update contexts. If this is * provided, it is expected that the caller has previously made - * the stream available, and placed whatever stream / file data - * into \ref user_data above. + * the stream available, and placed whatever stream/file data + * into \c user_data above. * - * If this is NULL, and the context requested is for writing an + * If this is `NULL`, and the context requested is for writing an * exr file, an internal implementation is provided for reading * from normal filesystem files, and the filename provided is * attempted to be opened as such. @@ -263,7 +270,7 @@ typedef struct _exr_context_initializer */ exr_write_func_ptr_t write_fn; - /** @brief optional function to destroy the user data block of a custom stream + /** @brief Optional function to destroy the user data block of a custom stream. * * Allows one to free any user allocated data, and close any handles. * @@ -271,25 +278,32 @@ typedef struct _exr_context_initializer * */ exr_destroy_stream_func_ptr_t destroy_fn; - /** initializes a field specifying what the maximum image width - * allowed by the context is. See \ref exr_set_default_maximum_image_size to - * understand how this interacts with global defaults */ + /** Initialize a field specifying what the maximum image width + * allowed by the context is. See exr_set_default_maximum_image_size() to + * understand how this interacts with global defaults. + */ int max_image_width; - /** initializes a field specifying what the maximum image height - * allowed by the context is. See \ref exr_set_default_maximum_image_size to - * understand how this interacts with global defaults */ + + /** Initialize a field specifying what the maximum image height + * allowed by the context is. See exr_set_default_maximum_image_size() to + * understand how this interacts with global defaults. + */ int max_image_height; - /** initializes a field specifying what the maximum tile width - * allowed by the context is. See \ref exr_set_default_maximum_tile_size to - * understand how this interacts with global defaults */ + + /** Initialize a field specifying what the maximum tile width + * allowed by the context is. See exr_set_default_maximum_tile_size() to + * understand how this interacts with global defaults. + */ int max_tile_width; - /** initializes a field specifying what the maximum tile height - * allowed by the context is. See \ref exr_set_default_maximum_tile_size to - * understand how this interacts with global defaults */ + + /** Initialize a field specifying what the maximum tile height + * allowed by the context is. See exr_set_default_maximum_tile_size() to + * understand how this interacts with global defaults. + */ int max_tile_height; } exr_context_initializer_t; -/** @brief simple macro to initialize the context initializer with default values */ +/** @brief Simple macro to initialize the context initializer with default values. */ #define EXR_DEFAULT_CONTEXT_INITIALIZER \ { \ sizeof (exr_context_initializer_t), 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 \ @@ -299,21 +313,21 @@ typedef struct _exr_context_initializer /** @brief Check the magic number of the file and report * `EXR_ERR_SUCCESS` if the file appears to be a valid file (or at least - * has the correct magic number and can be read) + * has the correct magic number and can be read). */ EXR_EXPORT exr_result_t exr_test_file_header ( const char* filename, const exr_context_initializer_t* ctxtdata); /** @brief Close and free any internally allocated memory, - * calling any provided destroy function for custom streams + * calling any provided destroy function for custom streams. * * If the file was opened for write, first save the chunk offsets * or any other unwritten data. */ EXR_EXPORT exr_result_t exr_finish (exr_context_t* ctxt); -/** @brief Create and initialize a read-only exr read context +/** @brief Create and initialize a read-only exr read context. * * If a custom read function is provided, the filename is for * informational purposes only, the system assumes the user has @@ -326,7 +340,7 @@ EXR_EXPORT exr_result_t exr_finish (exr_context_t* ctxt); * provide a safe context for multiple threads to request data from * the same context concurrently. * - * Once finished reading data, use \ref exr_finish to clean up + * Once finished reading data, use exr_finish() to clean up * the context. * * If you have custom I/O requirements, see the initializer context @@ -338,16 +352,16 @@ EXR_EXPORT exr_result_t exr_start_read ( const char* filename, const exr_context_initializer_t* ctxtdata); -/** @brief enum describing how default files are handled during write */ +/** @brief Enum describing how default files are handled during write. */ enum exr_default_write_mode { EXR_WRITE_FILE_DIRECTLY = - 0, /**< overwrites filename provided directly, deleted upon error */ + 0, /**< Overwrite filename provided directly, deleted upon error. */ EXR_INTERMEDIATE_TEMP_FILE = - 1 /**< creates a temporary file, renaming it upon successful write, leaving original upon error */ + 1 /**< Create a temporary file, renaming it upon successful write, leaving original upon error. */ }; -/** @brief Creates and initializes a write-only context. +/** @brief Create and initialize a write-only context. * * If a custom write function is provided, the filename is for * informational purposes only, and the @p default_mode parameter will be @@ -367,7 +381,8 @@ enum exr_default_write_mode * 3. Transition to writing data (this "commits" the part definitions, * any changes requested after will result in an error) * - * 4. Write part data in sequential order of parts ( part 0->(N-1) ). + * 4. Write part data in sequential order of parts (part0 + * -> partN-1). * * 5. Within each part, multiple threads can be encoding and writing * data concurrently. For some EXR part definitions, this may be able @@ -376,13 +391,13 @@ enum exr_default_write_mode * temporarily cache chunks until the data is received to flush in * order. The concurrency around this is handled by the library * - * 6. Once finished writing data, use \ref exr_finish to clean + * 6. Once finished writing data, use exr_finish() to clean * up the context, which will flush any unwritten data such as the * final chunk offset tables, and handle the temporary file flags. * * If you have custom I/O requirements, see the initializer context * documentation \ref exr_context_initializer_t. The @p ctxtdata - * parameter is optional, if NULL, default values will be used. + * parameter is optional, if `NULL`, default values will be used. */ EXR_EXPORT exr_result_t exr_start_write ( exr_context_t* ctxt, @@ -390,7 +405,7 @@ EXR_EXPORT exr_result_t exr_start_write ( enum exr_default_write_mode default_mode, const exr_context_initializer_t* ctxtdata); -/** @brief Creates a new context for updating an exr file in place +/** @brief Create a new context for updating an exr file in place. * * This is a custom mode that allows one to modify the value of a * metadata entry, although not to change the size of the header, or @@ -398,7 +413,7 @@ EXR_EXPORT exr_result_t exr_start_write ( * * If you have custom I/O requirements, see the initializer context * documentation \ref exr_context_initializer_t. The @p ctxtdata parameter - * is optional, if NULL, default values will be used. + * is optional, if `NULL`, default values will be used. */ EXR_EXPORT exr_result_t exr_start_inplace_header_update ( exr_context_t* ctxt, @@ -429,7 +444,7 @@ exr_get_user_data (exr_const_context_t ctxt, void** userdata); * *unpacked* buffer (the library will call the destroy function). * * NB: the pack function will be called twice (unless there is a - * memory failure), the first with a NULL buffer, requesting the + * memory failure), the first with a `NULL` buffer, requesting the * maximum size (or exact size if known) for the packed buffer, then * the second to fill the output packed buffer, at which point the * size can be re-updated to have the final, precise size to put into @@ -457,13 +472,13 @@ EXR_EXPORT exr_result_t exr_register_attr_type_handler ( EXR_EXPORT exr_result_t exr_set_longname_support (exr_context_t ctxt, int onoff); -/** @brief Write the header data +/** @brief Write the header data. * * Opening a new output file has a small initialization state problem - * compared to opening for read / update: we need to enable the user + * compared to opening for read/update: we need to enable the user * to specify an arbitrary set of metadata across an arbitrary number * of parts. To avoid having to create the list of parts and entire - * metadata up front, prior to calling the above \ref exr_start_write, + * metadata up front, prior to calling the above exr_start_write(), * allow the data to be set, then once this is called, it switches * into a mode where the library assumes the data is now valid. * diff --git a/src/lib/OpenEXRCore/openexr_debug.h b/src/lib/OpenEXRCore/openexr_debug.h index ac8c230bb..899c79010 100644 --- a/src/lib/OpenEXRCore/openexr_debug.h +++ b/src/lib/OpenEXRCore/openexr_debug.h @@ -12,6 +12,8 @@ extern "C" { #endif +/** @file */ + /** Debug function: print to stdout the parts and attributes of the * context @p c */ diff --git a/src/lib/OpenEXRCore/openexr_decode.h b/src/lib/OpenEXRCore/openexr_decode.h index 2a7c1a0d5..6553f3c9c 100644 --- a/src/lib/OpenEXRCore/openexr_decode.h +++ b/src/lib/OpenEXRCore/openexr_decode.h @@ -13,6 +13,8 @@ extern "C" { #endif +/** @file */ + /** Can be bit-wise or'ed into the decode_flags in the decode pipeline. * * Indicates that the sample count table should be decoded to a an @@ -21,7 +23,8 @@ extern "C" { * * Without this (i.e. a value of 0 in that bit), indicates the sample * count table should be decoded to a cumulative list (n, n+m, n+m+o, - * ...), which is the on-disk representation */ + * ...), which is the on-disk representation. + */ #define EXR_DECODE_SAMPLE_COUNTS_AS_INDIVIDUAL ((uint16_t) (1 << 0)) /** Can be bit-wise or'ed into the decode_flags in the decode pipeline. @@ -31,7 +34,7 @@ extern "C" { * mode, the user_pixel_stride and user_line_stride are used to * advance the pointer offsets for each pixel in the output, but the * user_bytes_per_element and user_data_type are used to put - * (successive) entries into each destination pointer (if not null). + * (successive) entries into each destination pointer (if not `NULL`). * * So each channel pointer must then point to an array of * chunk.width * chunk.height pointers. @@ -42,15 +45,17 @@ extern "C" { * * If this is NOT set (0), the default unpacking routine assumes the * data will be planar and contiguous (each channel is a separate - * memory block), ignoring user_line_stride and user_pixel_stride + * memory block), ignoring user_line_stride and user_pixel_stride. */ #define EXR_DECODE_NON_IMAGE_DATA_AS_POINTERS ((uint16_t) (1 << 1)) -/** When reading non-image data (i.e. deep), only read the sample table */ +/** + * When reading non-image data (i.e. deep), only read the sample table. + */ #define EXR_DECODE_SAMPLE_DATA_ONLY ((uint16_t) (1 << 2)) /** - * Structure meant to be used on a per-thread basis for reading exr data + * Struct meant to be used on a per-thread basis for reading exr data * * As should be obvious, this structure is NOT thread safe, but rather * meant to be used by separate threads, which can all be accessing @@ -58,125 +63,134 @@ extern "C" { */ typedef struct _exr_decode_pipeline { - /** the output channel information for this chunk + /** The output channel information for this chunk. * * User is expected to fill the channel pointers for the desired - * output channels (any that are NULL will be skipped) if you are - * going to use \ref exr_choose_unpack_routine. If all that is + * output channels (any that are `NULL` will be skipped) if you are + * going to use exr_decoding_choose_default_routines(). If all that is * desired is to read and decompress the data, this can be left * uninitialized. * * Describes the channel information. This information is - * allocated dynamically during \ref exr_initialize_decoding + * allocated dynamically during exr_decoding_initialize(). */ exr_coding_channel_info_t* channels; int16_t channel_count; - /** Decode flags to control the behavior*/ + /** Decode flags to control the behavior. */ uint16_t decode_flags; - /** copy of the parameters given to the initialize / update for convenience */ + /** Copy of the parameters given to the initialize/update for + * convenience. + */ int part_index; exr_const_context_t context; exr_chunk_info_t chunk; - /** - * can be used by the user to pass custom context data through - * the decode pipeline + /** Can be used by the user to pass custom context data through + * the decode pipeline. */ void* decoding_user_data; - /** the (compressed) buffer. + /** The (compressed) buffer. * - * If null, will be allocated during the run of the pipeline. + * If `NULL`, will be allocated during the run of the pipeline. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* packed_buffer; - /** used when re-using the same decode pipeline struct to know if - * chunk is changed size whether current buffer is large enough + + /** Used when re-using the same decode pipeline struct to know if + * chunk is changed size whether current buffer is large enough. */ size_t packed_alloc_size; - /** the decompressed buffer (unpacked_size from the chunk block + + /** The decompressed buffer (unpacked_size from the chunk block * info), but still packed into storage order, only needed for - * compressed files + * compressed files. * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* unpacked_buffer; - /** used when re-using the same decode pipeline struct to know if - * chunk is changed size whether current buffer is large enough + + /** Used when re-using the same decode pipeline struct to know if + * chunk is changed size whether current buffer is large enough. */ size_t unpacked_alloc_size; - /** for deep or other non-image data */ - /** packed sample table (i.e. compressed, raw on disk representation)*/ + /** For deep or other non-image data: packed sample table + * (compressed, raw on disk representation). + */ void* packed_sample_count_table; size_t packed_sample_count_alloc_size; - /** usable, native sample count table. Depending on the flag set + + /** Usable, native sample count table. Depending on the flag set * above, will be decoded to either a cumulative list (n, n+m, * n+m+o, ...), or an individual table (n, m, o, ...). As an * optimization, if the latter individual count table is chosen, * an extra int32_t will be allocated at the end of the table to * contain the total count of samples, so the table will be n+1 - * samples in size */ + * samples in size. + */ int32_t* sample_count_table; size_t sample_count_alloc_size; - /** a scratch buffer of unpacked_size for intermediate results + /** A scratch buffer of unpacked_size for intermediate results. * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* scratch_buffer_1; - /** used when re-using the same decode pipeline struct to know if - * chunk is changed size whether current buffer is large enough + + /** Used when re-using the same decode pipeline struct to know if + * chunk is changed size whether current buffer is large enough. */ size_t scratch_alloc_size_1; - /** some decompression routines may need a second scratch buffer (i.e. zlib) + + /** Some decompression routines may need a second scratch buffer (zlib). * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* scratch_buffer_2; - /** used when re-using the same decode pipeline struct to know if - * chunk is changed size whether current buffer is large enough */ + + /** Used when re-using the same decode pipeline struct to know if + * chunk is changed size whether current buffer is large enough. + */ size_t scratch_alloc_size_2; - /** - * enables a custom allocator for the different buffers (i.e. if - * decoding on a GPU). If NULL, will use the allocator from the - * context + /** Enable a custom allocator for the different buffers (if + * decoding on a GPU). If `NULL`, will use the allocator from the + * context. */ void* (*alloc_fn) (enum transcoding_pipeline_buffer_id, size_t); - /** - * enables a custom allocator for the different buffers (i.e. if - * decoding on a GPU). If NULL, will use the allocator from the - * context + + /** Enable a custom allocator for the different buffers (if + * decoding on a GPU). If `NULL`, will use the allocator from the + * context. */ void (*free_fn) (enum transcoding_pipeline_buffer_id, void*); - /** - * Function chosen to read chunk data from the context. + /** Function chosen to read chunk data from the context. * * Initialized to a default generic read routine, may be updated - * based on channel information when \ref - * exr_choose_default_routines is called. This is done such that + * based on channel information when + * exr_decoding_choose_default_routines() is called. This is done such that * if the file is uncompressed and the output channel data is * planar and the same type, the read function can read straight * into the output channels, getting closer to a zero-copy @@ -184,56 +198,55 @@ typedef struct _exr_decode_pipeline * unpack pipeline will be used with a default reader. * * This is allowed to be overridden, but probably is not necessary - * in most scenarios + * in most scenarios. */ exr_result_t (*read_fn) (struct _exr_decode_pipeline* pipeline); - /** - * Function chosen based on the compression type of the part to + + /** Function chosen based on the compression type of the part to * decompress data. * * If the user has a custom decompression method for the * compression on this part, this can be changed after * initialization. * - * If only compressed data is desired, then assign this to NULL + * If only compressed data is desired, then assign this to `NULL` * after initialization. */ exr_result_t (*decompress_fn) (struct _exr_decode_pipeline* pipeline); - /** - * Function which can be provided if you have bespoke handling for + + /** Function which can be provided if you have bespoke handling for * non-image data and need to re-allocate the data to handle the * about-to-be unpacked data. * - * If left NULL, will assume the memory pointed to by the channel - * pointers is sufficient + * If left `NULL`, will assume the memory pointed to by the channel + * pointers is sufficient. */ exr_result_t (*realloc_nonimage_data_fn) ( struct _exr_decode_pipeline* pipeline); - /** - * Function chosen based on the output layout of the channels of the part to + + /** Function chosen based on the output layout of the channels of the part to * decompress data. * - * This will be NULL after initialization, until the user + * This will be `NULL` after initialization, until the user * specifies a custom routine, or initializes the channel data and - * calls \ref exr_choose_unpack_routine. + * calls exr_decoding_choose_default_routines(). * * If only compressed data is desired, then leave or assign this - * to NULL after initialization. + * to `NULL` after initialization. */ exr_result_t (*unpack_and_convert_fn) ( struct _exr_decode_pipeline* pipeline); - /** - * Small stash of channel info values. This is faster than calling + /** Small stash of channel info values. This is faster than calling * malloc when the channel count in the part is small (RGBAZ), * which is super common, however if there are a large number of * channels, it will allocate space for that, so do not rely on - * this being used + * this being used. */ exr_coding_channel_info_t _quick_chan_store[5]; } exr_decode_pipeline_t; -/** @brief simple macro to initialize an empty decode pipeline */ +/** @brief Simple macro to initialize an empty decode pipeline. */ #define EXR_DECODE_PIPELINE_INITIALIZER \ { \ 0 \ @@ -242,9 +255,9 @@ typedef struct _exr_decode_pipeline /** Initialize the decoding pipeline structure with the channel info * for the specified part, and the first block to be read. * - * NB: The \ref unpack_and_convert_fn will be NULL after this. If that + * NB: The decode->unpack_and_convert_fn field will be `NULL` after this. If that * stage is desired, initialize the channel output information and - * call \ref exr_choose_unpack_routine + * call exr_decoding_choose_default_routines(). */ EXR_EXPORT exr_result_t exr_decoding_initialize ( @@ -254,12 +267,12 @@ exr_result_t exr_decoding_initialize ( exr_decode_pipeline_t* decode); /** Given an initialized decode pipeline, find appropriate functions - * to read and shuffle / convert data into the defined channel outputs + * to read and shuffle/convert data into the defined channel outputs. * * Calling this is not required if custom routines will be used, or if * just the raw compressed data is desired. Although in that scenario, - * it is probably easier to just read the chunk directly using \ref - * exr_read_chunk + * it is probably easier to just read the chunk directly using + * exr_read_chunk(). */ EXR_EXPORT exr_result_t exr_decoding_choose_default_routines ( @@ -269,7 +282,7 @@ exr_result_t exr_decoding_choose_default_routines ( * new chunk to be read. * * In this manner, memory buffers can be re-used to avoid continual - * malloc / free calls. Further, it allows the previous choices for + * malloc/free calls. Further, it allows the previous choices for * the various functions to be quickly re-used. */ EXR_EXPORT @@ -279,12 +292,12 @@ exr_result_t exr_decoding_update ( const exr_chunk_info_t* cinfo, exr_decode_pipeline_t* decode); -/** Execute the decoding pipeline */ +/** Execute the decoding pipeline. */ EXR_EXPORT exr_result_t exr_decoding_run ( exr_const_context_t ctxt, int part_index, exr_decode_pipeline_t* decode); -/** Free any intermediate memory in the decoding pipeline +/** Free any intermediate memory in the decoding pipeline. * * This does *not* free any pointers referred to in the channel info * areas, but rather only the intermediate buffers and memory needed diff --git a/src/lib/OpenEXRCore/openexr_encode.h b/src/lib/OpenEXRCore/openexr_encode.h index 978db7c51..f56d9e0e5 100644 --- a/src/lib/OpenEXRCore/openexr_encode.h +++ b/src/lib/OpenEXRCore/openexr_encode.h @@ -13,6 +13,8 @@ extern "C" { #endif +/** @file */ + /** Can be bit-wise or'ed into the decode_flags in the decode pipeline. * * Indicates that the sample count table should be encoded from an @@ -21,7 +23,8 @@ extern "C" { * * Without this (i.e. a value of 0 in that bit), indicates the sample * count table is already a cumulative list (n, n+m, n+m+o, ...), - * which is the on-disk representation */ + * which is the on-disk representation. + */ #define EXR_ENCODE_DATA_SAMPLE_COUNTS_ARE_INDIVIDUAL ((uint16_t) (1 << 0)) /** Can be bit-wise or'ed into the decode_flags in the decode pipeline. @@ -35,17 +38,16 @@ extern "C" { * * So each channel pointer must then point to an array of * chunk.width * chunk.height pointers. If an entry is - * NULL, 0 samples will be placed in the output. + * `NULL`, 0 samples will be placed in the output. * * If this is NOT set (0), the default packing routine assumes the * data will be planar and contiguous (each channel is a separate * memory block), ignoring user_line_stride and user_pixel_stride and - * advancing only by the sample counts and bytes per element + * advancing only by the sample counts and bytes per element. */ #define EXR_ENCODE_NON_IMAGE_DATA_AS_POINTERS ((uint16_t) (1 << 1)) -/** - * Structure meant to be used on a per-thread basis for writing exr data +/** Struct meant to be used on a per-thread basis for writing exr data. * * As should be obvious, this structure is NOT thread safe, but rather * meant to be used by separate threads, which can all be accessing @@ -53,90 +55,97 @@ extern "C" { */ typedef struct _exr_encode_pipeline { - /** the output channel information for this chunk + /** The output channel information for this chunk. * * User is expected to fill the channel pointers for the input * channels. For writing, all channels must be initialized prior - * to using \ref exr_choose_pack_routine. If a custom pack routine + * to using exr_encoding_choose_default_routines(). If a custom pack routine * is written, that is up to the implementor. * * Describes the channel information. This information is - * allocated dynamically during \ref exr_initialize_encoding + * allocated dynamically during exr_encoding_initialize(). */ exr_coding_channel_info_t* channels; int16_t channel_count; - /** Encode flags to control the behavior*/ + /** Encode flags to control the behavior. */ uint16_t encode_flags; - /** copy of the parameters given to the initialize / update for convenience */ + /** Copy of the parameters given to the initialize/update for convenience. */ int part_index; exr_const_context_t context; exr_chunk_info_t chunk; - /** - * can be used by the user to pass custom context data through - * the encode pipeline + /** Can be used by the user to pass custom context data through + * the encode pipeline. */ void* encoding_user_data; - /** the packed buffer where individual channels have been put into here. + /** The packed buffer where individual channels have been put into here. * - * If null, will be allocated during the run of the pipeline. + * If `NULL`, will be allocated during the run of the pipeline. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* packed_buffer; - /** differing from the allocation size, the number of actual bytes */ + + /** Differing from the allocation size, the number of actual bytes */ uint64_t packed_bytes; - /** used when re-using the same encode pipeline struct to know if + /** Used when re-using the same encode pipeline struct to know if * chunk is changed size whether current buffer is large enough * - * If null, will be allocated during the run of the pipeline. + * If `NULL`, will be allocated during the run of the pipeline. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ size_t packed_alloc_size; - /** for deep data. NB: the members NOT const because we need to + /** For deep data. NB: the members NOT const because we need to * temporarily swap it to xdr order and restore it (to avoid a - * duplicate buffer allocation) + * duplicate buffer allocation). * * Depending on the flag set above, will be treated either as a * cumulative list (n, n+m, n+m+o, ...), or an individual table * (n, m, o, ...). */ int32_t* sample_count_table; - /** allocated table size (to avoid re-allocations). Number of - * samples must always be width * height for the chunk */ + + /** Allocated table size (to avoid re-allocations). Number of + * samples must always be width * height for the chunk. + */ size_t sample_count_alloc_size; - /** packed sample table (i.e. compressed, raw on disk - * representation) for deep or other non-image data */ + /** Packed sample table (compressed, raw on disk representation) + * for deep or other non-image data. + */ void* packed_sample_count_table; + /** Number of bytes to write (actual size) for the - * packed_sample_count_table */ + * packed_sample_count_table. + */ size_t packed_sample_count_bytes; + /** Allocated size (to avoid re-allocations) for the - * packed_sample_count_table */ + * packed_sample_count_table. + */ size_t packed_sample_count_alloc_size; - /** the compressed buffer, only needed for - * compressed files + /** The compressed buffer, only needed for compressed files. * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* compressed_buffer; - /** must be filled in as the pipeline runs to inform the writing + + /** Must be filled in as the pipeline runs to inform the writing * software about the compressed size of the chunk (if it is an * uncompressed file or the compression would make the file * larger, it is expected to be the packed_buffer) @@ -146,10 +155,11 @@ typedef struct _exr_encode_pipeline * custom allocators. */ size_t compressed_bytes; - /** used when re-using the same encode pipeline struct to know if - * chunk is changed size whether current buffer is large enough + + /** Used when re-using the same encode pipeline struct to know if + * chunk is changed size whether current buffer is large enough. * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple @@ -158,56 +168,58 @@ typedef struct _exr_encode_pipeline */ size_t compressed_alloc_size; - /** a scratch buffer for intermediate results + /** A scratch buffer for intermediate results. * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* scratch_buffer_1; - /** used when re-using the same encode pipeline struct to know if - * chunk is changed size whether current buffer is large enough + + /** Used when re-using the same encode pipeline struct to know if + * chunk is changed size whether current buffer is large enough. * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ size_t scratch_alloc_size_1; - /** some compression routines may need a second scratch buffer + + /** Some compression routines may need a second scratch buffer. * - * If null, will be allocated during the run of the pipeline when + * If `NULL`, will be allocated during the run of the pipeline when * needed. * * If the caller wishes to take control of the buffer, simple - * adopt the pointer and set it to null here. Be cognizant of any + * adopt the pointer and set it to `NULL` here. Be cognizant of any * custom allocators. */ void* scratch_buffer_2; - /** used when re-using the same encode pipeline struct to know if - * chunk is changed size whether current buffer is large enough */ + + /** Used when re-using the same encode pipeline struct to know if + * chunk is changed size whether current buffer is large enough. + */ size_t scratch_alloc_size_2; - /** - * enables a custom allocator for the different buffers (i.e. if - * encoding on a GPU). If NULL, will use the allocator from the - * context + /** Enable a custom allocator for the different buffers (if + * encoding on a GPU). If `NULL`, will use the allocator from the + * context. */ void* (*alloc_fn) (enum transcoding_pipeline_buffer_id, size_t); - /** - * enables a custom allocator for the different buffers (i.e. if - * encoding on a GPU). If NULL, will use the allocator from the - * context + + /** Enable a custom allocator for the different buffers (if + * encoding on a GPU). If `NULL`, will use the allocator from the + * context. */ void (*free_fn) (enum transcoding_pipeline_buffer_id, void*); - /** - * Function chosen based on the output layout of the channels of the part to + /** Function chosen based on the output layout of the channels of the part to * decompress data. * * If the user has a custom method for the @@ -216,8 +228,7 @@ typedef struct _exr_encode_pipeline */ exr_result_t (*convert_and_pack_fn) (struct _exr_encode_pipeline* pipeline); - /** - * Function chosen based on the compression type of the part to + /** Function chosen based on the compression type of the part to * compress data. * * If the user has a custom compression method for the compression @@ -225,11 +236,10 @@ typedef struct _exr_encode_pipeline */ exr_result_t (*compress_fn) (struct _exr_encode_pipeline* pipeline); - /** - * This routine is used when waiting for other threads to finish + /** This routine is used when waiting for other threads to finish * writing previous chunks such that this thread can write this * chunk. This is used for parts which have a specified chunk - * ordering (increasing / decreasing y) and the chunks can not be + * ordering (increasing/decreasing y) and the chunks can not be * written randomly (as could be true for uncompressed). * * This enables the calling application to contribute thread time @@ -247,36 +257,34 @@ typedef struct _exr_encode_pipeline exr_result_t (*yield_until_ready_fn) ( struct _exr_encode_pipeline* pipeline); - /** - * Function chosen to write chunk data to the context. + /** Function chosen to write chunk data to the context. * * This is allowed to be overridden, but probably is not necessary - * in most scenarios + * in most scenarios. */ exr_result_t (*write_fn) (struct _exr_encode_pipeline* pipeline); - /** - * Small stash of channel info values. This is faster than calling + /** Small stash of channel info values. This is faster than calling * malloc when the channel count in the part is small (RGBAZ), * which is super common, however if there are a large number of * channels, it will allocate space for that, so do not rely on - * this being used + * this being used. */ exr_coding_channel_info_t _quick_chan_store[5]; } exr_encode_pipeline_t; -/** @brief simple macro to initialize an empty decode pipeline */ +/** @brief Simple macro to initialize an empty decode pipeline. */ #define EXR_ENCODE_PIPELINE_INITIALIZER \ { \ 0 \ } /** Initialize the encoding pipeline structure with the channel info - * for the specified part based on the chunk to be written + * for the specified part based on the chunk to be written. * - * NB: The \ref pack_and_convert_fn will be NULL after this. If that + * NB: The encode_pipe->pack_and_convert_fn field will be `NULL` after this. If that * stage is desired, initialize the channel output information and - * call \ref exr_choose_unpack_routine + * call exr_encoding_choose_default_routines(). */ EXR_EXPORT exr_result_t exr_encoding_initialize ( @@ -287,7 +295,7 @@ exr_result_t exr_encoding_initialize ( /** Given an initialized encode pipeline, find an appropriate * function to shuffle and convert data into the defined channel - * outputs + * outputs. * * Calling this is not required if a custom routine will be used, or * if just the raw decompressed data is desired. @@ -302,7 +310,7 @@ exr_result_t exr_encoding_choose_default_routines ( * new chunk to be written. * * In this manner, memory buffers can be re-used to avoid continual - * malloc / free calls. Further, it allows the previous choices for + * malloc/free calls. Further, it allows the previous choices for * the various functions to be quickly re-used. */ EXR_EXPORT @@ -312,14 +320,14 @@ exr_result_t exr_encoding_update ( const exr_chunk_info_t* cinfo, exr_encode_pipeline_t* encode_pipe); -/** Execute the encoding pipeline */ +/** Execute the encoding pipeline. */ EXR_EXPORT exr_result_t exr_encoding_run ( exr_const_context_t ctxt, int part_index, exr_encode_pipeline_t* encode_pipe); -/** Free any intermediate memory in the encoding pipeline +/** Free any intermediate memory in the encoding pipeline. * * This does NOT free any pointers referred to in the channel info * areas, but rather only the intermediate buffers and memory needed diff --git a/src/lib/OpenEXRCore/openexr_errors.h b/src/lib/OpenEXRCore/openexr_errors.h index 95e5e1a73..0525e10b2 100644 --- a/src/lib/OpenEXRCore/openexr_errors.h +++ b/src/lib/OpenEXRCore/openexr_errors.h @@ -14,9 +14,11 @@ extern "C" { #endif +/** @file */ + /** * @defgroup ErrorCodes Error Handling - * @brief These are a group of definitions related to error handling + * @brief These are a group of definitions related to error handling. * * All functions in the C layer will return a result, which will * correspond to one of these codes. To ensure binary stability, the @@ -25,7 +27,7 @@ extern "C" { * @{ */ -/** error codes that may be returned by various functions */ +/** Error codes that may be returned by various functions. */ typedef enum { EXR_ERR_SUCCESS = 0, @@ -63,16 +65,16 @@ typedef enum EXR_ERR_UNKNOWN } exr_error_code_t; -/** Return type for all functions */ +/** Return type for all functions. */ typedef int32_t exr_result_t; -/** @brief Return a static string corresponding to the specified error code +/** @brief Return a static string corresponding to the specified error code. * * The string should not be freed (it is compiled into the binary). */ EXR_EXPORT const char* exr_get_default_error_message (exr_result_t code); -/** @brief Return a static string corresponding to the specified error code +/** @brief Return a static string corresponding to the specified error code. * * The string should not be freed (it is compiled into the binary). */ diff --git a/src/lib/OpenEXRCore/openexr_part.h b/src/lib/OpenEXRCore/openexr_part.h index 0e366d8cc..d8d424cb2 100644 --- a/src/lib/OpenEXRCore/openexr_part.h +++ b/src/lib/OpenEXRCore/openexr_part.h @@ -14,8 +14,10 @@ extern "C" { #endif +/** @file */ + /** - * @defgroup PartInfo Part related definitions + * @defgroup PartInfo Part related definitions. * * A part is a separate entity in the OpenEXR file. This was * formalized in the OpenEXR 2.0 timeframe to allow there to be a @@ -35,22 +37,22 @@ extern "C" { * @{ */ -/** @brief Query how many parts are in the file */ +/** @brief Query how many parts are in the file. */ EXR_EXPORT exr_result_t exr_get_count (exr_const_context_t ctxt, int* count); -/** @brief Query the part name for the specified part +/** @brief Query the part name for the specified part. * * NB: If this file is a single part file and name has not been set, this - * will return NULL. + * will return `NULL`. */ EXR_EXPORT exr_result_t exr_get_name (exr_const_context_t ctxt, int part_index, const char** out); -/** @brief Query the storage type for the specified part */ +/** @brief Query the storage type for the specified part. */ EXR_EXPORT exr_result_t exr_get_storage (exr_const_context_t ctxt, int part_index, exr_storage_t* out); -/** @brief Define a new part in the file */ +/** @brief Define a new part in the file. */ EXR_EXPORT exr_result_t exr_add_part ( exr_context_t ctxt, const char* partname, @@ -64,7 +66,7 @@ EXR_EXPORT exr_result_t exr_add_part ( * Return `ERR_SUCCESS` on success, an error otherwise (i.e. if the part * is not tiled). * - * It is valid to pass NULL to either of the @p levelsx or @p levelsy + * It is valid to pass `NULL` to either of the @p levelsx or @p levelsy * arguments, which enables testing if this part is a tiled part, or * if you don't need both (i.e. in the case of a mip-level tiled * image) @@ -75,15 +77,15 @@ EXR_EXPORT exr_result_t exr_get_tile_levels ( int32_t* levelsx, int32_t* levelsy); -/** @brief Query the tile size for a particular level in the specified part +/** @brief Query the tile size for a particular level in the specified part. * * If the part is a tiled part, fill in the tile size for the - * specified part / level. + * specified part/level. * - * Return `ERR_SUCCESS` on `success`, an error otherwise (i.e. if the + * Return `ERR_SUCCESS` on success, an error otherwise (i.e. if the * part is not tiled). * - * It is valid to pass NULL to either of the @p tilew or @p tileh + * It is valid to pass `NULL` to either of the @p tilew or @p tileh * arguments, which enables testing if this part is a tiled part, or * if you don't need both (i.e. in the case of a mip-level tiled * image) @@ -96,17 +98,17 @@ EXR_EXPORT exr_result_t exr_get_tile_sizes ( int32_t* tilew, int32_t* tileh); -/** @brief Query the data sizes for a particular level in the specified part +/** @brief Query the data sizes for a particular level in the specified part. * - * If the part is a tiled part, fill in the width / height for the + * If the part is a tiled part, fill in the width/height for the * specified levels. * * Return `ERR_SUCCESS` on success, an error otherwise (i.e. if the part - * is not tiled) + * is not tiled). * - * It is valid to pass NULL to either of the @p levw or @p levh + * It is valid to pass `NULL` to either of the @p levw or @p levh * arguments, which enables testing if this part is a tiled part, or - * if you don't need both for some reason + * if you don't need both for some reason. */ EXR_EXPORT exr_result_t exr_get_level_sizes ( exr_const_context_t ctxt, @@ -116,7 +118,7 @@ EXR_EXPORT exr_result_t exr_get_level_sizes ( int32_t* levw, int32_t* levh); -/** Return the number of chunks contained in this part of the file +/** Return the number of chunks contained in this part of the file. * * As in the technical documentation for OpenEXR, the chunk is the * generic term for a pixel data block. This is the atomic unit that @@ -125,13 +127,13 @@ EXR_EXPORT exr_result_t exr_get_level_sizes ( * This should be used as a basis for splitting up how a file is * processed. Depending on the compression, a different number of * scanlines are encoded in each chunk, and since those need to be - * encoded / decoded as a block, the chunk should be the basis for I/O + * encoded/decoded as a block, the chunk should be the basis for I/O * as well. */ EXR_EXPORT exr_result_t exr_get_chunk_count (exr_const_context_t ctxt, int part_index, int32_t* out); -/** Return the number of scanlines chunks for this file part +/** Return the number of scanlines chunks for this file part. * * When iterating over a scanline file, this may be an easier metric * for multi-threading or other access than only negotiating chunk @@ -140,7 +142,7 @@ exr_get_chunk_count (exr_const_context_t ctxt, int part_index, int32_t* out); EXR_EXPORT exr_result_t exr_get_scanlines_per_chunk ( exr_const_context_t ctxt, int part_index, int32_t* out); -/** Return the maximum unpacked size of a chunk for the file part +/** Return the maximum unpacked size of a chunk for the file part. * * This may be used ahead of any actual reading of data, so can be * used to pre-allocate buffers for multiple threads in one block or @@ -151,22 +153,22 @@ EXR_EXPORT exr_result_t exr_get_chunk_unpacked_size ( /**************************************/ -/** @defgroup PartMetadata Functions to get and set metadata for a particular part +/** @defgroup PartMetadata Functions to get and set metadata for a particular part. * @{ * */ -/** @brief Query the count of attributes in a part */ +/** @brief Query the count of attributes in a part. */ EXR_EXPORT exr_result_t exr_get_attribute_count ( exr_const_context_t ctxt, int part_index, int32_t* count); enum exr_attr_list_access_mode { - EXR_ATTR_LIST_FILE_ORDER, /**< order they appear in the file */ - EXR_ATTR_LIST_SORTED_ORDER /**< alphabetically sorted */ + EXR_ATTR_LIST_FILE_ORDER, /**< Order they appear in the file. */ + EXR_ATTR_LIST_SORTED_ORDER /**< Alphabetically sorted. */ }; -/** @brief Query a particular attribute by index */ +/** @brief Query a particular attribute by index. */ EXR_EXPORT exr_result_t exr_get_attribute_by_index ( exr_const_context_t ctxt, int part_index, @@ -174,18 +176,18 @@ EXR_EXPORT exr_result_t exr_get_attribute_by_index ( int32_t idx, const exr_attribute_t** outattr); -/** @brief Query a particular attribute by name */ +/** @brief Query a particular attribute by name. */ EXR_EXPORT exr_result_t exr_get_attribute_by_name ( exr_const_context_t ctxt, int part_index, const char* name, const exr_attribute_t** outattr); -/** @brief Query the list of attributes in a part +/** @brief Query the list of attributes in a part. * * This retrieves a list of attributes currently defined in a part. * - * If outlist is NULL, this function still succeeds, filling only the + * If outlist is `NULL`, this function still succeeds, filling only the * count. In this manner, the user can allocate memory for the list of * attributes, then re-call this function to get the full list. */ @@ -196,7 +198,7 @@ EXR_EXPORT exr_result_t exr_get_attribute_list ( int32_t* count, const exr_attribute_t** outlist); -/** Declare an attribute within the specified part +/** Declare an attribute within the specified part. * * Only valid when a file is opened for write. */ @@ -207,7 +209,7 @@ EXR_EXPORT exr_result_t exr_attr_declare_by_type ( const char* type, exr_attribute_t** newattr); -/** @brief Declare an attribute within the specified part +/** @brief Declare an attribute within the specified part. * * Only valid when a file is opened for write. */ @@ -227,7 +229,7 @@ EXR_EXPORT exr_result_t exr_attr_declare ( * @{ */ -/** @brief Initialize all required attributes for all files +/** @brief Initialize all required attributes for all files. * * NB: other file types do require other attributes, such as the tile * description for a tiled file. @@ -260,7 +262,7 @@ EXR_EXPORT exr_result_t exr_initialize_required_attr_simple ( int32_t height, exr_compression_t ctype); -/** @brief Copy the attributes from one part to another +/** @brief Copy the attributes from one part to another. * * This allows one to quickly unassigned attributes from one source to another. * @@ -279,16 +281,16 @@ EXR_EXPORT exr_result_t exr_copy_unset_attributes ( exr_const_context_t source, int src_part_index); -/** @brief Retrieve the list of channels */ +/** @brief Retrieve the list of channels. */ EXR_EXPORT exr_result_t exr_get_channels ( exr_const_context_t ctxt, int part_index, const exr_attr_chlist_t** chlist); -/** @brief Define a new channel to the output file part +/** @brief Define a new channel to the output file part. * * The @p percept parameter is used for lossy compression techniques * to indicate that the value represented is closer to linear (1) or * closer to logarithmic (0). For r, g, b, luminance, this is normally - * 0 + * 0. */ EXR_EXPORT int exr_add_channel ( exr_context_t ctxt, @@ -299,64 +301,64 @@ EXR_EXPORT int exr_add_channel ( int32_t xsamp, int32_t ysamp); -/** @brief Copy the channels from another source +/** @brief Copy the channels from another source. * * Useful if you are manually constructing the list or simply copying - * from an input file + * from an input file. */ EXR_EXPORT exr_result_t exr_set_channels ( exr_context_t ctxt, int part_index, const exr_attr_chlist_t* channels); -/** @brief Retrieve the compression method used for the specified part */ +/** @brief Retrieve the compression method used for the specified part. */ EXR_EXPORT exr_result_t exr_get_compression ( exr_const_context_t ctxt, int part_index, exr_compression_t* compression); -/** @brief Set the compression method used for the specified part */ +/** @brief Set the compression method used for the specified part. */ EXR_EXPORT exr_result_t exr_set_compression ( exr_context_t ctxt, int part_index, exr_compression_t ctype); -/** @brief Retrieve the data window for the specified part */ +/** @brief Retrieve the data window for the specified part. */ EXR_EXPORT exr_result_t exr_get_data_window ( exr_const_context_t ctxt, int part_index, exr_attr_box2i_t* out); -/** @brief Set the data window for the specified part */ +/** @brief Set the data window for the specified part. */ EXR_EXPORT int exr_set_data_window ( exr_context_t ctxt, int part_index, const exr_attr_box2i_t* dw); -/** @brief Retrieve the display window for the specified part */ +/** @brief Retrieve the display window for the specified part. */ EXR_EXPORT exr_result_t exr_get_display_window ( exr_const_context_t ctxt, int part_index, exr_attr_box2i_t* out); -/** @brief Set the display window for the specified part */ +/** @brief Set the display window for the specified part. */ EXR_EXPORT int exr_set_display_window ( exr_context_t ctxt, int part_index, const exr_attr_box2i_t* dw); -/** @brief Retrieve the line order for storing data in the specified part (use 0 for single part images) */ +/** @brief Retrieve the line order for storing data in the specified part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_get_lineorder ( exr_const_context_t ctxt, int part_index, exr_lineorder_t* out); -/** @brief Set the line order for storing data in the specified part (use 0 for single part images) */ +/** @brief Set the line order for storing data in the specified part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_set_lineorder (exr_context_t ctxt, int part_index, exr_lineorder_t lo); /** @brief Retrieve the pixel aspect ratio for the specified part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_get_pixel_aspect_ratio ( exr_const_context_t ctxt, int part_index, float* par); -/** @brief Set the pixel aspect ratio for the specified part (use 0 for single part images) */ +/** @brief Set the pixel aspect ratio for the specified part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_set_pixel_aspect_ratio (exr_context_t ctxt, int part_index, float par); -/** @brief Retrieve the screen oriented window center for the specified part (use 0 for single part images) */ +/** @brief Retrieve the screen oriented window center for the specified part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_get_screen_window_center ( exr_const_context_t ctxt, int part_index, exr_attr_v2f_t* wc); -/** @brief Set the screen oriented window center for the specified part (use 0 for single part images) */ +/** @brief Set the screen oriented window center for the specified part (use 0 for single part images). */ EXR_EXPORT int exr_set_screen_window_center ( exr_context_t ctxt, int part_index, const exr_attr_v2f_t* wc); -/** @brief Retrieve the screen oriented window width for the specified part (use 0 for single part images) */ +/** @brief Retrieve the screen oriented window width for the specified part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_get_screen_window_width ( exr_const_context_t ctxt, int part_index, float* out); -/** @brief Set the screen oriented window width for the specified part (use 0 for single part images) */ +/** @brief Set the screen oriented window width for the specified part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_set_screen_window_width (exr_context_t ctxt, int part_index, float ssw); -/** @brief Retrieve the tiling info for a tiled part (use 0 for single part images) */ +/** @brief Retrieve the tiling info for a tiled part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_get_tile_descriptor ( exr_const_context_t ctxt, int part_index, @@ -365,7 +367,7 @@ EXR_EXPORT exr_result_t exr_get_tile_descriptor ( exr_tile_level_mode_t* level, exr_tile_round_mode_t* round); -/** @brief Set the tiling info for a tiled part (use 0 for single part images) */ +/** @brief Set the tiling info for a tiled part (use 0 for single part images). */ EXR_EXPORT exr_result_t exr_set_tile_descriptor ( exr_context_t ctxt, int part_index, @@ -386,7 +388,7 @@ exr_set_version (exr_context_t ctxt, int part_index, int32_t val); EXR_EXPORT exr_result_t exr_set_chunk_count (exr_context_t ctxt, int part_index, int32_t val); -/** @} */ /* required attr group */ +/** @} */ /* required attr group. */ /** * @defgroup BuiltinAttributeHelpers Attribute utilities for builtin types @@ -420,7 +422,7 @@ EXR_EXPORT exr_result_t exr_attr_set_box2f ( const char* name, const exr_attr_box2f_t* val); -/** @brief Zero-copy query of channel data +/** @brief Zero-copy query of channel data. * * Do not free or manipulate the @p chlist data, or use * after the lifetime of the context. @@ -432,7 +434,7 @@ EXR_EXPORT exr_result_t exr_attr_get_channels ( const exr_attr_chlist_t** chlist); /** @brief This allows one to quickly copy the channels from one file - * to another + * to another. */ EXR_EXPORT exr_result_t exr_attr_set_channels ( exr_context_t ctxt, @@ -485,7 +487,7 @@ EXR_EXPORT exr_result_t exr_attr_get_float ( EXR_EXPORT exr_result_t exr_attr_set_float ( exr_context_t ctxt, int part_index, const char* name, float val); -/** @brief Zero-copy query of float data +/** @brief Zero-copy query of float data. * * Do not free or manipulate the @p out data, or use after the * lifetime of the context. @@ -603,7 +605,7 @@ EXR_EXPORT exr_result_t exr_attr_set_rational ( const char* name, const exr_attr_rational_t* r); -/** @brief Zero-copy query of string value +/** @brief Zero-copy query of string value. * * Do not modify the string pointed to by @p out, and do not use * after the lifetime of the context. @@ -618,13 +620,13 @@ EXR_EXPORT exr_result_t exr_attr_get_string ( EXR_EXPORT exr_result_t exr_attr_set_string ( exr_context_t ctxt, int part_index, const char* name, const char* s); -/** @brief Zero-copy query of string data +/** @brief Zero-copy query of string data. * * Do not free the strings pointed to by the array. * * Must provide @p size. * - * @param out must be a ``const char**`` array large enough to hold + * \p out must be a ``const char**`` array large enough to hold * the string pointers for the string vector when provided. */ EXR_EXPORT exr_result_t exr_attr_get_string_vector ( diff --git a/src/lib/OpenEXRCore/openexr_std_attr.h b/src/lib/OpenEXRCore/openexr_std_attr.h index c3cc0eb80..959f0533e 100644 --- a/src/lib/OpenEXRCore/openexr_std_attr.h +++ b/src/lib/OpenEXRCore/openexr_std_attr.h @@ -12,6 +12,8 @@ extern "C" { #endif +/** @file */ + /** * @defgroup Standard attributes * @brief These are a group of attributes which are not strictly required,