mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-23 16:20:57 +08:00
619ee863ed
Purpose:
New filter functionality
Rename section to reflect filters rather than strictly compression
Description:
"Compression Interface" --> "Filter and Compression Interface"
Renamed section as "Filter and Compression Interface".
Extended introductory paragraphs to BRIEFLY describe filter pipeline.
Edit H5Zregister to speak from point of view of filters rather than
compression only.
Add H5Zunregister.
Add H5Zfilter_avail.
Platforms tested:
Safari, IE 5
303 lines
10 KiB
HTML
303 lines
10 KiB
HTML
<html>
|
||
<head>
|
||
<title>
|
||
HDF5/H5Z API Specification
|
||
</title>
|
||
|
||
<!-- #BeginLibraryItem "/ed_libs/styles_RM.lbi" --><link href="ed_styles/RMelect.css" rel="stylesheet" type="text/css"><!-- #EndLibraryItem --></head>
|
||
|
||
<body bgcolor="#FFFFFF">
|
||
|
||
|
||
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
||
<center>
|
||
<table border=0 width=98%>
|
||
<tr><td valign=top align=left>
|
||
<a href="index.html">HDF5 documents and links</a> <br>
|
||
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
||
<a href="H5.user.html">HDF5 User Guide</a> <br>
|
||
<!--
|
||
<a href="Glossary.html">Glossary</a><br>
|
||
-->
|
||
</td>
|
||
<td valign=top align=right>
|
||
And in this document, the
|
||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||
<br>
|
||
<a href="RM_H5.html">H5</a>
|
||
<a href="RM_H5A.html">H5A</a>
|
||
<a href="RM_H5D.html">H5D</a>
|
||
<a href="RM_H5E.html">H5E</a>
|
||
<a href="RM_H5F.html">H5F</a>
|
||
<a href="RM_H5G.html">H5G</a>
|
||
<a href="RM_H5I.html">H5I</a>
|
||
<a href="RM_H5P.html">H5P</a>
|
||
<br>
|
||
<a href="RM_H5R.html">H5R</a>
|
||
<a href="RM_H5S.html">H5S</a>
|
||
<a href="RM_H5T.html">H5T</a>
|
||
<a href="RM_H5Z.html">H5Z</a>
|
||
<a href="Tools.html">Tools</a>
|
||
<a href="PredefDTypes.html">Datatypes</a>
|
||
</td></tr>
|
||
</table>
|
||
</center>
|
||
<hr>
|
||
<!-- #EndLibraryItem --><center>
|
||
<h1>H5Z: Filter and Compression Interface</h1>
|
||
</center>
|
||
|
||
<h2>Filter and Compression API Functions</h2>
|
||
|
||
These functions enable the user to configure new filters
|
||
for the local environment.
|
||
|
||
<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 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.
|
||
Compact dataset compression is not supported because it would not produce
|
||
significant results.
|
||
<p>
|
||
See <a href="Datasets.html"><cite>The Dataset Interface (H5D)</cite></a>
|
||
in the <cite>HDF5 User's Guide</cite> for further information regarding
|
||
data compression.
|
||
|
||
<hr>
|
||
<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_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 filter.
|
||
<dt><strong>Description:</strong>
|
||
<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>comment</code> is used for debugging and may be
|
||
the null pointer.
|
||
<p>
|
||
<code>function</code> is a user-defined function
|
||
which performs the action of the filter.
|
||
<p>
|
||
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> 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>)
|
||
(<em>unsigned int</em> <code>flags</code>,
|
||
<em>size_t</em> <code>cd_nelmts</code>,
|
||
<em>const unsigned int</em> <code>cd_values[]</code>,
|
||
<em>size_t</em> <code>nbytes</code>,
|
||
<em>size_t *</em><code>buf_size</code>,
|
||
<em>void **</em><code>buf</code>)
|
||
</dir>
|
||
|
||
<p>The parameters <code>flags</code>, <code>cd_nelmts</code>,
|
||
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 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
|
||
failure. If the transformation cannot be done in place,
|
||
then the filter should allocate a new buffer with
|
||
<code>malloc()</code> and assign it to <code>*buf</code>,
|
||
assigning the allocated size of that buffer to
|
||
<code>*buf_size</code>.
|
||
The old buffer should be freed by calling <code>free()</code>.
|
||
|
||
<dt><strong>Parameters:</strong>
|
||
<dl>
|
||
<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: Filter function.
|
||
</dl>
|
||
<dt><strong>Returns:</strong>
|
||
<dd>Returns a non-negative value if successful;
|
||
otherwise returns a negative value.
|
||
</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>. <20>
|
||
<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%>
|
||
<tr><td valign=top align=left>
|
||
<a href="index.html">HDF5 documents and links</a> <br>
|
||
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
||
<a href="H5.user.html">HDF5 User Guide</a> <br>
|
||
<!--
|
||
<a href="Glossary.html">Glossary</a><br>
|
||
-->
|
||
</td>
|
||
<td valign=top align=right>
|
||
And in this document, the
|
||
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
||
<br>
|
||
<a href="RM_H5.html">H5</a>
|
||
<a href="RM_H5A.html">H5A</a>
|
||
<a href="RM_H5D.html">H5D</a>
|
||
<a href="RM_H5E.html">H5E</a>
|
||
<a href="RM_H5F.html">H5F</a>
|
||
<a href="RM_H5G.html">H5G</a>
|
||
<a href="RM_H5I.html">H5I</a>
|
||
<a href="RM_H5P.html">H5P</a>
|
||
<br>
|
||
<a href="RM_H5R.html">H5R</a>
|
||
<a href="RM_H5S.html">H5S</a>
|
||
<a href="RM_H5T.html">H5T</a>
|
||
<a href="RM_H5Z.html">H5Z</a>
|
||
<a href="Tools.html">Tools</a>
|
||
<a href="PredefDTypes.html">Datatypes</a>
|
||
</td></tr>
|
||
</table>
|
||
</center>
|
||
<hr>
|
||
<!-- #EndLibraryItem -->
|
||
|
||
<!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
|
||
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
||
<br>
|
||
Describes HDF5 Release 1.5, Unreleased Development Branch
|
||
</address><!-- #EndLibraryItem -->
|
||
|
||
Last modified: 2 April 2003
|
||
|
||
</body>
|
||
</html>
|