openexr_decode.h File Reference

#include "openexr_chunkio.h"
#include "openexr_coding.h"

Include dependency graph for openexr_decode.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	_exr_decode_pipeline

Macros
#define	EXR_DECODE_SAMPLE_COUNTS_AS_INDIVIDUAL   ((uint16_t) (1 << 0))
#define	EXR_DECODE_NON_IMAGE_DATA_AS_POINTERS   ((uint16_t) (1 << 1))
#define	EXR_DECODE_SAMPLE_DATA_ONLY   ((uint16_t) (1 << 2))
#define	EXR_DECODE_PIPELINE_INITIALIZER
	Simple macro to initialize an empty decode pipeline. More...

Typedefs
typedef struct _exr_decode_pipeline	exr_decode_pipeline_t

Functions
EXR_EXPORT exr_result_t	exr_decoding_initialize (exr_const_context_t ctxt, int part_index, const exr_chunk_info_t *cinfo, exr_decode_pipeline_t *decode)
EXR_EXPORT exr_result_t	exr_decoding_choose_default_routines (exr_const_context_t ctxt, int part_index, exr_decode_pipeline_t *decode)
EXR_EXPORT exr_result_t	exr_decoding_update (exr_const_context_t ctxt, int part_index, const exr_chunk_info_t *cinfo, exr_decode_pipeline_t *decode)
EXR_EXPORT exr_result_t	exr_decoding_run (exr_const_context_t ctxt, int part_index, exr_decode_pipeline_t *decode)
EXR_EXPORT exr_result_t	exr_decoding_destroy (exr_const_context_t ctxt, exr_decode_pipeline_t *decode)

Macro Definition Documentation

#define EXR_DECODE_NON_IMAGE_DATA_AS_POINTERS   ((uint16_t) (1 << 1))

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.

Definition at line 50 of file openexr_decode.h.

#define EXR_DECODE_PIPELINE_INITIALIZER

Value:

{                                                                          \
        0                                                                      \
    }

Simple macro to initialize an empty decode pipeline.

Definition at line 250 of file openexr_decode.h.

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

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.

Definition at line 28 of file openexr_decode.h.

#define EXR_DECODE_SAMPLE_DATA_ONLY   ((uint16_t) (1 << 2))

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

Definition at line 55 of file openexr_decode.h.

Typedef Documentation

typedef struct _exr_decode_pipeline exr_decode_pipeline_t

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.

Function Documentation

EXR_EXPORT exr_result_t exr_decoding_choose_default_routines	(	exr_const_context_t	ctxt,
		int	part_index,
		exr_decode_pipeline_t *	decode
	)

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

EXR_EXPORT exr_result_t exr_decoding_destroy	(	exr_const_context_t	ctxt,
		exr_decode_pipeline_t *	decode
	)

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.

EXR_EXPORT exr_result_t exr_decoding_initialize	(	exr_const_context_t	ctxt,
		int	part_index,
		const exr_chunk_info_t *	cinfo,
		exr_decode_pipeline_t *	decode
	)

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

EXR_EXPORT exr_result_t exr_decoding_run	(	exr_const_context_t	ctxt,
		int	part_index,
		exr_decode_pipeline_t *	decode
	)

Execute the decoding pipeline.

EXR_EXPORT exr_result_t exr_decoding_update	(	exr_const_context_t	ctxt,
		int	part_index,
		const exr_chunk_info_t *	cinfo,
		exr_decode_pipeline_t *	decode
	)

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.