Initialization

This page provides basic examples of how to use the Wisdom library in your project. The examples cover initialization and basic setup. Most of the examples are provided in the examples directory of the library.

Factory Initialization

In order to use the Wisdom library, you need to create the wis::Factory. The concept is similar to the IDXGIFactory in DirectX 12 and VkInstance in Vulkan.

First, you need to include the main header file:

#include <wisdom/wisdom.hpp>
 
int main() {return 0;}

To create the factory, you can use the wis::CreateFactory function. This function will create the factory and return it.

#include <wisdom/wisdom.hpp>
 
int main() {
  auto&& [result, factory] = wis::CreateFactory();
  return 0;
}

// or with RVO (Return Value Optimization)

int main() {
  wis::Result result = wis::success;
  auto factory = wis::CreateFactory(result);
}

Thats it! You have created the factory and can use it to create adapters and devices.

Note

The vulkan implemntation uses static storage for some of the objects. However it is thread safe. Though I don't see a reason to create more than one factory in your application.

Factory Extensions

wis::CreateFactory function will create the factory with the default extensions. However there are some extensions that you can use to extend the factory functionality. One of such extensions is wis::DebugExtension, which provides debug functionality for the factory. It is extension, so you need to link it to your project and include the header file:

# CMakeLists.txt
target_link_libraries(my_project PUBLIC wis::wisdom-debug)

// main.cpp
#include <wisdom/wisdom_debug.hpp>

To use the extension, you need to pass it to the wis::CreateFactory function as an argument. The first argument for wis::CreateFactory is a debug flag, which must be set to true if you want to use the debug extension. Then all the extensions are passed as an array of pointers to the wis::FactoryExtension objects.

wis::DebugExtension debug_ext;
wis::FactoryExtension* extensions[] = { &debug_ext };
auto&& [result, factory] = wis::CreateFactory(true, extensions, std::size(extensions));

That code will create the factory with the debug extension enabled.

Note

The extension is initialized in the CreateFactory function. Before that point the extension is not initialized and cannot be used. This is also true for Device extensions.

After the factory is created you can use factory to create adapters and devices. The debug extension can then be used to create debug messenger.

You can also use other extensions to extend the factory functionality.

List of factory extensions:

Extension	Header	Capability
wis::DebugExtension	<wisdom/wisdom_debug.hpp>	Debug functionality for the factory
wis::WindowsExtension	<wisdom/wisdom_platform.hpp> or <wisdom/wisdom_windows.hpp>	Windows-specific functionality for factory and swapchain creation
wis::X11Extension	<wisdom/wisdom_platform.hpp> or <wisdom/wisdom_x11.hpp>	X11-specific functionality for factory and swapchain creation
wis::WaylandExtension	<wisdom/wisdom_platform.hpp> or <wisdom/wisdom_wayland.hpp>	Wayland-specific functionality for factory and swapchain creation