diff --git a/gpu/api.h b/gpu/api.h new file mode 100644 index 000000000..6130e3e63 --- /dev/null +++ b/gpu/api.h @@ -0,0 +1,349 @@ +/* + * 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);