From 619ee863edbe4f35e9415f62475f23f02030d7de Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Wed, 2 Apr 2003 16:03:57 -0500 Subject: [svn-r6569] Purpose: New filter functionality Rename section to reflect filters rather than strictly compression Description: "Compression Interface" --> "Filter and Compression Interface" Renamed section as "Filter and Compression Interface". Extended introductory paragraphs to BRIEFLY describe filter pipeline. Edit H5Zregister to speak from point of view of filters rather than compression only. Add H5Zunregister. Add H5Zfilter_avail. Platforms tested: Safari, IE 5 --- doc/html/RM_H5Z.html | 172 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 138 insertions(+), 34 deletions(-) diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index e53146c..333d394 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -44,32 +44,52 @@ And in this document, the
-

H5Z: Compression Interface

+

H5Z: Filter and Compression Interface

-

Compression API Functions

+

Filter and Compression API Functions

-This function enable the user to configure a new compression -method for the local environment. +These functions enable the user to configure new filters +for the local environment. - +
       +       +

-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. +HDF5 supports a filter pipeline that provides the capability for standard +and customized raw data processing during I/O operations. +HDF5 is distributed with a small set of standard filters such as +compression (gzip and a shuffling algorithm) and +error checking (Fletcher32 checksum). +For further flexibility, the library includes tools enabling a +user application to extend the pipeline through the +creation and registration of customized filters. +

+As mentioned above, one set of filters distributed with HDF5 provides +built-in methods for raw data compression. +The flexibility of the filter pipeline implementation enables the +definition of additional compression methods by a user application. +A compression method
+ —  + is associated with a dataset when the dataset is created,
+ —  + can be used only with chunked data (ie., datasets stored in the + H5D_CHUNKED storage layout), and
+ —  + is applied independently to each chunk of the dataset.

The HDF5 library does not support compression for contiguous datasets because of the difficulty of implementing random access for partial I/O. @@ -84,28 +104,42 @@ data compression.

Name: H5Zregister
Signature: -
herr_t H5Zregister(H5Z_method_t method, - const char *name, +
herr_t H5Zregister(H5Z_filter_t filter, + const char *comment, H5Z_func_t function )
Purpose: -
Registers new compression / uncompression function. +
Registers new filter.
Description: -
H5Zregister registers a new compression / uncompression - function for the compression method specified by - the method number, method. +
H5Zregister registers a new filter with the + HDF5 library. +

+ Making a new filter available to an application is a two-step + process. The first step is to define + the new filter function as described below. + This step can be skipped only when the filter is predifined, as is + the case with the Fletcher32 checksum and shuffle filters that + are distributed with the HDF5 Library. + This call to H5Zregister, + registering the filter with the + library, is the second step. +

+ The new filter is specified by the filter identifier + filter.

- name is used for debugging and may be the null pointer. + comment 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. + function is a user-defined function + which performs the action of the filter.

- The statistics associated with a method number are not reset + The statistics associated with a filter 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: +

New filters. Before a filter can be + linked into an application with H5Zregister, + the filter must be defined as described in the HDF5 Library + header file H5Zpublic.h:

typedef size_t (*H5Z_func_t) @@ -118,12 +152,12 @@ data compression.

The parameters flags, cd_nelmts, - and cd_values are the same as for the - H5Pset_filter() function. + and cd_values are the same as for the function + H5Pset_filter. 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, + which has a 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 @@ -136,13 +170,14 @@ data compression.

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_filter_t method +
IN: Filter identifier. +
const char *comment +
IN: String associated with the filter; + used for debugging purposes only. + May be the null pointer.
H5Z_func_t function -
IN: Compression / uncompression method. +
IN: Filter function.
Returns:
Returns a non-negative value if successful; @@ -150,6 +185,75 @@ data compression.
+ + +
+
+
Name: H5Zunregister +
Signature: +
herr_t H5Zunregister(H5Z_filter_t filter) +
Purpose: +
Unregisters a filter. +
Description: +
H5Zunregister unregisters the filter + specified in filter.   +

+ After a call to H5Zunregister, the filter + specified in filter will no longer be + available to the application. +

Parameters: +
+
H5Z_filter_t filter +
IN: Identifier of the filter to be unregistered. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. + +
+ +
+
+
Name: H5Zfilter_avail +
Signature: +
herr_t H5Zfilter_avail(H5Z_filter_t filter) +
Purpose: +
Determines whether a filter is available. +
Description: +
H5Zfilter_avail determines whether the filter + specified in filter is available to the application. +
Parameters: +
+
H5Z_filter_t filter +
IN: Filter identifier. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. + +
+ + + + + + + +
@@ -192,7 +296,7 @@ And in this document, the Describes HDF5 Release 1.5, Unreleased Development Branch -Last modified: 11 February 2003 +Last modified: 2 April 2003 -- cgit v0.12