From ae1c0b48d966201e06ceb2c4863d46b629b48b9b Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Tue, 6 May 2003 17:20:37 -0500 Subject: [svn-r6815] Purpose: Update H5Zregister to describe new approach to filter management. Description: H5Zregister -- heavy revisions to reflect new filter-handling approach. Added H5Z_class_t struct, H5Z_can_apply_func_t callback function, and H5Z_set_local_func_t callback function, and rewrote much of the rest. Platforms tested: IE 5, Safari --- doc/html/RM_H5Z.html | 209 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 159 insertions(+), 50 deletions(-) diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index 5e377b2..aad57f4 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -137,44 +137,145 @@ facilitate moving easily between them.
Name: H5Zregister
Signature: -
herr_t H5Zregister(H5Z_filter_t filter, - const char *comment, - H5Z_func_t function +
herr_t H5Zregister(const H5Z_class_t filter_class) )
Purpose: -
Registers new filter. +
Registers new filter.
Description:
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. -

- comment is used for debugging and may be - the null pointer. -

- function is a user-defined function - which performs the action of the filter. -

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

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: - -

+ HDF5 library. +

+ Making a new filter available to an application is a two-step + process. The first step is to define + the three filter callback filter functions described below: + can_applyr_func, set_local_func, and + filter_func. + This step can be skipped only when the filter is predefined, 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. +

+ H5Zregister accepts a single parameter, + the filter_class data structure, + which is defined as follows: + 

+       typedef struct H5Z_class_t {
+           H5Z_filter_t filter_id;
+           const char  *comment;
+           H5Z_can_apply_func_t can_apply_func;
+           H5Z_set_local_func_t set_local_func;
+           H5Z_func_t filter_func;            
+       } H5Z_class_t;
+
+ +

+ filter_id is the identifier for the new filter. +

+ comment is used for debugging and may be + the null pointer. +

+ can_apply_func, described in detail below, + is a user-defined callback function which determines whether + the combination of the dataset creation property list setting, + the datatype, and the dataspace represent a valid combination + to apply this filter to. +

+ set_local_func, described in detail below, + is a user-defined callback function which sets any parameters that + are specific to this dataset, based on the combination of the + dataset creation property list values, the datatype, and the + dataspace. +

+ filter_func, described in detail below, + is a user-defined callback function which performs the action + of the filter. +

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

+ The callback functions +
+ Before H5Zregister can link a filter into an + application, three callback functions must be defined + as described in the HDF5 Library header file H5Zpublic.h. + +

+ The can apply callback function is defined as follows:
+

+ typedef herr_t (*H5Z_can_apply_func_t) + (hid_t dcpl_id, + hid_t type_id, + hid_t space_id) + +

+ Before a dataset is created, the can apply callbacks for + any filters used in the dataset creation property list are called + with the dataset's dataset creation property list, dcpl_id, + the dataset's datatype, type_id, and + a dataspace describing a chunk, space_id, + (for chunked dataset storage). +

+ This callback must determine whether the combination of the + dataset creation property list settings, the datatype, and the + dataspace represent a valid combination to which to apply this filter. + For example, an invalid combination may involve + the filter not operating correctly on certain datatypes, + on certain datatype sizes, or on certain sizes of the chunk dataspace. +

+ This callback can be the NULL pointer, in which case + the library will assume that the filter can be applied to a dataset with + any combination of dataset creation property list values, datatypes, + and dataspaces. +

+ The can apply callback function must return + a positive value for a valid combination, + zero for an invalid combination, and + a negative value for an error. + +

+ The set local callback function is defined as follows:
+

+ typedef herr_t (*H5Z_set_local_func_t) + (hid_t dcpl_id, + hid_t type_id, + hid_t space_id) + +

+ After the can apply callbacks are checked for a new dataset, + the set local callback functions for any filters used in the + dataset creation property list are called. + These callbacks receive + dcpl_id, the dataset's private copy of the dataset + creation property list passed in to H5Dcreate + (i.e. not the actual property list passed in to H5Dcreate); + type_id, the datatype identifier passed in to + H5Dcreate, + which is not copied and should not be modified; and + space_id, a dataspace describing the chunk + (for chunked dataset storage), which should also not be modified. +

+ The set local callback must set any parameters that are + specific to this dataset, based on the combination of the + dataset creation property list values, the datatype, and the dataspace. + For example, some filters perform different actions based on + different datatypes, datatype sizes, numbers of dimensions, + or dataspace sizes. +

+ The set local callback may be the NULL pointer, + in which case, the library will assume that there are + no dataset-specific settings for this filter. +

+ The set local callback function must return + a non-negative value on success and + a negative value for an error. + +

+ The filter operation callback function, + defining the filter's operation on the data, is defined as follows: +

typedef size_t (*H5Z_func_t) (unsigned int flags, size_t cd_nelmts, @@ -182,34 +283,42 @@ facilitate moving easily between them. size_t nbytes, size_t *buf_size, void **buf) - + -

The parameters flags, cd_nelmts, +

+ The parameters flags, cd_nelmts, and cd_values are the same as for the function - The additional flag H5Z_FLAG_REVERSE is set when + H5Pset_filter. + The one exception is that an 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 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, +

+ The filter should perform the transformation in place if + possible. 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(). - +

+ If successful, the filter operation callback function + returns the number of valid bytes of data contained in *buf. + In the case of failure, the return value is 0 (zero) + and all pointer arguments are left unchanged. +

Note: +
The H5Zregister interface is substantially revised + from the HDF5 Release 1.4.x series. + The H5Z_class_t struct and + the set local and can apply callback functions + first appeared in HDF5 Release 1.6.
Parameters:
-
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: Filter function. +
const H5Z_class_t filter_class +
IN: Struct containing filter-definition information.
Returns:
Returns a non-negative value if successful; @@ -334,7 +443,7 @@ And in this document, the Describes HDF5 Release 1.5, Unreleased Development Branch -Last modified: 8 April 2003 +Last modified: 6 May 2003 -- cgit v0.12