April, 2004

1. Overview

The HDF libraries are required to include SZIP compression as a standard filter. The SZIP library has some restrictions on its use for commercial purposes. Specifically, the decoder is free for all to use, but the encoder may be used only for non-commercial purposes.

The SZIP library has been modified so that it can be compiled in two versions:

• the full library, and 
• the library with the encoder disabled/removed. 

typedef struct H5Z_class_t {

    H5Z_filter_t id;		/* Filter ID number			     */

    const char	*name;		/* Comment for debugging		     */

    H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */

    H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */

    H5Z_func_t filter;		/* The actual filter function		     */

} H5Z_class_t;

typedef struct H5Z_class_t {

    unsigned version;           /* Version # of structure                    */

    H5Z_filter_t id;		/* Filter ID number			     */

    unsigned encoder_present;	/* Flag to indicate the filter has an encoder */

    unsigned decoder_present;	/* Flag to indicate the filter has a decoder */

    const char	*name;		/* Comment for debugging		     */

    H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */

    H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */

    H5Z_func_t filter;		/* The actual filter function		     */

} H5Z_class_t;

If the filter fails [...] during an H5Dwrite operation then the filter is just excluded from the pipeline for the chunk for which it failed...This is commonly used for compression filters: if the filter result would be larger than the input, then the compression filter returns failure and the uncompressed data is stored in the file.

1. Fail the write, or
2. write without compression

Name:  H5Zget_filter_info

Signature:

herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags)

Purpose:

Determines whether a filter is available, and if so, what features are enabled.

Description:

H5Zget_filter_info determines whether the filter specified in filter is available to the application. If so, the features are returned in a bit field.  The feature flags are:   

H5Z_FILTER_CONFIG_ENCODE_ENABLED     - encoding is enabled

H5Z_FILTER_CONFIG_DECODE_ENABLED     - decoding is enabled

Parameters:

H5Z_filter_t filter

IN: Filter identifier.

unsigned int * filter_config_flag  

         OUT: Bit mask of filter features.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value. A negative value will be returned if a filter that is not registered with the library is queried.

herr_t H5Pget_filter_by_id( hid_t plist_id, H5Z_filter_t filter, unsigned int *flags, size_t *cd_nelmts, unsigned intcd_values[], size_t namelen, char name[], unsigned int *filter_config )

unsigned int fileter_config

OUT: Bit vector specifying certain general properties of the filter.

H5Z_FILTER_CONFIG_ENCODE_ENABLED     - encoding is enabled
H5Z_FILTER_CONFIG_DECODE_ENABLED     - decoding is enabled

      struct
        {
	    int32 bits_per_pixel;
            int32 compression_mode;
            int32 options_mask;
            int32 pixels;
            int32 pixels_per_block;
            int32 pixels_per_scanline;
            int32 config_flags
         }
       szip;  /* for szip encoding  */

/* values for config_flags */

CSZIP_ENCODER_ENABLED   1
CSZIP_DECODER_ENABLED   2

HCcomp_available( comp_code_t )  

• "Extension" -- adds to existing enumeration or list
• "Change"    -- modifies existing API or data structure
• "Refinement" -- new or different behavior, does not impact existing code