@brief Disables reconstruction logic upon corrupt / missing data chunks * * This will disable the reconstruction logic that searches through an * incomplete file, and will instead just return errors at read * time. This is only valid for reading contexts

@brief Disables error messages while parsing headers * * The return values will remain the same, but error reporting will be * skipped. This is only valid for reading contexts

@brief context flag which will enforce strict header validation * checks and may prevent reading of files which could otherwise be * processed.

Can be bit-wise or'ed into the decode_flags in the decode pipeline. * * Indicates that the data in the channel pointers to decode to is not * a direct pointer, but instead is a pointer-to-pointers. In this * 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`). * * So each channel pointer must then point to an array of * chunk.width * chunk.height pointers. * * With this, you can only extract desired pixels (although all the * pixels must be initially decompressed) to handle such operations * like proxying where you might want to read every other pixel. * * 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.

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 * individual sample count list (n, m, o, ...), with an extra int at * the end containing the total samples. * * 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.

* * When reading non-image data (i.e. deep), only read the sample table.

@brief Simple macro to initialize the context initializer with default values.

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 * individual sample count list (n, m, o, ...), meaning it will have * to compute the cumulative counts on the fly. * * 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.

Can be bit-wise or'ed into the decode_flags in the decode pipeline. * * Indicates that the data in the channel pointers to encode from is not * a direct pointer, but instead is a pointer-to-pointers. In this * 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. * * 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. * * 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.

@brief Struct to hold a floating-point box/region definition.

@brief Struct to hold an integer box/region definition.

Individual channel information.

List of channel information (sorted alphabetically).

@brief Struct to hold color chromaticities to interpret the tristimulus color values in the image data.

Float vector storage struct.

@brief Struct to hold keycode information.

@brief struct to hold a 64-bit floating-point 3x3 matrix.

@brief struct to hold a 32-bit floating-point 3x3 matrix.

@brief Struct to hold a 64-bit floating-point 4x4 matrix.

@brief Struct to hold a 32-bit floating-point 4x4 matrix.

Custom storage structure for opaque data. * * Handlers for opaque types can be registered, then when a * non-builtin type is encountered with a registered handler, the * function pointers to unpack/pack it will be set up. * * @sa register_attr_type_handler

@brief Struct to define attributes of an embedded preview image.

@brief Struct to hold an integer ratio value.

Storage for a string.

Storage for a string vector.

@brief Struct holding base tiledesc attribute type defined in spec * * NB: This is in a tightly packed area so it can be read directly, be * careful it doesn't become padded to the next \c uint32_t boundary.

@brief Struct to hold timecode information.

@brief Struct to hold a 2-element 64-bit float vector.

@brief Struct to hold a 2-element 32-bit float vector.

@brief Struct to hold a 2-element integer vector.

@brief Struct to hold a 3-element 64-bit float vector.

@brief Struct to hold a 3-element 32-bit float vector.

@brief Struct to hold a 3-element integer vector.

@brief Storage, name and type information for an attribute. * * Attributes (metadata) for the file cause a surprising amount of * overhead. It is not uncommon for a production-grade EXR to have * many attributes. As such, the attribute struct is designed in a * slightly more complicated manner. It is optimized to have the * storage for that attribute: the struct itself, the name, the type, * and the data all allocated as one block. Further, the type and * standard names may use a static string to avoid allocating space * for those as necessary with the pointers pointing to static strings * (not to be freed). Finally, small values are optimized for.

@brief Built-in/native attribute type enum. * * This will enable us to do a tagged type struct to generically store * attributes.

* * 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 * common between all different forms of data that can be stored.

@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 * chunks for read and write, respectively. * * The first half of the structure will be filled by the library, and * the caller is expected to fill the second half appropriately.

Enum declaring allowed values for \c u8 value stored in built-in compression type.

@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. * * 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. * * It can be initialized using \c EXR_DEFAULT_CONTEXT_INITIALIZER. * * \code{.c} * exr_context_initializer_t myctxtinit = DEFAULT_CONTEXT_INITIALIZER; * myctxtinit.error_cb = &my_super_cool_error_callback_function; * ... * \endcode *

* * 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 * the same context concurrently.

@brief Enum describing how default files are handled during write.

Destroy custom stream function pointer * * Generic callback to clean up user data for custom streams. * This is called when the file is closed and expected not to * error. * * @param failed Indicates the write operation failed, the * implementor may wish to cleanup temporary files

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 * the same context concurrently.

Enum declaring allowed values for \c u8 value stored in built-in env map type.

@brief Error callback function * * Because a file can be read from using many threads at once, it is * difficult to store an error message for later retrieval. As such, * when a file is constructed, a callback function can be provided * which delivers an error message for the calling application to * handle. This will then be delivered on the same thread causing the * error.

