xref: /third_party/vk-gl-cts/external/vulkan-docs/src/appendices/versions.adoc

// Copyright 2015-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[appendix]

[[versions]]
= Core Revisions (Informative)

New minor versions of the Vulkan API are defined periodically by the Khronos
Vulkan Working Group.
These consist of some amount of additional functionality added to the core
API, potentially including both new functionality and functionality
<<extendingvulkan-compatibility-promotion,promoted>> from extensions.

ifdef::VK_VERSION_1_1[]
It is possible to build the specification for earlier versions, but to aid
readability of the latest versions, this appendix gives an overview of the
changes as compared to earlier versions.
endif::VK_VERSION_1_1[]

ifndef::VKSC_VERSION_1_0[:promoted: {generated}/meta]
ifdef::VKSC_VERSION_1_0[:promoted: {appendices}/sc_static]

ifdef::VK_VERSION_1_3[]
[[versions-1.3]]
== Version 1.3

// Unfortunately we cannot include titles in an open refpage block, so this
// is a refpage-specific alternate form of the section.
ifdef::isrefpage[]
[open,refpage='VK_VERSION_1_3',desc='Vulkan version 1.3',type='feature',anchor='versions-1.3',xrefs='VK_VERSION_1_0 VK_VERSION_1_1 VK_VERSION_1_2']
--
Vulkan Version 1.3 <<extendingvulkan-compatibility-promotion,promoted>> a
number of key extensions into the core API:

include::{generated}/meta/promoted_extensions_VK_VERSION_1_3.adoc[]

All differences in behavior between these extensions and the corresponding
Vulkan 1.3 functionality are summarized in the <<versions-1.3-promotions,
Vulkan 1.3 specification appendix>>.

include::{generated}/interfaces/VK_VERSION_1_3.adoc[]
--
endif::isrefpage[]

// This is the spec-specific form of the section
[[versions-1.3-promotions]]
Vulkan Version 1.3 <<extendingvulkan-compatibility-promotion,promoted>> a
number of key extensions into the core API:

include::{generated}/meta/promoted_extensions_VK_VERSION_1_3.adoc[]

All differences in behavior between these extensions and the corresponding
Vulkan 1.3 functionality are summarized below.

=== Differences Relative to `VK_EXT_4444_formats`

If the `apiext:VK_EXT_4444_formats` extension is not supported, support for
all formats defined by it are optional in Vulkan 1.3.
There are no members in the slink:VkPhysicalDeviceVulkan13Features structure
corresponding to the slink:VkPhysicalDevice4444FormatsFeaturesEXT structure.

=== Differences Relative to `VK_EXT_extended_dynamic_state`

All dynamic state enumerants and entry points defined by
`apiext:VK_EXT_extended_dynamic_state` are required in Vulkan 1.3.
There are no members in the slink:VkPhysicalDeviceVulkan13Features structure
corresponding to the slink:VkPhysicalDeviceExtendedDynamicStateFeaturesEXT
structure.

=== Differences Relative to `VK_EXT_extended_dynamic_state2`

The optional dynamic state enumerants and entry points defined by
`apiext:VK_EXT_extended_dynamic_state2` for patch control points and logic
op are not promoted in Vulkan 1.3.
There are no members in the slink:VkPhysicalDeviceVulkan13Features structure
corresponding to the slink:VkPhysicalDeviceExtendedDynamicState2FeaturesEXT
structure.

=== Differences Relative to `VK_EXT_texel_buffer_alignment`

The more specific alignment requirements defined by
slink:VkPhysicalDeviceTexelBufferAlignmentProperties are required in Vulkan
1.3.
There are no members in the slink:VkPhysicalDeviceVulkan13Features structure
corresponding to the slink:VkPhysicalDeviceTexelBufferAlignmentFeaturesEXT
structure.
The pname:texelBufferAlignment feature is enabled if using a Vulkan 1.3
instance.

=== Differences Relative to `VK_EXT_texture_compression_astc_hdr`

If the `apiext:VK_EXT_texture_compression_astc_hdr` extension is not
supported, support for all formats defined by it are optional in Vulkan 1.3.
The <<features-textureCompressionASTC_HDR,
pname:textureCompressionASTC_HDR>> member of
slink:VkPhysicalDeviceVulkan13Features indicates whether a Vulkan 1.3
implementation supports these formats.

=== Differences Relative to `VK_EXT_ycbcr_2plane_444_formats`

If the `apiext:VK_EXT_ycbcr_2plane_444_formats` extension is not supported,
support for all formats defined by it are optional in Vulkan 1.3.
There are no members in the slink:VkPhysicalDeviceVulkan13Features structure
corresponding to the slink:VkPhysicalDeviceYcbcr2Plane444FormatsFeaturesEXT
structure.

