[svn-r6611] Purpose:

    Code cleanup/new features

Description:
    Switch over to a new style for registering filters with the library -
instead passing in an ID, a string and a callback function to H5Zregister,
the client should pass in a single pointer to a H5Z_claass_t struct which
contains the ID, the description string and all the function callbacks as
fields.
    Added support for a new "can apply" callback for each filter, which is
called when a dataset is created to check whether the parameters for that
filter apply correctly to the combination of the datatype and the chunk size
(i.e. dataspace) for the dataset.
    Added support for a new "set local" callback for each filter, which
is called when a dataset is created (after the "can apply" filter callback)
and sets filter parameters that are specific to that particular dataset.
    Switched the filters we ship over to use the new H5Z_class_t struct for
their internal registrations and also added "set local" callbacks to the
szip and shuffle filters and a "can apply" callback to the szip filter.
    Lots of other code cleanups, etc. also


Solution:

Platforms tested:
    FreeBSD 4.8 (sleipnir) w/szip
    Linux 2.4 (sleipnir) w/szip
    Solaris 2.7 (arabica) w/FORTRAN
    IRIX64 6.5 (modi4) w/szip, FORTRAN & parallel

Misc. update:

1 files changed, 65 insertions, 4 deletions

diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h
index 237ab39..c455700 100644
--- a/src/H5Zpublic.h
+++ b/src/H5Zpublic.h
@@ -48,10 +48,12 @@ typedef int H5Z_filter_t;
 #define H5Z_FLAG_SKIP_EDC	0x0200	/*skip EDC filters for read	*/
 
 /* Special parameters for szip compression */
-#ifdef H5_HAVE_FILTER_SZIP
+/* [These are aliases for the similar definitions in szlib.h, which we can't
+ * include directly due to the duplication of various symbols with the zlib.h
+ * header file] */
 #define H5_SZIP_RAW_OPTION_MASK 128
 #define H5_SZIP_NN_OPTION_MASK   32
-#endif /* H5_HAVE_FILTER_SZIP */
+#define H5_SZIP_MAX_PIXELS_PER_BLOCK    32
 
 /* Values to decide if EDC is enabled for reading data */
 typedef enum H5Z_EDC_t {
@@ -84,6 +86,51 @@ extern "C" {
 #endif
 
 /*
+ * Before a dataset gets created, the "can_apply" callbacks for any filters used
+ * in the dataset creation property list are called
+ * with the dataset's dataset creation property list, the dataset's datatype and
+ * a dataspace describing a chunk (for chunked dataset storage).
+ * 
+ * The "can_apply" callback must determine if the combination of the dataset
+ * creation property list setting, the datatype and the dataspace represent a
+ * valid combination to apply this filter to.  For example, some cases of
+ * invalid combinations may involve the filter not operating correctly on
+ * certain datatypes (or certain datatype sizes), or certain sizes of the chunk
+ * dataspace.
+ * 
+ * The "can_apply" callback can be the NULL pointer, in which case, the library
+ * will assume that it can apply to any combination of dataset creation
+ * property list values, datatypes and dataspaces.
+ * 
+ * The "can_apply" callback returns positive a valid combination, zero for an
+ * invalid combination and negative for an error.
+ */
+typedef herr_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
+
+/*
+ * After the "can_apply" callbacks are checked for new datasets, the "set_local"
+ * callbacks for any filters used in the dataset creation property list are
+ * called.  These callbacks receive the dataset's private copy of the dataset
+ * creation property list passed in to H5Dcreate (i.e. not the actual property
+ * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate
+ * (which is not copied and should not be modified) and a dataspace describing
+ * the chunk (for chunked dataset storage) (which should also not be modified).
+ * 
+ * The "set_local" callback must set any parameters that are specific to this
+ * dataset, based on the combination of the dataset creation property list
+ * values, the datatype and the dataspace.  For example, some filters perform
+ * different actions based on different datatypes (or datatype sizes) or
+ * different number of dimensions or dataspace sizes.
+ * 
+ * The "set_local" callback can be the NULL pointer, in which case, the library
+ * will assume that there are no dataset-specific settings for this filter.
+ * 
+ * The "set_local" callback must return non-negative on success and negative
+ * for an error.
+ */
+typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
+
+/*
  * A filter gets definition flags and invocation flags (defined above), the
  * client data array and size defined when the filter was added to the
  * pipeline, the size in bytes of the data on which to operate, and pointers
@@ -102,11 +149,25 @@ typedef 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);
 
+/*
+ * The filter table maps filter identification numbers to structs that
+ * contain a pointers to the filter function and timing statistics.
+ */
+typedef struct H5Z_class_t {
+    H5Z_filter_t id;		/* Filter ID number			     */
+    const char	*name;		/* Comment for debugging		     */
+    H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */
+    H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */
+    H5Z_func_t filter;		/* The actual filter function		     */
+} H5Z_class_t;
+
+#ifdef H5_WANT_H5_V1_4_COMPAT
 H5_DLL herr_t H5Zregister(H5Z_filter_t id, const char *comment,
 			   H5Z_func_t filter);
-
+#else /* H5_WANT_H5_V1_4_COMPAT */
+H5_DLL herr_t H5Zregister(const H5Z_class_t *cls);
+#endif /* H5_WANT_H5_V1_4_COMPAT */
 H5_DLL herr_t H5Zunregister(H5Z_filter_t id);
-
 H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id);