You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: drop confusing "HDF5 v3" phrasing in favor of H5Z_class3_t
"HDF5 v3" reads as "HDF5 library 3.0", but the new plugin class
H5Z_class3_t ships in HDF5 2.x. Rename the section heading, the
subsection on updating existing registrations, and replace
"v3-aware library" / "v3 build" / "HDF5 v3 plugin" wording with
direct references to H5Z_class3_t or "HDF5 2.x" as appropriate.
The plugin-class version ("v3", as in v1/v2/v3 of H5Z_class_t) is
retained only where the versioning of the class itself is the
subject.
Copy file name to clipboardExpand all lines: docs/RegisteredFilterPlugins.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ Any member of the HDF5 community can register a plugin for their or a third-part
11
11
* Maintainer's contact information. Minimum an email address, preferably additional information like personal website, GitHub or social network handles. More ways to contact the responsible maintainer is better.
12
12
* Filter plugin's respository.
13
13
* Description of the new plugin including the specifics of the filter parameters (`cd_nelmts` and `cd_values[]`) supported by the plugin.
14
-
* A proposed **canonical name** for the filter. This is the short, stable string identifier that an HDF5 v3 (`H5Z_class3_t`) plugin will advertise in its `name` field and that the library will write into the on-disk filter-pipeline message. The canonical name must be non-empty, no more than 255 bytes, drawn from the character class `[A-Za-z0-9_.-]`, and is matched case-sensitively. See [Canonical Names](#canonical-names-hdf5-v3--h5z_class3_t) below for details. (Existing v1/v2 plugins without a canonical name continue to work unchanged; this only becomes load-bearing when a plugin opts into v3.)
14
+
* A proposed **canonical name** for the filter. This is the short, stable string identifier that an `H5Z_class3_t` plugin will advertise in its `name` field and that the library will write into the on-disk filter-pipeline message. The canonical name must be non-empty, no more than 255 bytes, drawn from the character class `[A-Za-z0-9_.-]`, and is matched case-sensitively. See [Canonical Names](#canonical-names-h5z_class3_t-plugin-class) below for details. (Existing `H5Z_class1_t`/`H5Z_class2_t` plugins without a canonical name continue to work unchanged; this only becomes load-bearing when a plugin opts into the v3 plugin class.)
15
15
* Links to any relevant documentation, including the licensing information.
16
16
17
17
Upon receiving a request with the above information, HDF Group will register the new plugin by assigning it a filter plugin _identifier_. The current policy for assigning an identifier is explained below:
@@ -25,7 +25,7 @@ Upon receiving a request with the above information, HDF Group will register the
25
25
26
26
## List of Filter Plugins Registered with The HDF Group
27
27
28
-
The **Canonical Name** column is the string identifier used by HDF5 v3 (`H5Z_class3_t`) plugins. Entries marked _(proposed)_ are pending confirmation by the plugin maintainer; see [Canonical Names](#canonical-names-hdf5-v3--h5z_class3_t) and the [tracking issue](https://github.com/HDFGroup/hdf5_plugins/issues/255).
28
+
The **Canonical Name** column is the string identifier used by `H5Z_class3_t` plugins. Entries marked _(proposed)_ are pending confirmation by the plugin maintainer; see [Canonical Names](#canonical-names-h5z_class3_t-plugin-class) and the [tracking issue](https://github.com/HDFGroup/hdf5_plugins/issues/255).
29
29
30
30
| Plugin Identifier | Canonical Name | For Filter | Short Description|
@@ -69,14 +69,14 @@ The **Canonical Name** column is the string identifier used by HDF5 v3 (`H5Z_cla
69
69
> [!NOTE]
70
70
> Please contact the maintainer of a filter plugin for help with the plugin or its filter in the HDF5 library.
71
71
72
-
## Canonical Names (HDF5 v3 / `H5Z_class3_t`)
72
+
## Canonical Names (`H5Z_class3_t` plugin class)
73
73
74
-
Starting with the v3 plugin class (`H5Z_class3_t`) introduced in HDF5 2.x, every registered filter has a **canonical name**: a short, stable string identifier used by callers, tools, and the on-disk format.
74
+
Starting with the v3 filter plugin class (`H5Z_class3_t`), introduced in HDF5 2.x, every registered filter has a **canonical name**: a short, stable string identifier used by callers, tools, and the on-disk format.
75
75
76
76
### Where the canonical name appears
77
77
78
-
***In the plugin source.**A v3 plugin sets `H5Z_class3_t::name` to its canonical name.
79
-
***In the file.** When a v3-aware library adds a filter to a dataset's pipeline, it writes the canonical name into the filter-pipeline message (`H5O_PLINE`), so tools like `h5dump` can identify the filter even when the plugin shared library is not installed.
78
+
***In the plugin source.**An `H5Z_class3_t` plugin sets its `name` to the canonical name.
79
+
***In the file.** When an HDF5 library that supports `H5Z_class3_t` adds a filter to a dataset's pipeline, it writes the canonical name into the filter-pipeline message (`H5O_PLINE`), so tools like `h5dump` can identify the filter even when the plugin shared library is not installed.
80
80
***In the API.** The forthcoming `H5Pappend_filter("canonical_name", "params")` interface accepts the canonical name to identify the filter, and accepts a TOML inline table parameter string for typed configuration. (Numeric filter IDs continue to work via the existing `H5Pset_filter` interface.)
81
81
***In CLI tools.**`h5repack`, `h5dump`, and other tools display the canonical name when printing filter information.
82
82
@@ -97,13 +97,13 @@ The HDF Group assigns a canonical name alongside the numeric `id` at filter-regi
97
97
98
98
Third-party plugins that have not gone through HDF Group filter registration should self-namespace their canonical names (for example, `org.example.fastlz`) to make accidental collisions vanishingly unlikely. Coordinated registration through The HDF Group remains the recommended path for plugins that want a short, bare name.
99
99
100
-
### Updating an existing registration for v3
100
+
### Updating an existing registration for `H5Z_class3_t`
101
101
102
-
Existing filter plugins continue to work unchanged with HDF5 v3-aware libraries; the canonical name only becomes load-bearing when a plugin opts into the new `H5Z_class3_t` class. Maintainers of currently registered plugins should:
102
+
Existing filter plugins continue to work unchanged with HDF5 2.x; the canonical name only becomes load-bearing when a plugin opts into the new `H5Z_class3_t` class. Maintainers of currently registered plugins should:
103
103
104
104
1. Review the proposed canonical name in the table above for your filter ID.
105
105
2. Confirm or propose a correction by replying on the [tracking issue](https://github.com/HDFGroup/hdf5_plugins/issues/255) or contacting the HDF Group [Helpdesk](mailto:help@hdfgroup.org). Confirmations replace _(proposed)_ in the table.
106
-
3. When shipping a v3 build of the plugin, set `H5Z_class3_t::name` to the registered canonical name byte-identically.
106
+
3. When porting the plugin to `H5Z_class3_t`, set the `name` field to the registered canonical name byte-identically.
107
107
108
108
See the HDF5 RFC on string-configured filters (RFC-HDFG-2026-001) for the full v3 design.
0 commit comments