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