Collaboration diagram for Fine-grained Initialization, Setup, and Allocation:

Functions
xrif_error_t	xrif_initialize_handle (xrif_t handle)
	Initialize an xrif handle object. More...

xrif_error_t	xrif_set_difference_method (xrif_t handle, int difference_method)
	Set the difference method. More...

xrif_error_t	xrif_set_reorder_method (xrif_t handle, int reorder_method)
	Set the reorder method. More...

xrif_error_t	xrif_set_compress_method (xrif_t handle, int compress_method)
	Set the compress method. More...

xrif_error_t	xrif_set_lz4_acceleration (xrif_t handle, int32_t lz4_accel)
	Set the LZ4 acceleration parameter. More...

size_t	xrif_min_raw_size (xrif_t handle)
	Calculate the minimum size of the raw buffer. More...

size_t	xrif_min_reordered_size (xrif_t handle)
	Calculate the minimum size of the reordered buffer. More...

size_t	xrif_min_compressed_size (xrif_t handle)
	Calculate the minimum size of the compressed buffer. More...

xrif_error_t	xrif_set_raw (xrif_t handle, void *raw, size_t size)
	Set the raw data buffer to a pre-allocated pointer. More...

xrif_error_t	xrif_allocate_raw (xrif_t handle)
	Allocate the raw buffer based on the already set stream dimensions. More...

xrif_error_t	xrif_set_reordered (xrif_t handle, void *reordered, size_t size)
	Set the rordered (working) data buffer to a pre-allocated pointer. More...

xrif_error_t	xrif_allocate_reordered (xrif_t handle)
	Allocate the reordered buffer based on the already set stream dimensions. More...

xrif_error_t	xrif_set_compressed (xrif_t handle, void *reordered, size_t size)
	Set the compressed data buffer to a pre-allocated pointer. More...

xrif_error_t	xrif_allocate_compressed (xrif_t handle)
	Allocate the compressed buffer based on the already set stream dimensions. More...

Function Documentation

◆ xrif_allocate_compressed()

xrif_error_t xrif_allocate_compressed ( xrif_t handle )

Allocate the compressed buffer based on the already set stream dimensions.

Must only be called after xrif_set_size and xrif_configure have been called.

If the compressed_buffer is currently allocated and owned, it is first free()-ed.

Returns: XRIF_ERROR_NULLPTR if handle is a null pointer; XRIF_ERROR_NOT_SETUP if the width, heigh, depth, frames, and data_size parameters have not been set; XRIF_ERROR_MALLOC if malloc returns a null pointer. In this case own_raw will be set to 0.; XRIF_NOERROR on success

Parameters

[in,out] handle [in/out] the xrif handle

Definition at line 760 of file xrif.c.

References xrif_handle::compressed_buffer, xrif_handle::compressed_buffer_size, xrif_handle::data_size, xrif_handle::depth, xrif_handle::frames, xrif_handle::height, xrif_handle::own_compressed, xrif_handle::width, XRIF_ERROR_INVALID_SIZE, XRIF_ERROR_MALLOC, XRIF_ERROR_NOT_SETUP, XRIF_ERROR_NULLPTR, XRIF_ERROR_PRINT, xrif_min_compressed_size(), and XRIF_NOERROR.

Referenced by xrif_allocate().

◆ xrif_allocate_raw()

xrif_error_t xrif_allocate_raw ( xrif_t handle )

Allocate the raw buffer based on the already set stream dimensions.

Must only be called after xrif_set_size and xrif_configure have been called.

If xrif_handle::raw_buffer is currently allocated and owned, it is first free()-ed.

The size will be set to the maximum of the pre-setup data size and (if xrif_handle::compress_on_raw == true) the LZ4_compressBound result. LZ4 typically (in all tested cases) requests a few hundred more bytes for compression.

Returns: XRIF_ERROR_NULLPTR if handle is a null pointer; XRIF_ERROR_NOT_SETUP if the width, heigh, depth, frames, and data_size parameters have not been set; XRIF_ERROR_MALLOC if malloc returns a null pointer. In this case own_raw will be set to 0.; XRIF_NOERROR on success

See also: xrif_set_raw

Parameters

[in,out] handle [in/out] the xrif object to modify

Definition at line 584 of file xrif.c.

