kitty/gpu/api.h
Kovid Goyal 9df76fcdf2
Add a backend neutral GPU driver API
gpu/api.h defines the interface between kitty and dynamically loaded GPU
drivers. It uses only standard C types, with opaque 64 bit handles for all
resources, so that it can be implemented with OpenGL, Vulkan or Metal.
2026-11-19 19:57:32 +05:30

349 lines
16 KiB
C

/*
* api.h
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// The backend neutral GPU driver API used by kitty. A driver is a shared
// library, loaded at runtime with dlopen(), that exports a single function
// named KITTY_GPU_DRIVER_ENTRY_POINT of type gpu_driver_load_func. That
// function fills in a GPUDriverAPI table of function pointers and returns an
// opaque driver object. Every function in the table takes that object as its
// first argument.
//
// This header must use only standard C so that it can be shared between
// kitty and drivers written for any graphics API (OpenGL, Vulkan, Metal).
//
// Conventions:
//
// * All resources are referred to by opaque 64 bit handles. The value zero
// (GPU_NULL_HANDLE) is never a valid handle and means "no resource".
// * Functions that create resources return GPU_NULL_HANDLE on failure, and
// functions that can fail return false. In both cases a description of the
// failure is available from last_error(). Errors from which the driver
// cannot recover are reported via the fatal() callback in GPUDriverInitParams.
// * Pixel coordinates for viewports, scissor rectangles and reading back pixels
// have their origin at the bottom left corner of the current render target,
// with y increasing upwards. Rows of pixel data read back from the GPU are
// ordered bottom to top. Pixel data uploaded to textures is ordered with the
// first row at texture coordinate t=0.
// * The driver tracks a small amount of "current" state: the pipeline,
// vertex layout, render target, viewport, scissor rectangle, sRGB output
// mode and textures bound to texture units. Draw calls use this state. This
// is cheap to implement on top of OpenGL and straightforward to record into
// command buffers for Vulkan and Metal.
// * On APIs where some objects are bound to a context or device queue, such
// as framebuffers and vertex array objects in OpenGL, vertex layouts and
// render targets are only valid in the context that was current when they
// were created. Textures, buffers and pipelines are shared between all
// contexts.
#pragma once
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#define KITTY_GPU_API_VERSION 1u
#define KITTY_GPU_DRIVER_ENTRY_POINT "kitty_gpu_driver_load"
#define GPU_NULL_HANDLE ((uint64_t)0)
typedef uint64_t gpu_texture_t;
typedef uint64_t gpu_buffer_t;
typedef uint64_t gpu_pipeline_t;
typedef uint64_t gpu_vertex_layout_t;
typedef uint64_t gpu_render_target_t;
// Initialization {{{
typedef void (*gpu_proc)(void);
typedef gpu_proc (*gpu_get_proc_address_func)(const char *name);
typedef void (*gpu_message_func)(const char *message);
typedef struct GPUDriverInitParams {
// Used by drivers that load their API entry points at runtime, such as
// OpenGL. Must be callable once a context is current, see initialize().
gpu_get_proc_address_func get_proc_address;
// Enable extra error checking and debug output
bool debug_rendering;
// Report a non-fatal error to the user
gpu_message_func log_error;
// Print debug output, only called when debug_rendering is true
gpu_message_func debug_print;
// Report an unrecoverable error, must not return
gpu_message_func fatal;
} GPUDriverInitParams;
typedef struct GPUCapabilities {
uint32_t max_texture_size; // max width and height of a texture
uint32_t max_array_texture_layers; // max number of layers in an array texture
// Whether render targets can encode linear colors to sRGB on output, see set_srgb_output()
bool supports_srgb_output;
} GPUCapabilities;
// }}}
// Textures {{{
typedef enum {
GPU_TEXTURE_2D = 1,
GPU_TEXTURE_2D_ARRAY,
} GPUTextureKind;
typedef enum {
GPU_FORMAT_R8 = 1, // one normalized 8 bit channel
GPU_FORMAT_R8UI, // one unsigned 8 bit integer channel
GPU_FORMAT_RG8UI, // two unsigned 8 bit integer channels
GPU_FORMAT_R32UI, // one unsigned 32 bit integer channel
GPU_FORMAT_RGBA8, // four normalized 8 bit channels
GPU_FORMAT_SRGB8_ALPHA8, // sRGB encoded colors with linear alpha, decoded to linear when sampled
GPU_FORMAT_RGBA16, // four normalized 16 bit channels
} GPUTextureFormat;
typedef enum {
GPU_FILTER_NEAREST = 1,
GPU_FILTER_LINEAR,
} GPUFilter;
typedef enum {
GPU_WRAP_CLAMP_TO_EDGE = 1,
GPU_WRAP_CLAMP_TO_BORDER, // sampling outside the texture returns transparent black
GPU_WRAP_REPEAT,
GPU_WRAP_MIRRORED_REPEAT,
} GPUWrap;
typedef struct GPUTextureDesc {
GPUTextureKind kind;
GPUTextureFormat format;
uint32_t width, height;
uint32_t layers; // number of layers, used only for GPU_TEXTURE_2D_ARRAY
GPUFilter filter;
GPUWrap wrap;
} GPUTextureDesc;
// The layout of pixel data in CPU memory
typedef enum {
GPU_PIXELS_R8 = 1, // one byte per pixel
GPU_PIXELS_RG8, // two bytes per pixel
GPU_PIXELS_RGB8, // three bytes per pixel, in the order R, G, B
GPU_PIXELS_RGBA8, // four bytes per pixel, in the order R, G, B, A
GPU_PIXELS_RGBA8_PACKED, // one native endian uint32_t per pixel with R in the most significant byte
GPU_PIXELS_R32UI, // one native endian uint32_t per pixel
} GPUPixelLayout;
typedef struct GPUPixelData {
GPUPixelLayout layout;
// Rows start at addresses that are a multiple of this many bytes, one of 1, 2, 4 or 8
uint32_t row_alignment;
const void *data;
} GPUPixelData;
// }}}
// Buffers {{{
typedef enum {
GPU_BUFFER_VERTEX = 1, // per vertex or per instance data for vertex layouts
GPU_BUFFER_UNIFORM, // data for uniform blocks
} GPUBufferKind;
typedef enum {
GPU_UPDATE_RARELY = 1, // written once, used many times
GPU_UPDATE_OFTEN, // written repeatedly, used many times
GPU_UPDATE_EVERY_USE, // written before every use
} GPUUpdateFrequency;
typedef enum {
GPU_MAP_WRITE = 1, // write to the buffer, preserving existing contents
GPU_MAP_WRITE_DISCARD_RANGE, // write to a range of the buffer, the previous contents of the range are discarded
GPU_MAP_WRITE_DISCARD_ALL, // write the whole buffer, its previous contents are discarded
GPU_MAP_READ, // read the contents of the buffer
} GPUMapMode;
// }}}
// Pipelines {{{
typedef enum {
GPU_SHADER_VERTEX = 1,
GPU_SHADER_FRAGMENT,
} GPUShaderStage;
typedef enum {
GPU_SHADER_LANGUAGE_GLSL = 1,
GPU_SHADER_LANGUAGE_SPIRV,
GPU_SHADER_LANGUAGE_MSL,
} GPUShaderLanguage;
typedef struct GPUShaderSource {
GPUShaderStage stage;
GPUShaderLanguage language;
const char *code;
size_t size; // size of code in bytes, may be zero for null terminated text
} GPUShaderSource;
typedef struct GPUUniformBlockInfo {
uint32_t index; // identifies the block within the pipeline
uint32_t size; // size in bytes of the data in the block
} GPUUniformBlockInfo;
typedef struct GPUUniformArrayInfo {
uint32_t offset; // byte offset of the array from the start of its uniform block
uint32_t stride; // bytes between consecutive elements
uint32_t count; // number of elements
} GPUUniformArrayInfo;
// }}}
// Drawing {{{
typedef enum {
GPU_ATTRIB_U8 = 1, // these integer types are passed to shaders as integers
GPU_ATTRIB_U16,
GPU_ATTRIB_U32,
GPU_ATTRIB_F32,
} GPUAttribType;
typedef enum {
GPU_BLEND_NONE = 1, // output replaces the existing contents
GPU_BLEND_PREMULTIPLIED_ALPHA // output, with pre-multiplied alpha, is composited over the existing contents
} GPUBlendMode;
// }}}
typedef struct GPUDriverAPI {
uint32_t api_version;
// Lifecycle {{{
// Called once, when the first context or surface the driver will render
// to is current. Must be called before any other function except
// destroy() and last_error().
bool (*initialize)(void *driver);
void (*destroy)(void *driver);
// A description of the last error, never NULL
const char *(*last_error)(void *driver);
// A human readable description of the GPU driver and API version
const char *(*version_string)(void *driver);
void (*get_capabilities)(void *driver, GPUCapabilities *ans);
// }}}
// Textures {{{
// Create a texture. If initial is not NULL it must contain the pixels of
// the whole texture, otherwise the contents of the texture are undefined.
gpu_texture_t (*texture_create)(void *driver, const GPUTextureDesc *desc, const GPUPixelData *initial);
// Replace the storage of an existing texture, keeping its handle
bool (*texture_reset)(void *driver, gpu_texture_t texture, const GPUTextureDesc *desc, const GPUPixelData *initial);
void (*texture_destroy)(void *driver, gpu_texture_t texture);
// Upload pixels to a rectangle within a single layer of a texture
void (*texture_upload)(
void *driver, gpu_texture_t texture, uint32_t x, uint32_t y, uint32_t layer, uint32_t width, uint32_t height, const GPUPixelData *pixels);
// Copy the entire contents of src into dst, starting at the origin of dst.
// Both textures must have the same kind and format and dst must be at
// least as large as src in every dimension.
void (*texture_copy)(void *driver, gpu_texture_t src, gpu_texture_t dst);
// Read back the first layer of a texture. dst must be large enough to hold
// width * height pixels of the specified layout with rows aligned to 4 bytes.
bool (*texture_read)(void *driver, gpu_texture_t texture, GPUPixelLayout layout, void *dst, size_t dst_size);
void (*texture_get_desc)(void *driver, gpu_texture_t texture, GPUTextureDesc *ans);
// Bind a texture to a texture unit, for sampling by the current pipeline
void (*bind_texture)(void *driver, uint32_t unit, gpu_texture_t texture);
// }}}
// Buffers {{{
gpu_buffer_t (*buffer_create)(void *driver, GPUBufferKind kind);
void (*buffer_destroy)(void *driver, gpu_buffer_t buffer);
// Allocate storage for the buffer, discarding its contents, unless it
// already has exactly that much storage
void (*buffer_allocate)(void *driver, gpu_buffer_t buffer, size_t size, GPUUpdateFrequency frequency);
// Map the buffer for access from the CPU. offset and size are used only
// by GPU_MAP_WRITE_DISCARD_RANGE and GPU_MAP_WRITE_DISCARD_ALL, the other
// modes map the whole buffer.
void *(*buffer_map)(void *driver, gpu_buffer_t buffer, GPUMapMode mode, size_t offset, size_t size);
void (*buffer_unmap)(void *driver, gpu_buffer_t buffer);
void (*buffer_copy)(void *driver, gpu_buffer_t src, size_t src_offset, gpu_buffer_t dst, size_t dst_offset, size_t size);
// Make a uniform buffer available to uniform blocks associated with binding_point
void (*bind_uniform_buffer)(void *driver, uint32_t binding_point, gpu_buffer_t buffer);
// }}}
// Pipelines {{{
// Create a pipeline from shader sources, on failure last_error() contains
// the compiler output
gpu_pipeline_t (*pipeline_create)(void *driver, const GPUShaderSource *sources, size_t num_sources);
void (*pipeline_destroy)(void *driver, gpu_pipeline_t pipeline);
// Make a pipeline current, GPU_NULL_HANDLE for none
void (*use_pipeline)(void *driver, gpu_pipeline_t pipeline);
// The slot used to set the named loose uniform with the set_uniform_*()
// functions, or -1 if the pipeline does not use that uniform. For arrays,
// name must not include a subscript.
int32_t (*pipeline_uniform_slot)(void *driver, gpu_pipeline_t pipeline, const char *name);
bool (*pipeline_uniform_block)(void *driver, gpu_pipeline_t pipeline, const char *name, GPUUniformBlockInfo *ans);
bool (*pipeline_uniform_array)(void *driver, gpu_pipeline_t pipeline, const char *name, GPUUniformArrayInfo *ans);
// Associate a uniform block of the pipeline with a binding point, see bind_uniform_buffer()
void (*pipeline_bind_uniform_block)(void *driver, gpu_pipeline_t pipeline, uint32_t block_index, uint32_t binding_point);
// The location of the named vertex input, -1 if it is not used
int32_t (*pipeline_attribute_location)(void *driver, gpu_pipeline_t pipeline, const char *name);
// Set the value of a loose uniform of the current pipeline. components is
// the number of components in each element (1 to 4) and count the number
// of elements. Slots that are negative are ignored.
void (*set_uniform_floats)(void *driver, int32_t slot, uint32_t components, uint32_t count, const float *values);
void (*set_uniform_ints)(void *driver, int32_t slot, uint32_t components, uint32_t count, const int32_t *values);
void (*set_uniform_uints)(void *driver, int32_t slot, uint32_t components, uint32_t count, const uint32_t *values);
// }}}
// Vertex layouts {{{
gpu_vertex_layout_t (*vertex_layout_create)(void *driver);
void (*vertex_layout_destroy)(void *driver, gpu_vertex_layout_t layout);
// Make a vertex layout current, GPU_NULL_HANDLE for none
void (*bind_vertex_layout)(void *driver, gpu_vertex_layout_t layout);
// Configure the vertex input at location to read components values of
// type from buffer, starting at offset bytes and advancing by stride bytes
// per vertex, or per instance_divisor instances if instance_divisor is
// not zero. Also makes the layout current.
void (*vertex_layout_set_attribute)(
void *driver,
gpu_vertex_layout_t layout,
uint32_t location,
gpu_buffer_t buffer,
uint32_t components,
GPUAttribType type,
uint32_t stride,
size_t offset,
uint32_t instance_divisor);
// }}}
// Render targets {{{
// Create a render target that draws into the specified texture. Does not
// change the current render target. Use render_target_status() to check
// that the render target is usable.
gpu_render_target_t (*render_target_create)(void *driver, gpu_texture_t color_texture);
void (*render_target_destroy)(void *driver, gpu_render_target_t target);
// Make a render target current, GPU_NULL_HANDLE for the window surface
void (*set_render_target)(void *driver, gpu_render_target_t target);
gpu_render_target_t (*get_render_target)(void *driver);
// NULL if the render target can be rendered to, otherwise a description of the problem
const char *(*render_target_status)(void *driver, gpu_render_target_t target);
// Fill the current render target, within the scissor rectangle if enabled, with the specified color
void (*clear)(void *driver, float r, float g, float b, float a);
void (*set_viewport)(void *driver, int32_t x, int32_t y, uint32_t width, uint32_t height);
void (*get_viewport)(void *driver, int32_t ans[4]);
void (*set_scissor)(void *driver, bool enabled, int32_t x, int32_t y, uint32_t width, uint32_t height);
// When enabled linear colors output by shaders are encoded to sRGB, if the render target supports it
void (*set_srgb_output)(void *driver, bool enabled);
// Read back a rectangle of the current render target as tightly packed GPU_PIXELS_RGBA8
void (*read_pixels)(void *driver, int32_t x, int32_t y, uint32_t width, uint32_t height, void *dst);
// Copy a rectangle of the current render target to the origin of a GPU_FORMAT_RGBA8 texture
void (*copy_to_texture)(void *driver, gpu_texture_t dst, int32_t x, int32_t y, uint32_t width, uint32_t height);
// }}}
// Drawing {{{
// Draw a quad using the current pipeline, vertex layout and render
// target. The vertex shader is invoked with vertex indices 0 to 3 and
// must map them to the corners of the quad going around its perimeter,
// so that 0, 1, 2 and 0, 2, 3 are the two triangles covering it. If
// instance_count is zero the draw is not instanced.
void (*draw_quad)(void *driver, uint32_t instance_count, GPUBlendMode blend);
// }}}
} GPUDriverAPI;
// The type of the function exported by drivers as KITTY_GPU_DRIVER_ENTRY_POINT.
// api_version is the KITTY_GPU_API_VERSION the caller was compiled with. On
// success, fills in api and driver and returns true. On failure writes a null
// terminated error message to errbuf and returns false.
typedef bool (*gpu_driver_load_func)(
uint32_t api_version, const GPUDriverInitParams *params, GPUDriverAPI *api, void **driver, char *errbuf, size_t errbuf_size);