1{{Include "vulkan_common.tmpl"}}
2{{Macro "DefineGlobals" $}}
3{{$ | Macro "vk.xml" | Reflow 4 | Write "vk.xml"}}
4
5
6{{/*
7-------------------------------------------------------------------------------
8  Entry point
9-------------------------------------------------------------------------------
10*/}}
11{{define "vk.xml"}}
12<?xml version="1.0" encoding="UTF-8"?>
13<registry>
14    »<comment>«
15Copyright (c) 2015 The Khronos Group Inc.
1617Permission is hereby granted, free of charge, to any person obtaining a
18copy of this software and/or associated documentation files (the
19"Materials"), to deal in the Materials without restriction, including
20without limitation the rights to use, copy, modify, merge, publish,
21distribute, sublicense, and/or sell copies of the Materials, and to
22permit persons to whom the Materials are furnished to do so, subject to
23the following conditions:
2425The above copyright notice and this permission notice shall be included
26in all copies or substantial portions of the Materials.
2728THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
29EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
30MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
31IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
32CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
33TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
34MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
3536------------------------------------------------------------------------
3738This file, vk.xml, is the Vulkan API Registry.»
39    </comment>
4041    <!-- SECTION: Vulkan type definitions -->
42    <types>»
43        <type name="vk_platform" category="include">#include "vk_platform.h"</type>
4445        <type category="define">#define <name>VK_MAKE_VERSION</name>(major, minor, patch) \
46    «((major &lt;&lt; 22) | (minor &lt;&lt; 12) | patch)</type>»
4748        <type category="define">// Vulkan API version supported by this file««
49#define <name>VK_API_VERSION</name> <type>VK_MAKE_VERSION</type>({{Global "VERSION_MAJOR"}}, {{Global "VERSION_MINOR"}}, {{Global "VERSION_PATCH"}})</type>
5051        »»<type category="define">««
52#if (_MSC_VER &gt;= 1800 || __cplusplus &gt;= 201103L)
53#define <name>VK_NONDISP_HANDLE_OPERATOR_BOOL</name>() explicit operator bool() const { return handle != 0; }
54#else
55#define VK_NONDISP_HANDLE_OPERATOR_BOOL()
56«#endif
57      »»»</type>
5859      <type category="define">«««
60#define <name>VK_DEFINE_HANDLE</name>(obj) typedef struct obj##_T* obj;</type>
61      »»»<type category="define">«««
62#if defined(__cplusplus)
63    »»#if (_MSC_VER &gt;= 1800 || __cplusplus &gt;= 201103L)
64        »// The bool operator only works if there are no implicit conversions from an obj to
65        // a bool-compatible type, which can then be used to unintentionally violate type safety.
66        // C++11 and above supports the "explicit" keyword on conversion operators to stop this
67        // from happening. Otherwise users of C++ below C++11 won't get direct access to evaluating
68        // the object handle as a bool in expressions like:
69        //     if (obj) vkDestroy(obj);
70        #define VK_NONDISP_HANDLE_OPERATOR_BOOL() explicit operator bool() const { return handle != 0; }
71        #define VK_NONDISP_HANDLE_CONSTRUCTOR_FROM_UINT64(obj) \
72            explicit obj(uint64_t x) : handle(x) { } \
73            obj(decltype(nullptr)) : handle(0) { }
74    «#else»
75        #define VK_NONDISP_HANDLE_OPERATOR_BOOL()
76        #define VK_NONDISP_HANDLE_CONSTRUCTOR_FROM_UINT64(obj) \
77            obj(uint64_t x) : handle(x) { }
78    «#endif
79    #define <name>VK_DEFINE_NONDISP_HANDLE</name>(obj) \»
80        struct obj { \
81            obj() { } \
82            VK_NONDISP_HANDLE_CONSTRUCTOR_FROM_UINT64(obj) \
83            obj&amp; operator =(uint64_t x) { handle = x; return *this; } \
84            bool operator==(const obj&amp; other) const { return handle == other.handle; } \
85            bool operator!=(const obj&amp; other) const { return handle != other.handle; } \
86            bool operator!() const { return !handle; } \
87            VK_NONDISP_HANDLE_OPERATOR_BOOL() \
88            uint64_t handle; \
89        };
90««#else
91    »#define VK_DEFINE_NONDISP_HANDLE(obj) typedef struct obj##_T { uint64_t handle; } obj;«
92#endif
93        »»</type>
9495        <type category="define">
96#if defined(__cplusplus) &amp;&amp; ((defined(_MSC_VER) &amp;&amp; _MSC_VER &gt;= 1800) || __cplusplus &gt;= 201103L)
97    »#define <name>VK_NULL_HANDLE</name> nullptr
98«#else
99    »#define VK_NULL_HANDLE 0
100«#endif
101        »»</type>
102103        <type requires="vk_platform" name="VkDeviceSize"/>
104        <type requires="vk_platform" name="VkSampleMask"/>
105        <type requires="vk_platform" name="VkFlags"/>
106        <!-- Basic C types, pulled in via vk_platform.h -->
107        <type requires="vk_platform" name="char"/>
108        <type requires="vk_platform" name="float"/>
109        <type requires="vk_platform" name="VkBool32"/>
110        <type requires="vk_platform" name="uint8_t"/>
111        <type requires="vk_platform" name="uint32_t"/>
112        <type requires="vk_platform" name="uint64_t"/>
113        <type requires="vk_platform" name="int32_t"/>
114        <type requires="vk_platform" name="size_t"/>
115        <!-- Bitfield types -->
116        {{range $e := $.Enums}}
117          {{if $e.IsBitfield}}
118            {{$bits := print (Macro "EnumName" $e | TrimRight "s") "Bits"}}
119            <type{{if $e.Entries}} requires="{{$bits}}"{{end}} category="bitmask">typedef <type>VkFlags</type> <name>{{$e.Name}}</name>;</type>§
120            {{if $e.Entries}}{{Macro "XML.Docs" $e.Docs}}
121            {{else}}{{Macro "XML.Docs" (Strings $e.Docs "(no bits yet)")}}
122            {{end}}
123          {{end}}
124        {{end}}
125126        <!-- Types which can be void pointers or class pointers, selected at compile time -->
127        {{range $i, $p := $.Pseudonyms}}
128          {{     if (GetAnnotation $p "dispatchHandle")}}
129            {{if Global "VK_DEFINE_HANDLE_TYPE_DEFINED"}}
130              <type category="handle">VK_DEFINE_HANDLE(<name>{{$p.Name}}</name>)</type>
131            {{else}}
132              {{Global "VK_DEFINE_HANDLE_TYPE_DEFINED" "YES"}}
133              <type category="handle"><type>VK_DEFINE_HANDLE</type>(<name>{{$p.Name}}</name>)</type>
134            {{end}}
135          {{else if (GetAnnotation $p "nonDispatchHandle")}}
136            {{if Global "VK_DEFINE_NONDISP_HANDLE_TYPE_DEFINED"}}
137              <type category="handle">VK_DEFINE_NONDISP_HANDLE(<name>{{$p.Name}}</name>)</type>
138            {{else}}
139              {{Global "VK_DEFINE_NONDISP_HANDLE_TYPE_DEFINED" "YES"}}
140              <type category="handle"><type>VK_DEFINE_NONDISP_HANDLE</type>(<name>{{$p.Name}}</name>)</type>
141            {{end}}
142          {{end}}
143        {{end}}
144145        <!-- Types generated from corresponding <enums> tags below -->
146        {{range $e := SortBy $.Enums "EnumName"}}
147          {{if and $e.Entries (not (GetAnnotation $e "internal"))}}
148            {{if $e.IsBitfield}}
149              <type name="{{Macro "EnumName" $e | TrimRight "s"}}Bits" category="enum"/>
150            {{else}}
151              <type name="{{$e.Name}}" category="enum"/>
152            {{end}}
153          {{end}}
154        {{end}}
155156        <!-- The PFN_vk*Function types are used by VkAllocCallbacks below -->
157        <type>typedef void* (VKAPI *<name>PFN_vkAllocFunction</name>)(«
158          void*                           pUserData,
159          size_t                          size,
160          size_t                          alignment,
161          <type>VkSystemAllocType</type>               allocType);</type>»
162        <type>typedef void (VKAPI *<name>PFN_vkFreeFunction</name>)(«
163          void*                           pUserData,
164          void*                           pMem);</type>»
165166        <!-- The PFN_vkVoidFunction type are used by VkGet*ProcAddr below -->
167        <type>typedef void (VKAPI *<name>PFN_vkVoidFunction</name>)(void);</type>
168169        <!-- Struct types -->
170        {{range $c := $.Classes}}
171          {{if not (GetAnnotation $c "internal")}}
172            {{Macro "Struct" $c}}
173          {{end}}
174        {{end}}
175    «</types>
176177    <!-- SECTION: Vulkan enumerant (token) definitions. -->
178179    <enums namespace="VK" comment="Misc. hardcoded constants - not an enumerated type">»
180            <!-- This is part of the header boilerplate -->
181      {{range $d := $.Definitions}}
182        {{if HasPrefix $d.Name "VK_"}}
183        <enum value="{{$d.Expression}}"        name="{{$d.Name}}"/>{{Macro "XML.Docs" $d.Docs}}
184        {{end}}
185      {{end}}
186        <enum value="1000.0f"  name="VK_LOD_CLAMP_NONE"/>
187        <enum value="(-0U)" name="VK_REMAINING_MIP_LEVELS"/>
188        <enum value="(~0U)" name="VK_REMAINING_ARRAY_LAYERS"/>
189        <enum value="(_0ULL)" name="VK_WHOLE_SIZE"/>
190        <enum value="(~0U)" name="VK_ATTACHMENT_UNUSED"/>
191        <enum value="(~0U)" name="VK_QUEUE_FAMILY_IGNORED"/>
192        <enum value="(~0U)" name="VK_SUBPASS_EXTERNAL"/>
193    «</enums>
194195    <!-- Unlike OpenGL, most tokens in Vulkan are actual typed enumerants in»
196         their own numeric namespaces. The "name" attribute is the C enum
197         type name, and is pulled in from a <type> definition above
198         (slightly clunky, but retains the type / enum distinction). "type"
199         attributes of "enum" or "bitmask" indicate that these values should
200         be generated inside an appropriate definition. -->«
201202    {{range $e := $.Enums}}
203      {{if not (or $e.IsBitfield (GetAnnotation $e "internal"))}}
204        {{Macro "XML.Enum" $e}}
205      {{end}}
206    {{end}}
207208    <!-- Flags -->
209    {{range $e := $.Enums}}
210      {{if $e.IsBitfield}}
211        {{Macro "XML.Bitfield" $e}}
212      {{end}}
213    {{end}}
214215    <!-- SECTION: Vulkan command definitions -->
216    <commands namespace="vk">»
217    {{range $f := AllCommands $}}
218      {{if not (GetAnnotation $f "pfn")}}
219        {{Macro "XML.Function" $f}}
220      {{end}}
221    {{end}}
222    «</commands>
223224    <!-- SECTION: Vulkan API interface definitions -->
225    <feature api="vulkan" name="VK_VERSION_1_0" number="1.0">»
226        <require comment="Header boilerplate">»
227            <type name="vk_platform"/>
228        «</require>
229        <require comment="API version">»
230            <type name="VK_API_VERSION"/>
231        «</require>
232        <require comment="API constants">»
233            <enum name="VK_LOD_CLAMP_NONE"/>
234            <enum name="VK_REMAINING_MIP_LEVELS"/>
235            <enum name="VK_REMAINING_ARRAY_LAYERS"/>
236            <enum name="VK_WHOLE_SIZE"/>
237            <enum name="VK_ATTACHMENT_UNUSED"/>
238            <enum name="VK_TRUE"/>
239            <enum name="VK_FALSE"/>
240        «</require>
241        <require comment="All functions (TODO: split by type)">»
242        {{range $f := AllCommands $}}
243          {{if not (GetAnnotation $f "pfn")}}
244          <command name="{{$f.Name}}"/>
245          {{end}}
246        {{end}}
247        </require>
248        «<require comment="Types not directly used by the API">»
249            <!-- Include <type name="typename"/> here for e.g. structs that»
250                 are not parameter types of commands, but still need to be
251                 defined in the API.
252             «-->
253            <type name="VkBufferMemoryBarrier"/>
254            <type name="VkDispatchIndirectCmd"/>
255            <type name="VkDrawIndexedIndirectCmd"/>
256            <type name="VkDrawIndirectCmd"/>
257            <type name="VkImageMemoryBarrier"/>
258            <type name="VkMemoryBarrier"/>
259        «</require>
260    «</feature>
261262    <!-- SECTION: Vulkan extension interface definitions (none yet) -->
263«</registry>
264{{end}}
265
266{{/*
267-------------------------------------------------------------------------------
268  Emits the C declaration for the specified bitfield.
269-------------------------------------------------------------------------------
270*/}}
271{{define "XML.Bitfield"}}
272  {{AssertType $ "Enum"}}
273
274  {{if $.Entries}}
275  <enums namespace="VK" name="{{Macro "EnumName" $ | TrimRight "s"}}Bits" type="bitmask">»
276  {{range $e := $.Entries}}
277    {{$pos := Bitpos $e.Value}}
278    <enum §
279      {{if gt $pos -1}} bitpos="{{$pos}}"    §
280      {{else}}value="{{if $e.Value}}{{printf "0x%.8X" $e.Value}}{{else}}0{{end}}"    §
281      {{end}}name="{{Macro "BitfieldEntryName" $e}}" §
282      {{if $d := $e.Docs}} comment="{{$d | JoinWith "  "}}"{{end}}/>
283  {{end}}
284  «</enums>
285  {{end}}
286
287{{end}}
288
289
290{{/*
291-------------------------------------------------------------------------------
292  Emits the C declaration for the specified enum.
293-------------------------------------------------------------------------------
294*/}}
295{{define "XML.Enum"}}
296  {{AssertType $ "Enum"}}
297
298  <enums namespace="VK" name="{{Macro "EnumName" $}}" type="enum" §
299         expand="{{Macro "EnumName" $ | SplitPascalCase | Upper | JoinWith "_"}}"{{if $.Docs}} comment="{{$.Docs | JoinWith "  "}}"{{end}}>»
300  {{range $i, $e := $.Entries}}
301    <enum value="{{AsSigned $e.Value}}"     name="{{Macro "BitfieldEntryName" $e}}"{{if $e.Docs}} comment="{{$e.Docs | JoinWith "  "}}"{{end}}/>
302  {{end}}
303  {{if $lu := GetAnnotation $ "lastUnused"}}
304    <unused start="{{index $lu.Arguments 0}}"/>
305  {{end}}
306  «</enums>
307{{end}}
308
309
310{{/*
311-------------------------------------------------------------------------------
312  Emits the C declaration for the specified class.
313-------------------------------------------------------------------------------
314*/}}
315{{define "Struct"}}
316  {{AssertType $ "Class"}}
317
318  <type category="{{Macro "StructType" $}}" name="{{Macro "StructName" $}}"{{if $.Docs}} comment="{{$.Docs | JoinWith "  "}}"{{end}}>»
319    {{range $f := $.Fields}}
320    <member>{{Node "XML.Type" $f}}        <name>{{$f.Name}}</name>{{Macro "XML.ArrayPostfix" $f}}</member>{{Macro "XML.Docs" $f.Docs}}
321    {{end}}
322  «</type>
323{{end}}
324
325
326{{/*
327-------------------------------------------------------------------------------
328  Emits either 'struct' or 'union' for the specified class.
329-------------------------------------------------------------------------------
330*/}}
331{{define "StructType"}}
332  {{AssertType $ "Class"}}
333
334  {{if GetAnnotation $ "union"}}union{{else}}struct{{end}}
335{{end}}
336
337
338{{/*
339-------------------------------------------------------------------------------
340  Emits the C function pointer typedef declaration for the specified command.
341-------------------------------------------------------------------------------
342*/}}
343{{define "XML.Function"}}
344  {{AssertType $ "Function"}}
345
346    {{$ts := GetAnnotation $ "threadSafety"}}
347    <command{{if $ts}} threadsafe="{{index $ts.Arguments 0}}"{{end}}>»
348        <proto>{{Node "XML.Type" $.Return}} <name>{{$.Name}}</name></proto>
349        {{range $p := $.CallParameters}}
350          <param>{{Node "XML.Type" $p}} <name>{{$p.Name}}{{Macro "ArrayPostfix" $p}}</name></param>
351        {{end}}
352    «</command>
353{{end}}
354
355
356{{/*
357-------------------------------------------------------------------------------
358  Emits the XML translation for the specified documentation block (string array).
359-------------------------------------------------------------------------------
360*/}}
361{{define "XML.Docs"}}
362  {{if $}} <!-- {{JoinWith "  " $ | Replace "<" "" | Replace ">" ""}} -->{{end}}
363{{end}}
364
365{{/*
366-------------------------------------------------------------------------------
367  Emits the C translation for the specified type.
368-------------------------------------------------------------------------------
369*/}}
370{{define "XML.Type.Class"      }}<type>{{Macro "StructName" $.Type}}</type>{{end}}
371{{define "XML.Type.Pseudonym"  }}<type>{{$.Type.Name}}</type>{{end}}
372{{define "XML.Type.Enum"       }}<type>{{$.Type.Name}}</type>{{end}}
373{{define "XML.Type.StaticArray"}}{{Node "XML.Type" $.Type.ValueType}}{{end}}
374{{define "XML.Type.Pointer"    }}{{if $.Type.Const}}{{Node "XML.ConstType" $.Type.To}}{{else}}{{Node "XML.Type" $.Type.To}}{{end}}*{{end}}
375{{define "XML.Type.Slice"      }}<type>{{Node "XML.Type" $.Type.To}}</type>*{{end}}
376{{define "XML.Type#s8"         }}<type>int8_t</type>{{end}}
377{{define "XML.Type#u8"         }}<type>uint8_t</type>{{end}}
378{{define "XML.Type#s16"        }}<type>int16_t</type>{{end}}
379{{define "XML.Type#u16"        }}<type>uint16_t</type>{{end}}
380{{define "XML.Type#s32"        }}<type>int32_t</type>{{end}}
381{{define "XML.Type#u32"        }}<type>uint32_t</type>{{end}}
382{{define "XML.Type#f32"        }}<type>float</type>{{end}}
383{{define "XML.Type#s64"        }}<type>int64_t</type>{{end}}
384{{define "XML.Type#u64"        }}<type>uint64_t</type>{{end}}
385{{define "XML.Type#f64"        }}<type>double</type>{{end}}
386{{define "XML.Type#char"       }}<type>char</type>{{end}}
387{{define "XML.Type#void"       }}void{{end}}
388
389{{define "XML.ConstType_Default"}}const {{Node "XML.Type" $.Type}}{{end}}
390{{define "XML.ConstType.Pointer"}}{{Node "XML.Type" $.Type}} const{{end}}
391
392
393{{/*
394-------------------------------------------------------------------------------
395  Emits a C type and name for the given parameter
396-------------------------------------------------------------------------------
397*/}}
398{{define "XML.Parameter"}}
399  {{AssertType $ "Parameter"}}
400
401  <type>{{Macro "ParameterType" $}}</type> <name>{{$.Name}}{{Macro "ArrayPostfix" $}}</name>
402{{end}}
403
404{{/*
405-------------------------------------------------------------------------------
406  Emits a comma-separated list of C type-name paired parameters for the given
407  command.
408-------------------------------------------------------------------------------
409*/}}
410{{define "XML.Parameters"}}
411  {{AssertType $ "Function"}}
412
413  {{ForEach $.CallParameters "XML.Parameter" | JoinWith ", "}}
414  {{if not $.CallParameters}}<type>void</type>{{end}}
415{{end}}
416
417
418{{/*
419-------------------------------------------------------------------------------
420  Emits the fixed-size-array postfix for pseudonym types annotated with @array
421-------------------------------------------------------------------------------
422*/}}
423{{define "XML.ArrayPostfix"}}{{Node "XML.ArrayPostfix" $}}{{end}}
424{{define "XML.ArrayPostfix.StaticArray"}}[{{Node "XML.NamedValue" $.Type.SizeExpr}}]{{end}}
425{{define "XML.ArrayPostfix_Default"}}{{end}}
426
427
428{{/*
429-------------------------------------------------------------------------------
430  Emits the value of the given constant, or the <enum> tagged name if existant.
431-------------------------------------------------------------------------------
432*/}}
433{{define "XML.NamedValue.Definition"}}<enum>{{$.Node.Name}}</enum>{{end}}
434{{define "XML.NamedValue.EnumEntry"}}<enum>{{$.Node.Name}}</enum>{{end}}
435{{define "XML.NamedValue_Default"}}{{$.Node}}{{end}}
436