1// Copyright 2015-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[fundamentals]] 6= Fundamentals 7 8This chapter introduces fundamental concepts including the Vulkan 9architecture and execution model, API syntax, queues, pipeline 10configurations, numeric representation, state and state queries, and the 11different types of objects and shaders. 12It provides a framework for interpreting more specific descriptions of 13commands and behavior in the remainder of the Specification. 14 15 16[[fundamentals-host-environment]] 17== Host and Device Environment 18 19The Vulkan Specification assumes and requires: the following properties of 20the host environment with respect to Vulkan implementations: 21 22 * The host must: have runtime support for 8, 16, 32 and 64-bit signed and 23 unsigned twos-complement integers, all addressable at the granularity of 24 their size in bytes. 25 * The host must: have runtime support for 32- and 64-bit floating-point 26 types satisfying the range and precision constraints in the 27 <<fundamentals-floatingpoint,Floating Point Computation>> section. 28 * The representation and endianness of these types on the host must: match 29 the representation and endianness of the same types on every physical 30 device supported. 31 32[NOTE] 33.Note 34==== 35Since a variety of data types and structures in Vulkan may: be accessible by 36both host and physical device operations, the implementation should: be able 37to access such data efficiently in both paths in order to facilitate writing 38portable and performant applications. 39==== 40 41 42[[fundamentals-execmodel]] 43== Execution Model 44 45This section outlines the execution model of a Vulkan system. 46 47Vulkan exposes one or more _devices_, each of which exposes one or more 48_queues_ which may: process work asynchronously to one another. 49The set of queues supported by a device is partitioned into _families_. 50Each family supports one or more types of functionality and may: contain 51multiple queues with similar characteristics. 52Queues within a single family are considered _compatible_ with one another, 53and work produced for a family of queues can: be executed on any queue 54within that family. 55This specification defines the following types of functionality that queues 56may: support: graphics, compute, 57ifdef::VK_KHR_video_decode_queue[] 58video decode, 59endif::VK_KHR_video_decode_queue[] 60ifdef::VK_KHR_video_encode_queue[] 61video encode, 62endif::VK_KHR_video_encode_queue[] 63transfer, and sparse memory management. 64 65[NOTE] 66.Note 67==== 68A single device may: report multiple similar queue families rather than, or 69as well as, reporting multiple members of one or more of those families. 70This indicates that while members of those families have similar 71capabilities, they are _not_ directly compatible with one another. 72==== 73 74Device memory is explicitly managed by the application. 75Each device may: advertise one or more heaps, representing different areas 76of memory. 77Memory heaps are either device-local or host-local, but are always visible 78to the device. 79Further detail about memory heaps is exposed via memory types available on 80that heap. 81Examples of memory areas that may: be available on an implementation 82include: 83 84 * _device-local_ is memory that is physically connected to the device. 85 * _device-local, host visible_ is device-local memory that is visible to 86 the host. 87 * _host-local, host visible_ is memory that is local to the host and 88 visible to the device and host. 89 90On other architectures, there may: only be a single heap that can: be used 91for any purpose. 92 93 94[[fundamentals-queueoperation]] 95=== Queue Operation 96 97Vulkan queues provide an interface to the execution engines of a device. 98Commands for these execution engines are recorded into command buffers ahead 99of execution time, and then submitted to a queue for execution. 100Once submitted to a queue, command buffers will begin and complete execution 101without further application intervention, though the order of this execution 102is dependent on a number of <<synchronization, implicit and explicit 103ordering constraints>>. 104 105Work is submitted to queues using _queue submission commands_ that typically 106take the form ftext:vkQueue* (e.g. flink:vkQueueSubmit, 107flink:vkQueueBindSparse), and can: take a list of semaphores upon which to 108wait before work begins and a list of semaphores to signal once work has 109completed. 110The work itself, as well as signaling and waiting on the semaphores are all 111_queue operations_. 112Queue submission commands return control to the application once queue 113operations have been submitted - they do not wait for completion. 114 115There are no implicit ordering constraints between queue operations on 116different queues, or between queues and the host, so these may: operate in 117any order with respect to each other. 118Explicit ordering constraints between different queues or with the host can: 119be expressed with <<synchronization-semaphores,semaphores>> and 120<<synchronization-fences,fences>>. 121 122Command buffer submissions to a single queue respect 123<<synchronization-submission-order, submission order>> and other 124<<synchronization-implicit, implicit ordering guarantees>>, but otherwise 125may: overlap or execute out of order. 126Other types of batches and queue submissions against a single queue (e.g. 127<<sparsemem-memory-binding, sparse memory binding>>) have no implicit 128ordering constraints with any other queue submission or batch. 129Additional explicit ordering constraints between queue submissions and 130individual batches can be expressed with 131<<synchronization-semaphores,semaphores>> and 132<<synchronization-fences,fences>>. 133 134Before a fence or semaphore is signaled, it is guaranteed that any 135previously submitted queue operations have completed execution, and that 136memory writes from those queue operations are 137<<synchronization-dependencies-available-and-visible,available>> to future 138queue operations. 139Waiting on a signaled semaphore or fence guarantees that previous writes 140that are available are also 141<<synchronization-dependencies-available-and-visible,visible>> to subsequent 142commands. 143 144Command buffer boundaries, both between primary command buffers of the same 145or different batches or submissions as well as between primary and secondary 146command buffers, do not introduce any additional ordering constraints. 147In other words, submitting the set of command buffers (which can: include 148executing secondary command buffers) between any semaphore or fence 149operations execute the recorded commands as if they had all been recorded 150into a single primary command buffer, except that the current state is 151<<commandbuffers-statereset,reset>> on each boundary. 152Explicit ordering constraints can: be expressed with <<synchronization, 153explicit synchronization primitives>>. 154 155There are a few <<synchronization-implicit, implicit ordering guarantees>> 156between commands within a command buffer, but only covering a subset of 157execution. 158Additional explicit ordering constraints can be expressed with the various 159<<synchronization, explicit synchronization primitives>>. 160 161[NOTE] 162.Note 163==== 164Implementations have significant freedom to overlap execution of work 165submitted to a queue, and this is common due to deep pipelining and 166parallelism in Vulkan devices. 167==== 168 169[[fundamentals-queueoperation-command-types]] 170Commands recorded in command buffers can perform actions, set state that 171persists across commands, synchronize other commands, or indirectly launch 172other commands, with some commands fulfilling several of these roles. 173The "`Command Properties`" section for each such command lists which of 174these roles the command takes. 175State setting commands update the _current state_ of the command buffer. 176Some commands that perform actions (e.g. draw/dispatch) do so based on the 177current state set cumulatively since the start of the command buffer. 178The work involved in performing action commands is often allowed to overlap 179or to be reordered, but doing so must: not alter the state to be used by 180each action command. 181In general, action commands are those commands that alter framebuffer 182attachments, read/write buffer or image memory, or write to query pools. 183 184Synchronization commands introduce explicit 185<<synchronization-dependencies,execution and memory dependencies>> between 186two sets of action commands, where the second set of commands depends on the 187first set of commands. 188These dependencies enforce both that the execution of certain 189<<synchronization-pipeline-stages, pipeline stages>> in the later set occurs 190after the execution of certain stages in the source set, and that the 191effects of <<synchronization-global-memory-barriers,memory accesses>> 192performed by certain pipeline stages occur in order and are visible to each 193other. 194When not enforced by an explicit dependency or <<synchronization-implicit, 195implicit ordering guarantees>>, action commands may: overlap execution or 196execute out of order, and may: not see the side effects of each other's 197memory accesses. 198 199 200[[fundamentals-objectmodel-overview]] 201== Object Model 202 203The devices, queues, and other entities in Vulkan are represented by Vulkan 204objects. 205At the API level, all objects are referred to by handles. 206There are two classes of handles, dispatchable and non-dispatchable. 207_Dispatchable_ handle types are a pointer to an opaque type. 208This pointer may: be used by layers as part of intercepting API commands, 209and thus each API command takes a dispatchable type as its first parameter. 210Each object of a dispatchable type must: have a unique handle value during 211its lifetime. 212 213_Non-dispatchable_ handle types are a 64-bit integer type whose meaning is 214implementation-dependent. 215ifdef::VK_VERSION_1_3,VK_EXT_private_data[] 216If the <<features-privateData, pname:privateData>> feature is enabled for a 217slink:VkDevice, each object of a non-dispatchable type created on that 218device must: have a handle value that is unique among objects created on 219that device, for the duration of the object's lifetime. 220Otherwise, non-dispatchable 221endif::VK_VERSION_1_3,VK_EXT_private_data[] 222ifndef::VK_VERSION_1_3,VK_EXT_private_data[Non-dispatchable] 223handles may: encode object information directly in the handle rather than 224acting as a reference to an underlying object, and thus may: not have unique 225handle values. 226If handle values are not unique, then destroying one such handle must: not 227cause identical handles of other types to become invalid, and must: not 228cause identical handles of the same type to become invalid if that handle 229value has been created more times than it has been destroyed. 230 231All objects created or allocated from a sname:VkDevice (i.e. with a 232sname:VkDevice as the first parameter) are private to that device, and must: 233not be used on other devices. 234 235 236[[fundamentals-objectmodel-lifetime]] 237=== Object Lifetime 238 239Objects are created or allocated by ftext:vkCreate* and ftext:vkAllocate* 240commands, respectively. 241Once an object is created or allocated, its "`structure`" is considered to 242be immutable, though the contents of certain object types is still free to 243change. 244Objects are destroyed or freed by ftext:vkDestroy* and ftext:vkFree* 245commands, respectively. 246 247Objects that are allocated (rather than created) take resources from an 248existing pool object or memory heap, and when freed return resources to that 249pool or heap. 250While object creation and destruction are generally expected to be 251low-frequency occurrences during runtime, allocating and freeing objects 252can: occur at high frequency. 253Pool objects help accommodate improved performance of the allocations and 254frees. 255 256It is an application's responsibility to track the lifetime of Vulkan 257objects, and not to destroy them while they are still in use. 258 259[[fundamentals-objectmodel-lifetime-acquire]] 260The ownership of application-owned memory is immediately acquired by any 261Vulkan command it is passed into. 262Ownership of such memory must: be released back to the application at the 263end of the duration of the command, so that the application can: alter or 264free this memory as soon as all the commands that acquired it have returned. 265 266The following object types are consumed when they are passed into a Vulkan 267command and not further accessed by the objects they are used to create. 268They must: not be destroyed in the duration of any API command they are 269passed into: 270 271 * sname:VkShaderModule 272 * sname:VkPipelineCache 273ifdef::VK_EXT_validation_cache[] 274 * sname:VkValidationCacheEXT 275endif::VK_EXT_validation_cache[] 276 277A sname:VkRenderPass 278ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 279or sname:VkPipelineLayout 280endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 281object passed as a parameter to create another object is not further 282accessed by that object after the duration of the command it is passed into. 283A sname:VkRenderPass used in a command buffer follows the rules described 284below. 285 286ifndef::VK_VERSION_1_3,VK_KHR_maintenance4[] 287A sname:VkPipelineLayout object must: not be destroyed while any command 288buffer that uses it is in the recording state. 289endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 290 291sname:VkDescriptorSetLayout objects may: be accessed by commands that 292operate on descriptor sets allocated using that layout, and those descriptor 293sets must: not be updated with flink:vkUpdateDescriptorSets after the 294descriptor set layout has been destroyed. 295Otherwise, a sname:VkDescriptorSetLayout object passed as a parameter to 296create another object is not further accessed by that object after the 297duration of the command it is passed into. 298 299The application must: not destroy any other type of Vulkan object until all 300uses of that object by the device (such as via command buffer execution) 301have completed. 302 303[[fundamentals-objectmodel-lifetime-cmdbuffers]] 304The following Vulkan objects must: not be destroyed while any command 305buffers using the object are in the <<commandbuffers-lifecycle, pending 306state>>: 307 308 * sname:VkEvent 309 * sname:VkQueryPool 310 * sname:VkBuffer 311 * sname:VkBufferView 312 * sname:VkImage 313 * sname:VkImageView 314 * sname:VkPipeline 315 * sname:VkSampler 316ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 317 * sname:VkSamplerYcbcrConversion 318endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 319 * sname:VkDescriptorPool 320 * sname:VkFramebuffer 321 * sname:VkRenderPass 322 * sname:VkCommandBuffer 323 * sname:VkCommandPool 324 * sname:VkDeviceMemory 325 * sname:VkDescriptorSet 326ifdef::VK_NV_device_generated_commands[] 327 * sname:VkIndirectCommandsLayoutNV 328endif::VK_NV_device_generated_commands[] 329ifdef::VK_NV_ray_tracing[] 330 * sname:VkAccelerationStructureNV 331endif::VK_NV_ray_tracing[] 332ifdef::VK_KHR_acceleration_structure[] 333 * sname:VkAccelerationStructureKHR 334endif::VK_KHR_acceleration_structure[] 335ifdef::VK_KHR_video_queue[] 336 * sname:VkVideoSessionKHR 337 * sname:VkVideoSessionParametersKHR 338endif::VK_KHR_video_queue[] 339 340Destroying these objects will move any command buffers that are in the 341<<commandbuffers-lifecycle, recording or executable state>>, and are using 342those objects, to the <<commandbuffers-lifecycle, invalid state>>. 343 344The following Vulkan objects must: not be destroyed while any queue is 345executing commands that use the object: 346 347 * sname:VkFence 348 * sname:VkSemaphore 349 * sname:VkCommandBuffer 350 * sname:VkCommandPool 351 352In general, objects can: be destroyed or freed in any order, even if the 353object being freed is involved in the use of another object (e.g. use of a 354resource in a view, use of a view in a descriptor set, 355ifdef::VK_KHR_pipeline_library[] 356use of a <<pipelines-library,pipeline library>> in another pipeline, 357endif::VK_KHR_pipeline_library[] 358ifdef::VK_NV_device_generated_commands[] 359use of a <<graphics-shadergroups,referenced pipeline>> for additional 360graphics shader groups in another pipeline, 361endif::VK_NV_device_generated_commands[] 362ifdef::VK_KHR_acceleration_structure[] 363use of a <<acceleration-structure-bottom-level, bottom level acceleration 364structure>> in an instance referenced by a 365<<acceleration-structure-top-level, top level acceleration structure>>, 366endif::VK_KHR_acceleration_structure[] 367use of an object in a command buffer, binding of a memory allocation to a 368resource), as long as any object that uses the freed object is not further 369used in any way except to be destroyed or to be reset in such a way that it 370no longer uses the other object (such as resetting a command buffer). 371If the object has been reset, then it can: be used as if it never used the 372freed object. 373An exception to this is when there is a parent/child relationship between 374objects. 375In this case, the application must: not destroy a parent object before its 376children, except when the parent is explicitly defined to free its children 377when it is destroyed (e.g. for pool objects, as defined below). 378 379sname:VkCommandPool objects are parents of sname:VkCommandBuffer objects. 380sname:VkDescriptorPool objects are parents of sname:VkDescriptorSet objects. 381sname:VkDevice objects are parents of many object types (all that take a 382sname:VkDevice as a parameter to their creation). 383 384The following Vulkan objects have specific restrictions for when they can: 385be destroyed: 386 387 * sname:VkQueue objects cannot: be explicitly destroyed. 388 Instead, they are implicitly destroyed when the sname:VkDevice object 389 they are retrieved from is destroyed. 390 * Destroying a pool object implicitly frees all objects allocated from 391 that pool. 392 Specifically, destroying sname:VkCommandPool frees all 393 sname:VkCommandBuffer objects that were allocated from it, and 394 destroying sname:VkDescriptorPool frees all sname:VkDescriptorSet 395 objects that were allocated from it. 396 * sname:VkDevice objects can: be destroyed when all sname:VkQueue objects 397 retrieved from them are idle, and all objects created from them have 398 been destroyed. 399 This includes the following objects: 400 ** sname:VkFence 401 ** sname:VkSemaphore 402 ** sname:VkEvent 403 ** sname:VkQueryPool 404 ** sname:VkBuffer 405 ** sname:VkBufferView 406 ** sname:VkImage 407 ** sname:VkImageView 408 ** sname:VkShaderModule 409 ** sname:VkPipelineCache 410 ** sname:VkPipeline 411 ** sname:VkPipelineLayout 412 ** sname:VkSampler 413ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 414 ** sname:VkSamplerYcbcrConversion 415endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 416 ** sname:VkDescriptorSetLayout 417 ** sname:VkDescriptorPool 418 ** sname:VkFramebuffer 419 ** sname:VkRenderPass 420 ** sname:VkCommandPool 421 ** sname:VkCommandBuffer 422 ** sname:VkDeviceMemory 423ifdef::VK_EXT_validation_cache[] 424 ** sname:VkValidationCacheEXT 425endif::VK_EXT_validation_cache[] 426ifdef::VK_NV_ray_tracing[] 427 ** sname:VkAccelerationStructureNV 428endif::VK_NV_ray_tracing[] 429ifdef::VK_KHR_acceleration_structure[] 430 ** sname:VkAccelerationStructureKHR 431endif::VK_KHR_acceleration_structure[] 432ifdef::VK_KHR_video_queue[] 433 ** sname:VkVideoSessionKHR 434 ** sname:VkVideoSessionParametersKHR 435endif::VK_KHR_video_queue[] 436 * sname:VkPhysicalDevice objects cannot: be explicitly destroyed. 437 Instead, they are implicitly destroyed when the sname:VkInstance object 438 they are retrieved from is destroyed. 439 * sname:VkInstance objects can: be destroyed once all sname:VkDevice 440 objects created from any of its sname:VkPhysicalDevice objects have been 441 destroyed. 442 443ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 444[[fundamentals-objectmodel-external]] 445=== External Object Handles 446 447As defined above, the scope of object handles created or allocated from a 448sname:VkDevice is limited to that logical device. 449Objects which are not in scope are said to be external. 450To bring an external object into scope, an external handle must: be exported 451from the object in the source scope and imported into the destination scope. 452 453[NOTE] 454.Note 455==== 456The scope of external handles and their associated resources may: vary 457according to their type, but they can: generally be shared across process 458and API boundaries. 459==== 460endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 461 462 463[[fundamentals-abi]] 464== Application Binary Interface 465 466The mechanism by which Vulkan is made available to applications is platform- 467or implementation- defined. 468On many platforms the C interface described in this Specification is 469provided by a shared library. 470Since shared libraries can be changed independently of the applications that 471use them, they present particular compatibility challenges, and this 472Specification places some requirements on them. 473 474Shared library implementations must: use the default Application Binary 475Interface (ABI) of the standard C compiler for the platform, or provide 476customized API headers that cause application code to use the 477implementation's non-default ABI. 478An ABI in this context means the size, alignment, and layout of C data 479types; the procedure calling convention; and the naming convention for 480shared library symbols corresponding to C functions. 481Customizing the calling convention for a platform is usually accomplished by 482defining <<boilerplate-platform-specific-calling-conventions,calling 483convention macros>> appropriately in `vk_platform.h`. 484 485On platforms where Vulkan is provided as a shared library, library symbols 486beginning with "`vk`" and followed by a digit or uppercase letter are 487reserved for use by the implementation. 488Applications which use Vulkan must: not provide definitions of these 489symbols. 490This allows the Vulkan shared library to be updated with additional symbols 491for new API versions or extensions without causing symbol conflicts with 492existing applications. 493 494Shared library implementations should: provide library symbols for commands 495in the highest version of this Specification they support, and for 496ifdef::VK_KHR_surface[] 497<<wsi,Window System Integration>> 498endif::VK_KHR_surface[] 499ifndef::VK_KHR_surface[] 500Window System Integration 501endif::VK_KHR_surface[] 502extensions relevant to the platform. 503They may: also provide library symbols for commands defined by additional 504extensions. 505 506[NOTE] 507.Note 508==== 509These requirements and recommendations are intended to allow implementors to 510take advantage of platform-specific conventions for SDKs, ABIs, library 511versioning mechanisms, etc. 512while still minimizing the code changes necessary to port applications or 513libraries between platforms. 514Platform vendors, or providers of the _de facto_ standard Vulkan shared 515library for a platform, are encouraged to document what symbols the shared 516library provides and how it will be versioned when new symbols are added. 517 518Applications should: only rely on shared library symbols for commands in the 519minimum core version required by the application. 520flink:vkGetInstanceProcAddr and flink:vkGetDeviceProcAddr should: be used to 521obtain function pointers for commands in core versions beyond the 522application's minimum required version. 523==== 524 525 526[[fundamentals-commandsyntax]] 527== Command Syntax and Duration 528 529The Specification describes Vulkan commands as functions or procedures using 530C99 syntax. 531Language bindings for other languages such as C++ and JavaScript may: allow 532for stricter parameter passing, or object-oriented interfaces. 533 534Vulkan uses the standard C types for the base type of scalar parameters 535(e.g. types from `<stdint.h>`), with exceptions described below, or 536elsewhere in the text when appropriate: 537 538[open,refpage='VkBool32',desc='Vulkan boolean type',type='basetypes',xrefs='VK_TRUE VK_FALSE'] 539-- 540basetype:VkBool32 represents boolean `True` and `False` values, since C does 541not have a sufficiently portable built-in boolean type: 542 543include::{generated}/api/basetypes/VkBool32.adoc[] 544 545ename:VK_TRUE represents a boolean *True* (unsigned integer 1) value, and 546ename:VK_FALSE a boolean *False* (unsigned integer 0) value. 547 548All values returned from a Vulkan implementation in a basetype:VkBool32 will 549be either ename:VK_TRUE or ename:VK_FALSE. 550 551Applications must: not pass any other values than ename:VK_TRUE or 552ename:VK_FALSE into a Vulkan implementation where a basetype:VkBool32 is 553expected. 554-- 555 556[open,refpage='VK_TRUE',desc='Boolean true value',type='consts',xrefs='VkBool32 VK_FALSE'] 557-- 558ename:VK_TRUE is a constant representing a basetype:VkBool32 *True* value. 559 560include::{generated}/api/enums/VK_TRUE.adoc[] 561-- 562 563[open,refpage='VK_FALSE',desc='Boolean false value',type='consts',xrefs='VkBool32 VK_TRUE'] 564-- 565ename:VK_FALSE is a constant representing a basetype:VkBool32 *False* value. 566 567include::{generated}/api/enums/VK_FALSE.adoc[] 568-- 569 570 571[open,refpage='VkDeviceSize',desc='Vulkan device memory size and offsets',type='basetypes'] 572-- 573basetype:VkDeviceSize represents device memory size and offset values: 574 575include::{generated}/api/basetypes/VkDeviceSize.adoc[] 576-- 577 578ifdef::VK_VERSION_1_0,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 579[open,refpage='VkDeviceAddress',desc='Vulkan device address type',type='basetypes'] 580-- 581basetype:VkDeviceAddress represents device buffer address values: 582 583include::{generated}/api/basetypes/VkDeviceAddress.adoc[] 584-- 585endif::VK_VERSION_1_0,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 586 587Commands that create Vulkan objects are of the form ftext:vkCreate* and take 588stext:Vk*CreateInfo structures with the parameters needed to create the 589object. 590These Vulkan objects are destroyed with commands of the form 591ftext:vkDestroy*. 592 593The last in-parameter to each command that creates or destroys a Vulkan 594object is pname:pAllocator. 595The pname:pAllocator parameter can: be set to a non-`NULL` value such that 596allocations for the given object are delegated to an application provided 597callback; refer to the <<memory-allocation,Memory Allocation>> chapter for 598further details. 599 600Commands that allocate Vulkan objects owned by pool objects are of the form 601ftext:vkAllocate*, and take stext:Vk*AllocateInfo structures. 602These Vulkan objects are freed with commands of the form ftext:vkFree*. 603These objects do not take allocators; if host memory is needed, they will 604use the allocator that was specified when their parent pool was created. 605 606Commands are recorded into a command buffer by calling API commands of the 607form ftext:vkCmd*. 608Each such command may: have different restrictions on where it can: be used: 609in a primary and/or secondary command buffer, inside and/or outside a render 610pass, and in one or more of the supported queue types. 611These restrictions are documented together with the definition of each such 612command. 613 614The _duration_ of a Vulkan command refers to the interval between calling 615the command and its return to the caller. 616 617 618[[fundamentals-commandsyntax-results-lifetime]] 619=== Lifetime of Retrieved Results 620 621Information is retrieved from the implementation with commands of the form 622ftext:vkGet* and ftext:vkEnumerate*. 623 624Unless otherwise specified for an individual command, the results are 625_invariant_; that is, they will remain unchanged when retrieved again by 626calling the same command with the same parameters, so long as those 627parameters themselves all remain valid. 628 629 630[[fundamentals-threadingbehavior]] 631== Threading Behavior 632 633Vulkan is intended to provide scalable performance when used on multiple 634host threads. 635All commands support being called concurrently from multiple threads, but 636certain parameters, or components of parameters are defined to be 637_externally synchronized_. 638This means that the caller must: guarantee that no more than one thread is 639using such a parameter at a given time. 640 641More precisely, Vulkan commands use simple stores to update the state of 642Vulkan objects. 643A parameter declared as externally synchronized may: have its contents 644updated at any time during the host execution of the command. 645If two commands operate on the same object and at least one of the commands 646declares the object to be externally synchronized, then the caller must: 647guarantee not only that the commands do not execute simultaneously, but also 648that the two commands are separated by an appropriate memory barrier (if 649needed). 650 651[NOTE] 652.Note 653==== 654Memory barriers are particularly relevant for hosts based on the ARM CPU 655architecture, which is more weakly ordered than many developers are 656accustomed to from x86/x64 programming. 657Fortunately, most higher-level synchronization primitives (like the pthread 658library) perform memory barriers as a part of mutual exclusion, so mutexing 659Vulkan objects via these primitives will have the desired effect. 660==== 661 662Similarly the application must: avoid any potential data hazard of 663application-owned memory that has its 664<<fundamentals-objectmodel-lifetime-acquire,ownership temporarily acquired>> 665by a Vulkan command. 666While the ownership of application-owned memory remains acquired by a 667command the implementation may: read the memory at any point, and it may: 668write non-code:const qualified memory at any point. 669Parameters referring to non-code:const qualified application-owned memory 670are not marked explicitly as _externally synchronized_ in the Specification. 671 672ifdef::VK_KHR_deferred_host_operations[] 673If an application is using <<deferred-host-operations, deferred host 674operations>> in a command, and that operation is successfully deferred, 675object parameters and application-owned memory passed to that command may: 676be accessed at any time until the deferred operation is complete. 677endif::VK_KHR_deferred_host_operations[] 678 679Many object types are _immutable_, meaning the objects cannot: change once 680they have been created. 681These types of objects never need external synchronization, except that they 682must: not be destroyed while they are in use on another thread. 683In certain special cases mutable object parameters are internally 684synchronized, making external synchronization unnecessary. 685Any command parameters that are not labeled as externally synchronized are 686either not mutated by the command or are internally synchronized. 687Additionally, certain objects related to a command's parameters (e.g. 688command pools and descriptor pools) may: be affected by a command, and must: 689also be externally synchronized. 690These implicit parameters are documented as described below. 691 692Parameters of commands that are externally synchronized are listed below. 693 694include::{generated}/hostsynctable/parameters.adoc[] 695 696ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 697For slink:VkPipelineCache objects created with pname:flags containing 698ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, the above table 699is extended with the pname:pipelineCache parameter to 700ftext:vkCreate*Pipelines being externally synchronized. 701endif::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 702 703There are also a few instances where a command can: take in a user allocated 704list whose contents are externally synchronized parameters. 705In these cases, the caller must: guarantee that at most one thread is using 706a given element within the list at a given time. 707These parameters are listed below. 708 709include::{generated}/hostsynctable/parameterlists.adoc[] 710 711In addition, there are some implicit parameters that need to be externally 712synchronized. 713For example, when a pname:commandBuffer parameter needs to be externally 714synchronized, it implies that the pname:commandPool from which that command 715buffer was allocated also needs to be externally synchronized. 716The implicit parameters and their associated object are listed below. 717 718include::{generated}/hostsynctable/implicit.adoc[] 719 720 721[[fundamentals-validusage]] 722== Valid Usage 723 724// preserving old id for permalinking 725[[fundamentals-errors]] 726Valid usage defines a set of conditions which must: be met in order to 727achieve well-defined runtime behavior in an application. 728These conditions depend only on Vulkan state, and the parameters or objects 729whose usage is constrained by the condition. 730 731The core layer assumes applications are using the API correctly. 732Except as documented elsewhere in the Specification, the behavior of the 733core layer to an application using the API incorrectly is undefined:, and 734may: include program termination. 735However, implementations must: ensure that incorrect usage by an application 736does not affect the integrity of the operating system, the Vulkan 737implementation, or other Vulkan client applications in the system. 738In particular, any guarantees made by an operating system about whether 739memory from one process can: be visible to another process or not must: not 740be violated by a Vulkan implementation for *any memory allocation*. 741Vulkan implementations are not required: to make additional security or 742integrity guarantees beyond those provided by the OS unless explicitly 743directed by the application's use of a particular feature or extension. 744 745[NOTE] 746.Note 747==== 748For instance, if an operating system guarantees that data in all its memory 749allocations are set to zero when newly allocated, the Vulkan implementation 750must: make the same guarantees for any allocations it controls (e.g. 751slink:VkDeviceMemory). 752 753Similarly, if an operating system guarantees that use-after-free of host 754allocations will not result in values written by another process becoming 755visible, the same guarantees must: be made by the Vulkan implementation for 756device memory. 757==== 758 759ifdef::VK_VERSION_1_1[] 760If the <<features-protectedMemory, pname:protectedMemory>> feature is 761supported, the implementation provides additional guarantees when invalid 762usage occurs to prevent values in protected memory from being accessed or 763inferred outside of protected operations, as described in 764<<memory-protected-access-rules>>. 765endif::VK_VERSION_1_1[] 766 767Some valid usage conditions have dependencies on runtime limits or feature 768availability. 769It is possible to validate these conditions against Vulkan's minimum 770supported values for these limits and features, or some subset of other 771known values. 772 773Valid usage conditions do not cover conditions where well-defined behavior 774(including returning an error code) exists. 775 776Valid usage conditions should: apply to the command or structure where 777complete information about the condition would be known during execution of 778an application. 779This is such that a validation layer or linter can: be written directly 780against these statements at the point they are specified. 781 782[NOTE] 783.Note 784==== 785This does lead to some non-obvious places for valid usage statements. 786For instance, the valid values for a structure might depend on a separate 787value in the calling command. 788In this case, the structure itself will not reference this valid usage as it 789is impossible to determine validity from the structure that it is invalid - 790instead this valid usage would be attached to the calling command. 791 792Another example is draw state - the state setters are independent, and can 793cause a legitimately invalid state configuration between draw calls; so the 794valid usage statements are attached to the place where all state needs to be 795valid - at the drawing command. 796==== 797 798Valid usage conditions are described in a block labelled "`Valid Usage`" 799following each command or structure they apply to. 800 801 802[[fundamentals-validation]] 803=== Usage Validation 804 805Vulkan is a layered API. 806The lowest layer is the core Vulkan layer, as defined by this Specification. 807The application can: use additional layers above the core for debugging, 808validation, and other purposes. 809 810One of the core principles of Vulkan is that building and submitting command 811buffers should: be highly efficient. 812Thus error checking and validation of state in the core layer is minimal, 813although more rigorous validation can: be enabled through the use of layers. 814 815Validation of correct API usage is left to validation layers. 816Applications should: be developed with validation layers enabled, to help 817catch and eliminate errors. 818Once validated, released applications should: not enable validation layers 819by default. 820 821 822[[fundamentals-implicit-validity]] 823=== Implicit Valid Usage 824 825Some valid usage conditions apply to all commands and structures in the API, 826unless explicitly denoted otherwise for a specific command or structure. 827These conditions are considered _implicit_, and are described in a block 828labelled "`Valid Usage (Implicit)`" following each command or structure they 829apply to. 830Implicit valid usage conditions are described in detail below. 831 832 833[[fundamentals-validusage-handles]] 834==== Valid Usage for Object Handles 835 836Any input parameter to a command that is an object handle must: be a valid 837object handle, unless otherwise specified. 838An object handle is valid if: 839 840 * It has been created or allocated by a previous, successful call to the 841 API. 842 Such calls are noted in the Specification. 843 * It has not been deleted or freed by a previous call to the API. 844 Such calls are noted in the Specification. 845 * Any objects used by that object, either as part of creation or 846 execution, must: also be valid. 847 848The reserved values dlink:VK_NULL_HANDLE and `NULL` can: be used in place of 849valid non-dispatchable handles and dispatchable handles, respectively, when 850_explicitly called out in the Specification_. 851Any command that creates an object successfully must: not return these 852values. 853It is valid to pass these values to ftext:vkDestroy* or ftext:vkFree* 854commands, which will silently ignore these values. 855 856 857[[fundamentals-validusage-pointers]] 858==== Valid Usage for Pointers 859 860Any parameter that is a pointer must: be a _valid pointer_ only if it is 861explicitly called out by a Valid Usage statement. 862 863A pointer is "`valid`" if it points at memory containing values of the 864number and type(s) expected by the command, and all fundamental types 865accessed through the pointer (e.g. as elements of an array or as members of 866a structure) satisfy the alignment requirements of the host processor. 867 868 869[[fundamentals-validusage-strings]] 870==== Valid Usage for Strings 871 872Any parameter that is a pointer to `char` must: be a finite sequence of 873values terminated by a null character, or if _explicitly called out in the 874Specification_, can: be `NULL`. 875 876 877[[fundamentals-validusage-enums]] 878==== Valid Usage for Enumerated Types 879 880Any parameter of an enumerated type must: be a valid enumerant for that 881type. 882A enumerant is valid if: 883 884 * The enumerant is defined as part of the enumerated type. 885 * The enumerant is not the special value (suffixed with 886 etext:_MAX_ENUM^1^) defined for the enumerated type. 887 8881:: 889 This special value exists only to ensure that C `enum` types are 32 bits 890 in size. 891 It is not part of the API, and should: not be used by applications. 892 893Any enumerated type returned from a query command or otherwise output from 894Vulkan to the application must: not have a reserved value. 895Reserved values are values not defined by any extension for that enumerated 896type. 897 898[NOTE] 899.Note 900==== 901This language is intended to accommodate cases such as "`hidden`" extensions 902known only to driver internals, or layers enabling extensions without 903knowledge of the application, without allowing return of values not defined 904by any extension. 905==== 906 907[NOTE] 908.Note 909==== 910Application developers are encouraged to be careful when using `switch` 911statements with Vulkan API enums. 912This is because new extensions can add new values to existing enums. 913Using a `default:` statement within a `switch` may avoid future compilation 914issues. 915 916ifdef::VK_VERSION_1_2[] 917This is particularly true for enums such as elink:VkDriverId, which may have 918values added that do not belong to a corresponding new extension. 919endif::VK_VERSION_1_2[] 920==== 921 922 923[[fundamentals-validusage-flags]] 924==== Valid Usage for Flags 925 926[open,refpage='VkFlags',desc='Vulkan bitmasks',type='basetypes',xrefs='VkColorComponentFlags VkFlags64'] 927-- 928A collection of flags is represented by a bitmask using the type 929basetype:VkFlags: 930 931include::{generated}/api/basetypes/VkFlags.adoc[] 932 933Bitmasks are passed to many commands and structures to compactly represent 934options, but basetype:VkFlags is not used directly in the API. 935Instead, a etext:Vk*Flags type which is an alias of basetype:VkFlags, and 936whose name matches the corresponding etext:Vk*FlagBits that are valid for 937that type, is used. 938 939Any etext:Vk*Flags member or parameter used in the API as an input must: be 940a valid combination of bit flags. 941A valid combination is either zero or the bitwise OR of valid bit flags. 942A bit flag is valid if: 943 944 * The bit flag is defined as part of the etext:Vk*FlagBits type, where the 945 bits type is obtained by taking the flag type and replacing the trailing 946 etext:Flags with etext:FlagBits. 947 For example, a flag value of type tlink:VkColorComponentFlags must: 948 contain only bit flags defined by elink:VkColorComponentFlagBits. 949 * The flag is allowed in the context in which it is being used. 950 For example, in some cases, certain bit flags or combinations of bit 951 flags are mutually exclusive. 952 953Any etext:Vk*Flags member or parameter returned from a query command or 954otherwise output from Vulkan to the application may: contain bit flags 955undefined: in its corresponding etext:Vk*FlagBits type. 956An application cannot: rely on the state of these unspecified bits. 957 958Only the low-order 31 bits (bit positions zero through 30) are available for 959use as flag bits. 960 961[NOTE] 962.Note 963==== 964This restriction is due to poorly defined behavior by C compilers given a C 965enumerant value of `0x80000000`. 966In some cases adding this enumerant value may increase the size of the 967underlying etext:Vk*FlagBits type, breaking the ABI. 968==== 969-- 970 971ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2,VK_KHR_synchronization2[] 972[open,refpage='VkFlags64',desc='Vulkan 64-bit bitmasks',type='basetypes',xrefs='VkFlags'] 973-- 974A collection of 64-bit flags is represented by a bitmask using the type 975basetype:VkFlags64: 976 977include::{generated}/api/basetypes/VkFlags64.adoc[] 978 979When the 31 bits available in basetype:VkFlags are insufficient, the 980basetype:VkFlags64 type can be passed to commands and structures to 981represent up to 64 options. 982basetype:VkFlags64 is not used directly in the API. 983Instead, a etext:Vk*Flags2 type which is an alias of basetype:VkFlags64, and 984whose name matches the corresponding etext:Vk*FlagBits2 that are valid for 985that type, is used. 986 987Any etext:Vk*Flags2 member or parameter used in the API as an input must: be 988a valid combination of bit flags. 989A valid combination is either zero or the bitwise OR of valid bit flags. 990A bit flag is valid if: 991 992 * The bit flag is defined as part of the etext:Vk*FlagBits2 type, where 993 the bits type is obtained by taking the flag type and replacing the 994 trailing etext:Flags2 with etext:FlagBits2. 995 For example, a flag value of type tlink:VkAccessFlags2KHR must: contain 996 only bit flags defined by elink:VkAccessFlagBits2KHR. 997 * The flag is allowed in the context in which it is being used. 998 For example, in some cases, certain bit flags or combinations of bit 999 flags are mutually exclusive. 1000 1001Any etext:Vk*Flags2 member or parameter returned from a query command or 1002otherwise output from Vulkan to the application may: contain bit flags 1003undefined: in its corresponding etext:Vk*FlagBits2 type. 1004An application cannot: rely on the state of these unspecified bits. 1005 1006[NOTE] 1007.Note 1008==== 1009Both the etext:Vk*FlagBits2 type, and the individual bits defined for that 1010type, are defined as `uint64_t` integers in the C API. 1011This is in contrast to the 32-bit types, where the etext:Vk*FlagBits type is 1012defined as a C `enum` and the individual bits as enumerants belonging to 1013that `enum`. 1014As a result, there is less compile-time type checking possible for the 101564-bit types. 1016This is unavoidable since there is no sufficiently portable way to define a 101764-bit `enum` type in C99. 1018==== 1019-- 1020endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2,VK_KHR_synchronization2[] 1021 1022 1023[[fundamentals-validusage-sType]] 1024==== Valid Usage for Structure Types 1025 1026Any parameter that is a structure containing a pname:sType member must: have 1027a value of ptext:sType which is a valid elink:VkStructureType value matching 1028the type of the structure. 1029 1030 1031[[fundamentals-validusage-pNext]] 1032==== Valid Usage for Structure Pointer Chains 1033 1034Any parameter that is a structure containing a code:void* ptext:pNext member 1035must: have a value of pname:pNext that is either `NULL`, or is a pointer to 1036a valid _extending structure_, containing ptext:sType and ptext:pNext 1037members as described in the <<vulkan-styleguide,Vulkan Documentation and 1038Extensions>> document in the section "`Extending Structures`". 1039The set of structures connected by ptext:pNext pointers is referred to as a 1040_pname:pNext chain_. 1041 1042Each structure included in the pname:pNext chain must: be defined at runtime 1043by either: 1044 1045 * a core version which is supported 1046 * an extension which is enabled 1047ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1048 * a supported device extension in the case of physical-device-level 1049functionality added by the device extension 1050endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1051 1052Each type of extending structure must: not appear more than once in a 1053ptext:pNext chain, including any 1054<<extendingvulkan-compatibility-aliases,aliases>>. 1055This general rule may be explicitly overridden for specific structures. 1056 1057Any component of the implementation (the loader, any enabled layers, and 1058drivers) must: skip over, without processing (other than reading the 1059pname:sType and pname:pNext members) any extending structures in the chain 1060not defined by core versions or extensions supported by that component. 1061 1062As a convenience to implementations and layers needing to iterate through a 1063structure pointer chain, the Vulkan API provides two _base structures_. 1064These structures allow for some type safety, and can be used by Vulkan API 1065functions that operate on generic inputs and outputs. 1066 1067[open,refpage='VkBaseInStructure',desc='Base structure for a read-only pointer chain',type='structs'] 1068-- 1069The sname:VkBaseInStructure structure is defined as: 1070 1071include::{generated}/api/structs/VkBaseInStructure.adoc[] 1072 1073 * pname:sType is the structure type of the structure being iterated 1074 through. 1075 * pname:pNext is `NULL` or a pointer to the next structure in a structure 1076 chain. 1077 1078sname:VkBaseInStructure can be used to facilitate iterating through a 1079read-only structure pointer chain. 1080-- 1081 1082[open,refpage='VkBaseOutStructure',desc='Base structure for a read-only pointer chain',type='structs'] 1083-- 1084The sname:VkBaseOutStructure structure is defined as: 1085 1086include::{generated}/api/structs/VkBaseOutStructure.adoc[] 1087 1088 * pname:sType is the structure type of the structure being iterated 1089 through. 1090 * pname:pNext is `NULL` or a pointer to the next structure in a structure 1091 chain. 1092 1093sname:VkBaseOutStructure can be used to facilitate iterating through a 1094structure pointer chain that returns data back to the application. 1095-- 1096 1097 1098[[fundamentals-validusage-nested-structs]] 1099==== Valid Usage for Nested Structures 1100 1101The above conditions also apply recursively to members of structures 1102provided as input to a command, either as a direct argument to the command, 1103or themselves a member of another structure. 1104 1105Specifics on valid usage of each command are covered in their individual 1106sections. 1107 1108 1109[[fundamentals-validusage-extensions]] 1110==== Valid Usage for Extensions 1111 1112Instance-level functionality or behavior added by an <<extensions, instance 1113extension>> to the API must: not be used unless that extension is supported 1114by the instance as determined by 1115flink:vkEnumerateInstanceExtensionProperties, and that extension is enabled 1116in slink:VkInstanceCreateInfo. 1117 1118Physical-device-level functionality or behavior added by an <<extensions, 1119instance extension>> to the API must: not be used unless that extension is 1120supported by the instance as determined by 1121flink:vkEnumerateInstanceExtensionProperties, and that extension is enabled 1122in slink:VkInstanceCreateInfo. 1123 1124ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1125Physical-device-level functionality or behavior added by a <<extensions, 1126device extension>> to the API must: not be used unless the conditions 1127described in <<initialization-phys-dev-extensions, Extending Physical Device 1128Core Functionality>> are met. 1129endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1130 1131Device functionality or behavior added by a <<extensions, device extension>> 1132to the API must: not be used unless that extension is supported by the 1133device as determined by flink:vkEnumerateDeviceExtensionProperties, and that 1134extension is enabled in slink:VkDeviceCreateInfo. 1135 1136 1137[[fundamentals-validusage-versions]] 1138==== Valid Usage for Newer Core Versions 1139 1140ifdef::VK_VERSION_1_1[] 1141 1142Instance-level functionality or behavior added by a <<versions, new core 1143version>> of the API must: not be used unless it is supported by the 1144instance as determined by flink:vkEnumerateInstanceVersion and the specified 1145version of slink:VkApplicationInfo::pname:apiVersion. 1146 1147endif::VK_VERSION_1_1[] 1148 1149Physical-device-level functionality or behavior added by a <<versions, new 1150core version>> of the API must: not be used unless it is supported by the 1151physical device as determined by 1152slink:VkPhysicalDeviceProperties::pname:apiVersion and the specified version 1153of slink:VkApplicationInfo::pname:apiVersion. 1154 1155Device-level functionality or behavior added by a <<versions, new core 1156version>> of the API must: not be used unless it is supported by the device 1157as determined by slink:VkPhysicalDeviceProperties::pname:apiVersion and the 1158specified version of slink:VkApplicationInfo::pname:apiVersion. 1159 1160 1161[[fundamentals-returncodes]] 1162== `VkResult` Return Codes 1163 1164[open,refpage='VkResult',desc='Vulkan command return codes',type='enums'] 1165-- 1166While the core Vulkan API is not designed to capture incorrect usage, some 1167circumstances still require return codes. 1168Commands in Vulkan return their status via return codes that are in one of 1169two categories: 1170 1171 * Successful completion codes are returned when a command needs to 1172 communicate success or status information. 1173 All successful completion codes are non-negative values. 1174 * Run time error codes are returned when a command needs to communicate a 1175 failure that could only be detected at runtime. 1176 All runtime error codes are negative values. 1177 1178All return codes in Vulkan are reported via elink:VkResult return values. 1179The possible codes are: 1180 1181include::{generated}/api/enums/VkResult.adoc[] 1182 1183[[fundamentals-successcodes]] 1184.Success Codes 1185 * ename:VK_SUCCESS Command successfully completed 1186 * ename:VK_NOT_READY A fence or query has not yet completed 1187 * ename:VK_TIMEOUT A wait operation has not completed in the specified 1188 time 1189 * ename:VK_EVENT_SET An event is signaled 1190 * ename:VK_EVENT_RESET An event is unsignaled 1191 * ename:VK_INCOMPLETE A return array was too small for the result 1192ifdef::VK_KHR_swapchain[] 1193 * ename:VK_SUBOPTIMAL_KHR A swapchain no longer matches the surface 1194 properties exactly, but can: still be used to present to the surface 1195 successfully. 1196endif::VK_KHR_swapchain[] 1197ifdef::VK_KHR_deferred_host_operations[] 1198 * ename:VK_THREAD_IDLE_KHR A deferred operation is not complete but there 1199 is currently no work for this thread to do at the time of this call. 1200 * ename:VK_THREAD_DONE_KHR A deferred operation is not complete but there 1201 is no work remaining to assign to additional threads. 1202 * ename:VK_OPERATION_DEFERRED_KHR A deferred operation was requested and 1203 at least some of the work was deferred. 1204 * ename:VK_OPERATION_NOT_DEFERRED_KHR A deferred operation was requested 1205 and no operations were deferred. 1206endif::VK_KHR_deferred_host_operations[] 1207ifdef::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 1208 * ename:VK_PIPELINE_COMPILE_REQUIRED A requested pipeline creation would 1209 have required compilation, but the application requested compilation to 1210 not be performed. 1211endif::VK_VERSION_1_3,VK_EXT_pipeline_creation_cache_control[] 1212 1213[[fundamentals-errorcodes]] 1214.Error codes 1215 * ename:VK_ERROR_OUT_OF_HOST_MEMORY A host memory allocation has failed. 1216 * ename:VK_ERROR_OUT_OF_DEVICE_MEMORY A device memory allocation has 1217 failed. 1218 * ename:VK_ERROR_INITIALIZATION_FAILED Initialization of an object could 1219 not be completed for implementation-specific reasons. 1220 * ename:VK_ERROR_DEVICE_LOST The logical or physical device has been lost. 1221 See <<devsandqueues-lost-device,Lost Device>> 1222 * ename:VK_ERROR_MEMORY_MAP_FAILED Mapping of a memory object has failed. 1223 * ename:VK_ERROR_LAYER_NOT_PRESENT A requested layer is not present or 1224 could not be loaded. 1225 * ename:VK_ERROR_EXTENSION_NOT_PRESENT A requested extension is not 1226 supported. 1227 * ename:VK_ERROR_FEATURE_NOT_PRESENT A requested feature is not supported. 1228 * ename:VK_ERROR_INCOMPATIBLE_DRIVER The requested version of Vulkan is 1229 not supported by the driver or is otherwise incompatible for 1230 implementation-specific reasons. 1231 * ename:VK_ERROR_TOO_MANY_OBJECTS Too many objects of the type have 1232 already been created. 1233 * ename:VK_ERROR_FORMAT_NOT_SUPPORTED A requested format is not supported 1234 on this device. 1235 * ename:VK_ERROR_FRAGMENTED_POOL A pool allocation has failed due to 1236 fragmentation of the pool's memory. 1237 This must: only be returned if no attempt to allocate host or device 1238 memory was made to accommodate the new allocation. 1239ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1240 This should: be returned in preference to 1241 ename:VK_ERROR_OUT_OF_POOL_MEMORY, but only if the implementation is 1242 certain that the pool allocation failure was due to fragmentation. 1243endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1244ifdef::VK_KHR_surface[] 1245 * ename:VK_ERROR_SURFACE_LOST_KHR A surface is no longer available. 1246 * ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR The requested window is already 1247 in use by Vulkan or another API in a manner which prevents it from being 1248 used again. 1249endif::VK_KHR_surface[] 1250ifdef::VK_KHR_swapchain[] 1251 * ename:VK_ERROR_OUT_OF_DATE_KHR A surface has changed in such a way that 1252 it is no longer compatible with the swapchain, and further presentation 1253 requests using the swapchain will fail. 1254 Applications must: query the new surface properties and recreate their 1255 swapchain if they wish to continue presenting to the surface. 1256endif::VK_KHR_swapchain[] 1257ifdef::VK_KHR_display_swapchain[] 1258 * ename:VK_ERROR_INCOMPATIBLE_DISPLAY_KHR The display used by a swapchain 1259 does not use the same presentable image layout, or is incompatible in a 1260 way that prevents sharing an image. 1261endif::VK_KHR_display_swapchain[] 1262ifdef::VK_NV_glsl_shader[] 1263 * ename:VK_ERROR_INVALID_SHADER_NV One or more shaders failed to compile 1264 or link. 1265 More details are reported back to the application via 1266 `apiext:VK_EXT_debug_report` if enabled. 1267endif::VK_NV_glsl_shader[] 1268ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1269 * ename:VK_ERROR_OUT_OF_POOL_MEMORY A pool memory allocation has failed. 1270 This must: only be returned if no attempt to allocate host or device 1271 memory was made to accommodate the new allocation. 1272 If the failure was definitely due to fragmentation of the pool, 1273 ename:VK_ERROR_FRAGMENTED_POOL should: be returned instead. 1274endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1275ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_KHR_external_semaphore,VK_KHR_external_fence[] 1276 * ename:VK_ERROR_INVALID_EXTERNAL_HANDLE An external handle is not a valid 1277 handle of the specified type. 1278endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_KHR_external_semaphore,VK_KHR_external_fence[] 1279ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1280 * ename:VK_ERROR_FRAGMENTATION A descriptor pool creation has failed due 1281 to fragmentation. 1282endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1283ifdef::VK_EXT_buffer_device_address[] 1284 * ename:VK_ERROR_INVALID_DEVICE_ADDRESS_EXT A buffer creation failed 1285 because the requested address is not available. 1286endif::VK_EXT_buffer_device_address[] 1287ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1288 * ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS A buffer creation 1289ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 1290 or memory allocation 1291endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 1292 failed because the requested address is not available. 1293ifdef::VK_KHR_ray_tracing_pipeline[] 1294 A shader group handle assignment failed because the requested shader 1295 group handle information is no longer valid. 1296endif::VK_KHR_ray_tracing_pipeline[] 1297endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 1298ifdef::VK_EXT_full_screen_exclusive[] 1299 * ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT An operation on a 1300 swapchain created with 1301 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT failed as it 1302 did not have exclusive full-screen access. 1303 This may: occur due to implementation-dependent reasons, outside of the 1304 application's control. 1305endif::VK_EXT_full_screen_exclusive[] 1306ifdef::VK_EXT_image_compression_control[] 1307 * ename:VK_ERROR_COMPRESSION_EXHAUSTED_EXT An image creation failed 1308 because internal resources required for compression are exhausted. 1309 This must: only be returned when fixed-rate compression is requested. 1310endif::VK_EXT_image_compression_control[] 1311ifdef::VK_KHR_video_queue[] 1312 * ename:VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR The requested 1313 tlink:VkImageUsageFlags are not supported. 1314 * ename:VK_ERROR_VIDEO_PICTURE_LAYOUT_NOT_SUPPORTED_KHR The requested 1315 video picture layout is not supported. 1316 * ename:VK_ERROR_VIDEO_PROFILE_OPERATION_NOT_SUPPORTED_KHR A video profile 1317 operation specified via 1318 slink:VkVideoProfileInfoKHR::pname:videoCodecOperation is not supported. 1319 * ename:VK_ERROR_VIDEO_PROFILE_FORMAT_NOT_SUPPORTED_KHR Format parameters 1320 in a requested slink:VkVideoProfileInfoKHR chain are not supported. 1321 * ename:VK_ERROR_VIDEO_PROFILE_CODEC_NOT_SUPPORTED_KHR Codec-specific 1322 parameters in a requested slink:VkVideoProfileInfoKHR chain are not 1323 supported. 1324 * ename:VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR The specified video 1325 Std header version is not supported. 1326endif::VK_KHR_video_queue[] 1327 * ename:VK_ERROR_UNKNOWN An unknown error has occurred; either the 1328 application has provided invalid input, or an implementation failure has 1329 occurred. 1330 1331If a command returns a runtime error, unless otherwise specified any output 1332parameters will have undefined: contents, except that if the output 1333parameter is a structure with pname:sType and pname:pNext fields, those 1334fields will be unmodified. 1335Any structures chained from pname:pNext will also have undefined: contents, 1336except that pname:sType and pname:pNext will be unmodified. 1337 1338etext:VK_ERROR_OUT_OF_*_MEMORY errors do not modify any currently existing 1339Vulkan objects. 1340Objects that have already been successfully created can: still be used by 1341the application. 1342 1343[NOTE] 1344.Note 1345==== 1346As a general rule, ftext:Free, ftext:Release, and ftext:Reset commands do 1347not return ename:VK_ERROR_OUT_OF_HOST_MEMORY, while any other command with a 1348return code may: return it. 1349Any exceptions from this rule are described for those commands. 1350==== 1351 1352ename:VK_ERROR_UNKNOWN will be returned by an implementation when an 1353unexpected error occurs that cannot be attributed to valid behavior of the 1354application and implementation. 1355Under these conditions, it may: be returned from any command returning a 1356elink:VkResult. 1357 1358[NOTE] 1359.Note 1360==== 1361ename:VK_ERROR_UNKNOWN is not expected to ever be returned if the 1362application behavior is valid, and if the implementation is bug-free. 1363If ename:VK_ERROR_UNKNOWN is received, the application should be checked 1364against the latest validation layers to verify correct behavior as much as 1365possible. 1366If no issues are identified it could be an implementation issue, and the 1367implementor should be contacted for support. 1368==== 1369 1370Performance-critical commands generally do not have return codes. 1371If a runtime error occurs in such commands, the implementation will defer 1372reporting the error until a specified point. 1373For commands that record into command buffers (ftext:vkCmd*) runtime errors 1374are reported by fname:vkEndCommandBuffer. 1375-- 1376 1377 1378[[fundamentals-numerics]] 1379== Numeric Representation and Computation 1380 1381Implementations normally perform computations in floating-point, and must: 1382meet the range and precision requirements defined under "`Floating-Point 1383Computation`" below. 1384 1385These requirements only apply to computations performed in Vulkan operations 1386outside of shader execution, such as texture image specification and 1387sampling, and per-fragment operations. 1388Range and precision requirements during shader execution differ and are 1389specified by the <<spirvenv-precision-operation, Precision and Operation of 1390SPIR-V Instructions>> section. 1391 1392In some cases, the representation and/or precision of operations is 1393implicitly limited by the specified format of vertex or texel data consumed 1394by Vulkan. 1395Specific floating-point formats are described later in this section. 1396 1397 1398[[fundamentals-floatingpoint]] 1399=== Floating-Point Computation 1400 1401Most floating-point computation is performed in SPIR-V shader modules. 1402The properties of computation within shaders are constrained as defined by 1403the <<spirvenv-precision-operation, Precision and Operation of SPIR-V 1404Instructions>> section. 1405 1406Some floating-point computation is performed outside of shaders, such as 1407viewport and depth range calculations. 1408For these computations, we do not specify how floating-point numbers are to 1409be represented, or the details of how operations on them are performed, but 1410only place minimal requirements on representation and precision as described 1411in the remainder of this section. 1412 1413ifdef::editing-notes[] 1414[NOTE] 1415.editing-note 1416==== 1417(Jon, Bug 14966) This is a rat's nest of complexity, both in terms of 1418describing/enumerating places such computation may: take place (other than 1419"`not shader code`") and in how implementations may: do it. 1420We have consciously deferred the resolution of this issue to post-1.0, and 1421in the meantime, the following language inherited from the OpenGL 1422Specification is inserted as a placeholder. 1423Hopefully it can: be tightened up considerably. 1424==== 1425endif::editing-notes[] 1426 1427We require simply that numbers`' floating-point parts contain enough bits 1428and that their exponent fields are large enough so that individual results 1429of floating-point operations are accurate to about 1 part in 10^5^. 1430The maximum representable magnitude for all floating-point values must: be 1431at least 2^32^. 1432 1433 {empty}:: [eq]#x {times} 0 = 0 {times} x = 0# for any non-infinite and 1434 non-[eq]#NaN# [eq]#x#. 1435 {empty}:: [eq]#1 {times} x = x {times} 1 = x#. 1436 {empty}:: [eq]#x {plus} 0 = 0 {plus} x = x#. 1437 {empty}:: [eq]#0^0^ = 1#. 1438 1439Occasionally, further requirements will be specified. 1440Most single-precision floating-point formats meet these requirements. 1441 1442The special values [eq]#Inf# and [eq]#-Inf# encode values with magnitudes 1443too large to be represented; the special value [eq]#NaN# encodes "`Not A 1444Number`" values resulting from undefined: arithmetic operations such as 1445[eq]#0 / 0#. 1446Implementations may: support [eq]#Inf# and [eq]#NaN# in their floating-point 1447computations. 1448Any computation which does not support either [eq]#Inf# or [eq]#NaN#, for 1449which that value is an input or output will yield an undefined: value. 1450 1451 1452[[fundamentals-fp-conversion]] 1453=== Floating-Point Format Conversions 1454 1455When a value is converted to a defined floating-point representation, finite 1456values falling between two representable finite values are rounded to one or 1457the other. 1458The rounding mode is not defined. 1459Finite values whose magnitude is larger than that of any representable 1460finite value may be rounded either to the closest representable finite value 1461or to the appropriately signed infinity. 1462For unsigned destination formats any negative values are converted to zero. 1463Positive infinity is converted to positive infinity; negative infinity is 1464converted to negative infinity in signed formats and to zero in unsigned 1465formats; and any [eq]#NaN# is converted to a [eq]#NaN#. 1466 1467 1468[[fundamentals-fp16]] 1469=== 16-Bit Floating-Point Numbers 1470 147116-bit floating point numbers are defined in the "`16-bit floating point 1472numbers`" section of the <<data-format,Khronos Data Format Specification>>. 1473 1474 1475[[fundamentals-fp11]] 1476=== Unsigned 11-Bit Floating-Point Numbers 1477 1478Unsigned 11-bit floating point numbers are defined in the "`Unsigned 11-bit 1479floating point numbers`" section of the <<data-format,Khronos Data Format 1480Specification>>. 1481 1482 1483[[fundamentals-fp10]] 1484=== Unsigned 10-Bit Floating-Point Numbers 1485 1486Unsigned 10-bit floating point numbers are defined in the "`Unsigned 10-bit 1487floating point numbers`" section of the <<data-format,Khronos Data Format 1488Specification>>. 1489 1490 1491[[fundamentals-general]] 1492=== General Requirements 1493 1494Any representable floating-point value in the appropriate format is legal as 1495input to a Vulkan command that requires floating-point data. 1496The result of providing a value that is not a floating-point number to such 1497a command is unspecified, but must: not lead to Vulkan interruption or 1498termination. 1499For example, providing a negative zero (where applicable) or a denormalized 1500number to a Vulkan command must: yield deterministic results, while 1501providing a [eq]#NaN# or [eq]#Inf# yields unspecified results. 1502 1503Some calculations require division. 1504In such cases (including implied divisions performed by vector 1505normalization), division by zero produces an unspecified result but must: 1506not lead to Vulkan interruption or termination. 1507 1508 1509[[fundamentals-fixedconv]] 1510== Fixed-Point Data Conversions 1511 1512When generic vertex attributes and pixel color or depth _components_ are 1513represented as integers, they are often (but not always) considered to be 1514_normalized_. 1515Normalized integer values are treated specially when being converted to and 1516from floating-point values, and are usually referred to as _normalized 1517fixed-point_. 1518 1519In the remainder of this section, [eq]#b# denotes the bit width of the 1520fixed-point integer representation. 1521When the integer is one of the types defined by the API, [eq]#b# is the bit 1522width of that type. 1523When the integer comes from an <<resources-images,image>> containing color 1524or depth component texels, [eq]#b# is the number of bits allocated to that 1525component in its <<formats,specified image format>>. 1526 1527The signed and unsigned fixed-point representations are assumed to be 1528[eq]#b#-bit binary two's-complement integers and binary unsigned integers, 1529respectively. 1530 1531 1532[[fundamentals-fixedfpconv]] 1533=== Conversion from Normalized Fixed-Point to Floating-Point 1534 1535Unsigned normalized fixed-point integers represent numbers in the range 1536[eq]#[0,1]#. 1537The conversion from an unsigned normalized fixed-point value [eq]#c# to the 1538corresponding floating-point value [eq]#f# is defined as 1539 1540[latexmath] 1541++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1542f = { c \over { 2^b - 1 } } 1543++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1544 1545Signed normalized fixed-point integers represent numbers in the range 1546[eq]#[-1,1]#. 1547The conversion from a signed normalized fixed-point value [eq]#c# to the 1548corresponding floating-point value [eq]#f# is performed using 1549 1550[latexmath] 1551++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1552f = \max\left( {c \over {2^{b-1} - 1}}, -1.0 \right) 1553++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1554 1555Only the range [eq]#[-2^b-1^ {plus} 1, 2^b-1^ - 1]# is used to represent 1556signed fixed-point values in the range [eq]#[-1,1]#. 1557For example, if [eq]#b = 8#, then the integer value [eq]#-127# corresponds 1558to [eq]#-1.0# and the value 127 corresponds to [eq]#1.0#. 1559This equation is used everywhere that signed normalized fixed-point values 1560are converted to floating-point. 1561 1562Note that while zero is exactly expressible in this representation, one 1563value ([eq]#-128# in the example) is outside the representable range, and 1564implementations must: clamp it to [eq]#-1.0#. 1565Where the value is subject to further processing by the implementation, e.g. 1566during texture filtering, values less than [eq]#-1.0# may: be used but the 1567result must: be clamped before the value is returned to shaders. 1568 1569 1570[[fundamentals-fpfixedconv]] 1571=== Conversion from Floating-Point to Normalized Fixed-Point 1572 1573The conversion from a floating-point value [eq]#f# to the corresponding 1574unsigned normalized fixed-point value [eq]#c# is defined by first clamping 1575[eq]#f# to the range [eq]#[0,1]#, then computing 1576 1577 {empty}:: [eq]#c = convertFloatToUint(f {times} (2^b^ - 1), b)# 1578 1579where [eq]#convertFloatToUint(r,b)# returns one of the two unsigned binary 1580integer values with exactly [eq]#b# bits which are closest to the 1581floating-point value [eq]#r#. 1582Implementations should: round to nearest. 1583If [eq]#r# is equal to an integer, then that integer value must: be 1584returned. 1585In particular, if [eq]#f# is equal to 0.0 or 1.0, then [eq]#c# must: be 1586assigned 0 or [eq]#2^b^ - 1#, respectively. 1587 1588The conversion from a floating-point value [eq]#f# to the corresponding 1589signed normalized fixed-point value [eq]#c# is performed by clamping [eq]#f# 1590to the range [eq]#[-1,1]#, then computing 1591 1592 {empty}:: [eq]#c = convertFloatToInt(f {times} (2^b-1^ - 1), b)# 1593 1594where [eq]#convertFloatToInt(r,b)# returns one of the two signed 1595two's-complement binary integer values with exactly [eq]#b# bits which are 1596closest to the floating-point value [eq]#r#. 1597Implementations should: round to nearest. 1598If [eq]#r# is equal to an integer, then that integer value must: be 1599returned. 1600In particular, if [eq]#f# is equal to -1.0, 0.0, or 1.0, then [eq]#c# must: 1601be assigned [eq]#-(2^b-1^ - 1)#, 0, or [eq]#2^b-1^ - 1#, respectively. 1602 1603This equation is used everywhere that floating-point values are converted to 1604signed normalized fixed-point. 1605 1606 1607[[fundamentals-common-objects]] 1608== Common Object Types 1609 1610Some types of Vulkan objects are used in many different structures and 1611command parameters, and are described here. 1612These types include _offsets_, _extents_, and _rectangles_. 1613 1614 1615=== Offsets 1616 1617Offsets are used to describe a pixel location within an image or 1618framebuffer, as an (x,y) location for two-dimensional images, or an (x,y,z) 1619location for three-dimensional images. 1620 1621[open,refpage='VkOffset2D',desc='Structure specifying a two-dimensional offset',type='structs'] 1622-- 1623A two-dimensional offset is defined by the structure: 1624 1625include::{generated}/api/structs/VkOffset2D.adoc[] 1626 1627 * pname:x is the x offset. 1628 * pname:y is the y offset. 1629 1630include::{generated}/validity/structs/VkOffset2D.adoc[] 1631-- 1632 1633[open,refpage='VkOffset3D',desc='Structure specifying a three-dimensional offset',type='structs'] 1634-- 1635A three-dimensional offset is defined by the structure: 1636 1637include::{generated}/api/structs/VkOffset3D.adoc[] 1638 1639 * pname:x is the x offset. 1640 * pname:y is the y offset. 1641 * pname:z is the z offset. 1642 1643include::{generated}/validity/structs/VkOffset3D.adoc[] 1644-- 1645 1646 1647=== Extents 1648 1649Extents are used to describe the size of a rectangular region of pixels 1650within an image or framebuffer, as (width,height) for two-dimensional 1651images, or as (width,height,depth) for three-dimensional images. 1652 1653[open,refpage='VkExtent2D',desc='Structure specifying a two-dimensional extent',type='structs'] 1654-- 1655A two-dimensional extent is defined by the structure: 1656 1657include::{generated}/api/structs/VkExtent2D.adoc[] 1658 1659 * pname:width is the width of the extent. 1660 * pname:height is the height of the extent. 1661 1662include::{generated}/validity/structs/VkExtent2D.adoc[] 1663-- 1664 1665[open,refpage='VkExtent3D',desc='Structure specifying a three-dimensional extent',type='structs'] 1666-- 1667A three-dimensional extent is defined by the structure: 1668 1669include::{generated}/api/structs/VkExtent3D.adoc[] 1670 1671 * pname:width is the width of the extent. 1672 * pname:height is the height of the extent. 1673 * pname:depth is the depth of the extent. 1674 1675include::{generated}/validity/structs/VkExtent3D.adoc[] 1676-- 1677 1678 1679=== Rectangles 1680 1681[open,refpage='VkRect2D',desc='Structure specifying a two-dimensional subregion',type='structs'] 1682-- 1683Rectangles are used to describe a specified rectangular region of pixels 1684within an image or framebuffer. 1685Rectangles include both an offset and an extent of the same dimensionality, 1686as described above. 1687Two-dimensional rectangles are defined by the structure 1688 1689include::{generated}/api/structs/VkRect2D.adoc[] 1690 1691 * pname:offset is a slink:VkOffset2D specifying the rectangle offset. 1692 * pname:extent is a slink:VkExtent2D specifying the rectangle extent. 1693 1694include::{generated}/validity/structs/VkRect2D.adoc[] 1695-- 1696 1697 1698// VkStructureType is pretty long, 1699// so keep it as a last chapter section for readability. 1700=== Structure Types 1701 1702[open,refpage='VkStructureType',desc='Vulkan structure types (pname:sType)',type='enums'] 1703-- 1704Each value corresponds to a particular structure with a pname:sType member 1705with a matching name. 1706As a general rule, the name of each elink:VkStructureType value is obtained 1707by taking the name of the structure, stripping the leading etext:Vk, 1708prefixing each capital letter with etext:_, converting the entire resulting 1709string to upper case, and prefixing it with etext:VK_STRUCTURE_TYPE_. 1710For example, structures of type slink:VkImageCreateInfo correspond to a 1711elink:VkStructureType value of ename:VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, 1712and thus a structure of this type must: have its pname:sType member set to 1713this value before it is passed to the API. 1714 1715The values ename:VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO and 1716ename:VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO are reserved for internal 1717use by the loader, and do not have corresponding Vulkan structures in this 1718Specification. 1719 1720Structure types supported by the Vulkan API include: 1721 1722include::{generated}/api/enums/VkStructureType.adoc[] 1723-- 1724 1725 1726[[fundamentals-api-name-aliases]] 1727== API Name Aliases 1728 1729A small number of APIs did not follow the <<vulkan-styleguide, naming 1730conventions>> when initially defined. 1731For consistency, when we discover an API name that violates the naming 1732conventions, we rename it in the Specification, XML, and header files. 1733For backwards compatibility, the original (incorrect) name is retained as a 1734"`typo alias`". 1735The alias is deprecated and should not be used, but will be retained 1736indefinitely. 1737 1738[NOTE] 1739.Note 1740==== 1741ename:VK_STENCIL_FRONT_AND_BACK is an example of a _typo alias_. 1742It was initially defined as part of elink:VkStencilFaceFlagBits. 1743Once the naming inconsistency was noticed, it was renamed to 1744ename:VK_STENCIL_FACE_FRONT_AND_BACK, and the old name was aliased to the 1745correct name. 1746==== 1747