Deprecation

Functionality in the specification such as commands and structures may be marked as deprecated, indicating that applications should avoid using it. A link to an explanatory section will be provided to explain how and why the functionality was deprecated, what functionality replaces it (if any), and what applications should do instead. Reasons for deprecating functionality may include:

  • Newer functionality fulfills the same role

  • Does not work as originally intended

  • Functionality cannot continue to work with newer features

Deprecation is tagged in the xml registry, with both core versions and extensions able to express deprecation of any other interface. All deprecations will be listed in this section, however only functionality deprecated by a core version that is present will be emphasized with warnings.

Deprecated functionality will remain available for backwards compatibility until a new major core version removes it, but applications targeting more recent versions of Vulkan should still avoid using deprecated functionality. Interactions with deprecated functionality will often be omitted when new extensions or features are developed, so deprecated functionality may not work with the latest features.

Extensions can be deprecated in their entirety by a different mechanism, and are marked as deprecated in their appendix. See the Deprecation section of the Extensions chapter for more information.

Deprecated Functionality

When functionality is deprecated, an explanation of its deprecation will be added to the below sections.

This list is a work in progress - we intend to add other items to this section over time; things such as shader modules (deprecated by VK_KHR_maintenance5) and anything superseded by a new version of the same functionality (e.g. VK_KHR_synchronization2).

Physical Device Queries: Deprecation via version 2

VK_KHR_get_physical_device_properties2 was incorporated into Vulkan 1.1, which introduced new versions of several physical device query functions. These provide the same functionality as the Vulkan 1.0 functionality but with greater extensibility.

When querying device features, vkGetPhysicalDeviceFeatures2 should be used instead of vkGetPhysicalDeviceFeatures. When enabling device features, VkPhysicalDeviceFeatures2 should be provided in the pNext chain of VkDeviceCreateInfo instead of using VkDeviceCreateInfo::pNext:pEnabledFeatures.

Version Macros: Deprecation via replacements including API variant

The version macros that do not take the API variant into account, such as VK_MAKE_VERSION or VK_VERSION_MAJOR, are deprecated by those that do, such as VK_MAKE_API_VERSION or VK_API_VERSION_MAJOR.

Instead of VK_API_VERSION, specific version defines (e.g. VK_API_VERSION_1_0) or the VK_MAKE_API_VERSION macro should be used instead.

Render Pass Functions: Deprecation via version 2

VK_KHR_create_renderpass2 was incorporated into Vulkan 1.2, which introduced new versions of several render pass functions. These provide the same functionality as the Vulkan 1.0 functionality but with greater extensibility.

Render pass objects and all related commands are further deprecated by dynamic rendering in Vulkan 1.4.

Render Pass Objects: Deprecation via dynamic rendering

In Vulkan 1.3, the VK_KHR_dynamic_rendering extension was promoted into core, which added a new way to specify render passes without needing to create VkFramebuffer and VkRenderPass objects. However, subpass functionality had no equivalent, meaning dynamic rendering was only suitable as a substitute for content not using subpasses.

In Vulkan 1.4 however, VK_KHR_dynamic_rendering_local_read was promoted into core as well, which allows the expression of most subpass functionality in core or extensions. Any subpass functionality which was not replicated is still expressible but requires applications to split work over multiple dynamic render pass instances. Functionality not covered with local reads would result in most or all vendors splitting the subpass internally.

VK_QCOM_render_pass_shader_resolve does not have equivalent functionality exposed via dynamic rendering. Use of deprecated functionality will be required to use that extension unless/until replacements are created.

Outside of vendor extensions, applications are advised to make use of vkCmdBeginRendering and vkCmdEndRendering to manage render passes from this API version onward.