From 9507a7dba5878a400aa3885840d77e8c27a58a1e Mon Sep 17 00:00:00 2001 From: swinston Date: Tue, 15 Jul 2025 10:37:51 -0700 Subject: [PATCH 1/8] add Vulkan Profiles chapter and include it in navigation. --- antora/modules/ROOT/nav.adoc | 1 + chapters/vulkan_profiles.adoc | 481 ++++++++++++++++++++++++++++++++++ 2 files changed, 482 insertions(+) create mode 100644 chapters/vulkan_profiles.adoc diff --git a/antora/modules/ROOT/nav.adoc b/antora/modules/ROOT/nav.adoc index ddfb192..84c5896 100644 --- a/antora/modules/ROOT/nav.adoc +++ b/antora/modules/ROOT/nav.adoc @@ -11,6 +11,7 @@ ** xref:{chapters}platforms.adoc[] ** xref:{chapters}checking_for_support.adoc[] ** xref:{chapters}versions.adoc[] +** xref:{chapters}vulkan_profiles.adoc[] ** xref:{chapters}vulkan_release_summary.adoc[] ** xref:{chapters}what_is_spirv.adoc[] ** xref:{chapters}portability_initiative.adoc[] diff --git a/chapters/vulkan_profiles.adoc b/chapters/vulkan_profiles.adoc new file mode 100644 index 0000000..5c3b63f --- /dev/null +++ b/chapters/vulkan_profiles.adoc @@ -0,0 +1,481 @@ +// Copyright 2025 Holochip, Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +// Required for both single-page and combined guide xrefs to work +ifndef::chapters[:chapters:] +ifndef::images[:images: images/] + +[[vulkan-profiles]] += Vulkan Profiles + +Vulkan Profiles is a mechanism that allows developers to target a specific set of features, extensions, and limits that are guaranteed to be supported by a range of Vulkan implementations. This is particularly useful for cross-platform development where you want to ensure your application works consistently across different devices. + +For detailed information, refer to the link:https://docs.vulkan.org/spec/latest/appendices/profiles.html[Vulkan Profiles] section in the Vulkan Specification. + +== What are Vulkan Profiles? + +A Vulkan Profile is a well-defined set of capabilities, (features, extensions, formats, queue families, etc.) that can be used as a baseline for application development. Profiles are defined in JSON format and can be used to: + +* Simplify development by providing a known set of capabilities +* Ensure compatibility across a range of devices +* Reduce the need for complex capability checking and fallback code +* Provide a clear target for both developers and hardware vendors + +The Khronos Group maintains a set of official profiles, and vendors can also define their own profiles for their specific hardware. + +=== History and Purpose + +Vulkan Profiles were introduced to address the challenge of fragmentation in the Vulkan ecosystem. With many different devices supporting various combinations of features and extensions, developers faced difficulties in: + +* Determining which features to target for maximum device compatibility +* Managing fallback paths for devices with limited capabilities +* Communicating requirements clearly to hardware vendors + +Profiles solve these problems by providing a standardized way to define and reference sets of Vulkan capabilities. They serve as a contract between application developers and hardware vendors, ensuring that devices claiming support for a profile will provide all the capabilities defined in that profile. + +=== Relationship with Vulkan Versions + +Vulkan Profiles are complementary to Vulkan versions. While Vulkan versions (1.0, 1.1, 1.2, etc.) define the core API functionality, profiles define specific subsets of features, extensions, and limits that may span across different Vulkan versions. + +For example: + +* The Android Baseline 2022 profile requires Vulkan 1.1 core functionality +* The Baseline 2022 profile for desktop platforms requires Vulkan 1.1 with specific extensions +* Future profiles may target newer Vulkan versions as they become more widely supported + +This approach allows developers to target specific capability sets without being tied to a particular Vulkan version, providing more flexibility in application development. + +== Official Profiles + +The Khronos Group maintains several official profiles, which are defined in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles[Vulkan-Profiles repository]: + +* *Baseline 2022* - A baseline profile for desktop platforms (link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_KHR_BASELINE_2022[Specification], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_BASELINE_2022.json[JSON Definition]) +* *Android Baseline 2022* - A baseline profile specifically for Android devices (link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_ANDROID_BASELINE_2022[Specification], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_BASELINE_2022.json[JSON Definition]) +* *Roadmap 2022* - A forward-looking profile that hardware vendors are encouraged to support in future implementations (link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_KHR_ROADMAP_2022[Specification], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_ROADMAP_2022.json[JSON Definition]) + +These profiles are versioned by year to allow for evolution over time while maintaining backward compatibility. You can find sample code demonstrating the use of these profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples repository]. + +=== Baseline 2022 Profile Details + +The Baseline 2022 profile (`VP_KHR_BASELINE_2022`) is designed for desktop platforms and includes: + +* Core Vulkan 1.1 functionality +* Key extensions such as: +** `VK_KHR_maintenance1`, `VK_KHR_maintenance2`, `VK_KHR_maintenance3` +** `VK_KHR_create_renderpass2` +** `VK_KHR_image_format_list` +** `VK_KHR_sampler_mirror_clamp_to_edge` +* Specific feature requirements include: +** `robustBufferAccess` +** `fullDrawIndexUint32` +** `imageCubeArray` +** `independentBlend` +** And many more core features + +This profile ensures that applications focusing on it will work consistently across a wide range of desktop GPUs from different vendors. + +=== Android Baseline 2022 Profile Details + +The Android Baseline 2022 profile (`VP_ANDROID_BASELINE_2022`) is tailored specifically for Android devices and includes: + +* Core Vulkan 1.1 functionality +* Android-specific extensions such as: +** `VK_KHR_android_surface` +** `VK_ANDROID_external_memory_android_hardware_buffer` +* Common rendering extensions: +** `VK_KHR_swapchain` +** `VK_KHR_maintenance1`, `VK_KHR_maintenance2`, `VK_KHR_maintenance3` +** `VK_KHR_dedicated_allocation` +* Mobile-optimized limits and features + +This profile is particularly valuable for Android game developers who want to ensure their applications run on a wide range of Android devices without having to implement complex device-specific code paths. + +=== Roadmap 2022 Profile + +The Roadmap 2022 profile (`VP_KHR_ROADMAP_2022`) is a forward-looking profile that defines capabilities that hardware vendors are encouraged to support in future implementations. It includes: + +* More advanced features and extensions beyond the baseline profiles +* Higher minimum limits for various resources +* Support for newer Vulkan functionality + +By targeting this profile, developers can prepare their applications for future hardware capabilities while still maintaining compatibility with current devices through fallback mechanisms. + +=== Profile Versioning Strategy + +Profiles use a year-based versioning scheme (e.g., 2022, 2023) to indicate when they were defined. This approach: + +* Provides clear temporal context for each profile +* Allows for the creation of new profiles that reflect evolving hardware capabilities +* Maintains backward compatibility, as older profiles remain valid even as new ones are introduced + +When a new yearly profile is released, it typically includes all the capabilities of the previous year's profile plus additional features and possibly higher limits, reflecting the advancement of hardware capabilities. + +== Using Vulkan Profiles + +There are two main ways to use Vulkan Profiles: + +=== 1. Using the Vulkan Profiles header + +The simplest way to use Vulkan Profiles is through the Vulkan Profiles header (`vulkan_profiles.hpp`), which is available in the link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK]. This header provides a C++ API that simplifies working with profiles. The header is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/README.md[Vulkan-Profiles library documentation]: + +[source,cpp] +---- +#include +#include + +// Create a profile instance for the Android baseline profile +vkp::AndroidBaseline2022Profile profile; + +// Check if the profile is supported on this device +VkBool32 supported = VK_FALSE; +profile.CheckSupport(physicalDevice, &supported); +if (supported) { + // The device supports the Android baseline profile + // Use the profile to create a device + VkDeviceCreateInfo deviceCreateInfo = {}; + profile.ConfigureDeviceCreation(physicalDevice, deviceCreateInfo); + + // Create the device with the profile-configured create info + VkDevice device; + vkCreateDevice(physicalDevice, &deviceCreateInfo, nullptr, &device); +} +---- + +=== 2. Using the Vulkan Profiles, JSON files directly + +For more advanced use cases, you can work with the JSON profile definitions directly. The JSON schema is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles schema documentation]. You can find example code that loads and uses JSON profiles in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/library/test[Vulkan-Profiles test directory]: + +[source,cpp] +---- +// Load a profile from a JSON file +VkpProfilesFileLoader loader; +loader.LoadFromFile("android_baseline_2022.json"); + +// Get the profile +VkpProfile profile = loader.GetProfile("VP_ANDROID_BASELINE_2022"); + +// Use the profile to check support and create a device +// (similar to the header-based approach) +---- + +=== Understanding Profile JSON Structure + +Vulkan Profiles are defined in JSON format with a specific structure. Understanding this structure is important for developers who want to create custom profiles or modify existing ones. The full JSON schema is defined in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/profiles-schema.json[profiles-schema.json] file and documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[schema documentation]. Here's a simplified example of a profile JSON structure: + +[source,json] +---- +{ + "file_format_version": "1.0.0", + "profiles": { + "VP_EXAMPLE_PROFILE": { + "version": 1, + "api_version": "1.1.0", + "label": "Example Profile", + "description": "A simple example profile", + "capabilities": [ + { + "extensions": { + "VK_KHR_swapchain": 1, + "VK_KHR_maintenance1": 1 + }, + "features": { + "VkPhysicalDeviceFeatures": { + "robustBufferAccess": true, + "fullDrawIndexUint32": true + } + }, + "properties": { + "VkPhysicalDeviceProperties": { + "limits": { + "maxImageDimension2D": 4096, + "maxFramebufferWidth": 4096 + } + } + }, + "formats": { + "VK_FORMAT_R8G8B8A8_UNORM": { + "VkFormatProperties": { + "linearTilingFeatures": [ + "VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT" + ], + "optimalTilingFeatures": [ + "VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT", + "VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT" + ] + } + } + } + } + ] + } + } +} +---- + +The key parts of a profile definition include: + +* *Profile Metadata*: Name, version, API version, label, and description +* *Capabilities*: The core of the profile, defining what the profile supports + * *Extensions*: Required extensions and their minimum versions + * *Features*: Required features that must be supported + * *Properties*: Required properties and limits + * *Formats*: Required format support with specific capabilities + +=== Creating Custom Profiles + +Developers can create custom profiles to target specific hardware configurations or to define a baseline for their own applications. The process is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/CUSTOM_PROFILES.md[Creating Custom Profiles] guide. To create a custom profile: + +1. Start with an existing profile as a template (see link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles[official profiles]) +2. Modify the capabilities to match your requirements +3. Save the profile as a JSON file +4. Use the profile in your application using either the header-based or JSON-based approach + +You can find examples of custom profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples]. + +Custom profiles are particularly useful for: + +* Internal development teams working on multiple applications +* Defining minimum requirements for specific application categories +* Creating hardware-specific optimized profiles + +Example of creating and using a custom profile: + +[source,cpp] +---- +// Define a custom profile (typically done offline and saved to a JSON file) +std::string customProfileJson = R"( +{ + "file_format_version": "1.0.0", + "profiles": { + "VP_CUSTOM_GAME_PROFILE": { + "version": 1, + "api_version": "1.1.0", + "label": "Custom Game Profile", + "description": "Profile for our game engine", + "capabilities": [ + // ... custom capabilities ... + ] + } + } +} +)"; + +// Load the custom profile +VkpProfilesFileLoader loader; +loader.LoadFromString(customProfileJson); + +// Use the custom profile +VkpProfile profile = loader.GetProfile("VP_CUSTOM_GAME_PROFILE"); +// ... use the profile as before ... +---- + +== Android Baseline Profile + +The Android Baseline Profile is particularly useful for Android developers as it provides a guaranteed set of features that are available on a wide range of Android devices. This profile is documented in the link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_ANDROID_BASELINE_2022[Vulkan Specification] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_BASELINE_2022.json[JSON definition]. This profile includes: + +* Core Vulkan 1.1 functionality +* Essential extensions for Android development +* Minimum guaranteed limits and features + +For Android-specific examples, see the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples] and the link:https://developer.android.com/ndk/guides/graphics/vulkan-profiles[Android NDK documentation on Vulkan Profiles]. + +By targeting the Android Baseline Profile, developers can: + +* Reduce the need for device-specific code paths +* Ensure consistent behavior across different Android devices +* Simplify testing and validation + +=== Example: Targeting Android Baseline Profile + +[source,cpp] +---- +#include +#include + +void SetupVulkanWithAndroidProfile() { + // Create a Vulkan instance + vk::InstanceCreateInfo instanceCreateInfo; + vk::Instance instance = vk::createInstance(instanceCreateInfo); + + // Get a physical device + vk::PhysicalDevice physicalDevice = instance.enumeratePhysicalDevices().front(); + + // Create a profile instance for the Android baseline profile + vkp::AndroidBaseline2022Profile profile; + + // Check if the profile is supported + VkBool32 supported = VK_FALSE; + profile.CheckSupport(physicalDevice, &supported); + + if (supported) { + // Configure device creation with the profile + vk::DeviceCreateInfo deviceCreateInfo; + profile.ConfigureDeviceCreation(physicalDevice, deviceCreateInfo); + + // Create the device + vk::Device device = physicalDevice.createDevice(deviceCreateInfo); + + // Now you can use the device with the guaranteed set of features + // defined in the Android Baseline Profile + } else { + // Handle the case where the profile is not supported + // This might involve falling back to a simpler rendering approach + // or showing an error message + } +} +---- + +== Integration with Existing Applications + +Integrating Vulkan Profiles into an existing Vulkan application involves several steps, which are described in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/README.md#integrating-with-existing-applications[Vulkan-Profiles library documentation]: + +1. *Identify Target Profiles*: Determine which profiles best match your application's requirements +2. *Add Profile Support*: Incorporate the Vulkan Profiles header or JSON handling +3. *Modify Device Creation*: Update your device creation code to use profiles +4. *Add Fallback Paths*: Implement fallback strategies for devices that don't support your target profile + +For examples of integrating profiles with existing applications, see the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/library/test[Vulkan-Profiles test directory]. + +Here's an example of integrating profiles into an existing application: + +[source,cpp] +---- +// Original device creation code +void CreateDeviceOriginal(VkPhysicalDevice physicalDevice) { + // Query for features, extensions, etc. + VkPhysicalDeviceFeatures features; + vkGetPhysicalDeviceFeatures(physicalDevice, &features); + + // Set up device creation info manually + VkDeviceCreateInfo createInfo = {}; + createInfo.sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO; + createInfo.pEnabledFeatures = &features; + // ... set up extensions, queues, etc. ... + + // Create the device + VkDevice device; + vkCreateDevice(physicalDevice, &createInfo, nullptr, &device); +} + +// Updated device creation code using profiles +void CreateDeviceWithProfiles(VkPhysicalDevice physicalDevice) { + // Try to use the Baseline 2022 profile + vkp::Baseline2022Profile profile; + + VkBool32 supported = VK_FALSE; + profile.CheckSupport(physicalDevice, &supported); + + if (supported) { + // Profile is supported, use it to configure device creation + VkDeviceCreateInfo createInfo = {}; + createInfo.sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO; + + profile.ConfigureDeviceCreation(physicalDevice, createInfo); + + // Create the device with profile-configured settings + VkDevice device; + vkCreateDevice(physicalDevice, &createInfo, nullptr, &device); + } else { + // Fall back to original method if profile is not supported + CreateDeviceOriginal(physicalDevice); + } +} +---- + +== Performance Considerations + +Using Vulkan Profiles has minimal runtime performance impact, but there are some considerations to keep in mind: + +1. *Initialization Overhead*: Loading and parsing profile JSON files adds some initialization time +2. *Memory Usage*: The profile data structures consume a small amount of memory +3. *Feature Enabling*: Enabling features you don't need might have a slight performance impact on some implementations + +To optimize performance when using profiles: + +* Use the header-based approach for better compile-time optimization +* Create custom profiles that only include the features you actually need +* Consider using different profiles for different hardware tiers + +== Troubleshooting and Common Issues + +When working with Vulkan Profiles, developers might encounter several common issues. The link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/README.md#troubleshooting[Vulkan-Profiles library documentation] provides guidance on troubleshooting, and the link:https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/khronos_validation_layer.md[Vulkan Validation Layers documentation] can help identify issues with profile usage: + +=== Profile Isn't Supported + +If `CheckSupport()` returns `VK_FALSE`, it means the device doesn't support all the requirements of the profile. To troubleshoot: + +1. Use the profile's `GetProfileCapabilitiesReport()` function to get detailed information about which specific requirements are not met +2. Consider using a less demanding profile +3. Implement a fallback path for devices that don't support your target profile + +Example: + +[source,cpp] +---- +VkBool32 supported = VK_FALSE; +profile.CheckSupport(physicalDevice, &supported); + +if (!supported) { + // Get detailed report on what's not supported + VkpProfileCapabilitiesReport report; + profile.GetProfileCapabilitiesReport(physicalDevice, report); + + // Log the unsupported capabilities + for (const auto& unsupported : report.unsupportedCapabilities) { + LogWarning("Unsupported: " + unsupported); + } + + // Fall back to a different profile or custom configuration +} +---- + +=== Version Compatibility Issues + +When using profiles across different Vulkan SDK versions, you might encounter compatibility issues. To avoid these: + +* Always use the profile definitions from the same SDK version as your Vulkan headers +* Be aware that profile definitions might evolve between SDK releases +* Consider bundling the profile JSON files with your application to ensure consistency + +=== Integration with Validation Layers + +Vulkan Profiles work well with validation layers, but there are some considerations: + +* Enable the `VK_LAYER_KHRONOS_validation` layer during development +* Be aware that some validation warnings might be triggered for profile-enabled features that you're not explicitly using +* Use debug callbacks to filter validation messages if necessary + +== Benefits of Using Vulkan Profiles + +Using Vulkan Profiles offers several advantages: + +1. *Simplified Development* + - Reduces the complexity of checking for individual features and extensions +2. *Better Compatibility* + - Ensures your application works consistently across different devices +3. *Future-Proofing* + - Profiles evolve in a controlled manner, making it easier to adapt to new hardware +4. *Clear Communication* + - Provides a common language for developers and hardware vendors to discuss capabilities +5. *Reduced Testing Burden* + - Fewer device-specific code paths means less testing required +6. *Standardized Capabilities* + - Provides a well-defined baseline that hardware vendors can target +7. *Easier Porting* + - Simplifies the process of porting applications between different platforms + +== Conclusion + +Vulkan Profiles provide a powerful mechanism for targeting a consistent set of Vulkan capabilities across different devices. By using profiles, particularly the Android Baseline Profile for mobile development, developers can simplify their code, ensure better compatibility, and reduce the need for device-specific workarounds. + +The profile system continues to evolve, with new profiles being defined to address emerging hardware capabilities and developer needs. By understanding how to effectively use profiles, create custom profiles, and integrate them into your applications, you can significantly streamline your Vulkan development process. + +For more information, refer to these resources: + +* link:https://docs.vulkan.org/spec/latest/appendices/profiles.html[Vulkan Profiles in the Vulkan Specification] +* link:https://github.com/KhronosGroup/Vulkan-Profiles[Vulkan-Profiles repository] + - Contains profile definitions, library code, and tools +* link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples] + - Sample code demonstrating profile usage +* link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Vulkan SDK Profiles API Library documentation] +* link:https://developer.android.com/ndk/guides/graphics/vulkan-profiles[Android NDK documentation on Vulkan Profiles] - For Android-specific guidance From e7ce08c58c8c80c3f46f095277363e63ecff93ab Mon Sep 17 00:00:00 2001 From: swinston Date: Tue, 15 Jul 2025 11:11:31 -0700 Subject: [PATCH 2/8] add Python chapter reference checker to CI and update chapter navigation for consistency. Or the less professional way to say it: I'm lazy and know how to use python. --- .github/scripts/check_chapter_references.py | 332 ++++++++++++++++++++ .github/workflows/CI.yml | 12 + README.adoc | 3 + guide.adoc | 116 +++++++ 4 files changed, 463 insertions(+) create mode 100755 .github/scripts/check_chapter_references.py diff --git a/.github/scripts/check_chapter_references.py b/.github/scripts/check_chapter_references.py new file mode 100755 index 0000000..f375a18 --- /dev/null +++ b/.github/scripts/check_chapter_references.py @@ -0,0 +1,332 @@ +#!/usr/bin/env python3 +# Copyright 2025 Holochip, Inc. +# SPDX-License-Identifier: Apache-2.0 + +""" +Script to ensure that all chapter files are properly referenced in the Guide +This script scans the chapters directory to identify all chapter files and checks if they are properly +referenced in the three files. If a chapter is missing from any of the files, the script can add it +to the appropriate section. +""" + +import os +import re +import sys +from pathlib import Path + +# Paths to the files that need to be checked +README_PATH = "README.adoc" +GUIDE_PATH = "guide.adoc" +NAV_PATH = "antora/modules/ROOT/nav.adoc" + +# Directories to scan for chapter files +CHAPTERS_DIR = "chapters" +EXTENSIONS_DIR = os.path.join(CHAPTERS_DIR, "extensions") + +def get_all_chapter_files(): + """ + Scan the chapters directory and its subdirectories to find all .adoc files. + Returns a dictionary with relative paths as keys and file info as values. + """ + chapter_files = {} + + # Scan main chapters directory + for file in os.listdir(CHAPTERS_DIR): + if file.endswith(".adoc") and os.path.isfile(os.path.join(CHAPTERS_DIR, file)): + rel_path = os.path.join(CHAPTERS_DIR, file) + chapter_files[rel_path] = { + "name": file, + "path": rel_path, + "is_extension": False + } + + # Scan extensions directory + if os.path.exists(EXTENSIONS_DIR): + for file in os.listdir(EXTENSIONS_DIR): + if file.endswith(".adoc") and os.path.isfile(os.path.join(EXTENSIONS_DIR, file)): + rel_path = os.path.join(EXTENSIONS_DIR, file) + chapter_files[rel_path] = { + "name": file, + "path": rel_path, + "is_extension": True + } + + return chapter_files + +def extract_title_from_chapter(file_path): + """ + Extract the title from a chapter file. + Returns the title or the filename if no title is found. + """ + try: + with open(file_path, 'r', encoding='utf-8') as f: + content = f.read() + + # Look for a title pattern like "= Title" or "== Title" + title_match = re.search(r'^=+\s+(.+?)$', content, re.MULTILINE) + if title_match: + return title_match.group(1).strip() + + # If no title found, use the filename without extension + return os.path.splitext(os.path.basename(file_path))[0] + except Exception as e: + print(f"Error reading {file_path}: {e}") + return os.path.splitext(os.path.basename(file_path))[0] + +def check_readme_references(chapter_files): + """ + Check if all chapter files are referenced in README.adoc. + Returns a list of files that are not referenced. + """ + try: + with open(README_PATH, 'r', encoding='utf-8') as f: + readme_content = f.read() + + missing_files = [] + for file_path, info in chapter_files.items(): + # Convert path to the format used in README.adoc + rel_path = file_path.replace(CHAPTERS_DIR + "/", "") + + # Check if the file is referenced in README.adoc + if not re.search(rf'xref:\{{chapters\}}{re.escape(rel_path)}', readme_content): + missing_files.append(info) + + return missing_files + except Exception as e: + print(f"Error checking README.adoc: {e}") + return list(chapter_files.values()) + +def check_guide_references(chapter_files): + """ + Check if all chapter files are referenced in guide.adoc. + Returns a list of files that are not referenced. + """ + try: + with open(GUIDE_PATH, 'r', encoding='utf-8') as f: + guide_content = f.read() + + missing_files = [] + for file_path, info in chapter_files.items(): + # Convert path to the format used in guide.adoc + rel_path = file_path.replace(CHAPTERS_DIR + "/", "") + + # Check if the file is referenced in guide.adoc + # The pattern needs to match both include:{chapters}file.adoc[] and include::{chapters}file.adoc[] + if not (re.search(rf'include:\{{chapters\}}{re.escape(rel_path)}', guide_content) or + re.search(rf'include::\{{chapters\}}{re.escape(rel_path)}', guide_content)): + missing_files.append(info) + + return missing_files + except Exception as e: + print(f"Error checking guide.adoc: {e}") + return list(chapter_files.values()) + +def check_nav_references(chapter_files): + """ + Check if all chapter files are referenced in nav.adoc. + Returns a list of files that are not referenced. + """ + try: + with open(NAV_PATH, 'r', encoding='utf-8') as f: + nav_content = f.read() + + missing_files = [] + for file_path, info in chapter_files.items(): + # Convert path to the format used in nav.adoc + rel_path = file_path.replace(CHAPTERS_DIR + "/", "") + + # Check if the file is referenced in nav.adoc + if not re.search(rf'xref:\{{chapters\}}{re.escape(rel_path)}', nav_content): + missing_files.append(info) + + return missing_files + except Exception as e: + print(f"Error checking nav.adoc: {e}") + return list(chapter_files.values()) + +def update_readme(missing_files): + """ + Update README.adoc to include missing chapter references. + Returns True if the file was updated, False otherwise. + """ + if not missing_files: + return False + + try: + with open(README_PATH, 'r', encoding='utf-8') as f: + content = f.readlines() + + # Find appropriate sections to add the missing files + extensions_section_idx = None + main_section_idx = None + + for i, line in enumerate(content): + if "= When and Why to use Extensions" in line: + extensions_section_idx = i + elif "= Using Vulkan" in line: + main_section_idx = i + + if extensions_section_idx is None or main_section_idx is None: + print("Could not find appropriate sections in README.adoc") + return False + + # Add missing files to appropriate sections + for file_info in missing_files: + title = extract_title_from_chapter(file_info["path"]) + rel_path = file_info["path"].replace(CHAPTERS_DIR + "/", "") + + if file_info["is_extension"]: + # Add to extensions section + content.insert(extensions_section_idx + 2, f"== xref:{{chapters}}{rel_path}[{title}]\n\n") + extensions_section_idx += 2 # Adjust index for next insertion + else: + # Add to main section + content.insert(main_section_idx + 2, f"== xref:{{chapters}}{rel_path}[{title}]\n\n") + main_section_idx += 2 # Adjust index for next insertion + + # Write updated content back to file + with open(README_PATH, 'w', encoding='utf-8') as f: + f.writelines(content) + + return True + except Exception as e: + print(f"Error updating README.adoc: {e}") + return False + +def update_guide(missing_files): + """ + Update guide.adoc to include missing chapter references. + Returns True if the file was updated, False otherwise. + """ + if not missing_files: + return False + + try: + with open(GUIDE_PATH, 'r', encoding='utf-8') as f: + content = f.readlines() + + # Find appropriate sections to add the missing files + extensions_section_idx = None + main_section_idx = None + + for i, line in enumerate(content): + if "= When and Why to use Extensions" in line: + extensions_section_idx = i + elif "= Using Vulkan" in line: + main_section_idx = i + + if extensions_section_idx is None or main_section_idx is None: + print("Could not find appropriate sections in guide.adoc") + return False + + # Add missing files to appropriate sections + for file_info in missing_files: + rel_path = file_info["path"].replace(CHAPTERS_DIR + "/", "") + + if file_info["is_extension"]: + # Add to extensions section + content.insert(extensions_section_idx + 2, f"include::{{chapters}}{rel_path}[]\n\n") + extensions_section_idx += 2 # Adjust index for next insertion + else: + # Add to main section + content.insert(main_section_idx + 2, f"include::{{chapters}}{rel_path}[]\n\n") + main_section_idx += 2 # Adjust index for next insertion + + # Write updated content back to file + with open(GUIDE_PATH, 'w', encoding='utf-8') as f: + f.writelines(content) + + return True + except Exception as e: + print(f"Error updating guide.adoc: {e}") + return False + +def update_nav(missing_files): + """ + Update nav.adoc to include missing chapter references. + Returns True if the file was updated, False otherwise. + """ + if not missing_files: + return False + + try: + with open(NAV_PATH, 'r', encoding='utf-8') as f: + content = f.readlines() + + # Find appropriate sections to add the missing files + extensions_section_idx = None + main_section_idx = None + + for i, line in enumerate(content): + if "* When and Why to use Extensions" in line: + extensions_section_idx = i + elif "* Using Vulkan" in line: + main_section_idx = i + + if extensions_section_idx is None or main_section_idx is None: + print("Could not find appropriate sections in nav.adoc") + return False + + # Add missing files to appropriate sections + for file_info in missing_files: + rel_path = file_info["path"].replace(CHAPTERS_DIR + "/", "") + + if file_info["is_extension"]: + # Add to extensions section + content.insert(extensions_section_idx + 1, f"** xref:{{chapters}}{rel_path}[]\n") + extensions_section_idx += 1 # Adjust index for next insertion + else: + # Add to main section + content.insert(main_section_idx + 1, f"** xref:{{chapters}}{rel_path}[]\n") + main_section_idx += 1 # Adjust index for next insertion + + # Write updated content back to file + with open(NAV_PATH, 'w', encoding='utf-8') as f: + f.writelines(content) + + return True + except Exception as e: + print(f"Error updating nav.adoc: {e}") + return False + +def main(): + """ + Main function to check and update chapter references. + """ + print("Checking chapter references...") + + # Get all chapter files + chapter_files = get_all_chapter_files() + print(f"Found {len(chapter_files)} chapter files") + + # Check if all chapter files are referenced in the three files + readme_missing = check_readme_references(chapter_files) + guide_missing = check_guide_references(chapter_files) + nav_missing = check_nav_references(chapter_files) + + print(f"Missing from README.adoc: {len(readme_missing)}") + print(f"Missing from guide.adoc: {len(guide_missing)}") + print(f"Missing from nav.adoc: {len(nav_missing)}") + + # Update files if needed + readme_updated = update_readme(readme_missing) + guide_updated = update_guide(guide_missing) + nav_updated = update_nav(nav_missing) + + if readme_updated: + print("Updated README.adoc") + if guide_updated: + print("Updated guide.adoc") + if nav_updated: + print("Updated nav.adoc") + + # Return non-zero exit code if any files were missing references + if readme_missing or guide_missing or nav_missing: + print("Some chapter files were missing references and have been added.") + return 1 + else: + print("All chapter files are properly referenced.") + return 0 + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index b8d2f59..55573db 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -24,6 +24,18 @@ jobs: with: ruby-version: '3.0' + # Set up Python for chapter reference checker + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + # Run chapter reference checker + - name: Check chapter references + run: | + chmod +x .github/scripts/check_chapter_references.py + python .github/scripts/check_chapter_references.py + # Run awesome_bot checker # Apparently this has trouble parsing one wiki link with () in it, so added to whitelist # need request-delay or will get 429 errors for sites such as GitHub diff --git a/README.adoc b/README.adoc index d683bf1..e930172 100644 --- a/README.adoc +++ b/README.adoc @@ -64,8 +64,11 @@ The Vulkan Guide can be built as a single page using `asciidoctor guide.adoc` = Using Vulkan +== xref:{chapters}vulkan_profiles.adoc[Vulkan Profiles] + == xref:{chapters}loader.adoc[Loader] + == xref:{chapters}layers.adoc[Layers] == xref:{chapters}querying_extensions_features.adoc[Querying Properties, Extensions, Features, Limits, and Formats] diff --git a/guide.adoc b/guide.adoc index 8416a1c..36d46c4 100644 --- a/guide.adoc +++ b/guide.adoc @@ -60,58 +60,174 @@ include::{chapters}decoder_ring.adoc[] = Using Vulkan +include::{chapters}descriptor_arrays.adoc[] + include::{chapters}loader.adoc[] +include::{chapters}swapchain_semaphore_reuse.adoc[] + +include::{chapters}buffer_device_address.adoc[] include::{chapters}layers.adoc[] +include::{chapters}push_constants.adoc[] + + +include::{chapters}checking_for_support.adoc[] include::{chapters}querying_extensions_features.adoc[] +include::{chapters}loader.adoc[] + +include::{chapters}vulkan_release_summary.adoc[] include::{chapters}enabling_extensions.adoc[] +include::{chapters}portability_initiative.adoc[] + +include::{chapters}validation_overview.adoc[] include::{chapters}enabling_features.adoc[] +include::{chapters}mapping_data_to_shaders.adoc[] + +include::{chapters}vulkan_spec.adoc[] include::{chapters}spirv_extensions.adoc[] +include::{chapters}depth.adoc[] +include::{chapters}decoder_ring.adoc[] + +include::{chapters}formats.adoc[] include::{chapters}formats.adoc[] +include::{chapters}vulkan_cts.adoc[] + include::{chapters}queues.adoc[] +include::{chapters}hlsl.adoc[] + +include::{chapters}atomics.adoc[] include::{chapters}wsi.adoc[] +include::{chapters}enabling_features.adoc[] + +include::{chapters}dynamic_state.adoc[] include::{chapters}pnext_and_stype.adoc[] +include::{chapters}sparse_resources.adoc[] + +include::{chapters}vertex_input_data_processing.adoc[] include::{chapters}synchronization.adoc[] +include::{chapters}queues.adoc[] + +include::{chapters}enabling_extensions.adoc[] // Switch imagesdir for chapters/extensions/ includes so they can also load as single pages, +include::{chapters}image_copies.adoc[] + // then switch it back again +include::{chapters}shader_memory_layout.adoc[] + // :imagesdir: chapters/images/extensions +include::{chapters}threading.adoc[] + // :images: images/ +include::{chapters}common_pitfalls.adoc[] + +include::{chapters}vulkan_profiles.adoc[] include::{chapters}extensions/VK_KHR_synchronization2.adoc[] +include::{chapters}protected.adoc[] + +include::{chapters}descriptor_dynamic_offset.adoc[] +include::{chapters}synchronization_examples.adoc[] include::{chapters}synchronization_examples.adoc[] +include::{chapters}pipeline_cache.adoc[] + include::{chapters}swapchain_semaphore_reuse.adoc[] +include::{chapters}querying_extensions_features.adoc[] :imagesdir: chapters +include::{chapters}ways_to_provide_spirv.adoc[] + +include::{chapters}primitive_topology.adoc[] + +include::{chapters}memory_allocation.adoc[] +include::{chapters}dynamic_state_map.adoc[] include::{chapters}memory_allocation.adoc[] include::{chapters}sparse_resources.adoc[] +include::{chapters}development_tools.adoc[] + +include::{chapters}wsi.adoc[] include::{chapters}protected.adoc[] +include::{chapters}robustness.adoc[] + +include::{chapters}spirv_extensions.adoc[] include::{chapters}buffer_device_address.adoc[] +include::{chapters}pnext_and_stype.adoc[] + +include::{chapters}platforms.adoc[] include::{chapters}pipeline_cache.adoc[] +include::{chapters}what_is_vulkan.adoc[] + +include::{chapters}extensions/VK_KHR_image_format_list.adoc[] + +include::{chapters}extensions/translation_layer_extensions.adoc[] + +include::{chapters}location_component_interface.adoc[] + +include::{chapters}extensions/VK_KHR_synchronization2.adoc[] include::{chapters}threading.adoc[] +include::{chapters}extensions/ray_tracing.adoc[] + +include::{chapters}what_is_spirv.adoc[] + +include::{chapters}extensions/VK_KHR_draw_indirect_count.adoc[] + +include::{chapters}extensions/external.adoc[] + +include::{chapters}layers.adoc[] + +include::{chapters}extensions/VK_KHR_debug_utils.adoc[] include::{chapters}depth.adoc[] +include::{chapters}extensions/VK_KHR_sampler_ycbcr_conversion.adoc[] + +include::{chapters}versions.adoc[] + +include::{chapters}extensions/VK_EXT_inline_uniform_block.adoc[] + +include::{chapters}extensions/VK_KHR_descriptor_update_template.adoc[] + +include::{chapters}high_level_shader_language_comparison.adoc[] + +include::{chapters}extensions/VK_KHR_imageless_framebuffer.adoc[] include::{chapters}primitive_topology.adoc[] +include::{chapters}extensions/VK_KHR_shader_subgroup_uniform_control_flow.adoc[] + +include::{chapters}storage_image_and_texel_buffers.adoc[] + +include::{chapters}extensions/VK_EXT_descriptor_indexing.adoc[] + +include::{chapters}extensions/device_groups.adoc[] + +include::{chapters}synchronization.adoc[] + +include::{chapters}extensions/shader_features.adoc[] include::{chapters}mapping_data_to_shaders.adoc[] +include::{chapters}extensions/VK_EXT_memory_priority.adoc[] + +include::{chapters}what_vulkan_can_do.adoc[] + +include::{chapters}extensions/cleanup.adoc[] + +include::{chapters}subgroups.adoc[] include::{chapters}storage_image_and_texel_buffers.adoc[] From dc65d0b3aab175be88368b805d325a39a3d741bc Mon Sep 17 00:00:00 2001 From: swinston Date: Wed, 16 Jul 2025 11:19:50 -0700 Subject: [PATCH 3/8] update Vulkan Profiles chapter with expanded details on profiles, updated links, and improved examples. --- chapters/vulkan_profiles.adoc | 72 ++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 26 deletions(-) diff --git a/chapters/vulkan_profiles.adoc b/chapters/vulkan_profiles.adoc index 5c3b63f..fdc433e 100644 --- a/chapters/vulkan_profiles.adoc +++ b/chapters/vulkan_profiles.adoc @@ -10,7 +10,7 @@ ifndef::images[:images: images/] Vulkan Profiles is a mechanism that allows developers to target a specific set of features, extensions, and limits that are guaranteed to be supported by a range of Vulkan implementations. This is particularly useful for cross-platform development where you want to ensure your application works consistently across different devices. -For detailed information, refer to the link:https://docs.vulkan.org/spec/latest/appendices/profiles.html[Vulkan Profiles] section in the Vulkan Specification. +For detailed information, refer to the link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Vulkan Profiles API Library] documentation on LunarG's website. == What are Vulkan Profiles? @@ -21,7 +21,10 @@ A Vulkan Profile is a well-defined set of capabilities, (features, extensions, f * Reduce the need for complex capability checking and fallback code * Provide a clear target for both developers and hardware vendors -The Khronos Group maintains a set of official profiles, and vendors can also define their own profiles for their specific hardware. +The Khronos Group maintains a set of official profiles, and vendors can also +define their own profiles for their specific hardware. Additionally, Vulkan +application developers can create profiles to specify engine code paths, like + Unreal Engine does. Or libraries such as Zink can specify their Vulkan requirements for OpenGL to run, enabling hardware vendors to prioritize their driver development to support specific code paths on engines or libraries. === History and Purpose @@ -31,7 +34,7 @@ Vulkan Profiles were introduced to address the challenge of fragmentation in the * Managing fallback paths for devices with limited capabilities * Communicating requirements clearly to hardware vendors -Profiles solve these problems by providing a standardized way to define and reference sets of Vulkan capabilities. They serve as a contract between application developers and hardware vendors, ensuring that devices claiming support for a profile will provide all the capabilities defined in that profile. +Profiles solve these problems by providing a convention to define and reference sets of Vulkan capabilities. They serve as a contract between application developers and hardware vendors, ensuring that devices claiming support for a profile will provide all the capabilities defined in that profile. === Relationship with Vulkan Versions @@ -40,24 +43,31 @@ Vulkan Profiles are complementary to Vulkan versions. While Vulkan versions (1.0 For example: * The Android Baseline 2022 profile requires Vulkan 1.1 core functionality -* The Baseline 2022 profile for desktop platforms requires Vulkan 1.1 with specific extensions +* The LunarG Desktop Baseline 2022 profile for desktop platforms requires Vulkan 1.1 with specific extensions * Future profiles may target newer Vulkan versions as they become more widely supported This approach allows developers to target specific capability sets without being tied to a particular Vulkan version, providing more flexibility in application development. == Official Profiles -The Khronos Group maintains several official profiles, which are defined in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles[Vulkan-Profiles repository]: +The Khronos Group maintains several profiles, which are defined in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles[Vulkan-Profiles repository]. The only official profiles are the Khronos Roadmap profiles and the Android Baseline profile. The others are maintained by Google and LunarG: -* *Baseline 2022* - A baseline profile for desktop platforms (link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_KHR_BASELINE_2022[Specification], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_BASELINE_2022.json[JSON Definition]) -* *Android Baseline 2022* - A baseline profile specifically for Android devices (link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_ANDROID_BASELINE_2022[Specification], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_BASELINE_2022.json[JSON Definition]) -* *Roadmap 2022* - A forward-looking profile that hardware vendors are encouraged to support in future implementations (link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_KHR_ROADMAP_2022[Specification], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_ROADMAP_2022.json[JSON Definition]) +* *LunarG Desktop Baseline 2022* - A baseline profile for desktop platforms +(link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_LUNARG_desktop_baseline_2022[JSON Definitions]) +* *Android Baseline 2022* - A baseline profile specifically for Android devices (link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_baseline_2022.json[JSON Definition]) +* *Roadmap 2022* - A forward-looking profile that hardware vendors are encouraged to support in future implementations (link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_roadmap_2022.json[JSON Definition]) -These profiles are versioned by year to allow for evolution over time while maintaining backward compatibility. You can find sample code demonstrating the use of these profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples repository]. +These profiles are versioned by year to allow for evolution over time while maintaining backward compatibility. You can find sample code demonstrating the use of these profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples repository]. -=== Baseline 2022 Profile Details +=== LunarG Desktop Baseline 2022 Profile Details -The Baseline 2022 profile (`VP_KHR_BASELINE_2022`) is designed for desktop platforms and includes: +The LunarG Desktop Baseline 2022 profile (`VP_LUNARG_DESKTOP_BASELINE_2022`) is designed for desktop platforms. It's described as "A profile generated by the intersection of a collection of GPUInfo.org device reports to support a large number of actual systems in the Vulkan ecosystem. This profile is meant to be a usage example for Vulkan application developers." + +The real purpose of the LunarG Desktop Baseline profiles is to provide examples to Vulkan application developers to create profiles for their applications. It's important to note that these profiles have some limitations - for example, Windows ARM / Qualcomm GPUs are not supported because these GPUs were not released or just released when the profiles were generated. + +If LunarG were to create a Desktop Baseline 2025 in the future, it would likely include Windows ARM / Qualcomm GPUs, which would make the Desktop Baseline 2025 both a subset and superset (likely Vulkan 1.3) of the Desktop Baseline 2024. + +The profile includes: * Core Vulkan 1.1 functionality * Key extensions such as: @@ -116,7 +126,7 @@ There are two main ways to use Vulkan Profiles: === 1. Using the Vulkan Profiles header -The simplest way to use Vulkan Profiles is through the Vulkan Profiles header (`vulkan_profiles.hpp`), which is available in the link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK]. This header provides a C++ API that simplifies working with profiles. The header is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/README.md[Vulkan-Profiles library documentation]: +The simplest way to use Vulkan Profiles is through the Vulkan Profiles header (`vulkan_profiles.hpp`), which is available in the link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK]. This header provides a C++ API that simplifies working with profiles. The header is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main[Vulkan-Profiles library documentation]: [source,cpp] ---- @@ -143,7 +153,11 @@ if (supported) { === 2. Using the Vulkan Profiles, JSON files directly -For more advanced use cases, you can work with the JSON profile definitions directly. The JSON schema is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles schema documentation]. You can find example code that loads and uses JSON profiles in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/library/test[Vulkan-Profiles test directory]: +For more advanced use cases, you can work with the JSON profile definitions +directly. The JSON schema is documented in the link:https://github +.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles +schema documentation]. You can find example code that loads and uses JSON +profiles in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/layer/TUTORIAL.md[Vulkan-Profiles]: [source,cpp] ---- @@ -160,7 +174,7 @@ VkpProfile profile = loader.GetProfile("VP_ANDROID_BASELINE_2022"); === Understanding Profile JSON Structure -Vulkan Profiles are defined in JSON format with a specific structure. Understanding this structure is important for developers who want to create custom profiles or modify existing ones. The full JSON schema is defined in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/profiles-schema.json[profiles-schema.json] file and documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[schema documentation]. Here's a simplified example of a profile JSON structure: +Vulkan Profiles are defined in JSON format with a specific structure. Understanding this structure is important for developers who want to create custom profiles or modify existing ones. Here's a simplified example of a profile JSON structure: [source,json] ---- @@ -223,14 +237,23 @@ The key parts of a profile definition include: === Creating Custom Profiles -Developers can create custom profiles to target specific hardware configurations or to define a baseline for their own applications. The process is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/CUSTOM_PROFILES.md[Creating Custom Profiles] guide. To create a custom profile: +Developers can create custom profiles to target specific hardware configurations or to define a baseline for their own applications. To create a custom profile: + +There are two main use cases that define the starting point: + +1. Creating a "Platform" profile - a profile that represents all the devices you want your Vulkan application to run on. Here, the starting point would be to use data from https://vulkan.gpuinfo.org/ when merging device capabilities. +2. Creating an "Engine" profile - a profile that lists all the requirements for your Vulkan application to run. In this case, modifying an existing profile is often the best approach. + +Both approaches work together to ensure a Vulkan application can ship reliably. + +To create a custom profile: -1. Start with an existing profile as a template (see link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles[official profiles]) +1. Start with an appropriate existing profile as a template (see link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles[profiles]) 2. Modify the capabilities to match your requirements 3. Save the profile as a JSON file 4. Use the profile in your application using either the header-based or JSON-based approach -You can find examples of custom profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples]. +You can find examples of custom profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples profiles examples]. Custom profiles are particularly useful for: @@ -271,13 +294,12 @@ VkpProfile profile = loader.GetProfile("VP_CUSTOM_GAME_PROFILE"); == Android Baseline Profile -The Android Baseline Profile is particularly useful for Android developers as it provides a guaranteed set of features that are available on a wide range of Android devices. This profile is documented in the link:https://docs.vulkan.org/spec/latest/appendices/profiles.html#profile-VP_ANDROID_BASELINE_2022[Vulkan Specification] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_BASELINE_2022.json[JSON definition]. This profile includes: +The Android Baseline Profile is particularly useful for Android developers as it provides a guaranteed set of features that are available on a wide range of Android devices. This profile is documented in the link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Vulkan Profiles API Library documentation] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_baseline_2022.json[JSON definition]. This profile includes: * Core Vulkan 1.1 functionality * Essential extensions for Android development * Minimum guaranteed limits and features -For Android-specific examples, see the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples] and the link:https://developer.android.com/ndk/guides/graphics/vulkan-profiles[Android NDK documentation on Vulkan Profiles]. By targeting the Android Baseline Profile, developers can: @@ -334,7 +356,7 @@ Integrating Vulkan Profiles into an existing Vulkan application involves several 3. *Modify Device Creation*: Update your device creation code to use profiles 4. *Add Fallback Paths*: Implement fallback strategies for devices that don't support your target profile -For examples of integrating profiles with existing applications, see the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/library/test[Vulkan-Profiles test directory]. +For examples of integrating profiles with existing applications, see the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples profiles examples] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/library/test[Vulkan-Profiles test directory]. Here's an example of integrating profiles into an existing application: @@ -359,8 +381,8 @@ void CreateDeviceOriginal(VkPhysicalDevice physicalDevice) { // Updated device creation code using profiles void CreateDeviceWithProfiles(VkPhysicalDevice physicalDevice) { - // Try to use the Baseline 2022 profile - vkp::Baseline2022Profile profile; + // Try to use the LunarG Desktop Baseline 2022 profile + vkp::LunargDesktopBaseline2022Profile profile; VkBool32 supported = VK_FALSE; profile.CheckSupport(physicalDevice, &supported); @@ -472,10 +494,8 @@ The profile system continues to evolve, with new profiles being defined to addre For more information, refer to these resources: -* link:https://docs.vulkan.org/spec/latest/appendices/profiles.html[Vulkan Profiles in the Vulkan Specification] +* link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Vulkan Profiles API Library documentation] * link:https://github.com/KhronosGroup/Vulkan-Profiles[Vulkan-Profiles repository] - Contains profile definitions, library code, and tools -* link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/api/profiles[Vulkan-Samples profiles examples] +* link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples profiles examples] - Sample code demonstrating profile usage -* link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Vulkan SDK Profiles API Library documentation] -* link:https://developer.android.com/ndk/guides/graphics/vulkan-profiles[Android NDK documentation on Vulkan Profiles] - For Android-specific guidance From f54c74cb2ba95ff9692f01701ee7f7aae1d7cf57 Mon Sep 17 00:00:00 2001 From: swinston Date: Wed, 16 Jul 2025 11:51:00 -0700 Subject: [PATCH 4/8] expand Vulkan Profiles chapter with clarification on backward compatibility and enhanced initialization guidance. --- chapters/vulkan_profiles.adoc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/chapters/vulkan_profiles.adoc b/chapters/vulkan_profiles.adoc index fdc433e..6f8b795 100644 --- a/chapters/vulkan_profiles.adoc +++ b/chapters/vulkan_profiles.adoc @@ -116,13 +116,16 @@ Profiles use a year-based versioning scheme (e.g., 2022, 2023) to indicate when * Provides clear temporal context for each profile * Allows for the creation of new profiles that reflect evolving hardware capabilities -* Maintains backward compatibility, as older profiles remain valid even as new ones are introduced +* Maintains backward compatibility, as older profiles remain valid even as +new ones are introduced. This is a feature of the design of the profiles, +yet sometimes, there are rare instances where the older profiles are updated +due to newly released hardware. When a new yearly profile is released, it typically includes all the capabilities of the previous year's profile plus additional features and possibly higher limits, reflecting the advancement of hardware capabilities. == Using Vulkan Profiles -There are two main ways to use Vulkan Profiles: +There are two main ways to use Vulkan Profiles to initialize a Vulkan application: === 1. Using the Vulkan Profiles header From c00b99c0eddbb839191cefd62fd2094939770cb0 Mon Sep 17 00:00:00 2001 From: swinston Date: Wed, 16 Jul 2025 12:11:28 -0700 Subject: [PATCH 5/8] update Vulkan Profiles chapter with latest documentation links. --- chapters/vulkan_profiles.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/chapters/vulkan_profiles.adoc b/chapters/vulkan_profiles.adoc index 6f8b795..35cf763 100644 --- a/chapters/vulkan_profiles.adoc +++ b/chapters/vulkan_profiles.adoc @@ -10,7 +10,7 @@ ifndef::images[:images: images/] Vulkan Profiles is a mechanism that allows developers to target a specific set of features, extensions, and limits that are guaranteed to be supported by a range of Vulkan implementations. This is particularly useful for cross-platform development where you want to ensure your application works consistently across different devices. -For detailed information, refer to the link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Vulkan Profiles API Library] documentation on LunarG's website. +For detailed information, refer to the link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Vulkan Profiles API Library] documentation on LunarG's website. == What are Vulkan Profiles? @@ -54,8 +54,8 @@ The Khronos Group maintains several profiles, which are defined in the link:http * *LunarG Desktop Baseline 2022* - A baseline profile for desktop platforms (link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_LUNARG_desktop_baseline_2022[JSON Definitions]) -* *Android Baseline 2022* - A baseline profile specifically for Android devices (link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_baseline_2022.json[JSON Definition]) -* *Roadmap 2022* - A forward-looking profile that hardware vendors are encouraged to support in future implementations (link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_roadmap_2022.json[JSON Definition]) +* *Android Baseline 2022* - A baseline profile specifically for Android devices (link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_baseline_2022.json[JSON Definition]) +* *Roadmap 2022* - A forward-looking profile that hardware vendors are encouraged to support in future implementations (link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_roadmap_2022.json[JSON Definition]) These profiles are versioned by year to allow for evolution over time while maintaining backward compatibility. You can find sample code demonstrating the use of these profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples repository]. @@ -297,7 +297,7 @@ VkpProfile profile = loader.GetProfile("VP_CUSTOM_GAME_PROFILE"); == Android Baseline Profile -The Android Baseline Profile is particularly useful for Android developers as it provides a guaranteed set of features that are available on a wide range of Android devices. This profile is documented in the link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Vulkan Profiles API Library documentation] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_baseline_2022.json[JSON definition]. This profile includes: +The Android Baseline Profile is particularly useful for Android developers as it provides a guaranteed set of features that are available on a wide range of Android devices. This profile is documented in the link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Vulkan Profiles API Library documentation] and the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_baseline_2022.json[JSON definition]. This profile includes: * Core Vulkan 1.1 functionality * Essential extensions for Android development @@ -497,7 +497,7 @@ The profile system continues to evolve, with new profiles being defined to addre For more information, refer to these resources: -* link:https://vulkan.lunarg.com/doc/sdk/1.4.321.0/windows/profiles_api_library.html[Vulkan Profiles API Library documentation] +* link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Vulkan Profiles API Library documentation] * link:https://github.com/KhronosGroup/Vulkan-Profiles[Vulkan-Profiles repository] - Contains profile definitions, library code, and tools * link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples profiles examples] From 21aef736e3e6daff625e326c865d51ff8102791e Mon Sep 17 00:00:00 2001 From: swinston Date: Wed, 16 Jul 2025 12:37:16 -0700 Subject: [PATCH 6/8] expand Vulkan Profiles chapter with updated links, new "Automatic Feature Enabling" section, roadmap revisions, and improved initialization guidance. --- chapters/checking_for_support.adoc | 2 +- chapters/vulkan_profiles.adoc | 36 ++++++++++++++++++++++-------- 2 files changed, 28 insertions(+), 10 deletions(-) diff --git a/chapters/checking_for_support.adoc b/chapters/checking_for_support.adoc index 5e531f3..c67be19 100644 --- a/chapters/checking_for_support.adoc +++ b/chapters/checking_for_support.adoc @@ -82,4 +82,4 @@ View the link:https://vulkan.lunarg.com/doc/sdk/latest/windows/via.html[SDK docu A simple way to check for Vulkan support cross platform is to create a simple "`Hello World`" Vulkan application. The `vkCreateInstance` function is used to create a Vulkan Instance and is also the shortest way to write a valid Vulkan application. -The Vulkan SDK provides a minimal link:https://vulkan.lunarg.com/doc/view/latest/windows/tutorial/html/01-init_instance.html[vkCreateInstance] example `01-init_instance.cpp` that can be used. +The Vulkan SDK provides a minimal link:https://docs.vulkan.org/tutorial/latest/03_Drawing_a_triangle/00_Setup/01_Instance.html[vkCreateInstance] example `01-init_instance.cpp` that can be used. diff --git a/chapters/vulkan_profiles.adoc b/chapters/vulkan_profiles.adoc index 35cf763..58954ea 100644 --- a/chapters/vulkan_profiles.adoc +++ b/chapters/vulkan_profiles.adoc @@ -20,6 +20,7 @@ A Vulkan Profile is a well-defined set of capabilities, (features, extensions, f * Ensure compatibility across a range of devices * Reduce the need for complex capability checking and fallback code * Provide a clear target for both developers and hardware vendors +* Automatically enable required features and extensions without manual configuration The Khronos Group maintains a set of official profiles, and vendors can also define their own profiles for their specific hardware. Additionally, Vulkan @@ -55,7 +56,9 @@ The Khronos Group maintains several profiles, which are defined in the link:http * *LunarG Desktop Baseline 2022* - A baseline profile for desktop platforms (link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_LUNARG_desktop_baseline_2022[JSON Definitions]) * *Android Baseline 2022* - A baseline profile specifically for Android devices (link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_ANDROID_baseline_2022.json[JSON Definition]) -* *Roadmap 2022* - A forward-looking profile that hardware vendors are encouraged to support in future implementations (link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Documentation], link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_KHR_roadmap_2022.json[JSON Definition]) +* *Roadmap 2024* - A forward-looking profile that hardware vendors are +encouraged to support in future implementations (link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Documentation], +link:https://docs.vulkan.org/spec/latest/appendices/roadmap.html#roadmap-2024[JSON Definition], link:https://docs.vulkan.org/spec/latest/appendices/roadmap.html[roadmap]) These profiles are versioned by year to allow for evolution over time while maintaining backward compatibility. You can find sample code demonstrating the use of these profiles in the link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples repository]. @@ -116,10 +119,7 @@ Profiles use a year-based versioning scheme (e.g., 2022, 2023) to indicate when * Provides clear temporal context for each profile * Allows for the creation of new profiles that reflect evolving hardware capabilities -* Maintains backward compatibility, as older profiles remain valid even as -new ones are introduced. This is a feature of the design of the profiles, -yet sometimes, there are rare instances where the older profiles are updated -due to newly released hardware. +* Maintains backward compatibility, as older profiles are only updated to fix shortcomings or issues. When a new yearly profile is released, it typically includes all the capabilities of the previous year's profile plus additional features and possibly higher limits, reflecting the advancement of hardware capabilities. @@ -127,6 +127,22 @@ When a new yearly profile is released, it typically includes all the capabilitie There are two main ways to use Vulkan Profiles to initialize a Vulkan application: +=== Automatic Feature Enabling + +One of the key benefits of using the Vulkan Profiles library is that it automatically handles the enabling of all required features, extensions, and properties defined in a profile. This eliminates the need to manually: + +* Track and enable each required extension +* Set up feature structures for each feature you need +* Configure property structures for specific requirements + +When you call `profile.ConfigureDeviceCreation()`, the library automatically: + +1. Populates the device creation info with all necessary extensions +2. Sets up the feature chain with all required features enabled +3. Configures any required properties + +This significantly simplifies device initialization and reduces the chance of errors from forgetting to enable specific features or extensions. + === 1. Using the Vulkan Profiles header The simplest way to use Vulkan Profiles is through the Vulkan Profiles header (`vulkan_profiles.hpp`), which is available in the link:https://vulkan.lunarg.com/sdk/home[Vulkan SDK]. This header provides a C++ API that simplifies working with profiles. The header is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main[Vulkan-Profiles library documentation]: @@ -157,8 +173,7 @@ if (supported) { === 2. Using the Vulkan Profiles, JSON files directly For more advanced use cases, you can work with the JSON profile definitions -directly. The JSON schema is documented in the link:https://github -.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles +directly. The JSON schema is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles schema documentation]. You can find example code that loads and uses JSON profiles in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/layer/TUTORIAL.md[Vulkan-Profiles]: @@ -352,7 +367,7 @@ void SetupVulkanWithAndroidProfile() { == Integration with Existing Applications -Integrating Vulkan Profiles into an existing Vulkan application involves several steps, which are described in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/README.md#integrating-with-existing-applications[Vulkan-Profiles library documentation]: +Integrating Vulkan Profiles into an existing Vulkan application involves several steps, which are described in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/TUTORIAL.md[Vulkan-Profiles library documentation]: 1. *Identify Target Profiles*: Determine which profiles best match your application's requirements 2. *Add Profile Support*: Incorporate the Vulkan Profiles header or JSON handling @@ -423,7 +438,7 @@ To optimize performance when using profiles: == Troubleshooting and Common Issues -When working with Vulkan Profiles, developers might encounter several common issues. The link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/README.md#troubleshooting[Vulkan-Profiles library documentation] provides guidance on troubleshooting, and the link:https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/khronos_validation_layer.md[Vulkan Validation Layers documentation] can help identify issues with profile usage: +When working with Vulkan Profiles, developers might encounter several common issues. The link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/library/TUTORIAL.md[Vulkan-Profiles library documentation] provides guidance on troubleshooting, and the link:https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/khronos_validation_layer.md[Vulkan Validation Layers documentation] can help identify issues with profile usage: === Profile Isn't Supported @@ -476,6 +491,7 @@ Using Vulkan Profiles offers several advantages: 1. *Simplified Development* - Reduces the complexity of checking for individual features and extensions + - *Automatically enables all required features and extensions* without manual configuration 2. *Better Compatibility* - Ensures your application works consistently across different devices 3. *Future-Proofing* @@ -488,6 +504,8 @@ Using Vulkan Profiles offers several advantages: - Provides a well-defined baseline that hardware vendors can target 7. *Easier Porting* - Simplifies the process of porting applications between different platforms +8. *Reduced Boilerplate Code* + - Eliminates the need to write extensive feature and extension enabling code == Conclusion From e7a82b6ad3f72c09874af4edf9e581831fffa671 Mon Sep 17 00:00:00 2001 From: swinston Date: Wed, 16 Jul 2025 13:00:29 -0700 Subject: [PATCH 7/8] update Vulkan Profiles chapter with simplified JSON schema reference and corrected example link. --- chapters/vulkan_profiles.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/chapters/vulkan_profiles.adoc b/chapters/vulkan_profiles.adoc index 58954ea..d7a7c1e 100644 --- a/chapters/vulkan_profiles.adoc +++ b/chapters/vulkan_profiles.adoc @@ -173,8 +173,7 @@ if (supported) { === 2. Using the Vulkan Profiles, JSON files directly For more advanced use cases, you can work with the JSON profile definitions -directly. The JSON schema is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles -schema documentation]. You can find example code that loads and uses JSON +directly. You can find example code that loads and uses JSON profiles in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/layer/TUTORIAL.md[Vulkan-Profiles]: [source,cpp] From 705d66ff1459bbc520dd05d703d2e54a1db02960 Mon Sep 17 00:00:00 2001 From: swinston Date: Fri, 18 Jul 2025 18:08:45 -0700 Subject: [PATCH 8/8] expand Vulkan Profiles chapter with new "Types of Vulkan Profiles" section, revised profile maintenance details, and additional documentation links. --- chapters/vulkan_profiles.adoc | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/chapters/vulkan_profiles.adoc b/chapters/vulkan_profiles.adoc index d7a7c1e..0547932 100644 --- a/chapters/vulkan_profiles.adoc +++ b/chapters/vulkan_profiles.adoc @@ -49,9 +49,12 @@ For example: This approach allows developers to target specific capability sets without being tied to a particular Vulkan version, providing more flexibility in application development. -== Official Profiles +== Maintained Profiles -The Khronos Group maintains several profiles, which are defined in the link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles[Vulkan-Profiles repository]. The only official profiles are the Khronos Roadmap profiles and the Android Baseline profile. The others are maintained by Google and LunarG: +The Khronos Group maintains several profiles, which are defined in the +link:https://github.com/KhronosGroup/Vulkan-Profiles/tree/main/profiles +[Vulkan-Profiles repository]. The only Khronos group maintained profiles are +the Khronos Roadmap profiles. The others are maintained by Google and LunarG: * *LunarG Desktop Baseline 2022* - A baseline profile for desktop platforms (link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_LUNARG_desktop_baseline_2022[JSON Definitions]) @@ -115,7 +118,8 @@ By targeting this profile, developers can prepare their applications for future === Profile Versioning Strategy -Profiles use a year-based versioning scheme (e.g., 2022, 2023) to indicate when they were defined. This approach: +Profiles may use a year-based versioning scheme (e.g., 2022, 2023) to indicate +when they were defined. This approach: * Provides clear temporal context for each profile * Allows for the creation of new profiles that reflect evolving hardware capabilities @@ -252,6 +256,19 @@ The key parts of a profile definition include: * *Properties*: Required properties and limits * *Formats*: Required format support with specific capabilities +=== Types of Vulkan Profiles + +Vulkan Profiles can be applied for a multitude of use cases, including: + +* *Roadmap profiles*: To express guidance on the future direction of Vulkan devices. +* *Platform profiles*: To express the Vulkan support available on different platforms. +* *Device profiles*: To express the Vulkan support of a single Vulkan driver on a Vulkan device. +* *Architecture profiles*: To express the Vulkan support of a class of GPUs. +* *Engine profiles*: To express some rendering code paths requirements of an engine. +* *Drivers bugs profiles*: To express capabilities that can't be used by an application. + +These different types of profiles allow developers to target specific hardware configurations, platforms, or use cases, ensuring compatibility and optimal performance across a wide range of scenarios. + === Creating Custom Profiles Developers can create custom profiles to target specific hardware configurations or to define a baseline for their own applications. To create a custom profile: @@ -519,3 +536,6 @@ For more information, refer to these resources: - Contains profile definitions, library code, and tools * link:https://github.com/KhronosGroup/Vulkan-Samples/tree/main/samples/tooling/profiles[Vulkan-Samples profiles examples] - Sample code demonstrating profile usage +* link:https://www.lunarg.com/wp-content/uploads/2024/02/The-Vulkan-Profiles-Tools-LunarG-Christophe-Riccio-02-01-2024.pdf[Vulkan Profiles pdf] + - LunarG's Cristophe Ricco exhaustive documentation for + Vulkan Profiles.