Rework the readme #2358

sharadhr · 2025-11-11T22:03:26Z

No description provided.

asuessenbach · 2025-11-12T09:21:40Z

Is there a reason you want to rework the readme?

sharadhr · 2025-11-12T10:51:59Z

Hi @asuessenbach! I've been meaning to do this for a while, actually. I have a list of things that I found a little less than ideal with the current readme:

Be clear on what this repository is actually for (development of the Vulkan-Hpp generator); the actual generated headers can be downloaded from Vulkan-Headers.
More instructions on installation/usage from the Vulkan SDK, vcpkg, and Conan.
Rearranging some of the information to flow a bit better; e.g. start with basic Info structs, then move on to specific Vulkan types like Device, Image, etc
- Some of the information is a bit scattershot; e.g. there are two sections for RAII best practices; these could be combined.
- Subsume the RAII programming guide into the readme, or split the readme up altogether.
- Also group together the language-side facilities that Vulkan-Hpp uses, e.g. [[nodiscard]], std::expected, std::optional, etc
Remove/edit deprecated information, especially pertaining to vulkan.cppm
Miscellaneous grammar, capitalisation, and formatting (e.g. as demonstrated, making all the configuration options demarcated ``in backticks`` makes it easy to avoid the \_stuff in the ToC.
- Adhere to some Common Markdown best practices, e.g. spaces around lists, - instead of *, etc.
- Also, the HTML hyperlinks are no longer necessary; as far as I understand, the Common Markdown specification provides a means to automatically generate a table of contents.

If you're OK with this, I can proceed with making these changes, naturally subject to your review at the end. I hope to improve the documentation at the end of this exercise.

asuessenbach · 2025-11-12T12:45:41Z

You're more than welcome to rework the readme!
I'm pretty sure, any change will be an improvement.

- Remove HTML hyperlinks; markdown generates automatically - Use backticks \` to demarcate config macros - Remove `VULKAN_HPP_NO_STD_MODULE` option

- `-` instead of `*` - Spaces around lists

- Minor changes to main readme so that links work

- Minor changes in main readme

- Add builder pattern

sharadhr · 2025-12-15T09:33:26Z

@asuessenbach, this is still in progress (and hence in draft mode), but do feel free to have a look at the branch to see the direction I'm going in. Hopefully intend to complete this by the end of the year.

M2-TE · 2025-12-18T13:38:06Z

How about adding CMake's FetchContent to the "Installation and Usage" section?
Something akin to

include(FetchContent)
FetchContent_Declare(vulkan-hpp
    GIT_REPOSITORY "https://github.com/KhronosGroup/Vulkan-Hpp.git"
    GIT_TAG "v1.4.336" # release tag, commit hash or branch name
    GIT_SHALLOW ON)
FetchContent_MakeAvailable(vulkan-hpp)

M2-TE · 2025-12-18T13:48:23Z

For the "Build Instructions", it is likely best to separate header generation and sample/test building. At the very least, the build section should state that building is purely for those tasks and that headers can be used by just including them.

For merely using the headers (because e.g. they haven't landed in Vulkan-Headers yet), quickly showing how to link against Vulkan::Hpp in CMake would be sufficient for those users. Or showing minimal include_directories(...) usage.

sharadhr · 2025-12-18T14:19:18Z

Both good points @M2-TE. I am focusing mostly on Usage for now (since that is where I see the biggest shortfall in documentation), but I will add these in to Building when I can.

- Rework flow; start with vulkan fundamentals - Move things around - Adhere to 1 sentence, 1 line

- Added TODOs for review - Added section on `std::expected`

- Reformat type traits and vkformat traits lists as tables

sharadhr · 2026-01-16T22:49:53Z

I'm much happier about the Usage document; probably a few final updates left for the last few sections. At this point, I'd like to ask you guys, @M2-TE and @asuessenbach to review what has been done; I have a lot of TODOs that you might want to search for and comment on. I suggest reading the document in a proper, top-down manner to ensure it flows correctly. I'd also love to note any missing features that have been recently added.

After that, I intend to work on migrating the RAII guide to Handles.md, and finally revise the building and installation sections.

M2-TE

This is a really great PR, fantastic work!
I've added some comments/suggestions where relevant.

and finally revise the building and installation sections

woops, I also added some comments regarding those sections. If it's too early, just mark them as resolved and I'll revisit them once you have finished the section!

M2-TE · 2026-01-17T08:55:39Z

docs/Building.md

+
+## Minimum requirements
+
+The generator, samples, and tests requires a C++11 compiler. The following compilers are known to work, and tested during releases:


The generator actually requires a C++20 compiler:

Vulkan-Hpp/CMakeLists.txt

Line 116 in 67ec7c9

set_target_properties( VulkanHppGenerator PROPERTIES CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON )

M2-TE · 2026-01-17T09:00:13Z

docs/Building.md

+
+1. Install dependencies:
+   - Install CMake and git; ensure both are available from a shell.
+   - Install the LunarG Vulkan SDK.


The SDK should not be needed for either the generators or the tests/samples. The headers and xml registry are fetched from the Vulkan-Headers submodule.
It might be worth noting here that, in order to build samples, you need additional deps on Ubuntu:

Vulkan-Hpp/.github/workflows/build.yml

Line 79 in 67ec7c9

sudo apt-get update && sudo apt-get install lsb-release gpg software-properties-common wget

M2-TE · 2026-01-17T09:08:29Z

docs/Building.md

+
+If a `clang-format` executable is found by CMake, the define `CLANG_FORMAT_EXECUTABLE` is set accordingly. In that case, the generated headers are formatted using the `.clang-format` file located in the root directory of this project; otherwise, the formatting is left as hard-coded in the generator.
+
+Use `clang-format` version 21.1.0 to format the generated files.


This line comes a bit out of nowhere after the previous paragraph; did you mean to say that you should use this version for PRs? It should probably say either that, or that it is the recommended version in general.

M2-TE · 2026-01-17T09:30:26Z

docs/Handles.md

+
+Vulkan-Hpp provides a `vk::SharedHandle<Type>` interface. For each Vulkan handle type `vk::Type` there is a shared handle `vk::SharedType` which will delete the underlying Vulkan resource upon destruction, e.g. `vk::SharedBuffer` is the shared handle for `vk::Buffer`.
+
+Unlike `vk::UniqueHandle`, `vk::SharedHandle` takes shared ownership of the resource as well as its parent. This means that the parent handle will not be destroyed until all child resources are deleted. This is useful for resources that are shared between multiple threads or objects.


Since you were on the topic of multithreading, is it worth mentioning that shared handles are not thread safe? Handling mutexes (mutices?) is up to the user.

M2-TE · 2026-01-17T09:38:46Z

docs/Usage.md

+                                     vk::SharingMode::eExclusive, 0, nullptr, vk::ImageLayout::eUndefined});
+```
+
+#### Designated initialisers


Suggested change

#### Designated initialisers

#### Designated initializers

Sadge. I use British English...

M2-TE · 2026-01-17T11:36:20Z

docs/Usage.md

+Vulkan-Hpp provides a per-function dispatch mechanism where each function representing a Vulkan operation accepts as its last parameter a dispatch class.
+This class must provide a callable type for each Vulkan function that is required.
+
+<!-- TODO: What is this code sample exactly?  -->


Isn't it just a duplicate of the following section?
Instead of VULKAN_HPP_DEFAULT_DISPATCHER it uses vk::detail::DispatchLoaderDynamic directly, using dld and such, rather than defaultDispatchLoaderDynamic.

The information about vulkan-1 is still useful though, so perhaps best merged with the dynamic dispatch section below it?

M2-TE · 2026-01-17T11:38:02Z

docs/Usage.md

+
+   - Use your own dynamic loader, which needs to provide a templated function `getProcAddress`. Refer to the implementation of `vk::detail::DynamicLoader` in `vulkan.hpp` for an example.
+
+     <!-- TODO: Add a skeleton implementation of `struct YourDynamicLoader`? -->


That would be a nice idea. Probably just a stripped down version from what we have in vulkan.hpp is sufficient.

M2-TE · 2026-01-17T11:44:36Z

docs/Usage.md

+#if VULKAN_HPP_DISPATCH_LOADER_DYNAMIC == 1
+VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE
+#endif
+
+auto main(int argc, char* const argv[]) -> int
+{
+#if ( VULKAN_HPP_DISPATCH_LOADER_DYNAMIC == 1 )
+    // initialize minimal set of function pointers
+    VULKAN_HPP_DEFAULT_DISPATCHER.init();
+#endif


Suggested change

#if VULKAN_HPP_DISPATCH_LOADER_DYNAMIC == 1

VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE

#endif

auto main(int argc, char* const argv[]) -> int

{

#if ( VULKAN_HPP_DISPATCH_LOADER_DYNAMIC == 1 )

// initialize minimal set of function pointers

VULKAN_HPP_DEFAULT_DISPATCHER.init();

#endif

VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE

auto main(int argc, char* const argv[]) -> int

{

// initialize minimal set of function pointers

VULKAN_HPP_DEFAULT_DISPATCHER.init();

Probably best to just use the dynamic dispatcher stuff directly. It's what the example is for, so no need to confuse readers with additional #ifdefs.

M2-TE · 2026-01-17T11:46:35Z

docs/Usage.md

+#endif
+
+  auto appInfo = vk::ApplicationInfo("My App", 1, "My Engine", 1, vk::makeApiVersion(1, 0, 0, 0));
+  // ...


Suggested change

// ...

// ...

// load function pointers with created instance

VULKAN_HPP_DEFAULT_DISPATCHER.init(instance);

// OPTIONAL: load function pointers specifically for a vk::device

VULKAN_HPP_DEFAULT_DISPATCHER.init(device);

Can't hurt to add the other two inits here as well, right?

M2-TE · 2026-01-17T11:51:43Z

docs/Usage.md

+Some functions might provide information that depends on the vulkan version.
+As all functions here operate only on strings, the Vulkan versions are encoded by a string prefixed with "VK_VERSION_", followed by the major and the minor version, separated by an underscore, like this: `VK_VERSION_1_0`.
+
+<!-- TODO: the descriptions in this table need to be reworded a bit, it's a little hard to follow. -->


Maybe just use function names and parameters, then add a separate column for return values?
I'm not sure how much more readable that is exactly, but things like the constexpr macro can be stripped out (add another column with checkmarks for which funcs can be constexpr?).

sharadhr · 2026-01-17T13:56:41Z

If it's too early, just mark them as resolved

No worries, I can collapse them and work on your suggestions for the usage doc first. Thanks for being so comprehensive :)

sharadhr mentioned this pull request Nov 14, 2025

Merge Vulkan Video module into main module #2349

Closed

sharadhr force-pushed the rework-readme branch from 9896e08 to c2a3479 Compare November 23, 2025 20:56

sharadhr added 4 commits December 9, 2025 21:14

Initial readme rework

a2fdd46

- Remove HTML hyperlinks; markdown generates automatically - Use backticks \` to demarcate config macros - Remove `VULKAN_HPP_NO_STD_MODULE` option

Adhere to some markdownlint recommendations

38f97ad

- `-` instead of `*` - Spaces around lists

Introduction and installation

2eeeffb

Building section

581d2fe

sharadhr force-pushed the rework-readme branch from 86cebc2 to 581d2fe Compare December 9, 2025 21:18

sharadhr added 6 commits December 9, 2025 21:45

Minor intro changes

44e8b2e

Initial move of stuff into separate markdown files

28da47d

- Minor changes to main readme so that links work

Changed header levels

ff47f4d

- Minor changes in main readme

WIP

48230db

Update Usage.md for structs

ea30728

- Add builder pattern

Add one more line break for note

576fd7a

sharadhr force-pushed the rework-readme branch from 4a2fb83 to 576fd7a Compare December 14, 2025 21:41

sharadhr added 4 commits January 10, 2026 21:12

Detail struct usage

8ebd4e1

Usage rework continues

ef06932

- Rework flow; start with vulkan fundamentals - Move things around - Adhere to 1 sentence, 1 line

Move handles dpcs to Handles.md

63baf67

Add changes from main

293eca2

sharadhr force-pushed the rework-readme branch from 70f1aba to 293eca2 Compare January 13, 2026 22:22

sharadhr mentioned this pull request Jan 14, 2026

Samples: Reintroduced support for VULKAN_HPP_PRECOMPILE #2439

Merged

sharadhr added 3 commits January 14, 2026 23:38

Rework error-handling section

6814ae4

- Added TODOs for review - Added section on `std::expected`

Add note about CI status broken

f226b87

Minor top-level updates

67cea09

sharadhr added 8 commits January 15, 2026 00:19

Move some things around in preparation

13a596f

Minor wording

babee1b

Move more things around and change header levels

bad7816

Add headings and TOC for Handles doc

cd2966a

Rewrite and reformat the dispatcher section

e069b48

Update misc sections;

099ec32

- Reformat type traits and vkformat traits lists as tables

Update last few sections

36da1fb

Big rewrite for C++ module section

f0ccf58

M2-TE reviewed Jan 17, 2026

View reviewed changes


		## Minimum requirements

		The generator, samples, and tests requires a C++11 compiler. The following compilers are known to work, and tested during releases:


		If a `clang-format` executable is found by CMake, the define `CLANG_FORMAT_EXECUTABLE` is set accordingly. In that case, the generated headers are formatted using the `.clang-format` file located in the root directory of this project; otherwise, the formatting is left as hard-coded in the generator.

		Use `clang-format` version 21.1.0 to format the generated files.


		Vulkan-Hpp provides a `vk::SharedHandle<Type>` interface. For each Vulkan handle type `vk::Type` there is a shared handle `vk::SharedType` which will delete the underlying Vulkan resource upon destruction, e.g. `vk::SharedBuffer` is the shared handle for `vk::Buffer`.

		Unlike `vk::UniqueHandle`, `vk::SharedHandle` takes shared ownership of the resource as well as its parent. This means that the parent handle will not be destroyed until all child resources are deleted. This is useful for resources that are shared between multiple threads or objects.


		- Use your own dynamic loader, which needs to provide a templated function `getProcAddress`. Refer to the implementation of `vk::detail::DynamicLoader` in `vulkan.hpp` for an example.

		<!-- TODO: Add a skeleton implementation of `struct YourDynamicLoader`? -->

-  // ...
+  // ...
+  // load function pointers with created instance
+  VULKAN_HPP_DEFAULT_DISPATCHER.init(instance);
+  // OPTIONAL: load function pointers specifically for a vk::device
+  VULKAN_HPP_DEFAULT_DISPATCHER.init(device);

Rework the readme #2358

Are you sure you want to change the base?

Rework the readme #2358

Conversation

sharadhr commented Nov 11, 2025

Uh oh!

asuessenbach commented Nov 12, 2025

Uh oh!

sharadhr commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

asuessenbach commented Nov 12, 2025

Uh oh!

sharadhr commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

M2-TE commented Dec 18, 2025

Uh oh!

M2-TE commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sharadhr commented Dec 18, 2025

Uh oh!

sharadhr commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

M2-TE left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sharadhr commented Jan 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sharadhr commented Nov 12, 2025 •

edited

Loading

sharadhr commented Dec 15, 2025 •

edited

Loading

M2-TE commented Dec 18, 2025 •

edited

Loading

sharadhr commented Jan 16, 2026 •

edited

Loading

M2-TE left a comment •

edited

Loading