This page explains how Wisdom is organized and how that maps to the targets used in examples.

Overview

Wisdom provides a single API surface with backend-specific implementations under it. The public interfaces are generated and kept consistent across C and C++ bindings.

In typical projects, you link one core target and one platform target:

Static: wis::wisdom + wis::wisdom-platform
Shared: wis::wisdom-shared + wis::wisdom-platform-shared

This is the same linking pattern used by examples such as hello_triangle.

How It Works

Wisdom sits above DirectX 12 and Vulkan with a minimal abstraction layer. Backend code is split into two families:

wisdom/dx12 for DirectX 12
wisdom/vulkan for Vulkan

High-level aliases in <wisdom/wisdom.hpp> map to backend-prefixed types:

wis::DX12* on DirectX 12 builds
wis::VK* on Vulkan builds

The main include is <wisdom/wisdom.hpp> for core objects and API entry points. Platform extensions are exposed through <wisdom/wisdom_platform.hpp>.

On Windows, DirectX 12 is the default backend. Vulkan can be forced with WISDOM_FORCE_VULKAN (CMake option or preprocessor define).

Types

Use public .hpp headers in C++ and .h C headers for C/C99 integration.

For regular usage, prefer generic aliases (wis::Instance, wis::Device, wis::Buffer, ...). If explicit backend control is needed, use prefixed types (wis::DX12* / wis::VK*) directly.

The C++ API uses wis::span in many places. It is intentionally similar to C++20 std::span, but remains compatible with C++11. This keeps call sites consistent and improves safety through explicit bounds-aware range passing.

The examples mostly use generic aliases and target-based linking, which is the recommended default.

Objects follow RAII lifetime management and are move-oriented for low-overhead ownership transfer.

API

Most operations report status with wis::Result. C++ helpers keep call sites compact while preserving explicit error handling.

Example:

wis::Result result = wis::success;

auto instance = wis::CreateInstance(nullptr, {}, result);

Extending the Library

Extension points are intentionally open-ended. Internal handles can be queried via GetInternal / GetMutableInternal when integrating custom backend-specific functionality.

Note: Internals are provided for advanced scenarios and may change between versions. Prefer public APIs unless direct interop is required. The first members of the implementation structures are the guaranteed to represent underlying logical type and guaranteed to stay unless major version bump, so you can safely use them in the extensions.