Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Misleading docs for Vulkan profiles

Open Beginner friendly
  • Is something wrong?
#397 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Domain
documentation

Research direction

Start with chapters/vulkan_profiles.adoc and compare the custom profile instructions with the Vulkan Profiles tutorial linked in the issue. Check the named sections for the unsupported API references and verify the correct support check function against the Vulkan Profiles documentation. Update the inaccurate instructions and references; done when the chapter describes supported workflows and APIs.

Written by the indexing model from the issue text.

Description

The Vulkan guide's chapter on Vulkan Profiles (chapters/vulkan_profiles.adoc) instructs the reader to use several non-existent API tools. I'm not sure if they are outdated or what happened, but I was pretty confused for a while.

Custom profiles:

The docs say to create a profile using a format that does not match Vulkan Profile's actual schema. It then says to "use the profile in your application using either the header-based or JSON-based approach" with the following pseudocode:

// 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 ...

VkpProfilesFileLoader, LoadFromString, VkpProfile, and GetProfile don't appear to exist in the entire Vulkan SDK other than in this doc. These would be great if they actually existed! The Vulkan Profiles tutorial describes how to generate the library with custom profiles, which is the only way I know of making custom profiles.

The same section also mentions the Vulkan Samples profile sample having examples of custom profiles, which is not true.

Support checks:

The CheckSupport function is referenced in the Automated Feature Enabling, Android Baseline Profile Example, Integration with Existing Applications, and Troubleshooting and Common Issues sections, which should be vpGetPhysicalDeviceProfileSupport.

Capabilities report:

VkpProfileCapabilitiesReport and GetProfileCapabilitiesReport are mentioned in the Troubleshooting and Common Issues section as a way to determine which requirements weren't met. This, unfortunately, doesn't seem to exist either.

Dominant language
Makefile
Stars
2.3k
Forks
198
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from KhronosGroup/Vulkan-Guide

All issues in KhronosGroup/Vulkan-Guide

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.