=== Additional Vulkan 1.3 Feature Support

[[versions-1.3-new-features]]
In addition to the promoted extensions described above, Vulkan 1.3 added
required support for:

  * SPIR-V version 1.6
  ** SPIR-V 1.6 deprecates (but does not remove) the code:WorkgroupSize
     decoration.
  * The <<features-bufferDeviceAddress, pname:bufferDeviceAddress>> feature
    which indicates support for accessing memory in shaders as storage
    buffers via flink:vkGetBufferDeviceAddress.
  * The <<features-vulkanMemoryModel, pname:vulkanMemoryModel>> and
    <<features-vulkanMemoryModelDeviceScope,
    pname:vulkanMemoryModelDeviceScope>> features, which indicate support
    for the corresponding Vulkan Memory Model capabilities.
  * The <<limits-maxInlineUniformTotalSize,
    pname:maxInlineUniformTotalSize>> limit is added to provide the total
    size of all inline uniform block bindings in a pipeline layout.

include::{generated}/interfaces/VK_VERSION_1_3.adoc[]

endif::VK_VERSION_1_3[]


ifdef::VK_VERSION_1_2[]
[[versions-1.2]]
== Version 1.2

// Unfortunately we cannot include titles in an open refpage block, so this
// is a refpage-specific alternate form of the section.
ifdef::isrefpage[]
[open,refpage='VK_VERSION_1_2',desc='Vulkan version 1.2',type='feature',anchor='versions-1.2',xrefs='VK_VERSION_1_0 VK_VERSION_1_1 VK_VERSION_1_3']
--
Vulkan Version 1.2 <<extendingvulkan-compatibility-promotion,promoted>> a
number of key extensions into the core API:

// Must be redefined in the refpage content
ifndef::VKSC_VERSION_1_0[:promoted: {generated}/meta]
ifdef::VKSC_VERSION_1_0[:promoted: {appendices}/sc_static]

include::{promoted}/promoted_extensions_VK_VERSION_1_2.adoc[]

All differences in behavior between these extensions and the corresponding
Vulkan 1.2 functionality are summarized in the <<versions-1.2-promotions,
Vulkan 1.2 specification appendix>>.

include::{generated}/interfaces/VK_VERSION_1_2.adoc[]
--
endif::isrefpage[]

// This is the spec-specific form of the section
[[versions-1.2-promotions]]
Vulkan Version 1.2 <<extendingvulkan-compatibility-promotion,promoted>> a
number of key extensions into the core API:

include::{promoted}/promoted_extensions_VK_VERSION_1_2.adoc[]

All differences in behavior between these extensions and the corresponding
Vulkan 1.2 functionality are summarized below.

=== Differences Relative to `VK_KHR_8bit_storage`

If the `apiext:VK_KHR_8bit_storage` extension is not supported, support for
the SPIR-V <<features-storageBuffer8BitAccess,
pname:storageBuffer8BitAccess>> capability in shader modules is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:storageBuffer8BitAccess when
queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_draw_indirect_count`

If the `apiext:VK_KHR_draw_indirect_count` extension is not supported,
support for the entry points flink:vkCmdDrawIndirectCount and
flink:vkCmdDrawIndexedIndirectCount is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:drawIndirectCount when queried
via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_sampler_mirror_clamp_to_edge`

If the `apiext:VK_KHR_sampler_mirror_clamp_to_edge` extension is not
supported, support for the elink:VkSamplerAddressMode
ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:samplerMirrorClampToEdge when
queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_EXT_descriptor_indexing`

If the `apiext:VK_EXT_descriptor_indexing` extension is not supported,
support for the <<features-descriptorIndexing, pname:descriptorIndexing>>
feature is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:descriptorIndexing when
queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_EXT_scalar_block_layout`

If the `apiext:VK_EXT_scalar_block_layout` extension is not supported,
support for the <<features-scalarBlockLayout, pname:scalarBlockLayout>>
feature is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:scalarBlockLayout when queried
via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_EXT_shader_viewport_index_layer`

The code:ShaderViewportIndexLayerEXT SPIR-V capability was replaced with the
code:ShaderViewportIndex and code:ShaderLayer capabilities.
Declaring both is equivalent to declaring code:ShaderViewportIndexLayerEXT.
If the `apiext:VK_EXT_shader_viewport_index_layer` extension is not
supported, support for the code:ShaderViewportIndexLayerEXT SPIR-V
capability is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:shaderOutputViewportIndex and
slink:VkPhysicalDeviceVulkan12Features::pname:shaderOutputLayer when queried
via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_buffer_device_address`

