From 6fbb889027660c2726ab271fd0bea68f51a44924 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Wed, 21 Aug 2024 03:05:04 -0700 Subject: [PATCH] Add discussion of processing frameworks being responsible for all defined attributes and tags and refer to it for sortorder and protect attributes Closes #2395 --- registry.adoc | 58 +++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 6 deletions(-) diff --git a/registry.adoc b/registry.adoc index 69f6d3bd5..f5c5e1b51 100644 --- a/registry.adoc +++ b/registry.adoc @@ -203,6 +203,40 @@ There are a variety of output generators included: * `extensionStubSource.py` - generate a simple C extension loader. +[[implementations]] += Alternate Registry Processing Frameworks + +We encourage people needing to process registry XML to use the Python +generator framework. +It has been successfully used by many other projects, such as OpenXR and +many of its software components + +Be aware that the schema is not static. +Over time, we have introduced a number of non-breaking changes in the form +of additional XML tags and attributes. +On rare occasion we have made a breaking change, such as replacing the +attr:requires syntax and attr:requiresCore attributes for specifying +extension and version dependencies with the attr:depends attribute. + +While such changes are supported in the Python scripts when they are made, +downstreams using other XML processing code are responsible for tracking and +implementing corresponding changes. + + +[[implementations-rare]] +== Rarely Used Tags and Attributes + +If you do implement your own XML processing framework, you are responsible +for complying with the interpretation of the schema and its contents, and +producing results consistent with the Python framework. + +Choosing to not implement processing of certain tags or attributes may +produce incorrect outputs. +If you are doing this because the tags or attributes are not currently used +in the Vulkan XML, you may want to flag a warning or error when they are +encountered. + + [[schema]] = Vulkan Registry Schema @@ -1355,15 +1389,24 @@ feature. A decimal number which specifies an order relative to other tag:feature tags when calling output generators. Defaults to `0`. - Rarely used, for when ordering by attr:name is insufficient. + Used when ordering by attr:name is insufficient. * attr:protect - optional. An additional preprocessor token used to protect a feature definition. Usually another feature or extension attr:name. - Rarely used, for odd circumstances where the definition of a feature or - extension requires another to be defined first. + Used when the definition of a feature or extension requires another to + be defined first. * attr:comment - optional. Arbitrary string (unused). +[NOTE] +==== +The attr:sortorder and attr:protect attributes may not be used +in the XML at times. +If writing an <>, +refer to the notes on <>. +==== + [NOTE] ==== The attr:name attribute used for Vulkan core versions, such as @@ -1459,7 +1502,7 @@ implemented against. A decimal number which specifies an order relative to other tag:extension tags when calling output generators. Defaults to `0`. - Rarely used, for when ordering by attr:number is insufficient. + Used when ordering by attr:number is insufficient. * attr:author - optional. The author name, such as a full company name. If not present, this can be taken from the corresponding tag:tag @@ -1520,8 +1563,8 @@ logical AND, and must be replaced by `+` in the `depends` attribute. An additional preprocessor token used to protect an extension definition. Usually another feature or extension attr:name. - Rarely used, for odd circumstances where the definition of an extension - requires another extension or a header file to be defined first. + Used when the definition of a feature or extension requires another to + be defined first. * attr:platform - optional. Indicates that the extension is specific to the platform identified by the attribute value, and should be emitted conditional on that platform @@ -3213,6 +3256,9 @@ Changes to the `.xml` files and Python scripts are logged in GitHub history. [[changelog]] = Change Log + * Added notes on <> and referred to them for rarely used attributes in the + <> tag (public issue 2395). * 2024-07-18 - Remove out of date guidance that builtin and external types should not be wrapped in tag:type tags, replaced with actual examples in the <> section (public issue 2394).