Enum declaring allowed values for \c u8 value stored in \c lineOrder type.

@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 * happen during processing of a file or stream. This can be used by * systems which provide rich malloc tracking routines to override the * 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 and return an out-of-memory error). * * If one is provided, both should be provided. * @sa exr_memory_free_func_t

@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 * happen during processing of a file or stream. This can be used by * systems which provide rich malloc tracking routines to override the * internal allocations performed by the library. * * This function is expected to return memory to the system, ala free * from the C library. * * If providing one, probably need to provide both routines. * @sa exr_memory_allocation_func_t

Hint for lossy compression methods about how to treat values * (logarithmic or linear), meaning a human sees values like R, G, B, * luminance difference between 0.1 and 0.2 as about the same as 1.0 * to 2.0 (logarithmic), where chroma coordinates are closer to linear * (0.1 and 0.2 is about the same difference as 1.0 and 1.1).

@brief Enum capturing the underlying data type on a channel.

Query stream size function pointer * * Used to query the size of the file, or amount of data representing * the openexr file in the data stream. * * This is used to validate requests against the file. If the size is * unavailable, return -1, which will disable these validation steps * for this file, although appropriate memory safeguards must be in * place in the calling application.

@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. * * It is required that this provides thread-safe concurrent access to * 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. * * A file should be expected to be accessed in the following pattern: * - upon open, the header and part information attributes will be read * - upon the first image read request, the offset tables will be read * multiple threads accessing this concurrently may actually read * these values at the same time * - chunks can then be read in any order as preferred by the * application * * 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 * 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 * atomically.

Error codes that may be returned by various functions. Return type for all functions.

Enum declaring allowed values for part type.

@brief Stream error notifier * * This function pointer is provided to the stream functions by the * library such that they can provide a nice error message to the * user during stream operations.

@brief Enum representing what type of tile information is contained.

@brief Enum representing how to scale positions between levels.

* * 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).

Write custom function pointer * * Used to write data to a custom output. Expects similar semantics to * 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. * * - 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. * * - 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. * * - at file close, the chunk offset tables are written to the file.

@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.

@brief Define a new part in the file.

@brief Declare an attribute within the specified part. * * Only valid when a file is opened for write.

Declare an attribute within the specified part. * * Only valid when a file is opened for write.

@brief Zero-copy query of channel data. * * Do not free or manipulate the @p chlist data, or use * after the lifetime of the context.

@brief Zero-copy query of float data. * * Do not free or manipulate the @p out data, or use after the * lifetime of the context.

@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.

@brief Zero-copy query of string data. * * Do not free the strings pointed to by the array. * * Must provide @p size. * * \p out must be a ``^cstring`` array large enough to hold * the string pointers for the string vector when provided.

@brief This allows one to quickly copy the channels from one file * to another.

