Is there some proper documentation somewhere?

[Falkgaard]

So far I've only been able to find the repo readme and the examples, but I feel like the examples are poorly documented... for example, what's a vk::raii::Context for? What's the vk::raii::su namespace and what does su even stand for? Why is it nested into raii? What's the different between the raii namespace stuff and UniqueHandles (aren't they supposed to clean up using RAII)? etc etc (and this is pretty much just the unanswered questions from the first raii example). Is there a doxygen page somewhere or something? I went into file RAII_Samples/utils/utils.hpp to check if it's commented there somewhere, but that file was pretty much devoid of comments (especially in regards to the questions above).

[asuessenbach]

@Falkgaard You're absolutely right, the documentation on the new stuff in the namespace vk::raii is substantially less than satisfying. Be assured, that I'm working on some.
Until then, let me shortly answer your questions:

what's a vk::raii::Context for?

The vk::raii::Context is a helper class needed for the classes in the vk::raii namespace. Essentially, it dynamically loads a minimal set of function pointers to do the very first steps in an application (enumerate extensions, layers, and the version). And it's passed into the vk::raii::Instance constructor, to allow the instance-related initializations.

What's the vk::raii::su namespace and what does su even stand for? Why is it nested into raii?

That su stands for "sample utilities". Similar to the non-raii samples with the vk::su namespace, it holds a collection of little helper or convenience functions used throughout the samples. Those utilities are very tightly related to the samples and are not meant as generally usable functions.

What's the different between the raii namespace stuff and UniqueHandles (aren't they supposed to clean up using RAII)?

First of all, the UniqueHandles don't follow the RAII-paradigm. You have to assign them some result from a function (like vk::UniqueBuffer ub = vk::Device::createBufferUnique()). A vk::raii::Buffer, on the other hand, creates the buffer on instantiation.
But they both throw away the resource on destruction. That is, the vk::raii handles are designed to be managed by smart pointers, like std::unique_ptr or std::shared_ptr.
Maybe even more important is the multi-device handling. Please have a look at #918 for some more "docu" on that.

[tomilov]

@asuessenbach In what respect does UniqueHandle not follow the RAII-paradigm? "It may not hold an object" this? Seems, technically this can be not the problem at all. Theoretically one can extend universum by a "null" object.

[asuessenbach]

With #1001, some kind of programming guide for the raii-wrapper classes has been added.

[amosnier]

what's a vk::raii::Context for?

The vk::raii::Context is a helper class needed for the classes in the vk::raii namespace. Essentially, it dynamically loads a minimal set of function pointers to do the very first steps in an application (enumerate extensions, layers, and the version). And it's passed into the vk::raii::Instance constructor, to allow the instance-related initializations.

I'm sorry, but I still don't get it. Why would vk::raii::Instance not be able to invoke e.g. vk::enumerateInstanceVersion directly?

[amosnier]

Maybe I have the answer to my own question: does vk::raii::Context cache some information fetched in its constructor, avoiding multiple fetching later on? Anyway, I will assume that for now, and start writing some code with vk::raii. Thanks for Vulkan-Hpp and vk::raii, it looks great so far.

[amosnier]

After a little more experimenting, I got a dl linking error (I'm on Linux) when instantiating vk::raii::Context, although I was able to link without error a program that invokes vk::enumerateInstanceVersion directly earlier.

Essentially, [vk::raii::Context] dynamically loads a minimal set of function pointers to do the very first steps in an application [...]

That starts to make a little more sense now. After adding dl as a library in my build, I could link without error, and removing Vulkan as a linked library did not trigger any new linking error. I'm guessing I will be able to continue working without explicitly linking Vulkan, although I'm not exactly sure how the decision to use dynamic linking at runtime is actually made.

[asuessenbach]

@amosnier The vk::raii classes provide a seperate set of handle wrapper classes. The new vk::raii::Context holds a vk::DynamicLoader, that handles the vulkan dll loading.
That is, when using the vk::raii classes, you don't need to instantiate your own vk::DynamicLoader any more (which probably is done by having VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE exactly once in your project).
And therefore, vk::raii::Context also is the hook to hold all the functions that are neither Instance nor Device related, like the enumerateInstanceVersion.

[JasonQiu1]

Could I also use this issue to ask about what enhanced mode does or changes? The README doesn't really explain what it is.

[asuessenbach]

@JasonQiu1 You're right, that's missing in the README. I'll add a few words about it...
'Til then: As long as VULKAN_HPP_DISABLE_ENHANCED_MODE is not defined, you get

• "enhanced" versions of the commands, in various flavors (consuming vk::ArrayProxy<>, simplifying handling of array data; returning requested data; throwing exceptions on errors (as long as VULKAN_HPP_NO_EXCEPTIONS is not defined));
• "enhanced" structure constructors (as long as VULKAN_HPP_NO_STRUCT_CONSTRUCTORS is not defined) (consuming vk::ArrayProxyNoTemporaries<>);
• "enhanced" set-functions on some members of a struct (consuming vk::ArrayProxyNoTemporaries<>, again);
• the helper classes vk::ArrayProxy<> and vk::ArrayProxyNoTemporaries<>;
• all the RAII-stuff in vulkan_raii.hpp.

[Pacheco95]

Is it correct/safe to use a local vk::raii::Context to initialize class member variables?

class Test {
public:
  void init() {
    vk::raii::Context context;

    auto& applicationInfo = vk::ApplicationInfo().setApiVersion(VK_API_VERSION_1_3);

    auto& instanceCreateInfo = vk::InstanceCreateInfo().setPApplicationInfo(&applicationInfo);

    m_instance = std::make_unique<vk::raii::Instance>(context, instanceCreateInfo);
  }

private:
  std::unique_ptr<vk::raii::Instance> m_instance = nullptr;
}

[asuessenbach]

Is it correct/safe to use a local vk::raii::Context to initialize class member variables?

No, that will not work. You need to hold the vk::raii::Context until all objects created from it (that is, the vk::raii::Instances) are destroyed. I will add some words about that to the https://github.com/asuessenbach/Vulkan-Hpp/blob/main/vk_raii_ProgrammingGuide.md.

[Pacheco95]

In addition, can you add some comparison between unique handles and raii? The pros and cons of each one, etc.