H5Z: Compression Interface

Compression API Functions

HDF5 supports compression of raw data by compression methods built into the library or defined by an application. A compression method is associated with a dataset when the dataset is created and is applied independently to each storage chunk of the dataset. The dataset must use the H5D_CHUNKED storage layout.

The HDF5 library does not support compression for contiguous datasets because of the difficulty of implementing random access for partial I/O. Compact dataset compression is not supported because it would not produce significant results.

See The Dataset Interface (H5D) in the HDF5 User's Guide for further information regarding data compression.

Name: H5Zregister

Signature:

herr_t H5Zregister(H5Z_method_t method, const char *name, H5Z_func_t function )

Purpose:

Registers new compression / uncompression function.

Description:

H5Zregister registers a new compression / uncompression function for the compression method specified by the method number, method.

name is used for debugging and may be the null pointer.

function is a user-defined function providing both compression and uncompression; it may be the null pointer.

The statistics associated with a method number are not reset by this function; they accumulate over the life of the library.

New filters are defined in two phases. Before a filter can be linked into the application with H5Zregister, H5Z_func_t must first be defined as follows:

typedef size_t (*H5Z_func_t) (unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, void **buf)

The parameters flags, cd_nelmts, and cd_values are the same as for the H5Pset_filter() function. The additional flag H5Z_FLAG_REVERSE is set when the filter is called as part of the input pipeline. The parameter *buf points to the input buffer which has a total size of *buf_size bytes, nbytes of which are valid data.

The filter should perform the transformation in place if possible and return the number of valid bytes or zero for failure. If the transformation cannot be done in place, then the filter should allocate a new buffer with malloc() and assign it to *buf, assigning the allocated size of that buffer to *buf_size. The old buffer should be freed by calling free().

Parameters:

H5Z_method_t method

IN: Number specifying compression method.

const char *name

IN: Name associated with the method number. Used for debugging purposes only.

H5Z_func_t function

IN: Compression / uncompression method.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.