References xrif_handle::data_size, xrif_handle::depth, xrif_handle::frames, xrif_handle::height, xrif_handle::own_raw, xrif_handle::raw_buffer, xrif_handle::raw_buffer_size, xrif_handle::width, XRIF_ERROR_INVALID_SIZE, XRIF_ERROR_MALLOC, XRIF_ERROR_NOT_SETUP, XRIF_ERROR_NULLPTR, XRIF_ERROR_PRINT, xrif_min_raw_size(), and XRIF_NOERROR.

Referenced by xrif_allocate().

◆ xrif_allocate_reordered()

xrif_error_t xrif_allocate_reordered ( xrif_t handle )

Allocate the reordered buffer based on the already set stream dimensions.

Must only be called after xrif_set_size and xrif_configure have been called.

If the reordered_buffer is currently allocated and owned, it is first free()-ed.

Returns: XRIF_ERROR_NULLPTR if handle is a null pointer; XRIF_ERROR_NOT_SETUP if the width, heigh, depth, frames, and data_size parameters have not been set; XRIF_ERROR_MALLOC if malloc returns a null pointer. In this case own_raw will be set to 0.; XRIF_NOERROR on success

Parameters

[in,out] handle [in/out] the xrif object to modify

Definition at line 673 of file xrif.c.

References xrif_handle::data_size, xrif_handle::depth, xrif_handle::frames, xrif_handle::height, xrif_handle::own_reordered, xrif_handle::reordered_buffer, xrif_handle::reordered_buffer_size, xrif_handle::width, XRIF_ERROR_INVALID_SIZE, XRIF_ERROR_MALLOC, XRIF_ERROR_NOT_SETUP, XRIF_ERROR_NULLPTR, XRIF_ERROR_PRINT, xrif_min_reordered_size(), and XRIF_NOERROR.

Referenced by xrif_allocate().

◆ xrif_initialize_handle()

xrif_error_t xrif_initialize_handle ( xrif_t handle )

Initialize an xrif handle object.

Sets all values to defaults, and ensures that calls to allocate functions or xrif_reset_handle will safely succeed.

In general this should not be called independently, rather you should use xrif_new. If you do, this function must only be called on an xrif handle which does not already have memory alocated – otherwise memory leaks will occur!

Returns: XRIF_ERROR_NULLPTR if handle is NULL.; XRIF_NOERROR on success

Test:

Verify handle initialization. [test doc]

Verify xrif_initialize_handle returns error on NULL pointer. [test doc]

Parameters

[out] handle [out] the xrif handle to initialize

Definition at line 294 of file xrif.c.

References xrif_handle::compressed_size, xrif_handle::data_size, xrif_handle::depth, xrif_handle::difference_method, xrif_handle::frames, xrif_handle::height, xrif_handle::raw_size, xrif_handle::type_code, xrif_handle::width, XRIF_ERROR_NULLPTR, and XRIF_ERROR_PRINT.

Referenced by START_TEST(), xrif_new(), and xrif_reset().

◆ xrif_min_compressed_size()

size_t xrif_min_compressed_size ( xrif_t handle )

Calculate the minimum size of the compressed buffer.

Result is based on current connfiguration of the handle.

Returns: the minimum size of the compressed buffer for a valid configuration.; 0 for an invalid configuration.

Parameters

[in] handle [in] the xrif handle

Definition at line 521 of file xrif.c.

References xrif_handle::compress_method.

Referenced by xrif_allocate_compressed(), xrif_min_raw_size(), and xrif_set_compressed().

◆ xrif_min_raw_size()

size_t xrif_min_raw_size ( xrif_t handle )

Calculate the minimum size of the raw buffer.

Result is based on current connfiguration of the handle.

Returns: the minimum size of the raw buffer for a valid configuration.; 0 for an invalid configuration.

Parameters

[in] handle [in] the xrif handle

Definition at line 462 of file xrif.c.

References xrif_handle::compress_on_raw, xrif_handle::data_size, xrif_handle::depth, xrif_handle::frames, xrif_handle::height, xrif_handle::width, and xrif_min_compressed_size().

Referenced by xrif_allocate_raw(), and xrif_set_raw().

◆ xrif_min_reordered_size()

size_t xrif_min_reordered_size ( xrif_t handle )

Calculate the minimum size of the reordered buffer.

Result is based on current connfiguration of the handle.

Returns: the minimum size of the reordered buffer for a valid configuration.; 0 for an invalid configuration.

