00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 00002 * Copyright by The HDF Group. * 00003 * Copyright by the Board of Trustees of the University of Illinois. * 00004 * All rights reserved. * 00005 * * 00006 * This file is part of HDF5. The full HDF5 copyright notice, including * 00007 * terms governing use, modification, and redistribution, is contained in * 00008 * the files COPYING and Copyright.html. COPYING can be found at the root * 00009 * of the source code distribution tree; Copyright.html can be found at the * 00010 * root level of an installed copy of the electronic HDF5 document set and * 00011 * is linked from the top-level documents page. It can also be found at * 00012 * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * 00013 * access to either file, you may request a copy from help@hdfgroup.org. * 00014 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 00015 00016 /* Programmer: Robb Matzke <matzke@llnl.gov> 00017 * Thursday, April 16, 1998 00018 */ 00019 00020 #ifndef _H5Zpublic_H 00021 #define _H5Zpublic_H 00022 00023 /* Public headers needed by this file */ 00024 #include "H5public.h" 00025 00026 /* 00027 * Filter identifiers. Values 0 through 255 are for filters defined by the 00028 * HDF5 library. Values 256 through 511 are available for testing new 00029 * filters. Subsequent values should be obtained from the HDF5 development 00030 * team at hdf5dev@ncsa.uiuc.edu. These values will never change because they 00031 * appear in the HDF5 files. 00032 */ 00033 typedef int H5Z_filter_t; 00034 00035 /* Filter IDs */ 00036 #define H5Z_FILTER_ERROR (-1) /*no filter */ 00037 #define H5Z_FILTER_NONE 0 /*reserved indefinitely */ 00038 #define H5Z_FILTER_DEFLATE 1 /*deflation like gzip */ 00039 #define H5Z_FILTER_SHUFFLE 2 /*shuffle the data */ 00040 #define H5Z_FILTER_FLETCHER32 3 /*fletcher32 checksum of EDC */ 00041 #define H5Z_FILTER_SZIP 4 /*szip compression */ 00042 #define H5Z_FILTER_NBIT 5 /*nbit compression */ 00043 #define H5Z_FILTER_SCALEOFFSET 6 /*scale+offset compression */ 00044 #define H5Z_FILTER_RESERVED 256 /*filter ids below this value are reserved for library use */ 00045 #define H5Z_FILTER_MAX 65535 /*maximum filter id */ 00046 00047 /* General macros */ 00048 #define H5Z_FILTER_ALL 0 /* Symbol to remove all filters in H5Premove_filter */ 00049 #define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */ 00050 /* (should probably be allowed to be an 00051 * unlimited amount, but currently each 00052 * filter uses a bit in a 32-bit field, 00053 * so the format would have to be 00054 * changed to accomodate that) 00055 */ 00056 00057 /* Flags for filter definition (stored) */ 00058 #define H5Z_FLAG_DEFMASK 0x00ff /*definition flag mask */ 00059 #define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory */ 00060 #define H5Z_FLAG_OPTIONAL 0x0001 /*filter is optional */ 00061 00062 /* Additional flags for filter invocation (not stored) */ 00063 #define H5Z_FLAG_INVMASK 0xff00 /*invocation flag mask */ 00064 #define H5Z_FLAG_REVERSE 0x0100 /*reverse direction; read */ 00065 #define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read */ 00066 00067 /* Special parameters for szip compression */ 00068 /* [These are aliases for the similar definitions in szlib.h, which we can't 00069 * include directly due to the duplication of various symbols with the zlib.h 00070 * header file] */ 00071 #define H5_SZIP_ALLOW_K13_OPTION_MASK 1 00072 #define H5_SZIP_CHIP_OPTION_MASK 2 00073 #define H5_SZIP_EC_OPTION_MASK 4 00074 #define H5_SZIP_NN_OPTION_MASK 32 00075 #define H5_SZIP_MAX_PIXELS_PER_BLOCK 32 00076 00077 /* Macros for the shuffle filter */ 00078 #define H5Z_SHUFFLE_USER_NPARMS 0 /* Number of parameters that users can set */ 00079 #define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */ 00080 00081 /* Macros for the szip filter */ 00082 #define H5Z_SZIP_USER_NPARMS 2 /* Number of parameters that users can set */ 00083 #define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */ 00084 #define H5Z_SZIP_PARM_MASK 0 /* "User" parameter for option mask */ 00085 #define H5Z_SZIP_PARM_PPB 1 /* "User" parameter for pixels-per-block */ 00086 #define H5Z_SZIP_PARM_BPP 2 /* "Local" parameter for bits-per-pixel */ 00087 #define H5Z_SZIP_PARM_PPS 3 /* "Local" parameter for pixels-per-scanline */ 00088 00089 /* Macros for the nbit filter */ 00090 #define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */ 00091 00092 /* Macros for the scale offset filter */ 00093 #define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */ 00094 00095 00096 /* Special parameters for ScaleOffset filter*/ 00097 #define H5Z_SO_INT_MINBITS_DEFAULT 0 00098 typedef enum H5Z_SO_scale_type_t { 00099 H5Z_SO_FLOAT_DSCALE = 0, 00100 H5Z_SO_FLOAT_ESCALE = 1, 00101 H5Z_SO_INT = 2 00102 } H5Z_SO_scale_type_t; 00103 00104 /* Current version of the H5Z_class_t struct */ 00105 #define H5Z_CLASS_T_VERS (1) 00106 00107 /* Values to decide if EDC is enabled for reading data */ 00108 typedef enum H5Z_EDC_t { 00109 H5Z_ERROR_EDC = -1, /* error value */ 00110 H5Z_DISABLE_EDC = 0, 00111 H5Z_ENABLE_EDC = 1, 00112 H5Z_NO_EDC = 2 /* must be the last */ 00113 } H5Z_EDC_t; 00114 00115 /* Bit flags for H5Zget_filter_info */ 00116 #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001) 00117 #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002) 00118 00119 /* Return values for filter callback function */ 00120 typedef enum H5Z_cb_return_t { 00121 H5Z_CB_ERROR = -1, 00122 H5Z_CB_FAIL = 0, /* I/O should fail if filter fails. */ 00123 H5Z_CB_CONT = 1, /* I/O continues if filter fails. */ 00124 H5Z_CB_NO = 2 00125 } H5Z_cb_return_t; 00126 00127 /* Filter callback function definition */ 00128 typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void* buf, 00129 size_t buf_size, void* op_data); 00130 00131 /* Structure for filter callback property */ 00132 typedef struct H5Z_cb_t { 00133 H5Z_filter_func_t func; 00134 void* op_data; 00135 } H5Z_cb_t; 00136 00137 #ifdef __cplusplus 00138 extern "C" { 00139 #endif 00140 00141 /* 00142 * Before a dataset gets created, the "can_apply" callbacks for any filters used 00143 * in the dataset creation property list are called 00144 * with the dataset's dataset creation property list, the dataset's datatype and 00145 * a dataspace describing a chunk (for chunked dataset storage). 00146 * 00147 * The "can_apply" callback must determine if the combination of the dataset 00148 * creation property list setting, the datatype and the dataspace represent a 00149 * valid combination to apply this filter to. For example, some cases of 00150 * invalid combinations may involve the filter not operating correctly on 00151 * certain datatypes (or certain datatype sizes), or certain sizes of the chunk 00152 * dataspace. 00153 * 00154 * The "can_apply" callback can be the NULL pointer, in which case, the library 00155 * will assume that it can apply to any combination of dataset creation 00156 * property list values, datatypes and dataspaces. 00157 * 00158 * The "can_apply" callback returns positive a valid combination, zero for an 00159 * invalid combination and negative for an error. 00160 */ 00161 typedef herr_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); 00162 00163 /* 00164 * After the "can_apply" callbacks are checked for new datasets, the "set_local" 00165 * callbacks for any filters used in the dataset creation property list are 00166 * called. These callbacks receive the dataset's private copy of the dataset 00167 * creation property list passed in to H5Dcreate (i.e. not the actual property 00168 * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate 00169 * (which is not copied and should not be modified) and a dataspace describing 00170 * the chunk (for chunked dataset storage) (which should also not be modified). 00171 * 00172 * The "set_local" callback must set any parameters that are specific to this 00173 * dataset, based on the combination of the dataset creation property list 00174 * values, the datatype and the dataspace. For example, some filters perform 00175 * different actions based on different datatypes (or datatype sizes) or 00176 * different number of dimensions or dataspace sizes. 00177 * 00178 * The "set_local" callback can be the NULL pointer, in which case, the library 00179 * will assume that there are no dataset-specific settings for this filter. 00180 * 00181 * The "set_local" callback must return non-negative on success and negative 00182 * for an error. 00183 */ 00184 typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); 00185 00186 /* 00187 * A filter gets definition flags and invocation flags (defined above), the 00188 * client data array and size defined when the filter was added to the 00189 * pipeline, the size in bytes of the data on which to operate, and pointers 00190 * to a buffer and its allocated size. 00191 * 00192 * The filter should store the result in the supplied buffer if possible, 00193 * otherwise it can allocate a new buffer, freeing the original. The 00194 * allocated size of the new buffer should be returned through the BUF_SIZE 00195 * pointer and the new buffer through the BUF pointer. 00196 * 00197 * The return value from the filter is the number of bytes in the output 00198 * buffer. If an error occurs then the function should return zero and leave 00199 * all pointer arguments unchanged. 00200 */ 00201 typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, 00202 const unsigned int cd_values[], size_t nbytes, 00203 size_t *buf_size, void **buf); 00204 00205 /* 00206 * The filter table maps filter identification numbers to structs that 00207 * contain a pointers to the filter function and timing statistics. 00208 */ 00209 typedef struct H5Z_class2_t { 00210 int version; /* Version number of the H5Z_class_t struct */ 00211 H5Z_filter_t id; /* Filter ID number */ 00212 unsigned encoder_present; /* Does this filter have an encoder? */ 00213 unsigned decoder_present; /* Does this filter have a decoder? */ 00214 const char *name; /* Comment for debugging */ 00215 H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ 00216 H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ 00217 H5Z_func_t filter; /* The actual filter function */ 00218 } H5Z_class2_t; 00219 00220 H5_DLL herr_t H5Zregister(const void *cls); 00221 H5_DLL herr_t H5Zunregister(H5Z_filter_t id); 00222 H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); 00223 H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags); 00224 00225 /* Symbols defined for compatibility with previous versions of the HDF5 API. 00226 * 00227 * Use of these symbols is deprecated. 00228 */ 00229 #ifndef H5_NO_DEPRECATED_SYMBOLS 00230 00231 /* 00232 * The filter table maps filter identification numbers to structs that 00233 * contain a pointers to the filter function and timing statistics. 00234 */ 00235 typedef struct H5Z_class1_t { 00236 H5Z_filter_t id; /* Filter ID number */ 00237 const char *name; /* Comment for debugging */ 00238 H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */ 00239 H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */ 00240 H5Z_func_t filter; /* The actual filter function */ 00241 } H5Z_class1_t; 00242 00243 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 00244 00245 #ifdef __cplusplus 00246 } 00247 #endif 00248 #endif 00249