HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
H5Zpublic.h
Go to the documentation of this file.
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 
46 #define H5Z_FILTER_MAX 65535 /*maximum filter id */
47 
48 /* General macros */
49 #define H5Z_FILTER_ALL 0 /* Symbol to remove all filters in H5Premove_filter */
50 #define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */
51  /* (should probably be allowed to be an
52  * unlimited amount, but currently each
53  * filter uses a bit in a 32-bit field,
54  * so the format would have to be
55  * changed to accomodate that)
56  */
57 
58 /* Flags for filter definition (stored) */
59 #define H5Z_FLAG_DEFMASK 0x00ff /*definition flag mask */
60 #define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory */
61 #define H5Z_FLAG_OPTIONAL 0x0001 /*filter is optional */
62 
63 /* Additional flags for filter invocation (not stored) */
64 #define H5Z_FLAG_INVMASK 0xff00 /*invocation flag mask */
65 #define H5Z_FLAG_REVERSE 0x0100 /*reverse direction; read */
66 #define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read */
67 
68 /* Special parameters for szip compression */
69 /* [These are aliases for the similar definitions in szlib.h, which we can't
70  * include directly due to the duplication of various symbols with the zlib.h
71  * header file] */
72 #define H5_SZIP_ALLOW_K13_OPTION_MASK 1
73 #define H5_SZIP_CHIP_OPTION_MASK 2
74 #define H5_SZIP_EC_OPTION_MASK 4
75 #define H5_SZIP_NN_OPTION_MASK 32
76 #define H5_SZIP_MAX_PIXELS_PER_BLOCK 32
77 
78 /* Macros for the shuffle filter */
79 #define H5Z_SHUFFLE_USER_NPARMS 0 /* Number of parameters that users can set */
80 #define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */
81 
82 /* Macros for the szip filter */
83 #define H5Z_SZIP_USER_NPARMS 2 /* Number of parameters that users can set */
84 #define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */
85 #define H5Z_SZIP_PARM_MASK 0 /* "User" parameter for option mask */
86 #define H5Z_SZIP_PARM_PPB 1 /* "User" parameter for pixels-per-block */
87 #define H5Z_SZIP_PARM_BPP 2 /* "Local" parameter for bits-per-pixel */
88 #define H5Z_SZIP_PARM_PPS 3 /* "Local" parameter for pixels-per-scanline */
89 
90 /* Macros for the nbit filter */
91 #define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */
92 
93 /* Macros for the scale offset filter */
94 #define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */
95 
96 
97 /* Special parameters for ScaleOffset filter*/
98 #define H5Z_SO_INT_MINBITS_DEFAULT 0
99 typedef enum H5Z_SO_scale_type_t {
104 
105 /* Current version of the H5Z_class_t struct */
106 #define H5Z_CLASS_T_VERS (1)
107 
108 /* Values to decide if EDC is enabled for reading data */
109 typedef enum H5Z_EDC_t {
110  H5Z_ERROR_EDC = -1, /* error value */
113  H5Z_NO_EDC = 2 /* must be the last */
114 } H5Z_EDC_t;
115 
116 /* Bit flags for H5Zget_filter_info */
117 #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001)
118 #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002)
119 
120 /* Return values for filter callback function */
121 typedef enum H5Z_cb_return_t {
123  H5Z_CB_FAIL = 0, /* I/O should fail if filter fails. */
124  H5Z_CB_CONT = 1, /* I/O continues if filter fails. */
127 
128 /* Filter callback function definition */
130  size_t buf_size, void* op_data);
131 
132 /* Structure for filter callback property */
133 typedef struct H5Z_cb_t {
135  void* op_data;
136 } H5Z_cb_t;
137 
138 #ifdef __cplusplus
139 extern "C" {
140 #endif
141 
142 /*
143  * Before a dataset gets created, the "can_apply" callbacks for any filters used
144  * in the dataset creation property list are called
145  * with the dataset's dataset creation property list, the dataset's datatype and
146  * a dataspace describing a chunk (for chunked dataset storage).
147  *
148  * The "can_apply" callback must determine if the combination of the dataset
149  * creation property list setting, the datatype and the dataspace represent a
150  * valid combination to apply this filter to. For example, some cases of
151  * invalid combinations may involve the filter not operating correctly on
152  * certain datatypes (or certain datatype sizes), or certain sizes of the chunk
153  * dataspace.
154  *
155  * The "can_apply" callback can be the NULL pointer, in which case, the library
156  * will assume that it can apply to any combination of dataset creation
157  * property list values, datatypes and dataspaces.
158  *
159  * The "can_apply" callback returns positive a valid combination, zero for an
160  * invalid combination and negative for an error.
161  */
162 typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
163 
164 /*
165  * After the "can_apply" callbacks are checked for new datasets, the "set_local"
166  * callbacks for any filters used in the dataset creation property list are
167  * called. These callbacks receive the dataset's private copy of the dataset
168  * creation property list passed in to H5Dcreate (i.e. not the actual property
169  * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate
170  * (which is not copied and should not be modified) and a dataspace describing
171  * the chunk (for chunked dataset storage) (which should also not be modified).
172  *
173  * The "set_local" callback must set any parameters that are specific to this
174  * dataset, based on the combination of the dataset creation property list
175  * values, the datatype and the dataspace. For example, some filters perform
176  * different actions based on different datatypes (or datatype sizes) or
177  * different number of dimensions or dataspace sizes.
178  *
179  * The "set_local" callback can be the NULL pointer, in which case, the library
180  * will assume that there are no dataset-specific settings for this filter.
181  *
182  * The "set_local" callback must return non-negative on success and negative
183  * for an error.
184  */
185 typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
186 
187 /*
188  * A filter gets definition flags and invocation flags (defined above), the
189  * client data array and size defined when the filter was added to the
190  * pipeline, the size in bytes of the data on which to operate, and pointers
191  * to a buffer and its allocated size.
192  *
193  * The filter should store the result in the supplied buffer if possible,
194  * otherwise it can allocate a new buffer, freeing the original. The
195  * allocated size of the new buffer should be returned through the BUF_SIZE
196  * pointer and the new buffer through the BUF pointer.
197  *
198  * The return value from the filter is the number of bytes in the output
199  * buffer. If an error occurs then the function should return zero and leave
200  * all pointer arguments unchanged.
201  */
202 typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts,
203  const unsigned int cd_values[], size_t nbytes,
204  size_t *buf_size, void **buf);
205 
206 /*
207  * The filter table maps filter identification numbers to structs that
208  * contain a pointers to the filter function and timing statistics.
209  */
210 typedef struct H5Z_class2_t {
211  int version; /* Version number of the H5Z_class_t struct */
212  H5Z_filter_t id; /* Filter ID number */
213  unsigned encoder_present; /* Does this filter have an encoder? */
214  unsigned decoder_present; /* Does this filter have a decoder? */
215  const char *name; /* Comment for debugging */
216  H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */
217  H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */
218  H5Z_func_t filter; /* The actual filter function */
219 } H5Z_class2_t;
220 
221 H5_DLL herr_t H5Zregister(const void *cls);
224 H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags);
225 
226 /* Symbols defined for compatibility with previous versions of the HDF5 API.
227  *
228  * Use of these symbols is deprecated.
229  */
230 #ifndef H5_NO_DEPRECATED_SYMBOLS
231 
232 /*
233  * The filter table maps filter identification numbers to structs that
234  * contain a pointers to the filter function and timing statistics.
235  */
236 typedef struct H5Z_class1_t {
237  H5Z_filter_t id; /* Filter ID number */
238  const char *name; /* Comment for debugging */
239  H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */
240  H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */
241  H5Z_func_t filter; /* The actual filter function */
242 } H5Z_class1_t;
243 
244 #endif /* H5_NO_DEPRECATED_SYMBOLS */
245 
246 #ifdef __cplusplus
247 }
248 #endif
249 #endif
250 
H5_DLL herr_t H5Zregister(const void *cls)
H5Z_func_t filter
Definition: H5Zpublic.h:218
H5Z_filter_t id
Definition: H5Zpublic.h:237
H5Z_set_local_func_t set_local
Definition: H5Zpublic.h:240
#define H5_DLL
Definition: H5api_adpt.h:406
int herr_t
Definition: H5public.h:107
GLbitfield flags
Definition: glcorearb.h:1595
htri_t(* H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id)
Definition: H5Zpublic.h:162
H5Z_SO_scale_type_t
Definition: H5Zpublic.h:99
H5Z_EDC_t
Definition: H5Zpublic.h:109
H5Z_func_t filter
Definition: H5Zpublic.h:241
H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags)
const char * name
Definition: H5Zpublic.h:238
herr_t(* H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id)
Definition: H5Zpublic.h:185
H5Z_filter_func_t func
Definition: H5Zpublic.h:134
H5Z_cb_return_t
Definition: H5Zpublic.h:121
H5_DLL herr_t H5Zunregister(H5Z_filter_t id)
int hid_t
Definition: H5Ipublic.h:56
H5Z_can_apply_func_t can_apply
Definition: H5Zpublic.h:216
H5Z_cb_return_t(* H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data)
Definition: H5Zpublic.h:129
unsigned encoder_present
Definition: H5Zpublic.h:213
struct H5Z_class2_t H5Z_class2_t
GLenum GLuint GLenum GLsizei const GLchar * buf
Definition: glcorearb.h:2539
H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id)
H5Z_can_apply_func_t can_apply
Definition: H5Zpublic.h:239
H5Z_set_local_func_t set_local
Definition: H5Zpublic.h:217
size_t(* H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, void **buf)
Definition: H5Zpublic.h:202
void * op_data
Definition: H5Zpublic.h:135
int H5Z_filter_t
Definition: H5Zpublic.h:33
struct H5Z_cb_t H5Z_cb_t
unsigned decoder_present
Definition: H5Zpublic.h:214
int htri_t
Definition: H5public.h:126
struct H5Z_class1_t H5Z_class1_t
const char * name
Definition: H5Zpublic.h:215
GLint GLint GLint GLint GLint GLint GLint GLbitfield GLenum filter
Definition: glcorearb.h:1296
H5Z_filter_t id
Definition: H5Zpublic.h:212