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,