Part related definitions.

Collaboration diagram for Part related definitions.:

Modules
	Functions to get and set metadata for a particular part.

Functions
EXR_EXPORT exr_result_t	exr_get_count (exr_const_context_t ctxt, int *count)
	Query how many parts are in the file. More...
EXR_EXPORT exr_result_t	exr_get_name (exr_const_context_t ctxt, int part_index, const char **out)
	Query the part name for the specified part. More...
EXR_EXPORT exr_result_t	exr_get_storage (exr_const_context_t ctxt, int part_index, exr_storage_t *out)
	Query the storage type for the specified part. More...
EXR_EXPORT exr_result_t	exr_add_part (exr_context_t ctxt, const char *partname, exr_storage_t type, int *new_index)
	Define a new part in the file. More...
EXR_EXPORT exr_result_t	exr_get_tile_levels (exr_const_context_t ctxt, int part_index, int32_t *levelsx, int32_t *levelsy)
	Query how many levels are in the specified part. More...
EXR_EXPORT exr_result_t	exr_get_tile_sizes (exr_const_context_t ctxt, int part_index, int levelx, int levely, int32_t *tilew, int32_t *tileh)
	Query the tile size for a particular level in the specified part. More...
EXR_EXPORT exr_result_t	exr_get_level_sizes (exr_const_context_t ctxt, int part_index, int levelx, int levely, int32_t *levw, int32_t *levh)
	Query the data sizes for a particular level in the specified part. More...
EXR_EXPORT exr_result_t	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)
EXR_EXPORT exr_result_t	exr_get_chunk_unpacked_size (exr_const_context_t ctxt, int part_index, uint64_t *out)
EXR_EXPORT exr_result_t	exr_get_zip_compression_level (exr_const_context_t ctxt, int part_index, int *level)
	Retrieve the zip compression level used for the specified part. More...
EXR_EXPORT exr_result_t	exr_set_zip_compression_level (exr_context_t ctxt, int part_index, int level)
	Set the zip compression method used for the specified part. More...
EXR_EXPORT exr_result_t	exr_get_dwa_compression_level (exr_const_context_t ctxt, int part_index, float *level)
	Retrieve the dwa compression level used for the specified part. More...
EXR_EXPORT exr_result_t	exr_set_dwa_compression_level (exr_context_t ctxt, int part_index, float level)
	Set the dwa compression method used for the specified part. More...

Detailed Description

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 clear set of eyes for stereo, or just a simple list of AOVs within a single OpenEXR file. Prior, it was managed by name convention, but with a multi-part file, they are clearly separate types, and can have separate behavior.

This is a set of functions to query, or set up when writing, that set of parts within a file. This remains backward compatible to OpenEXR files from before this change, in that a file with a single part is a subset of a multi-part file. As a special case, creating a file with a single part will write out as if it is a file which is not multi-part aware, so as to be compatible with those old libraries.

Function Documentation

EXR_EXPORT exr_result_t exr_add_part	(	exr_context_t	ctxt,
		const char *	partname,
		exr_storage_t	type,
		int *	new_index
	)

Define a new part in the file.

EXR_EXPORT exr_result_t exr_get_chunk_count	(	exr_const_context_t	ctxt,
		int	part_index,
		int32_t *	out
	)

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.

EXR_EXPORT exr_result_t exr_get_chunk_unpacked_size	(	exr_const_context_t	ctxt,
		int	part_index,
		uint64_t *	out
	)

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.

EXR_EXPORT exr_result_t exr_get_count	(	exr_const_context_t	ctxt,
		int *	count
	)

Query how many parts are in the file.

EXR_EXPORT exr_result_t exr_get_dwa_compression_level	(	exr_const_context_t	ctxt,
		int	part_index,
		float *	level
	)

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.

EXR_EXPORT exr_result_t exr_get_level_sizes	(	exr_const_context_t	ctxt,
		int	part_index,
		int	levelx,
		int	levely,
		int32_t *	levw,
		int32_t *	levh
	)

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 levw or levh arguments, which enables testing if this part is a tiled part, or if you don't need both for some reason.

EXR_EXPORT exr_result_t exr_get_name	(	exr_const_context_t	ctxt,
		int	part_index,
		const char **	out
	)

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.

EXR_EXPORT exr_result_t exr_get_scanlines_per_chunk	(	exr_const_context_t	ctxt,
		int	part_index,
		int32_t *	out
	)

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.

EXR_EXPORT exr_result_t exr_get_storage	(	exr_const_context_t	ctxt,
		int	part_index,
		exr_storage_t *	out
	)

Query the storage type for the specified part.

EXR_EXPORT exr_result_t exr_get_tile_levels	(	exr_const_context_t	ctxt,
		int	part_index,
		int32_t *	levelsx,
		int32_t *	levelsy
	)

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 levelsx or 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)

EXR_EXPORT exr_result_t exr_get_tile_sizes	(	exr_const_context_t	ctxt,
		int	part_index,
		int	levelx,
		int	levely,
		int32_t *	tilew,
		int32_t *	tileh
	)

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 tilew or 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)

EXR_EXPORT exr_result_t exr_get_zip_compression_level	(	exr_const_context_t	ctxt,
		int	part_index,
		int *	level
	)

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.

EXR_EXPORT exr_result_t exr_set_dwa_compression_level	(	exr_context_t	ctxt,
		int	part_index,
		float	level
	)

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.

EXR_EXPORT exr_result_t exr_set_zip_compression_level	(	exr_context_t	ctxt,
		int	part_index,
		int	level
	)

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.