1998-07-15 12:51:50 +08:00
|
|
|
|
<html>
|
2002-07-06 05:13:15 +08:00
|
|
|
|
<head>
|
|
|
|
|
|
<title>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
HDF5/H5Z API Specification
|
2002-07-06 05:13:15 +08:00
|
|
|
|
</title>
|
2003-03-15 03:12:34 +08:00
|
|
|
|
|
2003-07-03 05:28:11 +08:00
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/styles_RM.lbi" -->
|
|
|
|
|
|
|
|
|
|
|
|
<!--
|
|
|
|
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
|
|
|
|
* Copyright by the Board of Trustees of the University of Illinois. *
|
|
|
|
|
|
* All rights reserved. *
|
|
|
|
|
|
* *
|
|
|
|
|
|
* This file is part of HDF5. The full HDF5 copyright notice, including *
|
|
|
|
|
|
* terms governing use, modification, and redistribution, is contained in *
|
|
|
|
|
|
* the files COPYING and Copyright.html. COPYING can be found at the root *
|
|
|
|
|
|
* of the source code distribution tree; Copyright.html can be found at the *
|
|
|
|
|
|
* root level of an installed copy of the electronic HDF5 document set and *
|
|
|
|
|
|
* is linked from the top-level documents page. It can also be found at *
|
|
|
|
|
|
* http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have *
|
|
|
|
|
|
* access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
|
|
|
|
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
|
|
|
|
-->
|
|
|
|
|
|
|
|
|
|
|
|
<link href="ed_styles/RMelect.css" rel="stylesheet" type="text/css">
|
|
|
|
|
|
<!-- #EndLibraryItem --></head>
|
1998-07-15 12:51:50 +08:00
|
|
|
|
|
1998-12-22 06:52:56 +08:00
|
|
|
|
<body bgcolor="#FFFFFF">
|
2003-10-08 03:56:17 +08:00
|
|
|
|
<!-- HEADER RIGHT " " -->
|
1998-12-22 06:52:56 +08:00
|
|
|
|
|
1998-07-15 12:51:50 +08:00
|
|
|
|
|
2003-03-15 03:12:34 +08:00
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<center>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
<table border=0 width=98%>
|
|
|
|
|
|
<tr><td valign=top align=left>
|
2003-03-15 03:12:34 +08:00
|
|
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
2003-07-04 03:40:03 +08:00
|
|
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
<!--
|
|
|
|
|
|
<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>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<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>
|
1998-10-30 06:13:17 +08:00
|
|
|
|
<a href="RM_H5I.html">H5I</a>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<a href="RM_H5P.html">H5P</a>
|
2000-12-13 06:43:02 +08:00
|
|
|
|
<br>
|
1998-10-30 06:13:17 +08:00
|
|
|
|
<a href="RM_H5R.html">H5R</a>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<a href="RM_H5S.html">H5S</a>
|
|
|
|
|
|
<a href="RM_H5T.html">H5T</a>
|
2003-03-15 03:12:34 +08:00
|
|
|
|
<a href="RM_H5Z.html">H5Z</a>
|
1998-09-12 00:00:43 +08:00
|
|
|
|
<a href="Tools.html">Tools</a>
|
2000-12-13 06:43:02 +08:00
|
|
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
</td></tr>
|
|
|
|
|
|
</table>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
</center>
|
2004-02-25 06:10:12 +08:00
|
|
|
|
<hr><!-- #EndLibraryItem --><center>
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<h1>H5Z: Filter and Compression Interface</h1>
|
1998-07-15 12:51:50 +08:00
|
|
|
|
</center>
|
|
|
|
|
|
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<h2>Filter and Compression API Functions</h2>
|
1998-07-15 12:51:50 +08:00
|
|
|
|
|
2003-04-03 05:03:57 +08:00
|
|
|
|
These functions enable the user to configure new filters
|
|
|
|
|
|
for the local environment.
|
1998-07-15 12:51:50 +08:00
|
|
|
|
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<table border=0 width=80%>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
<tr><td valign=top width="30%">
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<ul>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
<li><a href="#Compression-FilterAvail">H5Zfilter_avail</a><br>
|
|
|
|
|
|
<li><a href="#Compression-GetFilterInfo">H5Zget_filter_info</a>
|
1998-07-15 12:51:50 +08:00
|
|
|
|
</ul>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
</td><td> </td><td valign=top width="30%">
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<ul>
|
2003-06-10 23:38:46 +08:00
|
|
|
|
<li><a href="#Compression-Register">H5Zregister</a>
|
2003-04-03 05:03:57 +08:00
|
|
|
|
</ul>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
</td><td> </td><td valign=top width="30%">
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<ul>
|
2003-06-10 23:38:46 +08:00
|
|
|
|
<li><a href="#Compression-Unregister">H5Zunregister</a>
|
1998-07-15 12:51:50 +08:00
|
|
|
|
</ul>
|
|
|
|
|
|
</td></tr>
|
|
|
|
|
|
</table>
|
|
|
|
|
|
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<br>
|
|
|
|
|
|
<strong>The FORTRAN90 Interfaces:</strong>
|
|
|
|
|
|
<br>
|
|
|
|
|
|
In general, each FORTRAN90 subroutine performs exactly the same task
|
|
|
|
|
|
as the corresponding C function.
|
|
|
|
|
|
<br>
|
|
|
|
|
|
|
|
|
|
|
|
<table border=0 width=80%>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
<tr><td valign=top width="30%">
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<ul>
|
|
|
|
|
|
<li><a href="#Compression-FilterAvail">h5zfilter_avail_f</a>
|
|
|
|
|
|
</ul>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
</td><td> </td><td valign=top width="30%">
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<ul>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
<!--<li><a href="#Compression-Register">h5zregister_f</a><br> -->
|
|
|
|
|
|
<li><a href="#Compression-GetFilterInfo">h5zget_filter_info_f</a>
|
2003-10-24 06:05:50 +08:00
|
|
|
|
</ul>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
</td><td> </td><td valign=top width="30%">
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<ul>
|
|
|
|
|
|
<li><a href="#Compression-Unregister">h5zunregister_f</a>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
</td></tr>
|
|
|
|
|
|
</table>
|
|
|
|
|
|
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<p>
|
2003-04-03 05:03:57 +08:00
|
|
|
|
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
|
2004-07-03 06:03:17 +08:00
|
|
|
|
compression (gzip, SZIP, and a shuffling algorithm) and
|
2003-04-03 05:03:57 +08:00
|
|
|
|
error checking (Fletcher32 checksum).
|
2003-06-24 04:32:50 +08:00
|
|
|
|
For further flexibility, the library allows a
|
2003-04-03 05:03:57 +08:00
|
|
|
|
user application to extend the pipeline through the
|
|
|
|
|
|
creation and registration of customized filters.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The flexibility of the filter pipeline implementation enables the
|
2003-06-24 04:32:50 +08:00
|
|
|
|
definition of additional filters by a user application.
|
2004-07-03 06:03:17 +08:00
|
|
|
|
A filter
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>is associated with a dataset when the dataset is created,
|
|
|
|
|
|
<li>can be used only with chunked data
|
2004-09-15 04:43:25 +08:00
|
|
|
|
<br>(i.e., datasets stored in the <code>H5D_CHUNKED</code>
|
|
|
|
|
|
storage layout), and
|
2004-07-03 06:03:17 +08:00
|
|
|
|
<li>is applied independently to each chunk of the dataset.
|
|
|
|
|
|
</ul>
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<p>
|
2003-06-24 04:32:50 +08:00
|
|
|
|
The HDF5 library does not support filters for contiguous datasets
|
1998-07-15 12:51:50 +08:00
|
|
|
|
because of the difficulty of implementing random access for partial I/O.
|
2003-06-24 04:32:50 +08:00
|
|
|
|
Compact dataset filters are not supported because it would not produce
|
1998-07-15 12:51:50 +08:00
|
|
|
|
significant results.
|
|
|
|
|
|
<p>
|
2004-07-03 06:03:17 +08:00
|
|
|
|
Filter identifiers for the filters distributed with the HDF5 Library
|
|
|
|
|
|
are as follows:
|
|
|
|
|
|
<table align=center border=0>
|
|
|
|
|
|
<tr valign=top align=left>
|
|
|
|
|
|
<td>
|
2004-12-29 22:26:20 +08:00
|
|
|
|
<code>H5Z_FILTER_DEFLATE</code></td><td>The gzip compression,
|
2004-07-03 06:03:17 +08:00
|
|
|
|
or deflation, filter
|
|
|
|
|
|
</td></tr><tr><td>
|
|
|
|
|
|
<code>H5Z_FILTER_SZIP</code></td><td>The SZIP compression filter
|
|
|
|
|
|
</td></tr><tr><td>
|
|
|
|
|
|
<code>H5Z_FILTER_SHUFFLE</code></td><td>The shuffle algorithm filter
|
|
|
|
|
|
</td></tr><tr><td>
|
2004-12-29 22:26:20 +08:00
|
|
|
|
<code>H5Z_FILTER_FLETCHER32 </code></td><td>The Fletcher32 checksum,
|
2004-07-03 06:03:17 +08:00
|
|
|
|
or error checking, filter
|
|
|
|
|
|
</td></tr>
|
|
|
|
|
|
</table>
|
2004-12-29 22:26:20 +08:00
|
|
|
|
Custom filters that have been registered with the library will have
|
2004-07-03 06:03:17 +08:00
|
|
|
|
additional unique identifiers.
|
|
|
|
|
|
<p>
|
2000-09-08 23:35:39 +08:00
|
|
|
|
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.
|
1998-07-15 12:51:50 +08:00
|
|
|
|
|
2003-10-08 03:56:17 +08:00
|
|
|
|
<!-- NEW PAGE -->
|
2004-12-29 22:26:20 +08:00
|
|
|
|
<!-- HEADER RIGHT " " -->
|
2003-10-08 03:56:17 +08:00
|
|
|
|
<!-- NEW PAGE -->
|
|
|
|
|
|
<!-- HEADER RIGHT "H5Zfilter_avail" -->
|
|
|
|
|
|
<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>
|
2004-02-25 06:10:12 +08:00
|
|
|
|
<ul><table>
|
|
|
|
|
|
<tr>
|
|
|
|
|
|
<td valign="top"><em>H5Z_filter_t</em> <code>filter </code></td>
|
2004-07-03 06:03:17 +08:00
|
|
|
|
<td valign="top">IN: Filter identifier.
|
|
|
|
|
|
See the introduction to this section of the reference manual
|
2004-09-03 07:00:33 +08:00
|
|
|
|
for a list of valid filter identifiers.</td></tr>
|
2004-02-25 06:10:12 +08:00
|
|
|
|
</table></ul>
|
2003-10-08 03:56:17 +08:00
|
|
|
|
<dt><strong>Returns:</strong>
|
|
|
|
|
|
<dd>Returns a non-negative value if successful;
|
|
|
|
|
|
otherwise returns a negative value.
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<dt><strong>Fortran90 Interface:</strong> h5zfilter_avail_f
|
|
|
|
|
|
<dd>
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
SUBROUTINE h5zfilter_avail_f(filter, status, hdferr)
|
|
|
|
|
|
IMPLICIT NONE
|
2003-10-25 05:16:16 +08:00
|
|
|
|
INTEGER, INTENT(IN) :: filter ! Filter
|
|
|
|
|
|
! Valid values are:
|
2003-10-24 06:05:50 +08:00
|
|
|
|
! H5Z_FILTER_DEFLATE_F
|
|
|
|
|
|
! H5Z_FILTER_SHUFFLE_F
|
|
|
|
|
|
! H5Z_FILTER_FLETCHER32_F
|
2004-07-03 06:03:17 +08:00
|
|
|
|
! H5Z_FILTER_SZIP_F
|
2003-10-25 05:16:16 +08:00
|
|
|
|
LOGICAL, INTENT(OUT) :: status ! Flag indicating whether
|
2004-07-03 06:03:17 +08:00
|
|
|
|
! filter is available:
|
2003-10-25 05:16:16 +08:00
|
|
|
|
! .TRUE.
|
|
|
|
|
|
! .FALSE.
|
2003-10-24 06:05:50 +08:00
|
|
|
|
END SUBROUTINE h5zfilter_avail_f
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
|
|
|
|
<dd>
|
|
|
|
|
|
|
2003-10-08 03:56:17 +08:00
|
|
|
|
<img src="Graphics/Java.gif">
|
|
|
|
|
|
<img src="Graphics/C++.gif">
|
|
|
|
|
|
-->
|
|
|
|
|
|
</dl>
|
2003-04-09 05:33:50 +08:00
|
|
|
|
|
2004-09-03 07:00:33 +08:00
|
|
|
|
|
|
|
|
|
|
<!-- NEW PAGE -->
|
|
|
|
|
|
<!-- HEADER RIGHT "H5Zget_filter_info" -->
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
<dl>
|
|
|
|
|
|
<dt><strong>Name:</strong> <a name="Compression-GetFilterInfo">H5Zget_filter_info</a>
|
|
|
|
|
|
<dt><strong>Signature:</strong>
|
|
|
|
|
|
<dd><em>herr_t</em>
|
|
|
|
|
|
<code>H5Zget_filter_info</code>(
|
|
|
|
|
|
<em>H5Z_filter_t</em> <code>filter</code>,
|
|
|
|
|
|
<em>unsigned int *</em><code>filter_config_flags</code>
|
|
|
|
|
|
)
|
|
|
|
|
|
<dt><strong>Purpose:</strong>
|
|
|
|
|
|
<dd>Retrieves information about a filter.
|
|
|
|
|
|
<dt><strong>Description:</strong>
|
|
|
|
|
|
<dd>
|
|
|
|
|
|
<code>H5Zget_filter_info</code> retrieves information about a filter.
|
|
|
|
|
|
At present, this means that the function retrieves a
|
|
|
|
|
|
filter's configuration flags, indicating whether the filter is
|
|
|
|
|
|
configured to decode data, to encode data, neither, or both.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
If <code>filter_config_flags</code> is not set to <small>NULL</small>
|
|
|
|
|
|
prior to the function call, the returned parameter contains a
|
|
|
|
|
|
bit field specifying the available filter configuration.
|
|
|
|
|
|
The configuration flag values can then be determined through
|
|
|
|
|
|
a series of bitwise <small>AND</small> operations, as described below.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Valid filter configuration flags include the following:
|
|
|
|
|
|
<table>
|
|
|
|
|
|
<tr><td><code> </code></td>
|
|
|
|
|
|
<td><code>H5Z_FILTER_CONFIG_ENCODE_ENABLED</code></td>
|
|
|
|
|
|
<td>Encoding is enabled for this filter
|
|
|
|
|
|
</td></tr>
|
|
|
|
|
|
<tr><td> </td>
|
|
|
|
|
|
<td><code>H5Z_FILTER_CONFIG_DECODE_ENABLED</code> </td>
|
|
|
|
|
|
<td>Decoding is enabled for this filter
|
|
|
|
|
|
</td></tr>
|
|
|
|
|
|
<tr><td> </td>
|
|
|
|
|
|
<td colspan="2" align="right"><small>(These flags
|
|
|
|
|
|
are defined in the HDF5 Library source code file
|
|
|
|
|
|
<code>H5Zpublic.h</code>.)</small>
|
|
|
|
|
|
</td></tr>
|
|
|
|
|
|
</table>
|
|
|
|
|
|
A bitwise <small>AND</small> of the returned
|
|
|
|
|
|
<code>filter_config_flags</code> and a valid
|
|
|
|
|
|
filter configuration flag will reveal whether
|
|
|
|
|
|
the related configuration option is available.
|
|
|
|
|
|
For example, if the value of
|
|
|
|
|
|
<br>
|
|
|
|
|
|
<code>
|
|
|
|
|
|
H5Z_FILTER_CONFIG_ENCODE_ENABLED
|
|
|
|
|
|
&
|
|
|
|
|
|
filter_config_flags</code>
|
|
|
|
|
|
<br>
|
|
|
|
|
|
is true, i.e., greater than <code>0</code> (zero),
|
|
|
|
|
|
the queried filter is configured to encode data;
|
|
|
|
|
|
if the value is <code>FALSE</code>,
|
|
|
|
|
|
i.e., equal to <code>0</code> (zero),
|
|
|
|
|
|
the filter is not so configured.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
If a filter is not encode-enabled, the corresponding
|
|
|
|
|
|
<code>H5Pset_*</code> function will return an error if the
|
|
|
|
|
|
filter is added to a dataset creation property list (which is
|
|
|
|
|
|
required if the filter is to be used to encode that dataset).
|
|
|
|
|
|
For example, if the <code>H5Z_FILTER_CONFIG_ENCODE_ENABLED</code>
|
|
|
|
|
|
flag is not returned for the SZIP filter,
|
|
|
|
|
|
<code>H5Z_FILTER_SZIP</code>, a call to <code>H5Pset_szip</code>
|
|
|
|
|
|
will fail.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
If a filter is not decode-enabled, the application will not be
|
|
|
|
|
|
able to read an existing file encoded with that filter.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
This function should be called, and the returned
|
|
|
|
|
|
<code>filter_config_flags</code> analyzed, before calling
|
|
|
|
|
|
any other function, such as <code>H5Pset_szip</code>,
|
|
|
|
|
|
that might require a particular filter configuration.
|
|
|
|
|
|
|
|
|
|
|
|
<dt><strong>Parameters:</strong>
|
|
|
|
|
|
<dl>
|
|
|
|
|
|
<dt><em>H5Z_filter_t</em> <code>filter</code>
|
|
|
|
|
|
<dd>IN: Identifier of the filter to query.
|
|
|
|
|
|
See the introduction to this section of the reference manual
|
|
|
|
|
|
for a list of valid filter identifiers.
|
|
|
|
|
|
<dt><em>unsigned int *</em><code>filter_config_flags</code>
|
|
|
|
|
|
<dd>OUT: A bit field encoding the returned filter information
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
<dt><strong>Returns:</strong>
|
|
|
|
|
|
<dd>Returns a non-negative value on success,
|
|
|
|
|
|
a negative value on failure.
|
|
|
|
|
|
|
2004-12-29 22:26:20 +08:00
|
|
|
|
<!-- NEW PAGE -->
|
|
|
|
|
|
<dt><strong>Fortran90 Interface:</strong>
|
2004-09-03 07:00:33 +08:00
|
|
|
|
<dd>
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
SUBROUTINE h5zget_filter_info_f(filter, config_flags, hdferr)
|
|
|
|
|
|
|
|
|
|
|
|
IMPLICIT NONE
|
|
|
|
|
|
INTEGER, INTENT(IN) :: filter ! Filter, may be one of the
|
|
|
|
|
|
! following:
|
|
|
|
|
|
! H5Z_FILTER_DEFLATE_F
|
|
|
|
|
|
! H5Z_FILTER_SHUFFLE_F
|
|
|
|
|
|
! H5Z_FILTER_FLETCHER32_F
|
|
|
|
|
|
! H5Z_FILTER_SZIP_F
|
|
|
|
|
|
INTEGER, INTENT(OUT) :: config_flags ! Bit field indicating whether
|
|
|
|
|
|
! a filter's encoder and/or
|
|
|
|
|
|
! decoder are available
|
|
|
|
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
|
|
|
|
|
|
|
|
|
|
END SUBROUTINE h5zfilter_avail_f
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
|
|
|
|
<dd>
|
|
|
|
|
|
|
|
|
|
|
|
<img src="Graphics/Java.gif">
|
|
|
|
|
|
<img src="Graphics/C++.gif">
|
|
|
|
|
|
-->
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
2003-10-08 03:56:17 +08:00
|
|
|
|
<!-- NEW PAGE -->
|
|
|
|
|
|
<!-- HEADER RIGHT "H5Zregister" -->
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<hr>
|
|
|
|
|
|
<dl>
|
|
|
|
|
|
<dt><strong>Name:</strong> <a name="Compression-Register">H5Zregister</a>
|
|
|
|
|
|
<dt><strong>Signature:</strong>
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<dd><em>herr_t</em> <code>H5Zregister</code>(<em>const H5Z_class_t</em> <code>filter_class</code>)
|
1998-07-15 12:51:50 +08:00
|
|
|
|
)
|
|
|
|
|
|
<dt><strong>Purpose:</strong>
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<dd>Registers new filter.
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<dt><strong>Description:</strong>
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<dd><code>H5Zregister</code> registers a new filter with the
|
2003-05-07 06:20:37 +08:00
|
|
|
|
HDF5 library.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Making a new filter available to an application is a two-step
|
2003-06-24 04:32:50 +08:00
|
|
|
|
process. The first step is to write
|
|
|
|
|
|
the three filter callback functions described below:
|
|
|
|
|
|
<code>can_apply_func</code>, <code>set_local_func</code>, and
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<code>filter_func</code>.
|
|
|
|
|
|
This call to <code>H5Zregister</code>,
|
|
|
|
|
|
<span class="termEmphasis">registering</span> the filter with the
|
|
|
|
|
|
library, is the second step.
|
2003-06-24 04:32:50 +08:00
|
|
|
|
The <code>can_apply_func</code> and <code>set_local_func</code>
|
|
|
|
|
|
fields can be set to <code>NULL</code>
|
|
|
|
|
|
if they are not required for the filter being registered.
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<p>
|
|
|
|
|
|
<code>H5Zregister</code> accepts a single parameter,
|
|
|
|
|
|
the <code>filter_class</code> data structure,
|
|
|
|
|
|
which is defined as follows:
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
typedef struct H5Z_class_t {
|
|
|
|
|
|
H5Z_filter_t filter_id;
|
|
|
|
|
|
const char *comment;
|
|
|
|
|
|
H5Z_can_apply_func_t can_apply_func;
|
|
|
|
|
|
H5Z_set_local_func_t set_local_func;
|
|
|
|
|
|
H5Z_func_t filter_func;
|
|
|
|
|
|
} H5Z_class_t;
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<code>filter_id</code> is the identifier for the new filter.
|
2003-06-24 04:32:50 +08:00
|
|
|
|
This is a user-defined value between
|
|
|
|
|
|
<code>H5Z_FILTER_RESERVED</code> and <code>H5Z_FILTER_MAX</code>,
|
|
|
|
|
|
both of which are defined in the HDF5 source file
|
|
|
|
|
|
<code>H5Zpublic.h</code>.
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<p>
|
2003-06-24 04:32:50 +08:00
|
|
|
|
<code>comment</code> is used for debugging,
|
|
|
|
|
|
may contain a descriptive name for the filter,
|
|
|
|
|
|
and may be the null pointer.
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<p>
|
|
|
|
|
|
<code>can_apply_func</code>, described in detail below,
|
|
|
|
|
|
is a user-defined callback function which determines whether
|
2003-06-24 04:32:50 +08:00
|
|
|
|
the combination of the dataset creation property list values,
|
2003-05-07 06:20:37 +08:00
|
|
|
|
the datatype, and the dataspace represent a valid combination
|
|
|
|
|
|
to apply this filter to.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<code>set_local_func</code>, described in detail below,
|
|
|
|
|
|
is a user-defined callback function which sets any parameters that
|
|
|
|
|
|
are specific to this dataset, based on the combination of the
|
|
|
|
|
|
dataset creation property list values, the datatype, and the
|
|
|
|
|
|
dataspace.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<code>filter_func</code>, described in detail below,
|
|
|
|
|
|
is a user-defined callback 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>The callback functions</strong>
|
|
|
|
|
|
<br>
|
|
|
|
|
|
Before <code>H5Zregister</code> can link a filter into an
|
|
|
|
|
|
application, three callback functions must be defined
|
|
|
|
|
|
as described in the HDF5 Library header file <code>H5Zpublic.h</code>.
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<u>The <i>can apply</i> callback function</u> is defined as follows:<br>
|
|
|
|
|
|
<dir>
|
|
|
|
|
|
<em>typedef herr_t</em> (*<code>H5Z_can_apply_func_t</code>)
|
|
|
|
|
|
(<em>hid_t</em> <code>dcpl_id</code>,
|
|
|
|
|
|
<em>hid_t</em> <code>type_id</code>,
|
|
|
|
|
|
<em>hid_t</em> <code>space_id</code>)
|
|
|
|
|
|
</dir>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
Before a dataset is created, the <i>can apply</i> callbacks for
|
|
|
|
|
|
any filters used in the dataset creation property list are called
|
|
|
|
|
|
with the dataset's dataset creation property list, <code>dcpl_id</code>,
|
|
|
|
|
|
the dataset's datatype, <code>type_id</code>, and
|
|
|
|
|
|
a dataspace describing a chunk, <code>space_id</code>,
|
|
|
|
|
|
(for chunked dataset storage).
|
|
|
|
|
|
<p>
|
|
|
|
|
|
This callback must determine whether the combination of the
|
|
|
|
|
|
dataset creation property list settings, the datatype, and the
|
|
|
|
|
|
dataspace represent a valid combination to which to apply this filter.
|
|
|
|
|
|
For example, an invalid combination may involve
|
|
|
|
|
|
the filter not operating correctly on certain datatypes,
|
|
|
|
|
|
on certain datatype sizes, or on certain sizes of the chunk dataspace.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
This callback can be the <code>NULL</code> pointer, in which case
|
|
|
|
|
|
the library will assume that the filter can be applied to a dataset with
|
|
|
|
|
|
any combination of dataset creation property list values, datatypes,
|
|
|
|
|
|
and dataspaces.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The <i>can apply</i> callback function must return
|
|
|
|
|
|
a positive value for a valid combination,
|
|
|
|
|
|
zero for an invalid combination, and
|
|
|
|
|
|
a negative value for an error.
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<u>The <i>set local</i> callback function</u> is defined as follows:<br>
|
|
|
|
|
|
<dir>
|
|
|
|
|
|
<em>typedef herr_t</em> (*<code>H5Z_set_local_func_t</code>)
|
|
|
|
|
|
(<em>hid_t</em> <code>dcpl_id</code>,
|
|
|
|
|
|
<em>hid_t</em> <code>type_id</code>,
|
|
|
|
|
|
<em>hid_t</em> <code>space_id</code>)
|
|
|
|
|
|
</dir>
|
|
|
|
|
|
<p>
|
|
|
|
|
|
After the <i>can apply</i> callbacks are checked for a new dataset,
|
|
|
|
|
|
the <i>set local</i> callback functions for any filters used in the
|
|
|
|
|
|
dataset creation property list are called.
|
|
|
|
|
|
These callbacks receive
|
|
|
|
|
|
<code>dcpl_id</code>, the dataset's private copy of the dataset
|
|
|
|
|
|
creation property list passed in to <code>H5Dcreate</code>
|
|
|
|
|
|
(i.e. not the actual property list passed in to <code>H5Dcreate</code>);
|
|
|
|
|
|
<code>type_id</code>, the datatype identifier passed in to
|
|
|
|
|
|
<code>H5Dcreate</code>,
|
|
|
|
|
|
which is not copied and should not be modified; and
|
|
|
|
|
|
<code>space_id</code>, a dataspace describing the chunk
|
|
|
|
|
|
(for chunked dataset storage), which should also not be modified.
|
|
|
|
|
|
<p>
|
2003-06-24 04:32:50 +08:00
|
|
|
|
The <i>set local</i> callback must set any filter parameters that are
|
2003-05-07 06:20:37 +08:00
|
|
|
|
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, datatype sizes, numbers of dimensions,
|
|
|
|
|
|
or dataspace sizes.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The <i>set local</i> callback may be the <code>NULL</code> pointer,
|
|
|
|
|
|
in which case, the library will assume that there are
|
|
|
|
|
|
no dataset-specific settings for this filter.
|
|
|
|
|
|
<p>
|
|
|
|
|
|
The <i>set local</i> callback function must return
|
|
|
|
|
|
a non-negative value on success and
|
|
|
|
|
|
a negative value for an error.
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
<u>The <i>filter operation</i> callback function</u>,
|
|
|
|
|
|
defining the filter's operation on the data, is defined as follows:
|
|
|
|
|
|
<dir>
|
2003-02-12 01:09:25 +08:00
|
|
|
|
<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>)
|
2003-05-07 06:20:37 +08:00
|
|
|
|
</dir>
|
2003-02-12 01:09:25 +08:00
|
|
|
|
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<p>
|
|
|
|
|
|
The parameters <code>flags</code>, <code>cd_nelmts</code>,
|
2003-04-03 05:03:57 +08:00
|
|
|
|
and <code>cd_values</code> are the same as for the function
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<a href="RM_H5P.html#Property-SetFilter"><code>H5Pset_filter</code></a>.
|
|
|
|
|
|
The one exception is that an additional flag,
|
|
|
|
|
|
<code>H5Z_FLAG_REVERSE</code>, is set when
|
2003-02-12 01:09:25 +08:00
|
|
|
|
the filter is called as part of the input pipeline.
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<p>
|
2003-02-12 01:09:25 +08:00
|
|
|
|
The parameter <code>*buf</code> points to the input buffer
|
2003-04-03 05:03:57 +08:00
|
|
|
|
which has a size of <code>*buf_size</code> bytes,
|
2003-02-12 01:09:25 +08:00
|
|
|
|
<code>nbytes</code> of which are valid data.
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<p>
|
|
|
|
|
|
The filter should perform the transformation in place if
|
|
|
|
|
|
possible. If the transformation cannot be done in place,
|
2003-02-12 01:09:25 +08:00
|
|
|
|
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>.
|
2003-05-07 06:20:37 +08:00
|
|
|
|
<p>
|
|
|
|
|
|
If successful, the <i>filter operation</i> callback function
|
|
|
|
|
|
returns the number of valid bytes of data contained in <code>*buf</code>.
|
|
|
|
|
|
In the case of failure, the return value is <code>0</code> (zero)
|
|
|
|
|
|
and all pointer arguments are left unchanged.
|
|
|
|
|
|
<dt><strong>Note:</strong>
|
|
|
|
|
|
<dd>The <code>H5Zregister</code> interface is substantially revised
|
|
|
|
|
|
from the HDF5 Release 1.4.x series.
|
|
|
|
|
|
The <code>H5Z_class_t</code> struct and
|
|
|
|
|
|
the <i>set local</i> and <i>can apply</i> callback functions
|
|
|
|
|
|
first appeared in HDF5 Release 1.6.
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<dt><strong>Parameters:</strong>
|
2004-02-25 06:10:12 +08:00
|
|
|
|
<ul><table>
|
|
|
|
|
|
<tr>
|
|
|
|
|
|
<td valign="top"><em>const H5Z_class_t</em> <code>filter_class </code></td>
|
|
|
|
|
|
<td valign="top">IN: Struct containing filter-definition information.</td></tr>
|
|
|
|
|
|
</table></ul>
|
1998-07-15 12:51:50 +08:00
|
|
|
|
<dt><strong>Returns:</strong>
|
1998-10-30 06:13:17 +08:00
|
|
|
|
<dd>Returns a non-negative value if successful;
|
|
|
|
|
|
otherwise returns a negative value.
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<dt><strong>Fortran90 Interface:</strong>
|
|
|
|
|
|
<dd>None.
|
2003-04-09 05:33:50 +08:00
|
|
|
|
<!--
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<pre>
|
|
|
|
|
|
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
-->
|
|
|
|
|
|
|
|
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
|
|
|
|
<dd>
|
|
|
|
|
|
|
2003-04-09 05:33:50 +08:00
|
|
|
|
<img src="Graphics/Java.gif">
|
|
|
|
|
|
<img src="Graphics/C++.gif">
|
|
|
|
|
|
-->
|
1998-07-15 12:51:50 +08:00
|
|
|
|
</dl>
|
|
|
|
|
|
|
2003-10-08 03:56:17 +08:00
|
|
|
|
<!-- NEW PAGE -->
|
|
|
|
|
|
<!-- HEADER RIGHT "H5Zunregister" -->
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<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>
|
2004-02-25 06:10:12 +08:00
|
|
|
|
<ul><table>
|
|
|
|
|
|
<tr>
|
|
|
|
|
|
<td valign="top"><em>H5Z_filter_t</em> <code>filter </code></td>
|
2004-07-03 06:03:17 +08:00
|
|
|
|
<td valign="top">IN: Identifier of the filter to be unregistered.
|
|
|
|
|
|
See the introduction to this section of the reference manual
|
2004-09-03 07:00:33 +08:00
|
|
|
|
for a list of identifiers for standard filters
|
|
|
|
|
|
distributed with the HDF5 Library.</td></tr>
|
2004-02-25 06:10:12 +08:00
|
|
|
|
</table></ul>
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<dt><strong>Returns:</strong>
|
|
|
|
|
|
<dd>Returns a non-negative value if successful;
|
|
|
|
|
|
otherwise returns a negative value.
|
2003-10-24 06:05:50 +08:00
|
|
|
|
<dt><strong>Fortran90 Interface:</strong> h5zunregister_f
|
|
|
|
|
|
<dd>
|
|
|
|
|
|
<pre>
|
|
|
|
|
|
SUBROUTINE h5zunregister_f(filter, hdferr)
|
|
|
|
|
|
IMPLICIT NONE
|
|
|
|
|
|
INTEGER, INTENT(IN) :: filter ! Filter; one of the possible values:
|
|
|
|
|
|
! H5Z_FILTER_DEFLATE_F
|
|
|
|
|
|
! H5Z_FILTER_SHUFFLE_F
|
|
|
|
|
|
! H5Z_FILTER_FLETCHER32_F
|
2004-07-03 06:03:17 +08:00
|
|
|
|
! H5Z_FILTER_SZIP_F
|
2003-10-24 06:05:50 +08:00
|
|
|
|
INTEGER, INTENT(OUT) :: hdferr ! Error code
|
|
|
|
|
|
! 0 on success, and -1 on failure
|
|
|
|
|
|
END SUBROUTINE h5zunregister_f
|
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
<!--<dt><strong>Non-C API(s):</strong>
|
|
|
|
|
|
<dd>
|
|
|
|
|
|
|
2003-04-03 05:03:57 +08:00
|
|
|
|
<img src="Graphics/Java.gif">
|
|
|
|
|
|
<img src="Graphics/C++.gif">
|
|
|
|
|
|
-->
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
2004-03-13 04:36:43 +08:00
|
|
|
|
<!-- HEADER RIGHT " " -->
|
2003-04-03 05:03:57 +08:00
|
|
|
|
|
2003-03-15 03:12:34 +08:00
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<center>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
<table border=0 width=98%>
|
|
|
|
|
|
<tr><td valign=top align=left>
|
2003-03-15 03:12:34 +08:00
|
|
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
2003-07-04 03:40:03 +08:00
|
|
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
<!--
|
|
|
|
|
|
<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>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<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>
|
1998-10-30 06:13:17 +08:00
|
|
|
|
<a href="RM_H5I.html">H5I</a>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<a href="RM_H5P.html">H5P</a>
|
2000-12-13 06:43:02 +08:00
|
|
|
|
<br>
|
1998-10-30 06:13:17 +08:00
|
|
|
|
<a href="RM_H5R.html">H5R</a>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<a href="RM_H5S.html">H5S</a>
|
|
|
|
|
|
<a href="RM_H5T.html">H5T</a>
|
2003-03-15 03:12:34 +08:00
|
|
|
|
<a href="RM_H5Z.html">H5Z</a>
|
1998-09-12 00:00:43 +08:00
|
|
|
|
<a href="Tools.html">Tools</a>
|
2000-12-13 06:43:02 +08:00
|
|
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
1998-12-22 06:52:56 +08:00
|
|
|
|
</td></tr>
|
|
|
|
|
|
</table>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
</center>
|
2004-02-25 06:10:12 +08:00
|
|
|
|
<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
|
1998-07-15 13:14:11 +08:00
|
|
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
2000-07-18 03:40:34 +08:00
|
|
|
|
<br>
|
2003-10-28 05:55:13 +08:00
|
|
|
|
Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0
|
2003-10-08 03:56:17 +08:00
|
|
|
|
</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
|
|
|
|
|
|
<!--
|
2004-09-03 07:00:33 +08:00
|
|
|
|
document.writeln("Last modified: 2 September 2004");
|
2003-10-08 03:56:17 +08:00
|
|
|
|
-->
|
|
|
|
|
|
</SCRIPT>
|
2003-03-15 03:12:34 +08:00
|
|
|
|
|
1998-07-15 12:51:50 +08:00
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
