mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-20 01:58:06 +00:00
7f7686d7f2
* Bump API patch number and header version number to 23 for this update.
Github Issues:
* Add explicit valid value attributes to pname:sType members in vk.xml
(public issue 34).
* Clarify usage of flink:vkGetInstanceProcAddr and
flink:vkGetDeviceProcAddr (public issue 225).
* Fix a copy-and-paste error in the description of
pname:pSwapchainImageCount saying that it was the count of ``format
pairs'' instead of ``swapchain images'' (public issue 292).
* flink:vkCmdExecuteCommandBuffers requires all command buffers to be
allocated from command pools created for the same queue family (public
issue 296).
* Remove bogus +optional+ attribute for
flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml
(public issue 301).
* Clean up the <<resources-image-views-compatibility,image and image view
compatibility table>> reference and contents. Use full enumerant names.
Refer to pname:layerCount in the ``view parameters'' column instead of
pname:arrayLayers. Require N >= 1 for the cube array subview row, not
just arrayLayers >= 6 N (public issue 304).
* Modify description of <<resources-memory-aliasing,memory aliasing>> to
be consistent with the description of
<<resources-bufferimagegranularity,buffer image granularity>> (public
issue 307).
Internal Issues:
* Describe remaining +vk_platform.h+ macros in the <<boilerplate,API
Boilerplate>> appendix (internal issue 6).
* Clarify
<<features-features-robustBufferAccess,pname:robustBufferAccess>>
feature behavior; what memory can be accessed, how bounds checking is
performed, and allowing for vectorization (internal issue 332).
* Document markup for automatic extraction of reference pages from the
spec sources in the style guide (internal issue 395).
* Allow flink:vkCreateDisplayModeKHR to return
ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode
parameters that the specified display does not support (internal issue
411).
* Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and
more clearly remove the subroutine keyword alongside it (internal issue
421).
* Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets
not contained in the layout (internal issue 427).
Other Commits:
* Change the order in which members of sname:VkAttachmentDescription and
sname:VkPipelineInputAssemblyStateCreateInfo are described to match
their order in the structures.
440 lines
15 KiB
Plaintext
440 lines
15 KiB
Plaintext
# Copyright (c) 2013-2016 The Khronos Group Inc.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
# Relax NG schema for Khronos Vulkan API Registry XML
|
|
#
|
|
# See https://www.khronos.org/vulkan/
|
|
#
|
|
# This definition is subject to change (mostly in the form of additions)
|
|
|
|
namespace xsd = "http://www.w3.org/2001/XMLSchema-datatypes"
|
|
|
|
# Toplevel is a <registry> tag.
|
|
# May be led by an optional <comment> tag containing e.g. copyrights.
|
|
start = element registry {
|
|
(
|
|
element comment { text } ? |
|
|
Vendorids * |
|
|
Tags * |
|
|
Types * |
|
|
Enums * |
|
|
Commands * |
|
|
Feature * |
|
|
Extensions *
|
|
) *
|
|
}
|
|
|
|
# <vendorids> defines a group of vendor IDs
|
|
Vendorids = element vendorids {
|
|
Vendorid *
|
|
}
|
|
|
|
# <vendorid> defines a single vendor ID.
|
|
# name - author ID of the vendor
|
|
# id - Khronos vendor ID (hexadecimal constant starting at 0x10000)
|
|
# comment - unused
|
|
Vendorid = element vendorid {
|
|
attribute name { text } ,
|
|
attribute id { text } ,
|
|
Comment ?
|
|
}
|
|
|
|
# <tags> defines a group of author tags
|
|
Tags = element tags {
|
|
Tag *
|
|
}
|
|
|
|
# <tag> defines a single author tag.
|
|
# name - name of the tag
|
|
# author - name of the author (usually a company or project name)
|
|
# contact - contact responsible for the tag (name and contact information)
|
|
Tag = element tag {
|
|
attribute name { text } ,
|
|
attribute author { text } ,
|
|
attribute contact { text }
|
|
}
|
|
|
|
# <types> defines a group of types
|
|
Types = element types {
|
|
Type *
|
|
}
|
|
|
|
# <type> defines a single type. It is usually a C typedef but
|
|
# may contain arbitrary C code.
|
|
# name - name of this type, if not present in the <name> tag
|
|
# api - matches a <feature> api attribute, if present
|
|
# requires - name of another type definition required by this one
|
|
# category - if present, "enum" indicates a matching <enums>
|
|
# block to generate an enumerated type for, and "struct"
|
|
# causes special interpretation of the contents of the type
|
|
# tag including ... TBD ...
|
|
# Other allowed values are "include", "define", "handle" and "bitmask",
|
|
# which don't change syntactic interpretation but allow organization in
|
|
# the generated header.
|
|
# comment - unused
|
|
# parent - only applicable if category is "handle". Notes another type with
|
|
# the "handle" category that acts as a parent object for this type.
|
|
# returnedonly - only applicable if category is "struct". Notes that this
|
|
# struct is going to be filled in by the API, rather than an application
|
|
# filling it out and passing it to the API.
|
|
# For types without a category, contents include
|
|
# <apientry /> - substitutes for an APIENTRY-style macro on output
|
|
# <name> - contains name of the type being defined
|
|
# <type> - contains name of types used to define this type. There
|
|
# may be multiple imbedded <type> tags
|
|
# For types with category "enum", contents should be empty
|
|
# For types with category "struct", contents should be one or more
|
|
# <member> - like <param> for a struct or union member
|
|
# len - if the member is an array, len may be one or more of the following
|
|
# things, separated by commas (one for each array indirection): another
|
|
# member of that struct, 'null-terminated' for a string, '1' to indicate it's
|
|
# just a pointer (used for nested pointers), or a latex equation (prefixed with
|
|
# 'latex:')
|
|
# externsync - denotes that the member should be externally synchronized
|
|
# when accessed by Vulkan
|
|
# optional - whether this value can be omitted by providing NULL (for
|
|
# pointers), VK_NULL_HANDLE (for handles) or 0 (for bitmasks/values)
|
|
# noautovalidity - tag stating that no automatic validity language should be generated
|
|
# validextensionstructs - comma-separate list of legal structure types in pNext chain
|
|
# values - comma-separated list of legal values, usually used only for sType enums
|
|
#
|
|
# *** There's a problem here: I'm not sure how to represent the <type>
|
|
# syntax where it may contain arbitrarily interleaved text, <type>, and
|
|
# <enum> child tags. This allows only the syntax
|
|
# text <type>name</type> text <enum>name</enum> text
|
|
# where <type> and <enum> are both optional and occur in the specified
|
|
# order, which might eventually be a problem.
|
|
Type = element type {
|
|
attribute api { text } ? ,
|
|
attribute requires { text } ? ,
|
|
attribute name { TypeName } ? ,
|
|
attribute category { text } ? ,
|
|
attribute parent { TypeName } ? ,
|
|
attribute returnedonly { text } ? ,
|
|
Comment ? ,
|
|
(
|
|
(
|
|
( text ,
|
|
element type { text } *
|
|
) * ,
|
|
element apientry { text } ? ,
|
|
( text ,
|
|
element type { text } *
|
|
) * ,
|
|
element name { TypeName } ? ,
|
|
( text ,
|
|
element type { text } *
|
|
) *
|
|
) |
|
|
(
|
|
element member {
|
|
attribute len { text } ? ,
|
|
attribute externsync { text } ? ,
|
|
attribute optional { text } ? ,
|
|
attribute noautovalidity { text } ? ,
|
|
attribute validextensionstructs { text } ? ,
|
|
attribute values { text } ? ,
|
|
mixed {
|
|
element type { TypeName } ? ,
|
|
element name { text },
|
|
element enum { EnumName } ?
|
|
}
|
|
} * ,
|
|
Validity ?
|
|
)
|
|
)
|
|
}
|
|
|
|
# <enums> defines a group of enumerants
|
|
# name - identifies a type name associated with this group. Should
|
|
# match a <type> name to trigger generation of the type.
|
|
# start, end - beginning and end of a numeric range
|
|
# vendor - owner of the numeric range
|
|
# type - "enum" or "bitmask", if present
|
|
# comment - unused
|
|
Enums = element enums {
|
|
attribute name { text } ? ,
|
|
attribute type { text } ? ,
|
|
attribute start { Integer } ? ,
|
|
attribute end { Integer } ? ,
|
|
Vendor ? ,
|
|
Comment ? ,
|
|
(Enum | Unused) *
|
|
}
|
|
|
|
# <enum> defines or references a single enumerant. There are two places it
|
|
# can be used: in an <enums> block, providing a global definition which
|
|
# may later be required by a feature or extension; or in a feature or
|
|
# extension, defining an enumerant specific to that feature. The second
|
|
# form has more possible attributes. Some combinations of attributes are
|
|
# nonsensical in on or the other place, but these are not detected by the
|
|
# validator.
|
|
#
|
|
# Ways to specify the enumerant value:
|
|
# value - integer (including hex) value of the enumerant
|
|
# bitpos - integer bit position of the enumerant in a bitmask
|
|
# offset, [dir] - integer offset and direction ("-" for negative,
|
|
# or positive if not specified) from a base value
|
|
#
|
|
# value and bitpos allow, and offset/dir require, the attribute:
|
|
# extends - type name of the enumerant being extended
|
|
#
|
|
# Other attributes:
|
|
# api - matches a <feature> api attribute, if present
|
|
# type - "u" (unsigned), "ull" (uint64), or integer if not present
|
|
# name - enumerant name
|
|
# alias - another enumerant this is semantically identical to
|
|
# comment - unused
|
|
Enum = element enum {
|
|
(
|
|
(
|
|
(
|
|
attribute value { Integer } &
|
|
attribute extends { TypeName } ?
|
|
) |
|
|
(
|
|
attribute bitpos { Integer } &
|
|
attribute extends { TypeName } ?
|
|
) |
|
|
(
|
|
attribute offset { Integer } &
|
|
attribute dir { text } ? &
|
|
attribute extends { TypeName }
|
|
)
|
|
) ? &
|
|
attribute api { text } ? &
|
|
attribute type { TypeSuffix } ? &
|
|
attribute name { text } &
|
|
attribute alias { text } ? &
|
|
Comment ?
|
|
)
|
|
}
|
|
|
|
# <unused> defines a range of enumerants not currently being used
|
|
# start, end - beginning and end of an unused numeric range
|
|
# vendor - unused
|
|
# comment - unused
|
|
Unused = element unused {
|
|
attribute start { Integer } ,
|
|
attribute end { Integer } ? ,
|
|
Vendor ? ,
|
|
Comment ?
|
|
}
|
|
# <commands> defines a group of commands
|
|
Commands = element commands {
|
|
Command *
|
|
}
|
|
|
|
# <command> defines a single command
|
|
#
|
|
# The possible attributes are not described in this comment block yet, but
|
|
# are in readme.pdf.
|
|
#
|
|
# <proto> is the C function prototype, including the return type
|
|
# <param> are function parameters, in order
|
|
# len - if the member is an array, len may be one or more of the following
|
|
# things, separated by commas (one for each array indirection): another
|
|
# member of that struct, 'null-terminated' for a string, '1' to indicate it's
|
|
# just a pointer (used for nested pointers), or a latex equation (prefixed with
|
|
# 'latex:')
|
|
# externsync - denotes that the member should be externally synchronized
|
|
# when accessed by Vulkan
|
|
# optional - whether this value can be omitted by providing NULL (for
|
|
# pointers), VK_NULL_HANDLE (for handles) or 0 (for bitmasks/values)
|
|
# noautovalidity - tag stating that no automatic validity language should be generated
|
|
# <type> is a <type> name, if present
|
|
# <name> is the function / parameter name
|
|
# The textual contents of <proto> and <param> should be legal C
|
|
# for those parts of a function declaration.
|
|
# <alias> - denotes function aliasing, if present
|
|
# name - name of aliased function
|
|
# <description> - unused text
|
|
# <implicitexternsyncparams> are spec-language descriptions of
|
|
# objects that are not parameters of the command, but
|
|
# are related to them and also require external synchronization.
|
|
Command = element command {
|
|
attribute queues { text } ? ,
|
|
attribute successcodes { text } ? ,
|
|
attribute errorcodes { text } ? ,
|
|
attribute renderpass { text } ? ,
|
|
attribute cmdbufferlevel { text } ? ,
|
|
Comment ? ,
|
|
element proto {
|
|
mixed {
|
|
element type { TypeName } ? ,
|
|
element name { text }
|
|
}
|
|
} ,
|
|
element param {
|
|
attribute len { text } ? ,
|
|
attribute externsync { text } ? ,
|
|
attribute optional { text } ? ,
|
|
attribute noautovalidity { text } ? ,
|
|
mixed {
|
|
element type { TypeName } ? ,
|
|
element name { text }
|
|
}
|
|
} * ,
|
|
(
|
|
element alias {
|
|
Name
|
|
} ? &
|
|
element description {
|
|
text
|
|
} ? &
|
|
element implicitexternsyncparams {
|
|
element param { text } *
|
|
} ? &
|
|
Validity ?
|
|
)
|
|
}
|
|
|
|
# Each <feature> defines the interface of an API version (e.g. OpenGL 1.2)
|
|
# api - API tag (e.g. 'gl', 'gles2', etc. - used internally, not
|
|
# necessarily an actual API name
|
|
# name - version name (C preprocessor name, e.g. GL_VERSION_4_2)
|
|
# number - version number, e.g. 4.2
|
|
# protect - additional #ifdef symbol to place around the feature
|
|
# <require> / <remove> contains features to require or remove in
|
|
# this version
|
|
# profile - only require/remove when generated profile matches
|
|
# comment - unused
|
|
Feature = element feature {
|
|
attribute api { text } ,
|
|
Name ,
|
|
attribute number { xsd:float } ,
|
|
attribute protect { text } ?,
|
|
Comment ? ,
|
|
(
|
|
element require {
|
|
ProfileName ? ,
|
|
Comment ? ,
|
|
InterfaceElement *,
|
|
element usage {
|
|
attribute struct { text } *,
|
|
attribute command { text } *,
|
|
text } *
|
|
} |
|
|
element remove {
|
|
ProfileName ? ,
|
|
Comment ? ,
|
|
InterfaceElement *,
|
|
element usage {
|
|
attribute struct { text } *,
|
|
attribute command { text } *,
|
|
text } *
|
|
}
|
|
) *
|
|
}
|
|
Extensions = element extensions {
|
|
Extension *
|
|
}
|
|
|
|
# Defines the interface of an API <extension>. Like a <feature>
|
|
# tag, but with slightly different attributes:
|
|
# api - regexp pattern matching one or more API tags, indicating
|
|
# which APIs the extension is known to work with. The only
|
|
# syntax supported is <name>{|<name>}* and each name must
|
|
# exactly match an API being generated (implicit ^$ surrounding).
|
|
# name - extension name string
|
|
# number - extension number (positive integer, should be unique)
|
|
# protect - C preprocessor symbol to conditionally define the interface
|
|
# supported - profile name(s) supporting this extension, e.g. "vulkan"
|
|
# or "disabled" to never generate output.
|
|
# author - name of the author (usually a company or project name)
|
|
# contact - contact responsible for the tag (name and contact information)
|
|
# In addition, <require> / <remove> tags also support an api attribute:
|
|
# api - only require/remove these features for the matching API.
|
|
# Not a regular expression.
|
|
Extension = element extension {
|
|
Name ,
|
|
attribute number { Integer } ?,
|
|
attribute protect { text } ?,
|
|
attribute supported { StringGroup } ? ,
|
|
attribute author { text } ? ,
|
|
attribute contact { text } ? ,
|
|
Comment ? ,
|
|
(
|
|
element require {
|
|
attribute api { text } ? ,
|
|
ProfileName ? ,
|
|
Comment ? ,
|
|
InterfaceElement *,
|
|
element usage {
|
|
attribute struct { text } *,
|
|
attribute command { text } *,
|
|
text } *
|
|
} |
|
|
element remove {
|
|
attribute api { text } ? ,
|
|
ProfileName ? ,
|
|
Comment ? ,
|
|
InterfaceElement *,
|
|
element usage {
|
|
attribute struct { text } *,
|
|
attribute command { text } *,
|
|
text } *
|
|
}
|
|
) *
|
|
}
|
|
|
|
# Contents of a <require> / <remove> tag, defining a group
|
|
# of features to require or remove.
|
|
# <type> / <enum> / <command> all have attributes
|
|
# name - feature name which must match
|
|
InterfaceElement =
|
|
element type {
|
|
Name ,
|
|
Comment ?
|
|
} |
|
|
Enum |
|
|
element command {
|
|
Name ,
|
|
Comment ?
|
|
}
|
|
|
|
# Defines validation text for the Vulkan spec and reference pages.
|
|
# Consists of multiple <usage> tags, each containing arbitrary
|
|
# asciidoc text.
|
|
Validity = element validity {
|
|
element usage { text } *
|
|
}
|
|
|
|
# Integers are allowed to be either decimal or C-hex (0x[0-9A-F]+), but
|
|
# XML Schema types don't seem to support hex notation, so we use this
|
|
# as a placeholder.
|
|
Integer = text
|
|
|
|
# EnumName is an compile-time constant name
|
|
EnumName = text
|
|
|
|
# ExtensionName is the name string of an API extension
|
|
ExtensionName = text
|
|
|
|
# TypeName is an argument/return value C type name
|
|
TypeName = text
|
|
|
|
# TypeSuffix is a C numeric type suffix, e.g. 'u' or 'ull'
|
|
TypeSuffix = text
|
|
|
|
# StringGroup is a regular expression with an implicit
|
|
# '^(' and ')$' bracketing it.
|
|
StringGroup = text
|
|
|
|
# Repeatedly used attributes
|
|
ProfileName = attribute profile { text }
|
|
Vendor = attribute vendor { text }
|
|
Comment = attribute comment { text }
|
|
Name = attribute name { text }
|