diff options
author | Dana Robinson <derobins@hdfgroup.org> | 2022-04-13 21:17:29 (GMT) |
---|---|---|
committer | Dana Robinson <derobins@hdfgroup.org> | 2022-04-13 21:17:29 (GMT) |
commit | cabc39c3e197e2591449d2604bfee26465fb60e1 (patch) | |
tree | d5f39f5f5965584bf9bf49646a2af617adfd3e4e /src/H5Zpublic.h | |
parent | 7355f4c505092a7a85474b47f18d5206028e2c95 (diff) | |
parent | ab69f5df770ee3cc6cd6c81d905a5317b894a002 (diff) | |
download | hdf5-feature/coding_standards.zip hdf5-feature/coding_standards.tar.gz hdf5-feature/coding_standards.tar.bz2 |
Merge branch 'develop' into feature/coding_standardsfeature/coding_standards
Diffstat (limited to 'src/H5Zpublic.h')
-rw-r--r-- | src/H5Zpublic.h | 421 |
1 files changed, 247 insertions, 174 deletions
diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index a2a44fa..5d04c9a 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -6,243 +6,316 @@ * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * - * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * + * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Robb Matzke <matzke@llnl.gov> +/* Programmer: Robb Matzke * Thursday, April 16, 1998 */ -#ifndef _H5Zpublic_H -#define _H5Zpublic_H +#ifndef H5Zpublic_H +#define H5Zpublic_H /* Public headers needed by this file */ #include "H5public.h" -/* - * Filter identifiers. Values 0 through 255 are for filters defined by the - * HDF5 library. Values 256 through 511 are available for testing new - * filters. Subsequent values should be obtained from the HDF5 development - * team at help@hdfgroup.org. These values will never change because they - * appear in the HDF5 files. +/** + * \brief Filter identifiers + * + * \details Values 0 through 255 are for filters defined by the HDF5 library. + * Values 256 through 511 are available for testing new filters. + * Subsequent values should be obtained from the HDF5 development team + * at mailto:help@hdfgroup.org. These values will never change because + * they appear in the HDF5 files. */ typedef int H5Z_filter_t; /* Filter IDs */ -#define H5Z_FILTER_ERROR (-1) /*no filter */ -#define H5Z_FILTER_NONE 0 /*reserved indefinitely */ -#define H5Z_FILTER_DEFLATE 1 /*deflation like gzip */ -#define H5Z_FILTER_SHUFFLE 2 /*shuffle the data */ -#define H5Z_FILTER_FLETCHER32 3 /*fletcher32 checksum of EDC */ -#define H5Z_FILTER_SZIP 4 /*szip compression */ -#define H5Z_FILTER_NBIT 5 /*nbit compression */ -#define H5Z_FILTER_SCALEOFFSET 6 /*scale+offset compression */ -#define H5Z_FILTER_RESERVED 256 /*filter ids below this value are reserved for library use */ - -#define H5Z_FILTER_MAX 65535 /*maximum filter id */ +/** + * no filter + */ +#define H5Z_FILTER_ERROR (-1) +/** + * reserved indefinitely + */ +#define H5Z_FILTER_NONE 0 +/** + * deflation like gzip + */ +#define H5Z_FILTER_DEFLATE 1 +/** + * shuffle the data + */ +#define H5Z_FILTER_SHUFFLE 2 +/** + * fletcher32 checksum of EDC + */ +#define H5Z_FILTER_FLETCHER32 3 +/** + * szip compression + */ +#define H5Z_FILTER_SZIP 4 +/** + * nbit compression + */ +#define H5Z_FILTER_NBIT 5 +/** + * scale+offset compression + */ +#define H5Z_FILTER_SCALEOFFSET 6 +/** + * filter ids below this value are reserved for library use + */ +#define H5Z_FILTER_RESERVED 256 +/** + * maximum filter id + */ +#define H5Z_FILTER_MAX 65535 /* General macros */ -#define H5Z_FILTER_ALL 0 /* Symbol to remove all filters in H5Premove_filter */ -#define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */ - /* (should probably be allowed to be an - * unlimited amount, but currently each - * filter uses a bit in a 32-bit field, - * so the format would have to be - * changed to accommodate that) - */ +/** + * Symbol to remove all filters in H5Premove_filter() + */ +#define H5Z_FILTER_ALL 0 +/** + * Maximum number of filters allowed in a pipeline + * + * \internal (should probably be allowed to be an unlimited amount, but + * currently each filter uses a bit in a 32-bit field, so the format + * would have to be changed to accommodate that) + */ +#define H5Z_MAX_NFILTERS 32 /* Flags for filter definition (stored) */ -#define H5Z_FLAG_DEFMASK 0x00ff /*definition flag mask */ -#define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory */ -#define H5Z_FLAG_OPTIONAL 0x0001 /*filter is optional */ +/** + * definition flag mask + */ +#define H5Z_FLAG_DEFMASK 0x00ff +/** + * filter is mandatory + */ +#define H5Z_FLAG_MANDATORY 0x0000 +/** + * filter is optional + */ +#define H5Z_FLAG_OPTIONAL 0x0001 /* Additional flags for filter invocation (not stored) */ -#define H5Z_FLAG_INVMASK 0xff00 /*invocation flag mask */ -#define H5Z_FLAG_REVERSE 0x0100 /*reverse direction; read */ -#define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read */ +/** + * invocation flag mask + */ +#define H5Z_FLAG_INVMASK 0xff00 +/** + * reverse direction; read + */ +#define H5Z_FLAG_REVERSE 0x0100 +/** + * skip EDC filters for read + */ +#define H5Z_FLAG_SKIP_EDC 0x0200 /* Special parameters for szip compression */ /* [These are aliases for the similar definitions in szlib.h, which we can't * include directly due to the duplication of various symbols with the zlib.h * header file] */ -#define H5_SZIP_ALLOW_K13_OPTION_MASK 1 -#define H5_SZIP_CHIP_OPTION_MASK 2 -#define H5_SZIP_EC_OPTION_MASK 4 -#define H5_SZIP_NN_OPTION_MASK 32 -#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 +/** + * \ingroup SZIP */ +#define H5_SZIP_ALLOW_K13_OPTION_MASK 1 +/** + * \ingroup SZIP */ +#define H5_SZIP_CHIP_OPTION_MASK 2 +/** + * \ingroup SZIP */ +#define H5_SZIP_EC_OPTION_MASK 4 +/** + * \ingroup SZIP */ +#define H5_SZIP_NN_OPTION_MASK 32 +/** + * \ingroup SZIP */ +#define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 /* Macros for the shuffle filter */ -#define H5Z_SHUFFLE_USER_NPARMS 0 /* Number of parameters that users can set */ -#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */ +/** + * \ingroup SHUFFLE + * Number of parameters that users can set for the shuffle filter + */ +#define H5Z_SHUFFLE_USER_NPARMS 0 +/** + * \ingroup SHUFFLE + * Total number of parameters for the shuffle filter + */ +#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Macros for the szip filter */ -#define H5Z_SZIP_USER_NPARMS 2 /* Number of parameters that users can set */ -#define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */ -#define H5Z_SZIP_PARM_MASK 0 /* "User" parameter for option mask */ -#define H5Z_SZIP_PARM_PPB 1 /* "User" parameter for pixels-per-block */ -#define H5Z_SZIP_PARM_BPP 2 /* "Local" parameter for bits-per-pixel */ -#define H5Z_SZIP_PARM_PPS 3 /* "Local" parameter for pixels-per-scanline */ +/** + * \ingroup SZIP + * Number of parameters that users can set for SZIP + */ +#define H5Z_SZIP_USER_NPARMS 2 +/** + * \ingroup SZIP + * Total number of parameters for SZIP filter + */ +#define H5Z_SZIP_TOTAL_NPARMS 4 +/** + * \ingroup SZIP + * "User" parameter for option mask + */ +#define H5Z_SZIP_PARM_MASK 0 +/** + * \ingroup SZIP + * "User" parameter for pixels-per-block + */ +#define H5Z_SZIP_PARM_PPB 1 +/** + * \ingroup SZIP + * "Local" parameter for bits-per-pixel + */ +#define H5Z_SZIP_PARM_BPP 2 +/** + * \ingroup SZIP + * "Local" parameter for pixels-per-scanline + */ +#define H5Z_SZIP_PARM_PPS 3 /* Macros for the nbit filter */ -#define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */ +/** + * \ingroup NBIT + * Number of parameters that users can set for the N-bit filter + */ +#define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */ /* Macros for the scale offset filter */ -#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */ - +/** + * \ingroup SCALEOFFSET + * Number of parameters that users can set for the scale-offset filter + */ +#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Special parameters for ScaleOffset filter*/ +/** + * \ingroup SCALEOFFSET */ #define H5Z_SO_INT_MINBITS_DEFAULT 0 +/** + * \ingroup SCALEOFFSET */ typedef enum H5Z_SO_scale_type_t { H5Z_SO_FLOAT_DSCALE = 0, H5Z_SO_FLOAT_ESCALE = 1, H5Z_SO_INT = 2 } H5Z_SO_scale_type_t; -/* Current version of the H5Z_class_t struct */ -#define H5Z_CLASS_T_VERS (1) - -/* Values to decide if EDC is enabled for reading data */ +/** + * \ingroup FLETCHER32 + * Values to decide if EDC is enabled for reading data + */ typedef enum H5Z_EDC_t { - H5Z_ERROR_EDC = -1, /* error value */ - H5Z_DISABLE_EDC = 0, - H5Z_ENABLE_EDC = 1, - H5Z_NO_EDC = 2 /* must be the last */ + H5Z_ERROR_EDC = -1, /**< error value */ + H5Z_DISABLE_EDC = 0, + H5Z_ENABLE_EDC = 1, + H5Z_NO_EDC = 2 /**< sentinel */ } H5Z_EDC_t; /* Bit flags for H5Zget_filter_info */ #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001) #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002) -/* Return values for filter callback function */ +/** + * Return values for filter callback function + */ typedef enum H5Z_cb_return_t { - H5Z_CB_ERROR = -1, - H5Z_CB_FAIL = 0, /* I/O should fail if filter fails. */ - H5Z_CB_CONT = 1, /* I/O continues if filter fails. */ - H5Z_CB_NO = 2 + H5Z_CB_ERROR = -1, /**< error value */ + H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */ + H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */ + H5Z_CB_NO = 2 /**< sentinel */ } H5Z_cb_return_t; -/* Filter callback function definition */ -typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void* buf, - size_t buf_size, void* op_data); - -/* Structure for filter callback property */ -typedef struct H5Z_cb_t { - H5Z_filter_func_t func; - void *op_data; -} H5Z_cb_t; +//! <!-- [H5Z_filter_func_t_snip] --> +/** + * Filter callback function definition + */ +typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data); +//! <!-- [H5Z_filter_func_t_snip] --> #ifdef __cplusplus extern "C" { #endif -/* - * Before a dataset gets 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, the dataset's datatype and - * a dataspace describing a chunk (for chunked dataset storage). - * - * The "can_apply" callback must determine if the combination of the dataset - * creation property list setting, the datatype and the dataspace represent a - * valid combination to apply this filter to. For example, some cases of - * invalid combinations may involve the filter not operating correctly on - * certain datatypes (or certain datatype sizes), or certain sizes of the chunk - * dataspace. - * - * The "can_apply" callback can be the NULL pointer, in which case, the library - * will assume that it can apply to any combination of dataset creation - * property list values, datatypes and dataspaces. - * - * The "can_apply" callback returns positive a valid combination, zero for an - * invalid combination and negative for an error. - */ -typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); - -/* - * After the "can_apply" callbacks are checked for new datasets, the "set_local" - * callbacks for any filters used in the dataset creation property list are - * called. These callbacks receive 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) and the datatype ID passed in to H5Dcreate - * (which is not copied and should not be modified) and 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 (or datatype sizes) or - * different number of dimensions or dataspace sizes. - * - * The "set_local" callback can 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 must return non-negative on success and negative - * for an error. - */ -typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); - -/* - * A filter gets definition flags and invocation flags (defined above), the - * client data array and size defined when the filter was added to the - * pipeline, the size in bytes of the data on which to operate, and pointers - * to a buffer and its allocated size. - * - * The filter should store the result in the supplied buffer if possible, - * otherwise it can allocate a new buffer, freeing the original. The - * allocated size of the new buffer should be returned through the BUF_SIZE - * pointer and the new buffer through the BUF pointer. - * - * The return value from the filter is the number of bytes in the output - * buffer. If an error occurs then the function should return zero and leave - * all pointer arguments unchanged. - */ -typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, - const unsigned int cd_values[], size_t nbytes, - size_t *buf_size, void **buf); - -/* - * The filter table maps filter identification numbers to structs that - * contain a pointers to the filter function and timing statistics. - */ -typedef struct H5Z_class2_t { - int version; /* Version number of the H5Z_class_t struct */ - H5Z_filter_t id; /* Filter ID number */ - unsigned encoder_present; /* Does this filter have an encoder? */ - unsigned decoder_present; /* Does this filter have a decoder? */ - const char *name; /* Comment for debugging */ - H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ - H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ - H5Z_func_t filter; /* The actual filter function */ -} H5Z_class2_t; - -H5_DLL herr_t H5Zregister(const void *cls); -H5_DLL herr_t H5Zunregister(H5Z_filter_t id); -H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); -H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags); - -/* Symbols defined for compatibility with previous versions of the HDF5 API. +/** + * \ingroup H5Z + * + * \brief Determines whether a filter is available * - * Use of these symbols is deprecated. + * \param[in] id Filter identifier + * \return \htri_t + * + * \details H5Zfilter_avail() determines whether the filter specified in \p id + * is available to the application. + * + * \since 1.6.0 */ -#ifndef H5_NO_DEPRECATED_SYMBOLS - -/* - * The filter table maps filter identification numbers to structs that - * contain a pointers to the filter function and timing statistics. +H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); +/** + * \ingroup H5Z + * + * \brief Retrieves information about a filter + * + * \param[in] filter Filter identifier + * \param[out] filter_config_flags A bit field encoding the returned filter + * information + * \return \herr_t + * + * \details H5Zget_filter_info() retrieves information about a filter. At + * present, this means that the function retrieves a filter's + * configuration flags, indicating whether the filter is configured to + * decode data, to encode data, neither, or both. + * + * If \p filter_config_flags is not set to NULL prior to the function + * call, the returned parameter contains a bit field specifying the + * available filter configuration. The configuration flag values can + * then be determined through a series of bitwise AND operations, as + * described below. + * + * Valid filter configuration flags include the following: + * <table> + * <tr><td>#H5Z_FILTER_CONFIG_ENCODE_ENABLED</td> + * <td>Encoding is enabled for this filter</td></tr> + * <tr><td>#H5Z_FILTER_CONFIG_DECODE_ENABLED</td> + * <td>Decoding is enabled for this filter</td></tr> + * </table> + * + * A bitwise AND of the returned \p filter_config_flags and a valid + * filter configuration flag will reveal whether the related + * configuration option is available. For example, if the value of + * \code + * H5Z_FILTER_CONFIG_ENCODE_ENABLED & filter_config_flags + * \endcode + * is true, i.e., greater than 0 (zero), the queried filter + * is configured to encode data; if the value is \c FALSE, i.e., equal to + * 0 (zero), the filter is not so configured. + * + * If a filter is not encode-enabled, the corresponding \c H5Pset_* + * function will return an error if the filter is added to a dataset + * creation property list (which is required if the filter is to be + * used to encode that dataset). For example, if the + * #H5Z_FILTER_CONFIG_ENCODE_ENABLED flag is not returned for the SZIP + * filter, #H5Z_FILTER_SZIP, a call to H5Pset_szip() will fail. + * + * If a filter is not decode-enabled, the application will not be able + * to read an existing file encoded with that filter. + * + * This function should be called, and the returned \p + * filter_config_flags analyzed, before calling any other function, + * such as H5Pset_szip() , that might require a particular filter + * configuration. + * + * \since 1.6.3 */ -typedef struct H5Z_class1_t { - H5Z_filter_t id; /* Filter ID number */ - const char *name; /* Comment for debugging */ - H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ - H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ - H5Z_func_t filter; /* The actual filter function */ -} H5Z_class1_t; - -#endif /* H5_NO_DEPRECATED_SYMBOLS */ +H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags); #ifdef __cplusplus } #endif -#endif +#endif /* _H5Zpublic_H */ |