If the `apiext:VK_KHR_buffer_device_address` extension is not supported,
support for the <<features-bufferDeviceAddress, pname:bufferDeviceAddress>>
feature is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:bufferDeviceAddress when
queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_shader_atomic_int64`

If the `apiext:VK_KHR_shader_atomic_int64` extension is not supported,
support for the <<features-shaderBufferInt64Atomics,
pname:shaderBufferInt64Atomics>> feature is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:shaderBufferInt64Atomics when
queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_shader_float16_int8`

If the `apiext:VK_KHR_shader_float16_int8` extension is not supported,
support for the <<features-shaderFloat16, pname:shaderFloat16>> and
<<features-shaderInt8, pname:shaderInt8>> features is optional.
Support for these features are defined by
slink:VkPhysicalDeviceVulkan12Features::pname:shaderFloat16 and
slink:VkPhysicalDeviceVulkan12Features::pname:shaderInt8 when queried via
flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_vulkan_memory_model`

If the `apiext:VK_KHR_vulkan_memory_model` extension is not supported,
support for the <<features-vulkanMemoryModel, pname:vulkanMemoryModel>>
feature is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVulkan12Features::pname:vulkanMemoryModel when queried
via flink:vkGetPhysicalDeviceFeatures2.

=== Additional Vulkan 1.2 Feature Support

[[versions-1.2-new-features]]
In addition to the promoted extensions described above, Vulkan 1.2 added
support for:

  * SPIR-V version 1.4.
  * SPIR-V version 1.5.
  * The <<features-samplerMirrorClampToEdge,
    pname:samplerMirrorClampToEdge>> feature which indicates whether the
    implementation supports the
    ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE sampler address mode.
  * The <<spirvenv-capabilities-table-ShaderNonUniform,
    code:ShaderNonUniform>> capability in SPIR-V version 1.5.
  * The <<features-shaderOutputViewportIndex,
    pname:shaderOutputViewportIndex>> feature which indicates that the
    <<spirvenv-capabilities-table-ShaderViewportIndex,
    code:ShaderViewportIndex>> capability can be used.
  * The <<features-shaderOutputLayer, pname:shaderOutputLayer>> feature
    which indicates that the <<spirvenv-capabilities-table-ShaderLayer,
    code:ShaderLayer>> capability can be used.
  * The <<features-subgroupBroadcastDynamicId,
    pname:subgroupBroadcastDynamicId>> feature which allows the "`Id`"
    operand of code:OpGroupNonUniformBroadcast to be dynamically uniform
    within a subgroup, and the "`Index`" operand of
    code:OpGroupNonUniformQuadBroadcast to be dynamically uniform within a
    derivative group, in shader modules of version 1.5 or higher.
  * The <<features-drawIndirectCount, pname:drawIndirectCount>> feature
    which indicates whether the flink:vkCmdDrawIndirectCount and
    flink:vkCmdDrawIndexedIndirectCount functions can be used.
  * The <<features-descriptorIndexing, pname:descriptorIndexing>> feature
    which indicates the implementation supports the minimum number of
    descriptor indexing features as defined in the <<features-requirements,
    Feature Requirements>> section.
  * The <<features-samplerFilterMinmax, pname:samplerFilterMinmax>> feature
    which indicates whether the implementation supports the minimum number
    of image formats that support the
    ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_MINMAX_BIT feature bit as
    defined by the
    <<limits-filterMinmaxSingleComponentFormats-minimum-requirements,
    pname:filterMinmaxSingleComponentFormats>> property minimum
    requirements.
  * The <<limits-framebufferIntegerColorSampleCounts,
    pname:framebufferIntegerColorSampleCounts>> limit which indicates the
    color sample counts that are supported for all framebuffer color
    attachments with integer formats.

include::{generated}/interfaces/VK_VERSION_1_2.adoc[]

endif::VK_VERSION_1_2[]


ifdef::VK_VERSION_1_1[]
[[versions-1.1]]
== Version 1.1

// Unfortunately we cannot include titles in an open refpage block, so this
// is a refpage-specific alternate form of the section.
ifdef::isrefpage[]
[open,refpage='VK_VERSION_1_1',desc='Vulkan version 1.1',type='feature',anchor='versions-1.1',xrefs='VK_VERSION_1_0 VK_VERSION_1_2 VK_VERSION_1_3']
--
Vulkan Version 1.1 <<extendingvulkan-compatibility-promotion,promoted>> a
number of key extensions into the core API:

// Must be redefined in the refpage content
ifndef::VKSC_VERSION_1_0[:promoted: {generated}/meta]
ifdef::VKSC_VERSION_1_0[:promoted: {appendices}/sc_static]

include::{promoted}/promoted_extensions_VK_VERSION_1_1.adoc[]

All differences in behavior between these extensions and the corresponding
Vulkan 1.1 functionality are summarized in the <<versions-1.1-promotions,
Vulkan 1.1 specification appendix>>.

include::{generated}/interfaces/VK_VERSION_1_1.adoc[]
--
endif::isrefpage[]

// This is the spec-specific form of the section
[[versions-1.1-promotions]]
Vulkan Version 1.1 <<extendingvulkan-compatibility-promotion,promoted>> a
number of key extensions into the core API:

include::{promoted}/promoted_extensions_VK_VERSION_1_1.adoc[]

All differences in behavior between these extensions and the corresponding
Vulkan 1.1 functionality are summarized below.

=== Differences Relative to `VK_KHR_16bit_storage`

If the `apiext:VK_KHR_16bit_storage` extension is not supported, support for
the <<features-storageBuffer16BitAccess, pname:storageBuffer16BitAccess>>
feature is optional.
Support for this feature is defined by
slink:VkPhysicalDevice16BitStorageFeatures::pname:storageBuffer16BitAccess
ifdef::VK_VERSION_1_2[]
or slink:VkPhysicalDeviceVulkan11Features::pname:storageBuffer16BitAccess
endif::VK_VERSION_1_2[]
when queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_sampler_ycbcr_conversion`

