/* * api.h * Copyright (C) 2026 Kovid Goyal * * 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 #include #include #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);