Home | History | Annotate | Download | only in templates 
      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>
     15 Copyright (c) 2015 The Khronos Group Inc.
     16 
     17 Permission is hereby granted, free of charge, to any person obtaining a
     18 copy of this software and/or associated documentation files (the
     19 "Materials"), to deal in the Materials without restriction, including
     20 without limitation the rights to use, copy, modify, merge, publish,
     21 distribute, sublicense, and/or sell copies of the Materials, and to
     22 permit persons to whom the Materials are furnished to do so, subject to
     23 the following conditions:
     24 
     25 The above copyright notice and this permission notice shall be included
     26 in all copies or substantial portions of the Materials.
     27 
     28 THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
     29 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
     30 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
     31 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
     32 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
     33 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
     34 MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
     35 
     36 ------------------------------------------------------------------------
     37 
     38 This file, vk.xml, is the Vulkan API Registry.
     39     </comment>
     40 
     41     <!-- SECTION: Vulkan type definitions -->
     42     <types>
     43         <type name="vk_platform" category="include">#include "vk_platform.h"</type>
     44 
     45         <type category="define">#define <name>VK_MAKE_VERSION</name>(major, minor, patch) \
     46     ((major &lt;&lt; 22) | (minor &lt;&lt; 12) | patch)</type>
     47 
     48         <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>
     50 
     51         <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>
     58 
     59       <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>
     94 
     95         <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>
    102 
    103         <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}}
    125 
    126         <!-- 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}}
    144 
    145         <!-- 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}}
    155 
    156         <!-- 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>
    165 
    166         <!-- The PFN_vkVoidFunction type are used by VkGet*ProcAddr below -->
    167         <type>typedef void (VKAPI *<name>PFN_vkVoidFunction</name>)(void);</type>
    168 
    169         <!-- Struct types -->
    170         {{range $c := $.Classes}}
    171           {{if not (GetAnnotation $c "internal")}}
    172             {{Macro "Struct" $c}}
    173           {{end}}
    174         {{end}}
    175     </types>
    176 
    177     <!-- SECTION: Vulkan enumerant (token) definitions. -->
    178 
    179     <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>
    194 
    195     <!-- 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. -->
    201 
    202     {{range $e := $.Enums}}
    203       {{if not (or $e.IsBitfield (GetAnnotation $e "internal"))}}
    204         {{Macro "XML.Enum" $e}}
    205       {{end}}
    206     {{end}}
    207 
    208     <!-- Flags -->
    209     {{range $e := $.Enums}}
    210       {{if $e.IsBitfield}}
    211         {{Macro "XML.Bitfield" $e}}
    212       {{end}}
    213     {{end}}
    214 
    215     <!-- 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>
    223 
    224     <!-- 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>
    261 
    262     <!-- 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