diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index 5548540c533..7aab29eb553 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -67,7 +67,7 @@ * H5Dread (dset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, rdata[0]); * \endcode * - * The command-line utility h5dump, for example, will read and display the data as shown: + * The command-line utility \ref sec_cltools_h5dump, for example, will read and display the data as shown: * \code * HDF5 "h5ex_d_bzip2.h5" { * GROUP "/" { @@ -101,7 +101,7 @@ * } * \endcode * - * If the filter can not be loaded then h5dump will show the following: + * If the filter can not be loaded then \ref sec_cltools_h5dump will show the following: * \code * ... * } @@ -162,7 +162,7 @@ * \endcode * * To avoid the problem make sure to close all objects to which the filter is applied and flush them using - * the H5Fflush call before unregistering the filter. + * the #H5Fflush call before unregistering the filter. * * \subsection subsec_filter_plugins_prog Programming Model for HDF5 Filter Plugins * This section describes how to create an HDF5 filter, an HDF5 filter plugin, and how to install the HDF5 @@ -179,50 +179,52 @@ * buffer if necessary, and appends the checksum to the end of the buffer. The input half calculates the * checksum on the first part of the buffer and compares it to the checksum already stored at the end of the * buffer. If the two differ then zero (failure) is returned, otherwise the buffer size is reduced to exclude - * the checksum. /code size_t md5_filter(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], - * size_t nbytes, size_t *buf_size, void **buf) - * { - * \c \#ifdef HAVE_MD5 - * unsigned char cksum[16]; - * - * if (flags & H5Z_REVERSE) { - * // Input - * assert(nbytes >= 16); - * md5(nbytes-16, *buf, cksum); - * // Compare - * if (memcmp(cksum, (char*)(*buf)+ nbytes- 16, 16)) { - * return 0; // fail - * } - * // Strip off checksum - * return nbytes - 16; - * } - * else { - * // Output - * md5(nbytes, *buf, cksum); - * // Increase buffer size if necessary - * if (nbytes + 16 > *buf_size) { - * *buf_size = nbytes + 16; - * *buf = realloc(*buf, *buf_size); - * } - * // Append checksum - * memcpy((char*)(*buf)+nbytes, cksum, 16); - * return nbytes+16; - * } - * \c \#else - * return 0; // fail - * \c \#endif - * } - * /endcode + * the checksum. + * \code + * size_t md5_filter(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], + * size_t nbytes, size_t *buf_size, void **buf) + * { + * #ifdef HAVE_MD5 + * unsigned char cksum[16]; + * + * if (flags & H5Z_REVERSE) { + * // Input + * assert(nbytes >= 16); + * md5(nbytes-16, *buf, cksum); + * // Compare + * if (memcmp(cksum, (char*)(*buf)+ nbytes- 16, 16)) { + * return 0; // fail + * } + * // Strip off checksum + * return nbytes - 16; + * } + * else { + * // Output + * md5(nbytes, *buf, cksum); + * // Increase buffer size if necessary + * if (nbytes + 16 > *buf_size) { + * *buf_size = nbytes + 16; + * *buf = realloc(*buf, *buf_size); + * } + * // Append checksum + * memcpy((char*)(*buf)+nbytes, cksum, 16); + * return nbytes+16; + * } + * #else + * return 0; // fail + * #endif + * } + * \endcode * * Once the filter function is defined it must be registered so * the HDF5 library knows about it. Since we're testing this * filter we choose one of the #H5Z_filter_t numbers * from the reserved range. We'll randomly choose 305. * - * /code - * \c \#define FILTER_MD5 305 + * \code + * #define FILTER_MD5 305 * herr_t status = H5Zregister(FILTER_MD5, "md5 checksum", md5_filter); - * /endcode + * \endcode * * Now we can use the filter in a pipeline. We could have added * the filter to the pipeline before defining or registering the @@ -232,26 +234,28 @@ * have automatically removed it from the pipeline for each chunk * written before the filter was defined and registered). * - * /code + * \code * hid_t dcpl = H5Pcreate(H5P_DATASET_CREATE); * hsize_t chunk_size[3] = {10,10,10}; * H5Pset_chunk(dcpl, 3, chunk_size); * H5Pset_filter(dcpl, FILTER_MD5, 0, 0, NULL); * hid_t dset = H5Dcreate(file, "dset", H5T_NATIVE_DOUBLE, space, dcpl); - * /endcode + * \endcode * - * See the example of a more sophisticated HDF5 bzip2 filter function in the /ref subsec_filter_plugins_build - * section. The HDF5 bzip2 filter function is also available for download from Filter Plugin Repository. + * See the example of a more sophisticated HDF5 bzip2 filter function in the \ref subsec_filter_plugins_build + * section. The HDF5 bzip2 filter function is also available for download from + * Filter Plugin Repository. * * The user has to remember a few things when writing an HDF5 filter function. - * + *
    + *
  1. An HDF5 filter is bidirectional.
    + * The filter handles both input and output to the file; a flag is passed to the filter to indicate the + * direction.
    2. + *
  2. An HDF5 filter operates on a buffer.
    + * The filter reads data from a buffer, performs some sort of transformation on the data, places + * he result in the same or new buffer, and returns the buffer pointer and size to the caller.
    3. + *
  3. An HDF5 filter should return zero in the case of failure.
    4. + *
