gfx_backend.h
What one backend implements. The device registry is the only caller.
#include "isolenui/gfx/gfx_backend.h". The guide starts at Writing a backend.
The backend table
Explained in Writing a backend.
gfx_backend_vtbl::set_presentgfx_backend_vtbl::set_transparentgfx_backend_vtblgfx_vulkan_backendgfx_metal_backendgfx_cpu_backendRegistry limits and handle bits
Explained in Assets and handles.
GFX_MAX_DEVICESGFX_MAX_IMAGESGFX_MAX_SVGSGFX_MAX_FONTSGFX_MAX_LISTENERSGFX_HANDLE_DEVICE_SHIFTGFX_HANDLE_REUSE_SHIFTgfx_handle_slotExample
backends_vtbl.cpp
#include "isolenui/gfx/gfx_backend.h"
// a d3d12 backend would define one of these the same way
// gfx_vulkan_backend, gfx_metal_backend and gfx_cpu_backend do, and an extern next to theirs
// is what lets the registry's per platform table point a slot at it
namespace {
struct d3d12_image {
uint32_t handle;
uint32_t width;
uint32_t height;
};
struct d3d12_state {
uint64_t frame;
d3d12_image images[GFX_MAX_IMAGES];
};
d3d12_state g_d3d12_state;
bool d3d12_probe(void)
{
return true;
}
// a null return is a failed open whatever why says, so a real open hands
// back a real state pointer
void* d3d12_open(window* w, const gfx_desc* d, gfx_status* why)
{
(void)w;
(void)d;
g_d3d12_state = {};
*why = gfx_ok;
return &g_d3d12_state;
}
void d3d12_close(void* state) { (void)state; }
bool d3d12_resize(void* state, uint32_t width, uint32_t height)
{
(void)state;
(void)width;
(void)height;
return true;
}
void d3d12_set_vsync(void* state, bool on) { (void)state; (void)on; }
void d3d12_set_clear(void* state, const float rgba[4]) { (void)state; (void)rgba; }
// true only when the surface really hands premultiplied alpha to the compositor
bool d3d12_set_transparent(void* state, bool on)
{
(void)state;
return !on;
}
void d3d12_wait_idle(void* state) { (void)state; }
bool d3d12_frame_begin(void* state, gfx_frame* out)
{
d3d12_state* s = static_cast<d3d12_state*>(state);
out->index = s->frame++;
out->backend = gfx_backend_d3d12;
out->native_encoder = nullptr;
out->native_target = nullptr;
return true;
}
// a record draws only when the handle it carries matches the one stored in
// its slot, so a stale handle from a freed image draws nothing, a null view
// draws at identity
void d3d12_frame_draw(void* state, const gfx_list* list, float scale, const gfx_view* view)
{
const d3d12_state* s = static_cast<const d3d12_state*>(state);
for (uint32_t i = 0; i < list->art_count; ++i) {
const gfx_art& a = list->art[i];
if (a.kind != gfx_art_image) {
continue;
}
const uint32_t slot = gfx_handle_slot(a.asset, GFX_MAX_IMAGES);
if (slot == 0xffffffffu || s->images[slot].handle != a.asset) {
continue;
}
// blit s->images[slot] at a.quad times scale here
}
(void)scale;
(void)view;
}
void d3d12_frame_end(void* state) { (void)state; }
// every asset call takes the full handle, the slot comes out of its low bits
bool d3d12_image_upload(void* state, uint32_t handle, const uint8_t* rgba,
uint32_t width, uint32_t height, uint32_t flags)
{
// flags carries gfx_image_no_mips, one level and no rebuild on update
(void)flags;
d3d12_state* s = static_cast<d3d12_state*>(state);
const uint32_t slot = gfx_handle_slot(handle, GFX_MAX_IMAGES);
if (slot == 0xffffffffu || !rgba) {
return false;
}
s->images[slot] = { handle, width, height };
return true;
}
// a rect of new pixels, copied before the call returns
bool d3d12_image_update(void* state, uint32_t handle, const uint8_t* rgba, uint32_t stride,
uint32_t x, uint32_t y, uint32_t w, uint32_t h)
{
(void)state;
(void)handle;
(void)rgba;
(void)stride;
(void)x;
(void)y;
(void)w;
(void)h;
return false;
}
// a texture the app made itself, refused here
bool d3d12_image_external(void* state, uint32_t handle, const gfx_external_image* d)
{
(void)state;
(void)handle;
(void)d;
return false;
}
void d3d12_image_free(void* state, uint32_t handle)
{
d3d12_state* s = static_cast<d3d12_state*>(state);
const uint32_t slot = gfx_handle_slot(handle, GFX_MAX_IMAGES);
if (slot != 0xffffffffu && s->images[slot].handle == handle) {
s->images[slot] = {};
}
}
bool d3d12_svg_upload(void* state, uint32_t handle, const char* path, float* width,
float* height)
{
(void)state;
(void)handle;
(void)path;
*width = 0.0f;
*height = 0.0f;
return false;
}
void d3d12_svg_free(void* state, uint32_t handle) { (void)state; (void)handle; }
bool d3d12_font_upload(void* state, uint32_t handle, const text_font* font)
{
(void)state;
(void)handle;
(void)font;
return true;
}
void d3d12_font_free(void* state, uint32_t handle) { (void)state; (void)handle; }
uint64_t d3d12_resident_bytes(void* state) { (void)state; return 0u; }
} // namespace
// extern gives the const external linkage so the registry can see it
extern const gfx_backend_vtbl gfx_d3d12_backend = {
gfx_backend_d3d12,
"d3d12",
d3d12_probe,
d3d12_open,
d3d12_close,
d3d12_resize,
d3d12_set_vsync,
d3d12_set_clear,
d3d12_set_transparent,
d3d12_wait_idle,
d3d12_frame_begin,
d3d12_frame_draw,
d3d12_frame_end,
d3d12_image_upload,
d3d12_image_update,
d3d12_image_external,
d3d12_image_free,
d3d12_svg_upload,
d3d12_svg_free,
d3d12_font_upload,
d3d12_font_free,
d3d12_resident_bytes,
nullptr, // set_present is optional
};