initialize chunk info with the default values from the specified part * * The 'x' and 'y' parameters are used to indicate the starting position * of the chunk being initialized. This does not perform any I/O to validate * and so the values are only indicative. (but can be used to do things * like compress / decompress a chunk without having a file to actually * read

Compresses a buffer using a zlib style compression. * * If the level is -1, will use the default compression set to the library * \ref set_default_zip_compression_level * data. This may include some extra padding for headers / scratch

Exposes a method to apply compression to a chunk of data. * * This can be useful for inheriting default behavior of the * compression stage of an encoding pipeline, or other helper classes * to expose compression. * * NB: As implied, this function will be used during a normal encode * and write operation but can be used directly with a temporary * context (i.e. not running the full encode pipeline).

Computes a buffer that will be large enough to hold the compressed * data. This may include some extra padding for headers / scratch

Routine to query the lines required per chunk to compress with the * specified method. * * This is only meaningful for scanline encodings, tiled * representations have a different interpretation of this. * * These are constant values, this function returns -1 if the compression * type is unknown.

@brief Copy the attributes from one part to another. * * This allows one to quickly unassigned attributes from one source to another. * * If an attribute in the source part has not been yet set in the * destination part, the item will be copied over. * * For example, when you add a part, the storage type and name * attributes are required arguments to the definition of a new part, * but channels has not yet been assigned. So by calling this with an * input file as the source, you can copy the channel definitions (and * any other unassigned attributes from the source).

Given an initialized decode pipeline, find appropriate functions * 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 * exr_read_chunk().

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 * for the structure itself.

Initialize the decoding pipeline structure with the channel info * for the specified part, and the first block to be read. * * 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 exr_decoding_choose_default_routines().

Execute the decoding pipeline.

Given a decode pipeline previously initialized, update it for the * 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 * the various functions to be quickly re-used.

Given an initialized encode pipeline, find an appropriate * function to shuffle and convert data into the defined channel * outputs. * * Calling this is not required if a custom routine will be used, or * if just the raw decompressed data is desired.

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 * for the structure itself.

Initialize the encoding pipeline structure with the channel info * for the specified part based on the chunk to be written. * * 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 exr_encoding_choose_default_routines().

Execute the encoding pipeline.

Given a encode pipeline previously initialized, update it for the * 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 * the various functions to be quickly re-used.

Return whether the chunk table for this part is completely written. * * This only validates that all the offsets are valid. * * return EXR_ERR_INCOMPLETE_CHUNK_TABLE when incomplete, EXR_ERR_SUCCESS * if it appears ok, or another error if otherwise problematic

@brief Close and free any internally allocated memory, * 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.

@brief Query a particular attribute by index.

@brief Query a particular attribute by name.

@brief Query the count 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 * count. In this manner, the user can allocate memory for the list of * attributes, then re-call this function to get the full list.

@brief Retrieve the list of channels.

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 * this library uses to negotiate data to and from a context. * * 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 * as well.

Return a pointer to the chunk table and the count * * TODO: consider removing this prior to release once C++ fully converted

@brief Retrieve the chunk table offset for the part in question.

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 * whatever your application may require.

@brief Retrieve the compression method used for the specified part.

@brief Query how many parts are in the file.

@brief Retrieve the data window for the specified part.

@brief Retrieve the global default dwa compression quality

@brief Return a static string corresponding to the specified error code. * * The string should not be freed (it is compiled into the binary).

@brief Retrieve the global default maximum image size. * * This function does not fail.

@brief Retrieve the global maximum tile size. * * This function does not fail.

@brief Retrieve the global default zip compression value

@brief Retrieve the display window for the specified part.

@brief Retrieve the dwa compression level used for the specified part. * * This only applies when the compression method is DWAA/DWAB. * * This value is NOT persisted in the file, and only exists for the * lifetime of the context, so will be at the default value when just * reading a file.

@brief Return a static string corresponding to the specified error code. * * The string should not be freed (it is compiled into the binary).

@brief Retrieve the file name the context is for as provided * during the start routine. * * Do not free the resulting string.

@brief Retrieve the file version and flags the context is for as * parsed during the start routine.

@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 * specified levels. * * 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 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.

@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.

@brief Retrieve the line order for storing data in the specified part (use 0 for single part images).

@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`.

@brief Retrieve the pixel aspect ratio for the specified part (use 0 for single part images).

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 * counts, and so is provided as a utility.

@brief Retrieve the screen oriented window center 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).

@brief Query the storage type for the specified part.

@brief Query the tile count for a particular level in the specified part. * * If the part is a tiled part, fills in the count for the * specified levels. * * 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 countx or @p county * arguments, which enables testing if this part is a tiled part, or * if you don't need both for some reason.

@brief Retrieve the tiling info for a tiled part (use 0 for single part images).

@brief Macro to access type of tiling from packed structure.

@brief Query how many levels are in the specified part. * * If the part is a tiled part, fill in how many tile levels are present. * * 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 * 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)

@brief Macro to access the rounding mode of tiling from packed structure.

@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. * * 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 * 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)

@brief Query the user data the context was constructed with. This * is perhaps useful in the error handler callback to jump back into * an object the user controls.

@brief Retrieve the zip compression level used for the specified part. * * This only applies when the compression method involves using zip * compression (zip, zips, some modes of DWAA/DWAB). * * This value is NOT persisted in the file, and only exists for the * lifetime of the context, so will be at the default value when just * reading a file.

@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.

@brief Initialize all required attributes to default values: * * - `displayWindow` is set to (0, 0 -> @p width - 1, @p height - 1) * - `dataWindow` is set to (0, 0 -> @p width - 1, @p height - 1) * - `pixelAspectRatio` is set to 1.0 * - `screenWindowCenter` is set to 0.f, 0.f * - `screenWindowWidth` is set to 1.f * - `lineorder` is set to `INCREASING_Y` * - `compression` is set to @p ctype

@brief Macro to pack the tiling type and rounding mode into packed structure.

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.

* * Read chunk for deep data. * * This allows one to read the packed data, the sample count data, or both. * \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.

Any opaque attribute data entry of the specified type is tagged * with these functions enabling downstream users to unpack (or pack) * the data. * * The library handles the memory packed data internally, but the * handler is expected to allocate and manage memory for the * *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 * 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 * the file.

Apply simple run length encoding and put in the output buffer.

Decode run length encoding and put in the output buffer.

@brief Copy the channels from another source. * * Useful if you are manually constructing the list or simply copying * from an input file.

@brief Set the compression method used for the specified part.

@brief Set the data window for the specified part.

@brief Assigns a default DWA compression quality level. * * This value may be controlled separately on each part, but this * global control determines the initial value.

@brief Limit the size of image allowed to be parsed or created by * 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. * * These values are among the only globals in the core layer of * OpenEXR. The intended use is for applications to define a global * default, which will be combined with the values provided to the * individual context creation routine. The values are used to check * against parsed header values. This adds some level of safety from * memory overruns where a corrupt file given to the system may cause * a large allocation to happen, enabling buffer overruns or other * potential security issue. * * These global values are combined with the values in * \ref exr_context_initializer_t using the following rules: * * 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. * * 3. If both are positive (non-zero), the minimum value is used. * * 4. If both values are 0, this disables the constrained size checks. * * This function does not fail.

@brief Limit the size of an image tile allowed to be parsed or * created by the library. * * Similar to image size, this places constraints on the maximum tile * size as a safety check against bad file data * * 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 * * These values are among the only globals in the core layer of * OpenEXR. The intended use is for applications to define a global * default, which will be combined with the values provided to the * individual context creation routine. The values are used to check * against parsed header values. This adds some level of safety from * memory overruns where a corrupt file given to the system may cause * a large allocation to happen, enabling buffer overruns or other * potential security issue. * * These global values are combined with the values in * \ref exr_context_initializer_t using the following rules: * * 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. * * 3. If both are positive (non-zero), the minimum value is used. * * 4. If both values are 0, this disables the constrained size checks. * * This function does not fail.

@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. * * This function does not fail.

@brief Assigns a default zip compression level. * * This value may be controlled separately on each part, but this * global control determines the initial value.

@brief Set the display window for the specified part.

@brief Set the dwa compression method used for the specified part. * * This only applies when the compression method is DWAA/DWAB. * * This value is NOT persisted in the file, and only exists for the * lifetime of the context, so this value will be ignored when * reading a file.

@brief Set the line order for storing data in 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).

@brief Set the screen oriented window center 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).

@brief Set the tiling info for a tiled part (use 0 for single part images).

@brief Set the zip compression method used for the specified part. * * This only applies when the compression method involves using zip * compression (zip, zips, some modes of DWAA/DWAB). * * This value is NOT persisted in the file, and only exists for the * lifetime of the context, so this value will be ignored when * reading a file.

@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 * any of the image data. * * 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.

@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 * previously opened a stream, file, or whatever and placed relevant * data in userdata to access that. * * One notable attribute of the context is that once it has been * created and returned a successful code, it has parsed all the * header data. This is done as one step such that it is easier to * provide a safe context for multiple threads to request data from * the same context concurrently. * * Once finished reading data, use exr_finish() to clean up * the context. * * 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.

@brief Create a new context for temporary use in memory. * * This is a custom mode that does not supporting writing actual image * data, but one can create one of these, manipulate attributes, * define additional parts, run validation, etc. without any * requirement of actual file i/o. * * Note that this creates an defines an initial part for use, so one * can immediately start definining attributes into part index 0. * * See the initializer context documentation \ref * exr_context_initializer_t to be able to provide allocation * overrides or other controls. The @p ctxtdata parameter is optional, * if `NULL`, default values will be used.

@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 * ignored. As such, the system assumes the user has previously opened * a stream, file, or whatever and placed relevant data in userdata to * access that. * * Multi-Threading: To avoid issues with creating multi-part EXR * files, the library approaches writing as a multi-step process, so * the same concurrent guarantees can not be made for writing a * file. The steps are: * * 1. Context creation (this function) * * 2. Part definition (required attributes and additional metadata) * * 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₀ * -> part_N-1). * * 5. Within each part, multiple threads can be encoding and writing * data concurrently. For some EXR part definitions, this may be able * to write data concurrently when it can predict the chunk sizes, or * data is allowed to be padded. For others, it may need to * 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 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.

@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).

Decompresses a buffer using a zlib style compression.

Exposes a method to decompress a chunk of data. * * This can be useful for inheriting default behavior of the * uncompression stage of an decoding pipeline, or other helper classes * to expose compress / uncompress operations. * * NB: This function will be used during a normal read and decode * operation but can be used directly with a temporary context (i.e. * not running the full decode pipeline).

* * @p y must the appropriate starting y for the specified chunk.

@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 * 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 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. * * It will recompute the number of chunks that will be written, and * reset the chunk offsets. If you modify file attributes or part * information after a call to this, it will error.

* * @p y must the appropriate starting y for the specified chunk.

Initialize a \c chunk_info_t structure when encoding scanline * data (similar to read but does not do anything with a chunk * table).

Initialize a \c chunk_info_t structure when encoding tiled data * (similar to read but does not do anything with a chunk table).