vulkan: import api from upstream
Imported from 74e25b28dc0e198a69add358d541b25291bcde82, which
corresponds to header version 0.138.0.
Change-Id: Ia9bde11a213527b1c366eb4b82aec8650ca13666
(cherry picked from commit 4e262baf54382c455c191a4c1417dec8d17e8926)
diff --git a/vulkan/api/templates/vk_xml.tmpl b/vulkan/api/templates/vk_xml.tmpl
new file mode 100644
index 0000000..c040938
--- /dev/null
+++ b/vulkan/api/templates/vk_xml.tmpl
@@ -0,0 +1,422 @@
+{{Include "vulkan_common.tmpl"}}
+{{Macro "DefineGlobals" $}}
+{{$ | Macro "vk.xml" | Reflow 4 | Write "vk.xml"}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Entry point
+-------------------------------------------------------------------------------
+*/}}
+{{define "vk.xml"}}
+<?xml version="1.0" encoding="UTF-8"?>
+<registry>
+ »<comment>«
+Copyright (c) 2015 The Khronos Group Inc.
+¶
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and/or associated documentation files (the
+"Materials"), to deal in the Materials without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Materials, and to
+permit persons to whom the Materials are furnished to do so, subject to
+the following conditions:
+¶
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Materials.
+¶
+THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
+¶
+------------------------------------------------------------------------
+¶
+This file, vk.xml, is the Vulkan API Registry.»
+ </comment>
+¶
+ <!-- SECTION: Vulkan type definitions -->
+ <types>»
+ <type name="vk_platform" category="include">#include "vk_platform.h"</type>
+¶
+ <type category="define">#define <name>VK_MAKE_VERSION</name>(major, minor, patch) \
+ «((major << 22) | (minor << 12) | patch)</type>»
+¶
+ <type category="define">// Vulkan API version supported by this file««
+#define <name>VK_API_VERSION</name> <type>VK_MAKE_VERSION</type>({{Global "VERSION_MAJOR"}}, {{Global "VERSION_MINOR"}}, {{Global "VERSION_PATCH"}})</type>
+¶
+ »»<type category="define">««
+#if (_MSC_VER >= 1800 || __cplusplus >= 201103L)
+#define <name>VK_NONDISP_HANDLE_OPERATOR_BOOL</name>() explicit operator bool() const { return handle != 0; }
+#else
+#define VK_NONDISP_HANDLE_OPERATOR_BOOL()
+«#endif
+ »»»</type>
+¶
+ <type category="define">«««
+#define <name>VK_DEFINE_HANDLE</name>(obj) typedef struct obj##_T* obj;</type>
+ »»»<type category="define">«««
+#if defined(__cplusplus)
+ »»#if (_MSC_VER >= 1800 || __cplusplus >= 201103L)
+ »// The bool operator only works if there are no implicit conversions from an obj to
+ // a bool-compatible type, which can then be used to unintentionally violate type safety.
+ // C++11 and above supports the "explicit" keyword on conversion operators to stop this
+ // from happening. Otherwise users of C++ below C++11 won't get direct access to evaluating
+ // the object handle as a bool in expressions like:
+ // if (obj) vkDestroy(obj);
+ #define VK_NONDISP_HANDLE_OPERATOR_BOOL() explicit operator bool() const { return handle != 0; }
+ «#else»
+ #define VK_NONDISP_HANDLE_OPERATOR_BOOL()
+ «#endif
+ #define <name>VK_DEFINE_NONDISP_HANDLE</name>(obj) \»
+ struct obj { \
+ obj() { } \
+ obj(uint64_t x) { handle = x; } \
+ obj& operator =(uint64_t x) { handle = x; return *this; } \
+ bool operator==(const obj& other) const { return handle == other.handle; } \
+ bool operator!=(const obj& other) const { return handle != other.handle; } \
+ bool operator!() const { return !handle; } \
+ VK_NONDISP_HANDLE_OPERATOR_BOOL() \
+ uint64_t handle; \
+ };
+««#else
+ »#define VK_DEFINE_NONDISP_HANDLE(obj) typedef struct obj##_T { uint64_t handle; } obj;«
+#endif
+ »»</type>
+¶
+ <type requires="vk_platform" name="VkDeviceSize"/>
+ <type requires="vk_platform" name="VkSampleMask"/>
+ <type requires="vk_platform" name="VkFlags"/>
+ <!-- Basic C types, pulled in via vk_platform.h -->
+ <type requires="vk_platform" name="char"/>
+ <type requires="vk_platform" name="float"/>
+ <type requires="vk_platform" name="VkBool32"/>
+ <type requires="vk_platform" name="uint8_t"/>
+ <type requires="vk_platform" name="uint32_t"/>
+ <type requires="vk_platform" name="uint64_t"/>
+ <type requires="vk_platform" name="int32_t"/>
+ <type requires="vk_platform" name="size_t"/>
+ <!-- Bitfield types -->
+ {{range $e := $.Enums}}
+ {{if $e.IsBitfield}}
+ {{$bits := print (Macro "EnumName" $e | TrimRight "s") "Bits"}}
+ <type{{if $e.Entries}} requires="{{$bits}}"{{end}} category="bitmask">typedef <type>VkFlags</type> <name>{{$e.Name}}</name>;</type>§
+ {{if $e.Entries}}{{Macro "XML.Docs" $e.Docs}}
+ {{else}}{{Macro "XML.Docs" (Strings $e.Docs "(no bits yet)")}}
+ {{end}}
+ {{end}}
+ {{end}}
+¶
+ <!-- Types which can be void pointers or class pointers, selected at compile time -->
+ {{range $i, $p := $.Pseudonyms}}
+ {{ if (GetAnnotation $p "dispatchHandle")}}
+ {{if Global "VK_DEFINE_HANDLE_TYPE_DEFINED"}}
+ <type category="handle">VK_DEFINE_HANDLE(<name>{{$p.Name}}</name>)</type>
+ {{else}}
+ {{Global "VK_DEFINE_HANDLE_TYPE_DEFINED" "YES"}}
+ <type category="handle"><type>VK_DEFINE_HANDLE</type>(<name>{{$p.Name}}</name>)</type>
+ {{end}}
+ {{else if (GetAnnotation $p "nonDispatchHandle")}}
+ {{if Global "VK_DEFINE_NONDISP_HANDLE_TYPE_DEFINED"}}
+ <type category="handle">VK_DEFINE_NONDISP_HANDLE(<name>{{$p.Name}}</name>)</type>
+ {{else}}
+ {{Global "VK_DEFINE_NONDISP_HANDLE_TYPE_DEFINED" "YES"}}
+ <type category="handle"><type>VK_DEFINE_NONDISP_HANDLE</type>(<name>{{$p.Name}}</name>)</type>
+ {{end}}
+ {{end}}
+ {{end}}
+¶
+ <!-- Types generated from corresponding <enums> tags below -->
+ {{range $e := SortBy $.Enums "EnumName"}}
+ {{if and $e.Entries (not (GetAnnotation $e "internal"))}}
+ {{if $e.IsBitfield}}
+ <type name="{{Macro "EnumName" $e | TrimRight "s"}}Bits" category="enum"/>
+ {{else}}
+ <type name="{{$e.Name}}" category="enum"/>
+ {{end}}
+ {{end}}
+ {{end}}
+¶
+ <!-- The PFN_vk*Function types are used by VkAllocCallbacks below -->
+ <type>typedef void* (VKAPI *<name>PFN_vkAllocFunction</name>)(«
+ void* pUserData,
+ size_t size,
+ size_t alignment,
+ <type>VkSystemAllocType</type> allocType);</type>»
+ <type>typedef void (VKAPI *<name>PFN_vkFreeFunction</name>)(«
+ void* pUserData,
+ void* pMem);</type>»
+¶
+ <!-- The PFN_vkVoidFunction type are used by VkGet*ProcAddr below -->
+ <type>typedef void (VKAPI *<name>PFN_vkVoidFunction</name>)(void);</type>
+¶
+ <!-- Struct types -->
+ {{range $c := $.Classes}}
+ {{if not (GetAnnotation $c "internal")}}
+ {{Macro "Struct" $c}}
+ {{end}}
+ {{end}}
+ «</types>
+¶
+ <!-- SECTION: Vulkan enumerant (token) definitions. -->
+¶
+ <enums namespace="VK" comment="Misc. hardcoded constants - not an enumerated type">»
+ <!-- This is part of the header boilerplate -->
+ {{range $d := $.Definitions}}
+ {{if HasPrefix $d.Name "VK_"}}
+ <enum value="{{$d.Expression}}" name="{{$d.Name}}"/>{{Macro "XML.Docs" $d.Docs}}
+ {{end}}
+ {{end}}
+ <enum value="MAX_FLOAT" name="VK_LOD_CLAMP_NONE"/>
+ <enum value="UINT32_MAX" name="VK_LAST_MIP_LEVEL"/>
+ <enum value="UINT32_MAX" name="VK_LAST_ARRAY_SLICE"/>
+ <enum value="UINT64_MAX" name="VK_WHOLE_SIZE"/>
+ <enum value="UINT32_MAX" name="VK_ATTACHMENT_UNUSED"/>
+ <enum value="UINT32_MAX" name="VK_QUEUE_FAMILY_IGNORED"/>
+ «</enums>
+¶
+ <!-- Unlike OpenGL, most tokens in Vulkan are actual typed enumerants in»
+ their own numeric namespaces. The "name" attribute is the C enum
+ type name, and is pulled in from a <type> definition above
+ (slightly clunky, but retains the type / enum distinction). "type"
+ attributes of "enum" or "bitmask" indicate that these values should
+ be generated inside an appropriate definition. -->«
+¶
+ {{range $e := $.Enums}}
+ {{if not (or $e.IsBitfield (GetAnnotation $e "internal"))}}
+ {{Macro "XML.Enum" $e}}
+ {{end}}
+ {{end}}
+¶
+ <!-- Flags -->
+ {{range $e := $.Enums}}
+ {{if $e.IsBitfield}}
+ {{Macro "XML.Bitfield" $e}}
+ {{end}}
+ {{end}}
+¶
+ <!-- SECTION: Vulkan command definitions -->
+ <commands namespace="vk">»
+ {{range $f := AllCommands $}}
+ {{if not (GetAnnotation $f "pfn")}}
+ {{Macro "XML.Function" $f}}
+ {{end}}
+ {{end}}
+ «</commands>
+¶
+ <!-- SECTION: Vulkan API interface definitions -->
+ <feature api="vulkan" name="VK_VERSION_1_0" number="1.0">»
+ <require comment="Header boilerplate">»
+ <type name="vk_platform"/>
+ «</require>
+ <require comment="API version">»
+ <type name="VK_API_VERSION"/>
+ «</require>
+ <require comment="API constants">»
+ <enum name="VK_LOD_CLAMP_NONE"/>
+ <enum name="VK_LAST_MIP_LEVEL"/>
+ <enum name="VK_LAST_ARRAY_SLICE"/>
+ <enum name="VK_WHOLE_SIZE"/>
+ <enum name="VK_ATTACHMENT_UNUSED"/>
+ <enum name="VK_TRUE"/>
+ <enum name="VK_FALSE"/>
+ <enum name="VK_NULL_HANDLE"/>
+ «</require>
+ <require comment="All functions (TODO: split by type)">»
+ {{range $f := AllCommands $}}
+ {{if not (GetAnnotation $f "pfn")}}
+ <command name="{{$f.Name}}"/>
+ {{end}}
+ {{end}}
+ </require>
+ «<require comment="Types not directly used by the API">»
+ <!-- Include <type name="typename"/> here for e.g. structs that»
+ are not parameter types of commands, but still need to be
+ defined in the API.
+ «-->
+ <type name="VkBufferMemoryBarrier"/>
+ <type name="VkDispatchIndirectCmd"/>
+ <type name="VkDrawIndexedIndirectCmd"/>
+ <type name="VkDrawIndirectCmd"/>
+ <type name="VkImageMemoryBarrier"/>
+ <type name="VkMemoryBarrier"/>
+ «</require>
+ «</feature>
+¶
+ <!-- SECTION: Vulkan extension interface definitions (none yet) -->
+«</registry>
+{{end}}
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the C declaration for the specified bitfield.
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.Bitfield"}}
+ {{AssertType $ "Enum"}}
+
+ {{if $.Entries}}
+ <enums namespace="VK" name="{{Macro "EnumName" $ | TrimRight "s"}}Bits" type="bitmask">»
+ {{range $e := $.Entries}}
+ {{$pos := Bitpos $e.Value}}
+ <enum §
+ {{if gt $pos -1}} bitpos="{{$pos}}" §
+ {{else}}value="{{if $e.Value}}{{printf "0x%.8X" $e.Value}}{{else}}0{{end}}" §
+ {{end}}name="{{Macro "BitfieldEntryName" $e}}" §
+ {{if $d := $e.Docs}} comment="{{$d | JoinWith " "}}"{{end}}/>
+ {{end}}
+ «</enums>
+ {{end}}
+
+{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the C declaration for the specified enum.
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.Enum"}}
+ {{AssertType $ "Enum"}}
+
+ <enums namespace="VK" name="{{Macro "EnumName" $}}" type="enum" §
+ expand="{{Macro "EnumName" $ | SplitPascalCase | Upper | JoinWith "_"}}"{{if $.Docs}} comment="{{$.Docs | JoinWith " "}}"{{end}}>»
+ {{range $i, $e := $.Entries}}
+ <enum value="{{AsSigned $e.Value}}" name="{{Macro "BitfieldEntryName" $e}}"{{if $e.Docs}} comment="{{$e.Docs | JoinWith " "}}"{{end}}/>
+ {{end}}
+ {{if $lu := GetAnnotation $ "lastUnused"}}
+ <unused start="{{index $lu.Arguments 0}}"/>
+ {{end}}
+ «</enums>
+{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the C declaration for the specified class.
+-------------------------------------------------------------------------------
+*/}}
+{{define "Struct"}}
+ {{AssertType $ "Class"}}
+
+ <type category="{{Macro "StructType" $}}" name="{{Macro "StructName" $}}"{{if $.Docs}} comment="{{$.Docs | JoinWith " "}}"{{end}}>»
+ {{range $f := $.Fields}}
+ <member>{{Node "XML.Type" $f}} <name>{{$f.Name}}</name>{{Macro "XML.ArrayPostfix" $f}}</member>{{Macro "XML.Docs" $f.Docs}}
+ {{end}}
+ «</type>
+{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits either 'struct' or 'union' for the specified class.
+-------------------------------------------------------------------------------
+*/}}
+{{define "StructType"}}
+ {{AssertType $ "Class"}}
+
+ {{if GetAnnotation $ "union"}}union{{else}}struct{{end}}
+{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the C function pointer typedef declaration for the specified command.
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.Function"}}
+ {{AssertType $ "Function"}}
+
+ {{$ts := GetAnnotation $ "threadSafety"}}
+ <command{{if $ts}} threadsafe="{{index $ts.Arguments 0}}"{{end}}>»
+ <proto>{{Node "XML.Type" $.Return}} <name>{{$.Name}}</name></proto>
+ {{range $p := $.CallParameters}}
+ <param>{{Node "XML.Type" $p}} <name>{{$p.Name}}{{Macro "ArrayPostfix" $p}}</name></param>
+ {{end}}
+ «</command>
+{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the XML translation for the specified documentation block (string array).
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.Docs"}}
+ {{if $}} <!-- {{JoinWith " " $ | Replace "<" "" | Replace ">" ""}} -->{{end}}
+{{end}}
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the C translation for the specified type.
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.Type.Class" }}<type>{{Macro "StructName" $.Type}}</type>{{end}}
+{{define "XML.Type.Pseudonym" }}<type>{{$.Type.Name}}</type>{{end}}
+{{define "XML.Type.Enum" }}<type>{{$.Type.Name}}</type>{{end}}
+{{define "XML.Type.StaticArray"}}{{Node "XML.Type" $.Type.ValueType}}{{end}}
+{{define "XML.Type.Pointer" }}{{if $.Type.Const}}{{Node "XML.ConstType" $.Type.To}}{{else}}{{Node "XML.Type" $.Type.To}}{{end}}*{{end}}
+{{define "XML.Type.Slice" }}<type>{{Node "XML.Type" $.Type.To}}</type>*{{end}}
+{{define "XML.Type#s8" }}<type>int8_t</type>{{end}}
+{{define "XML.Type#u8" }}<type>uint8_t</type>{{end}}
+{{define "XML.Type#s16" }}<type>int16_t</type>{{end}}
+{{define "XML.Type#u16" }}<type>uint16_t</type>{{end}}
+{{define "XML.Type#s32" }}<type>int32_t</type>{{end}}
+{{define "XML.Type#u32" }}<type>uint32_t</type>{{end}}
+{{define "XML.Type#f32" }}<type>float</type>{{end}}
+{{define "XML.Type#s64" }}<type>int64_t</type>{{end}}
+{{define "XML.Type#u64" }}<type>uint64_t</type>{{end}}
+{{define "XML.Type#f64" }}<type>double</type>{{end}}
+{{define "XML.Type#char" }}<type>char</type>{{end}}
+{{define "XML.Type#void" }}void{{end}}
+
+{{define "XML.ConstType_Default"}}const {{Node "XML.Type" $.Type}}{{end}}
+{{define "XML.ConstType.Pointer"}}{{Node "XML.Type" $.Type}} const{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits a C type and name for the given parameter
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.Parameter"}}
+ {{AssertType $ "Parameter"}}
+
+ <type>{{Macro "ParameterType" $}}</type> <name>{{$.Name}}{{Macro "ArrayPostfix" $}}</name>
+{{end}}
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits a comma-separated list of C type-name paired parameters for the given
+ command.
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.Parameters"}}
+ {{AssertType $ "Function"}}
+
+ {{ForEach $.CallParameters "XML.Parameter" | JoinWith ", "}}
+ {{if not $.CallParameters}}<type>void</type>{{end}}
+{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the fixed-size-array postfix for pseudonym types annotated with @array
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.ArrayPostfix"}}{{Node "XML.ArrayPostfix" $}}{{end}}
+{{define "XML.ArrayPostfix.StaticArray"}}[{{Node "XML.NamedValue" $.Type.SizeExpr}}]{{end}}
+{{define "XML.ArrayPostfix_Default"}}{{end}}
+
+
+{{/*
+-------------------------------------------------------------------------------
+ Emits the value of the given constant, or the <enum> tagged name if existant.
+-------------------------------------------------------------------------------
+*/}}
+{{define "XML.NamedValue.Definition"}}<enum>{{$.Node.Name}}</enum>{{end}}
+{{define "XML.NamedValue.EnumEntry"}}<enum>{{$.Node.Name}}</enum>{{end}}
+{{define "XML.NamedValue_Default"}}{{$.Node}}{{end}}