source/include/H5Zpublic.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 #ifndef H5Zpublic_H
0014 #define H5Zpublic_H
0015
0016 #include "H5public.h" /* Generic Functions                        */
0017
0018 /**
0019  * \brief Filter identifiers
0020  *
0021  * \details Values 0 through 255 are for filters defined by the HDF5 library.
0022  *          Values 256 through 511 are available for testing new filters.
0023  *          Subsequent values should be obtained from the HDF5 development team
0024  *          at mailto:help@hdfgroup.org. These values will never change because
0025  *          they appear in the HDF5 files.
0026  */
0027 typedef int H5Z_filter_t;
0028
0029 /* Filter IDs */
0030 /**
0031  * no filter
0032  */
0033 #define H5Z_FILTER_ERROR (-1)
0034 /**
0035  * reserved indefinitely
0036  */
0037 #define H5Z_FILTER_NONE 0
0038 /**
0039  * deflation like gzip
0040  */
0041 #define H5Z_FILTER_DEFLATE 1
0042 /**
0043  * shuffle the data
0044  */
0045 #define H5Z_FILTER_SHUFFLE 2
0046 /**
0047  * fletcher32 checksum of EDC
0048  */
0049 #define H5Z_FILTER_FLETCHER32 3
0050 /**
0051  * szip compression
0052  */
0053 #define H5Z_FILTER_SZIP 4
0054 /**
0055  * nbit compression
0056  */
0057 #define H5Z_FILTER_NBIT 5
0058 /**
0059  * scale+offset compression
0060  */
0061 #define H5Z_FILTER_SCALEOFFSET 6
0062 /**
0063  * filter ids below this value are reserved for library use
0064  */
0065 #define H5Z_FILTER_RESERVED 256
0066 /**
0067  * maximum filter id
0068  */
0069 #define H5Z_FILTER_MAX 65535
0070
0071 /* General macros */
0072 /**
0073  * Symbol to remove all filters in H5Premove_filter()
0074  */
0075 #define H5Z_FILTER_ALL 0
0076 /**
0077  * Maximum number of filters allowed in a pipeline
0078  *
0079  * \internal (should probably be allowed to be an unlimited amount, but
0080  *            currently each filter uses a bit in a 32-bit field, so the format
0081  *            would have to be changed to accommodate that)
0082  */
0083 #define H5Z_MAX_NFILTERS 32
0084
0085 /* Flags for filter definition (stored) */
0086 /**
0087  * definition flag mask
0088  */
0089 #define H5Z_FLAG_DEFMASK 0x00ff
0090 /**
0091  * filter is mandatory
0092  */
0093 #define H5Z_FLAG_MANDATORY 0x0000
0094 /**
0095  * filter is optional
0096  */
0097 #define H5Z_FLAG_OPTIONAL 0x0001
0098
0099 /* Additional flags for filter invocation (not stored) */
0100 /**
0101  * invocation flag mask
0102  */
0103 #define H5Z_FLAG_INVMASK 0xff00
0104 /**
0105  * reverse direction; read
0106  */
0107 #define H5Z_FLAG_REVERSE 0x0100
0108 /**
0109  * skip EDC filters for read
0110  */
0111 #define H5Z_FLAG_SKIP_EDC 0x0200
0112
0113 /* Special parameters for szip compression
0114  *
0115  * These are aliases for similarly-named definitions in szlib.h, which we
0116  * can't include directly due to the duplication of various symbols with the
0117  * zlib.h header file.
0118  *
0119  * The flag values are set to the same values as in szlib.h. The following
0120  * symbols are internal and defined in H5Zprivate.h:
0121  *
0122  * - H5_SZIP_LSB_OPTION_MASK
0123  * - H5_SZIP_MSB_OPTION_MASK
0124  * - H5_SZIP_RAW_OPTION_MASK
0125  *
0126  * TODO: These symbols should probably be deprecated and moved to H5Zprivate.h
0127  *       in the next major release of the library since they are only used
0128  *       internally:
0129  *
0130  * - H5_SZIP_ALLOW_K13_OPTION_MASK
0131  * - H5_SZIP_CHIP_OPTION_MASK
0132  */
0133 /**
0134  * \ingroup SZIP
0135  *
0136  * Used internally. Always added to the \p options_mask parameter of H5Pset_szip().
0137  */
0138 #define H5_SZIP_ALLOW_K13_OPTION_MASK 1
0139 /**
0140  * \ingroup SZIP
0141  *
0142  * Used internally. Always removed from the \p options_mask parameter of H5Pset_szip().
0143  */
0144 #define H5_SZIP_CHIP_OPTION_MASK 2
0145 /**
0146  * \ingroup SZIP
0147  *
0148  * Use the entropy coding method
0149  */
0150 #define H5_SZIP_EC_OPTION_MASK 4
0151 /**
0152  * \ingroup SZIP
0153  *
0154  * Use nearest neighbor preprocessing and then the entropy coding method
0155  */
0156 #define H5_SZIP_NN_OPTION_MASK 32
0157 /**
0158  * \ingroup SZIP
0159  *
0160  * The maximum number of pixels per block (see H5Pset_szip())
0161  */
0162 #define H5_SZIP_MAX_PIXELS_PER_BLOCK 32
0163
0164 /* Macros for the shuffle filter */
0165 /**
0166  * \ingroup SHUFFLE
0167  * Number of parameters that users can set for the shuffle filter
0168  */
0169 #define H5Z_SHUFFLE_USER_NPARMS 0
0170 /**
0171  * \ingroup SHUFFLE
0172  * Total number of parameters for the shuffle filter
0173  */
0174 #define H5Z_SHUFFLE_TOTAL_NPARMS 1
0175
0176 /* Macros for the szip filter */
0177 /**
0178  * \ingroup SZIP
0179  * Number of parameters that users can set for SZIP
0180  */
0181 #define H5Z_SZIP_USER_NPARMS 2
0182 /**
0183  * \ingroup SZIP
0184  * Total number of parameters for SZIP filter
0185  */
0186 #define H5Z_SZIP_TOTAL_NPARMS 4
0187 /**
0188  * \ingroup SZIP
0189  * "User" parameter for option mask
0190  */
0191 #define H5Z_SZIP_PARM_MASK 0
0192 /**
0193  * \ingroup SZIP
0194  * "User" parameter for pixels-per-block
0195  */
0196 #define H5Z_SZIP_PARM_PPB 1
0197 /**
0198  * \ingroup SZIP
0199  * "Local" parameter for bits-per-pixel
0200  */
0201 #define H5Z_SZIP_PARM_BPP 2
0202 /**
0203  * \ingroup SZIP
0204  * "Local" parameter for pixels-per-scanline
0205  */
0206 #define H5Z_SZIP_PARM_PPS 3
0207
0208 /* Macros for the nbit filter */
0209 /**
0210  * \ingroup NBIT
0211  * Number of parameters that users can set for the N-bit filter
0212  */
0213 #define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */
0214
0215 /* Macros for the scale offset filter */
0216 /**
0217  * \ingroup SCALEOFFSET
0218  * Number of parameters that users can set for the scale-offset filter
0219  */
0220 #define H5Z_SCALEOFFSET_USER_NPARMS 2
0221
0222 /* Special parameters for ScaleOffset filter*/
0223 /**
0224  * \ingroup SCALEOFFSET */
0225 #define H5Z_SO_INT_MINBITS_DEFAULT 0
0226 /**
0227  * \ingroup SCALEOFFSET */
0228 typedef enum H5Z_SO_scale_type_t {
0229     H5Z_SO_FLOAT_DSCALE = 0,
0230     H5Z_SO_FLOAT_ESCALE = 1,
0231     H5Z_SO_INT          = 2
0232 } H5Z_SO_scale_type_t;
0233
0234 /**
0235  * \ingroup FLETCHER32
0236  * Values to decide if EDC is enabled for reading data
0237  */
0238 typedef enum H5Z_EDC_t {
0239     H5Z_ERROR_EDC   = -1, /**< error value */
0240     H5Z_DISABLE_EDC = 0,
0241     H5Z_ENABLE_EDC  = 1,
0242     H5Z_NO_EDC      = 2 /**< sentinel */
0243 } H5Z_EDC_t;
0244
0245 /* Bit flags for H5Zget_filter_info */
0246 #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001)
0247 #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002)
0248
0249 /**
0250  * Return values for filter callback function
0251  */
0252 typedef enum H5Z_cb_return_t {
0253     H5Z_CB_ERROR = -1, /**< error value */
0254     H5Z_CB_FAIL  = 0,  /**< I/O should fail if filter fails. */
0255     H5Z_CB_CONT  = 1,  /**< I/O continues if filter fails.   */
0256     H5Z_CB_NO    = 2   /**< sentinel */
0257 } H5Z_cb_return_t;
0258
0259 //! <!-- [H5Z_filter_func_t_snip] -->
0260 /**
0261  *  Filter callback function definition
0262  */
0263 typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data);
0264 //! <!-- [H5Z_filter_func_t_snip] -->
0265
0266 #ifdef __cplusplus
0267 extern "C" {
0268 #endif
0269
0270 /**
0271  * \ingroup H5Z
0272  *
0273  * \brief Determines whether a filter is available
0274  *
0275  * \param[in] id Filter identifier
0276  * \return \htri_t
0277  *
0278  * \details H5Zfilter_avail() determines whether the filter specified in \p id
0279  *          is available to the application.
0280  *
0281  * \since 1.6.0
0282  */
0283 H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id);
0284 /**
0285  * \ingroup H5Z
0286  *
0287  * \brief Retrieves information about a filter
0288  *
0289  * \param[in] filter Filter identifier
0290  * \param[out] filter_config_flags A bit field encoding the returned filter
0291  *                                 information
0292  * \return \herr_t
0293  *
0294  * \details H5Zget_filter_info() retrieves information about a filter. At
0295  *          present, this means that the function retrieves a filter's
0296  *          configuration flags, indicating whether the filter is configured to
0297  *          decode data, encode data, neither, or both.
0298  *
0299  *          If \p filter_config_flags is not set to NULL prior to the function
0300  *          call, the returned parameter contains a bit field specifying the
0301  *          available filter configuration. The configuration flag values can
0302  *          then be determined through a series of bitwise AND operations, as
0303  *          described below.
0304  *
0305  *          Valid filter configuration flags include the following:
0306  *          <table>
0307  *            <tr><td>#H5Z_FILTER_CONFIG_ENCODE_ENABLED</td>
0308  *                <td>Encoding is enabled for this filter</td></tr>
0309  *            <tr><td>#H5Z_FILTER_CONFIG_DECODE_ENABLED</td>
0310  *                <td>Decoding is enabled for this filter</td></tr>
0311  *          </table>
0312  *
0313  *          A bitwise AND of the returned \p filter_config_flags and a valid
0314  *          filter configuration flag will reveal whether the related
0315  *          configuration option is available. For example, if the value of
0316  *          \code
0317  *          H5Z_FILTER_CONFIG_ENCODE_ENABLED & filter_config_flags
0318  *          \endcode
0319  *          is true, i.e., greater than 0 (zero), the queried filter
0320  *          is configured to encode data; if the value is \c false, i.e., equal to
0321  *          0 (zero), the filter is not so configured.
0322  *
0323  *          If a filter is not encode-enabled, the corresponding \c H5Pset_*
0324  *          function will return an error if the filter is added to a dataset
0325  *          creation property list (which is required if the filter is to be
0326  *          used to encode that dataset). For example, if the
0327  *          #H5Z_FILTER_CONFIG_ENCODE_ENABLED flag is not returned for the SZIP
0328  *          filter, #H5Z_FILTER_SZIP, a call to H5Pset_szip() will fail.
0329  *
0330  *          If a filter is not decode-enabled, the application will not be able
0331  *          to read an existing file encoded with that filter.
0332  *
0333  *          This function should be called, and the returned \p
0334  *          filter_config_flags should be analyzed, before calling any other function,
0335  *          such as H5Pset_szip(), that might require a particular filter
0336  *          configuration.
0337  *
0338  * \since 1.6.0
0339  */
0340 H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags);
0341
0342 #ifdef __cplusplus
0343 }
0344 #endif
0345
0346 #endif /* _H5Zpublic_H */