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