Add a Metal GPU driver and an MSL shader target

On macOS, kitty now tries to render using Metal, falling back to OpenGL,
see the gpu_driver option. The driver has not yet been compiled or run
on macOS, it was written on Linux and only syntax checked against stub
headers.

Shader targets of the form msl-NN (for MSL N.N) compile each program to
a single MSL source file containing the entry points for all stages,
compiled by the driver at runtime, for the built-in and custom shaders.
slangc ignores [[vk::binding]] for Metal, so the program metadata keeps
the kitty binding slots and passes the argument table indices assigned
by slangc as native names. The push constant block, emitted as an
ordinary constant buffer, is recognized by the name of its type. As
Metal has y=1 at the top in NDC, the generated code is fixed up to
negate the y coordinate of the position output by vertex entry points.
Layouts that would differ because bool is a single byte in MSL are
rejected. The MSL is validated with the Metal compiler when available.
The MSL shaders are temporarily built on all platforms, for development.

The driver follows the design of the Vulkan driver: command buffers with
serials and at most three in flight, copy on write of buffer storage the
GPU may still use, private textures uploaded with blits from staging
memory, pipeline variants created when first used and a CAMetalLayer
per window. Vertex inputs whose offset or stride is not a multiple of
four bytes, as Metal requires, are repacked into a cached copy.
This commit is contained in:
Kovid Goyal 2026-11-04 08:56:12 +05:30
parent 813e8cefd0
commit ca5b72bd26
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
12 changed files with 3292 additions and 39 deletions

246
gpu/metal/buffers.m Normal file
View file

