1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the COPYING file, which can be found at the root of the source code * 9 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * 10 * If you do not have access to either file, you may request a copy from * 11 * help@hdfgroup.org. * 12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 13 14 /* Programmer: Robb Matzke <matzke@llnl.gov> 15 * Thursday, April 16, 1998 16 */ 17 18 #ifndef _H5Zpublic_H 19 #define _H5Zpublic_H 20 21 /* Public headers needed by this file */ 22 #include "H5public.h" 23 24 /* 25 * Filter identifiers. Values 0 through 255 are for filters defined by the 26 * HDF5 library. Values 256 through 511 are available for testing new 27 * filters. Subsequent values should be obtained from the HDF5 development 28 * team at hdf5dev@ncsa.uiuc.edu. These values will never change because they 29 * appear in the HDF5 files. 30 */ 31 typedef int H5Z_filter_t; 32 33 /* Filter IDs */ 34 #define H5Z_FILTER_ERROR (-1) /*no filter */ 35 #define H5Z_FILTER_NONE 0 /*reserved indefinitely */ 36 #define H5Z_FILTER_DEFLATE 1 /*deflation like gzip */ 37 #define H5Z_FILTER_SHUFFLE 2 /*shuffle the data */ 38 #define H5Z_FILTER_FLETCHER32 3 /*fletcher32 checksum of EDC */ 39 #define H5Z_FILTER_SZIP 4 /*szip compression */ 40 #define H5Z_FILTER_NBIT 5 /*nbit compression */ 41 #define H5Z_FILTER_SCALEOFFSET 6 /*scale+offset compression */ 42 #define H5Z_FILTER_RESERVED 256 /*filter ids below this value are reserved for library use */ 43 44 #define H5Z_FILTER_MAX 65535 /*maximum filter id */ 45 46 /* General macros */ 47 #define H5Z_FILTER_ALL 0 /* Symbol to remove all filters in H5Premove_filter */ 48 #define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */ 49 /* (should probably be allowed to be an 50 * unlimited amount, but currently each 51 * filter uses a bit in a 32-bit field, 52 * so the format would have to be 53 * changed to accomodate that) 54 */ 55 56 /* Flags for filter definition (stored) */ 57 #define H5Z_FLAG_DEFMASK 0x00ff /*definition flag mask */ 58 #define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory */ 59 #define H5Z_FLAG_OPTIONAL 0x0001 /*filter is optional */ 60 61 /* Additional flags for filter invocation (not stored) */ 62 #define H5Z_FLAG_INVMASK 0xff00 /*invocation flag mask */ 63 #define H5Z_FLAG_REVERSE 0x0100 /*reverse direction; read */ 64 #define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read */ 65 66 /* Special parameters for szip compression */ 67 /* [These are aliases for the similar definitions in szlib.h, which we can't 68 * include directly due to the duplication of various symbols with the zlib.h 69 * header file] */ 70 #define H5_SZIP_ALLOW_K13_OPTION_MASK 1 71 #define H5_SZIP_CHIP_OPTION_MASK 2 72 #define H5_SZIP_EC_OPTION_MASK 4 73 #define H5_SZIP_NN_OPTION_MASK 32 74 #define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 75 76 /* Macros for the shuffle filter */ 77 #define H5Z_SHUFFLE_USER_NPARMS 0 /* Number of parameters that users can set */ 78 #define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */ 79 80 /* Macros for the szip filter */ 81 #define H5Z_SZIP_USER_NPARMS 2 /* Number of parameters that users can set */ 82 #define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */ 83 #define H5Z_SZIP_PARM_MASK 0 /* "User" parameter for option mask */ 84 #define H5Z_SZIP_PARM_PPB 1 /* "User" parameter for pixels-per-block */ 85 #define H5Z_SZIP_PARM_BPP 2 /* "Local" parameter for bits-per-pixel */ 86 #define H5Z_SZIP_PARM_PPS 3 /* "Local" parameter for pixels-per-scanline */ 87 88 /* Macros for the nbit filter */ 89 #define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */ 90 91 /* Macros for the scale offset filter */ 92 #define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */ 93 94 95 /* Special parameters for ScaleOffset filter*/ 96 #define H5Z_SO_INT_MINBITS_DEFAULT 0 97 typedef enum H5Z_SO_scale_type_t { 98 H5Z_SO_FLOAT_DSCALE = 0, 99 H5Z_SO_FLOAT_ESCALE = 1, 100 H5Z_SO_INT = 2 101 } H5Z_SO_scale_type_t; 102 103 /* Current version of the H5Z_class_t struct */ 104 #define H5Z_CLASS_T_VERS (1) 105 106 /* Values to decide if EDC is enabled for reading data */ 107 typedef enum H5Z_EDC_t { 108 H5Z_ERROR_EDC = -1, /* error value */ 109 H5Z_DISABLE_EDC = 0, 110 H5Z_ENABLE_EDC = 1, 111 H5Z_NO_EDC = 2 /* must be the last */ 112 } H5Z_EDC_t; 113 114 /* Bit flags for H5Zget_filter_info */ 115 #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001) 116 #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002) 117 118 /* Return values for filter callback function */ 119 typedef enum H5Z_cb_return_t { 120 H5Z_CB_ERROR = -1, 121 H5Z_CB_FAIL = 0, /* I/O should fail if filter fails. */ 122 H5Z_CB_CONT = 1, /* I/O continues if filter fails. */ 123 H5Z_CB_NO = 2 124 } H5Z_cb_return_t; 125 126 /* Filter callback function definition */ 127 typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void* buf, 128 size_t buf_size, void* op_data); 129 130 /* Structure for filter callback property */ 131 typedef struct H5Z_cb_t { 132 H5Z_filter_func_t func; 133 void* op_data; 134 } H5Z_cb_t; 135 136 #ifdef __cplusplus 137 extern "C" { 138 #endif 139 140 /* 141 * Before a dataset gets created, the "can_apply" callbacks for any filters used 142 * in the dataset creation property list are called 143 * with the dataset's dataset creation property list, the dataset's datatype and 144 * a dataspace describing a chunk (for chunked dataset storage). 145 * 146 * The "can_apply" callback must determine if the combination of the dataset 147 * creation property list setting, the datatype and the dataspace represent a 148 * valid combination to apply this filter to. For example, some cases of 149 * invalid combinations may involve the filter not operating correctly on 150 * certain datatypes (or certain datatype sizes), or certain sizes of the chunk 151 * dataspace. 152 * 153 * The "can_apply" callback can be the NULL pointer, in which case, the library 154 * will assume that it can apply to any combination of dataset creation 155 * property list values, datatypes and dataspaces. 156 * 157 * The "can_apply" callback returns positive a valid combination, zero for an 158 * invalid combination and negative for an error. 159 */ 160 typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); 161 162 /* 163 * After the "can_apply" callbacks are checked for new datasets, the "set_local" 164 * callbacks for any filters used in the dataset creation property list are 165 * called. These callbacks receive the dataset's private copy of the dataset 166 * creation property list passed in to H5Dcreate (i.e. not the actual property 167 * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate 168 * (which is not copied and should not be modified) and a dataspace describing 169 * the chunk (for chunked dataset storage) (which should also not be modified). 170 * 171 * The "set_local" callback must set any parameters that are specific to this 172 * dataset, based on the combination of the dataset creation property list 173 * values, the datatype and the dataspace. For example, some filters perform 174 * different actions based on different datatypes (or datatype sizes) or 175 * different number of dimensions or dataspace sizes. 176 * 177 * The "set_local" callback can be the NULL pointer, in which case, the library 178 * will assume that there are no dataset-specific settings for this filter. 179 * 180 * The "set_local" callback must return non-negative on success and negative 181 * for an error. 182 */ 183 typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); 184 185 /* 186 * A filter gets definition flags and invocation flags (defined above), the 187 * client data array and size defined when the filter was added to the 188 * pipeline, the size in bytes of the data on which to operate, and pointers 189 * to a buffer and its allocated size. 190 * 191 * The filter should store the result in the supplied buffer if possible, 192 * otherwise it can allocate a new buffer, freeing the original. The 193 * allocated size of the new buffer should be returned through the BUF_SIZE 194 * pointer and the new buffer through the BUF pointer. 195 * 196 * The return value from the filter is the number of bytes in the output 197 * buffer. If an error occurs then the function should return zero and leave 198 * all pointer arguments unchanged. 199 */ 200 typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, 201 const unsigned int cd_values[], size_t nbytes, 202 size_t *buf_size, void **buf); 203 204 /* 205 * The filter table maps filter identification numbers to structs that 206 * contain a pointers to the filter function and timing statistics. 207 */ 208 typedef struct H5Z_class2_t { 209 int version; /* Version number of the H5Z_class_t struct */ 210 H5Z_filter_t id; /* Filter ID number */ 211 unsigned encoder_present; /* Does this filter have an encoder? */ 212 unsigned decoder_present; /* Does this filter have a decoder? */ 213 const char *name; /* Comment for debugging */ 214 H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ 215 H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ 216 H5Z_func_t filter; /* The actual filter function */ 217 } H5Z_class2_t; 218 219 H5_DLL herr_t H5Zregister(const void *cls); 220 H5_DLL herr_t H5Zunregister(H5Z_filter_t id); 221 H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); 222 H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags); 223 224 /* Symbols defined for compatibility with previous versions of the HDF5 API. 225 * 226 * Use of these symbols is deprecated. 227 */ 228 #ifndef H5_NO_DEPRECATED_SYMBOLS 229 230 /* 231 * The filter table maps filter identification numbers to structs that 232 * contain a pointers to the filter function and timing statistics. 233 */ 234 typedef struct H5Z_class1_t { 235 H5Z_filter_t id; /* Filter ID number */ 236 const char *name; /* Comment for debugging */ 237 H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ 238 H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ 239 H5Z_func_t filter; /* The actual filter function */ 240 } H5Z_class1_t; 241 242 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 243 244 #ifdef __cplusplus 245 } 246 #endif 247 #endif 248 249