From 6683c7f08ca7c820776396476b7fe1000899c3f9 Mon Sep 17 00:00:00 2001 From: Sascha Willems Date: Mon, 26 Feb 2024 18:16:06 +0100 Subject: [PATCH] Samples documentation fixes and enhanchements (#905) * Include related extension list instead of linking to it (link was broken anyway) * Different content depending on generator * Reworking things List of examples in subfolder readme This is then included in tioplevel sample listing instead Paths need to be adjusted via attributes to make it work for both * Fix links to ray tracing samples #903 * Fix xref paths Makes xrefs works both on the separate sample list as well as the page including it Refs #898 * Fix links to ray tracing samples Refs #903 * Add samples listing to docs navigation * Move api samples listing into separate readme Include in main listing * Added readme for general samples folder Include in main listing * Add samples listing to docs navigation * Move tooling and performance samples listing into separate readme Include in main listing * Update pull request template * Remove link to pull request template Didn't work in github either, and makes no sense People will see that template when they actually do a PR against the repo * Add link to framework components Fix linkage for framework core * Fix link to debug utils sample * Add a stub readme for the docs folder * Fix broken links Refs #824 * Fix broken image links Refs #824 * Removed unnecessary paragraph PRs are created via github anyway, and this automatically uses the PR template No need to mention it explicitly * Fix copyright * Fix copyright (again...) * Fix typo --- CONTRIBUTING.adoc | 8 +- antora/modules/ROOT/nav.adoc | 10 +- components/README.adoc | 5 +- docs/README.adoc | 21 + docs/build.adoc | 4 +- docs/pull_request_template.md | 2 +- samples/README.adoc | 512 +----------------- samples/api/README.adoc | 111 +++- .../hpp_texture_mipmap_generation/README.adoc | 8 +- samples/extensions/README.adoc | 246 ++++++++- .../dynamic_line_rasterization/README.adoc | 4 +- samples/general/README.adoc | 27 + samples/performance/README.adoc | 132 ++++- .../command_buffer_usage/README.adoc | 2 +- .../descriptor_management/README.adoc | 4 +- .../hpp_pipeline_cache/README.adoc | 10 +- .../hpp_swapchain_images/README.adoc | 14 +- .../layout_transitions/README.adoc | 4 +- samples/performance/msaa/README.adoc | 4 +- .../multithreading_render_passes/README.adoc | 2 +- .../performance/pipeline_barriers/README.adoc | 4 +- samples/performance/render_passes/README.adoc | 4 +- samples/performance/subpasses/README.adoc | 6 +- samples/tooling/README.adoc | 14 +- 24 files changed, 600 insertions(+), 558 deletions(-) create mode 100644 docs/README.adoc create mode 100644 samples/general/README.adoc diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 26efb531e..7c432c231 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -134,11 +134,7 @@ Ensure that you are using clang-format 8. . Make sure the sample code builds and runs on Windows, Linux, macOS and Android. If you cannot verify on all these target platforms, please note platform restrictions in the sample's README. . Verify the sample against a recent version of the Vulkan validation layers, either built from source or from the most recent available Vulkan SDK. -. Submit a <> for the contribution, including electronically signing the Khronos Contributor License Agreement (CLA) for the repository using CLA-Assistant. - -== Creating a Pull Request - -When you create your pull request, ensure the description is created with xref:docs/pull_request_template.md[this template], and then fill out the relative information. +. Submit a pull request via github for the contribution, including electronically signing the Khronos Contributor License Agreement (CLA) for the repository using CLA-Assistant. == Code Reviews diff --git a/antora/modules/ROOT/nav.adoc b/antora/modules/ROOT/nav.adoc index e5b1d1eb5..136800a6b 100644 --- a/antora/modules/ROOT/nav.adoc +++ b/antora/modules/ROOT/nav.adoc @@ -1,6 +1,6 @@ //// -- Copyright (c) 2024, Holochip Inc -- Copyright (c) 2024, Sascha Willems +- Copyright (c) 2023, Holochip Inc +- Copyright (c) 2023-2024, Sascha Willems - - SPDX-License-Identifier: Apache-2.0 - @@ -17,8 +17,10 @@ - limitations under the License. - //// +* xref:samples/README.adoc[Samples overview] * xref:samples/vulkan_basics.adoc[Vulkan basics] * xref:framework/README.adoc[Sample framework] +** xref:components/README.adoc[Framework components] * xref:samples/api/README.adoc[Api usage samples] ** xref:samples/api/compute_nbody/README.adoc[Compute N-body] *** xref:samples/api/hpp_compute_nbody/README.adoc[Compute N-body (Vulkan-Hpp)] @@ -71,8 +73,8 @@ ** xref:samples/extensions/open_gl_interop/README.adoc[OpenGL interop] ** xref:samples/extensions/portability/README.adoc[Portability] ** xref:samples/extensions/push_descriptors/README.adoc[Push descriptors] -** xref:samples/extensions/raytracing_basic/README.adoc[Raytracing basic] -** xref:samples/extensions/raytracing_extended/README.adoc[Raytracing extended] +** xref:samples/extensions/ray_tracing_basic/README.adoc[Raytracing basic] +** xref:samples/extensions/ray_tracing_extended/README.adoc[Raytracing extended] ** xref:samples/extensions/ray_queries/README.adoc[Ray queries] ** xref:samples/extensions/ray_tracing_reflection/README.adoc[Ray tracing reflection] ** xref:samples/extensions/shader_object/README.adoc[Shader Object] diff --git a/components/README.adoc b/components/README.adoc index 9225a7e33..8f33066d1 100644 --- a/components/README.adoc +++ b/components/README.adoc @@ -1,5 +1,6 @@ //// -- Copyright (c) 2023, Thomas Atkinson +- Copyright (c) 2023-2024, Thomas Atkinson +- Copyright (c) 2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -31,7 +32,7 @@ These interfaces are defined in `components/core`. *Core* is the only component which does not follow the component pattern in its entirety. The only major difference between core and other components is the header prefix used is `core/` instead of `components/core/`. -See xref:core/README.adoc[core documentation] for more information. +See xref:./core/README.adoc[core documentation] for more information. == Create a new component diff --git a/docs/README.adoc b/docs/README.adoc new file mode 100644 index 000000000..952748f7c --- /dev/null +++ b/docs/README.adoc @@ -0,0 +1,21 @@ +//// +- Copyright (c) 2024, Sascha Willems +- +- 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. +- +//// += General documentation + +This folder contains documentation on general usage of the samples. \ No newline at end of file diff --git a/docs/build.adoc b/docs/build.adoc index 284368747..499ffb9d7 100644 --- a/docs/build.adoc +++ b/docs/build.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -82,7 +82,7 @@ Enable https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/sy Enable VK_EXT_debug_utils or VK_EXT_debug_marker, if supported. This enables debug names for Vulkan objects, and markers/labels in command buffers. -+ See the xref:samples/extensions/debug_utils/debug_utils_tutorial.adoc[debug utils sample] for more information. ++ See the xref:../samples/extensions/debug_utils/README.adoc[debug utils sample] for more information. *Default:* `ON` diff --git a/docs/pull_request_template.md b/docs/pull_request_template.md index 5818a36b4..580ddb736 100644 --- a/docs/pull_request_template.md +++ b/docs/pull_request_template.md @@ -31,6 +31,6 @@ If your PR contains a new or modified sample, these further checks must be carri - [ ] If the sample is vendor-specific, I have [tagged it appropriately](https://github.com/KhronosGroup/Vulkan-Samples/tree/main/CONTRIBUTING.adoc#General-Requirements) - [ ] I have stated on what implementation the sample has been tested so that others can test on different implementations and platforms - [ ] Any dependent assets have been merged and published in downstream modules -- [ ] For new samples, I have added a paragraph with a summary to the appropriate chapter in the [samples readme](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/samples/README.adoc) +- [ ] For new samples, I have added a paragraph with a summary to the appropriate chapter in the readme of the folder that the sample belongs to [e.g. api samples readme](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/samples/api/README.adoc) - [ ] For new samples, I have added a tutorial README.md file to guide users through what they need to know to implement code using this feature. For example, see [conditional_rendering](https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/extensions/conditional_rendering) - [ ] For new samples, I have added a link to the [Antora navigation](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/antora/modules/ROOT/nav.adoc) so that the sample will be listed at the Vulkan documentation site diff --git a/samples/README.adoc b/samples/README.adoc index c4b15dd1d..e7be87ccc 100644 --- a/samples/README.adoc +++ b/samples/README.adoc @@ -16,6 +16,12 @@ - limitations under the License. - //// +ifndef::performance_samplespath[:performance_samplespath: ./performance/] +ifndef::extension_samplespath[:extension_samplespath: ./extensions/] +ifndef::api_samplespath[:api_samplespath: ./api/] +ifndef::general_samplespath[:general_samplespath: ./general/] +ifndef::tooling_samplespath[:tooling_samplespath: ./tooling/] + = Samples overview :pp: {plus}{plus} :toc: @@ -27,503 +33,17 @@ This readme lists all Vulkan samples currently available in this repository. They are grouped into multiple categories. Many samples come with a tutorial, which can be found in their respective folders. -== Performance samples - -The goal of these samples is to demonstrate how to use certain features and functions to achieve optimal performance. -To visualize this, they also include real-time profiling information. - -=== xref:./performance/afbc/README.adoc[AFBC] - -AFBC (Arm Frame Buffer Compression) is a real-time lossless compression algorithm found in Arm Mali GPUs, designed to tackle the ever-growing demand for higher resolution graphics. -This format is applied to the framebuffers that are to be written to the GPU. -This technology can offer bandwidth reductions of https://developer.arm.com/technologies/graphics-technologies/arm-frame-buffer-compression[up to 50%]. - -=== xref:./performance/command_buffer_usage/README.adoc[Command buffer usage] - -This sample demonstrates how to use and manage secondary command buffers, and how to record them concurrently. -Implementing multi-threaded recording of draw calls can help reduce CPU frame time. - -=== xref:./performance/constant_data/README.adoc[Constant data] - -The Vulkan API exposes a few different ways in which we can send uniform data into our shaders. -There are enough methods that it raises the question "Which one is fastest?", and more often than not the answer is "It depends". -The main issue for developers is that the fastest methods may differ between the various vendors, so often there is no "one size fits all" solution. -This sample aims to highlight this issue, and help move the Vulkan ecosystem to a point where we are better equipped to solve this for developers. -This is done by having an interactive way to toggle different constant data methods that the Vulkan API expose to us. -This can then be run on a platform of the developers choice to see the performance implications that each of them bring. - -=== xref:./performance/descriptor_management/README.adoc[Descriptor management] -An application using Vulkan will have to implement a system to manage descriptor pools and sets. -The most straightforward and flexible approach is to re-create them for each frame, but doing so might be very inefficient, especially on mobile platforms. -The problem of descriptor management is intertwined with that of buffer management, that is choosing how to pack data in `VkBuffer` objects. -This sample will explore a few options to improve both descriptor and buffer management. - -=== xref:./performance/hpp_swapchain_images/README.adoc[HPP Swapchain images] - -A transcoded version of the Performance sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. - -=== xref:./performance/layout_transitions/README.adoc[Layout transitions] - -Vulkan requires the application to manage image layouts, so that all render pass attachments are in the correct layout when the render pass begins. -This is usually done using pipeline barriers or the `initialLayout` and `finalLayout` parameters of the render pass. -If the rendering pipeline is complex, transitioning each image to its correct layout is not trivial, as it requires some sort of state tracking. -If previous image contents are not needed, there is an easy way out, that is setting `oldLayout`/`initialLayout` to `VK_IMAGE_LAYOUT_UNDEFINED`. -While this is functionally correct, it can have performance implications as it may prevent the GPU from performing some optimizations. -This sample will cover an example of such optimizations and how to avoid the performance overhead from using sub-optimal layouts. - -=== xref:./performance/msaa/README.adoc[MSAA] - -Aliasing is the result of under-sampling a signal. -In graphics this means computing the color of a pixel at a resolution that results in artifacts, commonly jaggies at model edges. -Multisample anti-aliasing (MSAA) is an efficient technique that reduces pixel sampling error. - -=== xref:./performance/multithreading_render_passes/README.adoc[Multi-threaded recording with multiple render passes] - -Ideally you render all stages of your frame in a single render pass. -However, in some cases different stages can't be performed in the same render pass. -This sample shows how multi-threading can help to boost performance when using multiple render passes to render a single frame. - -=== xref:./performance/pipeline_barriers/README.adoc[Pipeline barriers] - -Vulkan gives the application significant control over memory access for resources. -Pipeline barriers are particularly convenient for synchronizing memory accesses between render passes. -Having barriers is required whenever there is a memory dependency - the application should not assume that render passes are executed in order. -However, having too many or too strict barriers can affect the application's performance. -This sample will cover how to set up pipeline barriers efficiently, with a focus on pipeline stages. - -=== xref:./performance/pipeline_cache/README.adoc[Pipeline cache] - -Vulkan gives applications the ability to save internal representation of a pipeline (graphics or compute) to enable recreating the same pipeline later. -This sample will look in detail at the implementation and performance implications of the pipeline creation, caching and management. - -=== xref:./performance/render_passes/README.adoc[Render passes] - -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`). -This sample lets you choose between different combinations of these operations at runtime. - -=== xref:./performance/specialization_constants/README.adoc[Specialization constants] - -Vulkan exposes a number of methods for setting values within shader code during run-time, this includes UBOs and Specialization Constants. -This sample compares these two methods and the performance impact of them. - -=== xref:./performance/subpasses/README.adoc[Sub passes] - -Vulkan introduces the concept of _subpasses_ to subdivide a single xref:./performance/render_passes/README.adoc[render pass] into separate logical phases. -The benefit of using subpasses over multiple render passes is that a GPU is able to perform various optimizations. -Tile-based renderers, for example, can take advantage of tile memory, which being on chip is decisively faster than external memory, potentially saving a considerable amount of bandwidth. - -=== xref:./performance/surface_rotation/README.adoc[Surface rotation] - -Mobile devices can be rotated, therefore the logical orientation of the application window and the physical orientation of the display may not match. -Applications then need to be able to operate in two modes: portrait and landscape. -The difference between these two modes can be simplified to just a change in resolution. -However, some display subsystems always work on the "native" (or "physical") orientation of the display panel. -Since the device has been rotated, to achieve the desired effect the application output must also rotate. -In this sample we focus on the rotation step, and analyze the performance implications of implementing it correctly with Vulkan. - -=== xref:./performance/swapchain_images/README.adoc[Swapchain images] - -Vulkan gives the application some significant control over the number of swapchain images to be created. -This sample analyzes the available options and their performance implications. - -=== xref:./performance/wait_idle/README.adoc[Wait idle] - -This sample compares two methods for synchronizing between the CPU and GPU, `WaitIdle` and `Fences` demonstrating which one is the best option in order to avoid stalling. - -=== xref:./performance/16bit_storage_input_output/README.adoc[16-bit storage InputOutput] - -This sample compares bandwidth consumption when using FP32 varyings compared to using FP16 varyings with `VK_KHR_16bit_storage`. - -=== xref:./performance/16bit_arithmetic/README.adoc[16-bit arithmetic] - -This sample compares arithmetic throughput for 32-bit arithmetic operations and 16-bit arithmetic. -The sample also shows how to enable 16-bit storage for SSBOs and push constants. - -=== xref:./performance/async_compute/README.adoc[Async compute] - -This sample demonstrates using multiple Vulkan queues to get better hardware utilization with compute post-processing workloads. - -=== xref:./performance/texture_compression_basisu/README.adoc[Basis Universal supercompressed GPU textures] - -This sample demonstrates how to use Basis universal supercompressed GPU textures in a Vulkan application. - -=== xref:./performance/multi_draw_indirect/README.adoc[GPU Rendering and Multi-Draw Indirect] - -This sample demonstrates how to reduce CPU usage by offloading draw call generation and frustum culling to the GPU. - -=== xref:./performance/texture_compression_comparison/README.adoc[Texture compression comparison] - -This sample demonstrates how to use different types of compressed GPU textures in a Vulkan application, and shows the timing benefits of each. - -== API samples - -The goal of these samples is to demonstrate how to use a given Vulkan feature at the API level with as little abstraction as possible. - -=== xref:./api/compute_nbody/README.adoc[Compute shader N-Body simulation] - -Compute shader example that uses two passes and shared compute shader memory for simulating a N-Body particle system. - -=== xref:./api/dynamic_uniform_buffers/README.adoc[Dynamic Uniform buffers] - -Dynamic uniform buffers are used for rendering multiple objects with separate matrices stored in a single uniform buffer object, that are addressed dynamically. - -=== xref:./api/hdr/README.adoc[High dynamic range] - -Implements a high dynamic range rendering pipeline using 16/32 bit floating point precision for all calculations. - -=== xref:./api/hello_triangle/README.adoc[Hello Triangle] - -A self-contained (minimal use of framework) sample that illustrates the rendering of a triangle. - -=== xref:./api/hpp_compute_nbody/README.adoc[HPP Compute shader N-Body simulation] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_dynamic_uniform_buffers/README.adoc[HPP Dynamic Uniform Buffers] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_hdr/README.adoc[HPP High dynamic range] - -A transcoded version of the API sample <>that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_hello_triangle/README.adoc[HPP Hello Triangle] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_hlsl_shaders/README.adoc[HPP HLSL shaders] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_instancing/README.adoc[HPP Instancing] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_oit_linked_lists/README.adoc[HPP OIT Linked Lists] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_separate_image_sampler/README.adoc[HPP Separate image sampler] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_terrain_tessellation/README.adoc[HPP Terrain Tessellation] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_texture_loading/README.adoc[HPP Texture Loading] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_texture_mipmap_generation/README.adoc[HPP Texture run-time mip-map generation] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. - -=== xref:./api/hpp_timestamp_queries/README.adoc[HPP Timestamp queries] - -A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. - -=== xref:./api/instancing/README.adoc[Instancing] - -Uses the instancing feature for rendering many instances of the same mesh from a single vertex buffer with variable parameters and textures. - -=== xref:./api/separate_image_sampler/README.adoc[Separate image sampler] - -Separate image and samplers, both in the application and the shaders. -The sample demonstrates how to use different samplers for the same image without the need to recreate descriptors. - -=== xref:./api/terrain_tessellation/README.adoc[Terrain Tessellation] - -Uses a tessellation shader for rendering a terrain with dynamic level-of-detail and frustum culling. - -=== xref:./api/texture_loading/README.adoc[Texture loading] - -Loading and rendering of a 2D texture map from a file. - -=== xref:./api/texture_mipmap_generation/README.adoc[Texture run-time mip-map generation] - -Generates a complete mip-chain for a texture at runtime instead of loading it from a file. - -=== xref:./api/hlsl_shaders/README.adoc[HLSL shaders] - -Converts High Level Shading Language (HLSL) shaders to Vulkan-compatible SPIR-V. - -=== xref:./api/timestamp_queries/README.adoc[Timestamp queries] - -Using timestamp queries for profiling GPU workloads. - -=== xref:./api/swapchain_recreation/README.adoc[Swapchain recreation] - -A sample that implements best practices in handling swapchain recreation, for example due to window resizing or present mode changes. - -=== xref:./api/oit_linked_lists/README.adoc[Order-independent transparency with per-pixel ordered linked lists] - -A sample that implements an order-independent transparency algorithm using per-pixel ordered linked lists. - -=== xref:./api/oit_depth_peeling/README.adoc[Order-independent transparency with depth peeling] - -A sample that implements order-independent transparency with depth peeling. - -== 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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/raytracing_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:./extensions/raytracing_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:./extensions/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:./extensions/hpp_mesh_shading/README.adoc[HPP Mesh shading] - -A transcoded version of the Extensions sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. - -=== xref:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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:./extensions/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. - -== Tooling Samples - -The goal of these samples is to demonstrate usage of tooling functions and libraries that are not directly part of the api. - -=== xref:./tooling/profiles/README.adoc[Profiles Library] - -Use the https://github.com/KhronosGroup/Vulkan-Profiles[Vulkan Profiles library] to simplify instance and device setup. -The library defines a common baseline of features, extensions, etc. +[[performance-samples]] +include::./performance/README.adoc[] -== General Samples +[[api-samples]] +include::./api/README.adoc[] -The goal of these samples is to demonstrate different techniques or showcase complex scenarios that doesn't necessarily fit any of the main categories. +[[extension-samples]] +include::./extensions/README.adoc[] -=== xref:./general/mobile_nerf/README.adoc[Mobile NeRF] +[[tooling-samples]] +include::./tooling/README.adoc[] -A Neural Radiance Field synthesizer sample, based on textured polygons. +[[general-samples]] +include::./general/README.adoc[] \ No newline at end of file diff --git a/samples/api/README.adoc b/samples/api/README.adoc index 28aa3b822..b5415840f 100644 --- a/samples/api/README.adoc +++ b/samples/api/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2021-2023, The Khronos Group +- Copyright (c) 2021-2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -16,8 +16,113 @@ - limitations under the License. - //// -= API samples +ifndef::api_samplespath[:api_samplespath:] + +== API samples The goal of these samples is to demonstrate how to use a given Vulkan feature at the API level with as little abstraction as possible. -A list of all API samples can be found link:../README.adoc#api-samples[here]. +=== xref:./{api_samplespath}compute_nbody/README.adoc[Compute shader N-Body simulation] + +Compute shader example that uses two passes and shared compute shader memory for simulating a N-Body particle system. + +=== xref:./{api_samplespath}dynamic_uniform_buffers/README.adoc[Dynamic Uniform buffers] + +Dynamic uniform buffers are used for rendering multiple objects with separate matrices stored in a single uniform buffer object, that are addressed dynamically. + +=== xref:./{api_samplespath}hdr/README.adoc[High dynamic range] + +Implements a high dynamic range rendering pipeline using 16/32 bit floating point precision for all calculations. + +=== xref:./{api_samplespath}hello_triangle/README.adoc[Hello Triangle] + +A self-contained (minimal use of framework) sample that illustrates the rendering of a triangle. + +=== xref:./{api_samplespath}hpp_compute_nbody/README.adoc[HPP Compute shader N-Body simulation] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_dynamic_uniform_buffers/README.adoc[HPP Dynamic Uniform Buffers] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_hdr/README.adoc[HPP High dynamic range] + +A transcoded version of the API sample <>that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_hello_triangle/README.adoc[HPP Hello Triangle] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_hlsl_shaders/README.adoc[HPP HLSL shaders] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_instancing/README.adoc[HPP Instancing] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_oit_linked_lists/README.adoc[HPP OIT Linked Lists] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of Vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_separate_image_sampler/README.adoc[HPP Separate image sampler] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_terrain_tessellation/README.adoc[HPP Terrain Tessellation] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_texture_loading/README.adoc[HPP Texture Loading] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_texture_mipmap_generation/README.adoc[HPP Texture run-time mip-map generation] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}hpp_timestamp_queries/README.adoc[HPP Timestamp queries] + +A transcoded version of the API sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. + +=== xref:./{api_samplespath}instancing/README.adoc[Instancing] + +Uses the instancing feature for rendering many instances of the same mesh from a single vertex buffer with variable parameters and textures. + +=== xref:./{api_samplespath}separate_image_sampler/README.adoc[Separate image sampler] + +Separate image and samplers, both in the application and the shaders. +The sample demonstrates how to use different samplers for the same image without the need to recreate descriptors. + +=== xref:./{api_samplespath}terrain_tessellation/README.adoc[Terrain Tessellation] + +Uses a tessellation shader for rendering a terrain with dynamic level-of-detail and frustum culling. + +=== xref:./{api_samplespath}texture_loading/README.adoc[Texture loading] + +Loading and rendering of a 2D texture map from a file. + +=== xref:./{api_samplespath}texture_mipmap_generation/README.adoc[Texture run-time mip-map generation] + +Generates a complete mip-chain for a texture at runtime instead of loading it from a file. + +=== xref:./{api_samplespath}hlsl_shaders/README.adoc[HLSL shaders] + +Converts High Level Shading Language (HLSL) shaders to Vulkan-compatible SPIR-V. + +=== xref:./{api_samplespath}timestamp_queries/README.adoc[Timestamp queries] + +Using timestamp queries for profiling GPU workloads. + +=== xref:./{api_samplespath}swapchain_recreation/README.adoc[Swapchain recreation] + +A sample that implements best practices in handling swapchain recreation, for example due to window resizing or present mode changes. + +=== xref:./{api_samplespath}oit_linked_lists/README.adoc[Order-independent transparency with per-pixel ordered linked lists] + +A sample that implements an order-independent transparency algorithm using per-pixel ordered linked lists. + +=== xref:./{api_samplespath}oit_depth_peeling/README.adoc[Order-independent transparency with depth peeling] + +A sample that implements order-independent transparency with depth peeling. \ No newline at end of file diff --git a/samples/api/hpp_texture_mipmap_generation/README.adoc b/samples/api/hpp_texture_mipmap_generation/README.adoc index d57ac14a3..f2a6a32d9 100644 --- a/samples/api/hpp_texture_mipmap_generation/README.adoc +++ b/samples/api/hpp_texture_mipmap_generation/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2023, The Khronos Group +- Copyright (c) 2022-2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -47,15 +47,15 @@ To detect this, check for queue families with only the `vk::QueueFlagBits::eTra Without mip mapping: -image::../texture_mipmap_generation/images/mip_mapping_off.jpg[Off,512px] +image::samples/api/texture_mipmap_generation/images/mip_mapping_off.jpg[Off,512px] Using mip mapping with a bilinear filter: -image:../texture_mipmap_generation/images/mip_mapping_bilinear.jpg[Bilinear,512px] +image::samples/api/texture_mipmap_generation/images/mip_mapping_bilinear.jpg[Bilinear,512px] Using mip mapping with an anisotropic filter: -image:../texture_mipmap_generation/images/mip_mapping_anisotropic.jpg[Anisotropic,512px] +image::samples/api/texture_mipmap_generation/images/mip_mapping_anisotropic.jpg[Anisotropic,512px] == Requirements diff --git a/samples/extensions/README.adoc b/samples/extensions/README.adoc index 33ba62991..cc24c3bec 100644 --- a/samples/extensions/README.adoc +++ b/samples/extensions/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2021-2023, The Khronos Group +- Copyright (c) 2021-2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -16,8 +16,248 @@ - limitations under the License. - //// -= Extension samples +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. -A list of all extension samples can be found link:../README.adoc#extension-samples[here]. +=== 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}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}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 <> 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}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. \ No newline at end of file diff --git a/samples/extensions/dynamic_line_rasterization/README.adoc b/samples/extensions/dynamic_line_rasterization/README.adoc index 6b76bd121..f913604c7 100644 --- a/samples/extensions/dynamic_line_rasterization/README.adoc +++ b/samples/extensions/dynamic_line_rasterization/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, Mobica Limited +- Copyright (c) 2023-2024, Mobica Limited - - 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::[] -image::screenshot.png[] +image::./screenshot.png[] == Overview diff --git a/samples/general/README.adoc b/samples/general/README.adoc new file mode 100644 index 000000000..b6fb95940 --- /dev/null +++ b/samples/general/README.adoc @@ -0,0 +1,27 @@ +//// +- Copyright (c) 2024, Sascha Willems +- +- 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::general_samplespath[:general_samplespath:] + +== General Samples + +The goal of these samples is to demonstrate different techniques or showcase complex scenarios that doesn't necessarily fit any of the main categories. + +=== xref:./{general_samplespath}mobile_nerf/README.adoc[Mobile NeRF] + +A Neural Radiance Field synthesizer sample, based on textured polygons. \ No newline at end of file diff --git a/samples/performance/README.adoc b/samples/performance/README.adoc index 0ee581b2d..05271ae35 100644 --- a/samples/performance/README.adoc +++ b/samples/performance/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2021-2023, The Khronos Group +- Copyright (c) 2021-2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -16,9 +16,135 @@ - limitations under the License. - //// -= Performance samples +ifndef::performance_samplespath[:performance_samplespath:] + +== Performance samples The goal of these samples is to demonstrate how to use certain features and functions to achieve optimal performance. To visualize this, they also include real-time profiling information. -A list of all performance samples can be found link:../README.adoc#performance-samples[here]. +=== xref:./{performance_samplespath}afbc/README.adoc[AFBC] + +AFBC (Arm Frame Buffer Compression) is a real-time lossless compression algorithm found in Arm Mali GPUs, designed to tackle the ever-growing demand for higher resolution graphics. +This format is applied to the framebuffers that are to be written to the GPU. +This technology can offer bandwidth reductions of https://developer.arm.com/technologies/graphics-technologies/arm-frame-buffer-compression[up to 50%]. + +=== xref:./{performance_samplespath}command_buffer_usage/README.adoc[Command buffer usage] + +This sample demonstrates how to use and manage secondary command buffers, and how to record them concurrently. +Implementing multi-threaded recording of draw calls can help reduce CPU frame time. + +=== xref:./{performance_samplespath}constant_data/README.adoc[Constant data] + +The Vulkan API exposes a few different ways in which we can send uniform data into our shaders. +There are enough methods that it raises the question "Which one is fastest?", and more often than not the answer is "It depends". +The main issue for developers is that the fastest methods may differ between the various vendors, so often there is no "one size fits all" solution. +This sample aims to highlight this issue, and help move the Vulkan ecosystem to a point where we are better equipped to solve this for developers. +This is done by having an interactive way to toggle different constant data methods that the Vulkan API expose to us. +This can then be run on a platform of the developers choice to see the performance implications that each of them bring. + +=== xref:./{performance_samplespath}descriptor_management/README.adoc[Descriptor management] +An application using Vulkan will have to implement a system to manage descriptor pools and sets. +The most straightforward and flexible approach is to re-create them for each frame, but doing so might be very inefficient, especially on mobile platforms. +The problem of descriptor management is intertwined with that of buffer management, that is choosing how to pack data in `VkBuffer` objects. +This sample will explore a few options to improve both descriptor and buffer management. + +=== xref:./{performance_samplespath}hpp_swapchain_images/README.adoc[HPP Swapchain images] + +A transcoded version of the Performance sample <> that illustrates the usage of the C{pp} bindings of vulkan provided by vulkan.hpp. + +=== xref:./{performance_samplespath}layout_transitions/README.adoc[Layout transitions] + +Vulkan requires the application to manage image layouts, so that all render pass attachments are in the correct layout when the render pass begins. +This is usually done using pipeline barriers or the `initialLayout` and `finalLayout` parameters of the render pass. +If the rendering pipeline is complex, transitioning each image to its correct layout is not trivial, as it requires some sort of state tracking. +If previous image contents are not needed, there is an easy way out, that is setting `oldLayout`/`initialLayout` to `VK_IMAGE_LAYOUT_UNDEFINED`. +While this is functionally correct, it can have performance implications as it may prevent the GPU from performing some optimizations. +This sample will cover an example of such optimizations and how to avoid the performance overhead from using sub-optimal layouts. + +=== xref:./{performance_samplespath}msaa/README.adoc[MSAA] + +Aliasing is the result of under-sampling a signal. +In graphics this means computing the color of a pixel at a resolution that results in artifacts, commonly jaggies at model edges. +Multisample anti-aliasing (MSAA) is an efficient technique that reduces pixel sampling error. + +=== xref:./{performance_samplespath}multithreading_render_passes/README.adoc[Multi-threaded recording with multiple render passes] + +Ideally you render all stages of your frame in a single render pass. +However, in some cases different stages can't be performed in the same render pass. +This sample shows how multi-threading can help to boost performance when using multiple render passes to render a single frame. + +=== xref:./{performance_samplespath}pipeline_barriers/README.adoc[Pipeline barriers] + +Vulkan gives the application significant control over memory access for resources. +Pipeline barriers are particularly convenient for synchronizing memory accesses between render passes. +Having barriers is required whenever there is a memory dependency - the application should not assume that render passes are executed in order. +However, having too many or too strict barriers can affect the application's performance. +This sample will cover how to set up pipeline barriers efficiently, with a focus on pipeline stages. + +=== xref:./{performance_samplespath}pipeline_cache/README.adoc[Pipeline cache] + +Vulkan gives applications the ability to save internal representation of a pipeline (graphics or compute) to enable recreating the same pipeline later. +This sample will look in detail at the implementation and performance implications of the pipeline creation, caching and management. + +=== xref:./{performance_samplespath}render_passes/README.adoc[Render passes] + +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`). +This sample lets you choose between different combinations of these operations at runtime. + +=== xref:./{performance_samplespath}specialization_constants/README.adoc[Specialization constants] + +Vulkan exposes a number of methods for setting values within shader code during run-time, this includes UBOs and Specialization Constants. +This sample compares these two methods and the performance impact of them. + +=== xref:./{performance_samplespath}subpasses/README.adoc[Sub passes] + +Vulkan introduces the concept of _subpasses_ to subdivide a single xref:./{performance_samplespath}render_passes/README.adoc[render pass] into separate logical phases. +The benefit of using subpasses over multiple render passes is that a GPU is able to perform various optimizations. +Tile-based renderers, for example, can take advantage of tile memory, which being on chip is decisively faster than external memory, potentially saving a considerable amount of bandwidth. + +=== xref:./{performance_samplespath}surface_rotation/README.adoc[Surface rotation] + +Mobile devices can be rotated, therefore the logical orientation of the application window and the physical orientation of the display may not match. +Applications then need to be able to operate in two modes: portrait and landscape. +The difference between these two modes can be simplified to just a change in resolution. +However, some display subsystems always work on the "native" (or "physical") orientation of the display panel. +Since the device has been rotated, to achieve the desired effect the application output must also rotate. +In this sample we focus on the rotation step, and analyze the performance implications of implementing it correctly with Vulkan. + +=== xref:./{performance_samplespath}swapchain_images/README.adoc[Swapchain images] + +Vulkan gives the application some significant control over the number of swapchain images to be created. +This sample analyzes the available options and their performance implications. + +=== xref:./{performance_samplespath}wait_idle/README.adoc[Wait idle] + +This sample compares two methods for synchronizing between the CPU and GPU, `WaitIdle` and `Fences` demonstrating which one is the best option in order to avoid stalling. + +=== xref:./{performance_samplespath}16bit_storage_input_output/README.adoc[16-bit storage InputOutput] + +This sample compares bandwidth consumption when using FP32 varyings compared to using FP16 varyings with `VK_KHR_16bit_storage`. + +=== xref:./{performance_samplespath}16bit_arithmetic/README.adoc[16-bit arithmetic] + +This sample compares arithmetic throughput for 32-bit arithmetic operations and 16-bit arithmetic. +The sample also shows how to enable 16-bit storage for SSBOs and push constants. + +=== xref:./{performance_samplespath}async_compute/README.adoc[Async compute] + +This sample demonstrates using multiple Vulkan queues to get better hardware utilization with compute post-processing workloads. + +=== xref:./{performance_samplespath}texture_compression_basisu/README.adoc[Basis Universal supercompressed GPU textures] + +This sample demonstrates how to use Basis universal supercompressed GPU textures in a Vulkan application. + +=== xref:./{performance_samplespath}multi_draw_indirect/README.adoc[GPU Rendering and Multi-Draw Indirect] + +This sample demonstrates how to reduce CPU usage by offloading draw call generation and frustum culling to the GPU. + +=== xref:./{performance_samplespath}texture_compression_comparison/README.adoc[Texture compression comparison] + +This sample demonstrates how to use different types of compressed GPU textures in a Vulkan application, and shows the timing benefits of each. diff --git a/samples/performance/command_buffer_usage/README.adoc b/samples/performance/command_buffer_usage/README.adoc index b46997395..e3cd0e502 100644 --- a/samples/performance/command_buffer_usage/README.adoc +++ b/samples/performance/command_buffer_usage/README.adoc @@ -177,7 +177,7 @@ In this application the differences between individual reset and pool reset are == Further reading -* xref:../multithreading_render_passes/README.adoc[Multi-threaded recording with multiple render passes] +* 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/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") diff --git a/samples/performance/descriptor_management/README.adoc b/samples/performance/descriptor_management/README.adoc index 9f5e90dbe..658e4b586 100644 --- a/samples/performance/descriptor_management/README.adoc +++ b/samples/performance/descriptor_management/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -88,7 +88,7 @@ Mobile implementations may use a simpler allocator if that flag is not set, rely It is possible to avoid using that flag by updating descriptor sets instead of deleting them. The application can keep track of recycled descriptor sets and re-use one of them when a new one is requested. -The xref:../subpasses/README.adoc[subpasses sample] uses this approach when it re-creates the G-buffer images. +The xref:samples/performance/subpasses/README.adoc[subpasses sample] uses this approach when it re-creates the G-buffer images. == Buffer management diff --git a/samples/performance/hpp_pipeline_cache/README.adoc b/samples/performance/hpp_pipeline_cache/README.adoc index 4feabbca5..fff64355b 100644 --- a/samples/performance/hpp_pipeline_cache/README.adoc +++ b/samples/performance/hpp_pipeline_cache/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2023, The Khronos Group +- Copyright (c) 2022-2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -48,7 +48,7 @@ To create a graphics pipeline in Vulkan, using Vulkan-Hpp, the following objects ** Depth Stencil ** Color Blend -image::../pipeline_cache/images/graphics_pipeline_dependencies.png[Graphics Pipeline Dependencies] +image::samples/performance/pipeline_cache/images/graphics_pipeline_dependencies.png[Graphics Pipeline Dependencies] Alternatively for a compute pipeline in Vulkan, using Vulkan-Hpp, you need: @@ -57,7 +57,7 @@ Alternatively for a compute pipeline in Vulkan, using Vulkan-Hpp, you need: ** Push Constants ** Descriptor Set Layouts -image::../pipeline_cache/images/compute_pipeline_dependencies.png[Compute Pipeline Dependencies] +image::samples/performance/pipeline_cache/images/compute_pipeline_dependencies.png[Compute Pipeline Dependencies] == Vulkan Pipeline Cache @@ -101,12 +101,12 @@ ____ Below is a screenshot of the sample on a phone with Mali G76 GPU: -image::../pipeline_cache/images/pipeline_cache_enable.jpg[Pipeline Cache Enable] +image::samples/performance/pipeline_cache/images/pipeline_cache_enable.jpg[Pipeline Cache Enable] Pipeline cache is enabled and Sponza is rendered at 60 FPS when the existing pipelines are destroyed. Pipeline re-creation takes 24.4 ms thanks to the pipeline cache. -image::../pipeline_cache/images/pipeline_cache_disable.jpg[Pipeline Cache Disable] +image::samples/performance/pipeline_cache/images/pipeline_cache_disable.jpg[Pipeline Cache Disable] If we disable the pipeline cache, re-creating the pipelines takes 50.4 ms, more than double the previous time. Building pipelines dynamically without a pipeline cache can result in a sudden framerate drop. diff --git a/samples/performance/hpp_swapchain_images/README.adoc b/samples/performance/hpp_swapchain_images/README.adoc index 00c4413d4..0a857fca0 100644 --- a/samples/performance/hpp_swapchain_images/README.adoc +++ b/samples/performance/hpp_swapchain_images/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2022-2023, The Khronos Group +- Copyright (c) 2022-2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -84,13 +84,13 @@ every 16 ms), which is the only chance for an image to be presented. Double buffering works well if frames can be processed within 16 ms, so at each VSync signal the processed image is presented on screen and the previously presented one becomes available to the application again. This behavior is demonstrated in the figure below: -image::../swapchain_images/images/swapchain_double_buffering.png[Double buffering at 60 FPS] +image::samples/performance/swapchain_images/images/swapchain_double_buffering.png[Double buffering at 60 FPS] This behavior breaks when frames take more than 16 ms to be processed. Let us suppose that a frame is ready after 20 ms. The following figure illustrates what happens in this case: -image::../swapchain_images/images/swapchain_double_buffering_slow.png[Double buffering at <60 FPS] +image::samples/performance/swapchain_images/images/swapchain_double_buffering_slow.png[Double buffering at <60 FPS] The orange dashed line highlights a point in which the whole system is idle. FB1 was not yet ready for presentation for the previous VSync signal, so the presentation engine keeps presenting FB0, which in turn cannot be used to start processing the next frame. @@ -98,7 +98,7 @@ FB1 was not yet ready for presentation for the previous VSync signal, so the pre This idling behavior caps framerate at 30 fps, while the application could achieve ~50 fps. With triple buffering there will always be an image already processed and ready for presentation, so the GPU can start processing a new image without stalling. -image::../swapchain_images/images/swapchain_triple_buffering.png[Triple buffering at 60 FPS] +image::samples/performance/swapchain_images/images/swapchain_triple_buffering.png[Triple buffering at 60 FPS] == The sample @@ -106,12 +106,12 @@ The `hpp_swapchain_images` Vulkan sample highlights this behavior, by allowing t This is a screenshot of the sample on a phone with a Mali G72 GPU: -image::../swapchain_images/images/sponza_triple_buffering.jpg[Sponza with triple buffering] +image::samples/performance/swapchain_images/images/sponza_triple_buffering.jpg[Sponza with triple buffering] Triple buffering is enabled and Sponza is comfortably rendered at 60 FPS. When we switch to double buffering the framerate drops to 30 FPS: -image::../swapchain_images/images/sponza_double_buffering.jpg[Sponza with double buffering] +image::samples/performance/swapchain_images/images/sponza_double_buffering.jpg[Sponza with double buffering] In this case the actual CPU and GPU frame time is close to 16 ms, so it is possible that the framerate remains at 60 FPS for a few seconds even after switching to double buffering. Thermal effects or other running processes may cause a small increase in frame time, resulting in the app missing VSync. @@ -121,7 +121,7 @@ In order for an application to achieve its potential framerate without being VSy We can confirm this behavior using https://developer.arm.com/products/software-development-tools/arm-development-studio/components/streamline-performance-analyzer[Streamline Performance Analyzer]. -image::../swapchain_images/images/streamline_swapchain_marker.png[Streamline analysis] +image::samples/performance/swapchain_images/images/streamline_swapchain_marker.png[Streamline analysis] The first part of the trace until the marker is with triple buffering. As we can see the CPU and GPU show a good utilization, with not much idling between frames. diff --git a/samples/performance/layout_transitions/README.adoc b/samples/performance/layout_transitions/README.adoc index b88f8fc7a..26bed09c5 100644 --- a/samples/performance/layout_transitions/README.adoc +++ b/samples/performance/layout_transitions/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -70,7 +70,7 @@ The `vkCmdBlitImage()` framebuffer transfer stage operation will also always inv The sample sets up deferred rendering using two render passes, to show the effect of transitioning G-buffer images from `UNDEFINED` rather than their last known layout. Note that a deferred rendering implementation using subpasses might be more efficient overall; -see xref:../subpasses/README.adoc[the subpasses tutorial] for more detail. +see xref:samples/performance/subpasses/README.adoc[the subpasses tutorial] for more detail. The base case is with all color images being transitioned from `UNDEFINED`, as shown in the image below. diff --git a/samples/performance/msaa/README.adoc b/samples/performance/msaa/README.adoc index e683798fb..3a87ec8d1 100644 --- a/samples/performance/msaa/README.adoc +++ b/samples/performance/msaa/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2021-2023, Arm Limited and Contributors +- Copyright (c) 2021-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -53,7 +53,7 @@ Irregular patterns achieve https://pdfs.semanticscholar.org/ebd9/ddb08c4244fc7df Note that MSAA has no effect for pixels within the primitive, where all samples store the same color value. MSAA is different from (and more efficient than) super-sampling anti-aliasing (SSAA) where the fragment shader is evaluated for each sample. -This would help reduce aliasing within primitives, but usually xref:../../api/texture_mipmap_generation/README.adoc[mip-maps] mitigate this already. +This would help reduce aliasing within primitives, but usually xref:samples/api/texture_mipmap_generation/README.adoc[mip-maps] mitigate this already. To enable MSAA, first query http://khronos.org/registry/vulkan/specs/1.2-khr-extensions/html/chap32.html#VkPhysicalDeviceLimits[`vkPhysicalDeviceLimits`] to select a supported level of MSAA e.g. http://khronos.org/registry/vulkan/specs/1.2-khr-extensions/html/chap32.html#VkSampleCountFlagBits[`VK_SAMPLE_COUNT_4_BIT`], and use this when creating the multisampled attachment, as well as when setting the http://khronos.org/registry/vulkan/specs/1.2-khr-extensions/html/chap24.html#VkPipelineMultisampleStateCreateInfo[`rasterizationSamples`] member of http://khronos.org/registry/vulkan/specs/1.2-khr-extensions/html/chap9.html#VkGraphicsPipelineCreateInfo[`pMultisampleState`] in the graphics pipeline. diff --git a/samples/performance/multithreading_render_passes/README.adoc b/samples/performance/multithreading_render_passes/README.adoc index 27e95ccf5..c9b226cf8 100644 --- a/samples/performance/multithreading_render_passes/README.adoc +++ b/samples/performance/multithreading_render_passes/README.adoc @@ -98,7 +98,7 @@ And indeed, in debug build, which was used for profiling, frame time is decrease == Further reading -xref:../command_buffer_usage/README.adoc[Command buffer usage and multi-threaded recording] +xref:samples/performance/command_buffer_usage/README.adoc[Command buffer usage and multi-threaded recording] == Best practice summary diff --git a/samples/performance/pipeline_barriers/README.adoc b/samples/performance/pipeline_barriers/README.adoc index a8c6f09d8..347f2a505 100644 --- a/samples/performance/pipeline_barriers/README.adoc +++ b/samples/performance/pipeline_barriers/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -102,7 +102,7 @@ The app is fragment-bound, which allows the GPU to fully utilize pipelining. The sample sets up deferred rendering with two render passes and uses pipeline barriers to synchronize them. Note that a deferred rendering implementation using subpasses might be more efficient overall; -see xref:../subpasses/README.adoc[the subpasses tutorial] for more detail. +see xref:samples/performance/subpasses/README.adoc[the subpasses tutorial] for more detail. The base case is with the most conservative barrier (`BOTTOM_OF_PIPE_BIT` → `TOP_OF_PIPE_BIT`). As the graphs show, vertex and fragment work are serialized, as they never happen at the same time. diff --git a/samples/performance/render_passes/README.adoc b/samples/performance/render_passes/README.adoc index a57d11310..c8408e9dd 100644 --- a/samples/performance/render_passes/README.adoc +++ b/samples/performance/render_passes/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -75,7 +75,7 @@ image::./images/clear_store.jpg[Using LOAD_OP_CLEAR] We can estimate the bandwidth cost of loading/storing an uncompressed attachment as `width * height * bpp/8 * FPS [MiB/s]`. We calculate an estimate of `2220 * 1080 * (32/8) * ~60 = ~575 MiB/s`. -The savings will be lower if the images are compressed, see xref:../afbc/README.adoc[Enabling AFBC in your Vulkan Application]. +The savings will be lower if the images are compressed, see xref:samples/performance/afbc/README.adoc[Enabling AFBC in your Vulkan Application]. == Depth attachment store operation diff --git a/samples/performance/subpasses/README.adoc b/samples/performance/subpasses/README.adoc index a957bdec1..e6ee3cf9c 100644 --- a/samples/performance/subpasses/README.adoc +++ b/samples/performance/subpasses/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2019-2023, Arm Limited and Contributors +- Copyright (c) 2019-2024, Arm Limited and Contributors - - SPDX-License-Identifier: Apache-2.0 - @@ -25,7 +25,7 @@ endif::[] == Overview -Vulkan introduces the concept of _subpasses_ to subdivide a single xref:../render_passes/README.adoc[render pass] into separate logical phases. +Vulkan introduces the concept of _subpasses_ to subdivide a single xref:samples/performance/render_passes/README.adoc[render pass] into separate logical phases. The benefit of using subpasses over multiple render passes is that a GPU is able to perform various optimizations. Tile-based renderers, for example, can take advantage of tile memory, which being on chip is decisively faster than external memory, potentially saving a considerable amount of bandwidth. @@ -151,7 +151,7 @@ As you can see in the above screenshot, we see roughly a double in fragment jobs * Keep your G-buffer budget for color small. * Use `DEPTH_STENCIL_READ_ONLY` image layout for depth after the geometry pass is done. * Use `LAZILY_ALLOCATED` memory to back images for every attachment except for the light buffer, which is the only texture written out to memory. -* Follow the basic xref:../render_passes/README.adoc[render pass best practices], with `LOAD_OP_CLEAR` or `LOAD_OP_DONT_CARE` for attachment loads and `STORE_OP_DONT_CARE` for transient stores. +* Follow the basic xref:samples/performance/render_passes/README.adoc[render pass best practices], with `LOAD_OP_CLEAR` or `LOAD_OP_DONT_CARE` for attachment loads and `STORE_OP_DONT_CARE` for transient stores. *Don't* diff --git a/samples/tooling/README.adoc b/samples/tooling/README.adoc index 272808b5c..c47a8baaa 100644 --- a/samples/tooling/README.adoc +++ b/samples/tooling/README.adoc @@ -1,5 +1,5 @@ //// -- Copyright (c) 2023, The Khronos Group +- Copyright (c) 2023-2024, The Khronos Group - - SPDX-License-Identifier: Apache-2.0 - @@ -16,9 +16,13 @@ - limitations under the License. - //// -= Tooling samples +ifndef::tooling_samplespath[:tooling_samplespath:] -The goal of these samples is to demonstrate how to use tooling features that are not directly part of Vulkan, but e.g. -provided by the LunarG Vulkan SDK. +== Tooling Samples -A list of all tooling samples can be found link:../README.adoc#tooling-samples[here]. +The goal of these samples is to demonstrate usage of tooling functions and libraries that are not directly part of the api. + +=== xref:./{tooling_samplespath}profiles/README.adoc[Profiles Library] + +Use the https://github.com/KhronosGroup/Vulkan-Profiles[Vulkan Profiles library] to simplify instance and device setup. +The library defines a common baseline of features, extensions, etc.