diff --git a/docs/misc.adoc b/docs/misc.adoc index 18b7dc2b2..ddf0b671c 100644 --- a/docs/misc.adoc +++ b/docs/misc.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -61,7 +61,7 @@ image::./images/debug-window.png[Debug Window] == Driver version -The debug window shows the driver version of the GPU, which follows the https://registry.khronos.org/vulkan/specs/1.3-extensions/html/chap44.html#extendingvulkan-coreversions-versionnumbers[Vulkan semantics], with a major, minor, and patch number. +The debug window shows the driver version of the GPU, which follows the https://registry.khronos.org/vulkan/specs/latest/html/chap44.html#extendingvulkan-coreversions-versionnumbers[Vulkan semantics], with a major, minor, and patch number. New versions of the driver will increment these numbers. The framework is able to get these values by calling `vkGetPhysicalDeviceProperties(physical_device, &properties)`. diff --git a/samples/api/hpp_timestamp_queries/README.adoc b/samples/api/hpp_timestamp_queries/README.adoc index cc9afd063..d1bd21527 100644 --- a/samples/api/hpp_timestamp_queries/README.adoc +++ b/samples/api/hpp_timestamp_queries/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023-2024, The Khronos Group +- Copyright (c) 2023-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -36,8 +36,8 @@ improve performance where needed. == Introduction -Vulkan offers several https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#queries[query types] that allow you to query different types of information from the GPU. -One such query type is the https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#queries-timestamps[timestamp query]. +Vulkan offers several https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#queries[query types] that allow you to query different types of information from the GPU. +One such query type is the https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#queries-timestamps[timestamp query]. This provides your application with a mechanism to time the execution of commands on the GPU. As with the other query types, a query pool is then used to either directly fetch or copy over the results to the host. @@ -274,7 +274,7 @@ float delta_in_ms = float(time_stamps[1] - time_stamps[0]) * device_limits.times == vk::CommandBuffer::writeTimestamp2 -The https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_synchronization2.html[VK_KHR_synchronization2] extension introduced `vk::CommandBuffer::writeTimestamp2`. +The https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_synchronization2.html[VK_KHR_synchronization2] extension introduced `vk::CommandBuffer::writeTimestamp2`. This is pretty much the same as the `vk::CommandBuffer::writeTimestamp` function used in this sample, but adds support for some additional pipeline stages using `vk::PipelineStageFlags2`. == Verdict diff --git a/samples/api/timestamp_queries/README.adoc b/samples/api/timestamp_queries/README.adoc index f65d4bfa4..6db9159ad 100644 --- a/samples/api/timestamp_queries/README.adoc +++ b/samples/api/timestamp_queries/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2024, Sascha Willems +- Copyright (c) 2022-2025, Sascha Willems - - SPDX-License-Identifier: Apache-2.0 - @@ -32,8 +32,8 @@ improve performance where needed. == Introduction -Vulkan offers several https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#queries[query types] that allow you to query different types of information from the GPU. -One such query type is the https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#queries-timestamps[timestamp query]. +Vulkan offers several https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#queries[query types] that allow you to query different types of information from the GPU. +One such query type is the https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#queries-timestamps[timestamp query]. This provides your application with a mechanism to time the execution of commands on the GPU. As with the other query types, a query pool is then used to either directly fetch or copy over the results to the host. @@ -256,7 +256,7 @@ float delta_in_ms = float(time_stamps[1] - time_stamps[0]) * device_limits.times == vkCmdWriteTimestamp2 -The https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_synchronization2.html[VK_KHR_synchronization2] extension introduced `vkCmdWriteTimestamp2`. +The https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_synchronization2.html[VK_KHR_synchronization2] extension introduced `vkCmdWriteTimestamp2`. This is pretty much the same as the `vkCmdWriteTimestamp` function used in this sample, but adds support for some additional pipeline stages using `VkPipelineStageFlags2`. == Verdict diff --git a/samples/extensions/README.adoc b/samples/extensions/README.adoc index 3c5787f11..cda58c81d 100644 --- a/samples/extensions/README.adoc +++ b/samples/extensions/README.adoc @@ -25,28 +25,28 @@ The goal of these samples is to demonstrate how to use a particular Vulkan exten === xref:./{extension_samplespath}conservative_rasterization/README.adoc[Conservative Rasterization] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_conservative_rasterization[`VK_EXT_conservative_rasterization`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_EXT_conservative_rasterization[`VK_EXT_conservative_rasterization`] Uses conservative rasterization to change the way fragments are generated. Enables overestimation to generate fragments for every pixel touched instead of only pixels that are fully covered. === xref:./{extension_samplespath}dynamic_rendering/README.adoc[Dynamic Rendering] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_dynamic_rendering[`VK_KHR_dynamic_rendering`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_dynamic_rendering[`VK_KHR_dynamic_rendering`] Demonstrates how to use Dynamic Rendering. Read the blog post here for discussion: (https://www.khronos.org/blog/streamlining-render-passes) === xref:./{extension_samplespath}dynamic_rendering_local_read/README.adoc[Dynamic Rendering local read] -*Extension*: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#VK_KHR_dynamic_rendering_local_read[`VK_KHR_dynamic_rendering_local_read`] +*Extension*: https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#VK_KHR_dynamic_rendering_local_read[`VK_KHR_dynamic_rendering_local_read`] Demonstrates how to use Dynamic Rendering with local reads to fully replace render passses with multiple subpasses. See this https://www.khronos.org/blog/streamlining-subpasses[this blogpost]. === xref:./{extension_samplespath}push_descriptors/README.adoc[Push Descriptors] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] Push descriptors apply the push constants concept to descriptor sets. Instead of creating per-object descriptor sets, this example passes descriptors at command buffer creation time. @@ -57,26 +57,26 @@ A transcoded version of the Extensions sample xref:./{extension_samplespath}push === xref:./{extension_samplespath}debug_utils/README.adoc[Debug Utilities] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_debug_utils[`VK_EXT_debug_utils`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_EXT_debug_utils[`VK_EXT_debug_utils`] Uses the debug utilities extension to name and group Vulkan objects (command buffers, images, etc.). This information makes debugging in tools like RenderDoc significantly easier. === xref:./{extension_samplespath}memory_budget/README.adoc[Memory Budget] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_memory_budget[`VK_EXT_memory_budget`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_EXT_memory_budget[`VK_EXT_memory_budget`] Uses the memory budget extension to monitor the allocated memory in the GPU and demonstrates how to use it. === xref:./{extension_samplespath}mesh_shader_culling/README.adoc[Mesh Shader Culling] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_mesh_shader[`VK_EXT_mesh_shader`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_EXT_mesh_shader[`VK_EXT_mesh_shader`] Uses the mesh shader extension to demonstrate how to do basic culling utilizing both a mesh and a task shader. === xref:./{extension_samplespath}ray_queries/README.adoc[Basic ray queries] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_ray_query[`VK_KHR_ray_query`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_ray_query[`VK_KHR_ray_query`], https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] Render a sponza scene using the ray query extension. Shows how to set up all data structures required for ray queries, including the bottom and top level acceleration structures for the geometry and a standard vertex/fragment shader pipeline. @@ -84,7 +84,7 @@ Shadows are cast dynamically by ray queries being cast by the fragment shader. === xref:./{extension_samplespath}ray_tracing_basic/README.adoc[Basic hardware accelerated ray tracing] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] Render a basic scene using the official cross-vendor ray tracing extension. Shows how to setup all data structures required for ray tracing, including the bottom and top level acceleration structures for the geometry, the shader binding table and the ray tracing pipelines with shader groups for ray generation, ray hits, and ray misses. @@ -92,7 +92,7 @@ After dispatching the rays, the final result is copied to the swapchain image. === xref:./{extension_samplespath}ray_tracing_extended/README.adoc[Extended hardware accelerated ray tracing] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] Render Sponza with Ambient Occlusion. Place a vase in center. @@ -102,7 +102,7 @@ Shows how to rebuild the acceleration structure and when to set it to fast rebui === xref:./{extension_samplespath}mesh_shading/README.adoc[Mesh shading] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_KHR_mesh_shader.html[`VK_EXT_mesh_shader`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_mesh_shader.html[`VK_EXT_mesh_shader`] Renders a triangle with the most simple of all possible mesh shader pipeline examples. There is no vertex shader, there is only a mesh and fragment shader. @@ -116,20 +116,20 @@ A transcoded version of the Extensions sample xref:./{extension_samplespath}mesh === xref:./{extension_samplespath}open_gl_interop/README.adoc[OpenGL interoperability] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`], https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] Render a procedural image using OpenGL and incorporate that rendered content into a Vulkan scene. Demonstrates using the same backing memory for a texture in both OpenGL and Vulkan and how to synchronize the APIs using shared semaphores and barriers. === xref:./{extension_samplespath}open_cl_interop/README.adoc[OpenCL interoperability] -**Extensions**: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`], https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] +**Extensions**: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`], https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] This sample shows how to do Vulkan and OpenCL interoperability using cross vendor extensions in both apis. The sample uses OpenCL to update an image that is then displayed in Vulkan. This is done by sharing the memory for that image across the two apis. The sample also shares semaphores for doing cross api synchronization. === xref:./{extension_samplespath}open_cl_interop_arm/README.adoc[OpenCL interoperability (Arm)] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html[`VK_ANDROID_external_memory_android_hardware_buffer`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html[`VK_ANDROID_external_memory_android_hardware_buffer`] This sample demonstrates usage of OpenCL extensions available on Arm devices. Fill a procedural texture using OpenCL and display it using Vulkan. @@ -137,33 +137,33 @@ In this sample data sharing between APIs is achieved using Android Hardware Buff === xref:./{extension_samplespath}timeline_semaphore/README.adoc[Timeline semaphore] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_timeline_semaphore.html[`VK_KHR_timeline_semaphore`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_timeline_semaphore.html[`VK_KHR_timeline_semaphore`] Demonstrates various use cases which are enabled with timeline semaphores. The sample implements "Game of Life" in an esoteric way, using out-of-order signal and wait, multiple waits on same semaphore in different queues, waiting and signalling semaphore on host. === xref:./{extension_samplespath}buffer_device_address/README.adoc[Buffer device address] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_buffer_device_address.html[`VK_KHR_buffer_device_address`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_buffer_device_address.html[`VK_KHR_buffer_device_address`] Demonstrates how to use the buffer device address feature, which enables extreme flexibility in how buffer memory is accessed. === xref:./{extension_samplespath}synchronization_2/README.adoc[Synchronization2] -*Extension* https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_synchronization2[`VK_KHR_synchronization2`] +*Extension* https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_synchronization2[`VK_KHR_synchronization2`] Demonstrates the use of the reworked synchronization api introduced with `VK_KHR_synchronization2`. Based on the compute shading N-Body particle system, this sample uses the new extension to streamline the memory barriers used for the compute and graphics work submissions. === xref:./{extension_samplespath}descriptor_indexing/README.adoc[Descriptor indexing] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_descriptor_indexing.html[`VK_EXT_descriptor_indexing`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_descriptor_indexing.html[`VK_EXT_descriptor_indexing`] Demonstrates how to use descriptor indexing to enable update-after-bind and non-dynamically uniform indexing of descriptors. === xref:./{extension_samplespath}fragment_shading_rate/README.adoc[Fragment shading rate] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] Uses a special framebuffer attachment to control fragment shading rates for different framebuffer regions. This allows explicit control over the number of fragment shader invocations for each pixel covered by a fragment, which is e.g. @@ -171,7 +171,7 @@ useful for foveated rendering. === xref:./{extension_samplespath}fragment_shading_rate_dynamic/README.adoc[Fragment shading rate_dynamic] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] Render a simple scene showing the basics of shading rate dynamic. This sample shows low and high frequency textures over several cubes. @@ -180,20 +180,20 @@ Then it uses that dynamic sample rate map as a base for the next frame. === xref:./{extension_samplespath}ray_tracing_reflection/README.adoc[Ray tracing: reflection, shadow rays] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_descriptor_indexing.html[`VK_EXT_descriptor_indexing`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_scalar_block_layout.html[`VK_EXT_scalar_block_layout`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`], https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_descriptor_indexing.html[`VK_EXT_descriptor_indexing`], https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_scalar_block_layout.html[`VK_EXT_scalar_block_layout`] Render a simple scene showing the basics of ray tracing, including reflection and shadow rays. The sample creates some geometries and create a bottom acceleration structure for each, then make instances of those, using different materials and placing them at different locations. === xref:./{extension_samplespath}ray_tracing_position_fetch/README.adoc[Ray tracing position fetch] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#VK_KHR_ray_tracing_position_fetch[`VK_KHR_ray_tracing_position_fetch`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_ray_tracing_position_fetch[`VK_KHR_ray_tracing_position_fetch`] Shows how to use the ray tracing position fetch extension to directly access vertex positions for a hit triangle from the acceleration structure, instead of having to explicitly pass and unpack that information === xref:./{extension_samplespath}portability/README.adoc[Portability] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#VK_KHR_portability_subset[`VK_KHR_portability_subset`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_portability_subset[`VK_KHR_portability_subset`] Demonstrate how to include non-conformant portable Vulkan implementations by using the portability extension to include those implementations in the device query. An example of a non-conformant portable Vulkan implementation is MoltenVk: https://github.com/KhronosGroup/MoltenVK[MoltenVk]. @@ -201,7 +201,7 @@ Also demonstrate use of beta extension which allows for querying which features === xref:./{extension_samplespath}graphics_pipeline_library/README.adoc[Graphics pipeline library] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_graphics_pipeline_library.html[`VK_EXT_graphics_pipeline_library`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_graphics_pipeline_library.html[`VK_EXT_graphics_pipeline_library`] Uses the graphics pipeline library extensions to improve run-time pipeline creation. Instead of creating the whole pipeline at once, this sample makes use of that extension to pre-build shared pipeline parts such as vertex input state and fragment output state. @@ -209,104 +209,104 @@ These building blocks are then used to create pipelines at runtime, improving bu === xref:./{extension_samplespath}conditional_rendering/README.adoc[Conditional rendering] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_conditional_rendering.html[`VK_EXT_conditional_rendering`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_conditional_rendering.html[`VK_EXT_conditional_rendering`] Demonstrate how to do conditional rendering, dynamically discarding rendering commands without having to update command buffers. This is done by sourcing conditional rendering blocks from a dedicated buffer that can be updated without having to touch command buffers. === xref:./{extension_samplespath}vertex_dynamic_state/README.adoc[Vertex input dynamic state] -*Extension*: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_vertex_input_dynamic_state.html[`VK_EXT_vertex_input_dynamic_state`] +*Extension*: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_vertex_input_dynamic_state.html[`VK_EXT_vertex_input_dynamic_state`] Demonstrate how to use vertex input bindings and attribute descriptions dynamically, which can reduce the number of pipeline objects that are needed to be created. === xref:./{extension_samplespath}extended_dynamic_state2/README.adoc[Extended dynamic state 2] -*Extension*: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state2.html[`VK_EXT_extended_dynamic_state2`] +*Extension*: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state2.html[`VK_EXT_extended_dynamic_state2`] Demonstrate how to use depth bias, primitive restart, rasterizer discard and patch control points dynamically, which can reduce the number of pipeline objects that are needed to be created. === xref:./{extension_samplespath}logic_op_dynamic_state/README.adoc[Logic operations dynamic state] -*Extension*: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state2.html[`VK_EXT_extended_dynamic_state2`] +*Extension*: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state2.html[`VK_EXT_extended_dynamic_state2`] Demonstrate how to use logical operations dynamically, which can reduce the number of pipeline objects that are needed to be created or allow to change the pipeline state dynamically (change type of the logical operation). === xref:./{extension_samplespath}patch_control_points/README.adoc[Patch control points] -*Extension*: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state2.html[`VK_EXT_extended_dynamic_state2`] +*Extension*: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state2.html[`VK_EXT_extended_dynamic_state2`] Demonstrate how to use patch control points dynamically, which can reduce the number of pipeline objects that are needed to be created. === xref:./{extension_samplespath}fragment_shader_barycentric/README.adoc[Fragment shader barycentric] -*Extension*: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_fragment_shader_barycentric.html[`VK_KHR_fragment_shader_barycentric`] +*Extension*: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_fragment_shader_barycentric.html[`VK_KHR_fragment_shader_barycentric`] Demonstrate how to use fragment shader barycentric feature, which allows accessing barycentric coordinates for each processed fragment. === xref:./{extension_samplespath}descriptor_buffer_basic/README.adoc[Basic descriptor buffer] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_ext_descriptor_buffer[`VK_EXT_descriptor_buffer`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_ext_descriptor_buffer[`VK_EXT_descriptor_buffer`] Demonstrate how to use the new extension to replace descriptor sets with resource descriptor buffers === xref:./{extension_samplespath}color_write_enable/README.adoc[Color write enable] -*Extension*: https://https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_color_write_enable.html[`VK_EXT_color_write_enable`] +*Extension*: https://https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_color_write_enable.html[`VK_EXT_color_write_enable`] Demonstrate how to create multiple color blend attachments and then toggle them dynamically. === xref:./{extension_samplespath}gshader_to_mshader/README.adoc[Geometry shader to mesh shader] -*Extension:* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_mesh_shader.html[`VK_EXT_mesh_shader`] +*Extension:* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_mesh_shader.html[`VK_EXT_mesh_shader`] Demonstrates how a mesh shader can be used to achieve the same results as with geometry shader, it loads model from a file and visualizes its normals. === xref:./{extension_samplespath}shader_object/README.adoc[Shader object] -*Extension:* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_shader_object.html[`VK_EXT_shader_object`] +*Extension:* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_shader_object.html[`VK_EXT_shader_object`] Demonstrate how to use shader objects. === xref:./{extension_samplespath}dynamic_blending[Dynamic blending] -*Extension:* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state.html[`VK_EXT_extended_dynamic_state3`] +*Extension:* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state.html[`VK_EXT_extended_dynamic_state3`] Demonstrate how to use the blending related functions available in the VK_EXT_extended_dynamic_state3 extension. === xref:./{extension_samplespath}dynamic_line_rasterization/README.adoc[Dynamic line rasterization] -*Extensions:* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_line_rasterization.html[`VK_EXT_line_rasterization`], https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_extended_dynamic_state3`] +*Extensions:* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_line_rasterization.html[`VK_EXT_line_rasterization`], https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_extended_dynamic_state3`] Demonstrate methods for dynamically customizing the appearance of the rendered lines. === xref:./{extension_samplespath}shader_debugprintf/README.adoc[Shader Debug Printf] -*Extension*: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_shader_non_semantic_info.html[`VK_KHR_shader_non_semantic_info`] +*Extension*: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_shader_non_semantic_info.html[`VK_KHR_shader_non_semantic_info`] Demonstrates how to use https://en.wikipedia.org/wiki/Printf[Printf] statements in a shader to output per-invocation values. This can help find issues with shaders in combination with graphics debugging tools. === xref:./{extension_samplespath}dynamic_primitive_clipping/README.adoc[Dynamic depth clipping and primitive clipping] -*Extension:* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_extended_dynamic_state3`] +*Extension:* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_extended_dynamic_state3`] Rendering using primitive clipping and depth clipping configured by dynamic pipeline state. === xref:./{extension_samplespath}host_image_copy/README.adoc[Host image copies] -*Extension:* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_host_image_copy.html[`VK_EXT_extended_dynamic_state3`] +*Extension:* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_host_image_copy.html[`VK_EXT_extended_dynamic_state3`] Demonstrate the use of the host image extension to directly copy from a host buffer to an image on the device without going through a staging buffer. === xref:./{extension_samplespath}dynamic_multisample_rasterization/README.adoc[Dynamic multisample rasterization] -*Extensions:* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_line_rasterization`], https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_extended_dynamic_state3`] +*Extensions:* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_line_rasterization`], https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state3.html[`VK_EXT_extended_dynamic_state3`] Demonstrate how to use dynamic multisample rasterization (MSAA) === xref:./{extension_samplespath}tensor_and_data_graph/README.adoc[Tensor and Data Graph] -*Extensions*: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_ARM_tensors.html[`VK_ARM_tensors`], https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_ARM_data_graph.html[`VK_ARM_data_graph`] +*Extensions*: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_ARM_tensors.html[`VK_ARM_tensors`], https://registry.khronos.org/vulkan/specs/latest/man/html/VK_ARM_data_graph.html[`VK_ARM_data_graph`] Demonstrate how to build data graph pipelines and execute neural networks: diff --git a/samples/extensions/color_write_enable/README.adoc b/samples/extensions/color_write_enable/README.adoc index 25e461c69..e5011ad52 100644 --- a/samples/extensions/color_write_enable/README.adoc +++ b/samples/extensions/color_write_enable/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Mobica Limited +- Copyright (c) 2023-2025, Mobica Limited - - SPDX-License-Identifier: Apache-2.0 - @@ -58,12 +58,12 @@ The sample shows how to setup an application to work with this extension: == Documentation links -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_color_write_enable.html +https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_color_write_enable.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkSubpassDescription.html +https://registry.khronos.org/vulkan/specs/latest/man/html/VkSubpassDescription.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkFramebufferCreateInfo.html +https://registry.khronos.org/vulkan/specs/latest/man/html/VkFramebufferCreateInfo.html == See also -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetColorWriteMaskEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetColorWriteMaskEXT.html diff --git a/samples/extensions/conditional_rendering/README.adoc b/samples/extensions/conditional_rendering/README.adoc index 99a66332d..2a1305dec 100644 --- a/samples/extensions/conditional_rendering/README.adoc +++ b/samples/extensions/conditional_rendering/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2023, Sascha Willems +- Copyright (c) 2022-2025, Sascha Willems - - SPDX-License-Identifier: Apache-2.0 - @@ -28,7 +28,7 @@ image::./images/sample.png[Sample] == Overview -The https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_conditional_rendering.html[VK_EXT_conditional_rendering] extension allows the execution of rendering commands to be conditional based on a value taken from a dedicated conditional buffer. +The https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_conditional_rendering.html[VK_EXT_conditional_rendering] extension allows the execution of rendering commands to be conditional based on a value taken from a dedicated conditional buffer. This may help an application reduce the latency by conditionally discarding rendering commands without application intervention. This sample demonstrates usage of this extension for conditionally toggling the visibility of sub-meshes of a complex glTF model. diff --git a/samples/extensions/conservative_rasterization/README.adoc b/samples/extensions/conservative_rasterization/README.adoc index 6f12ef668..c31dd9a2d 100644 --- a/samples/extensions/conservative_rasterization/README.adoc +++ b/samples/extensions/conservative_rasterization/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, The Khronos Group +- Copyright (c) 2019-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_conservative_rasterization[`VK_EXT_conservative_rasterization`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_EXT_conservative_rasterization[`VK_EXT_conservative_rasterization`] Uses conservative rasterization to change the way fragments are generated. Enables overestimation to generate fragments for every pixel touched instead of only pixels that are fully covered. diff --git a/samples/extensions/debug_utils/README.adoc b/samples/extensions/debug_utils/README.adoc index 033881f39..c74b8f120 100644 --- a/samples/extensions/debug_utils/README.adoc +++ b/samples/extensions/debug_utils/README.adoc @@ -25,7 +25,7 @@ endif::[] == Overview -This tutorial, along with the accompanying example code, demonstrates the use of the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_debug_utils[VK_EXT_debug_utils] extension to setup a validation layer messenger callback and pass additional debugging information to debuggers like https://renderdoc.org/[RenderDoc]. +This tutorial, along with the accompanying example code, demonstrates the use of the https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_EXT_debug_utils[VK_EXT_debug_utils] extension to setup a validation layer messenger callback and pass additional debugging information to debuggers like https://renderdoc.org/[RenderDoc]. `VK_EXT_debug_utils` has been introduced based on feedback for the initial Vulkan debugging extensions `VK_EXT_debug_report` and `VK_EXT_debug_marker`, combining these into a single instance extensions with some added functionality. diff --git a/samples/extensions/descriptor_buffer_basic/README.adoc b/samples/extensions/descriptor_buffer_basic/README.adoc index 1fc6efea6..1491e682e 100644 --- a/samples/extensions/descriptor_buffer_basic/README.adoc +++ b/samples/extensions/descriptor_buffer_basic/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023-2024, Sascha Willems +- Copyright (c) 2023-2025, Sascha Willems - - SPDX-License-Identifier: Apache-2.0 - @@ -26,7 +26,7 @@ endif::[] == Overview Binding and managing descriptors in Vulkan can become pretty complex, both for the application and the driver. -With the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_ext_descriptor_buffer[`VK_EXT_descriptor_buffer`] extension, this interface is simplified and maps more directly to how hardware sees descriptors. +With the https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_ext_descriptor_buffer[`VK_EXT_descriptor_buffer`] extension, this interface is simplified and maps more directly to how hardware sees descriptors. It also simplifies the programming model, as you no longer have to create descriptor pool upfront. This sample shows how to use that extension by rendering multiple objects with different uniform buffers and images using the new interface of creating and binding descriptors. diff --git a/samples/extensions/dynamic_blending/README.adoc b/samples/extensions/dynamic_blending/README.adoc index f58d645cc..aed5ac491 100644 --- a/samples/extensions/dynamic_blending/README.adoc +++ b/samples/extensions/dynamic_blending/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Mobica Limited +- Copyright (c) 2023-2025, Mobica Limited - - SPDX-License-Identifier: Apache-2.0 - @@ -58,10 +58,10 @@ The sample demonstrates how the use of each operator affects color blending. == Documentation links -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetColorBlendEnableEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetColorBlendEnableEXT.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetColorBlendEquationEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetColorBlendEquationEXT.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetColorBlendAdvancedEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetColorBlendAdvancedEXT.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetColorWriteMaskEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetColorWriteMaskEXT.html diff --git a/samples/extensions/dynamic_line_rasterization/README.adoc b/samples/extensions/dynamic_line_rasterization/README.adoc index f913604c7..0a3469ebb 100644 --- a/samples/extensions/dynamic_line_rasterization/README.adoc +++ b/samples/extensions/dynamic_line_rasterization/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023-2024, Mobica Limited +- Copyright (c) 2023-2025, Mobica Limited - - SPDX-License-Identifier: Apache-2.0 - @@ -57,12 +57,12 @@ The infinite grid shader is based on the code from the https://asliceofrendering == Documentation links -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetLineStippleEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetLineStippleEXT.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetPolygonModeEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetPolygonModeEXT.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetLineRasterizationModeEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetLineRasterizationModeEXT.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetLineStippleEnableEXT.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetLineStippleEnableEXT.html -https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetLineWidth.html +https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetLineWidth.html diff --git a/samples/extensions/extended_dynamic_state2/README.adoc b/samples/extensions/extended_dynamic_state2/README.adoc index 9843e5a6b..143afaee1 100644 --- a/samples/extensions/extended_dynamic_state2/README.adoc +++ b/samples/extensions/extended_dynamic_state2/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Mobica Limited +- Copyright (c) 2023-2025, Mobica Limited - - SPDX-License-Identifier: Apache-2.0 - @@ -260,7 +260,7 @@ void ExtendedDynamicState2::draw_from_scene(VkCommandBuffer command_buffer, std: == Enabling the Extension The extended dynamic state 2 api requires Vulkan 1.0 and the appropriate headers / SDK is required. -This extension has been https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state2.html#_promotion_to_vulkan_1_3[partially] promoted to Vulkan 1.3. +This extension has been https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state2.html#_promotion_to_vulkan_1_3[partially] promoted to Vulkan 1.3. The device extension is provided by `VK_EXT_EXTENDED_DYNAMIC_STATE_2_EXTENSION_NAME`. It also requires `VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME` instance extension to be enabled. @@ -271,6 +271,6 @@ add_instance_extension(VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME); add_device_extension(VK_EXT_EXTENDED_DYNAMIC_STATE_2_EXTENSION_NAME); ---- -If the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPhysicalDeviceExtendedDynamicState2FeaturesEXT.html[`VkPhysicalDeviceExtendedDynamicState2FeaturesEXT`] structure is included in the pNext chain of the `VkPhysicalDeviceFeatures2` structure passed to vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. +If the https://registry.khronos.org/vulkan/specs/latest/man/html/VkPhysicalDeviceExtendedDynamicState2FeaturesEXT.html[`VkPhysicalDeviceExtendedDynamicState2FeaturesEXT`] structure is included in the pNext chain of the `VkPhysicalDeviceFeatures2` structure passed to vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. `VkPhysicalDeviceExtendedDynamicState2FeaturesEXT` can also be used in the pNext chain of `VkDeviceCreateInfo` to selectively enable these features. o selectively enable these features. diff --git a/samples/extensions/fragment_shader_barycentric/README.adoc b/samples/extensions/fragment_shader_barycentric/README.adoc index d6f79f952..ac5d3df9f 100644 --- a/samples/extensions/fragment_shader_barycentric/README.adoc +++ b/samples/extensions/fragment_shader_barycentric/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Mobica Limited +- Copyright (c) 2023-2025, Mobica Limited - - SPDX-License-Identifier: Apache-2.0 - @@ -29,7 +29,7 @@ Fragment shader barycentric feature provides support for accessing the barycentr == Overview -The https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_fragment_shader_barycentric.html[VK_KHR_fragment_shader_barycentric] extension is based on https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_NV_fragment_shader_barycentric.html[VK_NV_fragment_shader_barycentric]. +The https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_fragment_shader_barycentric.html[VK_KHR_fragment_shader_barycentric] extension is based on https://registry.khronos.org/vulkan/specs/latest/man/html/VK_NV_fragment_shader_barycentric.html[VK_NV_fragment_shader_barycentric]. The extension provides access to additional built-in variables and decorations: @@ -50,7 +50,7 @@ The extension provides access to additional built-in variables and decorations: |=== The built-in fragment shader input variables `gl_BaryCoordEXT` and `gl_BaryCoordNoPerspEXT` are three-component floating-point vectors that provide the barycentric coordinates for the fragment. -The values for these built-ins are derived as described in https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#interfaces-builtin-variables[the Vulkan API Specifications]. +The values for these built-ins are derived as described in https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables[the Vulkan API Specifications]. The built-in variables hold barycentric weights for the fragment produced using: * perspective interpolation: `gl_BaryCoordEXT` @@ -64,8 +64,8 @@ layout(location = 0) pervertexEXT in vec4 perVertexAttr[]; ---- Each array element corresponds to one of the vertices of the primitive that produced the fragment. -The order of the vertices is defined in https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#primsrast-barycentric[the Vulkan API Specifications]. -Interpolated values are not available for inputs declared with the https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#shaders-interpolation-decorations-pervertexkhr[`pervertexEXT`]. +The order of the vertices is defined in https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#primsrast-barycentric[the Vulkan API Specifications]. +Interpolated values are not available for inputs declared with the https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#shaders-interpolation-decorations-pervertexkhr[`pervertexEXT`]. The fragment shader barycentric sample demonstrates feature usage by applying different effects on a cube. The effects are implemented using the `pervertexEXT` decoration and built-in variables `gl_BaryCoordEXT` and `gl_BaryCoordNoPerspEXT`. @@ -80,8 +80,8 @@ The following effects are available from the GUI: == Enabling the Extension -Enabling the fragment shader barycentric feature is done using the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR.html[`VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR`] structure, where `fragmentShaderBarycentric` indicates barycentric support in fragment shaders. -The structure should be passed to `vkGetPhysicalDeviceFeatures2` in the pNext member of the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPhysicalDeviceFeatures2.html[`VkPhysicalDeviceFeatures2`] structure. +Enabling the fragment shader barycentric feature is done using the https://registry.khronos.org/vulkan/specs/latest/man/html/VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR.html[`VkPhysicalDeviceFragmentShaderBarycentricFeaturesKHR`] structure, where `fragmentShaderBarycentric` indicates barycentric support in fragment shaders. +The structure should be passed to `vkGetPhysicalDeviceFeatures2` in the pNext member of the https://registry.khronos.org/vulkan/specs/latest/man/html/VkPhysicalDeviceFeatures2.html[`VkPhysicalDeviceFeatures2`] structure. [,C++] ---- diff --git a/samples/extensions/fragment_shading_rate/README.adoc b/samples/extensions/fragment_shading_rate/README.adoc index fa6f0c96e..beb99a1cc 100644 --- a/samples/extensions/fragment_shading_rate/README.adoc +++ b/samples/extensions/fragment_shading_rate/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, The Khronos Group +- Copyright (c) 2019-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] Uses a special framebuffer attachment to control fragment shading rates for different framebuffer regions. This allows explicit control over the number of fragment shader invocations for each pixel covered by a fragment, which is e.g. diff --git a/samples/extensions/fragment_shading_rate_dynamic/README.adoc b/samples/extensions/fragment_shading_rate_dynamic/README.adoc index bd78bbc7d..575879279 100644 --- a/samples/extensions/fragment_shading_rate_dynamic/README.adoc +++ b/samples/extensions/fragment_shading_rate_dynamic/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2023, Holochip +- Copyright (c) 2022-2025, Holochip - - SPDX-License-Identifier: Apache-2.0 - @@ -28,8 +28,8 @@ The KHR fragment shading rate extension introduces the ability to selectively re This can be useful when rendering at very high resolutions or when the frequency content is not evenly spread through the rendered image. This tutorial demonstrates one way of controlling that sample rate by estimating the frequency content of each pixel of the rendered image. -The fragment shading rate extension can be enabled through the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] device extension and the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VkPhysicalDeviceFragmentShadingRateFeaturesKHR.html[`VkPhysicalDeviceFragmentShadingRateFeaturesKHR`] device features. -This sample demonstrates the attachment capability, in which the render pass directly references the shading rate image through a https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VkFragmentShadingRateAttachmentInfoKHR.html[`VkFragmentShadingRateAttachmentInfoKHR`] struct attached to the `.pNext` of a sub-pass. +The fragment shading rate extension can be enabled through the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_fragment_shading_rate.html[`VK_KHR_fragment_shading_rate`] device extension and the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkPhysicalDeviceFragmentShadingRateFeaturesKHR.html[`VkPhysicalDeviceFragmentShadingRateFeaturesKHR`] device features. +This sample demonstrates the attachment capability, in which the render pass directly references the shading rate image through a https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkFragmentShadingRateAttachmentInfoKHR.html[`VkFragmentShadingRateAttachmentInfoKHR`] struct attached to the `.pNext` of a sub-pass. The image below shows the scene from this sample. Note the areas of high image variation in the center of each cube face, and the areas of low image variation in the sky and plain corners of each cube face. @@ -40,7 +40,7 @@ image::./rendered.png[Rendered image] When used as an attachment, each pixel within the shading rate image controls a "texel", or fixed region within the output image, specified by `shadingRateAttachmentTexelSize`. For example, each pixel in the shading rate image might control the shading rate of a 4x4 texel within the rendered image, since all output pixels of the texel are shaded at the same rate, the shading rate image has a lower resolution. -The number and type of possible shading rates is controlled by the device and can be queried through the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkGetPhysicalDeviceFragmentShadingRatesKHR.html[`vkGetPhysicalDeviceFragmentShadingRatesKHR`] function, and may include shading rates that vary in both the x- and y-directions, for instance 1x2 or 4x2 pixel texels. +The number and type of possible shading rates is controlled by the device and can be queried through the https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceFragmentShadingRatesKHR.html[`vkGetPhysicalDeviceFragmentShadingRatesKHR`] function, and may include shading rates that vary in both the x- and y-directions, for instance 1x2 or 4x2 pixel texels. These supported shading rate values are provided to the "compute shader" when determining the optimal shading rate. This sample demonstrates how to use a dynamic shading rate that responds to the frequency content of the image. diff --git a/samples/extensions/graphics_pipeline_library/README.adoc b/samples/extensions/graphics_pipeline_library/README.adoc index 7ee9bb20f..6f6d0d3b1 100644 --- a/samples/extensions/graphics_pipeline_library/README.adoc +++ b/samples/extensions/graphics_pipeline_library/README.adoc @@ -26,7 +26,7 @@ endif::[] == Overview -The https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_EXT_graphics_pipeline_library.html[`VK_EXT_graphics_pipeline_library`] extensions allows separate compilation of different parts of the graphics pipeline. +The https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_graphics_pipeline_library.html[`VK_EXT_graphics_pipeline_library`] extensions allows separate compilation of different parts of the graphics pipeline. With this it's now possible to split up the monolithic pipeline creation into different steps and re-use common parts shared across different pipelines. Compared to monolithic pipeline state, this results in faster pipeline creation times, making this extension a good fit for applications and games that do a lot of pipeline creation at runtime. @@ -35,10 +35,10 @@ Compared to monolithic pipeline state, this results in faster pipeline creation As noted above, the monolithic pipeline state has been split into distinct parts that can be compiled independently: -* https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#pipeline-graphics-subsets-vertex-input[Vertex Input Interface] -* https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#pipeline-graphics-subsets-pre-rasterization[Pre-Rasterization Shaders] -* https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#pipeline-graphics-subsets-fragment-shader[Fragment Shader] -* https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#pipeline-graphics-subsets-fragment-output[Fragment Output Interface] +* https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#pipeline-graphics-subsets-vertex-input[Vertex Input Interface] +* https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#pipeline-graphics-subsets-pre-rasterization[Pre-Rasterization Shaders] +* https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#pipeline-graphics-subsets-fragment-shader[Fragment Shader] +* https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#pipeline-graphics-subsets-fragment-output[Fragment Output Interface] == Creating pipeline libraries diff --git a/samples/extensions/host_image_copy/README.adoc b/samples/extensions/host_image_copy/README.adoc index 6cdd049a2..65b52e46e 100644 --- a/samples/extensions/host_image_copy/README.adoc +++ b/samples/extensions/host_image_copy/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2024, Sascha Willems +- Copyright (c) 2024-2025, Sascha Willems - - SPDX-License-Identifier: Apache-2.0 - @@ -38,7 +38,7 @@ NOTE: A staged upload usually has to first perform a CPU copy of data to a GPU-v == Enabling the Extension -The `VK_EXT_host_image_copy` extension needs to be enabled at device level. Depending on the Vulkan version you target, additional extensions might need to be enabled. See the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_host_image_copy.html#_extension_and_version_dependencies[extension and version dependencies] of the extension spec for details. +The `VK_EXT_host_image_copy` extension needs to be enabled at device level. Depending on the Vulkan version you target, additional extensions might need to be enabled. See the https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_host_image_copy.html#_extension_and_version_dependencies[extension and version dependencies] of the extension spec for details. In addition to the extension(s) you also need to enable the `hostImageCopy` for the extension structure: @@ -165,5 +165,5 @@ Aside from the use-case shown in this sample, the `VK_EXT_host_image_copy` exten * https://www.khronos.org/blog/copying-images-on-the-host-in-vulkan[Copying Images on the Host in Vulkan] * https://docs.vulkan.org/features/latest/features/proposals/VK_EXT_host_image_copy.html[Extension proposal] -* https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_host_image_copy.html[Specification] +* https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_host_image_copy.html[Specification] * https://vulkan.gpuinfo.org/displayextensiondetail?extension=VK_EXT_host_image_copy[Extension device support] diff --git a/samples/extensions/hpp_push_descriptors/README.adoc b/samples/extensions/hpp_push_descriptors/README.adoc index eead6ceed..3bc47e4ec 100644 --- a/samples/extensions/hpp_push_descriptors/README.adoc +++ b/samples/extensions/hpp_push_descriptors/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2020-2024, Arm Limited and Contributors +- Copyright (c) 2020-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] Push descriptors apply the push constants concept to descriptor sets. Instead of creating per-object descriptor sets, this example passes descriptors at command buffer creation time. diff --git a/samples/extensions/logic_op_dynamic_state/README.adoc b/samples/extensions/logic_op_dynamic_state/README.adoc index ae963c06d..d66ed5787 100644 --- a/samples/extensions/logic_op_dynamic_state/README.adoc +++ b/samples/extensions/logic_op_dynamic_state/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Mobica Limited +- Copyright (c) 2023-2025, Mobica Limited - - SPDX-License-Identifier: Apache-2.0 - @@ -27,7 +27,7 @@ image::./images/logic_op_dynamic_state_screenshot.png[Sample] == Overview -The https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state2.html[VK_EXT_extended_dynamic_state2] extension allows to use dynamic states e.g. +The https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state2.html[VK_EXT_extended_dynamic_state2] extension allows to use dynamic states e.g. the VK_DYNAMIC_STATE_LOGIC_OP_EXT. This may help an application to change a logical operation used without creating a new pipeline. @@ -35,7 +35,7 @@ The sample demonstrates usage of this extension with dynamically changed logical == Surface format setting -Logical operations are applied only for https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#framebuffer-logicop[signed and unsigned integer and normalized integer framebuffers]. +Logical operations are applied only for https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#framebuffer-logicop[signed and unsigned integer and normalized integer framebuffers]. In the sample the surface format is changed to `VK_FORMAT_B8G8R8A8_UNORM` by overriding the virtual method `create_render_context` (derived from `ApiVulkanSample` class). @@ -56,7 +56,7 @@ In the sample two pipelines are created: The cube model is used to present blending effect achieved using the dynamic logical operations. -The `logicOpEnable` member of the `VkPipelineColorBlendStateCreateInfo` structure https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPipelineColorBlendStateCreateInfo.html[controls if logical operations should be applied]. +The `logicOpEnable` member of the `VkPipelineColorBlendStateCreateInfo` structure https://registry.khronos.org/vulkan/specs/latest/man/html/VkPipelineColorBlendStateCreateInfo.html[controls if logical operations should be applied]. The `logicOpEnable` member is set to `VK_TRUE` during creation of the baseline pipeline in the `create_pipeline` method. @@ -69,7 +69,7 @@ VkPipelineColorBlendStateCreateInfo color_blend_state = color_blend_state.logicOpEnable = VK_TRUE; ---- -In the same method `VK_DYNAMIC_STATE_LOGIC_OP_EXT` is added to the vector of `VkDynamicState` (used to define pipeline dynamic state in https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPipelineDynamicStateCreateInfo.html[`VkPipelineDynamicStateCreateInfo`]). +In the same method `VK_DYNAMIC_STATE_LOGIC_OP_EXT` is added to the vector of `VkDynamicState` (used to define pipeline dynamic state in https://registry.khronos.org/vulkan/specs/latest/man/html/VkPipelineDynamicStateCreateInfo.html[`VkPipelineDynamicStateCreateInfo`]). [,C++] ---- @@ -85,7 +85,7 @@ VkPipelineDynamicStateCreateInfo dynamic_state = 0); ---- -Both structures: `color_blend_state` and `dynamic_state` are used to define https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkGraphicsPipelineCreateInfo.html[`VkGraphicsPipelineCreateInfo`] needed to create the graphics pipeline. +Both structures: `color_blend_state` and `dynamic_state` are used to define https://registry.khronos.org/vulkan/specs/latest/man/html/VkGraphicsPipelineCreateInfo.html[`VkGraphicsPipelineCreateInfo`] needed to create the graphics pipeline. [,C++] ---- @@ -112,9 +112,9 @@ color_blend_state.logicOpEnable = VK_FALSE; == Logical operation dynamic setting in command buffer creation -Calling https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdSetLogicOpEXT.html[`vkCmdSetLogicOpEXT`] allows to set the logic operation dynamically. +Calling https://registry.khronos.org/vulkan/specs/latest/man/html/vkCmdSetLogicOpEXT.html[`vkCmdSetLogicOpEXT`] allows to set the logic operation dynamically. In the sample it is called before drawing the model in the `build_command_buffers` method using a value provided by the GUI. -Available logical operations are defined by the `VkLogicOp` enumeration (check the Vulkan specification for details of https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#VkLogicOp[the logical operations]). +Available logical operations are defined by the `VkLogicOp` enumeration (check the Vulkan specification for details of https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#VkLogicOp[the logical operations]). The background model is drawn before the cube model (with logical operations enabled) to observe blending results on the cube model. [,C++] @@ -139,7 +139,7 @@ VK_CHECK(vkEndCommandBuffer(draw_cmd_buffer)); == Enabling the required extensions The extended dynamic state 2 API requires Vulkan 1.0 and the appropriate headers / SDK is required. -This extension has been https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state2.html#_promotion_to_vulkan_1_3[partially] promoted to Vulkan 1.3. +This extension has been https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state2.html#_promotion_to_vulkan_1_3[partially] promoted to Vulkan 1.3. The device extension `VK_EXT_EXTENDED_DYNAMIC_STATE_2_EXTENSION_NAME` requires `VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME` instance extension to be enabled. diff --git a/samples/extensions/mesh_shader_culling/README.adoc b/samples/extensions/mesh_shader_culling/README.adoc index 46f8ca125..0456ca8d8 100644 --- a/samples/extensions/mesh_shader_culling/README.adoc +++ b/samples/extensions/mesh_shader_culling/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Holochip Corporation +- Copyright (c) 2025, Holochip Corporation - - SPDX-License-Identifier: Apache-2.0 - @@ -27,7 +27,7 @@ image::./images/mesh_shader_culling.png[Mesh Shader Culling] == Overview -This sample demonstrates how to incorporate the Vulkan extension https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_EXT_mesh_shader[`VK_EXT_mesh_shader`], and introduces per primitive culling in a mesh shader. +This sample demonstrates how to incorporate the Vulkan extension https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_EXT_mesh_shader[`VK_EXT_mesh_shader`], and introduces per primitive culling in a mesh shader. == Contents diff --git a/samples/extensions/open_cl_interop/README.adoc b/samples/extensions/open_cl_interop/README.adoc index fc774f103..6671f6143 100644 --- a/samples/extensions/open_cl_interop/README.adoc +++ b/samples/extensions/open_cl_interop/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023-2024, Sascha Willems +- Copyright (c) 2023-2025, Sascha Willems - - SPDX-License-Identifier: Apache-2.0 - @@ -38,15 +38,15 @@ To fully understand how this sample works it's advised to have experience with b Both Vulkan and OpenCL offer extensions for so called external objects. An external object is something that can be referenced in multiple apis. In this sample we share images and semaphores, so we need to enable related extensions on both apis. -For *sharing the memory* backing up the image, in *Vulkan* we need to enable https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory_capabilities.html[`VK_KHR_external_memory_capabilities`] at instance level and https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`] at device level. We also need to enable specific extensions based on the platform we're running on. For Windows that's https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory_win32.html[`VK_KHR_external_memory_win32`] and for all Unix based platforms we need to enable https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory_fd.html[`VK_KHR_external_memory_fd`]. The OpenCl equivalents to these extensions are https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_external_memory[`cl_khr_external_memory`], `cl_khr_external_memory_win32` (Windows) and `cl_khr_external_memory_opaque_fd` (Unix based platforms). +For *sharing the memory* backing up the image, in *Vulkan* we need to enable https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_memory_capabilities.html[`VK_KHR_external_memory_capabilities`] at instance level and https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`] at device level. We also need to enable specific extensions based on the platform we're running on. For Windows that's https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_memory_win32.html[`VK_KHR_external_memory_win32`] and for all Unix based platforms we need to enable https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_memory_fd.html[`VK_KHR_external_memory_fd`]. The OpenCl equivalents to these extensions are https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_external_memory[`cl_khr_external_memory`], `cl_khr_external_memory_win32` (Windows) and `cl_khr_external_memory_opaque_fd` (Unix based platforms). -For *sharing the semaphores* used to sync image access between the apis, in *Vulkan* we need to enable https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_semaphore_capabilities.html[`VK_KHR_external_semaphore_capabilities`] at the instance level and https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] at the device level. The platform specific extension to enable are https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_semaphore_win32.html[`VK_KHR_external_semaphore_win32`] for Windows and https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_semaphore_fd.html[`VK_KHR_external_semaphore_fd`] for Unix based platforms. The *OpenCL equivalents* to these are https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_external_semaphore[`cl_khr_external_semaphore`], `cl_khr_external_semaphore_win32` (Windows) and `cl_khr_external_semaphore_opaque_fd` (Unix based platforms). +For *sharing the semaphores* used to sync image access between the apis, in *Vulkan* we need to enable https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_semaphore_capabilities.html[`VK_KHR_external_semaphore_capabilities`] at the instance level and https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] at the device level. The platform specific extension to enable are https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_semaphore_win32.html[`VK_KHR_external_semaphore_win32`] for Windows and https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_semaphore_fd.html[`VK_KHR_external_semaphore_fd`] for Unix based platforms. The *OpenCL equivalents* to these are https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_external_semaphore[`cl_khr_external_semaphore`], `cl_khr_external_semaphore_win32` (Windows) and `cl_khr_external_semaphore_opaque_fd` (Unix based platforms). -We also need to match devices between Vulkan and OpenCL. In Vulkan this functionality is provided e.g. by the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory_capabilities.html[`VK_KHR_external_memory_capabilities`] extension, in OpenCL this requires the `cl_khr_device_uuid`. More on this later. +We also need to match devices between Vulkan and OpenCL. In Vulkan this functionality is provided e.g. by the https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_memory_capabilities.html[`VK_KHR_external_memory_capabilities`] extension, in OpenCL this requires the `cl_khr_device_uuid`. More on this later. == Matching devices -For the type of external objects we are going to share between Vulkan and OpenCL in this sample, we must make sure that we use the same device in Vulkan and OpenCL. See https://registry.khronos.org/vulkan/specs/1.3-extensions/html/chap49.html#capabilities-image[this chapter of the spec] as to why this is required and to what types of external objects this applies. Esp. on desktop systems you may have multiple Vulkan and/or OpenCL implementations, and they may be reported by both apis in different orders. So just assuming that the first Vulkan device is also the first OpenCL device may not work. +For the type of external objects we are going to share between Vulkan and OpenCL in this sample, we must make sure that we use the same device in Vulkan and OpenCL. See https://registry.khronos.org/vulkan/specs/latest/html/chap49.html#capabilities-image[this chapter of the spec] as to why this is required and to what types of external objects this applies. Esp. on desktop systems you may have multiple Vulkan and/or OpenCL implementations, and they may be reported by both apis in different orders. So just assuming that the first Vulkan device is also the first OpenCL device may not work. For that, both apis expose universally unique (device) identifiers (uuid) that we can use to match the devices between the apis. This is done in the `prepare_opencl_resources` function. Since this is a Vulkan sample we'll try to find the OpenCL device that matches the UUID of our Vulkan sample: @@ -114,7 +114,7 @@ for (auto &platform_id : platform_ids) == A note on Windows security -On Windows we need to ensure read and write access to the shared memory for external handles (see https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkExportMemoryWin32HandleInfoKHR.html#_description[spec]). This requires setting up security attributes using the Windows API. To simplify this, the sample implements that in the `WinSecurityAttributes` class. This is then used in all places where we share memory on Windows. +On Windows we need to ensure read and write access to the shared memory for external handles (see https://registry.khronos.org/vulkan/specs/latest/man/html/VkExportMemoryWin32HandleInfoKHR.html#_description[spec]). This requires setting up security attributes using the Windows API. To simplify this, the sample implements that in the `WinSecurityAttributes` class. This is then used in all places where we share memory on Windows. == Creating and sharing the image diff --git a/samples/extensions/open_cl_interop_arm/README.adoc b/samples/extensions/open_cl_interop_arm/README.adoc index 1e2f2e025..7c651731e 100644 --- a/samples/extensions/open_cl_interop_arm/README.adoc +++ b/samples/extensions/open_cl_interop_arm/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2021-2023, Arm Limited and Contributors +- Copyright (c) 2021-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -51,7 +51,7 @@ image::./images/shared_hardware_buffer.png[Sample] === Support by Vulkan API -In Vulkan hardware buffers can be imported or exported using https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html[VK_ANDROID_external_memory_android_hardware_buffer] extension. +In Vulkan hardware buffers can be imported or exported using https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html[VK_ANDROID_external_memory_android_hardware_buffer] extension. AHardwareBuffer can be bound to a `VkDeviceMemory` object, which serves as an allocation for objects of type `VkImage` or `VkBuffer`. If we need to use an image backed by an AHardwareBuffer, we must specify while creating the image. @@ -87,7 +87,7 @@ export_memory_allocate_Info.handleTypes = VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID ---- This is specified as `pNext` of `VkMemoryAllocateInfo`, while `allocationSize` is set to 0. -You can find more info on this in the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VkMemoryRequirements[specification]. +You can find more info on this in the https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VkMemoryRequirements[specification]. Once the memory is allocated *and* bound to the image (or buffer), we can export a handle of type `AHardwareBuffer`: @@ -178,5 +178,5 @@ In this sample one of such handle types is demonstrated: Android Hardware Buffer The extensions used in this case are: -* https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html[VK_ANDROID_external_memory_android_hardware_buffer] +* https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html[VK_ANDROID_external_memory_android_hardware_buffer] * https://www.khronos.org/registry/OpenCL/extensions/arm/cl_arm_import_memory.txt[cl_arm_import_memory] diff --git a/samples/extensions/open_gl_interop/README.adoc b/samples/extensions/open_gl_interop/README.adoc index c5f09535c..9820478cc 100644 --- a/samples/extensions/open_gl_interop/README.adoc +++ b/samples/extensions/open_gl_interop/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2020-2023, The Khronos Group +- Copyright (c) 2020-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_external_memory.html[`VK_KHR_external_memory`], https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_external_semaphore.html[`VK_KHR_external_semaphore`] Render a procedural image using OpenGL and incorporate that rendered content into a Vulkan scene. Demonstrates using the same backing memory for a texture in both OpenGL and Vulkan and how to synchronize the APIs using shared semaphores and barriers. diff --git a/samples/extensions/patch_control_points/README.adoc b/samples/extensions/patch_control_points/README.adoc index a2d9ce99b..7eb0d2a51 100644 --- a/samples/extensions/patch_control_points/README.adoc +++ b/samples/extensions/patch_control_points/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Mobica Limited +- Copyright (c) 2023-2025, Mobica Limited - - SPDX-License-Identifier: Apache-2.0 - @@ -155,7 +155,7 @@ VK_CHECK(vkEndCommandBuffer(draw_cmd_buffer)); == Enabling the Extension The extended dynamic state 2 API requires Vulkan 1.0 and the appropriate headers / SDK is required. -This extension has been https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_extended_dynamic_state2.html#_promotion_to_vulkan_1_3[partially] promoted to Vulkan 1.3. +This extension has been https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_extended_dynamic_state2.html#_promotion_to_vulkan_1_3[partially] promoted to Vulkan 1.3. The device extension is provided by `VK_EXT_EXTENDED_DYNAMIC_STATE_2_EXTENSION_NAME`. It also requires `VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME` instance extension to be enabled. @@ -166,5 +166,5 @@ add_instance_extension(VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME); add_device_extension(VK_EXT_EXTENDED_DYNAMIC_STATE_2_EXTENSION_NAME); ---- -If the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPhysicalDeviceExtendedDynamicState2FeaturesEXT.html[`VkPhysicalDeviceExtendedDynamicState2FeaturesEXT`] structure is included in the pNext chain of the `VkPhysicalDeviceFeatures2` structure passed to vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. +If the https://registry.khronos.org/vulkan/specs/latest/man/html/VkPhysicalDeviceExtendedDynamicState2FeaturesEXT.html[`VkPhysicalDeviceExtendedDynamicState2FeaturesEXT`] structure is included in the pNext chain of the `VkPhysicalDeviceFeatures2` structure passed to vkGetPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. `VkPhysicalDeviceExtendedDynamicState2FeaturesEXT` can also be used in the pNext chain of `VkDeviceCreateInfo` to selectively enable these features. diff --git a/samples/extensions/portability/README.adoc b/samples/extensions/portability/README.adoc index eea6f080b..9649374c6 100644 --- a/samples/extensions/portability/README.adoc +++ b/samples/extensions/portability/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2023, Holochip +- Copyright (c) 2022-2025, Holochip - - SPDX-License-Identifier: Apache-2.0 - @@ -25,11 +25,11 @@ endif::[] == Overview -This tutorial, along with the accompanying example code, demonstrates the use of the https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#VK_KHR_portability_subset[VK_KHR_portability_subset] extension. +This tutorial, along with the accompanying example code, demonstrates the use of the https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_portability_subset[VK_KHR_portability_subset] extension. When the VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR is set in the `Instance` class, Vulkan will consider devices that aren't fully conformant such as https://github.com/KhronosGroup/MoltenVK[MoltenVk] to be identified as a conformant implementation. -When this happens, use the VkPhysicalDevicePortabilitySubsetPropertiesKHR extension with the https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkGetPhysicalDeviceFeatures2[vkGetPhysicalDeviceFeatures2] as detailed below to get the list of supported/unsupported features. +When this happens, use the VkPhysicalDevicePortabilitySubsetPropertiesKHR extension with the https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#vkGetPhysicalDeviceFeatures2[vkGetPhysicalDeviceFeatures2] as detailed below to get the list of supported/unsupported features. -This tutorial along with the accompanying code also demonstrates the use of the https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#VkPhysicalDevicePortabilitySubsetPropertiesKHR[VkPhysicalDevicePortabilitySubsetPropertiesKHR] which is currently a beta khronos extension. +This tutorial along with the accompanying code also demonstrates the use of the https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VkPhysicalDevicePortabilitySubsetPropertiesKHR[VkPhysicalDevicePortabilitySubsetPropertiesKHR] which is currently a beta khronos extension. This extension provides a list of supported and unsupported parts of Vulkan on a non-conformant Vulkan instance. Build with VK_ENABLE_BETA_EXTENSIONS set to enable this. diff --git a/samples/extensions/push_descriptors/README.adoc b/samples/extensions/push_descriptors/README.adoc index b7610817d..428ed51ce 100644 --- a/samples/extensions/push_descriptors/README.adoc +++ b/samples/extensions/push_descriptors/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2020-2023, Arm Limited and Contributors +- Copyright (c) 2020-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extension*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] +*Extension*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_push_descriptor[`VK_KHR_push_descriptor`] Push descriptors apply the push constants concept to descriptor sets. Instead of creating per-object descriptor sets, this example passes descriptors at command buffer creation time. diff --git a/samples/extensions/ray_queries/README.adoc b/samples/extensions/ray_queries/README.adoc index 8dfaca36a..05346324d 100644 --- a/samples/extensions/ray_queries/README.adoc +++ b/samples/extensions/ray_queries/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2020-2023, The Khronos Group +- Copyright (c) 2020-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_ray_query[`VK_KHR_ray_query`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_ray_query[`VK_KHR_ray_query`], https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] Render a sponza scene using the ray query extension. Shows how to set up all data structures required for ray queries, including the bottom and top level acceleration structures for the geometry and a standard vertex/fragment shader pipeline. diff --git a/samples/extensions/ray_tracing_basic/README.adoc b/samples/extensions/ray_tracing_basic/README.adoc index dafd39613..27d570f31 100644 --- a/samples/extensions/ray_tracing_basic/README.adoc +++ b/samples/extensions/ray_tracing_basic/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2020-2023, The Khronos Group +- Copyright (c) 2020-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extensions*: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] +*Extensions*: https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_ray_tracing_pipeline[`VK_KHR_ray_tracing_pipeline`], https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_acceleration_structure[`VK_KHR_acceleration_structure`] Render a basic scene using the official cross-vendor ray tracing extension. Shows how to setup all data structures required for ray tracing, including the bottom and top level acceleration structures for the geometry, the shader binding table and the ray tracing pipelines with shader groups for ray generation, ray hits, and ray misses. diff --git a/samples/extensions/shader_debugprintf/README.adoc b/samples/extensions/shader_debugprintf/README.adoc index 424f8e6b8..d11409760 100644 --- a/samples/extensions/shader_debugprintf/README.adoc +++ b/samples/extensions/shader_debugprintf/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2024, Sascha Willems +- Copyright (c) 2024-2025, Sascha Willems - - SPDX-License-Identifier: Apache-2.0 - @@ -28,7 +28,7 @@ image::./images/sample.png[Sample] == Overview -This sample demonstrates the usage of the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_shader_non_semantic_info.html[VK_KHR_shader_non_semantic_info] for adding means to output debug messages from SPIR-V shaders using a print function at runtime. +This sample demonstrates the usage of the https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_shader_non_semantic_info.html[VK_KHR_shader_non_semantic_info] for adding means to output debug messages from SPIR-V shaders using a print function at runtime. It allows you to output invocation related debug messages from a given shader stage and can help to find problems or bugs together with a graphics debugger like https://www.renderdoc.org[RenderDoc]. But it's also possible to display that data in your application (e.g. a debug window or the command line), although this has some limitations like a fixed buffer size that all messages need to fit in. diff --git a/samples/extensions/shader_object/README.adoc b/samples/extensions/shader_object/README.adoc index 680221461..7a9c3c7d6 100644 --- a/samples/extensions/shader_object/README.adoc +++ b/samples/extensions/shader_object/README.adoc @@ -353,7 +353,7 @@ This sample does not enable the `tessellationShader` device feature, so it's not == State Setting and Drawing -The https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#shaders-objects-state[Setting State] subsection of the https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#shaders-objects[Shader Objects] section of the Vulkan specification lists the graphics state that needs to be set on a command buffer before `vkCmdDraw*` can be called with graphics shader objects bound. +The https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#shaders-objects-state[Setting State] subsection of the https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#shaders-objects[Shader Objects] section of the Vulkan specification lists the graphics state that needs to be set on a command buffer before `vkCmdDraw*` can be called with graphics shader objects bound. This sample demonstrates one possible way to take advantage of these rules to minimize calls into the Vulkan driver. @@ -455,7 +455,7 @@ Because of this the layer's files will always need to be somewhere accessible to * https://www.khronos.org/blog/you-can-use-vulkan-without-pipelines-today[You Can Use Vulkan Without Pipelines Today] * https://docs.vulkan.org/features/latest/features/proposals/VK_EXT_shader_object.html[Extension Proposal] -* https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#shaders-objects[Specification] +* https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#shaders-objects[Specification] * https://github.com/KhronosGroup/Vulkan-ExtensionLayer/blob/main/docs/shader_object_layer.md[Emulation Layer] == Conclusion diff --git a/samples/extensions/synchronization_2/README.adoc b/samples/extensions/synchronization_2/README.adoc index 2dd656317..1365be858 100644 --- a/samples/extensions/synchronization_2/README.adoc +++ b/samples/extensions/synchronization_2/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2020-2023, The Khronos Group +- Copyright (c) 2020-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -24,7 +24,7 @@ TIP: The source for this sample can be found in the https://github.com/KhronosGr endif::[] -*Extension* https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_synchronization2[`VK_KHR_synchronization2`] +*Extension* https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#VK_KHR_synchronization2[`VK_KHR_synchronization2`] Demonstrates the use of the reworked synchronization api introduced with `VK_KHR_synchronization2`. Based on the compute shading N-Body particle system, this sample uses the new extension to streamline the memory barriers used for the compute and graphics work submissions. diff --git a/samples/performance/README.adoc b/samples/performance/README.adoc index fb97ea964..5436959b5 100644 --- a/samples/performance/README.adoc +++ b/samples/performance/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2021-2024, The Khronos Group +- Copyright (c) 2021-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -105,7 +105,7 @@ This sample will look in detail at the implementation and performance implicatio Vulkan render-passes use attachments to describe input and output render targets. This sample shows how loading and storing attachments might affect performance on mobile. During the creation of a render-pass, you can specify various color attachments and a depth-stencil attachment. -Each of those is described by a https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkAttachmentDescription.html[`VkAttachmentDescription`] struct, which contains attributes to specify the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkAttachmentLoadOp.html[load operation] (`loadOp`) and the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkAttachmentStoreOp.html[store operation] (`storeOp`). +Each of those is described by a https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkAttachmentDescription.html[`VkAttachmentDescription`] struct, which contains attributes to specify the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkAttachmentLoadOp.html[load operation] (`loadOp`) and the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkAttachmentStoreOp.html[store operation] (`storeOp`). This sample lets you choose between different combinations of these operations at runtime. === xref:./{performance_samplespath}specialization_constants/README.adoc[Specialization constants] diff --git a/samples/performance/command_buffer_usage/README.adoc b/samples/performance/command_buffer_usage/README.adoc index e3cd0e502..cf2720356 100644 --- a/samples/performance/command_buffer_usage/README.adoc +++ b/samples/performance/command_buffer_usage/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2024, Arm Limited and Contributors +- Copyright (c) 2019-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -35,12 +35,12 @@ This way they can all be submitted to the same render pass, and can take advanta == Secondary command buffers -Secondary command buffers can inherit the render pass state from a primary command buffer using a https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandBufferInheritanceInfo.html[VkCommandBufferInheritanceInfo] structure which is passed to https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkBeginCommandBuffer.html[vkBeginCommandBuffer] as part of https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandBufferBeginInfo.html[VkCommandBufferBeginInfo], along with the flag `VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT`. +Secondary command buffers can inherit the render pass state from a primary command buffer using a https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandBufferInheritanceInfo.html[VkCommandBufferInheritanceInfo] structure which is passed to https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkBeginCommandBuffer.html[vkBeginCommandBuffer] as part of https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandBufferBeginInfo.html[VkCommandBufferBeginInfo], along with the flag `VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT`. Secondary command buffers may then be recorded concurrently. -The primary command buffer must have used the flag `VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS` in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdBeginRenderPass.html[vkCmdBeginRenderPass]. +The primary command buffer must have used the flag `VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS` in https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdBeginRenderPass.html[vkCmdBeginRenderPass]. -Finally, the primary command buffer records https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdExecuteCommands.html[vkCmdExecuteCommands] (before https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdEndRenderPass.html[vkCmdEndRenderPass]) with an array of recorded secondary command buffers to execute. +Finally, the primary command buffer records https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdExecuteCommands.html[vkCmdExecuteCommands] (before https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdEndRenderPass.html[vkCmdEndRenderPass]) with an array of recorded secondary command buffers to execute. The sample divides the draw calls for opaque objects based on the slider value. It then submits a separate buffer for transparent objects if any, and finally one for the GUI elements if visible. @@ -49,8 +49,8 @@ It then submits a separate buffer for transparent objects if any, and finally on To record command buffers concurrently, the framework needs to manage resource pools per frame and per thread. According to the Vulkan Spec: -* https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandPool.html[_A command pool must not be used concurrently in multiple threads._] -* https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkDescriptorPool.html[_The application must not allocate and/or free descriptor sets from the same pool in multiple threads simultaneously._] +* https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandPool.html[_A command pool must not be used concurrently in multiple threads._] +* https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkDescriptorPool.html[_The application must not allocate and/or free descriptor sets from the same pool in multiple threads simultaneously._] In the framework, each frame in the queue (e.g. three frames in case of triple buffering) manages a collection of pools so that each thread can own: @@ -95,12 +95,12 @@ This sample compares them and demonstrates the best approach. === Allocate and free -Command buffers are allocated from a command pool with https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkAllocateCommandBuffers.html[vkAllocateCommandBuffers]. +Command buffers are allocated from a command pool with https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkAllocateCommandBuffers.html[vkAllocateCommandBuffers]. They can then be recorded and submitted to a queue for the Vulkan device to execute them. -A possible approach to managing the command buffers for each frame in our application would be to free them once they are executed, using https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkFreeCommandBuffers.html[vkFreeCommandBuffers]. +A possible approach to managing the command buffers for each frame in our application would be to free them once they are executed, using https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkFreeCommandBuffers.html[vkFreeCommandBuffers]. -The command pool will not automatically recycle memory from deleted command buffers if the command pool was created without the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] flag. +The command pool will not automatically recycle memory from deleted command buffers if the command pool was created without the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] flag. This flag however will force separate internal allocators to be used for each command buffer in the pool, which can increase CPU overhead compared to a single pool reset. This is the worst-performing method of managing command buffers as it involves a significant CPU overhead for allocating and freeing memory frequently. @@ -109,23 +109,23 @@ The sample shows how to use the framework to follow this approach and profile it image::./images/allocate_and_free.jpg[Allocate and Free] Rather than freeing and re-allocating the memory used by a command buffer, it is more efficient to recycle it for recording new commands. -There are two ways of resetting a command buffer: individually, with https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer], or indirectly by resetting the command pool with https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandPool.html[vkResetCommandPool]. +There are two ways of resetting a command buffer: individually, with https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer], or indirectly by resetting the command pool with https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandPool.html[vkResetCommandPool]. === Resetting individual command buffers -In order to reset command buffers individually with https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer], the pool must have been created with the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] flag set. +In order to reset command buffers individually with https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer], the pool must have been created with the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] flag set. The buffer will then return to a recordable state and the command pool can reuse the memory it allocated for it. -However frequent calls to https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer] are more expensive than a command pool reset. +However frequent calls to https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer] are more expensive than a command pool reset. image::./images/reset_buffers.jpg[Reset Buffers] === Resetting the command pool -Resetting the pool with https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandPool.html[vkResetCommandPool] automatically resets all the command buffers allocated by it. +Resetting the pool with https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandPool.html[vkResetCommandPool] automatically resets all the command buffers allocated by it. Doing this periodically will allow the pool to reuse the memory allocated for command buffers with lower CPU overhead. -To reset the pool the flag https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] is _not_ required, and it is actually better to avoid it since it prevents it from using a single large allocator for all buffers in the pool thus increasing memory overhead. +To reset the pool the flag https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] is _not_ required, and it is actually better to avoid it since it prevents it from using a single large allocator for all buffers in the pool thus increasing memory overhead. image::./images/reset_pool.jpg[Reset Pool] @@ -137,9 +137,9 @@ However the number of secondary command buffers should be kept low since their i This sample lets the user adjust the number of command buffers. Using a high number of secondary command buffers causes the application to become CPU bound and makes the differences between the described memory allocation approaches more pronounced. -All command buffers in this sample are initialized with the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandBufferUsageFlagBits.html[ONE_TIME_SUBMIT_BIT] flag set. +All command buffers in this sample are initialized with the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandBufferUsageFlagBits.html[ONE_TIME_SUBMIT_BIT] flag set. This indicates to the driver that the buffer will not be re-submitted after execution, and allows it to optimize accordingly. -Performance may be reduced if the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandBufferUsageFlagBits.html[SIMULTANEOUS_USE_BIT] flag is set instead. +Performance may be reduced if the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandBufferUsageFlagBits.html[SIMULTANEOUS_USE_BIT] flag is set instead. This sample provides options to try the three different approaches to command buffer management described above and monitor their efficiency. This is relatively obvious directly on the device by monitoring frame time. @@ -178,7 +178,7 @@ In this application the differences between individual reset and pool reset are == Further reading * xref:samples/performance/multithreading_render_passes/README.adoc[Multi-threaded recording with multiple render passes] -* https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/chap6.html#commandbuffer-allocation[Command Buffer Allocation and Management] +* https://www.khronos.org/registry/vulkan/specs/latest/html/chap6.html#commandbuffer-allocation[Command Buffer Allocation and Management] * https://www.khronos.org/registry/vulkan/specs/1.0-wsi_extensions/html/chap5.html#commandbuffers-lifecycle[Command Buffer Lifecycle] * _"Writing an efficient Vulkan renderer"_ by Arseny Kapoulkine (from "GPU Zen 2: Advanced Rendering Techniques") @@ -188,14 +188,14 @@ In this application the differences between individual reset and pool reset are * Use secondary command buffers to allow multi-threaded render pass construction. * Minimize the number of secondary command buffer invocations used per frame. -* Set https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandBufferUsageFlagBits.html[ONE_TIME_SUBMIT_BIT] if you are not going to reuse the command buffer. -* Periodically call https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandPool.html[vkResetCommandPool()] to release the memory if you are not reusing command buffers. +* Set https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandBufferUsageFlagBits.html[ONE_TIME_SUBMIT_BIT] if you are not going to reuse the command buffer. +* Periodically call https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandPool.html[vkResetCommandPool()] to release the memory if you are not reusing command buffers. *Don't* -* Set https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] if you only need to free the whole pool. +* Set https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandPoolCreateFlagBits.html[RESET_COMMAND_BUFFER_BIT] if you only need to free the whole pool. If the bit is not set, some implementations might use a single large allocator for the pool, reducing memory management overhead. -* Call https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer()] on a high frequency call path. +* Call https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer()] on a high frequency call path. *Impact* @@ -206,5 +206,5 @@ If the bit is not set, some implementations might use a single large allocator f *Debugging* -* Evaluate every use of any command buffer flag other than https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkCommandBufferUsageFlagBits.html[ONE_TIME_SUBMIT_BIT], and review whether it's a necessary use of the flag combination. -* Evaluate every use of https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer()] and see if it could be replaced with https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetCommandPool.html[vkResetCommandPool()] instead. +* Evaluate every use of any command buffer flag other than https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkCommandBufferUsageFlagBits.html[ONE_TIME_SUBMIT_BIT], and review whether it's a necessary use of the flag combination. +* Evaluate every use of https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandBuffer.html[vkResetCommandBuffer()] and see if it could be replaced with https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetCommandPool.html[vkResetCommandPool()] instead. diff --git a/samples/performance/constant_data/README.adoc b/samples/performance/constant_data/README.adoc index 8f4ebbb5a..46ab6a5f0 100644 --- a/samples/performance/constant_data/README.adoc +++ b/samples/performance/constant_data/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2021-2024, Arm Limited and Contributors +- Copyright (c) 2021-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -170,8 +170,8 @@ When we break this down, we have the following methods: * Dynamic Descriptor Sets * Update-after-bind Descriptor Sets * Buffer array with dynamic indexing -* https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_inline_uniform_block.html[Inline uniform buffer objects] (click to read more) -* https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_KHR_push_descriptor.html[Push descriptors] (click to read more) +* https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_EXT_inline_uniform_block.html[Inline uniform buffer objects] (click to read more) +* https://www.khronos.org/registry/vulkan/specs/latest/man/html/VK_KHR_push_descriptor.html[Push descriptors] (click to read more) *Inline uniform buffer objects* and *push descriptors* are not covered by this tutorial, please use the links above to learn more about them. @@ -234,7 +234,7 @@ layout(push_constant) uniform MeshData } mesh_data; ---- -To then send the push constant data to the shader we use the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#vkCmdPushConstants[`vkCmdPushConstants`] function: +To then send the push constant data to the shader we use the https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html#vkCmdPushConstants[`vkCmdPushConstants`] function: ---- void vkCmdPushConstants( @@ -285,7 +285,7 @@ So therefore we can deduce that for this shader we'd need a pipeline that has on To create a *descriptor set*, we need to allocate it from a *descriptor set pool* and give it a specific *descriptor set layout*. After a *descriptor set* is allocated, it needs to be updated with the *descriptors*. -The update process requires us to specify a list of *write operations*, where a write operation is a https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VkWriteDescriptorSet.html[`VkWriteDescriptorSet`] struct. +The update process requires us to specify a list of *write operations*, where a write operation is a https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkWriteDescriptorSet.html[`VkWriteDescriptorSet`] struct. Then the valid *descriptor set* is bound to a command buffer so that when `vkCmdDraw*()` commands are run, the right resources are made available in the GPU. @@ -385,7 +385,7 @@ To control the value of `gl_InstanceIndex` we use the `uint32_t firstInstance` p It's important to note that we can use other mechanisms to push this index to the shader, such as push constants. -For example, this `vkCmdDrawIndexed` is taken from the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkCmdDrawIndexed.html[Vulkan spec]: +For example, this `vkCmdDrawIndexed` is taken from the https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdDrawIndexed.html[Vulkan spec]: ---- void vkCmdDrawIndexed( @@ -431,7 +431,7 @@ A few different stats are affected in the Mali GPU by using this, but the main t == Further reading -* The https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html[Vulkan 1.2 spec] +* The https://www.khronos.org/registry/vulkan/specs/latest/html/vkspec.html[Vulkan 1.2 spec] * "Writing an efficient Vulkan renderer" by Arseny Kapoulkine https://zeux.io/2020/02/27/writing-an-efficient-vulkan-renderer/ * Alexander Overvoorde's https://vulkan-tutorial.com/Uniform_buffers/Descriptor_layout_and_buffer[Vulkan Tutorial on Descriptors] guide * Vulkan Fast Paths https://gpuopen.com/wp-content/uploads/2016/03/VulkanFastPaths.pdf diff --git a/samples/performance/descriptor_management/README.adoc b/samples/performance/descriptor_management/README.adoc index 658e4b586..d03ef4613 100644 --- a/samples/performance/descriptor_management/README.adoc +++ b/samples/performance/descriptor_management/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2024, Arm Limited and Contributors +- Copyright (c) 2019-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -41,10 +41,10 @@ We can either bind per-material and per-object descriptor sets separately or col Either way, complex applications will have a large amount of descriptor sets that may need to change on the fly, for example due to textures being streamed in or out. The simplest approach to circumvent the issue is to have one or more ``VkDescriptorPool``s per frame, reset them at the beginning of the frame and allocate the required descriptor sets from it. -This approach will consist of a https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetDescriptorPool.html[vkResetDescriptorPool()] call at the beginning, followed by a series of https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkAllocateDescriptorSets.html[vkAllocateDescriptorSets()] and https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkUpdateDescriptorSets.html[vkUpdateDescriptorSets()] to fill them with data. +This approach will consist of a https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetDescriptorPool.html[vkResetDescriptorPool()] call at the beginning, followed by a series of https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkAllocateDescriptorSets.html[vkAllocateDescriptorSets()] and https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkUpdateDescriptorSets.html[vkUpdateDescriptorSets()] to fill them with data. The issue is that these calls can add a significant overhead to the CPU frame time, especially on mobile. -In the worst cases, for example calling https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkUpdateDescriptorSets.html[vkUpdateDescriptorSets()] for each draw call, the time it takes to update descriptors can be longer than the time of the draws themselves. +In the worst cases, for example calling https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkUpdateDescriptorSets.html[vkUpdateDescriptorSets()] for each draw call, the time it takes to update descriptors can be longer than the time of the draws themselves. image::./images/bonza_no_caching_multiple_buf.jpg[Basic descriptor set management] @@ -57,7 +57,7 @@ Both these factors can significantly affect the results. == Caching descriptor sets A major way to reduce descriptor set updates is to re-use them as much as possible. -Instead of calling https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkResetDescriptorPool.html[vkResetDescriptorPool()] every frame, the app will keep the `VkDescriptorSet` handles stored with some caching mechanism to access them. +Instead of calling https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkResetDescriptorPool.html[vkResetDescriptorPool()] every frame, the app will keep the `VkDescriptorSet` handles stored with some caching mechanism to access them. The cache could be a hashmap with the contents of the descriptor set (images, buffers) as key. This approach is used in our framework by default. @@ -83,7 +83,7 @@ GPU frame time does not change much and the app is still CPU bound, so the speed This system is reasonably easy to implement for a static scene, but it becomes harder when you need to delete descriptor sets. Complex engines may implement techniques to figure out which descriptor sets have not been accessed for a certain number of frames, so they can be removed from the map. -This may correspond to calling https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkFreeDescriptorSets.html[vkFreeDescriptorSets()], but this solution poses another issue: in order to free individual descriptor sets the pool has to be created with the `VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT` flag. +This may correspond to calling https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkFreeDescriptorSets.html[vkFreeDescriptorSets()], but this solution poses another issue: in order to free individual descriptor sets the pool has to be created with the `VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT` flag. Mobile implementations may use a simpler allocator if that flag is not set, relying on the fact that pool memory will only be recycled in block. It is possible to avoid using that flag by updating descriptor sets instead of deleting them. @@ -110,7 +110,7 @@ This means that we will have many descriptor sets to create, since every object Furthermore, we will have to update many buffers separately, meaning we cannot control their memory layout and we might lose some optimization opportunities with caching. We can address both problems by reverting the approach: instead of having a `VkBuffer` per object containing per-frame data, we will have a `VkBuffer` per frame containing per-object data. -The buffer will be cleared at the beginning of the frame, then each object will record its data and will receive a dynamic offset to be used at https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdBindDescriptorSets.html[vkCmdBindDescriptorSets()] time. +The buffer will be cleared at the beginning of the frame, then each object will record its data and will receive a dynamic offset to be used at https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdBindDescriptorSets.html[vkCmdBindDescriptorSets()] time. With this approach we will need less descriptor sets, as more objects can share the same one: they will all reference the same `VkBuffer`, but at different dynamic offsets. Furthermore, we can control the memory layout within the buffer. @@ -151,6 +151,6 @@ For this relatively simple scene stacking the two approaches does not provide a *Debugging* -* The time spent in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkUpdateDescriptorSets.html[vkUpdateDescriptorSets()] can be checked with a CPU profiler. +* The time spent in https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkUpdateDescriptorSets.html[vkUpdateDescriptorSets()] can be checked with a CPU profiler. In the worst cases it may be comparable or higher than the time spent performing the actual draw calls. -* Monitor if there is contention on https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkAllocateDescriptorSets.html[vkAllocateDescriptorSets()], which will probably be a performance problem if it occurs. +* Monitor if there is contention on https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkAllocateDescriptorSets.html[vkAllocateDescriptorSets()], which will probably be a performance problem if it occurs. diff --git a/samples/performance/hpp_swapchain_images/README.adoc b/samples/performance/hpp_swapchain_images/README.adoc index 0a857fca0..ce3a3adcc 100644 --- a/samples/performance/hpp_swapchain_images/README.adoc +++ b/samples/performance/hpp_swapchain_images/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2024, The Khronos Group +- Copyright (c) 2022-2025, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -37,11 +37,11 @@ This sample analyzes the available options and their performance implications. == Choosing a number of images The control over the number of swapchain images is shared between the application and the platform. -The application can ask for a minimum number of images by setting the `minImageCount` parameter in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCreateSwapchainKHR.html[vk::Device::createSwapchainKHR]. -The exact number of images created can then be polled via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetSwapchainImagesKHR.html[vk::Device::getSwapchainImagesKHR]. +The application can ask for a minimum number of images by setting the `minImageCount` parameter in https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCreateSwapchainKHR.html[vk::Device::createSwapchainKHR]. +The exact number of images created can then be polled via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetSwapchainImagesKHR.html[vk::Device::getSwapchainImagesKHR]. -In order to properly set the `minImageCount` parameter, the application should get the surface capabilities of the physical device via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vk::PhysicalDevice::getSurfaceCapabilitiesKHR]. -The https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkSurfaceCapabilitiesKHR.html[vk::SurfaceCapabilitiesKHR] structure has the `minImageCount` and `maxImageCount` parameters, which set the boundaries for the image count that can be safely requested. +In order to properly set the `minImageCount` parameter, the application should get the surface capabilities of the physical device via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vk::PhysicalDevice::getSurfaceCapabilitiesKHR]. +The https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkSurfaceCapabilitiesKHR.html[vk::SurfaceCapabilitiesKHR] structure has the `minImageCount` and `maxImageCount` parameters, which set the boundaries for the image count that can be safely requested. As a rule of thumb on mobile, `+pSurfaceCapabilities->minImageCount+` is usually 2, while `+pSurfaceCapabilities->maxImageCount+` is large enough to not pose any problem with common applications (though it is still good practice to check its value). @@ -55,7 +55,7 @@ We will discuss present modes in the next section. == Choosing a present mode -The available present modes can be queried via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfacePresentModesKHR.html[vk::PhysicalDevice::getSurfacePresentModesKHR]. +The available present modes can be queried via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfacePresentModesKHR.html[vk::PhysicalDevice::getSurfacePresentModesKHR]. There are several presentation modes in Vulkan, but mobile GPUs do not support the ones in which the image is directly presented to the screen (immediate mode). The only ones which satisfy Android's VSync requirement are `vk::PresentModeKHR::eFifo` and `vk::PresentModeKHR::eMailbox`. @@ -131,7 +131,7 @@ After the marker we switch to double buffering and we confirm what we predicted *Do* -* Ensure that the value of `minImageCount` is within the valid range from https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vk::PhysicalDevice::getSurfaceCapabilitiesKHR] (between `minImageCount` and `maxImageCount`). +* Ensure that the value of `minImageCount` is within the valid range from https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vk::PhysicalDevice::getSurfaceCapabilitiesKHR] (between `minImageCount` and `maxImageCount`). * Use `vk::PresentModeKHR::eFifo` to avoid unnecessary CPU and GPU load. * Use triple buffering to maximize performance. @@ -148,5 +148,5 @@ If you want to cap framerate to 30 FPS to save power, this can be achieved on th *Debugging* -* It is possible to check how many images are created via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetSwapchainImagesKHR.html[vk::Device::getSwapchainImagesKHR]. +* It is possible to check how many images are created via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetSwapchainImagesKHR.html[vk::Device::getSwapchainImagesKHR]. If only 2 images are being created, `minImageCount` should be increased to 3, if the physical device allows for it (it normally does). diff --git a/samples/performance/image_compression_control/README.adoc b/samples/performance/image_compression_control/README.adoc index f6dcbe130..8f4af0e56 100644 --- a/samples/performance/image_compression_control/README.adoc +++ b/samples/performance/image_compression_control/README.adoc @@ -1,6 +1,6 @@ //// -- Copyright (c) 2024, The Khronos Group -- Copyright (c) 2024, Arm Limited and Contributors +- Copyright (c) 2024-2025, The Khronos Group +- Copyright (c) 2024-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -30,7 +30,7 @@ endif::[] == Overview -This sample shows how a Vulkan application can control the compression of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImage.html[`VkImage`] elements, in particular a framebuffer attachment and the swapchain. +This sample shows how a Vulkan application can control the compression of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImage.html[`VkImage`] elements, in particular a framebuffer attachment and the swapchain. This requires enabling and using the extensions https://docs.vulkan.org/spec/latest/appendices/extensions.html#VK_EXT_image_compression_control[`VK_EXT_image_compression_control`] and https://docs.vulkan.org/spec/latest/appendices/extensions.html#VK_EXT_image_compression_control_swapchain[`VK_EXT_image_compression_control_swapchain`], respectively. Applications that use compression generally perform better thanks to the reduced memory footprint and bandwidth. @@ -119,12 +119,12 @@ This is the case for the Space Module scene shown above. == VK_EXT_image_compression_control -This sample enables the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_compression_control.html[`VK_EXT_image_compression_control`] extension and requests the relevant device feature, https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPhysicalDeviceImageCompressionControlFeaturesEXT.html[`imageCompressionControl`] +This sample enables the https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_image_compression_control.html[`VK_EXT_image_compression_control`] extension and requests the relevant device feature, https://registry.khronos.org/vulkan/specs/latest/man/html/VkPhysicalDeviceImageCompressionControlFeaturesEXT.html[`imageCompressionControl`] This extension abstracts how applications choose a fixed compression rate, in terms of "minimum number of bits per component (BPC)". === Query for image compression support -To query if a particular image supports fixed-rate compression, add a https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageFormatProperties2KHR.html[`VkImageFormatProperties2`], and call https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceImageFormatProperties2KHR.html[`vkGetPhysicalDeviceImageFormatProperties2KHR`]: +To query if a particular image supports fixed-rate compression, add a https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageFormatProperties2KHR.html[`VkImageFormatProperties2`], and call https://registry.khronos.org/vulkan/specs/latest/man/html/vkGetPhysicalDeviceImageFormatProperties2KHR.html[`vkGetPhysicalDeviceImageFormatProperties2KHR`]: [,cpp] ---- @@ -148,8 +148,8 @@ vkGetPhysicalDeviceImageFormatProperties2KHR(device.get_gpu().get_handle(), &ima In the Vulkan Samples framework, this happens in the https://github.com/KhronosGroup/Vulkan-Samples/blob/main/framework/common/vk_common.cpp[`vkb::query_supported_fixed_rate_compression`] function. -Then inspect the values written to the `imageCompressionFixedRateFlags` component of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`]. -If fixed-rate compression is supported, the flags will indicate which levels may be selected for this image, for instance https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionFixedRateFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT`] or https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionFixedRateFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT`]. +Then inspect the values written to the `imageCompressionFixedRateFlags` component of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`]. +If fixed-rate compression is supported, the flags will indicate which levels may be selected for this image, for instance https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionFixedRateFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT`] or https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionFixedRateFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT`]. The sample will use the minimum BPC available for its high compression setting, and the maximum BPC available for its low compression setting. image::./images/fixed_rate_levels.png[Image Compression Control sample, 900, align="center"] @@ -159,7 +159,7 @@ __Fixed-rate options__ === Request image compression -To request fixed-rate compression, provide a https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionControlEXT.html[`VkImageCompressionControlEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCreateInfo.html[`VkImageCreateInfo`]: +To request fixed-rate compression, provide a https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionControlEXT.html[`VkImageCompressionControlEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCreateInfo.html[`VkImageCreateInfo`]: [,cpp] ---- @@ -180,13 +180,13 @@ image_info.pNext = &compression_control; vkCreateImage(device, &image_info, nullptr, &new_image); ---- -Note that, instead of using https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT`], one may use https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT`], and in that case it would not be necessary to provide a specific set of `pFixedRateFlags`. +Note that, instead of using https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT`], one may use https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT`], and in that case it would not be necessary to provide a specific set of `pFixedRateFlags`. In the Vulkan Samples framework, this happens in the https://github.com/KhronosGroup/Vulkan-Samples/blob/main/framework/core/image.cpp[`core::Image`] constructor. === Verify image compression [[verify_image_compression]] -To query which compression was applied, if any, once a https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImage.html[`VkImage`] has been created, add a https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageSubresource2EXT.html[`VkImageSubresource2EXT`], and call https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetImageSubresourceLayout2EXT.html[`vkGetImageSubresourceLayout2EXT`]: +To query which compression was applied, if any, once a https://registry.khronos.org/vulkan/specs/latest/man/html/VkImage.html[`VkImage`] has been created, add a https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageSubresource2EXT.html[`VkImageSubresource2EXT`], and call https://registry.khronos.org/vulkan/specs/latest/man/html/vkGetImageSubresourceLayout2EXT.html[`vkGetImageSubresourceLayout2EXT`]: [,cpp] ---- @@ -203,18 +203,18 @@ image_subresource.imageSubresource.arrayLayer = 0; vkGetImageSubresourceLayout2EXT(device, image, &image_subresource, &subresource_layout); ---- -Then inspect the values written to the `imageCompressionFlags` and `imageCompressionFixedRateFlags` components of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`]. +Then inspect the values written to the `imageCompressionFlags` and `imageCompressionFixedRateFlags` components of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`]. In the Vulkan Samples framework, this happens in the https://github.com/KhronosGroup/Vulkan-Samples/blob/main/framework/core/image.cpp[`core::Image::query_applied_compression`] function. == VK_EXT_image_compression_control_swapchain -Compression control for swapchain images is similar, but it requires the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_compression_control_swapchain.html[`VK_EXT_image_compression_control_swapchain`] extension and the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT.html[`imageCompressionControlSwapchain`] device feature to be enabled. -These depend on the https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_compression_control.html[`VK_EXT_image_compression_control`] being available and enabled too. +Compression control for swapchain images is similar, but it requires the https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_image_compression_control_swapchain.html[`VK_EXT_image_compression_control_swapchain`] extension and the https://registry.khronos.org/vulkan/specs/latest/man/html/VkPhysicalDeviceImageCompressionControlSwapchainFeaturesEXT.html[`imageCompressionControlSwapchain`] device feature to be enabled. +These depend on the https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_image_compression_control.html[`VK_EXT_image_compression_control`] being available and enabled too. === Query for surface compression support -To query if the surface supports fixed-rate compression, add a https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageFormatProperties2KHR.html[`VkImageFormatProperties2`], and call https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceImageFormatProperties2KHR.html[`vkGetPhysicalDeviceImageFormatProperties2KHR`]: +To query if the surface supports fixed-rate compression, add a https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageFormatProperties2KHR.html[`VkImageFormatProperties2`], and call https://registry.khronos.org/vulkan/specs/latest/man/html/vkGetPhysicalDeviceImageFormatProperties2KHR.html[`vkGetPhysicalDeviceImageFormatProperties2KHR`]: [,cpp] ---- @@ -239,12 +239,12 @@ for (uint32_t i = 0; i < surface_format_count; i++) vkGetPhysicalDeviceSurfaceFormats2KHR(device, &surface_info, &surface_format_count, surface_formats.data()); ---- -Then inspect the values written to the `imageCompressionFixedRateFlags` component of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`], associated to a particular https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkSurfaceFormat2KHR.html[`VkSurfaceFormat2KHR`]. +Then inspect the values written to the `imageCompressionFixedRateFlags` component of https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionPropertiesEXT.html[`VkImageCompressionPropertiesEXT`], associated to a particular https://registry.khronos.org/vulkan/specs/latest/man/html/VkSurfaceFormat2KHR.html[`VkSurfaceFormat2KHR`]. In the Vulkan Samples framework, this happens in the https://github.com/KhronosGroup/Vulkan-Samples/blob/main/framework/core/swapchain.cpp[`Swapchain::query_supported_fixed_rate_compression`] function. === Request surface compression -To request fixed-rate compression, provide a https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionControlEXT.html[`VkImageCompressionControlEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkSwapchainCreateInfoKHR.html[`VkSwapchainCreateInfoKHR`]: +To request fixed-rate compression, provide a https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionControlEXT.html[`VkImageCompressionControlEXT`] to the `pNext` chain of https://registry.khronos.org/vulkan/specs/latest/man/html/VkSwapchainCreateInfoKHR.html[`VkSwapchainCreateInfoKHR`]: [,cpp] ---- @@ -262,13 +262,13 @@ create_info.pNext = &compression_control; vkCreateSwapchainKHR(device, &create_info, nullptr, &new_swapchain); ---- -Similarly to regular images, https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT`] may be used instead. +Similarly to regular images, https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT`] may be used instead. In the Vulkan Samples framework, this happens in the https://github.com/KhronosGroup/Vulkan-Samples/blob/main/framework/core/swapchain.cpp[`Swapchain`] constructor. === Verify surface compression -To verify that compression was applied to the swapchain images, use the same method as described for a regular https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImage.html[`VkImage`] in <>. +To verify that compression was applied to the swapchain images, use the same method as described for a regular https://registry.khronos.org/vulkan/specs/latest/man/html/VkImage.html[`VkImage`] in <>. No need to enable https://docs.vulkan.org/spec/latest/appendices/extensions.html#VK_EXT_image_compression_control_swapchain[`VK_EXT_image_compression_control_swapchain`] for this. In the Vulkan Samples framework, this happens in the https://github.com/KhronosGroup/Vulkan-Samples/blob/main/framework/core/swapchain.cpp[`Swapchain::get_applied_compression`] function. @@ -278,9 +278,9 @@ The most likely reason is that, even though the GPU supports it, other IP compon == Disabling fixed-rate compression -As explained above, the `flags` in https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionControlEXT.html[`VkImageCompressionControlEXT`] control the compression scheme selection for images. +As explained above, the `flags` in https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionControlEXT.html[`VkImageCompressionControlEXT`] control the compression scheme selection for images. Take care not to accidentally disable <> when disabling <>. -That is, ensure that https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_DEFAULT_EXT`] is used by default, rather than https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_DISABLED_EXT`], which disables all compression, negatively impacting performance. +That is, ensure that https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_DEFAULT_EXT`] is used by default, rather than https://registry.khronos.org/vulkan/specs/latest/man/html/VkImageCompressionFlagBitsEXT.html[`VK_IMAGE_COMPRESSION_DISABLED_EXT`], which disables all compression, negatively impacting performance. == Conclusion diff --git a/samples/performance/render_passes/README.adoc b/samples/performance/render_passes/README.adoc index c8408e9dd..270de7eb9 100644 --- a/samples/performance/render_passes/README.adoc +++ b/samples/performance/render_passes/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2024, Arm Limited and Contributors +- Copyright (c) 2019-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -29,7 +29,7 @@ Vulkan render-passes use attachments to describe input and output render targets This sample shows how loading and storing attachments might affect performance on mobile. During the creation of a render-pass, you can specify various color attachments and a depth-stencil attachment. -Each of those is described by a https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkAttachmentDescription.html[`VkAttachmentDescription`] struct, which contains attributes to specify the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkAttachmentLoadOp.html[load operation] (`loadOp`) and the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkAttachmentStoreOp.html[store operation] (`storeOp`). +Each of those is described by a https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkAttachmentDescription.html[`VkAttachmentDescription`] struct, which contains attributes to specify the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkAttachmentLoadOp.html[load operation] (`loadOp`) and the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkAttachmentStoreOp.html[store operation] (`storeOp`). This sample lets you choose between different combinations of these operations at runtime. [,c] @@ -139,7 +139,7 @@ A render area is optimal when it satisfies all of the following conditions: * Either the `extent.height` member in `renderArea` is a multiple of the vertical granularity or `offset.y` + `extent.height` is equal to the height of the framebuffer in the `VkRenderPassBeginInfo`. A non optimal render area may cause a negative impact to performance. -More information on this is available https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetRenderAreaGranularity.html[here] and https://vulkan.lunarg.com/doc/view/1.0.33.0/linux/vkspec.chunked/ch07s04.html[here]. +More information on this is available https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetRenderAreaGranularity.html[here] and https://vulkan.lunarg.com/doc/view/1.0.33.0/linux/vkspec.chunked/ch07s04.html[here]. == Best-practice summary @@ -171,5 +171,5 @@ failing to follow this advice can result in significantly lower fragment shading *Debugging* -* Review API usage of https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkAttachmentDescription.html[attachments description]. -* Review API usage of https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCreateRenderPass.html[render pass creation], and any use of https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdClearColorImage.html[`vkCmdClearColorImage()`], https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdClearDepthStencilImage.html[`vkCmdClearDepthStencilImage()`] and https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdClearAttachments.html[`vkCmdClearAttachments()`]. +* Review API usage of https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkAttachmentDescription.html[attachments description]. +* Review API usage of https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCreateRenderPass.html[render pass creation], and any use of https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdClearColorImage.html[`vkCmdClearColorImage()`], https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdClearDepthStencilImage.html[`vkCmdClearDepthStencilImage()`] and https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdClearAttachments.html[`vkCmdClearAttachments()`]. diff --git a/samples/performance/subpasses/README.adoc b/samples/performance/subpasses/README.adoc index e6ee3cf9c..f678090ac 100644 --- a/samples/performance/subpasses/README.adoc +++ b/samples/performance/subpasses/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2024, Arm Limited and Contributors +- Copyright (c) 2019-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -90,7 +90,7 @@ image::./images/subpasses-renderpasses-trace.jpg[Subpasses vs render passes trac As stated by the Vulkan reference, _Subpasses with simple framebuffer-space dependencies may be merged into a single tile rendering pass, keeping the attachment data on-chip for the duration of a renderpass._ [<>]. Since subpass information is known ahead of time, the driver is able to detect if two or more subpasses can be merged together. -The consequence of this is that https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdNextSubpass.html[vkCmdNextSubpass] becomes a `NOP`. +The consequence of this is that https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCmdNextSubpass.html[vkCmdNextSubpass] becomes a `NOP`. In other words, a GPU driver can optimize even more by merging two or more subpasses together as long as certain requirements are met. Such requirements may vary between vendors, the following are the ones for Arm GPUs: @@ -128,7 +128,7 @@ Actually, there is not even a need to allocate them at all. image::./images/transient-attachments.jpg[Non-transient attachments] -In practice, their https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkImageUsageFlagBits.html[image usage] needs to be specified as `TRANSIENT` and their https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkMemoryPropertyFlagBits.html[memory] needs to be `LAZILY_ALLOCATED`. +In practice, their https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkImageUsageFlagBits.html[image usage] needs to be specified as `TRANSIENT` and their https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkMemoryPropertyFlagBits.html[memory] needs to be `LAZILY_ALLOCATED`. Failing to set these flags properly will lead to an increase of https://community.arm.com/developer/tools-software/graphics/b/blog/posts/mali-bifrost-family-performance-counters[fragment jobs] as the GPU will need to write them back to external memory. As you can see in the above screenshot, we see roughly a double in fragment jobs per second (from `56/s` to `113/s`). diff --git a/samples/performance/surface_rotation/README.adoc b/samples/performance/surface_rotation/README.adoc index 810a67166..5236a588c 100644 --- a/samples/performance/surface_rotation/README.adoc +++ b/samples/performance/surface_rotation/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2024, Arm Limited and Contributors +- Copyright (c) 2019-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -68,11 +68,11 @@ In a nutshell, below are the steps required to handle pre-rotation: | Re-create the swapchain using the new surface dimensions i.e. the swapchain dimensions match the surface's. -Ignore the `preTransform` field in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkSwapchainCreateInfoKHR.html[`VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR`]. -This will not match the value returned by https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[`vkGetPhysicalDeviceSurfaceCapabilitiesKHR`] and therefore the Android Compositor will rotate the scene before presenting it to the display +Ignore the `preTransform` field in https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkSwapchainCreateInfoKHR.html[`VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR`]. +This will not match the value returned by https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[`vkGetPhysicalDeviceSurfaceCapabilitiesKHR`] and therefore the Android Compositor will rotate the scene before presenting it to the display | Re-create the swapchain using the old swapchain dimensions, i.e. the swapchain dimensions do not change. -Update the `preTransform` field in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkSwapchainCreateInfoKHR.html[`VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR`] so that it matches the `currentTransform` field of the https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkSurfaceCapabilitiesKHR.html[`VkSurfaceCapabilitiesKHR`] returned by the new surface. +Update the `preTransform` field in https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkSwapchainCreateInfoKHR.html[`VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR`] so that it matches the `currentTransform` field of the https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkSurfaceCapabilitiesKHR.html[`VkSurfaceCapabilitiesKHR`] returned by the new surface. This communicates to Android that it does not need to rotate the scene. | Re-create the framebuffers @@ -163,8 +163,8 @@ VK_CHECK(vkGetPhysicalDeviceSurfaceCapabilitiesKHR(get_device().get_physical_dev pre_transform = surface_properties.currentTransform; ---- -`currentTransform` is a https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/chap32.html#VkSurfaceTransformFlagBitsKHR[`VkSurfaceTransformFlagBitsKHR`] value. -When we re-create the swapchain, we must set the swapchain's https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkSwapchainCreateInfoKHR.html[`preTransform`] to match this value. +`currentTransform` is a https://www.khronos.org/registry/vulkan/specs/latest/html/chap32.html#VkSurfaceTransformFlagBitsKHR[`VkSurfaceTransformFlagBitsKHR`] value. +When we re-create the swapchain, we must set the swapchain's https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkSwapchainCreateInfoKHR.html[`preTransform`] to match this value. This informs the compositor that the application has handled the required transform so it does not have to. To re-create the swapchain, the sample uses the helper function `update_swapchain` provided by the framework: @@ -288,8 +288,8 @@ In order to save battery life in those devices without a rotation-capable DPU, a *Do* -* To avoid presentation engine transformation passes ensure that swapchain https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkSwapchainCreateInfoKHR.html[`preTransform`] matches the `currentTransform` value returned by https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[`vkGetPhysicalDeviceSurfaceCapabilitiesKHR`]. -* If a swapchain image acquisition returns https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkResult.html[`VK_SUBOPTIMAL_KHR`] or https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkResult.html[`VK_ERROR_OUT_OF_DATE_KHR`] then recreate the swapchain taking into account any updated surface properties including potential orientation updates reported via `currentTransform`. +* To avoid presentation engine transformation passes ensure that swapchain https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkSwapchainCreateInfoKHR.html[`preTransform`] matches the `currentTransform` value returned by https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[`vkGetPhysicalDeviceSurfaceCapabilitiesKHR`]. +* If a swapchain image acquisition returns https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkResult.html[`VK_SUBOPTIMAL_KHR`] or https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkResult.html[`VK_ERROR_OUT_OF_DATE_KHR`] then recreate the swapchain taking into account any updated surface properties including potential orientation updates reported via `currentTransform`. *Don't* diff --git a/samples/performance/swapchain_images/README.adoc b/samples/performance/swapchain_images/README.adoc index caef1b8e0..2f3db785c 100644 --- a/samples/performance/swapchain_images/README.adoc +++ b/samples/performance/swapchain_images/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2025, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -31,11 +31,11 @@ This sample analyzes the available options and their performance implications. == Choosing a number of images The control over the number of swapchain images is shared between the application and the platform. -The application can ask for a minimum number of images by setting the `minImageCount` parameter in https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCreateSwapchainKHR.html[vkCreateSwapchainKHR]. -The exact number of images created can then be polled via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetSwapchainImagesKHR.html[vkGetSwapchainImagesKHR]. +The application can ask for a minimum number of images by setting the `minImageCount` parameter in https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkCreateSwapchainKHR.html[vkCreateSwapchainKHR]. +The exact number of images created can then be polled via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetSwapchainImagesKHR.html[vkGetSwapchainImagesKHR]. -In order to properly set the `minImageCount` parameter, the application should get the surface capabilities of the physical device via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vkGetPhysicalDeviceSurfaceCapabilitiesKHR]. -The https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/VkSurfaceCapabilitiesKHR.html[VkSurfaceCapabilitiesKHR] structure has the `minImageCount` and `maxImageCount` parameters, which set the boundaries for the image count that can be safely requested. +In order to properly set the `minImageCount` parameter, the application should get the surface capabilities of the physical device via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vkGetPhysicalDeviceSurfaceCapabilitiesKHR]. +The https://www.khronos.org/registry/vulkan/specs/latest/man/html/VkSurfaceCapabilitiesKHR.html[VkSurfaceCapabilitiesKHR] structure has the `minImageCount` and `maxImageCount` parameters, which set the boundaries for the image count that can be safely requested. As a rule of thumb on mobile, `+pSurfaceCapabilities->minImageCount+` is usually 2, while `+pSurfaceCapabilities->maxImageCount+` is large enough to not pose any problem with common applications (though it is still good practice to check its value). @@ -49,7 +49,7 @@ We will discuss present modes in the next section. == Choosing a present mode -The available present modes can be queried via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfacePresentModesKHR.html[vkGetPhysicalDeviceSurfacePresentModesKHR]. +The available present modes can be queried via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfacePresentModesKHR.html[vkGetPhysicalDeviceSurfacePresentModesKHR]. There are several presentation modes in Vulkan, but mobile GPUs do not support the ones in which the image is directly presented to the screen (immediate mode). The only ones which satisfy Android's VSync requirement are `VK_PRESENT_MODE_FIFO_KHR` and `VK_PRESENT_MODE_MAILBOX_KHR`. @@ -125,7 +125,7 @@ After the marker we switch to double buffering and we confirm what we predicted *Do* -* Ensure that the value of `minImageCount` is within the valid range from https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vkGetPhysicalDeviceSurfaceCapabilitiesKHR] (between `minImageCount` and `maxImageCount`). +* Ensure that the value of `minImageCount` is within the valid range from https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.html[vkGetPhysicalDeviceSurfaceCapabilitiesKHR] (between `minImageCount` and `maxImageCount`). * Use `VK_PRESENT_MODE_FIFO_KHR` to avoid unnecessary CPU and GPU load. * Use triple buffering to maximize performance. @@ -142,5 +142,5 @@ If you want to cap framerate to 30 FPS to save power, this can be achieved on th *Debugging* -* It is possible to check how many images are created via https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetSwapchainImagesKHR.html[vkGetSwapchainImagesKHR]. +* It is possible to check how many images are created via https://www.khronos.org/registry/vulkan/specs/latest/man/html/vkGetSwapchainImagesKHR.html[vkGetSwapchainImagesKHR]. If only 2 images are being created, `minImageCount` should be increased to 3, if the physical device allows for it (it normally does).