H5Zpublic.h

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