@ -0,0 +1,246 @@
/*
* buffers.m
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// Buffers, see internal.h for how they preserve the OpenGL semantics kitty relies on
#include "internal.h"
#define AS_BUFFER(handle) ((Buffer *)(uintptr_t)(handle))
// Storage {{{
static bool
create_storage(Driver *d, size_t size, BufferStorage *ans) {
*ans = (BufferStorage){.size = size};
// Metal does not allow buffers of size zero
ans->buffer = [d->device newBufferWithLength:MAX((size_t)16u, size) options:MTLResourceStorageModeShared];
if (ans->buffer == nil) {
set_error(d, "Failed to allocate a GPU buffer of size %zu", size);
return false;
}
return true;
}
static void
destroy_storage(BufferStorage *s) {
// Command buffers retain the buffers they use, so it can be released immediately
[s->buffer release];
*s = (BufferStorage){0};
}
static void
free_buffer(Buffer *b) {
destroy_storage(&b->storage);
for (size_t i = 0; i < b->num_retired; i++) destroy_storage(b->retired + i);
b->num_retired = 0;
[b->repacked.buffer release];
b->repacked.buffer = nil;
}
// Get storage of the specified size that no commands use, reusing retired storage if possible
static bool
fresh_storage(Driver *d, Buffer *b, size_t size, BufferStorage *ans) {
const uint64_t done = completed_serial(d);
for (size_t i = 0; i < b->num_retired; i++) {
BufferStorage *s = b->retired + i;
if (s->size == size && s->last_use_serial <= done) {
*ans = *s;
b->retired[i] = b->retired[--b->num_retired];
return true;
}
}
return create_storage(d, size, ans);
}
static void
retire_storage(Buffer *b, BufferStorage *s) {
if (s->buffer == nil) return;
if (b->num_retired >= arraysz(b->retired)) {
// Drop the oldest retired storage
destroy_storage(b->retired);
memmove(b->retired, b->retired + 1, (b->num_retired - 1) * sizeof(BufferStorage));
b->num_retired--;
}
b->retired[b->num_retired++] = *s;
*s = (BufferStorage){0};
}
// Ensure the current storage of the buffer is not used by any commands,
// preserving its contents if preserve is true
static void
make_writable(Driver *d, Buffer *b, bool preserve) {
b->generation++;
if (b->storage.last_use_serial <= completed_serial(d)) return;
BufferStorage s;
if (!fresh_storage(d, b, b->storage.size, &s)) fatal(d, "Failed to allocate a GPU buffer with error: %s", d->last_error);
// Only the CPU writes to buffers, so the old contents are current
if (preserve) memcpy([s.buffer contents], [b->storage.buffer contents], b->storage.size);
retire_storage(b, &b->storage);
b->storage = s;
}
// }}}
// API {{{
gpu_buffer_t
buffer_create(void *driver, GPUBufferKind kind) {
Driver *d = driver;
Buffer *b = calloc(1, sizeof(Buffer));
if (!b) {
set_error(d, "Out of memory");
return GPU_NULL_HANDLE;
}
b->kind = kind;
b->frequency = GPU_UPDATE_RARELY;
LIST_ADD(d->buffers, b);
return AS_HANDLE(b);
}
void
buffer_destroy(void *driver, gpu_buffer_t buffer) {
Driver *d = driver;
Buffer *b = AS_BUFFER(buffer);
if (!b) return;
for (size_t i = 0; i < arraysz(d->bound_buffers); i++) {
if (d->bound_buffers[i] == b) d->bound_buffers[i] = NULL;
}
free_buffer(b);
LIST_REMOVE(d->buffers, b);
free(b);
}
void
destroy_all_buffers(Driver *d) {
while (d->buffers) buffer_destroy(d, AS_HANDLE(d->buffers));
}
void
buffer_allocate(void *driver, gpu_buffer_t buffer, size_t size, GPUUpdateFrequency frequency) {
Driver *d = driver;
Buffer *b = AS_BUFFER(buffer);
b->frequency = frequency;
if (b->storage.buffer != nil && b->storage.size == size) return;
// Retired storage of a different size is useless
free_buffer(b);
b->generation++;
if (!size) return;
if (!create_storage(d, size, &b->storage)) fatal(d, "Failed to allocate a GPU buffer of size %zu with error: %s", size, d->last_error);
}
void *
buffer_map(void *driver, gpu_buffer_t buffer, GPUMapMode mode, size_t offset, size_t size) {
Driver *d = driver;
Buffer *b = AS_BUFFER(buffer);
if (b->storage.buffer == nil) return NULL;
switch (mode) {
case GPU_MAP_READ: return [b->storage.buffer contents];
case GPU_MAP_WRITE: make_writable(d, b, true); return [b->storage.buffer contents];
case GPU_MAP_WRITE_DISCARD_ALL: make_writable(d, b, false); return (uint8_t *)[b->storage.buffer contents] + offset;
case GPU_MAP_WRITE_DISCARD_RANGE:
// The contents outside the range must be preserved
make_writable(d, b, offset > 0 || size < b->storage.size);
return (uint8_t *)[b->storage.buffer contents] + offset;
}
return NULL;
}
void
buffer_unmap(void *driver UNUSED, gpu_buffer_t buffer UNUSED) {
// Buffers are in shared memory, which is coherent, and are always mapped
}
void
buffer_copy(void *driver, gpu_buffer_t src, size_t src_offset, gpu_buffer_t dst, size_t dst_offset, size_t size) {
Driver *d = driver;
Buffer *s = AS_BUFFER(src), *t = AS_BUFFER(dst);
if (!size || s->storage.buffer == nil || t->storage.buffer == nil) return;
if (src_offset + size > s->storage.size || dst_offset + size > t->storage.size) {
log_error(d, "Out of bounds GPU buffer copy");
return;
}
// Only the CPU writes to buffers, so copies are done by the CPU too
make_writable(d, t, true);
memmove((uint8_t *)[t->storage.buffer contents] + dst_offset, (uint8_t *)[s->storage.buffer contents] + src_offset, size);
}
bool
write_buffer(Driver *d, Buffer *b, const void *data, size_t size) {
if (b->storage.buffer == nil || b->storage.size < size) return false;
make_writable(d, b, size < b->storage.size);
memcpy([b->storage.buffer contents], data, size);
return true;
}
void
bind_uniform_buffer(void *driver, uint32_t slot, gpu_buffer_t buffer) {
Driver *d = driver;
if (slot >= MAX_BINDING_SLOTS) {
log_error(d, "Invalid uniform buffer binding slot: %u", slot);
return;
}
d->bound_buffers[slot] = AS_BUFFER(buffer);
}
void
use_buffer(Driver *d, Buffer *b) {
b->storage.last_use_serial = recording_serial(d);
}
// }}}
// Vertex buffers {{{
// Metal requires the offsets and strides of vertex buffers to be multiples
// of four bytes. kitty has vertex inputs with one byte elements that are
// tightly packed, such as the selection state of cells, whose elements are
// copied into a buffer where each element starts at a multiple of four bytes.
// The copy is cached with the buffer, it is made again only when the
// contents of the buffer change.
static bool
needs_repack(const VertexAttribute *a) {
return (a->offset % 4) != 0 || (a->stride % 4) != 0;
}
uint32_t
vertex_buffer_stride(const VertexAttribute *a, size_t element_size) {
return needs_repack(a) ? (uint32_t)((element_size + 3u) / 4u * 4u) : a->stride;
}
id<MTLBuffer>
vertex_buffer_for(Driver *d, const VertexAttribute *a, size_t element_size, size_t *offset, uint32_t *stride) {
Buffer *b = a->buffer;
if (!b || b->storage.buffer == nil) return nil;
use_buffer(d, b);
if (!needs_repack(a)) {
*offset = a->offset;
*stride = a->stride;
return b->storage.buffer;
}
const uint32_t new_stride = vertex_buffer_stride(a, element_size);
*offset = 0;
*stride = new_stride;
if (b->repacked.buffer != nil && b->repacked.generation == b->generation && b->repacked.offset == a->offset && b->repacked.stride == a->stride &&
b->repacked.element_size == element_size && b->repacked.size == b->storage.size)
return b->repacked.buffer;
// The number of whole elements in the buffer
size_t count = 0;
if (b->storage.size >= a->offset + element_size) count = (b->storage.size - a->offset - element_size) / a->stride + 1;
// The previous copy may still be used by commands, which retain it, so a new one is made
id<MTLBuffer> buf = [d->device newBufferWithLength:MAX((size_t)16u, count * new_stride) options:MTLResourceStorageModeShared];
if (buf == nil) {
log_error(d, "Failed to allocate a GPU buffer of size %zu for repacking vertex data", count * new_stride);
return nil;
}
const uint8_t *src = (const uint8_t *)[b->storage.buffer contents] + a->offset;
uint8_t *dst = [buf contents];
for (size_t i = 0; i < count; i++) memcpy(dst + i * new_stride, src + i * a->stride, element_size);
[b->repacked.buffer release];
b->repacked.buffer = buf;
b->repacked.generation = b->generation;
b->repacked.offset = a->offset;
b->repacked.stride = a->stride;
b->repacked.element_size = (uint32_t)element_size;
b->repacked.size = b->storage.size;
return buf;
}
// }}}

699
gpu/metal/commands.m Normal file
View file

@ -0,0 +1,699 @@
/*
* commands.m
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// Command buffers, encoders, rendering and drawing
#include "internal.h"
#define AS_TEXTURE(handle) ((Texture *)(uintptr_t)(handle))
#define AS_RENDER_TARGET(handle) ((RenderTarget *)(uintptr_t)(handle))
// Command buffers {{{
uint64_t
completed_serial(Driver *d) {
return atomic_load_explicit(&d->completed_serial, memory_order_acquire);
}
uint64_t
recording_serial(Driver *d) {
return d->cmd != nil ? d->cmd_serial : d->next_serial;
}
static void
mark_completed(Driver *d, uint64_t serial) {
uint64_t cur = atomic_load_explicit(&d->completed_serial, memory_order_acquire);
while (cur < serial && !atomic_compare_exchange_weak_explicit(&d->completed_serial, &cur, serial, memory_order_acq_rel, memory_order_acquire));
}
void
check_gpu_errors(Driver *d) {
if (!atomic_load_explicit(&d->gpu_error_pending, memory_order_acquire)) return;
log_error(d, "Metal: Executing GPU commands failed with error: %s", d->gpu_error);
// Allows the next failure to be recorded
atomic_store_explicit(&d->gpu_error_pending, false, memory_order_release);
}
id<MTLCommandBuffer>
command_buffer(Driver *d) {
if (d->cmd != nil) return d->cmd;
check_gpu_errors(d);
// Waiting for a slot throttles the CPU to at most NUM_IN_FLIGHT command
// buffers ahead of the GPU. The slot is released by the completed handler.
dispatch_semaphore_wait(d->in_flight, DISPATCH_TIME_FOREVER);
@autoreleasepool {
if (d->params.debug_rendering) {
// Detailed errors for the encoders of command buffers that fail
MTLCommandBufferDescriptor *desc = [[MTLCommandBufferDescriptor alloc] init];
[desc setErrorOptions:MTLCommandBufferErrorOptionEncoderExecutionStatus];
d->cmd = [[d->queue commandBufferWithDescriptor:desc] retain];
[desc release];
} else d->cmd = [[d->queue commandBuffer] retain];
}
if (d->cmd == nil) fatal(d, "Failed to create a Metal command buffer");
d->cmd_serial = d->next_serial;
// The handler runs on a thread owned by Metal, see internal.h. The driver
// outlives it, see destroy().
Driver *driver = d;
const uint64_t serial = d->cmd_serial;
[d->cmd addCompletedHandler:^(id<MTLCommandBuffer> cb) {
if ([cb status] == MTLCommandBufferStatusError) {
bool expected = false;
// Only one failure is recorded until it has been reported
if (atomic_compare_exchange_strong(&driver->gpu_error_pending, &expected, true)) {
// The flag is set before the message is written, so the main
// thread could read a partial message, which is harmless
snprintf(driver->gpu_error, sizeof(driver->gpu_error), "%s", error_description([cb error]));
}
}
mark_completed(driver, serial);
dispatch_semaphore_signal(driver->in_flight);
}];
return d->cmd;
}
void
submit_commands(Driver *d, bool wait) {
if (d->cmd == nil) return;
end_encoding(d);
id<MTLCommandBuffer> cmd = d->cmd;
const uint64_t serial = d->cmd_serial;
d->cmd = nil;
d->next_serial++;
[cmd commit];
if (wait) {
[cmd waitUntilCompleted];
// The completed handler might not have run yet
mark_completed(d, serial);
}
[cmd release];
if (wait) check_gpu_errors(d);
}
void
wait_for_idle(Driver *d) {
submit_commands(d, false);
// Every command buffer holds a slot until its completed handler has run
for (int i = 0; i < NUM_IN_FLIGHT; i++) dispatch_semaphore_wait(d->in_flight, DISPATCH_TIME_FOREVER);
for (int i = 0; i < NUM_IN_FLIGHT; i++) dispatch_semaphore_signal(d->in_flight);
check_gpu_errors(d);
}
void
end_rendering(Driver *d) {
if (d->rendering.encoder == nil) return;
[d->rendering.encoder endEncoding];
[d->rendering.encoder release];
d->rendering.encoder = nil;
d->rendering.view = nil;
d->rendering.texture = nil;
d->rendering.pipeline = nil;
}
void
end_encoding(Driver *d) {
end_rendering(d);
if (d->blit != nil) {
[d->blit endEncoding];
[d->blit release];
d->blit = nil;
}
}
id<MTLBlitCommandEncoder>
blit_encoder(Driver *d) {
end_rendering(d);
if (d->blit == nil) {
@autoreleasepool {
d->blit = [[command_buffer(d) blitCommandEncoder] retain];
}
if (d->blit == nil) fatal(d, "Failed to create a Metal blit command encoder");
}
return d->blit;
}
// }}}
// Staging {{{
bool
allocate_staging(Driver *d, size_t size, size_t alignment, id<MTLBuffer> *buffer, size_t *offset, void **mapped) {
const uint64_t serial = recording_serial(d), done = completed_serial(d);
alignment = MAX((size_t)16u, alignment);
if (size < STAGING_CHUNK_SIZE) {
// Small uploads are sub-allocated from chunks, first from those
// already used by the command buffer being encoded, then from those
// no longer used by the GPU
StagingChunk *found = NULL;
size_t start = 0;
for (size_t i = 0; i < d->num_staging && !found; i++) {
StagingChunk *c = d->staging + i;
if (c->serial != serial) continue;
start = (c->used + alignment - 1) / alignment * alignment;
if (start + size <= STAGING_CHUNK_SIZE) found = c;
}
for (size_t i = 0; i < d->num_staging && !found; i++) {
StagingChunk *c = d->staging + i;
if (c->serial <= done) {
found = c;
start = 0;
}
}
if (!found && d->num_staging < arraysz(d->staging)) {
id<MTLBuffer> b = [d->device newBufferWithLength:STAGING_CHUNK_SIZE options:MTLResourceStorageModeShared];
if (b == nil) {
set_error(d, "Failed to allocate %u bytes of staging memory", STAGING_CHUNK_SIZE);
return false;
}
found = d->staging + d->num_staging++;
*found = (StagingChunk){.buffer = b};
start = 0;
}
if (found) {
found->serial = serial;
found->used = start + size;
*buffer = found->buffer;
*offset = start;
*mapped = (uint8_t *)[found->buffer contents] + start;
return true;
}
}
// Uploads too large for a chunk, or when all chunks are in use, get a
// buffer of their own. It is autoreleased, the command buffer retains it
// once it is used by an encoded command.
id<MTLBuffer> b = [d->device newBufferWithLength:size options:MTLResourceStorageModeShared];
if (b == nil) {
set_error(d, "Failed to allocate %zu bytes of staging memory", size);
return false;
}
[b autorelease];
*buffer = b;
*offset = 0;
*mapped = [b contents];
return true;
}
void
release_staging(Driver *d) {
for (size_t i = 0; i < d->num_staging; i++) [d->staging[i].buffer release];
d->num_staging = 0;
}
// }}}
// Utility pipelines {{{
// Pipelines used by the driver itself, they draw a quad covering the viewport
// with a triangle strip of four vertices
static const char utility_shaders[] = "#include <metal_stdlib>\n"
"using namespace metal;\n"
"struct FullscreenVertex { float4 position [[position]]; };\n"
"vertex FullscreenVertex kitty_fullscreen_vertex(uint vid [[vertex_id]]) {\n"
" FullscreenVertex v;\n"
" v.position = float4((vid & 1u) ? 1.0 : -1.0, (vid & 2u) ? 1.0 : -1.0, 0.0, 1.0);\n"
" return v;\n"
"}\n"
"fragment float4 kitty_clear_fragment(constant float4 &color [[buffer(0)]]) { return color; }\n"
"fragment float4 kitty_copy_fragment(float4 position [[position]], texture2d<float, access::read> src [[texture(0)]],\n"
" constant int2 &origin [[buffer(0)]]) {\n"
" return src.read(uint2(int2(position.xy) + origin));\n"
"}\n";
bool
create_utility_pipelines(Driver *d) {
@autoreleasepool {
NSError *err = nil;
d->utility_library = [d->device newLibraryWithSource:[NSString stringWithUTF8String:utility_shaders] options:nil error:&err];
if (d->utility_library == nil) {
set_error(d, "Failed to compile the Metal utility shaders with error: %s", error_description(err));
return false;
}
d->fullscreen_vertex = [d->utility_library newFunctionWithName:@"kitty_fullscreen_vertex"];
d->clear_fragment = [d->utility_library newFunctionWithName:@"kitty_clear_fragment"];
d->copy_fragment = [d->utility_library newFunctionWithName:@"kitty_copy_fragment"];
if (d->fullscreen_vertex == nil || d->clear_fragment == nil || d->copy_fragment == nil) {
set_error(d, "The Metal utility shaders are missing functions");
return false;
}
}
return true;
}
void
destroy_utility_pipelines(Driver *d) {
for (size_t i = 0; i < d->num_clear_pipelines; i++) [d->clear_pipelines[i].state release];
for (size_t i = 0; i < d->num_copy_pipelines; i++) [d->copy_pipelines[i].state release];
d->num_clear_pipelines = d->num_copy_pipelines = 0;
[d->fullscreen_vertex release];
[d->clear_fragment release];
[d->copy_fragment release];
[d->utility_library release];
d->fullscreen_vertex = d->clear_fragment = d->copy_fragment = nil;
d->utility_library = nil;
}
static id<MTLRenderPipelineState>
utility_pipeline(Driver *d, bool is_copy, MTLPixelFormat format) {
UtilityPipeline *cache = is_copy ? d->copy_pipelines : d->clear_pipelines;
size_t *num = is_copy ? &d->num_copy_pipelines : &d->num_clear_pipelines;
for (size_t i = 0; i < *num; i++) {
if (cache[i].format == format) return cache[i].state;
}
if (*num >= MAX_UTILITY_FORMATS) {
log_error(d, "Metal: Too many render target formats");
return nil;
}
id<MTLRenderPipelineState> ans = nil;
@autoreleasepool {
MTLRenderPipelineDescriptor *desc = [[MTLRenderPipelineDescriptor alloc] init];
[desc setLabel:is_copy ? @"kitty copy" : @"kitty clear"];
[desc setVertexFunction:d->fullscreen_vertex];
[desc setFragmentFunction:is_copy ? d->copy_fragment : d->clear_fragment];
[[[desc colorAttachments] objectAtIndexedSubscript:0] setPixelFormat:format];
NSError *err = nil;
ans = [d->device newRenderPipelineStateWithDescriptor:desc error:&err];
[desc release];
if (ans == nil) {
log_error(d, "Metal: Failed to create a utility pipeline with error: %s", error_description(err));
return nil;
}
}
cache[(*num)++] = (UtilityPipeline){.format = format, .state = ans};
return ans;
}
// }}}
// Rendering {{{
// The image the current render target renders into
static bool
target_image(Driver *d, RenderImage *ans) {
if (d->render_target) {
Texture *t = d->render_target->texture;
if (!t || t->texture == nil) return false;
*ans = (RenderImage){
.texture = t->texture,
.unorm_view = t->unorm_view,
.srgb_view = t->srgb_view,
.width = (uint32_t)[t->texture width],
.height = (uint32_t)[t->texture height]};
return true;
}
return current_surface_image(d, ans);
}
// The view of the image to render into, honoring the sRGB output mode, nil if it cannot be rendered into
static id<MTLTexture>
render_view(Driver *d, const RenderImage *img) {
return d->srgb_output && img->srgb_view != nil ? img->srgb_view : img->unorm_view;
}
// Begin a render pass into view, ending any active pass or blit encoder. If
// clear_color is not NULL the view is first cleared to it.
static void
start_render_pass(Driver *d, const RenderImage *img, id<MTLTexture> view, const float *clear_color) {
end_encoding(d);
id<MTLCommandBuffer> cmd = command_buffer(d);
@autoreleasepool {
MTLRenderPassDescriptor *rp = [MTLRenderPassDescriptor renderPassDescriptor];
MTLRenderPassColorAttachmentDescriptor *a = [[rp colorAttachments] objectAtIndexedSubscript:0];
[a setTexture:view];
[a setLoadAction:clear_color ? MTLLoadActionClear : MTLLoadActionLoad];
if (clear_color) [a setClearColor:MTLClearColorMake(clear_color[0], clear_color[1], clear_color[2], clear_color[3])];
[a setStoreAction:MTLStoreActionStore];
d->rendering.encoder = [[cmd renderCommandEncoderWithDescriptor:rp] retain];
}
if (d->rendering.encoder == nil) fatal(d, "Failed to create a Metal render command encoder");
d->rendering.view = view;
d->rendering.texture = img->texture;
d->rendering.format = [view pixelFormat];
d->rendering.width = img->width;
d->rendering.height = img->height;
// Encoder state does not carry over between encoders
d->rendering.pipeline = nil;
d->rendering.push_constants_of = NULL;
d->rendering.push_constants_dirty = false;
d->rendering.viewport_valid = d->rendering.scissor_valid = false;
}
// Begin a render pass for the current render target, if not already active.
// Returns false if there is nothing to render to.
static bool
begin_rendering(Driver *d) {
RenderImage img;
if (!target_image(d, &img)) return false;
id<MTLTexture> view = render_view(d, &img);
if (view == nil) {
log_error(d, "Cannot render into a texture of this format");
return false;
}
if (d->rendering.encoder != nil && d->rendering.view == view) return true;
start_render_pass(d, &img, view, NULL);
return true;
}
// The scissor rectangle, clipped to the render target of size width x height, as x, y, width, height
static void
current_scissor(Driver *d, uint32_t width, uint32_t height, int32_t ans[4]) {
const int32_t w = (int32_t)width, h = (int32_t)height;
int32_t x0 = 0, y0 = 0, x1 = w, y1 = h;
if (d->scissor.enabled) {
x0 = MAX(0, MIN(w, d->scissor.rect[0]));
y0 = MAX(0, MIN(h, d->scissor.rect[1]));
x1 = MAX(x0, MIN(w, d->scissor.rect[0] + d->scissor.rect[2]));
y1 = MAX(y0, MIN(h, d->scissor.rect[1] + d->scissor.rect[3]));
}
ans[0] = x0;
ans[1] = y0;
ans[2] = x1 - x0;
ans[3] = y1 - y0;
}
static void
apply_scissor(Driver *d, const int32_t sc[4]) {
if (d->rendering.scissor_valid && memcmp(d->rendering.scissor, sc, sizeof(d->rendering.scissor)) == 0) return;
const MTLScissorRect r = {.x = (NSUInteger)sc[0], .y = (NSUInteger)sc[1], .width = (NSUInteger)sc[2], .height = (NSUInteger)sc[3]};
[d->rendering.encoder setScissorRect:r];
memcpy(d->rendering.scissor, sc, sizeof(d->rendering.scissor));
d->rendering.scissor_valid = true;
}
void
clear(void *driver, float r, float g, float b, float a) {
Driver *d = driver;
RenderImage img;
if (!target_image(d, &img)) return;
id<MTLTexture> view = render_view(d, &img);
if (view == nil) return;
int32_t sc[4];
current_scissor(d, img.width, img.height, sc);
if (sc[2] <= 0 || sc[3] <= 0) return;
const float color[4] = {r, g, b, a};
const bool whole = sc[0] == 0 && sc[1] == 0 && (uint32_t)sc[2] == img.width && (uint32_t)sc[3] == img.height;
if (whole && !(d->rendering.encoder != nil && d->rendering.view == view)) {
// Clearing the whole render target is done by the load action of a new render pass
start_render_pass(d, &img, view, color);
return;
}
// Otherwise draw a quad with the clear color, restricted to the scissor rectangle
if (!begin_rendering(d)) return;
id<MTLRenderPipelineState> ps = utility_pipeline(d, false, d->rendering.format);
if (ps == nil) return;
id<MTLRenderCommandEncoder> enc = d->rendering.encoder;
[enc setRenderPipelineState:ps];
d->rendering.pipeline = ps;
// Clears are not affected by the viewport
const MTLViewport vp = {.originX = 0, .originY = 0, .width = (double)img.width, .height = (double)img.height, .znear = 0, .zfar = 1};
[enc setViewport:vp];
d->rendering.viewport_valid = false;
apply_scissor(d, sc);
[enc setFragmentBytes:color length:sizeof(color) atIndex:0];
// That replaced the buffer used for the push constants of kitty's pipelines
d->rendering.push_constants_of = NULL;
[enc drawPrimitives:MTLPrimitiveTypeTriangleStrip vertexStart:0 vertexCount:4];
}
void
set_viewport(void *driver, int32_t x, int32_t y, uint32_t width, uint32_t height) {
Driver *d = driver;
d->viewport[0] = x;
d->viewport[1] = y;
d->viewport[2] = (int32_t)width;
d->viewport[3] = (int32_t)height;
}
void
get_viewport(void *driver, int32_t ans[4]) {
memcpy(ans, ((Driver *)driver)->viewport, sizeof(int32_t) * 4);
}
void
set_scissor(void *driver, bool enabled, int32_t x, int32_t y, uint32_t width, uint32_t height) {
Driver *d = driver;
d->scissor.enabled = enabled;
d->scissor.rect[0] = x;
d->scissor.rect[1] = y;
d->scissor.rect[2] = (int32_t)width;
d->scissor.rect[3] = (int32_t)height;
}
void
set_srgb_output(void *driver, bool enabled) {
// Takes effect at the next draw, which uses the corresponding view of the render target
((Driver *)driver)->srgb_output = enabled;
}
// }}}
// Drawing {{{
// Check that the textures used by the pipeline are bound and are not being rendered into
static bool
check_textures(Driver *d, const Pipeline *p) {
RenderImage target = {0};
const bool has_target = target_image(d, &target);
for (size_t i = 0; i < p->num_bindings; i++) {
const PipelineBinding *b = p->bindings + i;
if (b->kind != GPU_BINDING_TEXTURE) continue;
const Texture *t = d->bound_textures[b->slot];
if (!t || t->texture == nil) {
log_error(d, "No texture is bound to the slot: %u used by the texture: %s", b->slot, b->name);
return false;
}
if (has_target && target.texture == t->texture) {
log_error(d, "Cannot sample from the texture: %s while rendering into it", b->name);
return false;
}
// A pass rendering into the texture must end before it can be sampled
if (d->rendering.texture == t->texture) end_rendering(d);
}
return true;
}
// The uniform buffer bound to a slot, either a parameter block of the pipeline or a buffer bound by kitty
static Buffer *
uniform_buffer_for_slot(Driver *d, const Pipeline *p, uint32_t slot) {
for (size_t i = 0; i < p->num_param_blocks; i++) {
if (p->param_blocks[i].slot == (int32_t)slot) return p->param_blocks[i].buffer;
}
return d->bound_buffers[slot];
}
static bool
bind_resources(Driver *d, id<MTLRenderCommandEncoder> enc, const Pipeline *p) {
for (size_t i = 0; i < p->num_bindings; i++) {
const PipelineBinding *b = p->bindings + i;
if (b->kind == GPU_BINDING_TEXTURE) {
const Texture *t = d->bound_textures[b->slot];
const NSUInteger ti = (NSUInteger)b->texture_index, si = (NSUInteger)b->sampler_index;
[enc setVertexTexture:t->texture atIndex:ti];
[enc setFragmentTexture:t->texture atIndex:ti];
[enc setVertexSamplerState:t->sampler atIndex:si];
[enc setFragmentSamplerState:t->sampler atIndex:si];
} else {
Buffer *buf = uniform_buffer_for_slot(d, p, b->slot);
if (!buf || buf->storage.buffer == nil) {
log_error(d, "No uniform buffer is bound to the slot: %u used by the uniform block: %s", b->slot, b->name);
return false;
}
use_buffer(d, buf);
const NSUInteger bi = (NSUInteger)b->buffer_index;
[enc setVertexBuffer:buf->storage.buffer offset:0 atIndex:bi];
[enc setFragmentBuffer:buf->storage.buffer offset:0 atIndex:bi];
}
}
return true;
}
static bool
bind_vertex_buffers(Driver *d, id<MTLRenderCommandEncoder> enc, const PipelineVariantKey *key) {
for (uint32_t loc = 0; loc < MAX_VERTEX_ATTRIBUTES; loc++) {
if (key->inputs[loc].format == MTLVertexFormatInvalid) continue;
const VertexAttribute *a = d->vertex_layout->attributes + loc;
size_t offset;
uint32_t stride;
id<MTLBuffer> buf = vertex_buffer_for(d, a, vertex_attribute_size(a->components, a->type), &offset, &stride);
if (buf == nil) {
log_error(d, "The vertex buffer for the vertex input at location: %u has no storage", loc);
return false;
}
[enc setVertexBuffer:buf offset:offset atIndex:VERTEX_BUFFER_INDEX(loc)];
}
return true;
}
void
draw_quad(void *driver, uint32_t instance_count, GPUBlendMode blend) {
Driver *d = driver;
Pipeline *p = d->pipeline;
if (!p) return;
@autoreleasepool {
if (!check_textures(d, p) || !begin_rendering(d)) return;
int32_t sc[4];
current_scissor(d, d->rendering.width, d->rendering.height, sc);
if (sc[2] <= 0 || sc[3] <= 0) return;
PipelineVariantKey key;
id<MTLRenderPipelineState> ps = pipeline_for_current_state(d, blend == GPU_BLEND_PREMULTIPLIED_ALPHA, &key);
if (ps == nil) return;
id<MTLRenderCommandEncoder> enc = d->rendering.encoder;
if (d->rendering.pipeline != ps) {
[enc setRenderPipelineState:ps];
d->rendering.pipeline = ps;
}
if (!d->rendering.viewport_valid || memcmp(d->rendering.viewport, d->viewport, sizeof(d->viewport)) != 0) {
const MTLViewport v = {
.originX = d->viewport[0], .originY = d->viewport[1], .width = d->viewport[2], .height = d->viewport[3], .znear = 0, .zfar = 1};
[enc setViewport:v];
memcpy(d->rendering.viewport, d->viewport, sizeof(d->viewport));
d->rendering.viewport_valid = true;
}
apply_scissor(d, sc);
if (p->push_constants_index >= 0 && (d->rendering.push_constants_of != p || d->rendering.push_constants_dirty)) {
// The block is used by every stage, see GPUParamBlock
const NSUInteger idx = (NSUInteger)p->push_constants_index;
[enc setVertexBytes:p->push_constants length:PUSH_CONSTANTS_SIZE atIndex:idx];
[enc setFragmentBytes:p->push_constants length:PUSH_CONSTANTS_SIZE atIndex:idx];
d->rendering.push_constants_of = p;
d->rendering.push_constants_dirty = false;
}
if (!bind_resources(d, enc, p)) return;
if (d->vertex_layout && !bind_vertex_buffers(d, enc, &key)) return;
[enc drawIndexedPrimitives:MTLPrimitiveTypeTriangle
indexCount:6
indexType:MTLIndexTypeUInt16
indexBuffer:d->quad_indices
indexBufferOffset:0
instanceCount:MAX(1u, instance_count)];
}
}
// }}}
// Render targets and reading back {{{
gpu_render_target_t
render_target_create(void *driver, gpu_texture_t color_texture) {
Driver *d = driver;
RenderTarget *rt = calloc(1, sizeof(RenderTarget));
if (!rt) {
set_error(d, "Out of memory");
return GPU_NULL_HANDLE;
}
rt->texture = AS_TEXTURE(color_texture);
return AS_HANDLE(rt);
}
void
render_target_destroy(void *driver, gpu_render_target_t target) {
Driver *d = driver;
RenderTarget *rt = AS_RENDER_TARGET(target);
if (!rt) return;
if (d->render_target == rt) {
end_rendering(d);
d->render_target = NULL;
}
free(rt);
}
void
set_render_target(void *driver, gpu_render_target_t target) {
// Rendering switches to the new target at the next draw
((Driver *)driver)->render_target = AS_RENDER_TARGET(target);
}
gpu_render_target_t
get_render_target(void *driver) {
return AS_HANDLE(((Driver *)driver)->render_target);
}
const char *
render_target_status(void *driver, gpu_render_target_t target) {
const Driver *d = driver;
// The drawable of the window surface is acquired lazily, so is always usable
if (!target) return d->current_surface ? NULL : "No surface is current";
const RenderTarget *rt = AS_RENDER_TARGET(target);
if (!rt->texture || rt->texture->texture == nil) return "No texture";
if (rt->texture->unorm_view == nil) return "The texture format cannot be rendered to";
return NULL;
}
void
read_pixels(void *driver, int32_t x, int32_t y, uint32_t width, uint32_t height, void *dst) {
Driver *d = driver;
if (!width || !height) return;
@autoreleasepool {
RenderImage img;
if (!target_image(d, &img)) return;
if (x < 0 || y < 0 || (uint64_t)x + width > img.width || (uint64_t)y + height > img.height) {
log_error(d, "Reading pixels outside the render target");
return;
}
// The raw contents of the image, without decoding sRGB, as in the Vulkan driver
const MTLPixelFormat format = [img.texture pixelFormat];
const size_t bpp = bytes_per_pixel(format), row = (size_t)width * bpp, size = row * height;
id<MTLBuffer> buf = [d->device newBufferWithLength:size options:MTLResourceStorageModeShared];
if (buf == nil) {
log_error(d, "Failed to allocate memory for reading back pixels");
return;
}
[blit_encoder(d) copyFromTexture:img.texture
sourceSlice:0
sourceLevel:0
sourceOrigin:MTLOriginMake((NSUInteger)x, (NSUInteger)y, 0)
sourceSize:MTLSizeMake(width, height, 1)
toBuffer:buf
destinationOffset:0
destinationBytesPerRow:row
destinationBytesPerImage:size];
submit_commands(d, true);
convert_to_rgba8(format, [buf contents], dst, (size_t)width * height);
[buf release];
}
}
void
copy_to_texture(void *driver, gpu_texture_t dst, int32_t x, int32_t y, uint32_t width, uint32_t height) {
Driver *d = driver;
Texture *t = AS_TEXTURE(dst);
if (!t || t->texture == nil || !width || !height) return;
@autoreleasepool {
RenderImage img;
if (!target_image(d, &img)) return;
if (x < 0 || y < 0 || (uint64_t)x + width > img.width || (uint64_t)y + height > img.height || width > [t->texture width] ||
height > [t->texture height]) {
log_error(d, "Copying pixels outside the render target or the texture");
return;
}
// Copy the raw contents, without decoding sRGB
id<MTLTexture> src = img.unorm_view != nil ? img.unorm_view : img.texture;
if ([src pixelFormat] == [t->texture pixelFormat]) {
[blit_encoder(d) copyFromTexture:src
sourceSlice:0
sourceLevel:0
sourceOrigin:MTLOriginMake((NSUInteger)x, (NSUInteger)y, 0)
sourceSize:MTLSizeMake(width, height, 1)
toTexture:t->texture
destinationSlice:0
destinationLevel:0
destinationOrigin:MTLOriginMake(0, 0, 0)];
return;
}
// Blits cannot convert between formats, such as from the BGRA
// drawables of windows, so draw instead
if (t->unorm_view == nil) {
log_error(d, "Cannot copy into a texture of this format");
return;
}
id<MTLRenderPipelineState> ps = utility_pipeline(d, true, [t->unorm_view pixelFormat]);
if (ps == nil) return;
const RenderImage dest = {
.texture = t->texture, .unorm_view = t->unorm_view, .width = (uint32_t)[t->texture width], .height = (uint32_t)[t->texture height]};
start_render_pass(d, &dest, t->unorm_view, NULL);
id<MTLRenderCommandEncoder> enc = d->rendering.encoder;
[enc setRenderPipelineState:ps];
const MTLViewport vp = {.originX = 0, .originY = 0, .width = (double)width, .height = (double)height, .znear = 0, .zfar = 1};
[enc setViewport:vp];
[enc setScissorRect:(MTLScissorRect){.x = 0, .y = 0, .width = width, .height = height}];
[enc setFragmentTexture:src atIndex:0];
const int32_t origin[2] = {x, y};
[enc setFragmentBytes:origin length:sizeof(origin) atIndex:0];
[enc drawPrimitives:MTLPrimitiveTypeTriangleStrip vertexStart:0 vertexCount:4];
// Rendering continues into the current render target at the next draw
end_rendering(d);
}
}
// }}}

291
gpu/metal/driver.m Normal file
View file

@ -0,0 +1,291 @@
/*
* driver.m
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// The Metal implementation of the kitty GPU driver API, see ../api.h and
// internal.h for an overview.
#include "internal.h"
#include "version.h"
#import <CoreGraphics/CGDirectDisplayMetal.h>
// There is only ever one driver per process
static Driver *the_driver = NULL;
// Errors {{{
void
set_error(Driver *d, const char *fmt, ...) {
va_list ap;
va_start(ap, fmt);
vsnprintf(d->last_error, sizeof(d->last_error), fmt, ap);
va_end(ap);
}
void
log_error(Driver *d, const char *fmt, ...) {
char buf[4096];
va_list ap;
va_start(ap, fmt);
vsnprintf(buf, sizeof(buf), fmt, ap);
va_end(ap);
d->params.log_error(buf);
}
void
debug_print(Driver *d, const char *fmt, ...) {
if (!d->params.debug_rendering) return;
char buf[4096];
va_list ap;
va_start(ap, fmt);
vsnprintf(buf, sizeof(buf), fmt, ap);
va_end(ap);
d->params.debug_print(buf);
}
void
fatal(Driver *d, const char *fmt, ...) {
char buf[4096];
va_list ap;
va_start(ap, fmt);
vsnprintf(buf, sizeof(buf), fmt, ap);
va_end(ap);
d->params.fatal(buf);
abort();
}
const char *
error_description(NSError *err) {
if (err == nil) return "unknown error";
const char *ans = [[err localizedDescription] UTF8String];
return ans ? ans : "unknown error";
}
// }}}
// Device {{{
static id<MTLDevice>
choose_device(Driver *d) {
// Use the GPU driving the main display, which avoids copying rendered
// frames between GPUs and, on machines with automatic graphics switching,
// does not force a switch to the discrete GPU.
id<MTLDevice> ans = CGDirectDisplayCopyCurrentMetalDevice(CGMainDisplayID());
if (ans == nil) {
debug_print(d, "Metal: Could not get the GPU driving the main display, using the system default GPU");
ans = MTLCreateSystemDefaultDevice();
}
return ans;
}
static bool
create_shared_objects(Driver *d) {
// The indices of the two triangles covering a quad, see draw_quad() in ../api.h
static const uint16_t indices[6] = {0, 1, 2, 0, 2, 3};
d->quad_indices = [d->device newBufferWithBytes:indices length:sizeof(indices) options:MTLResourceStorageModeShared];
if (d->quad_indices == nil) {
set_error(d, "Failed to create a Metal buffer");
return false;
}
d->in_flight = dispatch_semaphore_create(NUM_IN_FLIGHT);
if (!d->in_flight) {
set_error(d, "Failed to create a semaphore");
return false;
}
d->next_serial = 1;
return create_samplers(d) && create_utility_pipelines(d);
}
// }}}
// Lifecycle {{{
static const char *
shader_target(void *driver UNUSED) {
#define S(x) #x
#define TARGET(v) "msl-" S(v)
return TARGET(MSL_VERSION);
#undef TARGET
#undef S
}
static bool
connect_to_display(void *driver, const GPUNativeWindow *display) {
Driver *d = driver;
if (display->platform != GPU_PLATFORM_COCOA) {
set_error(d, "The Metal driver supports only Cocoa");
return false;
}
@autoreleasepool {
d->device = choose_device(d);
if (d->device == nil) {
set_error(d, "No Metal capable GPU found");
return false;
}
// MSL 2.4 needs macOS 12, every Mac that can run it supports the Mac2 or Apple7 GPU families
if (![d->device supportsFamily:MTLGPUFamilyMac2] && ![d->device supportsFamily:MTLGPUFamilyApple7]) {
set_error(d, "The GPU %s does not support the Metal features needed by kitty", [[d->device name] UTF8String]);
return false;
}
d->queue = [d->device newCommandQueueWithMaxCommandBufferCount:NUM_IN_FLIGHT + 1];
if (d->queue == nil) {
set_error(d, "Failed to create a Metal command queue");
return false;
}
[d->queue setLabel:@"kitty"];
if (!create_shared_objects(d)) return false;
snprintf(d->version_string, sizeof(d->version_string), "Metal (MSL %d.%d) on %s", MSL_VERSION / 10, MSL_VERSION % 10, [[d->device name] UTF8String]);
}
debug_print(d, "Using %s", d->version_string);
return true;
}
static bool
initialize(void *driver) {
Driver *d = driver;
if (d->device == nil) {
set_error(d, "The Metal driver was not connected to a display");
return false;
}
d->initialized = true;
return true;
}
static void
destroy(void *driver) {
Driver *d = driver;
@autoreleasepool {
if (d->device != nil) {
release_native_resources(d);
if (d->cmd != nil) submit_commands(d, false);
// Acquiring every slot ensures the completed handlers of all
// command buffers have run, as they access the driver
if (d->in_flight) wait_for_idle(d);
release_staging(d);
destroy_all_pipelines(d);
destroy_all_textures(d);
destroy_all_buffers(d);
while (d->vertex_layouts) vertex_layout_destroy(d, AS_HANDLE(d->vertex_layouts));
destroy_utility_pipelines(d);
destroy_samplers(d);
[d->quad_indices release];
[d->queue release];
[d->device release];
}
if (d->in_flight) dispatch_release(d->in_flight);
}
if (the_driver == d) the_driver = NULL;
free(d);
}
static const char *
last_error(void *driver) {
return ((Driver *)driver)->last_error;
}
static const char *
version_string(void *driver) {
return ((Driver *)driver)->version_string;
}
static void
get_capabilities(void *driver, GPUCapabilities *ans) {
Driver *d = driver;
ans->max_texture_size = MAX_TEXTURE_SIZE;
ans->max_array_texture_layers = MAX_TEXTURE_LAYERS;
// Any texture can be viewed with the sRGB variant of its pixel format, including drawables
ans->supports_srgb_output = d->device != nil;
}
// }}}
__attribute__((visibility("default"))) bool
kitty_gpu_driver_load(uint32_t api_version, const GPUDriverInitParams *params, GPUDriverAPI *api, void **driver, char *errbuf, size_t errbuf_size) {
if (api_version != KITTY_GPU_API_VERSION) {
snprintf(errbuf, errbuf_size, "The Metal driver supports GPU API version %u but version %u was requested", KITTY_GPU_API_VERSION, api_version);
return false;
}
if (!params->log_error || !params->fatal || !params->debug_print) {
snprintf(errbuf, errbuf_size, "The Metal driver was not passed all required callbacks");
return false;
}
if (the_driver) {
snprintf(errbuf, errbuf_size, "The Metal driver has already been loaded");
return false;
}
Driver *d = calloc(1, sizeof(Driver));
if (!d) {
snprintf(errbuf, errbuf_size, "Out of memory allocating the Metal driver");
return false;
}
d->params = *params;
the_driver = d;
*api = (GPUDriverAPI){
.api_version = KITTY_GPU_API_VERSION,
.name = "Metal",
#define F(name) .name = name
F(shader_target),
.connect = connect_to_display,
F(initialize),
F(destroy),
F(last_error),
F(version_string),
F(get_capabilities),
F(texture_create),
F(texture_reset),
F(texture_destroy),
F(texture_upload),
F(texture_copy),
F(texture_read),
F(texture_get_desc),
F(bind_texture),
F(buffer_create),
F(buffer_destroy),
F(buffer_allocate),
F(buffer_map),
F(buffer_unmap),
F(buffer_copy),
F(bind_uniform_buffer),
F(pipeline_create),
F(pipeline_destroy),
F(use_pipeline),
F(pipeline_uniform_block),
F(pipeline_attribute_location),
F(set_params),
F(vertex_layout_create),
F(vertex_layout_destroy),
F(bind_vertex_layout),
F(vertex_layout_set_attribute),
F(choose_native_visual),
F(surface_create),
F(surface_destroy),
F(make_surface_current),
F(get_current_surface),
F(surface_resize),
F(surface_present),
F(surface_set_swap_interval),
F(surface_native_changed),
F(surface_recreate),
F(release_native_resources),
F(render_target_create),
F(render_target_destroy),
F(set_render_target),
F(get_render_target),
F(render_target_status),
F(clear),
F(set_viewport),
F(get_viewport),
F(set_scissor),
F(set_srgb_output),
F(read_pixels),
F(copy_to_texture),
F(draw_quad),
#undef F
};
*driver = d;
return true;
}

462
gpu/metal/internal.h Normal file
View file

@ -0,0 +1,462 @@
/*
* internal.h
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// Types and functions shared between the files of the Metal driver.
//
// Overview of how the driver implements the immediate mode API in ../api.h,
// it follows the design of the Vulkan driver, simplified by the things Metal
// does automatically:
//
// * Commands are encoded into the current command buffer, created when first
// needed. It is committed when a surface is presented, or when the CPU
// needs the results, such as when reading back pixels. At most
// NUM_IN_FLIGHT command buffers are in flight, creating a new one waits
// for the oldest to complete, which throttles the CPU.
// * Every command buffer has a serial number, the completed handler of the
// command buffer records when it has completed. It runs on a thread owned
// by Metal, so it only touches atomics and the in flight semaphore.
// * Command buffers retain the resources used by the commands encoded into
// them, so objects can be released as soon as kitty destroys them. Metal
// also tracks hazards between passes automatically, so no barriers are
// needed.
// * Rendering into the current render target is done with a render command
// encoder, begun lazily by the first draw or clear and ended when the
// render target changes or a blit is needed, such as for uploading pixels
// to a texture. Render passes always load and store the contents of the
// render target, except for clears of the whole render target, which use
// a clear load action.
// * Buffers live in shared memory and are only ever written by the CPU.
// Writing to a buffer that encoded commands might still read gives it new
// storage, so that, as with OpenGL, commands use the contents the buffer
// had when they were encoded. Textures are private to the GPU and pixels
// are uploaded with blits from staging memory, so uploads are ordered with
// respect to draws, as in OpenGL.
// * Textures are bound with set{Vertex,Fragment}Texture() and
// set{Vertex,Fragment}SamplerState(), uniform buffers with
// set{Vertex,Fragment}Buffer() and the push constant block of pipelines
// with set{Vertex,Fragment}Bytes(), at the argument table indices
// assigned by the shader compiler, which are passed to the driver as native
// names, see MSL_PUSH_CONSTANTS_NAME in kitty/shaders/slang.py.
// * Vertex inputs each use a buffer of their own, at the highest buffer
// argument table indices, see VERTEX_BUFFER_INDEX.
//
// The code uses manual reference counting, not ARC, like the rest of the
// Objective-C code in kitty. Objects that are kept are owned by the driver,
// either because they were obtained from methods whose names begin with
// new/alloc/copy, or because they were retained. Every API function that can
// create autoreleased objects drains an autorelease pool, as kitty's render
// loop is not guaranteed to run inside one.
#pragma once
#define _GNU_SOURCE // for strdup() with glibc, has no effect on Darwin
#include "../api.h"
#import <Cocoa/Cocoa.h>
#import <Metal/Metal.h>
#import <QuartzCore/CAMetalLayer.h>
#include <stdarg.h>
#include <stdatomic.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#define UNUSED __attribute__((unused))
#define arraysz(x) (sizeof(x) / sizeof(x[0]))
#ifndef MIN
#define MIN(x, y) ((x) < (y) ? (x) : (y))
#endif
#ifndef MAX
#define MAX(x, y) ((x) > (y) ? (x) : (y))
#endif
#define AS_HANDLE(ptr) ((uint64_t)(uintptr_t)(ptr))
// The maximum number of command buffers submitted to the GPU and not yet completed
#define NUM_IN_FLIGHT 3
// The maximum number of binding slots of textures and uniform buffers, the
// slots used by kitty are much smaller than this
#define MAX_BINDING_SLOTS 32
// The maximum number of vertex inputs
#define MAX_VERTEX_ATTRIBUTES 16
// The maximum size of the push constant block, see GPUParamBlock
#define PUSH_CONSTANTS_SIZE 128
// Metal has 31 entries in the buffer argument table of each stage. Vertex
// buffers use the highest of them, one per vertex input location, the buffers
// used by shaders must have indices below MAX_SHADER_BUFFER_INDEX.
#define NUM_BUFFER_INDICES 31
#define VERTEX_BUFFER_INDEX(location) (NUM_BUFFER_INDICES - 1 - (location))
#define MAX_SHADER_BUFFER_INDEX (NUM_BUFFER_INDICES - MAX_VERTEX_ATTRIBUTES)
// The maximum number of texture and sampler argument table entries used by shaders
#define MAX_SHADER_TEXTURE_INDEX 31
#define MAX_SHADER_SAMPLER_INDEX 16
// The native name of the push constant block, must match MSL_PUSH_CONSTANTS_NAME in kitty/shaders/slang.py
#define MSL_PUSH_CONSTANTS_NAME "push_constants"
// The maximum number of staging buffers kept for reuse
#define MAX_STAGING_CHUNKS 16
// The size of the staging buffers that small uploads are sub-allocated from
#define STAGING_CHUNK_SIZE (4u * 1024u * 1024u)
// The limits of the Mac2 and Apple7 GPU families, see the Metal feature set tables
#define MAX_TEXTURE_SIZE 16384u
#define MAX_TEXTURE_LAYERS 2048u
// The maximum number of render target pixel formats for the utility pipelines, see Driver
#define MAX_UTILITY_FORMATS 8
// Resources {{{
typedef struct BufferStorage {
id<MTLBuffer> buffer;
size_t size;
uint64_t last_use_serial;
} BufferStorage;
typedef struct Buffer {
GPUBufferKind kind;
GPUUpdateFrequency frequency;
BufferStorage storage; // the current storage, size zero if not yet allocated
// Storage that commands might still use, reusable once the serial completes
BufferStorage retired[4];
size_t num_retired;
// Incremented whenever the contents of the buffer change
uint64_t generation;
// A copy of the contents with the elements of a vertex input moved to
// offsets and strides that are multiples of four bytes, as required by
// Metal, see repacked_vertex_buffer()
struct {
id<MTLBuffer> buffer;
uint64_t generation;
size_t offset, size;
uint32_t stride, element_size;
} repacked;
struct Buffer *prev, *next;
} Buffer;
typedef struct Texture {
GPUTextureDesc desc;
MTLPixelFormat format;
id<MTLTexture> texture;
// Views for rendering without and with encoding to sRGB, see
// set_srgb_output(). unorm_view is nil if the texture cannot be rendered
// to and srgb_view is nil if the texture is not sRGB encoded. They can be
// the texture itself.
id<MTLTexture> unorm_view, srgb_view;
id<MTLSamplerState> sampler; // owned by the driver, see Driver.samplers
struct Texture *prev, *next;
} Texture;
typedef struct VertexAttribute {
bool enabled;
Buffer *buffer;
uint32_t components, stride, divisor;
GPUAttribType type;
size_t offset;
} VertexAttribute;
typedef struct VertexLayout {
VertexAttribute attributes[MAX_VERTEX_ATTRIBUTES];
struct VertexLayout *prev, *next;
} VertexLayout;
typedef struct VertexInputKey {
MTLVertexFormat format; // MTLVertexFormatInvalid for unused inputs
uint32_t stride, step_rate;
bool per_instance;
} VertexInputKey;
typedef struct PipelineVariantKey {
MTLPixelFormat color_format;
bool blend;
VertexInputKey inputs[MAX_VERTEX_ATTRIBUTES];
} PipelineVariantKey;
typedef struct PipelineVariant {
PipelineVariantKey key;
id<MTLRenderPipelineState> state;
} PipelineVariant;
typedef struct PipelineBinding {
GPUBindingKind kind;
uint32_t slot;
char *name;
// The argument table indices, from the native name of the binding
int32_t buffer_index, texture_index, sampler_index;
} PipelineBinding;
typedef struct ParamBlock {
int32_t slot; // -1 for the push constant block
uint32_t size;
Buffer *buffer; // the uniform buffer holding the contents of blocks with a slot
} ParamBlock;
typedef struct Pipeline {
id<MTLFunction> vertex_function, fragment_function;
PipelineBinding *bindings;
size_t num_bindings;
ParamBlock *param_blocks;
size_t num_param_blocks;
uint8_t push_constants[PUSH_CONSTANTS_SIZE];
uint32_t push_constants_size;
int32_t push_constants_index; // the buffer argument table index of the push constant block, -1 if none
uint32_t vertex_inputs; // bit mask of the locations of the inputs used by the vertex function
uint32_t declared_inputs; // bit mask of the locations of all inputs declared by the vertex function
PipelineVariant *variants;
size_t num_variants, variants_capacity;
struct Pipeline *prev, *next;
} Pipeline;
typedef struct RenderTarget {
Texture *texture;
} RenderTarget;
// Something that can be rendered into, a texture or the drawable of a surface
typedef struct RenderImage {
id<MTLTexture> texture; // the texture itself, for blits and reading back
id<MTLTexture> unorm_view, srgb_view;
uint32_t width, height;
} RenderImage;
// }}}
// Surfaces {{{
typedef struct Surface {
NSView *view;
CAMetalLayer *layer;
GPUSurfaceConfig config;
uint32_t width, height; // the size of the window framebuffer
int swap_interval;
// The drawable being rendered into, acquired by the first rendering after
// the surface was last presented, along with its view for encoding to sRGB
id<CAMetalDrawable> drawable;
id<MTLTexture> drawable_srgb_view;
struct Surface *prev, *next;
} Surface;
// }}}
typedef struct StagingChunk {
id<MTLBuffer> buffer;
size_t used;
uint64_t serial; // the serial of the command buffer using the chunk
} StagingChunk;
typedef struct UtilityPipeline {
MTLPixelFormat format;
id<MTLRenderPipelineState> state;
} UtilityPipeline;
typedef struct Driver {
GPUDriverInitParams params;
char last_error[8192];
char version_string[512];
id<MTLDevice> device;
id<MTLCommandQueue> queue;
bool initialized;
// Command buffers
id<MTLCommandBuffer> cmd; // the command buffer being encoded, nil if none
uint64_t cmd_serial; // the serial of cmd
uint64_t next_serial; // the serial of the next command buffer to be created
_Atomic uint64_t completed_serial; // the serial of the last command buffer that completed
// Set by the completed handler of the first command buffer that fails, along
// with a description of the failure, reported by check_gpu_errors()
_Atomic bool gpu_error_pending;
char gpu_error[1024];
dispatch_semaphore_t in_flight;
id<MTLBlitCommandEncoder> blit; // the active blit encoder, nil if none
StagingChunk staging[MAX_STAGING_CHUNKS];
size_t num_staging;
// Shared objects
id<MTLBuffer> quad_indices;
id<MTLSamplerState> samplers[2][4][2]; // [filter][wrap][is_integer]
// Pipelines used by the driver itself, for clearing rectangles and for
// copying between textures of different formats, one per render target format
id<MTLLibrary> utility_library;
id<MTLFunction> fullscreen_vertex, clear_fragment, copy_fragment;
UtilityPipeline clear_pipelines[MAX_UTILITY_FORMATS], copy_pipelines[MAX_UTILITY_FORMATS];
size_t num_clear_pipelines, num_copy_pipelines;
// Live objects, destroyed with the driver
Texture *textures;
Buffer *buffers;
Pipeline *pipelines;
VertexLayout *vertex_layouts;
Surface *surfaces;
// Current state, see "current" state in ../api.h
Surface *current_surface;
RenderTarget *render_target; // NULL for the window
int32_t viewport[4];
struct {
bool enabled;
int32_t rect[4];
} scissor;
bool srgb_output;
Pipeline *pipeline;
VertexLayout *vertex_layout;
Texture *bound_textures[MAX_BINDING_SLOTS];
Buffer *bound_buffers[MAX_BINDING_SLOTS];
// The active render command encoder and the state set on it
struct {
id<MTLRenderCommandEncoder> encoder; // nil if no render pass is active
id<MTLTexture> view; // the attachment being rendered into
id<MTLTexture> texture; // the texture the attachment is a view of
MTLPixelFormat format;
uint32_t width, height;
id<MTLRenderPipelineState> pipeline;
Pipeline *push_constants_of; // the pipeline whose push constants were last set
bool push_constants_dirty;
int32_t viewport[4], scissor[4];
bool viewport_valid, scissor_valid;
} rendering;
} Driver;
// driver.m
void set_error(Driver *d, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
void log_error(Driver *d, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
void debug_print(Driver *d, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
void fatal(Driver *d, const char *fmt, ...) __attribute__((format(printf, 2, 3), noreturn));
// The description of an NSError, never NULL
const char *error_description(NSError *err);
// commands.m
// The command buffer to encode into, creating it if needed
id<MTLCommandBuffer> command_buffer(Driver *d);
// The serial of the command buffer being encoded
uint64_t recording_serial(Driver *d);
uint64_t completed_serial(Driver *d);
// Commit the command buffer being encoded, if any. If wait is true, waits for it to complete.
void submit_commands(Driver *d, bool wait);
// Wait until all committed command buffers have completed
void wait_for_idle(Driver *d);
// The active blit encoder, ending any render pass
id<MTLBlitCommandEncoder> blit_encoder(Driver *d);
// End the active render pass and blit encoder, if any
void end_encoding(Driver *d);
// End the active render pass, if any
void end_rendering(Driver *d);
// Report errors from command buffers that failed
void check_gpu_errors(Driver *d);
// Staging memory for uploads in the command buffer being encoded, valid until it completes
bool allocate_staging(Driver *d, size_t size, size_t alignment, id<MTLBuffer> *buffer, size_t *offset, void **mapped);
void release_staging(Driver *d);
bool create_utility_pipelines(Driver *d);
void destroy_utility_pipelines(Driver *d);
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);
void set_srgb_output(void *driver, bool enabled);
void read_pixels(void *driver, int32_t x, int32_t y, uint32_t width, uint32_t height, void *dst);
void copy_to_texture(void *driver, gpu_texture_t dst, int32_t x, int32_t y, uint32_t width, uint32_t height);
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);
void set_render_target(void *driver, gpu_render_target_t target);
gpu_render_target_t get_render_target(void *driver);
const char *render_target_status(void *driver, gpu_render_target_t target);
void draw_quad(void *driver, uint32_t instance_count, GPUBlendMode blend);
// buffers.m
gpu_buffer_t buffer_create(void *driver, GPUBufferKind kind);
void buffer_destroy(void *driver, gpu_buffer_t buffer);
void buffer_allocate(void *driver, gpu_buffer_t buffer, size_t size, GPUUpdateFrequency frequency);
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);
void bind_uniform_buffer(void *driver, uint32_t slot, gpu_buffer_t buffer);
// Mark the current storage of the buffer as used by the commands being encoded
void use_buffer(Driver *d, Buffer *b);
// Write data to the start of the buffer, giving it new storage if commands might still use the current one
bool write_buffer(Driver *d, Buffer *b, const void *data, size_t size);
// The buffer and offset to use for a vertex input, repacking its elements if
// their offset or stride are not multiples of four bytes. Sets stride to the
// stride of the elements in the returned buffer. nil on failure.
id<MTLBuffer> vertex_buffer_for(Driver *d, const VertexAttribute *a, size_t element_size, size_t *offset, uint32_t *stride);
// The stride of the elements of a vertex input in the buffer returned by vertex_buffer_for()
uint32_t vertex_buffer_stride(const VertexAttribute *a, size_t element_size);
void destroy_all_buffers(Driver *d);
// textures.m
bool create_samplers(Driver *d);
void destroy_samplers(Driver *d);
gpu_texture_t texture_create(void *driver, const GPUTextureDesc *desc, const GPUPixelData *initial);
bool texture_reset(void *driver, gpu_texture_t texture, const GPUTextureDesc *desc, const GPUPixelData *initial);
void texture_destroy(void *driver, gpu_texture_t 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);
void texture_copy(void *driver, gpu_texture_t src, gpu_texture_t dst);
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);
void bind_texture(void *driver, uint32_t slot, gpu_texture_t texture);
void destroy_all_textures(Driver *d);
// The number of bytes per pixel of textures of the format
size_t bytes_per_pixel(MTLPixelFormat f);
// Convert pixels read back from a texture of the specified format to tightly packed RGBA8
void convert_to_rgba8(MTLPixelFormat format, const uint8_t *src, uint8_t *dst, size_t num_pixels);
// pipelines.m
gpu_pipeline_t pipeline_create(
void *driver,
const GPUShaderSource *sources,
size_t num_sources,
const GPUParamBlock *param_blocks,
size_t num_param_blocks,
const GPUBinding *bindings,
size_t num_bindings,
const GPUNativeName *native_names,
size_t num_native_names);
void pipeline_destroy(void *driver, gpu_pipeline_t pipeline);
void use_pipeline(void *driver, gpu_pipeline_t pipeline);
bool pipeline_uniform_block(void *driver, gpu_pipeline_t pipeline, const char *name, GPUUniformBlockInfo *ans);
int32_t pipeline_attribute_location(void *driver, gpu_pipeline_t pipeline, const char *name);
void set_params(void *driver, gpu_pipeline_t pipeline, uint32_t block, const void *data, size_t size);
gpu_vertex_layout_t vertex_layout_create(void *driver);
void vertex_layout_destroy(void *driver, gpu_vertex_layout_t layout);
void bind_vertex_layout(void *driver, gpu_vertex_layout_t layout);
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);
// The size in bytes of one element of a vertex input
size_t vertex_attribute_size(uint32_t components, GPUAttribType type);
// The pipeline state for drawing with the current state, with its key in
// key, nil on failure. Must be called with a render pass active.
id<MTLRenderPipelineState> pipeline_for_current_state(Driver *d, bool blend, PipelineVariantKey *key);
void destroy_all_pipelines(Driver *d);
// surfaces.m
bool choose_native_visual(void *driver, const GPUNativeWindow *native, const GPUSurfaceConfig *config, uint64_t *visual_id);
gpu_surface_t surface_create(void *driver, const GPUNativeWindow *native, const GPUSurfaceConfig *config, uint32_t width, uint32_t height);
void surface_destroy(void *driver, gpu_surface_t surface);
bool make_surface_current(void *driver, gpu_surface_t surface);
gpu_surface_t get_current_surface(void *driver);
void surface_resize(void *driver, gpu_surface_t surface, uint32_t width, uint32_t height);
bool surface_present(void *driver, gpu_surface_t surface);
void surface_set_swap_interval(void *driver, gpu_surface_t surface, int interval);
void surface_native_changed(void *driver, gpu_surface_t surface);
bool surface_recreate(void *driver, gpu_surface_t surface);
void release_native_resources(void *driver);
// The drawable of the current surface to render into, acquiring it if needed. false on failure.
bool current_surface_image(Driver *d, RenderImage *ans);
// Intrusive doubly linked lists of live objects
#define LIST_ADD(head, item) \
do { \
(item)->prev = NULL; \
(item)->next = (head); \
if (head) (head)->prev = (item); \
(head) = (item); \
} while (0)
#define LIST_REMOVE(head, item) \
do { \
if ((item)->prev) (item)->prev->next = (item)->next; \
else (head) = (item)->next; \
if ((item)->next) (item)->next->prev = (item)->prev; \
(item)->prev = (item)->next = NULL; \
} while (0)

522
gpu/metal/pipelines.m Normal file
View file

@ -0,0 +1,522 @@
/*
* pipelines.m
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// Pipelines and vertex layouts.
//
// A GPU API pipeline corresponds to several Metal render pipeline states, its
// variants, as Metal pipeline states also depend on the pixel format of the
// render target, the blend mode and the formats, strides and step rates of
// the vertex inputs. Variants are created when they are first drawn with.
#include "internal.h"
#include "version.h"
// The language version passed to the MSL compiler, see compile_library()
_Static_assert(MSL_VERSION == 24, "Update the MTLLanguageVersion used for compiling shaders");
#define AS_PIPELINE(handle) ((Pipeline *)(uintptr_t)(handle))
#define AS_LAYOUT(handle) ((VertexLayout *)(uintptr_t)(handle))
#define AS_BUFFER(handle) ((Buffer *)(uintptr_t)(handle))
// Native names {{{
// The native name of a Slang name, see MSL_PUSH_CONSTANTS_NAME, NULL if there is none
static const char *
native_name(const GPUNativeName *names, size_t num_names, const char *name) {
for (size_t i = 0; i < num_names; i++) {
if (names[i].name && names[i].native_name && strcmp(names[i].name, name) == 0) return names[i].native_name;
}
return NULL;
}
static bool
buffer_index_for(Driver *d, const GPUNativeName *names, size_t num_names, const char *name, int32_t *ans) {
const char *n = native_name(names, num_names, name);
int idx = -1;
if (!n || sscanf(n, "buffer(%d)", &idx) != 1) {
set_error(d, "The uniform block %s has no buffer index in the native names of the shader", name);
return false;
}
if (idx < 0 || idx >= MAX_SHADER_BUFFER_INDEX) {
set_error(d, "The buffer index %d of the uniform block %s is not below %d", idx, name, MAX_SHADER_BUFFER_INDEX);
return false;
}
*ans = idx;
return true;
}
static bool
texture_indices_for(Driver *d, const GPUNativeName *names, size_t num_names, const char *name, int32_t *texture, int32_t *sampler) {
const char *n = native_name(names, num_names, name);
int t = -1, s = -1;
if (!n || sscanf(n, "texture(%d) sampler(%d)", &t, &s) != 2) {
set_error(d, "The texture %s has no texture and sampler indices in the native names of the shader", name);
return false;
}
if (t < 0 || t >= MAX_SHADER_TEXTURE_INDEX || s < 0 || s >= MAX_SHADER_SAMPLER_INDEX) {
set_error(d, "The texture and sampler indices %d and %d of the texture %s are out of range", t, s, name);
return false;
}
*texture = t;
*sampler = s;
return true;
}
// }}}
// Pipelines {{{
static void
free_pipeline(Driver *d, Pipeline *p) {
for (size_t i = 0; i < p->num_variants; i++) {
if (d->rendering.pipeline == p->variants[i].state) d->rendering.pipeline = nil;
// Command buffers retain the pipeline states they use
[p->variants[i].state release];
}
free(p->variants);
[p->vertex_function release];
[p->fragment_function release];
if (p->param_blocks) {
for (size_t i = 0; i < p->num_param_blocks; i++) {
if (p->param_blocks[i].buffer) buffer_destroy(d, AS_HANDLE(p->param_blocks[i].buffer));
}
}
free(p->param_blocks);
if (p->bindings) {
for (size_t i = 0; i < p->num_bindings; i++) free(p->bindings[i].name);
}
free(p->bindings);
free(p);
}
static bool
add_binding(Driver *d, Pipeline *p, GPUBindingKind kind, uint32_t slot, const char *name, const GPUNativeName *names, size_t num_names) {
if (!name) name = "";
if (slot >= MAX_BINDING_SLOTS) {
set_error(d, "The binding slot %u of %s is too large", slot, name);
return false;
}
for (size_t i = 0; i < p->num_bindings; i++) {
if (p->bindings[i].slot == slot) {
set_error(d, "The binding slot %u is used by both %s and %s", slot, p->bindings[i].name, name);
return false;
}
}
PipelineBinding *b = p->bindings + p->num_bindings;
*b = (PipelineBinding){.kind = kind, .slot = slot, .buffer_index = -1, .texture_index = -1, .sampler_index = -1};
if (kind == GPU_BINDING_TEXTURE) {
if (!texture_indices_for(d, names, num_names, name, &b->texture_index, &b->sampler_index)) return false;
} else if (!buffer_index_for(d, names, num_names, name, &b->buffer_index)) return false;
if (!(b->name = strdup(name))) {
set_error(d, "Out of memory");
return false;
}
p->num_bindings++;
return true;
}
static id<MTLLibrary>
compile_library(Driver *d, const GPUShaderSource *s) {
const size_t size = s->size ? s->size : strlen(s->code);
id<MTLLibrary> ans = nil;
@autoreleasepool {
NSString *src = [[[NSString alloc] initWithBytes:s->code length:size encoding:NSUTF8StringEncoding] autorelease];
if (src == nil) {
set_error(d, "The MSL shader is not valid UTF-8");
return nil;
}
MTLCompileOptions *opts = [[[MTLCompileOptions alloc] init] autorelease];
[opts setLanguageVersion:MTLLanguageVersion2_4];
// Without fast math, so that rendering matches the other drivers
#if defined(__MAC_15_0) && __MAC_OS_X_VERSION_MAX_ALLOWED >= __MAC_15_0
if (@available(macOS 15.0, *)) [opts setMathMode:MTLMathModeSafe];
else
#endif
{
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdeprecated-declarations"
[opts setFastMathEnabled:NO];
#pragma clang diagnostic pop
}
NSError *err = nil;
ans = [d->device newLibraryWithSource:src options:opts error:&err];
if (ans == nil) set_error(d, "Failed to compile the MSL shader with error: %s", error_description(err));
else if (err != nil) debug_print(d, "Metal: Compiling an MSL shader produced warnings: %s", error_description(err));
}
return ans;
}
static bool
same_source(const GPUShaderSource *a, const GPUShaderSource *b) {
if (a->code == b->code && a->size == b->size) return true;
const size_t asz = a->size ? a->size : strlen(a->code), bsz = b->size ? b->size : strlen(b->code);
return asz == bsz && memcmp(a->code, b->code, asz) == 0;
}
static id<MTLFunction>
get_function(Driver *d, id<MTLLibrary> library, const char *name) {
id<MTLFunction> ans = nil;
@autoreleasepool {
ans = [library newFunctionWithName:[NSString stringWithUTF8String:name]];
}
if (ans == nil) set_error(d, "The MSL shader has no function named: %s", name);
return ans;
}
static bool
create_functions(Driver *d, Pipeline *p, const GPUShaderSource *sources, size_t num_sources) {
if (num_sources != 2) {
set_error(d, "A pipeline needs a vertex and a fragment shader");
return false;
}
id<MTLLibrary> libraries[2] = {nil, nil};
bool ok = true;
for (size_t i = 0; i < num_sources && ok; i++) {
const GPUShaderSource *s = sources + i;
if (s->language != GPU_SHADER_LANGUAGE_MSL) {
set_error(d, "The Metal driver supports only MSL shaders");
ok = false;
break;
}
if (!s->code || !s->entry_point) {
set_error(d, "Invalid MSL shader");
ok = false;
break;
}
// Modules containing the entry points of several stages are passed for
// each stage, as separate copies, compiling them is slow, so do it once
if (i > 0 && same_source(sources, s)) libraries[i] = [libraries[0] retain];
else if (!(libraries[i] = compile_library(d, s))) {
ok = false;
break;
}
id<MTLFunction> f = get_function(d, libraries[i], s->entry_point);
if (f == nil) {
ok = false;
break;
}
const MTLFunctionType expected = s->stage == GPU_SHADER_VERTEX ? MTLFunctionTypeVertex : MTLFunctionTypeFragment;
if ([f functionType] != expected) {
set_error(d, "The MSL function %s is not a %s function", s->entry_point, s->stage == GPU_SHADER_VERTEX ? "vertex" : "fragment");
[f release];
ok = false;
break;
}
if (s->stage == GPU_SHADER_VERTEX) {
[p->vertex_function release];
p->vertex_function = f;
} else {
[p->fragment_function release];
p->fragment_function = f;
}
}
// The functions retain their libraries
[libraries[0] release];
[libraries[1] release];
if (!ok) return false;
if (p->vertex_function == nil || p->fragment_function == nil) {
set_error(d, "A pipeline needs a vertex and a fragment shader");
return false;
}
// Only the inputs actually used by the vertex function need to be
// supplied by vertex layouts. Declared but unused inputs are passed if the
// vertex layout has them.
for (MTLVertexAttribute *a in [p->vertex_function vertexAttributes]) {
const NSUInteger loc = [a attributeIndex];
if (loc >= MAX_VERTEX_ATTRIBUTES) {
set_error(d, "The vertex input %s has the location %lu, which is too large", [[a name] UTF8String], (unsigned long)loc);
return false;
}
p->declared_inputs |= 1u << loc;
if ([a isActive]) p->vertex_inputs |= 1u << loc;
}
return true;
}
gpu_pipeline_t
pipeline_create(
void *driver,
const GPUShaderSource *sources,
size_t num_sources,
const GPUParamBlock *param_blocks,
size_t num_param_blocks,
const GPUBinding *bindings,
size_t num_bindings,
const GPUNativeName *native_names,
size_t num_native_names) {
Driver *d = driver;
Pipeline *p = calloc(1, sizeof(Pipeline));
if (!p) goto oom;
p->push_constants_index = -1;
if (!(p->bindings = calloc(MAX(1u, num_bindings + num_param_blocks), sizeof(PipelineBinding)))) goto oom;
if (!(p->param_blocks = calloc(MAX(1u, num_param_blocks), sizeof(ParamBlock)))) goto oom;
if (!create_functions(d, p, sources, num_sources)) goto fail;
for (size_t i = 0; i < num_bindings; i++) {
if (!add_binding(d, p, bindings[i].kind, bindings[i].slot, bindings[i].name, native_names, num_native_names)) goto fail;
}
for (size_t i = 0; i < num_param_blocks; i++) {
const GPUParamBlock *src = param_blocks + i;
ParamBlock *pb = p->param_blocks + p->num_param_blocks++;
pb->slot = src->slot;
pb->size = src->size;
if (src->slot < 0) {
if (src->size > PUSH_CONSTANTS_SIZE) {
set_error(d, "The push constant block of size %u is larger than the maximum of %d", src->size, PUSH_CONSTANTS_SIZE);
goto fail;
}
p->push_constants_size = src->size;
if (!buffer_index_for(d, native_names, num_native_names, MSL_PUSH_CONSTANTS_NAME, &p->push_constants_index)) goto fail;
} else {
// Uniform blocks whose contents are constant for the lifetime of
// the pipeline are kept in a uniform buffer owned by the pipeline
if (!add_binding(d, p, GPU_BINDING_UNIFORM_BLOCK, (uint32_t)src->slot, src->name, native_names, num_native_names)) goto fail;
pb->buffer = AS_BUFFER(buffer_create(d, GPU_BUFFER_UNIFORM));
if (!pb->buffer) goto fail;
buffer_allocate(d, AS_HANDLE(pb->buffer), src->size, GPU_UPDATE_RARELY);
memset([pb->buffer->storage.buffer contents], 0, src->size);
}
}
LIST_ADD(d->pipelines, p);
return AS_HANDLE(p);
oom:
set_error(d, "Out of memory");
fail:
if (p) free_pipeline(d, p);
return GPU_NULL_HANDLE;
}
void
pipeline_destroy(void *driver, gpu_pipeline_t pipeline) {
Driver *d = driver;
Pipeline *p = AS_PIPELINE(pipeline);
if (!p) return;
if (d->pipeline == p) d->pipeline = NULL;
if (d->rendering.push_constants_of == p) d->rendering.push_constants_of = NULL;
LIST_REMOVE(d->pipelines, p);
free_pipeline(d, p);
}
void
destroy_all_pipelines(Driver *d) {
while (d->pipelines) pipeline_destroy(d, AS_HANDLE(d->pipelines));
}
void
use_pipeline(void *driver, gpu_pipeline_t pipeline) {
((Driver *)driver)->pipeline = AS_PIPELINE(pipeline);
}
bool
pipeline_uniform_block(void *driver, gpu_pipeline_t pipeline, const char *name, GPUUniformBlockInfo *ans) {
Driver *d = driver;
const Pipeline *p = AS_PIPELINE(pipeline);
for (size_t i = 0; i < p->num_bindings; i++) {
if (p->bindings[i].kind == GPU_BINDING_UNIFORM_BLOCK && strcmp(p->bindings[i].name, name) == 0) {
ans->index = p->bindings[i].slot;
// The size is not known without pipeline reflection
ans->size = 0;
return true;
}
}
set_error(d, "The pipeline has no uniform block named: %s", name);
return false;
}
int32_t
pipeline_attribute_location(void *driver UNUSED, gpu_pipeline_t pipeline UNUSED, const char *name UNUSED) {
// The names of inputs in the MSL code are mangled by the shader compiler,
// the locations come from the reflection data in the program metadata
return -1;
}
void
set_params(void *driver, gpu_pipeline_t pipeline, uint32_t block, const void *data, size_t size) {
Driver *d = driver;
Pipeline *p = AS_PIPELINE(pipeline);
if (block >= p->num_param_blocks) {
log_error(d, "Invalid parameter block index: %u", block);
return;
}
ParamBlock *pb = p->param_blocks + block;
if (size != pb->size) {
log_error(d, "The data for parameter block %u is %zu bytes instead of %u", block, size, pb->size);
return;
}
if (pb->slot < 0) {
memcpy(p->push_constants, data, size);
if (d->rendering.push_constants_of == p) d->rendering.push_constants_dirty = true;
} else if (!write_buffer(d, pb->buffer, data, size)) log_error(d, "Failed to write the parameter block %u", block);
}
// }}}
// Variants {{{
size_t
vertex_attribute_size(uint32_t components, GPUAttribType type) {
switch (type) {
case GPU_ATTRIB_U8: return components;
case GPU_ATTRIB_U16: return 2u * components;
case GPU_ATTRIB_U32:
case GPU_ATTRIB_F32: return 4u * components;
}
return 4u * components;
}
static MTLVertexFormat
vertex_format(uint32_t components, GPUAttribType type) {
static const MTLVertexFormat formats[4][4] = {
{MTLVertexFormatUChar, MTLVertexFormatUChar2, MTLVertexFormatUChar3, MTLVertexFormatUChar4},
{MTLVertexFormatUShort, MTLVertexFormatUShort2, MTLVertexFormatUShort3, MTLVertexFormatUShort4},
{MTLVertexFormatUInt, MTLVertexFormatUInt2, MTLVertexFormatUInt3, MTLVertexFormatUInt4},
{MTLVertexFormatFloat, MTLVertexFormatFloat2, MTLVertexFormatFloat3, MTLVertexFormatFloat4},
};
if (components < 1 || components > 4) return MTLVertexFormatInvalid;
switch (type) {
case GPU_ATTRIB_U8: return formats[0][components - 1];
case GPU_ATTRIB_U16: return formats[1][components - 1];
case GPU_ATTRIB_U32: return formats[2][components - 1];
case GPU_ATTRIB_F32: return formats[3][components - 1];
}
return MTLVertexFormatInvalid;
}
static id<MTLRenderPipelineState>
create_variant(Driver *d, Pipeline *p, const PipelineVariantKey *key) {
id<MTLRenderPipelineState> ans = nil;
@autoreleasepool {
MTLRenderPipelineDescriptor *desc = [[[MTLRenderPipelineDescriptor alloc] init] autorelease];
[desc setVertexFunction:p->vertex_function];
[desc setFragmentFunction:p->fragment_function];
MTLVertexDescriptor *vd = [MTLVertexDescriptor vertexDescriptor];
bool has_inputs = false;
for (uint32_t loc = 0; loc < MAX_VERTEX_ATTRIBUTES; loc++) {
const VertexInputKey *k = key->inputs + loc;
if (k->format == MTLVertexFormatInvalid) continue;
has_inputs = true;
// Each input has a buffer of its own, its offset is applied when binding the buffer
MTLVertexAttributeDescriptor *a = [[vd attributes] objectAtIndexedSubscript:loc];
[a setFormat:k->format];
[a setOffset:0];
[a setBufferIndex:VERTEX_BUFFER_INDEX(loc)];
MTLVertexBufferLayoutDescriptor *l = [[vd layouts] objectAtIndexedSubscript:VERTEX_BUFFER_INDEX(loc)];
[l setStride:k->stride];
[l setStepFunction:k->per_instance ? MTLVertexStepFunctionPerInstance : MTLVertexStepFunctionPerVertex];
[l setStepRate:k->step_rate];
}
if (has_inputs) [desc setVertexDescriptor:vd];
MTLRenderPipelineColorAttachmentDescriptor *ca = [[desc colorAttachments] objectAtIndexedSubscript:0];
[ca setPixelFormat:key->color_format];
[ca setBlendingEnabled:key->blend ? YES : NO];
// Pre-multiplied alpha, see GPU_BLEND_PREMULTIPLIED_ALPHA
[ca setRgbBlendOperation:MTLBlendOperationAdd];
[ca setAlphaBlendOperation:MTLBlendOperationAdd];
[ca setSourceRGBBlendFactor:MTLBlendFactorOne];
[ca setSourceAlphaBlendFactor:MTLBlendFactorOne];
[ca setDestinationRGBBlendFactor:MTLBlendFactorOneMinusSourceAlpha];
[ca setDestinationAlphaBlendFactor:MTLBlendFactorOneMinusSourceAlpha];
NSError *err = nil;
ans = [d->device newRenderPipelineStateWithDescriptor:desc error:&err];
if (ans == nil) log_error(d, "Failed to create a Metal pipeline with error: %s", error_description(err));
}
return ans;
}
id<MTLRenderPipelineState>
pipeline_for_current_state(Driver *d, bool blend, PipelineVariantKey *key) {
Pipeline *p = d->pipeline;
memset(key, 0, sizeof(*key)); // the key is compared with memcmp()
key->color_format = d->rendering.format;
key->blend = blend;
for (uint32_t loc = 0; loc < MAX_VERTEX_ATTRIBUTES; loc++) {
if (!(p->declared_inputs & (1u << loc))) continue;
const VertexAttribute *a = d->vertex_layout ? d->vertex_layout->attributes + loc : NULL;
if (!a || !a->enabled) {
if (!(p->vertex_inputs & (1u << loc))) continue;
log_error(d, "The vertex layout has no input at location: %u used by the shader", loc);
return nil;
}
VertexInputKey *k = key->inputs + loc;
k->format = vertex_format(a->components, a->type);
if (k->format == MTLVertexFormatInvalid) {
log_error(d, "The vertex input at location: %u has an unsupported format", loc);
return nil;
}
k->stride = vertex_buffer_stride(a, vertex_attribute_size(a->components, a->type));
k->per_instance = a->divisor > 0;
k->step_rate = a->divisor > 0 ? a->divisor : 1;
}
for (size_t i = 0; i < p->num_variants; i++) {
if (memcmp(&p->variants[i].key, key, sizeof(*key)) == 0) return p->variants[i].state;
}
if (p->num_variants >= p->variants_capacity) {
const size_t cap = MAX((size_t)4u, p->variants_capacity * 2);
PipelineVariant *v = realloc(p->variants, cap * sizeof(PipelineVariant));
if (!v) fatal(d, "Out of memory");
p->variants = v;
p->variants_capacity = cap;
}
id<MTLRenderPipelineState> state = create_variant(d, p, key);
if (state == nil) return nil;
p->variants[p->num_variants++] = (PipelineVariant){.key = *key, .state = state};
return state;
}
// }}}
// Vertex layouts {{{
gpu_vertex_layout_t
vertex_layout_create(void *driver) {
Driver *d = driver;
VertexLayout *l = calloc(1, sizeof(VertexLayout));
if (!l) {
set_error(d, "Out of memory");
return GPU_NULL_HANDLE;
}
LIST_ADD(d->vertex_layouts, l);
return AS_HANDLE(l);
}
void
vertex_layout_destroy(void *driver, gpu_vertex_layout_t layout) {
Driver *d = driver;
VertexLayout *l = AS_LAYOUT(layout);
if (!l) return;
if (d->vertex_layout == l) d->vertex_layout = NULL;
LIST_REMOVE(d->vertex_layouts, l);
free(l);
}
void
bind_vertex_layout(void *driver, gpu_vertex_layout_t layout) {
((Driver *)driver)->vertex_layout = AS_LAYOUT(layout);
}
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) {
Driver *d = driver;
VertexLayout *l = AS_LAYOUT(layout);
if (location >= MAX_VERTEX_ATTRIBUTES) {
log_error(d, "Invalid vertex input location: %u", location);
return;
}
l->attributes[location] = (VertexAttribute){
.enabled = true,
.buffer = AS_BUFFER(buffer),
.components = components,
.type = type,
// A stride of zero means tightly packed, as in OpenGL
.stride = stride ? stride : (uint32_t)vertex_attribute_size(components, type),
.offset = offset,
.divisor = instance_divisor,
};
d->vertex_layout = l;
}
// }}}

206
gpu/metal/surfaces.m Normal file
View file

@ -0,0 +1,206 @@
/*
* surfaces.m
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// Surfaces, rendering into Cocoa windows with CAMetalLayer
#include "internal.h"
#define AS_SURFACE(handle) ((Surface *)(uintptr_t)(handle))
bool
choose_native_visual(void *driver UNUSED, const GPUNativeWindow *native UNUSED, const GPUSurfaceConfig *config UNUSED, uint64_t *visual_id) {
*visual_id = 0;
return true;
}
// Update the properties of the layer that depend on the window
static void
configure_layer(Surface *s) {
@autoreleasepool {
NSWindow *w = [s->view window];
[s->layer setContentsScale:(s->config.high_resolution && w != nil) ? [w backingScaleFactor] : 1.0];
// The contents are in the color space of the window, as with OpenGL,
// see the macos_colorspace option
[s->layer setColorspace:w != nil ? [[w colorSpace] CGColorSpace] : NULL];
if (s->width && s->height) [s->layer setDrawableSize:CGSizeMake(s->width, s->height)];
}
}
// Release the drawable of the surface, without presenting it
static void
release_drawable(Driver *d, Surface *s) {
if (s->drawable == nil) return;
if (d->rendering.texture == [s->drawable texture]) end_rendering(d);
[s->drawable_srgb_view release];
[s->drawable release];
s->drawable_srgb_view = nil;
s->drawable = nil;
}
bool
current_surface_image(Driver *d, RenderImage *ans) {
Surface *s = d->current_surface;
if (!s) return false;
if (s->drawable == nil) {
// There is nothing to render to, such as when the window is minimized
if (!s->width || !s->height) return false;
@autoreleasepool {
// Waits for at most a second, see allowsNextDrawableTimeout
s->drawable = [[s->layer nextDrawable] retain];
}
if (s->drawable == nil) {
debug_print(d, "Metal: Timed out acquiring a drawable");
return false;
}
// The view for encoding to sRGB, see set_srgb_output(). Views that
// differ from the texture only in being sRGB need no special usage.
s->drawable_srgb_view = [[s->drawable texture] newTextureViewWithPixelFormat:MTLPixelFormatBGRA8Unorm_sRGB];
}
id<MTLTexture> t = [s->drawable texture];
*ans = (RenderImage){.texture = t, .unorm_view = t, .srgb_view = s->drawable_srgb_view, .width = (uint32_t)[t width], .height = (uint32_t)[t height]};
return true;
}
gpu_surface_t
surface_create(void *driver, const GPUNativeWindow *native, const GPUSurfaceConfig *config, uint32_t width, uint32_t height) {
Driver *d = driver;
if (native->platform != GPU_PLATFORM_COCOA || !native->handle) {
set_error(d, "The Metal driver supports only Cocoa windows");
return GPU_NULL_HANDLE;
}
Surface *s = calloc(1, sizeof(Surface));
if (!s) {
set_error(d, "Out of memory");
return GPU_NULL_HANDLE;
}
s->config = *config;
s->width = width;
s->height = height;
@autoreleasepool {
s->layer = [[CAMetalLayer layer] retain];
if (s->layer == nil) {
set_error(d, "Failed to create a CAMetalLayer");
free(s);
return GPU_NULL_HANDLE;
}
s->view = [(NSView *)native->handle retain];
[s->layer setDevice:d->device];
[s->layer setPixelFormat:MTLPixelFormatBGRA8Unorm];
// Drawables are read back and copied from, see read_pixels() and copy_to_texture()
[s->layer setFramebufferOnly:NO];
[s->layer setOpaque:config->transparent ? NO : YES];
[s->layer setMaximumDrawableCount:3];
[s->layer setAllowsNextDrawableTimeout:YES];
// kitty paces rendering itself, using CVDisplayLink, as with OpenGL,
// where the swap interval is zero, see surface_set_swap_interval()
[s->layer setDisplaySyncEnabled:NO];
configure_layer(s);
// Make the view layer hosting, the layer must be set before wantsLayer
[s->view setLayer:s->layer];
[s->view setWantsLayer:YES];
}
LIST_ADD(d->surfaces, s);
debug_print(d, "Created Metal surface for window of size: %ux%u", width, height);
return AS_HANDLE(s);
}
void
surface_destroy(void *driver, gpu_surface_t surface) {
Driver *d = driver;
Surface *s = AS_SURFACE(surface);
if (!s) return;
release_drawable(d, s);
if (d->current_surface == s) d->current_surface = NULL;
@autoreleasepool {
if ([s->view layer] == s->layer) {
[s->view setWantsLayer:NO];
[s->view setLayer:nil];
}
[s->layer release];
[s->view release];
}
LIST_REMOVE(d->surfaces, s);
free(s);
}
bool
make_surface_current(void *driver, gpu_surface_t surface) {
Driver *d = driver;
Surface *s = AS_SURFACE(surface);
if (s != d->current_surface && !d->render_target) end_rendering(d);
d->current_surface = s;
return true;
}
gpu_surface_t
get_current_surface(void *driver) {
return AS_HANDLE(((Driver *)driver)->current_surface);
}
void
surface_resize(void *driver UNUSED, gpu_surface_t surface, uint32_t width, uint32_t height) {
Surface *s = AS_SURFACE(surface);
if (!s) return;
s->width = width;
s->height = height;
// A drawable that has already been acquired keeps its size until presented
configure_layer(s);
}
bool
surface_present(void *driver, gpu_surface_t surface) {
Driver *d = driver;
Surface *s = AS_SURFACE(surface);
if (!s) return false;
if (s->drawable == nil) return true; // nothing was rendered
@autoreleasepool {
if (d->rendering.texture == [s->drawable texture]) end_rendering(d);
// Presented once the command buffer has completed
[command_buffer(d) presentDrawable:s->drawable];
submit_commands(d, false);
release_drawable(d, s);
}
return true;
}
void
surface_set_swap_interval(void *driver UNUSED, gpu_surface_t surface, int interval) {
Surface *s = AS_SURFACE(surface);
if (!s || s->swap_interval == interval) return;
s->swap_interval = interval;
[s->layer setDisplaySyncEnabled:interval > 0 ? YES : NO];
}
void
surface_native_changed(void *driver UNUSED, gpu_surface_t surface) {
// The window changed screens or its backing properties changed
Surface *s = AS_SURFACE(surface);
if (s) configure_layer(s);
}
bool
surface_recreate(void *driver, gpu_surface_t surface) {
Driver *d = driver;
Surface *s = AS_SURFACE(surface);
if (!s) return false;
// A new drawable is acquired by the next rendering
release_drawable(d, s);
@autoreleasepool {
if ([s->view layer] != s->layer) {
[s->view setLayer:s->layer];
[s->view setWantsLayer:YES];
}
}
configure_layer(s);
return make_surface_current(d, surface);
}
void
release_native_resources(void *driver) {
Driver *d = driver;
while (d->surfaces) surface_destroy(d, AS_HANDLE(d->surfaces));
}

480
gpu/metal/textures.m Normal file
View file

@ -0,0 +1,480 @@
/*
* textures.m
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
// Textures and samplers
#include "internal.h"
#define AS_TEXTURE(handle) ((Texture *)(uintptr_t)(handle))
// Formats {{{
static MTLPixelFormat
mtl_format_for(GPUTextureFormat f) {
switch (f) {
case GPU_FORMAT_R8: return MTLPixelFormatR8Unorm;
case GPU_FORMAT_R8UI: return MTLPixelFormatR8Uint;
case GPU_FORMAT_RG8UI: return MTLPixelFormatRG8Uint;
case GPU_FORMAT_R32UI: return MTLPixelFormatR32Uint;
case GPU_FORMAT_RGBA8: return MTLPixelFormatRGBA8Unorm;
case GPU_FORMAT_SRGB8_ALPHA8: return MTLPixelFormatRGBA8Unorm_sRGB;
case GPU_FORMAT_RGBA16: return MTLPixelFormatRGBA16Unorm;
}
return MTLPixelFormatInvalid;
}
static bool
is_integer_format(MTLPixelFormat f) {
return f == MTLPixelFormatR8Uint || f == MTLPixelFormatRG8Uint || f == MTLPixelFormatR32Uint;
}
size_t
bytes_per_pixel(MTLPixelFormat f) {
switch (f) {
case MTLPixelFormatR8Unorm:
case MTLPixelFormatR8Uint: return 1;
case MTLPixelFormatRG8Uint: return 2;
case MTLPixelFormatRGBA16Unorm: return 8;
default: return 4;
}
}
// The number of 8 bit channels in a pixel, zero for formats that are not made of 8 bit channels
static unsigned
channels_8bit(MTLPixelFormat f) {
switch (f) {
case MTLPixelFormatR8Unorm:
case MTLPixelFormatR8Uint: return 1;
case MTLPixelFormatRG8Uint: return 2;
case MTLPixelFormatRGBA8Unorm:
case MTLPixelFormatRGBA8Unorm_sRGB:
case MTLPixelFormatBGRA8Unorm:
case MTLPixelFormatBGRA8Unorm_sRGB: return 4;
default: return 0;
}
}
static size_t
pixel_layout_size(GPUPixelLayout l) {
switch (l) {
case GPU_PIXELS_R8: return 1;
case GPU_PIXELS_RG8: return 2;
case GPU_PIXELS_RGB8: return 3;
case GPU_PIXELS_RGBA8:
case GPU_PIXELS_RGBA8_PACKED:
case GPU_PIXELS_R32UI: return 4;
}
return 4;
}
static size_t
row_stride(size_t row_bytes, uint32_t alignment) {
if (alignment < 1) alignment = 1;
return (row_bytes + alignment - 1) / alignment * alignment;
}
// Convert pixels from CPU memory into tightly packed pixels of the format
static bool
convert_pixels(const GPUPixelData *src, uint32_t width, uint32_t height, MTLPixelFormat format, uint8_t *dst) {
const size_t sbpp = pixel_layout_size(src->layout), dbpp = bytes_per_pixel(format);
const size_t sstride = row_stride(sbpp * width, src->row_alignment), dstride = dbpp * width;
const uint8_t *s = src->data;
if (src->layout == GPU_PIXELS_R32UI || format == MTLPixelFormatR32Uint) {
if (src->layout != GPU_PIXELS_R32UI || format != MTLPixelFormatR32Uint) return false;
for (uint32_t y = 0; y < height; y++) memcpy(dst + y * dstride, s + y * sstride, dstride);
return true;
}
const unsigned dch = channels_8bit(format);
// Fast path, the layout of the pixels is the same as that of the texture
if (dch && src->layout != GPU_PIXELS_RGBA8_PACKED && dch == sbpp) {
for (uint32_t y = 0; y < height; y++) memcpy(dst + y * dstride, s + y * sstride, dstride);
return true;
}
for (uint32_t y = 0; y < height; y++) {
const uint8_t *row = s + y * sstride;
uint8_t *out = dst + y * dstride;
for (uint32_t x = 0; x < width; x++) {
uint8_t c[4] = {0, 0, 0, 255};
const uint8_t *p = row + x * sbpp;
switch (src->layout) {
case GPU_PIXELS_R8: c[0] = p[0]; break;
case GPU_PIXELS_RG8:
c[0] = p[0];
c[1] = p[1];
break;
case GPU_PIXELS_RGB8: memcpy(c, p, 3); break;
case GPU_PIXELS_RGBA8: memcpy(c, p, 4); break;
case GPU_PIXELS_RGBA8_PACKED: {
uint32_t v;
memcpy(&v, p, 4);
c[0] = (uint8_t)(v >> 24);
c[1] = (uint8_t)(v >> 16);
c[2] = (uint8_t)(v >> 8);
c[3] = (uint8_t)v;
} break;
case GPU_PIXELS_R32UI: break;
}
if (dch) memcpy(out + x * dch, c, dch);
else if (format == MTLPixelFormatRGBA16Unorm) {
uint16_t w[4];
for (int i = 0; i < 4; i++) w[i] = (uint16_t)(c[i] * 257u);
memcpy(out + x * 8, w, 8);
} else return false;
}
}
return true;
}
void
convert_to_rgba8(MTLPixelFormat format, const uint8_t *src, uint8_t *dst, size_t num_pixels) {
switch (format) {
case MTLPixelFormatBGRA8Unorm:
case MTLPixelFormatBGRA8Unorm_sRGB:
for (size_t i = 0; i < num_pixels; i++, src += 4, dst += 4) {
dst[0] = src[2];
dst[1] = src[1];
dst[2] = src[0];
dst[3] = src[3];
}
break;
case MTLPixelFormatRGBA16Unorm:
for (size_t i = 0; i < num_pixels * 4; i++) {
uint16_t v;
memcpy(&v, src + 2 * i, 2);
dst[i] = (uint8_t)(v >> 8);
}
break;
default: memcpy(dst, src, num_pixels * 4); break;
}
}
// }}}
// Samplers {{{
static MTLSamplerAddressMode
address_mode(int wrap) {
switch (wrap) {
case 0: return MTLSamplerAddressModeClampToEdge;
case 1: return MTLSamplerAddressModeClampToBorderColor;
case 2: return MTLSamplerAddressModeRepeat;
default: return MTLSamplerAddressModeMirrorRepeat;
}
}
bool
create_samplers(Driver *d) {
@autoreleasepool {
for (int filter = 0; filter < 2; filter++) {
for (int wrap = 0; wrap < 4; wrap++) {
for (int integer = 0; integer < 2; integer++) {
// Integer textures cannot be filtered, they are only read from
const MTLSamplerMinMagFilter f = filter && !integer ? MTLSamplerMinMagFilterLinear : MTLSamplerMinMagFilterNearest;
MTLSamplerDescriptor *desc = [[MTLSamplerDescriptor alloc] init];
[desc setMinFilter:f];
[desc setMagFilter:f];
[desc setMipFilter:MTLSamplerMipFilterNotMipmapped];
[desc setSAddressMode:address_mode(wrap)];
[desc setTAddressMode:address_mode(wrap)];
[desc setRAddressMode:address_mode(wrap)];
[desc setBorderColor:MTLSamplerBorderColorTransparentBlack];
[desc setNormalizedCoordinates:YES];
d->samplers[filter][wrap][integer] = [d->device newSamplerStateWithDescriptor:desc];
[desc release];
if (d->samplers[filter][wrap][integer] == nil) {
set_error(d, "Failed to create a Metal sampler");
return false;
}
}
}
}
}
return true;
}
void
destroy_samplers(Driver *d) {
for (int filter = 0; filter < 2; filter++) {
for (int wrap = 0; wrap < 4; wrap++) {
for (int integer = 0; integer < 2; integer++) {
[d->samplers[filter][wrap][integer] release];
d->samplers[filter][wrap][integer] = nil;
}
}
}
}
static id<MTLSamplerState>
sampler_for(Driver *d, const GPUTextureDesc *desc, MTLPixelFormat format) {
const int filter = desc->filter == GPU_FILTER_LINEAR ? 1 : 0;
int wrap = 0;
switch (desc->wrap) {
case GPU_WRAP_CLAMP_TO_EDGE: wrap = 0; break;
case GPU_WRAP_CLAMP_TO_BORDER: wrap = 1; break;
case GPU_WRAP_REPEAT: wrap = 2; break;
case GPU_WRAP_MIRRORED_REPEAT: wrap = 3; break;
}
return d->samplers[filter][wrap][is_integer_format(format) ? 1 : 0];
}
// }}}
// Textures {{{
static void
release_texture_objects(Driver *d, Texture *t) {
// Command buffers retain the textures they use, so they can be released
// immediately, but a render pass into the texture must be ended first
if (t->texture != nil && d->rendering.texture == t->texture) end_rendering(d);
[t->unorm_view release];
[t->srgb_view release];
[t->texture release];
t->texture = t->unorm_view = t->srgb_view = nil;
}
static bool
create_texture_objects(Driver *d, Texture *t, const GPUTextureDesc *desc) {
const MTLPixelFormat format = mtl_format_for(desc->format);
if (format == MTLPixelFormatInvalid) {
set_error(d, "Unknown texture format: %d", (int)desc->format);
return false;
}
const uint32_t width = MAX(1u, desc->width), height = MAX(1u, desc->height);
const uint32_t layers = desc->kind == GPU_TEXTURE_2D_ARRAY ? MAX(1u, desc->layers) : 1;
if (width > MAX_TEXTURE_SIZE || height > MAX_TEXTURE_SIZE || layers > MAX_TEXTURE_LAYERS) {
set_error(d, "The texture of size %ux%ux%u is too large", width, height, layers);
return false;
}
// Integer textures are only read from, others can also be rendered into
const bool renderable = !is_integer_format(format);
const bool is_srgb = format == MTLPixelFormatRGBA8Unorm_sRGB;
@autoreleasepool {
MTLTextureDescriptor *td = [[MTLTextureDescriptor alloc] init];
[td setTextureType:desc->kind == GPU_TEXTURE_2D_ARRAY ? MTLTextureType2DArray : MTLTextureType2D];
[td setPixelFormat:format];
[td setWidth:width];
[td setHeight:height];
[td setArrayLength:layers];
[td setMipmapLevelCount:1];
[td setStorageMode:MTLStorageModePrivate];
MTLTextureUsage usage = MTLTextureUsageShaderRead;
if (renderable) usage |= MTLTextureUsageRenderTarget;
// Rendering into sRGB textures encodes to sRGB only when sRGB output is
// enabled, see set_srgb_output(), so they also need a non-sRGB view
if (is_srgb) usage |= MTLTextureUsagePixelFormatView;
[td setUsage:usage];
t->texture = [d->device newTextureWithDescriptor:td];
[td release];
}
if (t->texture == nil) {
set_error(d, "Failed to create a Metal texture of size %ux%ux%u", width, height, layers);
return false;
}
if (renderable) {
if (is_srgb) {
t->unorm_view = [t->texture newTextureViewWithPixelFormat:MTLPixelFormatRGBA8Unorm];
t->srgb_view = [t->texture retain];
if (t->unorm_view == nil) {
set_error(d, "Failed to create a view of an sRGB texture");
release_texture_objects(d, t);
return false;
}
} else t->unorm_view = [t->texture retain];
}
t->format = format;
t->desc = *desc;
t->sampler = sampler_for(d, desc, format);
return true;
}
static bool
upload(Driver *d, Texture *t, uint32_t x, uint32_t y, uint32_t layer, uint32_t width, uint32_t height, const GPUPixelData *pixels) {
if (!width || !height) return true;
const NSUInteger tw = [t->texture width], th = [t->texture height], tl = [t->texture arrayLength];
if ((uint64_t)x + width > tw || (uint64_t)y + height > th || layer >= tl) {
set_error(d, "Texture upload out of bounds");
return false;
}
const size_t bpp = bytes_per_pixel(t->format), row = (size_t)width * bpp, size = row * height;
id<MTLBuffer> buffer;
size_t offset;
void *mapped;
if (!allocate_staging(d, size, bpp, &buffer, &offset, &mapped)) return false;
if (!convert_pixels(pixels, width, height, t->format, mapped)) {
set_error(d, "Cannot upload pixels of layout: %d to a texture of format: %d", (int)pixels->layout, (int)t->format);
return false;
}
[blit_encoder(d) copyFromBuffer:buffer
sourceOffset:offset
sourceBytesPerRow:row
sourceBytesPerImage:size
sourceSize:MTLSizeMake(width, height, 1)
toTexture:t->texture
destinationSlice:layer
destinationLevel:0
destinationOrigin:MTLOriginMake(x, y, 0)];
return true;
}
static bool
init_texture(Driver *d, Texture *t, const GPUTextureDesc *desc, const GPUPixelData *initial) {
if (!create_texture_objects(d, t, desc)) return false;
if (initial) {
// The pixels of all layers, one after the other
const uint32_t w = (uint32_t)[t->texture width], h = (uint32_t)[t->texture height], layers = (uint32_t)[t->texture arrayLength];
const size_t layer_size = row_stride(pixel_layout_size(initial->layout) * w, initial->row_alignment) * h;
for (uint32_t layer = 0; layer < layers; layer++) {
GPUPixelData p = *initial;
p.data = (const uint8_t *)initial->data + layer * layer_size;
if (!upload(d, t, 0, 0, layer, w, h, &p)) return false;
}
}
return true;
}
gpu_texture_t
texture_create(void *driver, const GPUTextureDesc *desc, const GPUPixelData *initial) {
Driver *d = driver;
Texture *t = calloc(1, sizeof(Texture));
if (!t) {
set_error(d, "Out of memory");
return GPU_NULL_HANDLE;
}
bool ok;
@autoreleasepool {
ok = init_texture(d, t, desc, initial);
}
if (!ok) {
release_texture_objects(d, t);
free(t);
return GPU_NULL_HANDLE;
}
LIST_ADD(d->textures, t);
return AS_HANDLE(t);
}
bool
texture_reset(void *driver, gpu_texture_t texture, const GPUTextureDesc *desc, const GPUPixelData *initial) {
Driver *d = driver;
Texture *t = AS_TEXTURE(texture);
release_texture_objects(d, t);
bool ok;
@autoreleasepool {
ok = init_texture(d, t, desc, initial);
}
if (!ok) release_texture_objects(d, t);
return ok;
}
void
texture_destroy(void *driver, gpu_texture_t texture) {
Driver *d = driver;
Texture *t = AS_TEXTURE(texture);
if (!t) return;
for (size_t i = 0; i < arraysz(d->bound_textures); i++) {
if (d->bound_textures[i] == t) d->bound_textures[i] = NULL;
}
release_texture_objects(d, t);
LIST_REMOVE(d->textures, t);
free(t);
}
void
destroy_all_textures(Driver *d) {
while (d->textures) texture_destroy(d, AS_HANDLE(d->textures));
}
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) {
Driver *d = driver;
bool ok;
@autoreleasepool {
ok = upload(d, AS_TEXTURE(texture), x, y, layer, width, height, pixels);
}
if (!ok) log_error(d, "Failed to upload texture: %s", d->last_error);
}
void
texture_copy(void *driver, gpu_texture_t src, gpu_texture_t dst) {
Driver *d = driver;
Texture *s = AS_TEXTURE(src), *t = AS_TEXTURE(dst);
const NSUInteger w = [s->texture width], h = [s->texture height];
if (s->format != t->format || w > [t->texture width] || h > [t->texture height]) {
log_error(d, "Cannot copy between incompatible textures");
return;
}
@autoreleasepool {
const NSUInteger layers = MIN([s->texture arrayLength], [t->texture arrayLength]);
id<MTLBlitCommandEncoder> blit = blit_encoder(d);
for (NSUInteger layer = 0; layer < layers; layer++) {
[blit copyFromTexture:s->texture
sourceSlice:layer
sourceLevel:0
sourceOrigin:MTLOriginMake(0, 0, 0)
sourceSize:MTLSizeMake(w, h, 1)
toTexture:t->texture
destinationSlice:layer
destinationLevel:0
destinationOrigin:MTLOriginMake(0, 0, 0)];
}
}
}
bool
texture_read(void *driver, gpu_texture_t texture, GPUPixelLayout layout, void *dst, size_t dst_size) {
Driver *d = driver;
Texture *t = AS_TEXTURE(texture);
const uint32_t width = (uint32_t)[t->texture width], height = (uint32_t)[t->texture height];
const size_t tsz = bytes_per_pixel(t->format), npx = (size_t)width * height;
const size_t out_bpp = pixel_layout_size(layout), out_stride = row_stride(out_bpp * width, 4);
if (dst_size < out_stride * height) {
set_error(d, "The buffer for reading the texture is too small");
return false;
}
const bool converts_to_rgba8 = channels_8bit(t->format) == 4 || t->format == MTLPixelFormatRGBA16Unorm;
if (layout == GPU_PIXELS_RGBA8 ? !converts_to_rgba8 : out_bpp != tsz) {
set_error(d, "Cannot read a texture of format %d as pixel layout %d", (int)t->format, (int)layout);
return false;
}
@autoreleasepool {
id<MTLBuffer> buf = [d->device newBufferWithLength:MAX((size_t)16u, npx * tsz) options:MTLResourceStorageModeShared];
if (buf == nil) {
set_error(d, "Failed to allocate memory for reading back a texture");
return false;
}
[blit_encoder(d) copyFromTexture:t->texture
sourceSlice:0
sourceLevel:0
sourceOrigin:MTLOriginMake(0, 0, 0)
sourceSize:MTLSizeMake(width, height, 1)
toBuffer:buf
destinationOffset:0
destinationBytesPerRow:(NSUInteger)width * tsz
destinationBytesPerImage:npx * tsz];
submit_commands(d, true);
const uint8_t *src = [buf contents];
for (uint32_t y = 0; y < height; y++) {
uint8_t *out = (uint8_t *)dst + y * out_stride;
const uint8_t *in = src + (size_t)y * width * tsz;
if (layout == GPU_PIXELS_RGBA8) convert_to_rgba8(t->format, in, out, width);
else memcpy(out, in, (size_t)width * tsz);
}
[buf release];
}
return true;
}
void
texture_get_desc(void *driver UNUSED, gpu_texture_t texture, GPUTextureDesc *ans) {
*ans = AS_TEXTURE(texture)->desc;
}
void
bind_texture(void *driver, uint32_t slot, gpu_texture_t texture) {
Driver *d = driver;
if (slot >= MAX_BINDING_SLOTS) {
log_error(d, "Invalid texture binding slot: %u", slot);
return;
}
d->bound_textures[slot] = AS_TEXTURE(texture);
}
// }}}

13
gpu/metal/version.h Normal file
View file

@ -0,0 +1,13 @@
/*
* version.h
* Copyright (C) 2026 Kovid Goyal <kovid at kovidgoyal.net>
*
* Distributed under terms of the GPL3 license.
*/
#pragma once
// The version of the Metal Shading Language shaders are compiled to, as
// major * 10 + minor. MSL 2.4 is supported from macOS 12, the minimum
// version of macOS supported by kitty.
#define MSL_VERSION 24