If the `apiext:VK_KHR_sampler_ycbcr_conversion` extension is not supported,
support for the <<features-samplerYcbcrConversion,
pname:samplerYcbcrConversion>> feature is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceSamplerYcbcrConversionFeatures::pname:samplerYcbcrConversion
ifdef::VK_VERSION_1_2[]
or slink:VkPhysicalDeviceVulkan11Features::pname:samplerYcbcrConversion
endif::VK_VERSION_1_2[]
when queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_shader_draw_parameters`

If the `apiext:VK_KHR_shader_draw_parameters` extension is not supported,
support for the
{spirv}/KHR/SPV_KHR_shader_draw_parameters.html[`SPV_KHR_shader_draw_parameters`]
SPIR-V extension is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceShaderDrawParametersFeatures::pname:shaderDrawParameters
ifdef::VK_VERSION_1_2[]
or slink:VkPhysicalDeviceVulkan11Features::pname:shaderDrawParameters
endif::VK_VERSION_1_2[]
when queried via flink:vkGetPhysicalDeviceFeatures2.

=== Differences Relative to `VK_KHR_variable_pointers`

If the `apiext:VK_KHR_variable_pointers` extension is not supported, support
for the <<features-variablePointersStorageBuffer,
pname:variablePointersStorageBuffer>> feature is optional.
Support for this feature is defined by
slink:VkPhysicalDeviceVariablePointersFeatures::pname:variablePointersStorageBuffer
ifdef::VK_VERSION_1_2[]
or
slink:VkPhysicalDeviceVulkan11Features::pname:variablePointersStorageBuffer
endif::VK_VERSION_1_2[]
when queried via flink:vkGetPhysicalDeviceFeatures2.

=== Additional Vulkan 1.1 Feature Support

[[versions-1.1-new-features]]
In addition to the promoted extensions described above, Vulkan 1.1 added
support for:

  * The <<shaders-group-operations, group operations>> and
    <<shaders-scope-subgroup, subgroup scope>>.
  * The <<memory-protected-memory, protected memory>> feature.
  * A new command to enumerate the instance version:
    flink:vkEnumerateInstanceVersion.
  * The slink:VkPhysicalDeviceShaderDrawParametersFeatures feature query
    struct (where the `apiext:VK_KHR_shader_draw_parameters` extension did
    not have one).

include::{generated}/interfaces/VK_VERSION_1_1.adoc[]

endif::VK_VERSION_1_1[]


[[versions-1.0]]
== Version 1.0

// Unfortunately we cannot include titles in an open refpage block, so this
// is a refpage-specific alternate form of the section.
ifdef::isrefpage[]
[open,refpage='VK_VERSION_1_0',desc='Vulkan version 1.0',type='feature',anchor='versions-1.0',xrefs='VK_VERSION_1_1 VK_VERSION_1_2 VK_VERSION_1_3']
--
Vulkan Version 1.0 was the initial release of the Vulkan API.

include::{generated}/interfaces/VK_VERSION_1_0.adoc[]
--
endif::isrefpage[]

// This is the spec-specific form of the section
Vulkan Version 1.0 was the initial release of the Vulkan API.

include::{generated}/interfaces/VK_VERSION_1_0.adoc[]