Parameters

[in] handle [in] the xrif handle

Definition at line 485 of file xrif.c.

References xrif_handle::reorder_method.

Referenced by xrif_allocate_reordered(), xrif_compress_lz4(), xrif_decompress_lz4(), and xrif_set_reordered().

◆ xrif_set_compress_method()

xrif_error_t xrif_set_compress_method	(	xrif_t	handle,
		int	compress_method
	)

Set the compress method.

Sets the compress_method member of handle. Valid methods are XRIF_COMPRESS_NONE, XRIF_COMPRESS_DEFAULT, and XRIF_COMPRESS_LZ4. XRIF_COMPRESS_DEFAULT is equivalent to XRIF_COMPRESS_LZ4.

Returns: XRIF_ERROR_NULLPTR if handle is a NULL pointer; XRIF_ERROR_BADARG if compress_method is not a valid compress method. Will set method to XRIF_COMPRESS_DEFAULT.; XRIF_NOERROR on success.

Parameters

[in,out]	handle	[in/out] the xrif handle to be configured
[in]	compress_method	[in] the new compress method

Definition at line 408 of file xrif.c.

References XRIF_ERROR_NULLPTR, and XRIF_ERROR_PRINT.

Referenced by xrif_configure().

◆ xrif_set_compressed()

xrif_error_t xrif_set_compressed	(	xrif_t	handle,
		void *	reordered,
		size_t	size
	)

Set the compressed data buffer to a pre-allocated pointer.

Must only be called after xrif_set_size and xrif_configure have been called.

You are responsible for allocating the buffer to be at least as large as xrif_min_compressed_size(xrif_t).

This pointer will not be free()-ed on a call to xrif_reset_handle.

Returns: XRIF_ERROR_NULLPTR if handle is a NULL pointer; XRIF_ERROR_INVALID_SIZE if bad values are passed for raw or size; XRIF_ERROR_INSUFFICIENT_SIZE if the size of the buffer is too small for the configured parameters; XRIF_NOERROR on success

Todo:: need to have a min size calculation function exposed

Parameters

[in,out]	handle	[in/out] the xrif object to modify
[in]	reordered	[in] pointer to a pre-allocated block
[in]	size	[in] the size of the pre-allocated block

Definition at line 715 of file xrif.c.

References xrif_handle::compressed_buffer, xrif_handle::compressed_buffer_size, xrif_handle::own_compressed, XRIF_ERROR_INSUFFICIENT_SIZE, XRIF_ERROR_INVALID_SIZE, XRIF_ERROR_NULLPTR, XRIF_ERROR_PRINT, xrif_min_compressed_size(), and XRIF_NOERROR.

◆ xrif_set_difference_method()

xrif_error_t xrif_set_difference_method	(	xrif_t	handle,
		int	difference_method
	)

Set the difference method.

Sets the difference_method member of handle.

Returns: XRIF_ERROR_NULLPTR if handle is a NULL pointer; XRIF_ERROR_BADARG if difference_method is not a valid difference method. Will set method to XRIF_DIFFERENCE_DEFAULT.; XRIF_NOERROR on success.

Parameters

[in,out]	handle	[in/out] the xrif handle to be configured
[in]	difference_method	[in] the new reorder method

Definition at line 355 of file xrif.c.

References XRIF_ERROR_NULLPTR, and XRIF_ERROR_PRINT.

Referenced by xrif_configure().

◆ xrif_set_lz4_acceleration()

xrif_error_t xrif_set_lz4_acceleration	(	xrif_t	handle,
		int32_t	lz4_accel
	)

Set the LZ4 acceleration parameter.

The LZ4 acceleration paraameter is a number greater than or equal to 1. Larger values speed up the compression process, but with less size reduction. The default and minimum value is 1 (XRIF_LZ4_ACCEL_MIN).
The maximum value is 65537 (XRIF_LZ4_ACCEL_MAX). The LZ4 docs claim a +-3% improvement in speed for each incrment.

Returns: XRIF_ERROR_NULLPTR if handle is a NULL pointer; XRIF_ERROR_BADARG if lz4_acceleration is out of range. Will set value to correspondling min or max limit.; XRIF_NOERROR on success.

Parameters

[in,out]	handle	[in/out] the xrif handle to be configured
[in]	lz4_accel	[in] LZ4 acceleration parameter

