Add VK_KHR_pipeline_binary sample

antora/modules/ROOT/nav.adoc

@@ -77,6 +77,7 @@
 ** xref:samples/extensions/open_cl_interop/README.adoc[OpenCL interop]
 ** xref:samples/extensions/open_cl_interop_arm/README.adoc[OpenCL interop (Arm)]
 ** xref:samples/extensions/open_gl_interop/README.adoc[OpenGL interop]
+** xref:samples/extensions/pipeline_binary/README.adoc[Pipeline Binary]
 ** xref:samples/extensions/portability/README.adoc[Portability]
 ** xref:samples/extensions/push_descriptors/README.adoc[Push descriptors]
 *** xref:samples/extensions/hpp_push_descriptors/README.adoc[Push descriptors (Vulkan-Hpp)]

framework/vulkan_type_mapping.h

@@ -295,6 +295,12 @@ struct HPPType<VkSampler>
 {
 	using Type = vk::Sampler;
 };
+
+template <>
+struct HPPType<VkPhysicalDevicePipelineBinaryFeaturesKHR>
+{
+	using Type = vk::PhysicalDevicePipelineBinaryFeaturesKHR;
+};
 }        // namespace detail
 
 template <vkb::BindingType bindingType, typename T>

samples/extensions/README.adoc

@@ -1,5 +1,5 @@
 ////
-- Copyright (c) 2021-2024, The Khronos Group
+- Copyright (c) 2021-2025, The Khronos Group
 -
 - SPDX-License-Identifier: Apache-2.0
 -
@@ -233,6 +233,10 @@ Demonstrate how to use logical operations dynamically, which can reduce the numb
 
 === xref:./{extension_samplespath}patch_control_points/README.adoc[Patch control points]
 
+*Extension*: https://docs.vulkan.org/spec/latest/appendices/extensions.html#VK_KHR_pipeline_binary[`VK_KHR_pipeline_binaries`]
+
+Demonstrate how to use pipeline binaries which provides a method to obtain binary data associated with individual pipelines such that applications can manage caching themselves instead of using VkPipelineCache objects.
+
 *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.

samples/extensions/pipeline_binary/CMakeLists.txt

@@ -0,0 +1,29 @@
+# Copyright (c) 2025, Holochip Inc
+#
+# 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.
+#
+
+get_filename_component(FOLDER_NAME ${CMAKE_CURRENT_LIST_DIR} NAME)
+get_filename_component(PARENT_DIR ${CMAKE_CURRENT_LIST_DIR} PATH)
+get_filename_component(CATEGORY_NAME ${PARENT_DIR} NAME)
+
+add_sample_with_tags(
+        ID ${FOLDER_NAME}
+        CATEGORY ${CATEGORY_NAME}
+        AUTHOR "Holochip"
+        NAME "Pipeline binary"
+        DESCRIPTION "Demonstrates VK_KHR_pipeline_binary: querying keys and capturing pipeline binaries."
+        SHADER_FILES_GLSL
+            "pipeline_binary/glsl/binary_demo.comp")

samples/extensions/pipeline_binary/README.adoc

@@ -0,0 +1,78 @@
+////
+- Copyright (c) 2025, Holochip Inc.
+-
+- 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.
+-
+////
+= Pipeline binary (VK_KHR_pipeline_binary)
+:description: Demonstrates querying a pipeline key and capturing a pipeline binary.
+
+== Overview
+VK_KHR_pipeline_binary lets you explicitly capture and reuse driver-produced pipeline binaries. Instead of relying only on opaque pipeline caches, you can:
+
+- Compute a portable pipeline key up front for a given set of creation parameters.
+- Ask the driver to give you an implementation-specific binary for that key.
+- Persist that binary and reuse it on the same driver/device to avoid runtime compilation hitches.
+
+This sample builds a tiny compute pipeline solely to demonstrate that flow. It logs support, queries a key, and (if available) captures the binary data.
+
+== Why and when to use it
+Pipeline caches are useful, but they are intentionally opaque and not keyed by a structure you can compute deterministically. Pipeline binaries add:
+
+- Deterministic cache management (you can compute the key before creating a pipeline).
+- Cross-process or install-time pre-warming strategies.
+- A clear, explicit handle (VkPipelineBinaryKHR) you can store and manage.
+
+They complement other techniques:
+
+- VK_EXT_graphics_pipeline_library reduces link-time work, but doesn’t hand you the final binary for persistence.
+- VK_EXT_shader_object changes the binding model, not binary persistence.
+
+== How it works (TL;DR)
+. Prepare the same creation info you’d pass to vkCreate*Pipelines (compute or graphics).
+. Wrap it in VkPipelineCreateInfoKHR.
+. vkGetPipelineKeyKHR(device, &VkPipelineCreateInfoKHR, &VkPipelineBinaryKeyKHR) → portable key.
+. vkCreatePipelineBinariesKHR(device, &VkPipelineBinaryCreateInfoKHR, …) → VkPipelineBinaryKHR handle.
+. vkGetPipelineBinaryDataKHR(device, &VkPipelineBinaryDataInfoKHR, …) → query size, then fetch bytes.
+. Store bytes together with device/vendor/driver identifiers and the key.
+
+== Required Vulkan extensions and features
+To use feature chaining like the other samples, this sample enables the following and requests the needed feature explicitly:
+
+- Instance: `VK_KHR_get_physical_device_properties2` — required by the framework to chain extension feature structs during device creation.
+- Device: `VK_KHR_pipeline_binary` — the extension demonstrated here.
+- Device: `VK_KHR_maintenance5` — defines the `VkPipelineCreateFlags2` flag space that includes CAPTURE_DATA (not required for this sample’s path, but commonly expected by validation).
+- Device: `VK_KHR_dynamic_rendering`, `VK_KHR_depth_stencil_resolve`, `VK_KHR_create_renderpass2` — commonly used by the framework/WSI paths; enabled to avoid spurious present-time validation issues.
+
+Note: This sample uses the `pPipelineCreateInfo` path when creating pipeline binaries, so it does not require creating a live pipeline with `CAPTURE_DATA` set.
+
+== Walkthrough of the code
+- log_pipeline_binary_support() uses vkGetPhysicalDeviceFeatures2/properties2 to show what the driver supports and prefers regarding internal caches and compression.
+- demo_pipeline_key_and_binary():
+  * Reuses the cached compute pipeline creation info and wraps it in VkPipelineCreateInfoKHR.
+  * Calls vkGetPipelineKeyKHR to compute the key.
+  * Calls vkCreatePipelineBinariesKHR with pPipelineCreateInfo set (and pipeline/pKeysAndDataInfo null) to get a VkPipelineBinaryKHR.
+  * Calls vkGetPipelineBinaryDataKHR twice to first query size, then fetch bytes (requires a valid VkPipelineBinaryKeyKHR pointer on both calls).
+
+== Best practices and caveats
+- Treat captured binaries as opaque and device/driver-specific; don’t assume portability across vendors or driver revisions.
+- Record identity metadata (vendor ID, device ID, driver version, pipeline key) so you can invalidate stale entries.
+- Some drivers may prefer or enforce internal caches; honor properties like pipelineBinaryPrefersInternalCache.
+- Not all implementations will return data; some may return zero bytes. Handle that gracefully.
+- Any change in creation parameters changes the key and the resulting binary.
+
+== References
+- Vulkan specification and Khronos Registry entries for VK_KHR_pipeline_binary
+- Related samples: graphics_pipeline_library, pipeline_cache