summaryrefslogtreecommitdiffstats
path: root/src/H5Zmodule.h
diff options
context:
space:
mode:
authorGerd Heber <gheber@hdfgroup.org>2021-09-01 21:09:27 (GMT)
committerGitHub <noreply@github.com>2021-09-01 21:09:27 (GMT)
commitcf25524474a4012a70cc2bdb6eaddc402b5ea136 (patch)
treecf7e30d16a602e5146500158696d429a146cb2c2 /src/H5Zmodule.h
parent01fe2549a36d7635b2cbe6f6a57cbcce29c1335b (diff)
downloadhdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.zip
hdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.tar.gz
hdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.tar.bz2
A batch of life-cycle examples for different modules (#654)
* Create a tag file for permalinks. * Added DOXYGEN_TAG_FILE. * Added Doxygen life-cycle examples for different modules. Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src/H5Zmodule.h')
-rw-r--r--src/H5Zmodule.h109
1 files changed, 66 insertions, 43 deletions
diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h
index 76a2380..9312b72 100644
--- a/src/H5Zmodule.h
+++ b/src/H5Zmodule.h
@@ -29,57 +29,80 @@
#define H5_MY_PKG_ERR H5E_PLINE
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5Z H5Z
+/**\defgroup H5Z H5Z
*
+ * Use the functions in this module to manage HDF5 filters.
*
- * \brief Filter and Compression Interface
+ * User-defined filters are created by registering a filter descriptor of
+ * type #H5Z_class_t with the library.
*
- * \details The functions in this module let you configure filters that process
- * data during I/O operation.
+ * Available filters can be read or examined at runtime.
*
- * 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, SZIP, and a shuffling algorithm) and error
- * checking (Fletcher32 checksum). For further flexibility, the
- * library allows a user application to extend the pipeline through
- * the creation and registration of customized filters.
+ * It is conceivable that filters are stateful and that that state be
+ * updated at runtime.
*
- * The flexibility of the filter pipeline implementation enables the
- * definition of additional filters by a user application. A filter
- * \li is associated with a dataset when the dataset is created,
- * \li can be used only with chunked data (i.e., datasets stored in
- * the #H5D_CHUNKED storage layout), and
- * \li is applied independently to each chunk of the dataset.
+ * Filters are deleted by unregistering.
*
- * The HDF5 library does not support filters for contiguous datasets
- * because of the difficulty of implementing random access for partial
- * I/O. Compact dataset filters are not supported because it would not
- * produce significant results.
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5Z_examples.c filter
+ * \snippet{lineno} H5Z_examples.c create
+ * </td>
+ * <td>
+ * \snippet{lineno} H5Z_examples.c read
+ * </td>
+ * </tr>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5Z_examples.c update
+ * </td>
+ * <td>
+ * \snippet{lineno} H5Z_examples.c delete
+ * </tr>
+ * </table>
*
- * Filter identifiers for the filters distributed with the HDF5
- * Library are as follows:
- * <table>
- * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or
- * deflation, filter</td></tr>
- * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression
- * filter</td></tr>
- * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression
- * filter</td></tr>
- * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset
- * compression filter</td></tr>
- * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm
- * filter</td></tr>
- * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum,
- * or error checking, filter</td></tr>
- * </table>
- * Custom filters that have been registered with the library will have
- * additional unique identifiers.
+ * 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, SZIP, and a
+ * shuffling algorithm) and error checking (Fletcher32 checksum). For further
+ * flexibility, the library allows a user application to extend the pipeline
+ * through the creation and registration of customized filters.
*
- * See \ref_dld_filters for more information on how an HDF5
- * application can apply a filter that is not registered with the HDF5
- * library.
+ * The flexibility of the filter pipeline implementation enables the definition
+ * of additional filters by a user application. A filter
+ * \li is associated with a dataset when the dataset is created,
+ * \li can be used only with chunked data (i.e., datasets stored in the
+ * #H5D_CHUNKED storage layout), and
+ * \li is applied independently to each chunk of the dataset.
+ *
+ * The HDF5 library does not support filters for contiguous datasets because of
+ * the difficulty of implementing random access for partial I/O. Compact dataset
+ * filters are not supported because it would not produce significant results.
+ *
+ * Filter identifiers for the filters distributed with the HDF5
+ * Library are as follows:
+ * <table>
+ * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or
+ * deflation, filter</td></tr>
+ * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression
+ * filter</td></tr>
+ * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression
+ * filter</td></tr>
+ * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset
+ * compression filter</td></tr>
+ * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm
+ * filter</td></tr>
+ * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum,
+ * or error checking, filter</td></tr>
+ * </table>
+ * Custom filters that have been registered with the library will have
+ * additional unique identifiers.
+ *
+ * See \ref_dld_filters for more information on how an HDF5 application can
+ * apply a filter that is not registered with the HDF5 library.
*
* \defgroup H5ZPRE Predefined Filters
* \ingroup H5Z