extensions.txt
1 // Copyright (c) 2015-2019 Khronos Group. This work is licensed under a 2 // Creative Commons Attribution 4.0 International License; see 3 // http://creativecommons.org/licenses/by/4.0/ 4 5 [[extendingvulkan]] 6 = Extending Vulkan 7 8 New functionality may: be added to Vulkan via either new extensions or new 9 versions of the core, or new versions of an extension in some cases. 10 11 This chapter describes how Vulkan is versioned, how compatibility is 12 affected between different versions, and compatibility rules that are 13 followed by the Vulkan Working Group. 14 15 16 [[extendingvulkan-instanceanddevicefunctionality]] 17 == Instance and Device Functionality 18 19 Commands that enumerate instance properties, or that accept a 20 slink:VkInstance object as a parameter, are considered instance-level 21 functionality. 22 Commands 23 ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 24 that enumerate physical device properties, or 25 endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 26 that accept a slink:VkDevice object or any of a device's child objects as a 27 parameter, are considered device-level functionality. 28 29 ifdef::VK_VERSION_1_1[] 30 [NOTE] 31 .Note 32 ==== 33 Applications usually interface to Vulkan using a loader that implements only 34 instance-level functionality, passing device-level functionality to 35 implementations of the full Vulkan API on the system. 36 In some circumstances, as these may be implemented independently, it is 37 possible that the loader and device implementations on a given installation 38 will support different versions. 39 To allow for this and call out when it happens, the Vulkan specification 40 enumerates device and instance level functionality separately - they have 41 <<extendingvulkan-coreversions-queryingversionsupport,independent version 42 queries>>. 43 ==== 44 endif::VK_VERSION_1_1[] 45 46 [NOTE] 47 .Note 48 ==== 49 Vulkan 1.0 initially specified new physical device enumeration functionality 50 as instance-level, requiring it to be included in an instance extension. 51 As the capabilities of device-level functionality require discovery via 52 physical device enumeration, this led to the situation where many device 53 extensions required an instance extension as well. 54 To alleviate this extra work, `VK_KHR_get_physical_device_properties2` (and 55 subsequently Vulkan 1.1) redefined device-level functionality to include 56 physical device enumeration. 57 ==== 58 59 60 [[extendingvulkan-coreversions]] 61 == Core Versions 62 63 The Vulkan Specification is regularly updated with bug fixes and 64 clarifications. 65 Occasionally new functionality is added to the core and at some point it is 66 expected that there will be a desire to perform a large, breaking change to 67 the API. 68 In order to indicate to developers how and when these changes are made to 69 the specification, and to provide a way to identify each set of changes, the 70 Vulkan API maintains a version number. 71 72 73 [[extendingvulkan-coreversions-versionnumbers]] 74 === Version Numbers 75 76 The Vulkan version number comprises three parts indicating the major, minor 77 and patch version of the Vulkan API Specification. 78 79 The _major version_ indicates a significant change in the API, which will 80 encompass a wholly new version of the specification. 81 82 The _minor version_ indicates the incorporation of new functionality into 83 the core specification. 84 85 The _patch version_ indicates bug fixes, clarifications, and language 86 improvements have been incorporated into the specification. 87 88 Compatibility guarantees made about versions of the API sharing any of the 89 same version numbers are documented in 90 <<extendingvulkan-compatibility-coreversions>> 91 92 The version number is used in several places in the API. 93 In each such use, the version numbers are packed into a 32-bit integer as 94 follows: 95 96 * The major version is a 10-bit integer packed into bits 31-22. 97 * The minor version number is a 10-bit integer packed into bits 21-12. 98 * The patch version number is a 12-bit integer packed into bits 11-0. 99 100 [open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines'] 101 -- 102 103 dname:VK_VERSION_MAJOR extracts the API major version number from a packed 104 version number: 105 106 include::{generated}/api/defines/VK_VERSION_MAJOR.txt[] 107 108 -- 109 110 [open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines'] 111 -- 112 113 dname:VK_VERSION_MINOR extracts the API minor version number from a packed 114 version number: 115 116 include::{generated}/api/defines/VK_VERSION_MINOR.txt[] 117 118 -- 119 120 [open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines'] 121 -- 122 123 dname:VK_VERSION_PATCH extracts the API patch version number from a packed 124 version number: 125 126 include::{generated}/api/defines/VK_VERSION_PATCH.txt[] 127 128 -- 129 130 [open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance'] 131 -- 132 133 dname:VK_MAKE_VERSION constructs an API version number. 134 135 include::{generated}/api/defines/VK_MAKE_VERSION.txt[] 136 137 * pname:major is the major version number. 138 * pname:minor is the minor version number. 139 * pname:patch is the patch version number. 140 -- 141 142 [open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 143 -- 144 145 dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.0. 146 147 include::{generated}/api/defines/VK_API_VERSION_1_0.txt[] 148 149 -- 150 151 ifdef::VK_VERSION_1_1[] 152 [open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 153 -- 154 155 dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.0. 156 157 include::{generated}/api/defines/VK_API_VERSION_1_1.txt[] 158 159 -- 160 endif::VK_VERSION_1_1[] 161 162 163 [[extendingvulkan-coreversions-queryingversionsupport]] 164 === Querying Version Support 165 166 ifndef::VK_VERSION_1_1[] 167 [NOTE] 168 .Note 169 ==== 170 In Vulkan 1.0, there is no mechanism to detect the separate versions of 171 <<extendingvulkan-instanceanddevicefunctionality,instance-level and 172 device-level functionality>> supported. 173 However, the fname:vkEnumerateInstanceVersion command was added in Vulkan 174 1.1 to determine the supported version of instance-level functionality - 175 querying for this function via flink:vkGetInstanceProcAddr will return 176 `NULL` on implementations that only support Vulkan 1.0 functionality. 177 For more information on this, please refer to the Vulkan 1.1 specification. 178 ==== 179 endif::VK_VERSION_1_1[] 180 181 ifdef::VK_VERSION_1_1[] 182 The version of instance-level functionality can be queried by calling 183 flink:vkEnumerateInstanceVersion. 184 endif::VK_VERSION_1_1[] 185 186 The version of device-level functionality can be queried by calling 187 flink:vkGetPhysicalDeviceProperties 188 ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 189 or flink:vkGetPhysicalDeviceProperties2, 190 endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 191 and is returned in slink:VkPhysicalDeviceProperties::pname:apiVersion, 192 encoded as described in <<extendingvulkan-coreversions-versionnumbers>>. 193 194 195 [[extendingvulkan-layers]] 196 == Layers 197 198 When a layer is enabled, it inserts itself into the call chain for Vulkan 199 commands the layer is interested in. 200 Layers can: be used for a variety of tasks that extend the base behavior of 201 Vulkan beyond what is required by the specification - such as call logging, 202 tracing, validation, or providing additional extensions. 203 204 [NOTE] 205 .Note 206 ==== 207 For example, an implementation is not expected to check that the value of 208 enums used by the application fall within allowed ranges. 209 Instead, a validation layer would do those checks and flag issues. 210 This avoids a performance penalty during production use of the application 211 because those layers would not be enabled in production. 212 ==== 213 214 [NOTE] 215 .Note 216 ==== 217 Vulkan layers may: wrap object handles (i.e. return a different handle value 218 to the application than that generated by the implementation). 219 This is generally discouraged, as it increases the probability of 220 incompatibilities with new extensions. 221 The validation layers wrap handles in order to track the proper use and 222 destruction of each object. 223 See the <<LoaderAndLayerInterface, "`Vulkan Loader Specification and 224 Architecture Overview`">> document for additional information. 225 ==== 226 227 [open,refpage='vkEnumerateInstanceLayerProperties',desc='Returns up to requested number of global layer properties',type='protos'] 228 -- 229 230 To query the available layers, call: 231 232 include::{generated}/api/protos/vkEnumerateInstanceLayerProperties.txt[] 233 234 * pname:pPropertyCount is a pointer to an integer related to the number of 235 layer properties available or queried, as described below. 236 * pname:pProperties is either `NULL` or a pointer to an array of 237 slink:VkLayerProperties structures. 238 239 If pname:pProperties is `NULL`, then the number of layer properties 240 available is returned in pname:pPropertyCount. 241 Otherwise, pname:pPropertyCount must: point to a variable set by the user to 242 the number of elements in the pname:pProperties array, and on return the 243 variable is overwritten with the number of structures actually written to 244 pname:pProperties. 245 If pname:pPropertyCount is less than the number of layer properties 246 available, at most pname:pPropertyCount structures will be written. 247 If pname:pPropertyCount is smaller than the number of layers available, 248 ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 249 indicate that not all the available layer properties were returned. 250 251 The list of available layers may change at any time due to actions outside 252 of the Vulkan implementation, so two calls to 253 fname:vkEnumerateInstanceLayerProperties with the same parameters may: 254 return different results, or retrieve different pname:pPropertyCount values 255 or pname:pProperties contents. 256 Once an instance has been created, the layers enabled for that instance will 257 continue to be enabled and valid for the lifetime of that instance, even if 258 some of them become unavailable for future instances. 259 260 include::{generated}/validity/protos/vkEnumerateInstanceLayerProperties.txt[] 261 -- 262 263 [open,refpage='VkLayerProperties',desc='Structure specifying layer properties',type='structs'] 264 -- 265 266 The sname:VkLayerProperties structure is defined as: 267 268 include::{generated}/api/structs/VkLayerProperties.txt[] 269 270 * pname:layerName is a null-terminated UTF-8 string specifying the name of 271 the layer. 272 Use this name in the pname:ppEnabledLayerNames array passed in the 273 slink:VkInstanceCreateInfo structure to enable this layer for an 274 instance. 275 * pname:specVersion is the Vulkan version the layer was written to, 276 encoded as described in <<extendingvulkan-coreversions-versionnumbers>>. 277 * pname:implementationVersion is the version of this layer. 278 It is an integer, increasing with backward compatible changes. 279 * pname:description is a null-terminated UTF-8 string providing additional 280 details that can: be used by the application to identify the layer. 281 282 include::{generated}/validity/structs/VkLayerProperties.txt[] 283 -- 284 285 To enable a layer, the name of the layer should: be added to the 286 pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating 287 a sname:VkInstance. 288 289 Loader implementations may: provide mechanisms outside the Vulkan API for 290 enabling specific layers. 291 Layers enabled through such a mechanism are _implicitly enabled_, while 292 layers enabled by including the layer name in the pname:ppEnabledLayerNames 293 member of slink:VkInstanceCreateInfo are _explicitly enabled_. 294 Except where otherwise specified, implicitly enabled and explicitly enabled 295 layers differ only in the way they are enabled. 296 Explicitly enabling a layer that is implicitly enabled has no additional 297 effect. 298 299 300 [[extendingvulkan-layers-devicelayerdeprecation]] 301 === Device Layer Deprecation 302 303 Previous versions of this specification distinguished between instance and 304 device layers. 305 Instance layers were only able to intercept commands that operate on 306 sname:VkInstance and sname:VkPhysicalDevice, except they were not able to 307 intercept flink:vkCreateDevice. 308 Device layers were enabled for individual devices when they were created, 309 and could only intercept commands operating on that device or its child 310 objects. 311 312 Device-only layers are now deprecated, and this specification no longer 313 distinguishes between instance and device layers. 314 Layers are enabled during instance creation, and are able to intercept all 315 commands operating on that instance or any of its child objects. 316 At the time of deprecation there were no known device-only layers and no 317 compelling reason to create one. 318 319 In order to maintain compatibility with implementations released prior to 320 device-layer deprecation, applications should: still enumerate and enable 321 device layers. 322 The behavior of fname:vkEnumerateDeviceLayerProperties and valid usage of 323 the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo maximizes 324 compatibility with applications written to work with the previous 325 requirements. 326 327 [open,refpage='vkEnumerateDeviceLayerProperties',desc='Returns properties of available physical device layers',type='protos'] 328 -- 329 330 To enumerate device layers, call: 331 332 include::{generated}/api/protos/vkEnumerateDeviceLayerProperties.txt[] 333 334 * pname:pPropertyCount is a pointer to an integer related to the number of 335 layer properties available or queried. 336 * pname:pProperties is either `NULL` or a pointer to an array of 337 slink:VkLayerProperties structures. 338 339 If pname:pProperties is `NULL`, then the number of layer properties 340 available is returned in pname:pPropertyCount. 341 Otherwise, pname:pPropertyCount must: point to a variable set by the user to 342 the number of elements in the pname:pProperties array, and on return the 343 variable is overwritten with the number of structures actually written to 344 pname:pProperties. 345 If pname:pPropertyCount is less than the number of layer properties 346 available, at most pname:pPropertyCount structures will be written. 347 If pname:pPropertyCount is smaller than the number of layers available, 348 ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 349 indicate that not all the available layer properties were returned. 350 351 The list of layers enumerated by fname:vkEnumerateDeviceLayerProperties 352 must: be exactly the sequence of layers enabled for the instance. 353 The members of sname:VkLayerProperties for each enumerated layer must: be 354 the same as the properties when the layer was enumerated by 355 fname:vkEnumerateInstanceLayerProperties. 356 357 include::{generated}/validity/protos/vkEnumerateDeviceLayerProperties.txt[] 358 -- 359 360 The pname:ppEnabledLayerNames and pname:enabledLayerCount members of 361 sname:VkDeviceCreateInfo are deprecated and their values must: be ignored by 362 implementations. 363 However, for compatibility, only an empty list of layers or a list that 364 exactly matches the sequence enabled at instance creation time are valid, 365 and validation layers should: issue diagnostics for other cases. 366 367 Regardless of the enabled layer list provided in sname:VkDeviceCreateInfo, 368 the sequence of layers active for a device will be exactly the sequence of 369 layers enabled when the parent instance was created. 370 371 372 [[extendingvulkan-extensions]] 373 == Extensions 374 375 Extensions may: define new Vulkan commands, structures, and enumerants. 376 For compilation purposes, the interfaces defined by registered extensions, 377 including new structures and enumerants as well as function pointer types 378 for new commands, are defined in the Khronos-supplied `vulkan_core.h` 379 together with the core API. 380 However, commands defined by extensions may: not be available for static 381 linking - in which case function pointers to these commands should: be 382 queried at runtime as described in <<initialization-functionpointers>>. 383 Extensions may: be provided by layers as well as by a Vulkan implementation. 384 385 Because extensions may: extend or change the behavior of the Vulkan API, 386 extension authors should: add support for their extensions to the Khronos 387 validation layers. 388 This is especially important for new commands whose parameters have been 389 wrapped by the validation layers. 390 See the <<LoaderAndLayerInterface, "`Vulkan Loader Specification and 391 Architecture Overview`">> document for additional information. 392 393 [NOTE] 394 .Note 395 ==== 396 Valid Usage sections for individual commands and structures do not currently 397 contain which extensions have to be enabled in order to make their use 398 valid, although it might do so in the future. 399 It is defined only in the <<fundamentals-validusage-extensions>> section. 400 ==== 401 402 403 === Instance Extensions 404 405 Instance extensions add new 406 <<extendingvulkan-instanceanddevicefunctionality,instance-level 407 functionality>> to the API, outside of the core specification. 408 409 [open,refpage='vkEnumerateInstanceExtensionProperties',desc='Returns up to requested number of global extension properties',type='protos'] 410 -- 411 412 To query the available instance extensions, call: 413 414 include::{generated}/api/protos/vkEnumerateInstanceExtensionProperties.txt[] 415 416 * pname:pLayerName is either `NULL` or a pointer to a null-terminated 417 UTF-8 string naming the layer to retrieve extensions from. 418 * pname:pPropertyCount is a pointer to an integer related to the number of 419 extension properties available or queried, as described below. 420 * pname:pProperties is either `NULL` or a pointer to an array of 421 slink:VkExtensionProperties structures. 422 423 When pname:pLayerName parameter is `NULL`, only extensions provided by the 424 Vulkan implementation or by implicitly enabled layers are returned. 425 When pname:pLayerName is the name of a layer, the instance extensions 426 provided by that layer are returned. 427 428 If pname:pProperties is `NULL`, then the number of extensions properties 429 available is returned in pname:pPropertyCount. 430 Otherwise, pname:pPropertyCount must: point to a variable set by the user to 431 the number of elements in the pname:pProperties array, and on return the 432 variable is overwritten with the number of structures actually written to 433 pname:pProperties. 434 If pname:pPropertyCount is less than the number of extension properties 435 available, at most pname:pPropertyCount structures will be written. 436 If pname:pPropertyCount is smaller than the number of extensions available, 437 ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 438 indicate that not all the available properties were returned. 439 440 Because the list of available layers may change externally between calls to 441 flink:vkEnumerateInstanceExtensionProperties, two calls may retrieve 442 different results if a pname:pLayerName is available in one call but not in 443 another. 444 The extensions supported by a layer may also change between two calls, e.g. 445 if the layer implementation is replaced by a different version between those 446 calls. 447 448 Implementations must: not advertise any pair of extensions that cannot be 449 enabled together due to behavioral differences, or any extension that cannot 450 be enabled against the advertised version. 451 452 include::{generated}/validity/protos/vkEnumerateInstanceExtensionProperties.txt[] 453 -- 454 455 To enable an instance extension, the name of the extension should: be added 456 to the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo 457 when creating a sname:VkInstance. 458 459 [NOTE] 460 .Note 461 ==== 462 Enabling an extension does not change behavior of functionality exposed by 463 the core Vulkan API or any other extension, other than making valid the use 464 of the commands, enums and structures defined by that extension. 465 ==== 466 467 468 === Device Extensions 469 470 Device extensions add new 471 <<extendingvulkan-instanceanddevicefunctionality,device-level 472 functionality>> to the API, outside of the core specification. 473 474 [open,refpage='vkEnumerateDeviceExtensionProperties',desc='Returns properties of available physical device extensions',type='protos'] 475 -- 476 477 To query the extensions available to a given physical device, call: 478 479 include::{generated}/api/protos/vkEnumerateDeviceExtensionProperties.txt[] 480 481 * pname:physicalDevice is the physical device that will be queried. 482 * pname:pLayerName is either `NULL` or a pointer to a null-terminated 483 UTF-8 string naming the layer to retrieve extensions from. 484 * pname:pPropertyCount is a pointer to an integer related to the number of 485 extension properties available or queried, and is treated in the same 486 fashion as the 487 flink:vkEnumerateInstanceExtensionProperties::pname:pPropertyCount 488 parameter. 489 * pname:pProperties is either `NULL` or a pointer to an array of 490 slink:VkExtensionProperties structures. 491 492 When pname:pLayerName parameter is `NULL`, only extensions provided by the 493 Vulkan implementation or by implicitly enabled layers are returned. 494 When pname:pLayerName is the name of a layer, the device extensions provided 495 by that layer are returned. 496 497 Implementations must: not advertise any pair of extensions that cannot be 498 enabled together due to behavioral differences, or any extension that cannot 499 be enabled against the advertised version. 500 501 include::{generated}/validity/protos/vkEnumerateDeviceExtensionProperties.txt[] 502 -- 503 504 [open,refpage='VkExtensionProperties',desc='Structure specifying an extension properties',type='structs'] 505 -- 506 507 The sname:VkExtensionProperties structure is defined as: 508 509 include::{generated}/api/structs/VkExtensionProperties.txt[] 510 511 * pname:extensionName is a null-terminated string specifying the name of 512 the extension. 513 * pname:specVersion is the version of this extension. 514 It is an integer, incremented with backward compatible changes. 515 516 include::{generated}/validity/structs/VkExtensionProperties.txt[] 517 -- 518 519 [[extendingvulkan-extensions-extensiondependencies]] 520 == Extension Dependencies 521 522 Some extensions are dependent on other extensions to function. 523 To enable extensions with dependencies, such _required extensions_ must: 524 also be enabled through the same API mechanisms when creating an instance 525 with flink:vkCreateInstance or a device with flink:vkCreateDevice. 526 Each extension which has such dependencies documents them in the 527 <<extensions, appendix summarizing that extension>>. 528 529 If an extension is supported (as queried by 530 flink:vkEnumerateInstanceExtensionProperties or 531 flink:vkEnumerateDeviceExtensionProperties), then _required extensions_ of 532 that extension must: also be supported for the same instance or physical 533 device. 534 535 Any device extension that has an instance extension dependency that is not 536 enabled by flink:vkCreateInstance is considered to be unsupported, hence it 537 must: not be returned by flink:vkEnumerateDeviceExtensionProperties for any 538 slink:VkPhysicalDevice child of the instance. 539 540 541 == Compatibility Guarantees (Informative) 542 543 This section is marked as informal as there is no binding responsibility on 544 implementations of the Vulkan API - these guarantees are however a contract 545 between the Vulkan Working Group and developers using this Specification. 546 547 548 [[extendingvulkan-compatibility-coreversions]] 549 === Core Versions 550 551 Each of the <<extendingvulkan-coreversions,major, minor, and patch 552 versions>> of the Vulkan specification provide different compatibility 553 guarantees. 554 555 556 ==== Patch Versions 557 558 A difference in the patch version indicates that a set of bug fixes or 559 clarifications have been made to the Specification. 560 Informative enums returned by Vulkan commands that will not affect the 561 runtime behavior of a valid application may be added in a patch version 562 (e.g. elink:VkVendorId). 563 564 The specification's patch version is strictly increasing for a given major 565 version of the specification; any change to a specification as described 566 above will result in the patch version being increased by 1. 567 Patch versions are applied to all minor versions, even if a given minor 568 version is not affected by the provoking change. 569 570 Specifications with different patch versions but the same major and minor 571 version are _fully compatible_ with each other - such that a valid 572 application written against one will work with an implementation of another. 573 574 [NOTE] 575 .Note 576 ==== 577 If a patch version includes a bug fix or clarification that could have a 578 significant impact on developer expectations, these will be highlighted in 579 the change log. 580 Generally the Vulkan Working Group tries to avoid these kinds of changes, 581 instead fixing them in either an extension or core version. 582 ==== 583 584 585 ==== Minor Versions 586 587 Changes in the minor version of the specification indicate that new 588 functionality has been added to the core specification. 589 This will usually include new interfaces in the header, and may: also 590 include behavior changes and bug fixes. 591 Core functionality may: be deprecated in a minor version, but will not be 592 obsoleted or removed. 593 594 The specification's minor version is strictly increasing for a given major 595 version of the specification; any change to a specification as described 596 above will result in the minor version being increased by 1. 597 Changes that can be accomodated in a patch version will not increase the 598 minor version. 599 600 Specifications with a lower minor version are _backwards compatible_ with an 601 implementation of a specification with a higher minor version for core 602 functionality and extensions issued with the KHR vendor tag. 603 Vendor and multi-vendor extensions are not guaranteed to remain functional 604 across minor versions, though in general they are with few exceptions - see 605 <<extendingvulkan-compatibility-obsoletion>> for more information. 606 607 608 ==== Major Versions 609 610 A difference in the major version of specifications indicates a large set of 611 changes which will likely include interface changes, behavioral changes, 612 removal of <<extendingvulkan-compatibility-deprecation,deprecated 613 functionality>>, and the modification, addition, or replacement of other 614 functionality. 615 616 The specification's major version is monotonically increasing; any change to 617 the specification as described above will result in the major version being 618 increased. 619 Changes that can be accomodated in a patch or minor version will not 620 increase the major version. 621 622 The Vulkan Working Group intends to only issue a new major version of the 623 Specification in order to realise significant improvements to the Vulkan API 624 that will necessarily require breaking compatibility. 625 626 A new major version will likely include a wholly new version of the 627 specification to be issued - which could include an overhaul of the 628 versioning semantics for the minor and patch versions. 629 The patch and minor versions of a specification are therefore not meaningful 630 across major versions. 631 If a major version of the specification includes similar versioning 632 semantics, it is expected that the the patch and minor version will be reset 633 to 0 for that major version. 634 635 636 [[extendingvulkan-compatibility-extensions]] 637 === Extensions 638 639 A KHR extension must: be able to be enabled alongside any other KHR 640 extension, and for any minor or patch version of the core Specification 641 beyond the minimum version it requires. 642 A multi-vendor extension should: be able to be enabled alongside any KHR 643 extension or other multi-vendor extension, and for any minor or patch 644 version of the core Specification beyond the minimum version it requires. 645 A vendor extension should: be able to be enabled alongside any KHR 646 extension, multi-vendor extension, or other vendor extension from the same 647 vendor, and for any minor or patch version of the core Specification beyond 648 the minimum version it requires. 649 A vendor extension may: be able to be enabled alongside vendor extensions 650 from another vendor. 651 652 The one other exception to this is if a vendor or multi-vendor extension is 653 <<extendingvulkan-compatibility-obsoletion, made obsolete>> by either a core 654 version or another extension, which will be highlighted in the 655 <<extensions,extension appendix>>. 656 657 658 [[extendingvulkan-compatibility-promotion]] 659 ==== Promotion 660 661 Extensions, or features of an extension, may: be promoted to a new 662 <<versions,core version of the API>>, or a newer extension which an equal or 663 greater number of implementors are in favour of. 664 665 When extension functionality is promoted, minor changes may: be introduced, 666 limited to the following: 667 668 * Naming 669 * Non-intrusive parameters changes 670 * <<features,Feature advertisement/enablement>> 671 * Combining structure parameters into larger structures 672 * Author ID suffixes changed or removed 673 674 [NOTE] 675 .Note 676 ==== 677 If extension functionality is promoted, there is no guarantee of direct 678 compatibility, however it should require little effort to port code from the 679 original feature to the promoted one. 680 681 The Vulkan Working Group endeavours to ensure that larger changes are marked 682 as either <<extendingvulkan-compatibility-deprecation, deprecated>> or 683 <<extendingvulkan-compatibility-obsoletion, obsoleted>> as appropriate, and 684 can do so retroactively if necessary. 685 ==== 686 687 Extensions that are promoted are listed as being promoted in their extension 688 appendices, with reference to where they were promoted to. 689 690 691 [[extendingvulkan-compatibility-deprecation]] 692 ==== Deprecation 693 694 Extensions may: be marked as deprecated when the intended use cases either 695 become irrelevant or can be solved in other ways. 696 Generally, a new feature will become available to solve the use case in 697 another extension or core version of the API, but it is not guaranteed. 698 699 [NOTE] 700 .Note 701 ==== 702 Features that are intended to replace deprecated functionality have no 703 guarantees of compatibility, and applications may require drastic 704 modification in order to make use of the new features. 705 ==== 706 707 Extensions that are deprecated are listed as being deprecated in their 708 extension appendices, with an explanation of the deprecation and any 709 features that are relevant. 710 711 712 [[extendingvulkan-compatibility-obsoletion]] 713 ==== Obsoletion 714 715 Occasionally, an extension will be marked as obsolete if a new version of 716 the core API or a new extension is fundamentally incompatible with it. 717 An obsoleted extension must: not be used with the extension or core version 718 that obsoleted it. 719 720 Extensions that are obsoleted are listed as being obsoleted in their 721 extension appendices, with reference to what they were obsoleted by. 722 723 724 [[extendingvulkan-compatibility-aliases]] 725 ==== Aliases 726 727 When an extension is promoted or deprecated by a newer feature, some or all 728 of its functionality may: be replicated into the newer feature. 729 Rather than duplication of all the documentation and definitions, the 730 specification instead identifies the identical commands and types as 731 _aliases_ of one another. 732 Each alias is mentioned together with the definition it aliases, with the 733 older aliases marked as "`equivalents`". 734 Each alias of the same command has identical behavior, and each alias of the 735 same type has identical meaning - they can be used interchangably in an 736 application with no compatibility issues. 737 738 [NOTE] 739 .Note 740 ==== 741 For promoted types, the aliased extension type is semantically identical to 742 the new core type. 743 The C99 headers simply `typedef` the older aliases to the promoted types. 744 745 For promoted command aliases, however, there are two separate entry point 746 definitions, due to the fact that the C99 ABI has no way to alias command 747 definitions without resorting to macros. 748 Calling via either entry point definition will produce identical behavior 749 within the bounds of the specification, and should still invoke the same 750 entry point in the implementation. 751 Debug tools may use separate entry points with different debug behavior; to 752 write the appropriate command name to an output log, for instance. 753 ====