View file

@ -207,11 +207,13 @@ def variant_name(variant: dict[str, str], default: dict[str, str]) -> str:
class ShaderTarget(NamedTuple):
# The shader target consumed by a GPU driver, identified by strings of the
# form family-version, for example glsl-140 or spirv-16 (SPIR-V 1.6).
# Built-in shaders are compiled for the targets of the drivers being built,
# at build time, and custom shaders for the target of the loaded driver, at
# runtime. GLSL targets produce one text file per stage, SPIR-V targets a
# single binary module containing all the entry points of the program.
# form family-version, for example glsl-140, spirv-16 (SPIR-V 1.6) or
# msl-24 (Metal Shading Language 2.4). Built-in shaders are compiled for
# the targets of the drivers being built, at build time, and custom
# shaders for the target of the loaded driver, at runtime. GLSL targets
# produce one text file per stage, SPIR-V and MSL targets a single module,
# binary for SPIR-V and source code for MSL, containing all the entry
# points of the program.
family: str
version: int
@ -224,7 +226,7 @@ class ShaderTarget(NamedTuple):
family, sep, version = spec.partition('-')
if not sep or not version.isdigit():
raise ValueError(f'Invalid shader target: {spec!r}')
if family not in ('glsl', 'spirv'):
if family not in ('glsl', 'spirv', 'msl'):
raise ValueError(f'Unsupported shader target: {spec!r}')
return cls(family, int(version))
@ -232,14 +234,30 @@ class ShaderTarget(NamedTuple):
def is_spirv(self) -> bool:
return self.family == 'spirv'
@property
def is_msl(self) -> bool:
return self.family == 'msl'
@property
def is_single_module(self) -> bool:
# Whether a program is compiled to a single module containing the entry points of all its stages
return self.family in ('spirv', 'msl')
@property
def module_extension(self) -> str:
# The file extension of single modules, see is_single_module
return '.spv' if self.is_spirv else '.metal'
@property
def slangc_args(self) -> list[str]:
major, minor = divmod(self.version, 10)
if self.is_spirv:
major, minor = divmod(self.version, 10)
# The GLSL 450 profile provides the shader capabilities, such as
# texture gathering, without it slangc warns that it implicitly
# upgrades the profile
return ['-target', 'spirv', '-profile', 'glsl_450', '-capability', f'spirv_{major}_{minor}', '-fvk-use-entrypoint-name']
if self.is_msl:
return ['-target', 'metal', '-capability', f'METAL_{major}_{minor}', '-line-directive-mode', 'none']
# slangc fails with glsl_140 https://github.com/shader-slang/slang/issues/11898
return ['-target', 'glsl', '-profile', f'glsl_{max(150, self.version)}']
@ -263,6 +281,10 @@ def builtin_program(target: ShaderTarget, name: str, variant_name: str = '') ->
with open(f'{base}.spv', 'rb') as b:
spirv = b.read()
return spirv, spirv, metadata
if target.is_msl:
with open(f'{base}.metal') as f:
msl = f.read()
return msl, msl, metadata
with open(f'{base}.vert.glsl') as f:
vert = f.read()
with open(f'{base}.frag.glsl') as f:
@ -1070,16 +1092,18 @@ def serialize_source_metadata(sources: dict[str, SlangFile], dest_dir: str) -> N
f.write(json.dumps(sfile.asdict(skip_source=True), indent=2, sort_keys=True))
def commands_to_compile_to_spirv(
def commands_to_compile_to_module(
sources: dict[str, SlangFile], build_dir: str, dest_dir: str, target: ShaderTarget, built_files: list[str]
) -> Iterator[Command]:
# One module containing all the entry points of each program
# One module containing all the entry points of each program, for targets
# where is_single_module is True
os.makedirs(os.path.join(dest_dir, target.id), exist_ok=True)
os.makedirs(os.path.join(build_dir, target.id), exist_ok=True)
ext = target.module_extension
for base_dest, base_build, slang_module, scmd, sfile in iter_entry_point_shaders(sources, build_dir, os.path.join(dest_dir, target.id)):
for x in sfile.specializations:
cmd = list(scmd)
dest = f'{base_dest}{x.filename_insert}.spv' if x.name else f'{base_dest}.spv'
dest = f'{base_dest}{x.filename_insert}{ext}' if x.name else f'{base_dest}{ext}'
if x.variables:
cmd.insert(-1, f'{base_build}{x.filename_insert}.slang-module')
cmd += target.slangc_args + ['-o', dest, '-reflection-json', reflection_path(target, build_dir, dest)]
@ -1091,17 +1115,21 @@ def commands_to_compile_to_spirv(
yield Command(needs_build, f'Linking |{os.path.basename(dest)}| ...', cmd)
def write_spirv_metadata(paths: Iterable[str], target: ShaderTarget, reflection_dir: str) -> None:
"Write the program metadata for compiled SPIR-V modules"
def write_module_metadata(paths: Iterable[str], target: ShaderTarget, reflection_dir: str) -> None:
"Write the program metadata for compiled single modules, see ShaderTarget.is_single_module, fixing up MSL code as needed"
for path in paths:
with open(reflection_path(target, reflection_dir, path)) as f:
reflection = json.load(f)
try:
metadata = program_metadata(target, [reflection], GLSLMetadata())
if target.is_msl:
with open(path) as f:
msl = f.read()
write_if_changed(path, fixup_metal_code(msl, metadata['entry_points'], os.path.basename(path)))
except Exception:
os.unlink(path)
raise
write_if_changed(path.removesuffix('.spv') + '.json', json.dumps(metadata, indent=2, sort_keys=True))
write_if_changed(path.removesuffix(target.module_extension) + '.json', json.dumps(metadata, indent=2, sort_keys=True))
def spirv_validation_command(target: ShaderTarget, path: str) -> list[str]:
@ -1110,6 +1138,82 @@ def spirv_validation_command(target: ShaderTarget, path: str) -> list[str]:
return ['spirv-val', '--target-env', env, path]
# MSL {{{
# Marks MSL code that has been fixed up by fixup_metal_code()
METAL_FIXUP_MARKER = '// kitty: fixed up for the Metal GPU driver'
def _matching_close(code: str, start: int, open_char: str, close_char: str) -> int:
# The index of the character closing the bracket at code[start]
depth = 0
for i in range(start, len(code)):
c = code[i]
if c == open_char:
depth += 1
elif c == close_char:
depth -= 1
if depth == 0:
return i
raise ValueError(f'Unbalanced {open_char}{close_char} in MSL code')
def fixup_metal_code(msl: str, entry_points: dict[str, str], shader_name: str) -> str:
"""
Make the MSL output of slangc follow the coordinate conventions of the
GPU API, see gpu/api.h. Shaders produce positions with NDC y=-1 at the
top of the viewport, as in Vulkan, while in Metal y=1 is the top, so the
y coordinate of the position output by the vertex entry point is negated.
Everything else, viewports, scissor rectangles and texture coordinates,
already has its origin at the top left in Metal.
"""
if METAL_FIXUP_MARKER in msl:
return msl
for stage, attr in (('vertex', '[[vertex]]'), ('fragment', '[[fragment]]')):
name = entry_points.get(stage, '')
if not re.search(r'^' + re.escape(attr) + r'\s+[^(]*?\b' + re.escape(name) + r'\s*\(', msl, flags=re.MULTILINE):
raise ValueError(f'Could not find the {stage} entry point {name!r} in the MSL shader: {shader_name}')
vertex = entry_points['vertex']
m = re.search(r'^\[\[vertex\]\]\s+(\w+)\s+' + re.escape(vertex) + r'\s*\(', msl, flags=re.MULTILINE)
assert m is not None
result_type = m.group(1)
if result_type == 'float4':
flip = 'r.y = -r.y;'
else:
sm = re.search(r'^struct ' + re.escape(result_type) + r'\s*\{(.*?)^\};', msl, flags=re.MULTILINE | re.DOTALL)
if sm is None:
raise ValueError(f'Could not find the definition of the result type {result_type} of the vertex entry point in the MSL shader: {shader_name}')
fm = re.search(r'(\w+)\s*\[\[position\]\]', sm.group(1))
if fm is None:
raise ValueError(f'The result type of the vertex entry point in the MSL shader: {shader_name} has no position')
flip = f'r.{fm.group(1)}.y = -r.{fm.group(1)}.y;'
params_end = _matching_close(msl, m.end() - 1, '(', ')')
body_start = msl.index('{', params_end)
body_end = _matching_close(msl, body_start, '{', '}')
body, n = re.subn(r'\breturn\s+([^;]+);', r'return kitty_flip_y(\1);', msl[body_start : body_end + 1])
if not n:
raise ValueError(f'The vertex entry point in the MSL shader: {shader_name} has no return statement')
helper = f'{METAL_FIXUP_MARKER}\nstatic inline {result_type} kitty_flip_y({result_type} r) {{ {flip} return r; }}\n\n'
return msl[: m.start()] + helper + msl[m.start() : body_start] + body + msl[body_end + 1 :]
@lru_cache(maxsize=2)
def metal_compiler_available() -> bool:
# The Metal compiler is part of Xcode, it is not available on other platforms
if sys.platform != 'darwin' or not shutil.which('xcrun'):
return False
return subprocess.run(['xcrun', '-sdk', 'macosx', '-f', 'metal'], capture_output=True).returncode == 0
def msl_validation_command(target: ShaderTarget, path: str) -> list[str]:
# Compile the MSL with the Metal compiler, discarding the output
major, minor = divmod(target.version, 10)
return ['xcrun', '-sdk', 'macosx', 'metal', f'-std=macos-metal{major}.{minor}', '-c', path, '-o', os.devnull]
# }}}
# GLSL {{{
@ -1397,13 +1501,14 @@ SHADER_BINDING_SLOTS = MappingProxyType(
)
def check_binding_slot(name: str, slot: int) -> int:
def check_binding_slot(name: str, slot: int | None) -> int:
# Pass slot as None for targets that ignore [[vk::binding]], such as MSL
expected = SHADER_BINDING_SLOTS.get(name)
if expected is None:
raise ValueError(f'The shader resource {name} has no binding slot in SHADER_BINDING_SLOTS')
if slot != expected:
if slot is not None and slot != expected:
raise ValueError(f'The shader resource {name} uses binding slot {slot} instead of {expected}, declare it with [[vk::binding({expected})]]')
return slot
return expected
# The uniform parameters of every program are declared as a single struct,
@ -1420,6 +1525,19 @@ def check_binding_slot(name: str, slot: int) -> int:
# loose uniforms for OpenGL. Vulkan guarantees only this many bytes of push
# constants.
PUSH_CONSTANTS_MAX_SIZE = 128
# The name of the type of the push constant block in the Slang source. Targets
# without push constants, such as MSL, emit the block as an ordinary constant
# buffer, which is recognized by the name of its type.
PUSH_CONSTANTS_TYPE_NAME = 'Params'
# For MSL, Slang assigns indices in the buffer, texture and sampler argument
# tables of Metal itself, ignoring [[vk::binding]]. They are passed to the
# driver as native names, see GPUNativeName in gpu/api.h, of the forms
# "buffer(N)" for uniform and parameter blocks and "texture(N) sampler(M)" for
# textures, the attributes of the parameters in the MSL code. The native name
# of the push constant block is stored under this name, which must match
# MSL_PUSH_CONSTANTS_NAME in gpu/metal/internal.h.
MSL_PUSH_CONSTANTS_NAME = 'push_constants'
_PARAM_SCALARS = MappingProxyType({'float32': 'float', 'int32': 'int', 'uint32': 'uint', 'bool': 'bool'})
@ -1448,6 +1566,25 @@ def param_field(name: str, offset: int, t: dict[str, Any]) -> dict[str, Any]:
}
def check_msl_bools(fields: Sequence[dict[str, Any]]) -> None:
# kitty writes bool parameters as 32 bit values, see GPU_PARAM_BOOL, but
# in MSL bool is a single byte. Since all parameters are 32 bit scalars,
# a lone bool works on the little endian machines Metal runs on, its byte
# is the first one of the 32 bit value and the next field is aligned to
# four bytes either way. Vectors and arrays of bool and consecutive bools
# would be laid out differently, so are not allowed.
for i, f in enumerate(fields):
if f['scalar'] != 'bool':
continue
if f['components'] != 1 or f['count'] != 1:
raise ValueError(f'The shader parameter {f["name"]} is a vector or array of bool, which is not supported by Metal, use uint instead')
if i + 1 < len(fields) and fields[i + 1]['scalar'] == 'bool':
raise ValueError(
f'The shader parameters {f["name"]} and {fields[i + 1]["name"]} are consecutive bools, which are not supported by Metal,'
' use uint instead, or separate them with other parameters'
)
def program_metadata(target: ShaderTarget, reflections: Sequence[dict[str, Any]], native: GLSLMetadata) -> dict[str, Any]:
"""
The metadata about a program passed to the C code. It is generated from the
@ -1469,11 +1606,25 @@ def program_metadata(target: ShaderTarget, reflections: Sequence[dict[str, Any]]
# compiled code.
real_blocks = set(native.uniform_struct_names)
entry_points: dict[str, str] = {}
# The argument table indices assigned by Slang for MSL, see MSL_PUSH_CONSTANTS_NAME
msl_names: dict[str, str] = {}
def msl_bindings(p: dict[str, Any]) -> dict[str, int]:
bindings = p['bindings'] if 'bindings' in p else [p['binding']]
return {b['kind']: b['index'] for b in bindings}
def is_push_constants(p: dict[str, Any]) -> bool:
if target.is_msl:
return p['type']['elementVarLayout']['type'].get('name') == PUSH_CONSTANTS_TYPE_NAME
return bool(p['binding']['kind'] == 'pushConstantBuffer')
for refl in reflections:
for p in refl['parameters']:
t = p['type']
match t['kind']:
case 'constantBuffer' if p['binding']['kind'] == 'pushConstantBuffer':
case 'constantBuffer' if is_push_constants(p):
if target.is_msl:
msl_names[MSL_PUSH_CONSTANTS_NAME] = f'buffer({msl_bindings(p)["constantBuffer"]})'
evl = t['elementVarLayout']
size = evl['binding']['size']
if size > PUSH_CONSTANTS_MAX_SIZE:
@ -1488,7 +1639,11 @@ def program_metadata(target: ShaderTarget, reflections: Sequence[dict[str, Any]]
evl = t['elementVarLayout']
et = evl['type']
tname = et['name']
slot = check_binding_slot(tname, p['binding']['index'])
if target.is_msl:
slot = check_binding_slot(tname, None)
msl_names[tname] = f'buffer({msl_bindings(p)["constantBuffer"]})'
else:
slot = check_binding_slot(tname, p['binding']['index'])
if tname in PIPELINE_CONSTANT_BLOCKS:
param_blocks[tname] = {
'name': tname,
@ -1496,7 +1651,7 @@ def program_metadata(target: ShaderTarget, reflections: Sequence[dict[str, Any]]
'size': evl['binding']['size'],
'fields': [param_field(f['name'], f['binding']['offset'], f['type']) for f in et['fields']],
}
elif tname in real_blocks or target.is_spirv:
elif tname in real_blocks or target.is_single_module:
arrays = {}
for f in et['fields']:
ft = f['type']
@ -1506,7 +1661,14 @@ def program_metadata(target: ShaderTarget, reflections: Sequence[dict[str, Any]]
# Otherwise the block is declared in an imported module but not
# used by this program, so it is not present in the compiled code
case 'resource':
textures[p['name']] = check_binding_slot(p['name'], p['binding']['index'])
if target.is_msl:
textures[p['name']] = check_binding_slot(p['name'], None)
b = msl_bindings(p)
if 'shaderResource' not in b or 'samplerState' not in b:
raise ValueError(f'The texture {p["name"]} must be a combined texture and sampler, such as Sampler2D')
msl_names[p['name']] = f'texture({b["shaderResource"]}) sampler({b["samplerState"]})'
else:
textures[p['name']] = check_binding_slot(p['name'], p['binding']['index'])
case _:
raise ValueError(f'Unsupported shader parameter: {p["name"]} of kind: {t["kind"]}')
for ep in refl['entryPoints']:
@ -1524,9 +1686,13 @@ def program_metadata(target: ShaderTarget, reflections: Sequence[dict[str, Any]]
f'The {stage} entry point has the uniform parameter: {p["name"]}, uniform parameters must be declared'
' in a push constant block, see PUSH_CONSTANTS_MAX_SIZE'
)
if target.is_msl:
for pb in param_blocks.values():
check_msl_bools(pb['fields'])
native_names = {k: v.partition('[')[0] for k, v in native.loose_uniforms.items()} # ]
native_names.update(native.uniform_struct_names)
native_names.update(native.native_inputs)
native_names.update(msl_names)
return {
'target': target.id,
'entry_points': entry_points,
@ -1626,17 +1792,19 @@ def compile_builtin_shaders(build_dir: str, dest_dir: str, parallel_run: Paralle
target_commands: list[Iterator[Command]] = []
for target in targets:
built_files[target] = []
if target.is_spirv:
target_commands.append(commands_to_compile_to_spirv(source_tree, build_dir, dest_dir, target, built_files[target]))
if target.is_single_module:
target_commands.append(commands_to_compile_to_module(source_tree, build_dir, dest_dir, target, built_files[target]))
else:
target_commands.append(commands_to_compile_to_glsl(source_tree, build_dir, dest_dir, target, built_files[target]))
# Now run all commands
parallel_run(chain(*target_commands))
for target, built in built_files.items():
if target.is_spirv:
write_spirv_metadata(built, target, build_dir)
if shutil.which('spirv-val'):
if target.is_single_module:
write_module_metadata(built, target, build_dir)
if target.is_spirv and shutil.which('spirv-val'):
parallel_run((True, f'Validating |{os.path.basename(x)}| ...', spirv_validation_command(target, x)) for x in built)
if target.is_msl and metal_compiler_available():
parallel_run((True, f'Validating |{os.path.basename(x)}| ...', msl_validation_command(target, x)) for x in built)
continue
fixup_opengl_files(built, target, build_dir)
if shutil.which('glslangValidator'):
@ -2368,7 +2536,7 @@ def build_custom_shader_pipeline(
"""
Build the program for a custom shader pipeline, for the specified shader
target. Returns the vertex and fragment shaders, which are the same module
for SPIR-V, and the program metadata.
for SPIR-V and MSL, and the program metadata.
"""
import kitty.constants as kc
@ -2411,14 +2579,20 @@ def build_custom_shader_pipeline(
inc.extend(('-I', x))
cmd = list(slangc()) + inc + ['-warnings-as-errors', 'all', '-line-directive-mode', 'none', '-lang', 'slang'] + target.slangc_args
src = module_wrapper_for_slot(slot)
if target.is_spirv:
if target.is_single_module:
# A single module containing both entry points
module = os.path.join(out_dir, f'{slot}.spv')
mname = f'{slot}{target.module_extension}'
module = os.path.join(out_dir, mname)
if module_mtime > safe_mtime(metadata):
run(((f'{slot}.spv', cmd + ['-o', module, '-reflection-json', reflection_path(target, out_dir, module), '--', '-']),), src)
write_spirv_metadata((module,), target, out_dir)
with open(module, 'rb') as sf:
vcode: str | bytes = sf.read()
run(((mname, cmd + ['-o', module, '-reflection-json', reflection_path(target, out_dir, module), '--', '-']),), src)
write_module_metadata((module,), target, out_dir)
vcode: str | bytes
if target.is_msl:
with open(module) as tf:
vcode = tf.read()
else:
with open(module, 'rb') as sf:
vcode = sf.read()
fcode = vcode
else:
vertex = os.path.join(out_dir, f'{slot}.vert.glsl')

View file

@ -164,6 +164,9 @@ class TestBuild(BaseTest):
self.assertTrue(hasattr(lib, 'kitty_gpu_driver_load'), f'{path} does not export kitty_gpu_driver_load')
check('opengl')
if is_macos:
check('metal')
self.assertTrue(glob.glob(os.path.join(shaders_dir, 'msl-*', 'cell.json')), 'The built-in shaders have not been compiled for the Metal GPU driver')
# The Vulkan driver is built only when the Vulkan headers are available
if not is_macos and os.path.exists(gpu_driver_path('vulkan')):
check('vulkan')

View file

@ -14,6 +14,8 @@ from unittest.mock import patch
from kitty.constants import gpu_driver_path, shaders_dir, slangc
from kitty.fast_data_types import gpu_shader_target, load_gpu_driver
from kitty.shaders.slang import (
METAL_FIXUP_MARKER,
MSL_PUSH_CONSTANTS_NAME,
PUSH_CONSTANTS_MAX_SIZE,
EntryPoint,
GLSLMetadata,
@ -30,7 +32,10 @@ from kitty.shaders.slang import (
clear_caches,
custom_shader,
defines_pointer_map,
fixup_metal_code,
get_custom_pipeline_src,
metal_compiler_available,
msl_validation_command,
parse_pipeline_definition,
parse_slang_declarations,
parse_slang_text,
@ -121,6 +126,116 @@ class TestSlang(BaseTest):
with self.assertRaises(ValueError):
program_metadata(target, [refl], GLSLMetadata())
def test_msl_target(self):
# Metal has y=1 at the top in NDC, the vertex entry point negates it, see fixup_metal_code()
msl = """
struct Params_0
{
float4 rect_0;
};
struct vertex_main_Result_0
{
float2 texcoord_0 [[user(TEXCOORD)]];
float4 position_0 [[position]];
};
[[vertex]] vertex_main_Result_0 vertex_main(uint vertex_id_0 [[vertex_id]], Params_0 constant* uniforms_0 [[buffer(0)]])
{
vertex_main_Result_0 r_0;
if (vertex_id_0 == 0U) { r_0.position_0 = float4(0); return r_0; }
r_0.position_0 = float4(1);
return r_0;
}
[[fragment]] float4 fragment_main(float2 texcoord_0 [[stage_in]]) { return float4(texcoord_0, 0, 1); }
"""
eps = {'vertex': 'vertex_main', 'fragment': 'fragment_main'}
fixed = fixup_metal_code(msl, eps, 'test')
self.assertIn(METAL_FIXUP_MARKER, fixed)
self.assertIn('r.position_0.y = -r.position_0.y;', fixed)
self.assertEqual(2, fixed.count('return kitty_flip_y(r_0);'))
self.assertIn('return float4(texcoord_0, 0, 1);', fixed)
self.ae(fixed, fixup_metal_code(fixed, eps, 'test'))
with self.assertRaises(ValueError):
fixup_metal_code(msl, {'vertex': 'missing', 'fragment': 'fragment_main'}, 'test')
# Slang assigns Metal argument table indices itself, they are passed
# as native names, while the slots remain those of SHADER_BINDING_SLOTS
target = ShaderTarget.parse('msl-24')
self.assertTrue(target.is_msl and target.is_single_module)
scalar = {'kind': 'scalar', 'scalarType': 'float32'}
def cbuffer(var: str, tname: str, index: int, fields: list[dict]) -> dict:
return {
'name': var,
'binding': {'kind': 'constantBuffer', 'index': index},
'type': {
'kind': 'constantBuffer',
'elementVarLayout': {
'type': {'kind': 'struct', 'name': tname, 'fields': fields},
'binding': {'kind': 'uniform', 'offset': 0, 'size': 4 * len(fields)},
},
},
}
def field(name: str, offset: int, scalar_type: str = 'float32') -> dict:
return {'name': name, 'type': {'kind': 'scalar', 'scalarType': scalar_type}, 'binding': {'kind': 'uniform', 'offset': offset, 'size': 4}}
texture = {
'name': 'sprites',
'bindings': [{'kind': 'shaderResource', 'index': 1}, {'kind': 'samplerState', 'index': 2}],
'type': {'kind': 'resource', 'baseShape': 'texture2D', 'combined': True, 'resultType': scalar},
}
refl = {
'parameters': [
cbuffer('uniforms', 'Params', 0, [field('a', 0), field('b', 4)]),
cbuffer('crd', 'CellRenderData', 3, [field('x', 0)]),
cbuffer('glt', 'GammaLUT', 2, [field('gamma_lut', 0)]),
texture,
],
'entryPoints': [{'name': 'vertex_main', 'stage': 'vertex', 'parameters': []}, {'name': 'fragment_main', 'stage': 'fragment', 'parameters': []}],
}
m = program_metadata(target, [refl], GLSLMetadata())
self.ae(m['target'], 'msl-24')
self.ae(m['entry_points'], {'vertex': 'vertex_main', 'fragment': 'fragment_main'})
self.ae(m['textures'], {'sprites': 0})
self.ae(m['blocks']['CellRenderData']['slot'], 6)
self.ae(
m['native_names'],
{MSL_PUSH_CONSTANTS_NAME: 'buffer(0)', 'CellRenderData': 'buffer(3)', 'GammaLUT': 'buffer(2)', 'sprites': 'texture(1) sampler(2)'},
)
self.ae([(b['name'], b['slot']) for b in m['param_blocks']], [('GammaLUT', 8), ('', -1)])
# Metal bools are a single byte, see check_msl_bools()
refl['parameters'][0] = cbuffer('uniforms', 'Params', 0, [field('a', 0, 'bool'), field('b', 4, 'bool')])
with self.assertRaises(ValueError):
program_metadata(target, [refl], GLSLMetadata())
refl['parameters'][0] = cbuffer('uniforms', 'Params', 0, [field('a', 0, 'bool'), field('b', 4)])
program_metadata(target, [refl], GLSLMetadata())
# The built-in shaders compiled for MSL, if they were built
tdir = os.path.join(shaders_dir, target.id)
if not os.path.isdir(tdir):
return
names = [x for x in os.listdir(tdir) if x.endswith('.json')]
self.assertTrue(names, f'No compiled shaders in {tdir}')
for name in names:
with open(os.path.join(tdir, name)) as f:
m = json.load(f)
with open(os.path.join(tdir, name.replace('.json', '.metal'))) as f:
code = f.read()
self.assertIn(METAL_FIXUP_MARKER, code, name)
nn = m['native_names']
if any(b['slot'] < 0 for b in m['param_blocks']):
self.assertRegex(nn[MSL_PUSH_CONSTANTS_NAME], r'^buffer\(\d+\)$', name)
for tex in m['textures']:
self.assertRegex(nn[tex], r'^texture\(\d+\) sampler\(\d+\)$', name)
for block in list(m['blocks']) + [b['name'] for b in m['param_blocks'] if b['slot'] >= 0]:
# Vertex buffers use the highest buffer indices, see VERTEX_BUFFER_INDEX in gpu/metal/internal.h
self.assertLess(int(nn[block][len('buffer(') : -1]), 15, name)
for ep in m['entry_points'].values():
self.assertIn(f' {ep}(', code, name)
def test_animation_step_parsing(self):
def step(val):
return parse_pipeline_definition(['startgroup', f'animation_step {val}', 'shaders focus-highlight', 'endgroup'], 'test')['groups'][0][
@ -966,11 +1081,14 @@ float f() { static const float SCAN = 2; return SCAN; }
if entry.name.endswith('.slang') and entry.name[: -len('.slang')] not in _SUPPORT_SHADER_NAMES
)
# Compile for the target of the loaded driver and for SPIR-V, used by
# the Vulkan driver, which may not be loadable on the test machine
# Compile for the target of the loaded driver and for SPIR-V and MSL,
# used by the Vulkan and Metal drivers, which may not be loadable on
# the test machine
targets = [driver_shader_target()]
if not targets[0].is_spirv:
targets.append(ShaderTarget('spirv', 16))
if not targets[0].is_msl:
targets.append(ShaderTarget('msl', 24))
failures: list[str] = []
def check(name: str, target: ShaderTarget, vert_src: str | bytes, frag_src: str | bytes, tdir: str) -> None:
@ -985,6 +1103,16 @@ float f() { static const float SCAN = 2; return SCAN; }
cp = subprocess.run(spirv_validation_command(target, path), capture_output=True)
if cp.returncode != 0:
failures.append(f'{name}: invalid SPIR-V: {cp.stderr.decode()}{cp.stdout.decode()}')
if target.is_msl and isinstance(vert_src, str):
if METAL_FIXUP_MARKER not in vert_src:
failures.append(f'{name}: the MSL code was not fixed up')
if metal_compiler_available():
path = os.path.join(tdir, 'check.metal')
with open(path, 'w') as f:
f.write(vert_src)
cp = subprocess.run(msl_validation_command(target, path), capture_output=True)
if cp.returncode != 0:
failures.append(f'{name}: invalid MSL: {cp.stderr.decode()}{cp.stdout.decode()}')
for target in targets:
with tempfile.TemporaryDirectory() as cache_dir:

View file

@ -1303,7 +1303,7 @@ def build_wayland_protocols(
def gpu_api_headers() -> List[str]:
return ['gpu/api.h', 'gpu/opengl/version.h', 'gpu/vulkan/version.h']
return ['gpu/api.h', 'gpu/opengl/version.h', 'gpu/vulkan/version.h', 'gpu/metal/version.h']
@lru_cache(maxsize=2)
@ -1323,10 +1323,13 @@ def vulkan_headers_available() -> bool:
def gpu_drivers_to_build() -> List[str]:
# The GPU drivers built for this platform. OpenGL is built on all platforms
# and Vulkan on platforms other than macOS, when its headers are available.
# The GPU drivers built for this platform. OpenGL is built on all
# platforms, Metal on macOS and Vulkan on other platforms, when its headers
# are available.
ans = ['opengl']
if not is_macos:
if is_macos:
ans.insert(0, 'metal')
else:
if vulkan_headers_available():
ans.insert(0, 'vulkan')
else:
@ -1334,6 +1337,21 @@ def gpu_drivers_to_build() -> List[str]:
return ans
# TODO: Remove once the Metal GPU driver is complete. The shaders for the
# Metal driver are needed only on macOS, they are also built on other
# platforms, where the slangc output can be checked but not run, while the
# Metal driver is being developed.
BUILD_METAL_SHADERS_ON_ALL_PLATFORMS = True
def gpu_shader_targets_to_build() -> List[str]:
# The shader targets the built-in shaders are compiled for, those of the GPU drivers being built
drivers = gpu_drivers_to_build()
if BUILD_METAL_SHADERS_ON_ALL_PLATFORMS and 'metal' not in drivers:
drivers.append('metal')
return [t for driver in drivers for t in gpu_driver_shader_targets(driver)]
def gpu_driver_init_env(env: Env, driver: str = 'opengl') -> Env:
ans = env.copy()
ans.cflags.append('-fPIC')
@ -1356,6 +1374,9 @@ def gpu_driver_init_env(env: Env, driver: str = 'opengl') -> Env:
# and libX11 are loaded at runtime.
ans.cflags.extend(pkg_config('x11', '--cflags-only-I'))
ans.ldpaths.append('-ldl')
elif driver == 'metal':
for f_ in ('Metal', 'QuartzCore', 'CoreGraphics', 'Cocoa'):
ans.ldpaths.extend(('-framework', f_))
return ans
@ -1375,6 +1396,12 @@ def gpu_driver_shader_targets(driver: str = 'opengl') -> List[str]:
if m is None:
raise SystemExit('Could not find SPIRV_VERSION in gpu/vulkan/version.h')
return [f'spirv-{m.group(1)}']
if driver == 'metal':
with open('gpu/metal/version.h') as f:
m = re.search(r'^#define MSL_VERSION (\d+)', f.read(), flags=re.MULTILINE)
if m is None:
raise SystemExit('Could not find MSL_VERSION in gpu/metal/version.h')
return [f'msl-{m.group(1)}']
raise KeyError(f'Unknown GPU driver: {driver}')
@ -1385,6 +1412,8 @@ def gpu_driver_sources(driver: str) -> List[str]:
return [f'gpu/{driver}/{x}' for x in common + platform]
if driver == 'vulkan':
return [f'gpu/{driver}/{x}' for x in ('driver.c', 'memory.c', 'commands.c', 'textures.c', 'pipelines.c', 'surfaces.c')]
if driver == 'metal':
return [f'gpu/{driver}/{x}' for x in ('driver.m', 'commands.m', 'buffers.m', 'textures.m', 'pipelines.m', 'surfaces.m')]
raise KeyError(f'Unknown GPU driver: {driver}')
@ -1545,7 +1574,7 @@ def generate_shaders(kitty_exe: str) -> None:
'+launch',
os.path.join(src_base, 'kitty/shaders/slang.py'),
'verbose' if verbose else '',
'--targets=' + ','.join(t for driver in gpu_drivers_to_build() for t in gpu_driver_shader_targets(driver)),
'--targets=' + ','.join(gpu_shader_targets_to_build()),
'build/shaders',
'shaders',
],