Lines Matching +refs:_obj +refs:a
35 a variety of outputs, including C header files as well as several types of
46 The registry uses an XML representation of the Vulkan API, together with a
57 The Vulkan C header files generated from the registry are checked into a
92 into a separate repository, but since there is so much specification valid
112 This should regenerate `vulkan_core.h` and a variety of platform-specific
120 The `install` target also generates source code for a simple extension
152 interfaces and creates a C-language header file for them.
174 `generator.py` is used to create a header file.
177 There are a variety of output generators included:
183 * `pygenerator.py` - generate a Python dictionary-based encoding of
185 * `extensionStubSource.py` - generate a simple C extension loader.
191 The format of the Vulkan registry is a top level tag:registry tag containing
194 This description corresponds to a formal Relax NG schema file,
234 If present, the attribute value must be a comma-separated list of one or
236 This allows specializing a definition for different, closely related APIs.
253 * tag:comment - Contains arbitrary text, such as a copyright statement.
265 Related groups may be tagged as an enumerated type corresponding to a
266 tag:type tag, and resulting in a C `enum` declaration.
317 A tag:platform tag describes a single platform name.
323 This must be a short alphanumeric string corresponding to the platform
324 name, valid as part of a C99 identifier.
326 In some cases, it may be desirable to distinguish a subset of platform
347 This must be a C99 preprocessor token beginning with `VK_USE_PLATFORM_`
392 A tag:tag tag contains information defining a single author ID.
401 The author name, such as a full company or project name.
451 This is typically used when promoting a type defined by an extension to
452 a new core version of the API.
462 A string which indicates that this type contains a more complex
470 Notes another type with the `handle` category that acts as a parent
477 This is a comma-separated list of structures whose `pNext` can include
481 This will generate a validity statement on the top level structure that
491 Specifies the name of a `VkObjectType` enumerant which corresponds to
501 If the attr:category tag has the value `enum`, the type is a C enumeration.
504 attr:name attribute of a <<tag-enums,tag:enums>> tag.
505 The enumerant values defined within the tag:enums tag are used to generate a
510 If the attr:category tag has the values `struct` or `union`, the type is a C
513 the tag:type tag are a series of tag:member tags defining the members of the
518 The tag:member tag defines the type and name of a structure or union member.
522 * attr:values - only valid on the `sType` member of a struct.
523 This is a comma-separated list of enumerant values that are valid for
524 the structure type; usually there is only a single value.
527 another member of that struct; `"null-terminated"` for a string; `"1"`
528 to indicate it is just a pointer (used for nested pointers); or an
529 equation in math markup for incorporation in the specification (a LaTeX
533 * attr:altlen - if the attr:len attribute is specified, and contains a
537 It must be a valid C99 expression whose result is equal to attr:len for
539 It is a comma separated list that has size equal to only the `latexmath`
549 If the member is a pointer to one of those types, multiple values may be
554 `optional="true"`, since there is no requirement that any member of a
555 `pNext` chain have a following member in the chain.
569 If the member is a union, attr:selector identifies another member of the
572 For a member of a union, attr:selection identifies a value of the
583 Specifies the type of a device limit.
584 This type describes how a value might be compared with the value of a
590 indicate the presence of a capability
591 ** `"range"` specifies a [min, max] range
596 values representing a Vulkan obejct handle.
597 Specifies the name of another member which must be a `VkObjectType` or
603 The text elements of a tag:member tag, with all other tags removed, is a
604 legal C declaration of a struct or union member.
608 It contains text which is a valid type name found in another tag:type
615 It contains text which is a valid enumerant name found in another
627 contains text which is legal C code for a type declaration.
632 * tag:apientry/ - insert a platform calling convention macro here during
637 values for a `bitmask` type.
640 There is no restriction on which sorts of definitions may be made in a given
647 Therefore, types in a category should correspond to the intended purpose
668 == Example of a tag:types tag
690 If `VkStruct` is in turn required by a command or another type during header
711 This could also be done using a CDATA block but unless there are many
721 In some cases these correspond to a C `enum`, and in some cases they are
728 This is a historical hangover from the OpenGL XML format which this schema
738 If present, this attribute should match the attr:name attribute of a
745 Integers defining the start and end of a reserved range of enumerants
746 for a particular vendor or purpose.
752 String describing the vendor or purpose to whom a reserved range of
758 If omitted, a default value of 32 is used.
768 <<tag-types:example,An example>> showing a tag with attribute
780 When processed into a C header, and assuming all these tokens were required,
793 Each tag:enum tag defines a single Vulkan (or other API) token.
797 * attr:value is a numeric value in the form of a legal C expression when
799 This is usually either a literal integer value or the name of an alias
800 for a previously defined value, though more complex expressions are
803 * attr:bitpos is a literal integer bit position in a bitmask.
804 The bit position must be in the range [0,30] when used as a flag bit in
805 a `Vk*FlagBits` data type.
811 Enumerant name, a legal C preprocessor token name.
819 In this case, attr:type is optional except when defining a
822 If present the attribute must be a C scalar type corresponding to the
830 have been changed as a result of profile changes or for consistency
832 An enumerant alias is simply a different attr:name for the exact same
845 expected to be a benign change.
858 Each tag:unused tag defines a range of enumerants which is allocated, but
867 be a good way to avoid the attributes becoming out of date.
877 If attr:end is not present, then attr:start defines a single unused
882 String describing the vendor or purposes to whom a reserved range of
915 The tag:command tag contains a structured definition of a single API command
920 There are two ways to define a command.
921 The first uses a set of attributes to the tag:command tag defining
934 as a comma-separated list of Vulkan result code names.
936 A string describing possible error return codes from the command, as a
939 A string identifying whether the command can be issued only inside a
940 render pass (`"inside"`), only outside a render pass (`"outside"`), or
950 The second way of defining a command is as an alias of another command.
975 It is a tag defining the C function prototype of a command as described
980 If a command takes no arguments, it has no tag:param tags.
982 Following these elements, the remaining elements in a tag:command tag are
986 Has no attributes and contains a string which is the name of another
987 command this command is an alias of, used when promoting a function from
994 Contains a list of tag:param tags, each containing asciidoc source text
995 describing an object which is not a parameter of the command but is
1014 The tag:proto tag defines the return type and name of a command.
1027 The text elements of a tag:proto tag, with all other tags removed, is legal
1028 C code describing the return type and name of a command.
1031 * The tag:type tag is optional, and contains text which is a valid type
1032 name found in a tag:type tag.
1044 The tag:param tag defines the type and name of a parameter.
1054 another param of that command; `"null-terminated"` for a string; `"1"`
1055 to indicate it is just a pointer (used for nested pointers); or an
1056 equation in math markup for incorporation in the specification (a LaTeX
1060 * attr:altlen - if the attr:len attribute is specified, and contains a
1064 It must be a valid C99 expression whose result is equal to attr:len for
1066 It is a comma separated list that has size equal to only the `latexmath`
1074 If the parameter is a pointer to one of those types, multiple values may
1091 If the parameter is a union, attr:selector identifies another parameter
1099 A value of `"true"` indicates that this parameter (e.g. the object a
1100 handle refers to, or the contents of an array a pointer refers to) is
1105 Each string describes a member which is modified.
1120 values representing a Vulkan obejct handle.
1121 Specifies the name of another parameter which must be a `VkObjectType`
1127 The text elements of a tag:param tag, with all other tags removed, is legal
1128 C code describing the type and name of a function parameter.
1131 * The tag:type tag is optional, and contains text which is a valid type
1139 == Example of a tag:commands tag
1152 When processed into a C header, this results in
1166 A feature is the set of interfaces (enumerants and commands) defined by a
1179 Feature version number, usually a string interpreted as
1188 An additional preprocessor token used to protect a feature definition.
1190 Rarely used, for odd circumstances where the definition of a feature or
1200 It is used only as a preprocessor guard in the headers, and an asciidoctor
1210 Each tag describes a set of interfaces that is respectively required for, or
1213 == Example of a tag:feature tag
1231 When processed into a C header for Vulkan, this results in:
1271 An extension is the set of interfaces defined by a particular API extension
1274 attr:number attribute, it instead has a attr:supported attribute, which
1292 The author name, such as a full company name.
1295 However, `EXT` and other multi-vendor extensions may not have a
1299 extension (which may have since been promoted to use a different author
1325 requires another extension or a header file to be defined first.
1329 being available, in a platform-specific header, etc.
1337 Interfaces defined in a `disabled` extension block are tentative at best
1343 A Vulkan version or a name of an extension that this extension was
1347 A Vulkan version or a name of an extension that _deprecates_ this
1352 A Vulkan version or a name of an extension that _obsoletes_ this
1360 indicating a special purpose of the extension.
1382 Such functionality should be specified within a tag:require, using the
1390 Each tag describes a set of interfaces that is respectively required for, or
1411 When processed into a C header for the `vulkan` profile, this results in
1450 A tag:require block defines a set of interfaces (types, enumerants and
1451 commands) 'required' by a tag:feature or tag:extension.
1452 A tag:remove block defines a set of interfaces 'removed' by a tag:feature.
1480 tag:feature tags already define a specific API.
1485 These attribues are allowed only for a tag:require tag.
1494 attr:name of a tag:feature tag, and that feature is enabled.
1515 tag:command specifies an required (or removed) command defined in a
1526 tag:enum specifies an required (or removed) enumerant defined in a tag:enums
1543 _Reference enums_ simply pull in the definition of an enumerant given in a
1549 corresponding value is defined in a tag:enums block.
1556 There are a variety of attributes which are used to specify the value of the
1559 * attr:value and attr:type - define a constant value in the same fashion
1561 * attr:bitpos - define a constant bitmask value in the same fashion as an
1563 attr:bitpos is a literal integer bit position in a bitmask.
1566 * attr:extends - the name of a separately defined enumerated type (e.g. a
1570 enumerant, in the same fashion as the attr:requires attribute of a
1572 If not present, the enumerant is treated as a global constant value.
1574 The extension number in turn specifies the starting value of a block
1578 enumerated type in a block defined by a different extension.
1590 An enumerant alias is simply a different name for the same enumerant
1593 extension to a new core version of the API.
1596 It may also be used when token names have been changed as a result of
1598 * attr:protect - define a preprocessor protection symbol for the enum in
1599 the same fashion as a tag:enum tag in an <<tag-enum,tag:enums>> block.
1615 [1]: If attr:extnumber is not present, the tag:enum tag may only be within a
1617 Otherwise, the tag:enum tag may also be within a tag:feature.
1619 [2]: If attr:extends is not present, the enumerant value is a global
1629 tag:type specifies a required (or removed) type defined in a tag:types
1632 but in a few cases, additional types need to be specified explicitly.
1633 It is unlikely that a type would ever be removed, although this usage is
1707 An image format corresponds to a Vulkan `VkFormat` enumerant.
1717 Format name, matching a `VkFormat` tag:enum attr:name.
1721 A string whose value is shared by a group of formats which may be
1722 compatible, and is a textual description of something important that
1729 A decimal integer which is the number of texels in a texel block of the
1732 Three-dimensional extent of a texel block.
1738 If defined, a single image element in this format can be stored in the
1739 same space as a scalar type of this bit width.
1741 A string whose value is shared by a group of formats which use the same
1742 general texture compression scheme, and is a textual description of that
1759 Each tag describes the scale of a specific image plane of the format
1764 Each tag describes a SPIR-V format name corresponding to the tag:format.
1766 == Example of a tag:format tag
1794 Must be either a decimal integer which is the number of bits in this
1795 component, or `"compressed"`, corresponding to a specific compression
1803 …ues using sRGB nonlinear encoding, while the A component (if one exists) is a regular unsigned nor…
1811 If present, must correspond to the attr:index attribute value of a
1852 The tag:spirvimageformat tag specifies the name of a SPIR-V image format
1898 Each tag describes a single enabling mechanism for the extension.
1900 == Example of a tag:spirvextensions tag
1944 Each tag describes a single enabling mechanism for the capability.
1946 == Example of a tag:spirvcapabilities tag
1962 The tag:enable tag describes a single mechanism in the API which enables a
1972 An API feature name, matching a tag:feature attr:name attribute value.
1989 An API feature structure name, matching a tag:struct attr:name attribute
1992 An API feature name, matching a tag:member tag:name value of the feature
2011 An API property structure name, matching a tag:struct attr:name
2014 An API property name, matching a tag:member tag:name value of the
2018 If the property is a bitfield, tag:value must be a bitmask value
2080 This makes it possible to include different API versions and extensions in a
2082 So you must introduce a dependency on new features in the corresponding
2097 These are just being used as a logical grouping mechanism for related parts
2126 The first tag:require block says to require a type named `vk_platform`.
2127 If you look at the beginning of the tag:types section, there is a
2138 This section is invoked by the requirement and emits a bunch of boilerplate
2145 to a collection of freeform preprocessor includes and macros and comments.
2146 Most other tag:type tags do define a specific type and are much simpler, but
2221 This is a structure type, defining a C `struct` with all the members defined
2236 In this case, the type `VkInstance` is defined by a special compile time
2237 macro which defines it as a derived class of `VkObject` (for `C```) or a
2279 … #define VK_DEFINE_PTR_HANDLE(_obj) struct _obj##_T { char _placeholder; }; typedef _obj##_T* _obj;
2280 …#define VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) struct _obj##_T : public _base##_T {}; typedef …
2282 #define VK_DEFINE_BASE_HANDLE(_obj) VK_DEFINE_PTR_HANDLE(_obj)
2283 #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base)
2284 … #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base)
2286 #define VK_DEFINE_BASE_HANDLE(_obj) typedef VkUintPtrLeast64 _obj;
2287 #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) typedef uintptr_t _obj;
2288 #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) typedef VkUintPtrLeast64 _obj;
2362 Add (if not present) a nested tag:require block labelled
2383 In this block, add a tag whose attr:name attribute matches the attr:name you
2399 The attr:value attribute must be a legal C99 constant scalar expression when
2403 * a single C decimal integer or floating-point value
2411 For this example, assume we want to define a type corresponding to a C
2426 If `VkInstanceCreateInfo` is the type of a parameter of a command in the
2427 API, make sure that command's definition (see below for how to add a
2431 Otherwise, if the struct type is not used directly by a command in the API,
2432 nor required by a chain of type dependencies for other commands, an explicit
2442 In this block, add a tag whose attr:name attribute matches the attr:name of
2452 Then go to the tag:types tag and add a new tag:type tag defining the struct
2481 If the type is a C `union`, rather than a `struct`, then set the value of
2487 For this example, assume we want to define a type corresponding to a C
2498 If `VkDeviceCreateFlagBits` is the type of a parameter to a command in the
2499 API, or of a member in a structure or union, make sure that command
2503 Otherwise, if the enumerated type is not used directly by a command in the
2504 API, nor required by a chain of type dependencies for commands and structs,
2529 the individual enumerants represent elements of a bitmask.
2533 In this case, because the enumerants are bits in a bitmask, their values are
2536 specifying a single bit number, and the resulting value is printed as a
2567 Firstly, a definition is needed for the flags type used as a parameter to
2576 At the end of the list of `VkFlags` and `VkFlags64` types, add a definition
2584 The attr:category defines this as a `"bitmask"` type.
2603 This defines a type for the flag bits for generators that need it.
2629 individual enumerants represent elements of a bitmask.
2630 The attr:bitwidth attribute is set to `"64"` indicating that this is a
2635 In this case, a "no flags" type is defined in `VK_EXAMPLE_NONE` with the
2636 attr:value attribute defining it to have a hard value of 0.
2640 specifying a single bit number, and the resulting value is printed as a
2647 Doing so is broadly similar to 64-bit bit flags, but with a few key
2650 corresponding to a C `enum` and flags type defined as follows:
2677 a bitwidth of 32) as follows:
2703 features which the new command should be grouped with, or define a new
2705 For this example, add a new block, and require the command by using the
2719 The tag:require block may include a attr:comment attribute whose value is a
2725 Then go to the tag:commands tag and add a new tag:command tag defining the
2754 The registry schema can represent a good deal of additional information, for
2764 Types and commands are defined using syntax which is a subset of C,
2766 It would be possible to use a language-independent syntax for representing
2767 such information, but since we are writing a C API, any such representation
2826 attribute as introducing a requirement for the enumerated type being
2831 relationship between a Vulkan handle and another member or parameter
2839 * 2021-03-30 - Add a description of the <<compile-time-constants-format,
2860 current usage, including allowing specifying multiple API names for a
2871 to the same entry point in the underlying layer stack, matching a
2915 Add a subsection to the introduction describing the schema choices and
2920 * 2015-12-07 - Move `vulkan/vulkan.h` to a subdirectory.
2930 attr:threadsafe attribute and replace it with a combination of