Collaboration diagram for Context related definitions:

Modules
	OpenEXR Context Stream/File Functions
	These are a group of function interfaces used to customize the error handling, memory allocations, or I/O behavior of an OpenEXR context.

Typedefs
typedef struct _priv_exr_context_t *	exr_context_t

typedef const struct _priv_exr_context_t *	exr_const_context_t

typedef enum exr_default_write_mode	exr_default_write_mode_t
	Enum describing how default files are handled during write. More...

Enumerations
enum	exr_default_write_mode { EXR_WRITE_FILE_DIRECTLY, EXR_INTERMEDIATE_TEMP_FILE }
	Enum describing how default files are handled during write. More...

Functions
EXR_EXPORT exr_result_t	exr_test_file_header (const char filename, const exr_context_initializer_t ctxtdata)
	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). More...

EXR_EXPORT exr_result_t	exr_finish (exr_context_t *ctxt)
	Close and free any internally allocated memory, calling any provided destroy function for custom streams. More...

EXR_EXPORT exr_result_t	exr_start_read (exr_context_t ctxt, const char filename, const exr_context_initializer_t *ctxtdata)
	Create and initialize a read-only exr read context. More...

EXR_EXPORT exr_result_t	exr_start_write (exr_context_t ctxt, const char filename, exr_default_write_mode_t default_mode, const exr_context_initializer_t *ctxtdata)
	Create and initialize a write-only context. More...

EXR_EXPORT exr_result_t	exr_start_inplace_header_update (exr_context_t ctxt, const char filename, const exr_context_initializer_t *ctxtdata)
	Create a new context for updating an exr file in place. More...

EXR_EXPORT exr_result_t	exr_get_file_name (exr_const_context_t ctxt, const char **name)
	Retrieve the file name the context is for as provided during the start routine. More...

EXR_EXPORT exr_result_t	exr_get_user_data (exr_const_context_t ctxt, void **userdata)
	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. More...

EXR_EXPORT exr_result_t	exr_register_attr_type_handler (exr_context_t ctxt, const char type, exr_result_t(unpack_func_ptr)(exr_context_t ctxt, const void data, int32_tattrsize, int32_t outsize, void *outbuffer), exr_result_t(pack_func_ptr)(exr_context_t ctxt, const void data, int32_tdatasize, int32_t outsize, void outbuffer), void(destroy_unpacked_func_ptr)(exr_context_t ctxt, void *data, int32_t datasize))

EXR_EXPORT exr_result_t	exr_set_longname_support (exr_context_t ctxt, int onoff)
	Enable long name support in the output context. More...

EXR_EXPORT exr_result_t	exr_write_header (exr_context_t ctxt)
	Write the header data. More...

Detailed Description

A context is a single instance of an OpenEXR file or stream. Beyond a particular file or stream handle, it also has separate controls for error handling and memory allocation. This is done to enable encoding or decoding on mixed hardware.

Typedef Documentation

typedef const struct _priv_exr_context_t* exr_const_context_t

Definition at line 43 of file openexr_context.h.

typedef struct _priv_exr_context_t* exr_context_t

Opaque context handle

The implementation of this is partly opaque to provide better 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.

Definition at line 42 of file openexr_context.h.

typedef enum exr_default_write_mode exr_default_write_mode_t

Enum describing how default files are handled during write.

Enumeration Type Documentation

enum exr_default_write_mode

Enum describing how default files are handled during write.

Enumerator
EXR_WRITE_FILE_DIRECTLY	Overwrite filename provided directly, deleted upon error.
EXR_INTERMEDIATE_TEMP_FILE	Create a temporary file, renaming it upon successful write, leaving original upon error

Definition at line 395 of file openexr_context.h.

Function Documentation

EXR_EXPORT exr_result_t exr_finish ( exr_context_t * ctxt )

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.

EXR_EXPORT exr_result_t exr_get_file_name	(	exr_const_context_t	ctxt,
		const char **	name
	)

Retrieve the file name the context is for as provided during the start routine.

Do not free the resulting string.

EXR_EXPORT exr_result_t exr_get_user_data	(	exr_const_context_t	ctxt,
		void **	userdata
	)

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.

EXR_EXPORT exr_result_t exr_register_attr_type_handler	(	exr_context_t	ctxt,
		const char *	type,
		exr_result_t()(exr_context_t ctxt, const void data, int32_tattrsize, int32_t outsize, void *outbuffer)	unpack_func_ptr,
		exr_result_t()(exr_context_t ctxt, const void data, int32_tdatasize, int32_t outsize, void outbuffer)	pack_func_ptr,
		void()(exr_context_t ctxt, void data, int32_t datasize)	destroy_unpacked_func_ptr
	)

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.

EXR_EXPORT exr_result_t exr_set_longname_support	(	exr_context_t	ctxt,
		int	onoff
	)

Enable long name support in the output context.

EXR_EXPORT exr_result_t exr_start_inplace_header_update	(	exr_context_t *	ctxt,
		const char *	filename,
		const exr_context_initializer_t *	ctxtdata
	)

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 exr_context_initializer_t. The ctxtdata parameter is optional, if NULL, default values will be used.

EXR_EXPORT exr_result_t exr_start_read	(	exr_context_t *	ctxt,
		const char *	filename,
		const exr_context_initializer_t *	ctxtdata
	)

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 exr_context_initializer_t. The ctxtdata parameter is optional, if NULL, default values will be used.

EXR_EXPORT exr_result_t exr_start_write	(	exr_context_t *	ctxt,
		const char *	filename,
		exr_default_write_mode_t	default_mode,
		const exr_context_initializer_t *	ctxtdata
	)

Create and initialize a write-only context.

If a custom write function is provided, the filename is for informational purposes only, and the 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:

Context creation (this function)
Part definition (required attributes and additional metadata)
Transition to writing data (this "commits" the part definitions, any changes requested after will result in an error)
Write part data in sequential order of parts (part₀ -> part_N-1).
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
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 exr_context_initializer_t. The ctxtdata parameter is optional, if NULL, default values will be used.

EXR_EXPORT exr_result_t exr_test_file_header	(	const char *	filename,
		const exr_context_initializer_t *	ctxtdata
	)

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

EXR_EXPORT exr_result_t exr_write_header ( exr_context_t ctxt )

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.

Modules

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation