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