* * The signature of the HDF5 filter function and the accompanying filter structure (see the section below) * are described in the \ref RM #H5Z_filter_t. @@ -285,35 +289,42 @@ * The HDF5 Library and command-line tools have access to the “name” field. An application can * use the H5Pget_filter<*> functions to retrieve information about the filters. * - * Using the example of the structure above, the h5dump tool will print the string “HDF5 bzip2 + * Using the example of the structure above, the \ref sec_cltools_h5dump tool will print the string “HDF5 bzip2 * filter found at …” pointing users to the applied filter (see the example in the \ref * subsubsec_filter_plugins_model_read section) thus solving the problem of the filter’s origin. * * \subsubsection subsubsec_filter_plugins_prog_create Creating an HDF5 Filter Plugin * The HDF5 filter plugin source should include: - * + *
    + *
  1. The H5PLextern.h header file from the HDF5 distribution.
    2. + *
  2. The definition of the filter structure (see the example shown in the section above).
    3. + *
  3. The filter function (for example, H5Z_filter_bzip2).
    4. + *
  4. The two functions necessary for the HDF5 Library to find the correct type of the plugin library + * while loading it at runtime and to get information about the filter function:
    + * + * + * + *
    H5PL_type_t H5PLget_plugin_type(void);
    const void* H5PLget_plugin_info(void);

    + * Here is an example of the functions above for the HDF5 bzip2 filter:
    + * + * + * + *
    H5PL_type_t H5PLget_plugin_type(void) {return H5PL_TYPE_FILTER;}
    const void* H5PLget_plugin_info(void) {return H5Z_BZIP2;}
    5. + *
  5. Other functions such as the source of the compression library may also be included.
    6. + *
+ * * Build the HDF5 filter plugin as a shared library. The following steps should be taken: - * + *
    + *
  1. When compiling, point to the HDF5 header files.
    2. + *
  2. Use the appropriate linking flags.
    3. + *
  3. Link with any required external libraries.
    4. + *
  4. For example, if libbz2.so is installed on a Linux system, the HDF5 bzip2 plugin library + * libH5Zbzip2.so may be linked with libbz2.so instead of including bzip2 source into the + * plugin library.
    + * The complete example of the HDF5 bzip2 plugin library is provided at + * BZIP2 Filter Plugin + * and can be adopted for other plugins.
    5. + *
* * \subsubsection subsubsec_filter_plugins_prog_install Installing an HDF5 Filter Plugin * The default directory for an HDF5 filter plugin library is defined on UNIX-like systems as diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index f73d49e257c..360af0911d8 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -98,24 +98,18 @@ * * \snippet{doc} H5Zpublic.h FiltersIdTable * - * Filter identifiers for the filters distributed with the HDF5 - * Library are as follows: - * [PreDefFilters] - * - * - * - * - * - * - * - *
#H5Z_FILTER_DEFLATEThe gzip compression, or - * deflation, filter
#H5Z_FILTER_SZIPThe SZIP compression - * filter
#H5Z_FILTER_NBITThe N-bit compression - * filter
#H5Z_FILTER_SCALEOFFSETThe scale-offset - * compression filter
#H5Z_FILTER_SHUFFLEThe shuffle algorithm - * filter
#H5Z_FILTER_FLETCHER32The Fletcher32 checksum, - * or error checking, filter
- * [PreDefFilters] + * Filter identifiers for the filters distributed with the HDF5 Library are as follows: +//! [PreDefFilters] + + + + + + + +
#H5Z_FILTER_DEFLATEThe gzip compression, or deflation, filter
#H5Z_FILTER_SZIPThe SZIP compressionfilter
#H5Z_FILTER_NBITThe N-bit compression filter
#H5Z_FILTER_SCALEOFFSETThe scale-offset compression filter
#H5Z_FILTER_SHUFFLEThe shuffle algorithm filter
#H5Z_FILTER_FLETCHER32The Fletcher32 checksum, or error checking, filter
+//! [PreDefFilters] + * * Custom filters that have been registered with the library will have * additional unique identifiers. * diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index 06512f56435..f8d8448d84d 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -17,40 +17,40 @@ /** * \brief Filter identifiers * - * [FiltersIdTable] - - - - - - - - - - - - - - - - - - - - -
Values for #H5Z_filter_tDescription
0-255These values are reserved for filters predefined and - registered by the HDF5 library and of use to the general public.
256-511Filter values in this range are intended for testing only and can be - temporarily used by any organization. No attempts are made to resolve - numbering conflicts, as all definitions are temporary.
512-32,767Filter values within this range are designated for filters managed by - The HDF Group, but they are nominally requested, developed, and supported - by third parties. Please contact the - HDF5 development team - to reserve a value or range of values for use by your filters.
32,768-65,535Filter values in this range are designated for internal company use or - application testing when assessing a feature. The HDF Group does not - track or document the use of filters within this range. -
- * [FiltersIdTable] -*/ +//! [FiltersIdTable] + + + + + + + + + + + + + + + + + + + + +
Values for #H5Z_filter_tDescription
0-255These values are reserved for filters predefined and + registered by the HDF5 library and of use to the general public.
256-511Filter values in this range are intended for testing only and can be + temporarily used by any organization. No attempts are made to resolve + numbering conflicts, as all definitions are temporary.
512-32,767Filter values within this range are designated for filters managed by + The HDF Group, but they are nominally requested, developed, and supported + by third parties. Please contact the + HDF5 development team + to reserve a value or range of values for use by your filters.
32,768-65,535Filter values in this range are designated for internal company use or + application testing when assessing a feature. The HDF Group does not + track or document the use of filters within this range. +
+//! [FiltersIdTable] + */ typedef int H5Z_filter_t;