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