diff options
Diffstat (limited to 'doc/html/RM_H5Z.html')
| -rw-r--r-- | doc/html/RM_H5Z.html | 172 |
1 files changed, 138 insertions, 34 deletions
diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index e53146c..333d394 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -44,32 +44,52 @@ And in this document, the </center> <hr> <!-- #EndLibraryItem --><center> -<h1>H5Z: Compression Interface</h1> +<h1>H5Z: Filter and Compression Interface</h1> </center> -<h2>Compression API Functions</h2> +<h2>Filter and Compression API Functions</h2> -This function enable the user to configure a new compression -method for the local environment. +These functions enable the user to configure new filters +for the local environment. -<table border=0> +<table border=0 width=80%> <tr><td valign=top> <ul> <li><a href="#Compression-Register">H5Zregister</a> </ul> </td><td> </td><td valign=top> <ul> - + <li><a href="#Compression-Unregister">H5Zunregister</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Compression-FilterAvail">H5Zfilter_avail</a> </ul> </td></tr> </table> <p> -HDF5 supports compression of raw data by compression methods -built into the library or defined by an application. -A compression method is associated with a dataset when the dataset is -created and is applied independently to each storage chunk of the dataset. -The dataset must use the <code>H5D_CHUNKED</code> storage layout. +HDF5 supports a filter pipeline that provides the capability for standard +and customized raw data processing during I/O operations. +HDF5 is distributed with a small set of standard filters such as +compression (gzip and a shuffling algorithm) and +error checking (Fletcher32 checksum). +For further flexibility, the library includes tools enabling a +user application to extend the pipeline through the +creation and registration of customized filters. +<p> +As mentioned above, one set of filters distributed with HDF5 provides +built-in methods for raw data compression. +The flexibility of the filter pipeline implementation enables the +definition of additional compression methods by a user application. +A compression method<br> + — + is associated with a dataset when the dataset is created,<br> + — + can be used only with chunked data (ie., datasets stored in the + <code>H5D_CHUNKED</code> storage layout), and<br> + — + is applied independently to each chunk of the dataset. <p> The HDF5 library does not support compression for contiguous datasets because of the difficulty of implementing random access for partial I/O. @@ -84,28 +104,42 @@ data compression. <dl> <dt><strong>Name:</strong> <a name="Compression-Register">H5Zregister</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Zregister</code>(<em>H5Z_method_t</em> <code>method</code>, - <em>const char *</em><code>name</code>, + <dd><em>herr_t</em> <code>H5Zregister</code>(<em>H5Z_filter_t</em> <code>filter</code>, + <em>const char *</em><code>comment</code>, <em>H5Z_func_t</em> <code>function</code> ) <dt><strong>Purpose:</strong> - <dd> Registers new compression / uncompression function. + <dd> Registers new filter. <dt><strong>Description:</strong> - <dd><code>H5Zregister</code> registers a new compression / uncompression - function for the compression method specified by - the method number, <code>method</code>. + <dd><code>H5Zregister</code> registers a new filter with the + HDF5 library. + <p> + Making a new filter available to an application is a two-step + process. The first step is to <span class="termEmphasis">define</span> + the new filter <code>function</code> as described below. + This step can be skipped only when the filter is predifined, as is + the case with the Fletcher32 checksum and shuffle filters that + are distributed with the HDF5 Library. + This call to <code>H5Zregister</code>, + <span class="termEmphasis">registering</span> the filter with the + library, is the second step. + <p> + The new filter is specified by the filter identifier + <code>filter</code>. <p> - <code>name</code> is used for debugging and may be the null pointer. + <code>comment</code> is used for debugging and may be + the null pointer. <p> - <code>function</code> is a user-defined function providing both - compression and uncompression; it may be the null pointer. + <code>function</code> is a user-defined function + which performs the action of the filter. <p> - The statistics associated with a method number are not reset + The statistics associated with a filter are not reset by this function; they accumulate over the life of the library. - <p><strong>New filters</strong> are defined in two phases. Before a filter can be - linked into the application with <code>H5Zregister</code>, - <code>H5Z_func_t</code> must first be defined as follows: + <p><strong>New filters.</strong> Before a filter can be + linked into an application with <code>H5Zregister</code>, + the filter must be defined as described in the HDF5 Library + header file <code>H5Zpublic.h</code>: <dir> <em>typedef size_t</em> (*<code>H5Z_func_t</code>) @@ -118,12 +152,12 @@ data compression. </dir> <p>The parameters <code>flags</code>, <code>cd_nelmts</code>, - and <code>cd_values</code> are the same as for the - <code>H5Pset_filter()</code> function. + and <code>cd_values</code> are the same as for the function + <code>H5Pset_filter</code>. The additional flag <code>H5Z_FLAG_REVERSE</code> is set when the filter is called as part of the input pipeline. The parameter <code>*buf</code> points to the input buffer - which has a total size of <code>*buf_size</code> bytes, + which has a size of <code>*buf_size</code> bytes, <code>nbytes</code> of which are valid data. <p>The filter should perform the transformation in place if possible and return the number of valid bytes or zero for @@ -136,13 +170,14 @@ data compression. <dt><strong>Parameters:</strong> <dl> - <dt><em>H5Z_method_t</em> <code>method</code> - <dd>IN: Number specifying compression method. - <dt><em>const char *</em><code>name</code> - <dd>IN: Name associated with the method number. - Used for debugging purposes only. + <dt><em>H5Z_filter_t</em> <code>method</code> + <dd>IN: Filter identifier. + <dt><em>const char *</em><code>comment</code> + <dd>IN: String associated with the filter; + used for debugging purposes only. + May be the null pointer. <dt><em>H5Z_func_t</em> <code>function</code> - <dd>IN: Compression / uncompression method. + <dd>IN: Filter function. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; @@ -150,6 +185,75 @@ data compression. </dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Compression-Unregister">H5Zunregister</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Zunregister</code>(<em>H5Z_filter_t</em> <code>filter</code>) + <dt><strong>Purpose:</strong> + <dd>Unregisters a filter. + <dt><strong>Description:</strong> + <dd><code>H5Zunregister</code> unregisters the filter + specified in <code>filter</code>. + <p> + After a call to <code>H5Zunregister</code>, the filter + specified in <code>filter</code> will no longer be + available to the application. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>H5Z_filter_t</em> <code>filter</code> + <dd>IN: Identifier of the filter to be unregistered. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. + <!-- + <dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5p_FORTRAN.html#h5pget_nfilters_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + --> <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Compression-FilterAvail">H5Zfilter_avail</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Zfilter_avail</code>(<em>H5Z_filter_t</em> <code>filter</code>) + <dt><strong>Purpose:</strong> + <dd>Determines whether a filter is available. + <dt><strong>Description:</strong> + <dd><code>H5Zfilter_avail</code> determines whether the filter + specified in <code>filter</code> is available to the application. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>H5Z_filter_t</em> <code>filter</code> + <dd>IN: Filter identifier. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. + <!-- + <dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5p_FORTRAN.html#h5pget_nfilters_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + --> <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> + + + + + + + + <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> <table border=0 width=98%> @@ -192,7 +296,7 @@ And in this document, the Describes HDF5 Release 1.5, Unreleased Development Branch </address><!-- #EndLibraryItem --> -Last modified: 11 February 2003 +Last modified: 2 April 2003 </body> </html> |