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

Collaboration diagram for OpenEXR Context Stream/File Functions:

Classes
struct	_exr_context_initializer_v3
	Struct used to pass function pointers into the context initialization routines. More...

Macros
#define	EXR_CONTEXT_FLAG_STRICT_HEADER (1 << 0)
	context flag which will enforce strict header validation checks and may prevent reading of files which could otherwise be processed. More...

#define	EXR_CONTEXT_FLAG_SILENT_HEADER_PARSE (1 << 1)
	Disables error messages while parsing headers. More...

#define	EXR_CONTEXT_FLAG_DISABLE_CHUNK_RECONSTRUCTION (1 << 2)
	Disables reconstruction logic upon corrupt / missing data chunks. More...

#define	EXR_CONTEXT_FLAG_WRITE_LEGACY_HEADER (1 << 3)
	Writes an old-style, sorted header with minimal information. More...

#define	EXR_DEFAULT_CONTEXT_INITIALIZER { sizeof (exr_context_initializer_t), 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -2, -1.f, 0, { 0, 0, 0, 0 } }
	Simple macro to initialize the context initializer with default values. More...

Typedefs
typedef exr_result_t(*	exr_stream_error_func_ptr_t )(exr_const_context_t ctxt, exr_result_t code, const char *fmt,...) EXR_PRINTF_FUNC_ATTRIBUTE
	Stream error notifier. More...

typedef void(*	exr_error_handler_cb_t )(exr_const_context_t ctxt, exr_result_t code, const char *msg)
	Error callback function. More...

typedef void(*	exr_destroy_stream_func_ptr_t )(exr_const_context_t ctxt, void *userdata, int failed)

typedef int64_t(*	exr_query_size_func_ptr_t )(exr_const_context_t ctxt, void *userdata)

typedef int64_t(*	exr_read_func_ptr_t )(exr_const_context_t ctxt, void userdata, void buffer, uint64_t sz, uint64_t offset, exr_stream_error_func_ptr_t error_cb)
	Read custom function pointer. More...

typedef int64_t(*	exr_write_func_ptr_t )(exr_const_context_t ctxt, void userdata, const void buffer, uint64_t sz, uint64_t offset, exr_stream_error_func_ptr_t error_cb)

typedef struct _exr_context_initializer_v3	exr_context_initializer_t
	Struct used to pass function pointers into the context initialization routines. More...

Detailed Description

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

Macro Definition Documentation

#define EXR_CONTEXT_FLAG_DISABLE_CHUNK_RECONSTRUCTION (1 << 2)

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

Definition at line 345 of file openexr_context.h.

#define EXR_CONTEXT_FLAG_SILENT_HEADER_PARSE (1 << 1)

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

Definition at line 337 of file openexr_context.h.

#define EXR_CONTEXT_FLAG_STRICT_HEADER (1 << 0)

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

Definition at line 330 of file openexr_context.h.

#define EXR_CONTEXT_FLAG_WRITE_LEGACY_HEADER (1 << 3)

Writes an old-style, sorted header with minimal information.

Definition at line 348 of file openexr_context.h.

#define EXR_DEFAULT_CONTEXT_INITIALIZER { sizeof (exr_context_initializer_t), 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -2, -1.f, 0, { 0, 0, 0, 0 } }

Simple macro to initialize the context initializer with default values.

Definition at line 352 of file openexr_context.h.

Typedef Documentation

typedef struct _exr_context_initializer_v3 exr_context_initializer_t

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

exr_context_initializer_t myctxtinit = DEFAULT_CONTEXT_INITIALIZER;
myctxtinit.error_cb = &my_super_cool_error_callback_function;
...

typedef void(* exr_destroy_stream_func_ptr_t)(exr_const_context_t ctxt, void *userdata, int failed)

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.

Parameters

failed	Indicates the write operation failed, the implementor may wish to cleanup temporary files
ctxt	The context
userdata	The userdata

Definition at line 88 of file openexr_context.h.

typedef void(* exr_error_handler_cb_t)(exr_const_context_t ctxt, exr_result_t code, const char *msg)

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.

Definition at line 74 of file openexr_context.h.

typedef int64_t(* exr_query_size_func_ptr_t)(exr_const_context_t ctxt, void *userdata)

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.

Definition at line 101 of file openexr_context.h.

typedef int64_t(* exr_read_func_ptr_t)(exr_const_context_t ctxt, void *userdata, void *buffer, uint64_t sz, uint64_t offset, exr_stream_error_func_ptr_t error_cb)

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.

Definition at line 129 of file openexr_context.h.

typedef exr_result_t(* exr_stream_error_func_ptr_t)(exr_const_context_t ctxt, exr_result_t code, const char *fmt,...) EXR_PRINTF_FUNC_ATTRIBUTE

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.

Definition at line 61 of file openexr_context.h.

typedef int64_t(* exr_write_func_ptr_t)(exr_const_context_t ctxt, void *userdata, const void *buffer, uint64_t sz, uint64_t offset, exr_stream_error_func_ptr_t error_cb)

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.

Definition at line 161 of file openexr_context.h.

Classes

Macros

Typedefs

Detailed Description

Macro Definition Documentation

Typedef Documentation