H5Zregister(H5Z_filter_t filter,
- const char *comment,
- H5Z_func_t function
+ H5Zregister(const H5Z_class_t filter_class)
)
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. + 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. -
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:
+
+ 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:
+
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:
+
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: +
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.
+
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.
method
- comment
- function
- filter_class
+