Backend Selection

ink supports multiple rendering backends through a unified API. The drawing code is identical regardless of which backend is active.

Available Backends

Backend	Status	Description
CPU (Software)	Working	Software rasterization to a `Pixmap` buffer. No GPU required.
OpenGL 3.3+	Working	Hardware-accelerated rendering via FBO, GLSL shaders, and vertex batching.
Metal	Working	macOS / iOS hardware-accelerated rendering.
Vulkan	Planned	Not yet implemented.

CPU Backend

The CPU backend is always available and requires no external dependencies:

auto surface = ink::Surface::MakeRaster(800, 600);

You can also wrap an existing pixel buffer (zero-copy):

auto info = ink::PixmapInfo::MakeBGRA(800, 600);
auto surface = ink::Surface::MakeRasterDirect(info, myPixelBuffer);

OpenGL Backend

Enable the GL backend at build time with -DINK_ENABLE_GL=ON (default).

#include <ink/ink.hpp>
#include <ink/gpu/gl/gl_context.hpp>

// Caller must have a current GL context before calling MakeGL()
auto ctx = ink::GpuContexts::MakeGL();
auto surface = ink::Surface::MakeGpu(ctx, 800, 600);

Important

The caller is responsible for ensuring the correct GL context is current before any ink GPU calls. If you use SDL with SDL_RENDERER_ACCELERATED, it may create its own GL context that conflicts with ink’s offscreen rendering. Use SDL_RENDERER_SOFTWARE for the SDL renderer when combining with ink’s GL backend.

Metal Backend

On macOS, enable with -DINK_ENABLE_METAL=ON:

#include <ink/gpu/metal/metal_context.hpp>

auto ctx = ink::GpuContexts::MakeMetal();
auto surface = ink::Surface::MakeGpu(ctx, 800, 600);

Metal does not share context state with SDL, so SDL_RENDERER_ACCELERATED works without issues.

Fallback Behavior

Surface::MakeGpu() falls back to a CPU surface if the provided GpuContext is null or invalid. This makes it safe to attempt GPU creation without checking for errors:

auto ctx = ink::GpuContexts::MakeGL();  // may fail
auto surface = ink::Surface::MakeGpu(ctx, 800, 600);
// surface is valid either way (GPU or CPU fallback)