Rework the readme

[sharadhr]

EDIT for posterity:

Resolves #2463

[asuessenbach]

Is there a reason you want to rework the readme?

[sharadhr]

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]

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

[M2-TE]

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]

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]

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.

[asuessenbach]

Wow!

I tried hard, but could not spot anything to improve!

After you've resolved the conflict, I'll merge this.

[sharadhr]

@asuessenbach there are a few TODOs though; hope you can think of some solutions for them. (You may need to revert to the old GitHub suggestions view; the new one hides all the comments).

[asuessenbach]

Indeed, a couple of Todos I didn't see before.
I tried to answer some of them, others (like the one in the Readme.md) just needs to be done.

[asuessenbach]

If I remember correctly, there was some company having their own (private) graphics library as a dll, based on Vulkan-Hpp. And the actual user of that dll doesn't need to know about that.

[asuessenbach]

@sharadhr and @M2-TE, while we're working on the documentation of Vulkan-Hpp: I'm thinking about completely removing those vk::UniqueHandles. I think, they could be easily replaced by the more versatile vk::raii::Handles.

I imagine to have some words about removing them in the Readme, telling that they're gonna be marked as deprecated in about a year, and finally be removed in about another year.

What would you think about that?

[sharadhr]

I think this is something that needs to be discussed with the wider community. I think maybe this should be in its own issue and PR?

There is overlap, but I'm not sure I can speak for everyone about removing vk::UniqueHandle.

[M2-TE]

I agree with @sharadhr as in that should probably be discussed in a separate PR.

Off the top of my head, one thing to discuss might be the dispatchers; vk::UniqueHandles use the static/dynamic dispatchers, whereas vk::raii::Handles have their own from what I've seen. So, unique handles could easily be mixed with normal handles, whereas raii handles likely have duplicate/separate dispatch storage?

I've used neither myself, so this is a question that probably needs a little more community reach like on the Vulkan Discord or Reddit.

[sharadhr]

OK—I think this is ready for final review and merge.

I don't want any more scope creep and hope to address the rest of the readme in phases and separate PRs.

[M2-TE]

I don't want to be overly picky, but you have this line in your latest commit about the static dispatcher:

Vulkan-Hpp provides a static dispatch loader, vk::detail::DispatchLoaderStatic, which contains stubs for all functions known to the library. This is the default, and a loader library such as volk can be used to populate the stubs with function pointers

The last part populate the stubs with function pointers is not entirely accurate. The functions, when using the static dispatcher, are simply declared (vulkan_core.h) and just never defined. The static dispatcher simply short-circuits to these.

So, for the static dispatcher, the function declarations need to have function definitions somewhere (some select few provided by vulkan-1, all provided by volk for example). This is why you can get linking errors with vulkan-1.

The dynamic dispatcher however does indeed use proper function pointers, so that is correct. When using it, all the function declarations are never declared in vulkan_core.h in the first place (VK_NO_PROTOTYPES).

[M2-TE]

Perfect, I see nothing else to comment on!

[asuessenbach]

What a great work!
The readme file is now no longer just a “readme file,” but documentation.

Thanks a lot for this great contribution.