Definition at line 432 of file xrif.c.

References XRIF_ERROR_NULLPTR, and XRIF_ERROR_PRINT.

◆ xrif_set_raw()

xrif_error_t xrif_set_raw	(	xrif_t	handle,
		void *	raw,
		size_t	size
	)

Set the raw data buffer to a pre-allocated pointer.

Must only be called after xrif_set_size and xrif_configure have been called. You are responsible for allocating the buffer to be at least as large as the value returned by xrif_min_raw_size. This will return an error if size is too small for the currently set values.

This pointer will not be free()-ed on a call to xrif_reset_handle.

Returns: XRIF_ERROR_NULLPTR if handle is a NULL pointer; XRIF_ERROR_INVALID_SIZE if bad values are passed for raw or size; XRIF_ERROR_INSUFFICIENT_SIZE if the size of the buffer is too small for the configured parameters; XRIF_NOERROR on success

See also: xrif_allocate_raw

Parameters

[in,out]	handle	[in/out] the xrif handle
[in]	raw	[in] the pointer to a pre-allocated block
[in]	size	[in] the size of the pre-allocated block

Definition at line 538 of file xrif.c.

References xrif_handle::own_raw, xrif_handle::raw_buffer, xrif_handle::raw_buffer_size, XRIF_ERROR_INSUFFICIENT_SIZE, XRIF_ERROR_INVALID_SIZE, XRIF_ERROR_NULLPTR, XRIF_ERROR_PRINT, xrif_min_raw_size(), and XRIF_NOERROR.

◆ xrif_set_reorder_method()

xrif_error_t xrif_set_reorder_method	(	xrif_t	handle,
		int	reorder_method
	)

Set the reorder method.

Sets the reorder_method member of handle.

Returns: XRIF_ERROR_NULLPTR if handle is a NULL pointer; XRIF_ERROR_BADARG if reorder_method is not a valid reorder method. Will set method to XRIF_REORDER_DEFAULT.; XRIF_NOERROR on success.

Parameters

[in,out]	handle	[in/out] the xrif handle to be configured
[in]	reorder_method	[in] the new reorder method

Definition at line 382 of file xrif.c.

References XRIF_ERROR_NULLPTR, and XRIF_ERROR_PRINT.

Referenced by xrif_configure().

◆ xrif_set_reordered()

xrif_error_t xrif_set_reordered	(	xrif_t	handle,
		void *	reordered,
		size_t	size
	)

Set the rordered (working) data buffer to a pre-allocated pointer.

Must only be called after xrif_set_size and xrif_configure have been called.

You are responsible for allocating the buffer to be at least the value returned by xrif_min_reordered_size(xrif_t).

This pointer will not be free()-ed on a call to xrif_reset_handle.

Returns: 0 on success; < 0 on error, with the appropriate XRIF_ERROR_* code.; XRIF_ERROR_NULLPTR if handle is a NULL pointer; XRIF_ERROR_INVALID_SIZE if bad values are passed for raw or size; XRIF_ERROR_INSUFFICIENT_SIZE if the size of the buffer is too small for the configured parameters; XRIF_NOERROR on success

Todo:: need to have a min size calculation function exposed

Parameters

[in,out]	handle	[in/out] the xrif object to modify
[in]	reordered	[in] pointer to a pre-allocated block
[in]	size	[in] the size of the pre-allocated block

Definition at line 627 of file xrif.c.

References xrif_handle::own_reordered, xrif_handle::reordered_buffer, xrif_handle::reordered_buffer_size, XRIF_ERROR_INSUFFICIENT_SIZE, XRIF_ERROR_INVALID_SIZE, XRIF_ERROR_NULLPTR, XRIF_ERROR_PRINT, xrif_min_reordered_size(), and XRIF_NOERROR.

Functions

Function Documentation

◆ xrif_allocate_compressed()

◆ xrif_allocate_raw()

◆ xrif_allocate_reordered()

◆ xrif_initialize_handle()

◆ xrif_min_compressed_size()

◆ xrif_min_raw_size()

◆ xrif_min_reordered_size()

◆ xrif_set_compress_method()

◆ xrif_set_compressed()

◆ xrif_set_difference_method()

◆ xrif_set_lz4_acceleration()

◆ xrif_set_raw()

◆ xrif_set_reorder_method()

◆ xrif_set_reordered()