////
- Copyright (c) 2021-2024, The Khronos Group
-
- SPDX-License-Identifier: Apache-2.0
-
- Licensed under the Apache License, Version 2.0 the "License";
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-
////
ifndef::extension_samplespath[:extension_samplespath:]

== Extension samples

The goal of these samples is to demonstrate how to use a particular Vulkan extension at the API level with as little abstraction as possible.

=== 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`]

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`]

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`]

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`]

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.

=== xref:./{extension_samplespath}hpp_push_descriptors/README.adoc[HPP Push Descriptors]

A transcoded version of the Extensions sample xref:./{extension_samplespath}push_descriptors/README.adoc[Push Descriptors] that illustrates the usage of the C{pp} bindings of vulkan provided by Vulkan-Hpp.

=== 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`]

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`]

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`]

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`]

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.
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`]

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.
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`]

Render Sponza with Ambient Occlusion.
Place a vase in center.
Generate a particle fire that  demonstrates the TLAS (Top Level Acceleration Structure) animation for the same underlying geometry.
Procedurally generate a transparent quad and deform the geometry of the quad in the BLAS (Bottom Level Acceleration  Structure) to demonstrate how to animate with deforming geometry.
Shows how to rebuild the acceleration structure and when to set it to fast rebuild vs fast traversal.

=== 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`]

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.
The mesh shader creates the vertices for the triangle.
The mesh shading  pipeline includes the task and mesh shaders before going into the fragment shader.
This replaces the vertex /  geometry shader standard pipeline.

=== xref:./{extension_samplespath}hpp_mesh_shading/README.adoc[HPP Mesh shading]

A transcoded version of the Extensions sample xref:./{extension_samplespath}mesh_shading/README.adoc[Mesh shading] that illustrates the usage of the C{pp} bindings of vulkan provided by Vulkan-Hpp.

=== 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`]

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`]

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`]

This sample demonstrates usage of OpenCL extensions available on Arm devices.
Fill a procedural texture using OpenCL and display it using Vulkan.
In this sample data sharing between APIs is achieved using Android Hardware Buffers.

=== 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`]

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`]

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`]

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`]

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`]

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.
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`]

Render a simple scene showing the basics of shading rate dynamic.
This sample shows low and high frequency textures  over several cubes.
It creates a sample rate map based upon this frequency every frame.
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`]

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`]

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`]

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].
Also demonstrate use of beta extension which allows  for querying which features of the full Vulkan spec are not currently supported by the non-conformant Vulkan  implementation.

=== 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`]

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.
These building blocks are then used to create pipelines at runtime, improving build times compared to traditional pipeline creation.

=== 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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

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`]

Demonstrate how to use dynamic multisample rasterization (MSAA)
