1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[extendingvulkan]] 6= Extending Vulkan 7 8New functionality may: be added to Vulkan via either new extensions or new 9versions of the core, or new versions of an extension in some cases. 10 11This chapter describes how Vulkan is versioned, how compatibility is 12affected between different versions, and compatibility rules that are 13followed by the Vulkan Working Group. 14 15 16[[extendingvulkan-instanceanddevicefunctionality]] 17== Instance and Device Functionality 18 19Commands that enumerate instance properties, or that accept a 20slink:VkInstance object as a parameter, are considered instance-level 21functionality. 22 23Commands that dispatch from a slink:VkDevice object or a child object of a 24slink:VkDevice, or take any of them as a parameter, are considered 25device-level functionality. 26Types defined by a <<extendingvulkan-device-extensions,device extension>> 27are also considered device-level functionality. 28 29Commands that dispatch from slink:VkPhysicalDevice, or accept a 30slink:VkPhysicalDevice object as a parameter, are considered either 31instance-level or device-level functionality depending if the functionality 32is specified by an <<extendingvulkan-instance-extensions,instance 33extension>> or <<extendingvulkan-device-extensions,device extension>> 34respectively. 35 36ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 37Additionally, commands that enumerate physical device properties are 38considered device-level functionality. 39endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 40 41ifdef::VK_VERSION_1_1[] 42[NOTE] 43.Note 44==== 45Applications usually interface to Vulkan using a loader that implements only 46instance-level functionality, passing device-level functionality to 47implementations of the full Vulkan API on the system. 48In some circumstances, as these may be implemented independently, it is 49possible that the loader and device implementations on a given installation 50will support different versions. 51To allow for this and call out when it happens, the Vulkan specification 52enumerates device and instance level functionality separately - they have 53<<extendingvulkan-coreversions-queryingversionsupport,independent version 54queries>>. 55==== 56endif::VK_VERSION_1_1[] 57 58ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 59[NOTE] 60.Note 61==== 62Vulkan 1.0 initially specified new physical device enumeration functionality 63as instance-level, requiring it to be included in an instance extension. 64As the capabilities of device-level functionality require discovery via 65physical device enumeration, this led to the situation where many device 66extensions required an instance extension as well. 67To alleviate this extra work, 68`apiext:VK_KHR_get_physical_device_properties2` (and subsequently Vulkan 691.1) redefined device-level functionality to include physical device 70enumeration. 71==== 72endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 73 74 75[[extendingvulkan-coreversions]] 76== Core Versions 77 78The Vulkan Specification is regularly updated with bug fixes and 79clarifications. 80Occasionally new functionality is added to the core and at some point it is 81expected that there will be a desire to perform a large, breaking change to 82the API. 83In order to indicate to developers how and when these changes are made to 84the specification, and to provide a way to identify each set of changes, the 85Vulkan API maintains a version number. 86 87 88[[extendingvulkan-coreversions-versionnumbers]] 89=== Version Numbers 90 91The Vulkan version number comprises four parts indicating the variant, 92major, minor and patch version of the Vulkan API Specification. 93 94The _variant_ indicates the variant of the Vulkan API supported by the 95implementation. 96ifndef::VKSC_VERSION_1_0[] 97This is always 0 for the Vulkan API. 98endif::VKSC_VERSION_1_0[] 99ifdef::VKSC_VERSION_1_0[] 100This is always 1 for the Vulkan SC API. 101The Base Vulkan API is variant 0. 102endif::VKSC_VERSION_1_0[] 103 104[NOTE] 105.Note 106==== 107A non-zero variant indicates the API is a variant of the Vulkan API and 108applications will typically need to be modified to run against it. 109The variant field was a later addition to the version number, added in 110version 1.2.175 of the 111ifdef::VKSC_VERSION_1_0[Base Vulkan] 112Specification. 113ifndef::VKSC_VERSION_1_0[] 114As Vulkan uses variant 0, this change is fully backwards compatible with the 115previous version number format for Vulkan implementations. 116New version number macros have been added for this change and the old macros 117deprecated. 118For existing applications using the older format and macros, an 119implementation with non-zero variant will decode as a very high Vulkan 120version. 121The high version number should be detectable by applications performing 122suitable version checking. 123endif::VKSC_VERSION_1_0[] 124==== 125 126The _major version_ indicates a significant change in the API, which will 127encompass a wholly new version of the specification. 128 129The _minor version_ indicates the incorporation of new functionality into 130the core specification. 131 132The _patch version_ indicates bug fixes, clarifications, and language 133improvements have been incorporated into the specification. 134 135Compatibility guarantees made about versions of the API sharing any of the 136same version numbers are documented in 137<<extendingvulkan-compatibility-coreversions>> 138 139The version number is used in several places in the API. 140In each such use, the version numbers are packed into a 32-bit integer as 141follows: 142 143 * The variant is a 3-bit integer packed into bits 31-29. 144 * The major version is a 7-bit integer packed into bits 28-22. 145 * The minor version number is a 10-bit integer packed into bits 21-12. 146 * The patch version number is a 12-bit integer packed into bits 11-0. 147 148[open,refpage='VK_API_VERSION_VARIANT',desc='Extract API variant number',type='defines'] 149-- 150dname:VK_API_VERSION_VARIANT extracts the API variant number from a packed 151version number: 152 153include::{generated}/api/defines/VK_API_VERSION_VARIANT.adoc[] 154-- 155 156[open,refpage='VK_API_VERSION_MAJOR',desc='Extract API major version number',type='defines'] 157-- 158dname:VK_API_VERSION_MAJOR extracts the API major version number from a 159packed version number: 160 161include::{generated}/api/defines/VK_API_VERSION_MAJOR.adoc[] 162-- 163 164ifndef::VKSC_VERSION_1_0[] 165[open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines'] 166-- 167dname:VK_VERSION_MAJOR extracts the API major version number from a packed 168version number: 169 170include::{generated}/api/defines/VK_VERSION_MAJOR.adoc[] 171-- 172endif::VKSC_VERSION_1_0[] 173 174[open,refpage='VK_API_VERSION_MINOR',desc='Extract API minor version number',type='defines'] 175-- 176dname:VK_API_VERSION_MINOR extracts the API minor version number from a 177packed version number: 178 179include::{generated}/api/defines/VK_API_VERSION_MINOR.adoc[] 180-- 181 182ifndef::VKSC_VERSION_1_0[] 183[open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines'] 184-- 185dname:VK_VERSION_MINOR extracts the API minor version number from a packed 186version number: 187 188include::{generated}/api/defines/VK_VERSION_MINOR.adoc[] 189-- 190endif::VKSC_VERSION_1_0[] 191 192[open,refpage='VK_API_VERSION_PATCH',desc='Extract API patch version number',type='defines'] 193-- 194dname:VK_API_VERSION_PATCH extracts the API patch version number from a 195packed version number: 196 197include::{generated}/api/defines/VK_API_VERSION_PATCH.adoc[] 198-- 199 200ifndef::VKSC_VERSION_1_0[] 201[open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines'] 202-- 203dname:VK_VERSION_PATCH extracts the API patch version number from a packed 204version number: 205 206include::{generated}/api/defines/VK_VERSION_PATCH.adoc[] 207-- 208endif::VKSC_VERSION_1_0[] 209 210[open,refpage='VK_MAKE_API_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance'] 211-- 212dname:VK_MAKE_API_VERSION constructs an API version number. 213 214include::{generated}/api/defines/VK_MAKE_API_VERSION.adoc[] 215 216 * pname:variant is the variant number. 217 * pname:major is the major version number. 218 * pname:minor is the minor version number. 219 * pname:patch is the patch version number. 220-- 221 222ifndef::VKSC_VERSION_1_0[] 223[open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance'] 224-- 225dname:VK_MAKE_VERSION constructs an API version number. 226 227include::{generated}/api/defines/VK_MAKE_VERSION.adoc[] 228 229 * pname:major is the major version number. 230 * pname:minor is the minor version number. 231 * pname:patch is the patch version number. 232-- 233endif::VKSC_VERSION_1_0[] 234 235[open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 236-- 237dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.0. 238 239include::{generated}/api/defines/VK_API_VERSION_1_0.adoc[] 240-- 241 242ifdef::VK_VERSION_1_1[] 243[open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 244-- 245dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.0. 246 247include::{generated}/api/defines/VK_API_VERSION_1_1.adoc[] 248-- 249endif::VK_VERSION_1_1[] 250 251ifdef::VK_VERSION_1_2[] 252[open,refpage='VK_API_VERSION_1_2',desc='Return API version number for Vulkan 1.2',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 253-- 254dname:VK_API_VERSION_1_2 returns the API version number for Vulkan 1.2.0. 255 256include::{generated}/api/defines/VK_API_VERSION_1_2.adoc[] 257-- 258endif::VK_VERSION_1_2[] 259 260ifdef::VK_VERSION_1_3[] 261[open,refpage='VK_API_VERSION_1_3',desc='Return API version number for Vulkan 1.3',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 262-- 263dname:VK_API_VERSION_1_3 returns the API version number for Vulkan 1.3.0. 264 265include::{generated}/api/defines/VK_API_VERSION_1_3.adoc[] 266-- 267endif::VK_VERSION_1_3[] 268 269ifdef::VKSC_VERSION_1_0[] 270[open,refpage='VKSC_API_VARIANT',desc='Returns the API variant number for Vulkan SC',type='defines'] 271-- 272dname:VKSC_API_VARIANT returns the API variant number for Vulkan SC. 273 274include::{generated}/api/defines/VKSC_API_VARIANT.adoc[] 275-- 276 277[open,refpage='VKSC_API_VERSION_1_0',desc='Return API version number for Vulkan SC 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 278-- 279dname:VKSC_API_VERSION_1_0 returns the API version number for Vulkan SC 2801.0.0. 281 282include::{generated}/api/defines/VKSC_API_VERSION_1_0.adoc[] 283-- 284endif::VKSC_VERSION_1_0[] 285 286 287[[extendingvulkan-coreversions-queryingversionsupport]] 288=== Querying Version Support 289 290ifndef::VK_VERSION_1_1[] 291[NOTE] 292.Note 293==== 294In Vulkan 1.0, there is no mechanism to detect the separate versions of 295<<extendingvulkan-instanceanddevicefunctionality,instance-level and 296device-level functionality>> supported. 297However, the fname:vkEnumerateInstanceVersion command was added in Vulkan 2981.1 to determine the supported version of instance-level functionality - 299querying for this function via flink:vkGetInstanceProcAddr will return 300`NULL` on implementations that only support Vulkan 1.0 functionality. 301For more information on this, please refer to the Vulkan 1.1 specification. 302==== 303endif::VK_VERSION_1_1[] 304 305ifdef::VK_VERSION_1_1[] 306The version of instance-level functionality can be queried by calling 307flink:vkEnumerateInstanceVersion. 308endif::VK_VERSION_1_1[] 309 310The version of device-level functionality can be queried by calling 311flink:vkGetPhysicalDeviceProperties 312ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 313or flink:vkGetPhysicalDeviceProperties2, 314endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 315and is returned in slink:VkPhysicalDeviceProperties::pname:apiVersion, 316encoded as described in <<extendingvulkan-coreversions-versionnumbers>>. 317 318 319[[extendingvulkan-layers]] 320== Layers 321 322When a layer is enabled, it inserts itself into the call chain for Vulkan 323commands the layer is interested in. 324Layers can: be used for a variety of tasks that extend the base behavior of 325Vulkan beyond what is required by the specification - such as call logging, 326tracing, validation, or providing additional extensions. 327 328[NOTE] 329.Note 330==== 331For example, an implementation is not expected to check that the value of 332enums used by the application fall within allowed ranges. 333Instead, a validation layer would do those checks and flag issues. 334This avoids a performance penalty during production use of the application 335because those layers would not be enabled in production. 336==== 337 338[NOTE] 339.Note 340==== 341Vulkan layers may: wrap object handles (i.e. return a different handle value 342to the application than that generated by the implementation). 343This is generally discouraged, as it increases the probability of 344incompatibilities with new extensions. 345The validation layers wrap handles in order to track the proper use and 346destruction of each object. 347See the <<LoaderInterfaceArchitecture, "`Architecture of the Vulkan Loader 348Interfaces`">> document for additional information. 349==== 350 351[open,refpage='vkEnumerateInstanceLayerProperties',desc='Returns up to requested number of global layer properties',type='protos'] 352-- 353To query the available layers, call: 354 355include::{generated}/api/protos/vkEnumerateInstanceLayerProperties.adoc[] 356 357 * pname:pPropertyCount is a pointer to an integer related to the number of 358 layer properties available or queried, as described below. 359 * pname:pProperties is either `NULL` or a pointer to an array of 360 slink:VkLayerProperties structures. 361 362If pname:pProperties is `NULL`, then the number of layer properties 363available is returned in pname:pPropertyCount. 364Otherwise, pname:pPropertyCount must: point to a variable set by the user to 365the number of elements in the pname:pProperties array, and on return the 366variable is overwritten with the number of structures actually written to 367pname:pProperties. 368If pname:pPropertyCount is less than the number of layer properties 369available, at most pname:pPropertyCount structures will be written, and 370ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 371indicate that not all the available properties were returned. 372 373The list of available layers may change at any time due to actions outside 374of the Vulkan implementation, so two calls to 375fname:vkEnumerateInstanceLayerProperties with the same parameters may: 376return different results, or retrieve different pname:pPropertyCount values 377or pname:pProperties contents. 378Once an instance has been created, the layers enabled for that instance will 379continue to be enabled and valid for the lifetime of that instance, even if 380some of them become unavailable for future instances. 381 382include::{generated}/validity/protos/vkEnumerateInstanceLayerProperties.adoc[] 383-- 384 385[open,refpage='VkLayerProperties',desc='Structure specifying layer properties',type='structs'] 386-- 387The sname:VkLayerProperties structure is defined as: 388 389include::{generated}/api/structs/VkLayerProperties.adoc[] 390 391 * pname:layerName is an array of ename:VK_MAX_EXTENSION_NAME_SIZE 392 code:char containing a null-terminated UTF-8 string which is the name of 393 the layer. 394 Use this name in the pname:ppEnabledLayerNames array passed in the 395 slink:VkInstanceCreateInfo structure to enable this layer for an 396 instance. 397 * pname:specVersion is the Vulkan version the layer was written to, 398 encoded as described in <<extendingvulkan-coreversions-versionnumbers>>. 399 * pname:implementationVersion is the version of this layer. 400 It is an integer, increasing with backward compatible changes. 401 * pname:description is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char 402 containing a null-terminated UTF-8 string which provides additional 403 details that can: be used by the application to identify the layer. 404 405include::{generated}/validity/structs/VkLayerProperties.adoc[] 406-- 407 408[open,refpage='VK_MAX_EXTENSION_NAME_SIZE',desc='Maximum length of a layer of extension name string',type='consts'] 409-- 410ename:VK_MAX_EXTENSION_NAME_SIZE is the length in code:char values of an 411array containing a layer or extension name string, as returned in 412slink:VkLayerProperties::pname:layerName, 413slink:VkExtensionProperties::pname:extensionName, and other queries. 414 415include::{generated}/api/enums/VK_MAX_EXTENSION_NAME_SIZE.adoc[] 416-- 417 418[open,refpage='VK_MAX_DESCRIPTION_SIZE',desc='Length of a driver name string',type='consts'] 419-- 420ename:VK_MAX_DESCRIPTION_SIZE is the length in code:char values of an array 421containing a string with additional descriptive information about a query, 422as returned in slink:VkLayerProperties::pname:description and other queries. 423 424include::{generated}/api/enums/VK_MAX_DESCRIPTION_SIZE.adoc[] 425-- 426 427To enable a layer, the name of the layer should: be added to the 428pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating 429a sname:VkInstance. 430 431Loader implementations may: provide mechanisms outside the Vulkan API for 432enabling specific layers. 433Layers enabled through such a mechanism are _implicitly enabled_, while 434layers enabled by including the layer name in the pname:ppEnabledLayerNames 435member of slink:VkInstanceCreateInfo are _explicitly enabled_. 436Implicitly enabled layers are loaded before explicitly enabled layers, such 437that implicitly enabled layers are closer to the application, and explicitly 438enabled layers are closer to the driver. 439Except where otherwise specified, implicitly enabled and explicitly enabled 440layers differ only in the way they are enabled, and the order in which they 441are loaded. 442Explicitly enabling a layer that is implicitly enabled results in this layer 443being loaded as an implicitly enabled layer; it has no additional effect. 444 445 446[[extendingvulkan-layers-devicelayerdeprecation]] 447=== Device Layer Deprecation 448 449Previous versions of this specification distinguished between instance and 450device layers. 451Instance layers were only able to intercept commands that operate on 452sname:VkInstance and sname:VkPhysicalDevice, except they were not able to 453intercept flink:vkCreateDevice. 454Device layers were enabled for individual devices when they were created, 455and could only intercept commands operating on that device or its child 456objects. 457 458Device-only layers are now deprecated, and this specification no longer 459distinguishes between instance and device layers. 460Layers are enabled during instance creation, and are able to intercept all 461commands operating on that instance or any of its child objects. 462At the time of deprecation there were no known device-only layers and no 463compelling reason to create one. 464 465ifndef::VKSC_VERSION_1_0[] 466In order to maintain compatibility with implementations released prior to 467device-layer deprecation, applications should: still enumerate and enable 468device layers. 469The behavior of fname:vkEnumerateDeviceLayerProperties and valid usage of 470the pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo maximizes 471compatibility with applications written to work with the previous 472requirements. 473endif::VKSC_VERSION_1_0[] 474 475[open,refpage='vkEnumerateDeviceLayerProperties',desc='Returns properties of available physical device layers',type='protos'] 476-- 477:refpage: vkEnumerateDeviceLayerProperties 478 479To enumerate device layers, call: 480 481include::{generated}/api/protos/vkEnumerateDeviceLayerProperties.adoc[] 482 483 * pname:physicalDevice is the physical device that will be queried. 484 * pname:pPropertyCount is a pointer to an integer related to the number of 485 layer properties available or queried. 486 * pname:pProperties is either `NULL` or a pointer to an array of 487 slink:VkLayerProperties structures. 488 489ifndef::VKSC_VERSION_1_0[] 490If pname:pProperties is `NULL`, then the number of layer properties 491available is returned in pname:pPropertyCount. 492Otherwise, pname:pPropertyCount must: point to a variable set by the user to 493the number of elements in the pname:pProperties array, and on return the 494variable is overwritten with the number of structures actually written to 495pname:pProperties. 496If pname:pPropertyCount is less than the number of layer properties 497available, at most pname:pPropertyCount structures will be written, and 498ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 499indicate that not all the available properties were returned. 500 501The list of layers enumerated by fname:vkEnumerateDeviceLayerProperties 502must: be exactly the sequence of layers enabled for the instance. 503The members of sname:VkLayerProperties for each enumerated layer must: be 504the same as the properties when the layer was enumerated by 505fname:vkEnumerateInstanceLayerProperties. 506 507[NOTE] 508.Note 509==== 510Due to platform details on Android, fname:vkEnumerateDeviceLayerProperties 511may be called with pname:physicalDevice equal to `NULL` during layer 512discovery. 513This behaviour will only be observed by layer implementations, and not the 514underlying Vulkan driver. 515==== 516endif::VKSC_VERSION_1_0[] 517ifdef::VKSC_VERSION_1_0[] 518Physical device layers are not supported. 519pname:pPropertyCount is set to `0` and ename:VK_SUCCESS is returned. 520endif::VKSC_VERSION_1_0[] 521 522include::{generated}/validity/protos/vkEnumerateDeviceLayerProperties.adoc[] 523-- 524 525The pname:ppEnabledLayerNames and pname:enabledLayerCount members of 526slink:VkDeviceCreateInfo are deprecated and their values must: be ignored by 527implementations. 528ifndef::VKSC_VERSION_1_0[] 529However, for compatibility, only an empty list of layers or a list that 530exactly matches the sequence enabled at instance creation time are valid, 531and validation layers should: issue diagnostics for other cases. 532 533Regardless of the enabled layer list provided in slink:VkDeviceCreateInfo, 534the 535endif::VKSC_VERSION_1_0[] 536ifdef::VKSC_VERSION_1_0[The] 537sequence of layers active for a device will be exactly the sequence of 538layers enabled when the parent instance was created. 539 540 541[[extendingvulkan-extensions]] 542== Extensions 543 544Extensions may: define new Vulkan commands, structures, and enumerants. 545For compilation purposes, the interfaces defined by registered extensions, 546including new structures and enumerants as well as function pointer types 547for new commands, are defined in the Khronos-supplied `{core_header}` 548together with the core API. 549However, commands defined by extensions may: not be available for static 550linking - in which case function pointers to these commands should: be 551queried at runtime as described in <<initialization-functionpointers>>. 552Extensions may: be provided by layers as well as by a Vulkan implementation. 553 554Because extensions may: extend or change the behavior of the Vulkan API, 555extension authors should: add support for their extensions to the Khronos 556validation layers. 557This is especially important for new commands whose parameters have been 558wrapped by the validation layers. 559See the <<LoaderInterfaceArchitecture, "`Architecture of the Vulkan Loader 560Interfaces`">> document for additional information. 561 562[NOTE] 563.Note 564==== 565To enable an instance extension, the name of the extension can: be added to 566the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when 567creating a sname:VkInstance. 568 569To enable a device extension, the name of the extension can: be added to the 570pname:ppEnabledExtensionNames member of slink:VkDeviceCreateInfo when 571creating a sname:VkDevice. 572 573ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 574Physical-Device-Level functionality does not have any enabling mechanism and 575can: be used as long as the slink:VkPhysicalDevice supports the device 576extension as determined by flink:vkEnumerateDeviceExtensionProperties. 577endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 578 579Enabling an extension (with no further use of that extension) does not 580change the behavior of functionality exposed by the core Vulkan API or any 581other extension, other than making valid the use of the commands, enums and 582structures defined by that extension. 583 584Valid Usage sections for individual commands and structures do not currently 585contain which extensions have to be enabled in order to make their use 586valid, although they might do so in the future. 587It is defined only in the <<fundamentals-validusage-extensions>> section. 588==== 589 590 591[[extendingvulkan-instance-extensions]] 592=== Instance Extensions 593 594Instance extensions add new 595<<extendingvulkan-instanceanddevicefunctionality,instance-level 596functionality>> to the API, outside of the core specification. 597 598[open,refpage='vkEnumerateInstanceExtensionProperties',desc='Returns up to requested number of global extension properties',type='protos'] 599-- 600To query the available instance extensions, call: 601 602include::{generated}/api/protos/vkEnumerateInstanceExtensionProperties.adoc[] 603 604 * pname:pLayerName is either `NULL` or a pointer to a null-terminated 605 UTF-8 string naming the layer to retrieve extensions from. 606 * pname:pPropertyCount is a pointer to an integer related to the number of 607 extension properties available or queried, as described below. 608 * pname:pProperties is either `NULL` or a pointer to an array of 609 slink:VkExtensionProperties structures. 610 611When pname:pLayerName parameter is `NULL`, only extensions provided by the 612Vulkan implementation or by implicitly enabled layers are returned. 613When pname:pLayerName is the name of a layer, the instance extensions 614provided by that layer are returned. 615 616If pname:pProperties is `NULL`, then the number of extensions properties 617available is returned in pname:pPropertyCount. 618Otherwise, pname:pPropertyCount must: point to a variable set by the user to 619the number of elements in the pname:pProperties array, and on return the 620variable is overwritten with the number of structures actually written to 621pname:pProperties. 622If pname:pPropertyCount is less than the number of extension properties 623available, at most pname:pPropertyCount structures will be written, and 624ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 625indicate that not all the available properties were returned. 626 627Because the list of available layers may change externally between calls to 628flink:vkEnumerateInstanceExtensionProperties, two calls may retrieve 629different results if a pname:pLayerName is available in one call but not in 630another. 631The extensions supported by a layer may also change between two calls, e.g. 632if the layer implementation is replaced by a different version between those 633calls. 634 635Implementations must: not advertise any pair of extensions that cannot be 636enabled together due to behavioral differences, or any extension that cannot 637be enabled against the advertised version. 638 639include::{generated}/validity/protos/vkEnumerateInstanceExtensionProperties.adoc[] 640-- 641 642 643[[extendingvulkan-device-extensions]] 644=== Device Extensions 645 646Device extensions add new 647<<extendingvulkan-instanceanddevicefunctionality,device-level 648functionality>> to the API, outside of the core specification. 649 650[open,refpage='vkEnumerateDeviceExtensionProperties',desc='Returns properties of available physical device extensions',type='protos'] 651-- 652:refpage: vkEnumerateDeviceExtensionProperties 653 654To query the extensions available to a given physical device, call: 655 656include::{generated}/api/protos/vkEnumerateDeviceExtensionProperties.adoc[] 657 658 * pname:physicalDevice is the physical device that will be queried. 659 * pname:pLayerName is either `NULL` or a pointer to a null-terminated 660 UTF-8 string naming the layer to retrieve extensions from. 661 * pname:pPropertyCount is a pointer to an integer related to the number of 662 extension properties available or queried, and is treated in the same 663 fashion as the 664 flink:vkEnumerateInstanceExtensionProperties::pname:pPropertyCount 665 parameter. 666 * pname:pProperties is either `NULL` or a pointer to an array of 667 slink:VkExtensionProperties structures. 668 669When pname:pLayerName parameter is `NULL`, only extensions provided by the 670Vulkan implementation or by implicitly enabled layers are returned. 671When pname:pLayerName is the name of a layer, the device extensions provided 672by that layer are returned. 673 674Implementations must: not advertise any pair of extensions that cannot be 675enabled together due to behavioral differences, or any extension that cannot 676be enabled against the advertised version. 677 678ifdef::VK_VERSION_1_3[] 679Implementations claiming support for the <<roadmap-2022, Roadmap 2022>> 680profile must: advertise the `apiext:VK_KHR_global_priority` extension in 681pname:pProperties. 682endif::VK_VERSION_1_3[] 683 684[NOTE] 685.Note 686==== 687Due to platform details on Android, 688fname:vkEnumerateDeviceExtensionProperties may be called with 689pname:physicalDevice equal to `NULL` during layer discovery. 690This behaviour will only be observed by layer implementations, and not the 691underlying Vulkan driver. 692==== 693 694include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 695 696include::{generated}/validity/protos/vkEnumerateDeviceExtensionProperties.adoc[] 697-- 698 699[open,refpage='VkExtensionProperties',desc='Structure specifying an extension properties',type='structs'] 700-- 701The sname:VkExtensionProperties structure is defined as: 702 703include::{generated}/api/structs/VkExtensionProperties.adoc[] 704 705 * pname:extensionName is an array of ename:VK_MAX_EXTENSION_NAME_SIZE 706 code:char containing a null-terminated UTF-8 string which is the name of 707 the extension. 708 * pname:specVersion is the version of this extension. 709 It is an integer, incremented with backward compatible changes. 710 711include::{generated}/validity/structs/VkExtensionProperties.adoc[] 712-- 713 714[[extendingvulkan-accessing-device-physical-device]] 715==== Accessing Device-Level Functionality From a slink:VkPhysicalDevice 716 717Some device extensions also add support for physical-device-level 718functionality. 719Physical-device-level functionality can: be used, if the required extension 720is supported as advertised by flink:vkEnumerateDeviceExtensionProperties for 721a given slink:VkPhysicalDevice. 722 723[[extendingvulkan-accessing-device-logical-device]] 724==== Accessing Device-Level Functionality From a slink:VkDevice 725 726For commands that are dispatched from a slink:VkDevice, or from a child 727object of a slink:VkDevice, device extensions must: be enabled in 728flink:vkCreateDevice. 729 730[[extendingvulkan-extensions-extensiondependencies]] 731== Extension Dependencies 732 733Some extensions are dependent on other extensions, or on specific core API 734versions, to function. 735To enable extensions with dependencies, any _required extensions_ must: also 736be enabled through the same API mechanisms when creating an instance with 737flink:vkCreateInstance or a device with flink:vkCreateDevice. 738Each extension which has such dependencies documents them in the 739<<extensions, appendix summarizing that extension>>. 740 741If an extension is supported (as queried by 742flink:vkEnumerateInstanceExtensionProperties or 743flink:vkEnumerateDeviceExtensionProperties), then _required extensions_ of 744that extension must: also be supported for the same instance or physical 745device. 746 747Any device extension that has an instance extension dependency that is not 748enabled by flink:vkCreateInstance is considered to be unsupported, hence it 749must: not be returned by flink:vkEnumerateDeviceExtensionProperties for any 750slink:VkPhysicalDevice child of the instance. 751Instance extensions do not have dependencies on device extensions. 752 753If a required extension has been <<extendingvulkan-compatibility-promotion, 754promoted>> to another extension or to a core API version, then as a 755_general_ rule, the dependency is also satisfied by the promoted extension 756or core version. 757This will be true so long as any features required by the original extension 758are also required or enabled by the promoted extension or core version. 759However, in some cases an extension is promoted while making some of its 760features optional in the promoted extension or core version. 761In this case, the dependency may: not be satisfied. 762The only way to be certain is to look at the descriptions of the original 763dependency and the promoted version in the <<extensions, Layers & 764Extensions>> and <<versions, Core Revisions>> appendices. 765 766[NOTE] 767.Note 768==== 769There is metadata in `vk.xml` describing some aspects of promotion, 770especially `requires`, `promotedto` and `deprecatedby` attributes of 771`<extension>` tags. 772However, the metadata does not yet fully describe this scenario. 773In the future, we may extend the XML schema to describe the full set of 774extensions and versions satisfying a dependency. 775==== 776 777 778== Compatibility Guarantees (Informative) 779 780This section is marked as informal as there is no binding responsibility on 781implementations of the Vulkan API - these guarantees are however a contract 782between the Vulkan Working Group and developers using this Specification. 783 784 785[[extendingvulkan-compatibility-coreversions]] 786=== Core Versions 787 788Each of the <<extendingvulkan-coreversions,major, minor, and patch 789versions>> of the Vulkan specification provide different compatibility 790guarantees. 791 792 793==== Patch Versions 794 795A difference in the patch version indicates that a set of bug fixes or 796clarifications have been made to the Specification. 797Informative enums returned by Vulkan commands that will not affect the 798runtime behavior of a valid application may be added in a patch version 799(e.g. elink:VkVendorId). 800 801The specification's patch version is strictly increasing for a given major 802version of the specification; any change to a specification as described 803above will result in the patch version being increased by 1. 804Patch versions are applied to all minor versions, even if a given minor 805version is not affected by the provoking change. 806 807Specifications with different patch versions but the same major and minor 808version are _fully compatible_ with each other - such that a valid 809application written against one will work with an implementation of another. 810 811[NOTE] 812.Note 813==== 814If a patch version includes a bug fix or clarification that could have a 815significant impact on developer expectations, these will be highlighted in 816the change log. 817Generally the Vulkan Working Group tries to avoid these kinds of changes, 818instead fixing them in either an extension or core version. 819==== 820 821 822==== Minor Versions 823 824Changes in the minor version of the specification indicate that new 825functionality has been added to the core specification. 826This will usually include new interfaces in the header, and may: also 827include behavior changes and bug fixes. 828Core functionality may: be deprecated in a minor version, but will not be 829obsoleted or removed. 830 831The specification's minor version is strictly increasing for a given major 832version of the specification; any change to a specification as described 833above will result in the minor version being increased by 1. 834Changes that can be accommodated in a patch version will not increase the 835minor version. 836 837Specifications with a lower minor version are _backwards compatible_ with an 838implementation of a specification with a higher minor version for core 839functionality and extensions issued with the KHR vendor tag. 840Vendor and multi-vendor extensions are not guaranteed to remain functional 841across minor versions, though in general they are with few exceptions - see 842<<extendingvulkan-compatibility-obsoletion>> for more information. 843 844 845==== Major Versions 846 847A difference in the major version of specifications indicates a large set of 848changes which will likely include interface changes, behavioral changes, 849removal of <<extendingvulkan-compatibility-deprecation,deprecated 850functionality>>, and the modification, addition, or replacement of other 851functionality. 852 853The specification's major version is monotonically increasing; any change to 854the specification as described above will result in the major version being 855increased. 856Changes that can be accommodated in a patch or minor version will not 857increase the major version. 858 859The Vulkan Working Group intends to only issue a new major version of the 860Specification in order to realise significant improvements to the Vulkan API 861that will necessarily require breaking compatibility. 862 863A new major version will likely include a wholly new version of the 864specification to be issued - which could include an overhaul of the 865versioning semantics for the minor and patch versions. 866The patch and minor versions of a specification are therefore not meaningful 867across major versions. 868If a major version of the specification includes similar versioning 869semantics, it is expected that the patch and the minor version will be reset 870to 0 for that major version. 871 872 873[[extendingvulkan-compatibility-extensions]] 874=== Extensions 875 876A KHR extension must: be able to be enabled alongside any other KHR 877extension, and for any minor or patch version of the core Specification 878beyond the minimum version it requires. 879A multi-vendor extension should: be able to be enabled alongside any KHR 880extension or other multi-vendor extension, and for any minor or patch 881version of the core Specification beyond the minimum version it requires. 882A vendor extension should: be able to be enabled alongside any KHR 883extension, multi-vendor extension, or other vendor extension from the same 884vendor, and for any minor or patch version of the core Specification beyond 885the minimum version it requires. 886A vendor extension may: be able to be enabled alongside vendor extensions 887from another vendor. 888 889The one other exception to this is if a vendor or multi-vendor extension is 890<<extendingvulkan-compatibility-obsoletion, made obsolete>> by either a core 891version or another extension, which will be highlighted in the 892<<extensions,extension appendix>>. 893 894 895[[extendingvulkan-compatibility-promotion]] 896==== Promotion 897 898Extensions, or features of an extension, may: be promoted to a new 899<<versions,core version of the API>>, or a newer extension which an equal or 900greater number of implementors are in favour of. 901 902When extension functionality is promoted, minor changes may: be introduced, 903limited to the following: 904 905 * Naming 906 * Non-intrusive parameters changes 907 * <<features, Feature advertisement/enablement>> 908 * Combining structure parameters into larger structures 909 * Author ID suffixes changed or removed 910 911[NOTE] 912.Note 913==== 914If extension functionality is promoted, there is no guarantee of direct 915compatibility, however it should require little effort to port code from the 916original feature to the promoted one. 917 918The Vulkan Working Group endeavours to ensure that larger changes are marked 919as either <<extendingvulkan-compatibility-deprecation, deprecated>> or 920<<extendingvulkan-compatibility-obsoletion, obsoleted>> as appropriate, and 921can do so retroactively if necessary. 922==== 923 924Extensions that are promoted are listed as being promoted in their extension 925appendices, with reference to where they were promoted to. 926 927When an extension is promoted, any backwards compatibility aliases which 928exist in the extension will *not* be promoted. 929 930[NOTE] 931.Note 932==== 933As a hypothetical example, if the `apiext:VK_KHR_surface` extension were 934promoted to part of a future core version, the 935ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR token defined by that extension 936would be promoted to etext:VK_COLOR_SPACE_SRGB_NONLINEAR. 937However, the etext:VK_COLORSPACE_SRGB_NONLINEAR_KHR token aliases 938ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR. 939The etext:VK_COLORSPACE_SRGB_NONLINEAR_KHR would not be promoted, because it 940is a backwards compatibility alias that exists only due to a naming mistake 941when the extension was initially published. 942==== 943 944 945[[extendingvulkan-compatibility-deprecation]] 946==== Deprecation 947 948Extensions may: be marked as deprecated when the intended use cases either 949become irrelevant or can be solved in other ways. 950Generally, a new feature will become available to solve the use case in 951another extension or core version of the API, but it is not guaranteed. 952 953[NOTE] 954.Note 955==== 956Features that are intended to replace deprecated functionality have no 957guarantees of compatibility, and applications may require drastic 958modification in order to make use of the new features. 959==== 960 961Extensions that are deprecated are listed as being deprecated in their 962extension appendices, with an explanation of the deprecation and any 963features that are relevant. 964 965 966[[extendingvulkan-compatibility-obsoletion]] 967==== Obsoletion 968 969Occasionally, an extension will be marked as obsolete if a new version of 970the core API or a new extension is fundamentally incompatible with it. 971An obsoleted extension must: not be used with the extension or core version 972that obsoleted it. 973 974Extensions that are obsoleted are listed as being obsoleted in their 975extension appendices, with reference to what they were obsoleted by. 976 977 978[[extendingvulkan-compatibility-aliases]] 979==== Aliases 980 981When an extension is promoted or deprecated by a newer feature, some or all 982of its functionality may: be replicated into the newer feature. 983Rather than duplication of all the documentation and definitions, the 984specification instead identifies the identical commands and types as 985_aliases_ of one another. 986Each alias is mentioned together with the definition it aliases, with the 987older aliases marked as "`equivalents`". 988Each alias of the same command has identical behavior, and each alias of the 989same type has identical meaning - they can be used interchangeably in an 990application with no compatibility issues. 991 992[NOTE] 993.Note 994==== 995For promoted types, the aliased extension type is semantically identical to 996the new core type. 997The C99 headers simply `typedef` the older aliases to the promoted types. 998 999For promoted command aliases, however, there are two separate entry point 1000definitions, due to the fact that the C99 ABI has no way to alias command 1001definitions without resorting to macros. 1002Calling via either entry point definition will produce identical behavior 1003within the bounds of the specification, and should still invoke the same 1004entry point in the implementation. 1005Debug tools may use separate entry points with different debug behavior; to 1006write the appropriate command name to an output log, for instance. 1007==== 1008 1009 1010[[extendingvulkan-compatibility-specialuse]] 1011==== Special Use Extensions 1012 1013Some extensions exist only to support a specific purpose or specific class 1014of application. 1015These are referred to as "`special use extensions`". 1016Use of these extensions in applications not meeting the special use criteria 1017is not recommended. 1018 1019Special use cases are restricted, and only those defined below are used to 1020describe extensions: 1021 1022// The attributes in the "Special Use" column are defined in 1023// config/attribs.adoc, and used in reference pages as well as here. 1024// They define human-readable names for corresponding XML attribute values, 1025// so specialuse="cadsupport" -> "CAD Support". They are used in the table 1026// here and in the ExtensionMetaDocGenerator script that produces metadata 1027// includes for extension appendices. When introducing a new special use, 1028// the attribute and the table must both be extended. 1029 1030[[extendingvulkan-specialuse-table]] 1031.Extension Special Use Cases 1032[width="100%",options="header",cols="25%,15%,60%"] 1033|==== 1034| Special Use | XML Tag | Full Description 1035| {cadsupport} | cadsupport 1036 | Extension is intended to support specialized functionality used by 1037 CAD/CAM applications. 1038| {d3demulation} | d3demulation 1039 | Extension is intended to support D3D emulation layers, and 1040 applications ported from D3D, by adding functionality specific to D3D. 1041| {devtools} | devtools 1042 | Extension is intended to support developer tools such as 1043 capture-replay libraries. 1044| {debugging} | debugging 1045 | Extension is intended for use by applications when debugging. 1046| {glemulation} | glemulation 1047 | Extension is intended to support OpenGL and/or OpenGL ES emulation 1048 layers, and applications ported from those APIs, by adding 1049 functionality specific to those APIs. 1050|==== 1051 1052Special use extensions are identified in the metadata for each such 1053extension in the <<extensions, Layers & Extensions>> appendix, using the 1054name in the "`Special Use`" column above. 1055 1056Special use extensions are also identified in `vk.xml` with the short name 1057in "`XML Tag`" column above, as described in the "`API Extensions 1058(`extension` tag)`" section of the <<vulkan-registry, registry schema 1059documentation>>. 1060 1061