Skip to content

Commit 21aef73

Browse files
committed
expand Vulkan Profiles chapter with updated links, new "Automatic Feature Enabling" section, roadmap revisions, and improved initialization guidance.
1 parent c00b99c commit 21aef73

File tree

2 files changed

+28
-10
lines changed

2 files changed

+28
-10
lines changed

chapters/checking_for_support.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,4 +82,4 @@ View the link:https://vulkan.lunarg.com/doc/sdk/latest/windows/via.html[SDK docu
8282

8383
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.
8484

85-
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.
85+
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.

chapters/vulkan_profiles.adoc

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ A Vulkan Profile is a well-defined set of capabilities, (features, extensions, f
2020
* Ensure compatibility across a range of devices
2121
* Reduce the need for complex capability checking and fallback code
2222
* Provide a clear target for both developers and hardware vendors
23+
* Automatically enable required features and extensions without manual configuration
2324

2425
The Khronos Group maintains a set of official profiles, and vendors can also
2526
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
5556
* *LunarG Desktop Baseline 2022* - A baseline profile for desktop platforms
5657
(link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/profiles/VP_LUNARG_desktop_baseline_2022[JSON Definitions])
5758
* *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])
58-
* *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])
59+
* *Roadmap 2024* - A forward-looking profile that hardware vendors are
60+
encouraged to support in future implementations (link:https://vulkan.lunarg.com/doc/sdk/latest/windows/profiles_api_library.html[Documentation],
61+
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])
5962

6063
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].
6164

@@ -116,17 +119,30 @@ Profiles use a year-based versioning scheme (e.g., 2022, 2023) to indicate when
116119

117120
* Provides clear temporal context for each profile
118121
* Allows for the creation of new profiles that reflect evolving hardware capabilities
119-
* Maintains backward compatibility, as older profiles remain valid even as
120-
new ones are introduced. This is a feature of the design of the profiles,
121-
yet sometimes, there are rare instances where the older profiles are updated
122-
due to newly released hardware.
122+
* Maintains backward compatibility, as older profiles are only updated to fix shortcomings or issues.
123123

124124
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.
125125

126126
== Using Vulkan Profiles
127127

128128
There are two main ways to use Vulkan Profiles to initialize a Vulkan application:
129129

130+
=== Automatic Feature Enabling
131+
132+
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:
133+
134+
* Track and enable each required extension
135+
* Set up feature structures for each feature you need
136+
* Configure property structures for specific requirements
137+
138+
When you call `profile.ConfigureDeviceCreation()`, the library automatically:
139+
140+
1. Populates the device creation info with all necessary extensions
141+
2. Sets up the feature chain with all required features enabled
142+
3. Configures any required properties
143+
144+
This significantly simplifies device initialization and reduces the chance of errors from forgetting to enable specific features or extensions.
145+
130146
=== 1. Using the Vulkan Profiles header
131147

132148
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) {
157173
=== 2. Using the Vulkan Profiles, JSON files directly
158174

159175
For more advanced use cases, you can work with the JSON profile definitions
160-
directly. The JSON schema is documented in the link:https://github
161-
.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles
176+
directly. The JSON schema is documented in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/schema/README.md[Vulkan-Profiles
162177
schema documentation]. You can find example code that loads and uses JSON
163178
profiles in the link:https://github.com/KhronosGroup/Vulkan-Profiles/blob/main/layer/TUTORIAL.md[Vulkan-Profiles]:
164179

@@ -352,7 +367,7 @@ void SetupVulkanWithAndroidProfile() {
352367

353368
== Integration with Existing Applications
354369

355-
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]:
370+
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]:
356371

357372
1. *Identify Target Profiles*: Determine which profiles best match your application's requirements
358373
2. *Add Profile Support*: Incorporate the Vulkan Profiles header or JSON handling
@@ -423,7 +438,7 @@ To optimize performance when using profiles:
423438

424439
== Troubleshooting and Common Issues
425440

426-
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:
441+
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:
427442

428443
=== Profile Isn't Supported
429444

@@ -476,6 +491,7 @@ Using Vulkan Profiles offers several advantages:
476491

477492
1. *Simplified Development*
478493
- Reduces the complexity of checking for individual features and extensions
494+
- *Automatically enables all required features and extensions* without manual configuration
479495
2. *Better Compatibility*
480496
- Ensures your application works consistently across different devices
481497
3. *Future-Proofing*
@@ -488,6 +504,8 @@ Using Vulkan Profiles offers several advantages:
488504
- Provides a well-defined baseline that hardware vendors can target
489505
7. *Easier Porting*
490506
- Simplifies the process of porting applications between different platforms
507+
8. *Reduced Boilerplate Code*
508+
- Eliminates the need to write extensive feature and extension enabling code
491509

492510
== Conclusion
493511

0 commit comments

Comments
 (0)