summaryrefslogtreecommitdiff
path: root/src/gpu
diff options
context:
space:
mode:
Diffstat (limited to 'src/gpu')
-rw-r--r--src/gpu/Executor.zig746
-rw-r--r--src/gpu/scene.zig263
2 files changed, 1009 insertions, 0 deletions
diff --git a/src/gpu/Executor.zig b/src/gpu/Executor.zig
new file mode 100644
index 0000000..412d0ed
--- /dev/null
+++ b/src/gpu/Executor.zig
@@ -0,0 +1,746 @@
+//! Runs `abi.gpu` passes and dispatches with SDL_GPU: the translation from
+//! GPU work as data to a real API. Shaders and pipelines are built on first
+//! use and cached by the hash of their description; entries a sketch stops
+//! using (an edited shader, after a reload) are released after a while.
+const Gpu = @This();
+const std = @import("std");
+const c = @import("c");
+const abi = @import("abi");
+
+pub const color_format = c.SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
+/// Frames an unused shader or pipeline survives.
+const keep_frames = 300;
+
+gpa: std.mem.Allocator,
+device: *c.SDL_GPUDevice,
+stencil_format: c.SDL_GPUTextureFormat,
+shaders: std.AutoHashMapUnmanaged(u64, Cached(c.SDL_GPUShader)) = .empty,
+pipelines: std.AutoHashMapUnmanaged(u64, Cached(c.SDL_GPUGraphicsPipeline)) = .empty,
+kernels: std.AutoHashMapUnmanaged(u64, Cached(c.SDL_GPUComputePipeline)) = .empty,
+/// Storage buffers by handle: `Buffer` n is `buffers[n - 1]`, null once freed.
+buffers: std.ArrayList(?Storage) = .empty,
+/// Uploads to storage buffers go through this, in chunks of its size.
+staging: ?*c.SDL_GPUTransferBuffer = null,
+/// Render targets per image: the resolved texture the renderer shows, and
+/// multisampled and stencil attachments as passes ask for them.
+targets: std.AutoHashMapUnmanaged(abi.Image, Target) = .empty,
+vertices: ?*c.SDL_GPUBuffer = null,
+vertex_capacity: u32 = 0,
+upload: ?*c.SDL_GPUTransferBuffer = null,
+upload_capacity: u32 = 0,
+post_sampler: ?*c.SDL_GPUSampler = null,
+frame: u64 = 0,
+/// Set by `--profile-gpu`: every command is timed alone (see `Profile`).
+profile: ?Profile = null,
+/// Downloads in flight, oldest first, and transfer buffers to reuse.
+downloads: std.ArrayList(Download) = .empty,
+spare: std.ArrayList(Transfer) = .empty,
+
+const Transfer = struct { buffer: *c.SDL_GPUTransferBuffer, size: u32 };
+const Download = struct { key: u32, size: u32, transfer: Transfer, fence: *c.SDL_GPUFence };
+
+/// CPU wall time per labelled GPU command, from recording through fence wait.
+/// Includes submission and synchronization overhead; not hardware GPU timestamps.
+pub const Profile = struct {
+ entries: std.StringArrayHashMapUnmanaged(Entry) = .empty,
+ arena: std.heap.ArenaAllocator,
+ start_frame: u64 = 0,
+
+ pub const Entry = struct {
+ count: u64 = 0,
+ total: u64 = 0,
+ worst: u64 = 0,
+ samples: [2048]u64 = undefined,
+
+ pub fn add(entry: *Entry, ns: u64) void {
+ entry.samples[@intCast(entry.count % entry.samples.len)] = ns;
+ entry.count += 1;
+ entry.total += ns;
+ entry.worst = @max(entry.worst, ns);
+ }
+
+ pub fn retained(entry: *const Entry) usize {
+ return @intCast(@min(entry.count, entry.samples.len));
+ }
+
+ pub fn sample(entry: *const Entry, index: usize) u64 {
+ std.debug.assert(index < entry.retained());
+ return entry.samples[@intCast((entry.count - entry.retained() + index) % entry.samples.len)];
+ }
+
+ /// Called by inspection only; the render path just writes the ring.
+ pub fn percentiles(entry: *const Entry) [2]u64 {
+ const n = entry.retained();
+ if (n == 0) return .{ 0, 0 };
+ var scratch: [2048]u64 = undefined;
+ @memcpy(scratch[0..n], entry.samples[0..n]);
+ std.mem.sortUnstable(u64, scratch[0..n], {}, std.sort.asc(u64));
+ return .{ scratch[(n * 95 + 99) / 100 - 1], scratch[(n * 99 + 99) / 100 - 1] };
+ }
+ };
+
+ pub fn init(gpa: std.mem.Allocator) Profile {
+ return .{ .arena = .init(gpa) };
+ }
+
+ pub fn deinit(p: *Profile) void {
+ p.arena.deinit();
+ }
+
+ fn add(p: *Profile, label: []const u8, ns: u64) void {
+ const a = p.arena.allocator();
+ const entry = p.entries.getOrPut(a, label) catch return;
+ if (!entry.found_existing) {
+ entry.key_ptr.* = a.dupe(u8, label) catch "?";
+ entry.value_ptr.* = .{};
+ }
+ entry.value_ptr.add(ns);
+ }
+
+ pub fn report(p: *Profile, total_frames: u64) void {
+ const frames = total_frames -| p.start_frame;
+ std.debug.print("gpu time over {d} frames (ms)\n{s: <24} {s: >7} {s: >9} {s: >9} {s: >11}\n", .{ frames, "command", "count", "mean", "worst", "per frame" });
+ var sum: u64 = 0;
+ var it = p.entries.iterator();
+ while (it.next()) |e| {
+ const v = e.value_ptr;
+ sum += v.total;
+ std.debug.print("{s: <24} {d: >7} {d: >9.3} {d: >9.3} {d: >11.3}\n", .{ e.key_ptr.*, v.count, ms(v.total) / @as(f64, @floatFromInt(@max(v.count, 1))), ms(v.worst), ms(v.total) / @as(f64, @floatFromInt(@max(frames, 1))) });
+ }
+ std.debug.print("{s: <24} {s: >7} {s: >9} {s: >9} {d: >11.3}\n", .{ "all", "", "", "", ms(sum) / @as(f64, @floatFromInt(@max(frames, 1))) });
+ }
+
+ fn ms(ns: u64) f64 {
+ return @as(f64, @floatFromInt(ns)) / std.time.ns_per_ms;
+ }
+};
+
+/// Submits `cmd`; when profiling, waits for it and books its time from
+/// `start` (taken on an idle GPU, before recording) under `label`.
+fn submit(g: *Gpu, cmd: *c.SDL_GPUCommandBuffer, label: []const u8, start: u64) !void {
+ const p = if (g.profile) |*profile| profile else {
+ if (!c.SDL_SubmitGPUCommandBuffer(cmd)) return error.GpuSubmit;
+ return;
+ };
+ const fence = c.SDL_SubmitGPUCommandBufferAndAcquireFence(cmd) orelse return error.GpuSubmit;
+ defer c.SDL_ReleaseGPUFence(g.device, fence);
+ _ = c.SDL_WaitForGPUFences(g.device, true, &fence, 1);
+ p.add(label, c.SDL_GetTicksNS() - start);
+}
+
+/// When profiling: waits for the GPU to be idle, then the time to start from.
+fn startTiming(g: *Gpu) u64 {
+ if (g.profile != null) _ = c.SDL_WaitForGPUIdle(g.device);
+ return c.SDL_GetTicksNS();
+}
+
+/// The most bytes one buffer upload stages at a time.
+const staging_size = 4 << 20;
+
+fn Cached(comptime T: type) type {
+ return struct { object: *T, used: u64 };
+}
+
+const Storage = struct { buffer: *c.SDL_GPUBuffer, size: u32 };
+
+const Target = struct {
+ width: u32,
+ height: u32,
+ texture: *c.SDL_GPUTexture,
+ samples: u8 = 1,
+ msaa: ?*c.SDL_GPUTexture = null,
+ /// Not rendered into yet: undefined natively, so the first pass that
+ /// would load clears to zero (WebGPU's starting contents).
+ fresh: bool = true,
+ msaa_fresh: bool = true,
+ stencil_samples: u8 = 0,
+ stencil: ?*c.SDL_GPUTexture = null,
+};
+
+pub fn init(gpa: std.mem.Allocator, device: *c.SDL_GPUDevice) Gpu {
+ const d24 = c.SDL_GPUTextureSupportsFormat(device, c.SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, c.SDL_GPU_TEXTURETYPE_2D, c.SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET);
+ return .{
+ .gpa = gpa,
+ .device = device,
+ .stencil_format = if (d24) c.SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT else c.SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT,
+ };
+}
+
+pub fn deinit(g: *Gpu) void {
+ if (g.profile) |*p| {
+ p.report(g.frame);
+ p.deinit();
+ }
+ var shaders = g.shaders.valueIterator();
+ while (shaders.next()) |s| c.SDL_ReleaseGPUShader(g.device, s.object);
+ var pipelines = g.pipelines.valueIterator();
+ while (pipelines.next()) |p| c.SDL_ReleaseGPUGraphicsPipeline(g.device, p.object);
+ var kernels = g.kernels.valueIterator();
+ while (kernels.next()) |k| c.SDL_ReleaseGPUComputePipeline(g.device, k.object);
+ for (g.buffers.items) |entry| if (entry) |b| c.SDL_ReleaseGPUBuffer(g.device, b.buffer);
+ for (g.downloads.items) |d| {
+ _ = c.SDL_WaitForGPUFences(g.device, true, &d.fence, 1);
+ c.SDL_ReleaseGPUFence(g.device, d.fence);
+ c.SDL_ReleaseGPUTransferBuffer(g.device, d.transfer.buffer);
+ }
+ for (g.spare.items) |t| c.SDL_ReleaseGPUTransferBuffer(g.device, t.buffer);
+ g.downloads.deinit(g.gpa);
+ g.spare.deinit(g.gpa);
+ if (g.staging) |b| c.SDL_ReleaseGPUTransferBuffer(g.device, b);
+ var targets = g.targets.iterator();
+ while (targets.next()) |entry| g.releaseTarget(entry.value_ptr.*);
+ if (g.vertices) |b| c.SDL_ReleaseGPUBuffer(g.device, b);
+ if (g.upload) |b| c.SDL_ReleaseGPUTransferBuffer(g.device, b);
+ if (g.post_sampler) |s| c.SDL_ReleaseGPUSampler(g.device, s);
+ g.shaders.deinit(g.gpa);
+ g.pipelines.deinit(g.gpa);
+ g.kernels.deinit(g.gpa);
+ g.buffers.deinit(g.gpa);
+ g.targets.deinit(g.gpa);
+}
+
+/// Releases what nothing has used for a while.
+pub fn endFrame(g: *Gpu) void {
+ g.frame += 1;
+ inline for (.{ &g.pipelines, &g.shaders, &g.kernels }) |map| {
+ var it = map.iterator();
+ while (it.next()) |entry| {
+ if (g.frame - entry.value_ptr.used < keep_frames) continue;
+ switch (@TypeOf(map)) {
+ @TypeOf(&g.pipelines) => c.SDL_ReleaseGPUGraphicsPipeline(g.device, entry.value_ptr.object),
+ @TypeOf(&g.kernels) => c.SDL_ReleaseGPUComputePipeline(g.device, entry.value_ptr.object),
+ else => c.SDL_ReleaseGPUShader(g.device, entry.value_ptr.object),
+ }
+ map.removeByPtr(entry.key_ptr);
+ // The iterator is invalid after a removal: the rest waits a frame.
+ break;
+ }
+ }
+}
+
+pub fn run(g: *Gpu, pass: abi.gpu.Pass) !void {
+ const start = g.startTiming();
+ const cmd = c.SDL_AcquireGPUCommandBuffer(g.device) orelse return error.GpuCommandBuffer;
+ errdefer _ = c.SDL_CancelGPUCommandBuffer(cmd);
+ try g.record(cmd, pass);
+ try g.submit(cmd, if (pass.label.len > 0) pass.label else "pass", start);
+}
+
+/// Records into the caller's command buffer; the caller submits it.
+/// Uploads cycle their buffers, allowing several passes in one frame.
+pub fn record(g: *Gpu, cmd: *c.SDL_GPUCommandBuffer, pass: abi.gpu.Pass) !void {
+ return g.recordWithInput(cmd, pass, null);
+}
+
+/// A second pass on the same command buffer; input and output must differ.
+pub fn postProcess(g: *Gpu, cmd: *c.SDL_GPUCommandBuffer, source: abi.Image, target: abi.Image, post: abi.gpu.PostProcess) !void {
+ if (source == target) return error.FeedbackLoop;
+ const input = g.output(source) orelse return error.MissingImage;
+ try g.recordWithInput(cmd, .{
+ .image = target,
+ .width = input.width,
+ .height = input.height,
+ .pipelines = &.{.{ .vertex = post.vertex, .fragment = post.fragment, .stride = 0, .attributes = &.{}, .blend = .none }},
+ .draws = &.{.{ .pipeline = 0, .vertex_count = 3, .fragment_uniforms = post.fragment_uniforms }},
+ }, input.texture);
+}
+
+fn recordWithInput(g: *Gpu, cmd: *c.SDL_GPUCommandBuffer, pass: abi.gpu.Pass, input: ?*c.SDL_GPUTexture) !void {
+ if (pass.width == 0 or pass.height == 0 or pass.draws.len == 0 and pass.clear == null) return;
+ if (input != null and g.post_sampler == null) {
+ g.post_sampler = c.SDL_CreateGPUSampler(g.device, &std.mem.zeroInit(c.SDL_GPUSamplerCreateInfo, .{
+ .min_filter = c.SDL_GPU_FILTER_NEAREST,
+ .mag_filter = c.SDL_GPU_FILTER_NEAREST,
+ .address_mode_u = c.SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE,
+ .address_mode_v = c.SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE,
+ })) orelse return error.GpuSampler;
+ }
+ const samples = g.supportedSamples(pass.samples);
+ const t = try g.renderTarget(pass.image, pass.width, pass.height, samples, pass.stencil or pass.depth);
+ // Each pipeline is looked up on first use in the pass, not per draw:
+ // the lookup hashes the shaders' code. Outer null: not looked up yet;
+ // inner null: it failed (warned once).
+ const built = try g.gpa.alloc(??*c.SDL_GPUGraphicsPipeline, pass.pipelines.len);
+ defer g.gpa.free(built);
+ @memset(built, null);
+ // Compile before recording: a refused shader leaves the caller's
+ // command buffer usable and the fallback picture visible.
+ for (pass.draws) |d| {
+ if (d.pipeline >= pass.pipelines.len) return error.BadPipeline;
+ const p = pass.pipelines[d.pipeline];
+ if ((p.depth_test != null or p.depth_write) and !pass.depth) return error.MissingDepthAttachment;
+ if (built[d.pipeline] == null) built[d.pipeline] = try g.pipeline(pass.pipelines[d.pipeline], samples, pass.stencil or pass.depth, @intFromBool(input != null));
+ }
+
+ // Every draw's vertices go up in one copy.
+ var total: u32 = 0;
+ for (pass.draws) |d| total += @intCast(std.mem.alignForward(usize, d.vertices.len, 4));
+ if (total > 0) {
+ try g.reserve(total);
+ const mapped: [*]u8 = @ptrCast(c.SDL_MapGPUTransferBuffer(g.device, g.upload, true) orelse return error.GpuMap);
+ var offset: usize = 0;
+ for (pass.draws) |d| {
+ @memcpy(mapped[offset..][0..d.vertices.len], d.vertices);
+ offset += std.mem.alignForward(usize, d.vertices.len, 4);
+ }
+ c.SDL_UnmapGPUTransferBuffer(g.device, g.upload);
+ const copy = c.SDL_BeginGPUCopyPass(cmd);
+ c.SDL_UploadToGPUBuffer(copy, &.{ .transfer_buffer = g.upload, .offset = 0 }, &.{ .buffer = g.vertices, .offset = 0, .size = total }, true);
+ c.SDL_EndGPUCopyPass(copy);
+ }
+
+ const clear = pass.clear orelse .{ 0, 0, 0, 0 };
+ var color: c.SDL_GPUColorTargetInfo = std.mem.zeroes(c.SDL_GPUColorTargetInfo);
+ color.clear_color = .{ .r = clear[0], .g = clear[1], .b = clear[2], .a = clear[3] };
+ // `clear = null` keeps what the attachment holds, as on the web: a
+ // multisampled pass loads its multisampled attachment, which every
+ // pass therefore stores as well as resolves. A new attachment is
+ // cleared to zero instead, since Vulkan starts it undefined where
+ // WebGPU starts it zeroed.
+ const fresh = if (samples > 1) &t.msaa_fresh else &t.fresh;
+ color.load_op = if (pass.clear != null or fresh.*) c.SDL_GPU_LOADOP_CLEAR else c.SDL_GPU_LOADOP_LOAD;
+ fresh.* = false;
+ if (samples > 1) {
+ color.texture = t.msaa;
+ color.store_op = c.SDL_GPU_STOREOP_RESOLVE_AND_STORE;
+ color.resolve_texture = t.texture;
+ } else {
+ color.texture = t.texture;
+ color.store_op = c.SDL_GPU_STOREOP_STORE;
+ }
+ t.fresh = false;
+ var depth: c.SDL_GPUDepthStencilTargetInfo = std.mem.zeroes(c.SDL_GPUDepthStencilTargetInfo);
+ if (pass.stencil or pass.depth) {
+ depth.texture = t.stencil;
+ depth.load_op = if (pass.depth) c.SDL_GPU_LOADOP_CLEAR else c.SDL_GPU_LOADOP_DONT_CARE;
+ depth.clear_depth = 1;
+ depth.store_op = c.SDL_GPU_STOREOP_DONT_CARE;
+ depth.stencil_load_op = c.SDL_GPU_LOADOP_CLEAR;
+ depth.stencil_store_op = c.SDL_GPU_STOREOP_DONT_CARE;
+ depth.clear_stencil = 0;
+ }
+ const rp = c.SDL_BeginGPURenderPass(cmd, &color, 1, if (pass.stencil or pass.depth) &depth else null) orelse return error.GpuRenderPass;
+ if (input) |texture_| c.SDL_BindGPUFragmentSamplers(rp, 0, &.{ .texture = texture_, .sampler = g.post_sampler.? }, 1);
+ var bound: ?*c.SDL_GPUGraphicsPipeline = null;
+ // State already set in this pass, so draws that repeat it skip the call.
+ var vertex_uniforms: ?[]const u8 = null;
+ var stencil_reference: ?u8 = null;
+ var scissor: ?c.SDL_Rect = null;
+ var vertex_base: ?u32 = null;
+ var offset: u32 = 0;
+ for (pass.draws) |d| {
+ defer offset += @intCast(std.mem.alignForward(usize, d.vertices.len, 4));
+ if (d.pipeline >= pass.pipelines.len or d.vertex_count == 0) continue;
+ const slot = &built[d.pipeline];
+ const chosen = slot.*.? orelse continue;
+ if (bound != chosen) {
+ c.SDL_BindGPUGraphicsPipeline(rp, chosen);
+ bound = chosen;
+ }
+ // Vertices at a multiple of the stride are reached from one binding
+ // at 0 by the draw's first vertex; others get a binding of their own.
+ var first: u32 = 0;
+ if (d.vertices.len > 0) {
+ const stride = pass.pipelines[d.pipeline].stride;
+ const base = if (stride > 0 and offset % stride == 0) 0 else offset;
+ if (base == 0 and stride > 0) first = offset / stride;
+ if (vertex_base != base) {
+ c.SDL_BindGPUVertexBuffers(rp, 0, &.{ .buffer = g.vertices, .offset = base }, 1);
+ vertex_base = base;
+ }
+ }
+ var bound_storage: [8]*c.SDL_GPUBuffer = undefined;
+ if (d.vertex_storage.len > 0) c.SDL_BindGPUVertexStorageBuffers(rp, 0, &bound_storage, g.resolve(d.vertex_storage, &bound_storage) catch continue);
+ if (d.fragment_storage.len > 0) c.SDL_BindGPUFragmentStorageBuffers(rp, 0, &bound_storage, g.resolve(d.fragment_storage, &bound_storage) catch continue);
+ // Pushed uniforms stay for later draws: the same bytes (sketches
+ // share one slice for a pass's viewport) need no second push.
+ if (d.vertex_uniforms.len > 0) if (vertex_uniforms == null or vertex_uniforms.?.ptr != d.vertex_uniforms.ptr or vertex_uniforms.?.len != d.vertex_uniforms.len) {
+ c.SDL_PushGPUVertexUniformData(cmd, 0, d.vertex_uniforms.ptr, @intCast(d.vertex_uniforms.len));
+ vertex_uniforms = d.vertex_uniforms;
+ };
+ if (d.fragment_uniforms.len > 0) c.SDL_PushGPUFragmentUniformData(cmd, 0, d.fragment_uniforms.ptr, @intCast(d.fragment_uniforms.len));
+ if (pass.stencil and stencil_reference != d.stencil_reference) {
+ c.SDL_SetGPUStencilReference(rp, d.stencil_reference);
+ stencil_reference = d.stencil_reference;
+ }
+ const full: abi.Rect = .{ .w = @floatFromInt(pass.width), .h = @floatFromInt(pass.height) };
+ const s = d.scissor orelse full;
+ const rect: c.SDL_Rect = .{ .x = @intFromFloat(@max(s.x, 0)), .y = @intFromFloat(@max(s.y, 0)), .w = @intFromFloat(@max(s.w, 0)), .h = @intFromFloat(@max(s.h, 0)) };
+ if (scissor == null or !std.meta.eql(scissor.?, rect)) {
+ c.SDL_SetGPUScissor(rp, &rect);
+ scissor = rect;
+ }
+ c.SDL_DrawGPUPrimitives(rp, d.vertex_count, 1, first, 0);
+ }
+ c.SDL_EndGPURenderPass(rp);
+}
+
+/// Runs one dispatch in a compute pass of its own.
+pub fn compute(g: *Gpu, d: abi.gpu.Dispatch) !void {
+ if (d.groups[0] == 0 or d.groups[1] == 0 or d.groups[2] == 0) return;
+ const built = try g.kernel(d.kernel);
+ const start = g.startTiming();
+ var readonly: [8]*c.SDL_GPUBuffer = undefined;
+ const readonly_count = try g.resolve(d.readonly, &readonly);
+ var readwrite: [8]*c.SDL_GPUBuffer = undefined;
+ const readwrite_count = try g.resolve(d.readwrite, &readwrite);
+ var bindings: [8]c.SDL_GPUStorageBufferReadWriteBinding = undefined;
+ for (readwrite[0..readwrite_count], bindings[0..readwrite_count]) |b, *binding| binding.* = std.mem.zeroInit(c.SDL_GPUStorageBufferReadWriteBinding, .{ .buffer = b });
+ const cmd = c.SDL_AcquireGPUCommandBuffer(g.device) orelse return error.GpuCommandBuffer;
+ const pass = c.SDL_BeginGPUComputePass(cmd, null, 0, &bindings, readwrite_count) orelse {
+ _ = c.SDL_CancelGPUCommandBuffer(cmd);
+ return error.GpuComputePass;
+ };
+ c.SDL_BindGPUComputePipeline(pass, built);
+ if (readonly_count > 0) c.SDL_BindGPUComputeStorageBuffers(pass, 0, &readonly, readonly_count);
+ if (d.uniforms.len > 0) c.SDL_PushGPUComputeUniformData(cmd, 0, d.uniforms.ptr, @intCast(d.uniforms.len));
+ c.SDL_DispatchGPUCompute(pass, d.groups[0], d.groups[1], d.groups[2]);
+ c.SDL_EndGPUComputePass(pass);
+ try g.submit(cmd, if (d.label.len > 0) d.label else "compute", start);
+}
+
+/// A zeroed storage buffer, readable by every stage and writable by compute.
+pub fn newBuffer(g: *Gpu, size: u32) !abi.Buffer {
+ if (size == 0) return error.EmptyBuffer;
+ const usage = c.SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ | c.SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ | c.SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE;
+ const buffer = c.SDL_CreateGPUBuffer(g.device, &.{ .usage = usage, .size = size, .props = 0 }) orelse return error.GpuBuffer;
+ errdefer c.SDL_ReleaseGPUBuffer(g.device, buffer);
+ try g.buffers.append(g.gpa, .{ .buffer = buffer, .size = size });
+ const handle: abi.Buffer = @fromBackingInt(@intCast(g.buffers.items.len));
+ // Vulkan leaves new memory undefined; sketches get zeroes, copied from
+ // one zeroed staging block as many times as it takes.
+ const staging = try g.stagingBuffer();
+ const block: u32 = @min(size, staging_size);
+ const mapped: [*]u8 = @ptrCast(c.SDL_MapGPUTransferBuffer(g.device, staging, true) orelse return error.GpuMap);
+ @memset(mapped[0..block], 0);
+ c.SDL_UnmapGPUTransferBuffer(g.device, staging);
+ const cmd = c.SDL_AcquireGPUCommandBuffer(g.device) orelse return error.GpuCommandBuffer;
+ const copy = c.SDL_BeginGPUCopyPass(cmd);
+ var offset: u32 = 0;
+ while (offset < size) : (offset += block) {
+ c.SDL_UploadToGPUBuffer(copy, &.{ .transfer_buffer = staging, .offset = 0 }, &.{ .buffer = buffer, .offset = offset, .size = @min(block, size - offset) }, false);
+ }
+ c.SDL_EndGPUCopyPass(copy);
+ if (!c.SDL_SubmitGPUCommandBuffer(cmd)) return error.GpuSubmit;
+ return handle;
+}
+
+fn stagingBuffer(g: *Gpu) !*c.SDL_GPUTransferBuffer {
+ if (g.staging == null) g.staging = c.SDL_CreateGPUTransferBuffer(g.device, &.{ .usage = c.SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, .size = staging_size, .props = 0 }) orelse return error.GpuBuffer;
+ return g.staging.?;
+}
+
+pub fn freeBuffer(g: *Gpu, handle: abi.Buffer) void {
+ const index = @backingInt(handle);
+ if (index == 0 or index > g.buffers.items.len) return;
+ const entry = &g.buffers.items[index - 1];
+ if (entry.*) |b| c.SDL_ReleaseGPUBuffer(g.device, b.buffer);
+ entry.* = null;
+}
+
+/// Copies `bytes` into a buffer at `offset`, through the staging buffer.
+pub fn write(g: *Gpu, handle: abi.Buffer, offset: u32, bytes: []const u8) !void {
+ const target = g.storage(handle) orelse return error.UnknownBuffer;
+ if (@as(u64, offset) + bytes.len > target.size) return error.UploadOutOfBounds;
+ const staging = try g.stagingBuffer();
+ var done: usize = 0;
+ while (done < bytes.len) {
+ const chunk = bytes[done..][0..@min(staging_size, bytes.len - done)];
+ const start = g.startTiming();
+ // Cycling: a chunk still in flight keeps its own memory.
+ const mapped: [*]u8 = @ptrCast(c.SDL_MapGPUTransferBuffer(g.device, staging, true) orelse return error.GpuMap);
+ @memcpy(mapped[0..chunk.len], chunk);
+ c.SDL_UnmapGPUTransferBuffer(g.device, staging);
+ const cmd = c.SDL_AcquireGPUCommandBuffer(g.device) orelse return error.GpuCommandBuffer;
+ const copy = c.SDL_BeginGPUCopyPass(cmd);
+ c.SDL_UploadToGPUBuffer(copy, &.{ .transfer_buffer = staging, .offset = 0 }, &.{ .buffer = target.buffer, .offset = offset + @as(u32, @intCast(done)), .size = @intCast(chunk.len) }, false);
+ c.SDL_EndGPUCopyPass(copy);
+ try g.submit(cmd, "upload", start);
+ done += chunk.len;
+ }
+}
+
+/// Starts copying `size` bytes of a buffer from `offset` back to the CPU;
+/// `collect` hands them over once the GPU is done, a frame or more later.
+pub fn download(g: *Gpu, d: @FieldType(abi.Command, "download")) !void {
+ const source = g.storage(d.buffer) orelse return error.UnknownBuffer;
+ if (d.size == 0 or @as(u64, d.offset) + d.size > source.size) return error.DownloadOutOfBounds;
+ const transfer = for (g.spare.items, 0..) |t, i| {
+ if (t.size >= d.size) break g.spare.swapRemove(i);
+ } else Transfer{
+ .buffer = c.SDL_CreateGPUTransferBuffer(g.device, &.{ .usage = c.SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD, .size = d.size, .props = 0 }) orelse return error.GpuBuffer,
+ .size = d.size,
+ };
+ errdefer g.spare.append(g.gpa, transfer) catch c.SDL_ReleaseGPUTransferBuffer(g.device, transfer.buffer);
+ const cmd = c.SDL_AcquireGPUCommandBuffer(g.device) orelse return error.GpuCommandBuffer;
+ const copy = c.SDL_BeginGPUCopyPass(cmd);
+ c.SDL_DownloadFromGPUBuffer(copy, &.{ .buffer = source.buffer, .offset = d.offset, .size = d.size }, &.{ .transfer_buffer = transfer.buffer, .offset = 0 });
+ c.SDL_EndGPUCopyPass(copy);
+ const fence = c.SDL_SubmitGPUCommandBufferAndAcquireFence(cmd) orelse return error.GpuSubmit;
+ g.downloads.append(g.gpa, .{ .key = d.key, .size = d.size, .transfer = transfer, .fence = fence }) catch |err| {
+ _ = c.SDL_WaitForGPUFences(g.device, true, &fence, 1);
+ c.SDL_ReleaseGPUFence(g.device, fence);
+ return err;
+ };
+}
+
+/// The downloads the GPU has finished, copied into `arena`, in the order
+/// they were asked for.
+pub fn collect(g: *Gpu, arena: std.mem.Allocator) ![]const abi.Download {
+ var done: std.ArrayList(abi.Download) = .empty;
+ while (g.downloads.items.len > 0) {
+ const d = g.downloads.items[0];
+ if (!c.SDL_QueryGPUFence(g.device, d.fence)) break;
+ _ = g.downloads.orderedRemove(0);
+ c.SDL_ReleaseGPUFence(g.device, d.fence);
+ defer g.spare.append(g.gpa, d.transfer) catch c.SDL_ReleaseGPUTransferBuffer(g.device, d.transfer.buffer);
+ const mapped: [*]const u8 = @ptrCast(c.SDL_MapGPUTransferBuffer(g.device, d.transfer.buffer, false) orelse return error.GpuMap);
+ defer c.SDL_UnmapGPUTransferBuffer(g.device, d.transfer.buffer);
+ try done.append(arena, .{ .key = d.key, .bytes = try arena.dupe(u8, mapped[0..d.size]) });
+ }
+ return done.items;
+}
+
+fn storage(g: *Gpu, handle: abi.Buffer) ?Storage {
+ const index = @backingInt(handle);
+ if (index == 0 or index > g.buffers.items.len) return null;
+ return g.buffers.items[index - 1];
+}
+
+/// The SDL buffers behind `handles`, into `out`; returns how many.
+fn resolve(g: *Gpu, handles: []const abi.Buffer, out: []*c.SDL_GPUBuffer) !u32 {
+ if (handles.len > out.len) return error.TooManyBuffers;
+ for (handles, out[0..handles.len]) |handle, *b| b.* = (g.storage(handle) orelse return error.UnknownBuffer).buffer;
+ return @intCast(handles.len);
+}
+
+fn kernel(g: *Gpu, k: abi.gpu.Kernel) !*c.SDL_GPUComputePipeline {
+ var h = std.hash.Wyhash.init(0);
+ h.update(k.code);
+ inline for (.{ k.readonly_buffers, k.readwrite_buffers, k.uniform_buffers, k.threads[0], k.threads[1], k.threads[2] }) |v| h.update(std.mem.asBytes(&@as(u32, v)));
+ const key = h.final();
+ const entry = try g.kernels.getOrPut(g.gpa, key);
+ if (!entry.found_existing) {
+ errdefer _ = g.kernels.remove(key);
+ var info: c.SDL_GPUComputePipelineCreateInfo = std.mem.zeroes(c.SDL_GPUComputePipelineCreateInfo);
+ info.code_size = k.code.len;
+ info.code = k.code.ptr;
+ info.entrypoint = "main";
+ info.format = c.SDL_GPU_SHADERFORMAT_SPIRV;
+ info.num_readonly_storage_buffers = k.readonly_buffers;
+ info.num_readwrite_storage_buffers = k.readwrite_buffers;
+ info.num_uniform_buffers = k.uniform_buffers;
+ info.threadcount_x = k.threads[0];
+ info.threadcount_y = k.threads[1];
+ info.threadcount_z = k.threads[2];
+ entry.value_ptr.object = c.SDL_CreateGPUComputePipeline(g.device, &info) orelse return error.GpuComputePipeline;
+ }
+ entry.value_ptr.used = g.frame;
+ return entry.value_ptr.object;
+}
+
+fn supportedSamples(g: *Gpu, wanted: u8) u8 {
+ var s: u8 = if (wanted >= 8) 8 else if (wanted >= 4) 4 else if (wanted >= 2) 2 else 1;
+ while (s > 1 and !c.SDL_GPUTextureSupportsSampleCount(g.device, color_format, sampleCount(s))) s /= 2;
+ return s;
+}
+
+fn sampleCount(s: u8) c.SDL_GPUSampleCount {
+ return switch (s) {
+ 8 => c.SDL_GPU_SAMPLECOUNT_8,
+ 4 => c.SDL_GPU_SAMPLECOUNT_4,
+ 2 => c.SDL_GPU_SAMPLECOUNT_2,
+ else => c.SDL_GPU_SAMPLECOUNT_1,
+ };
+}
+
+/// The image's render target, (re)created to fit the pass.
+fn renderTarget(g: *Gpu, image: abi.Image, w: u32, h: u32, samples: u8, stencil: bool) !*Target {
+ var entry = try g.targets.getOrPut(g.gpa, image);
+ if (entry.found_existing and (entry.value_ptr.width != w or entry.value_ptr.height != h)) {
+ g.releaseTarget(entry.value_ptr.*);
+ entry.found_existing = false;
+ }
+ if (!entry.found_existing) {
+ errdefer _ = g.targets.remove(image);
+ const resolved = try g.texture(w, h, color_format, c.SDL_GPU_TEXTUREUSAGE_COLOR_TARGET | c.SDL_GPU_TEXTUREUSAGE_SAMPLER, 1);
+ errdefer c.SDL_ReleaseGPUTexture(g.device, resolved);
+ entry.value_ptr.* = .{ .width = w, .height = h, .texture = resolved };
+ }
+ const t = entry.value_ptr;
+ if (samples > 1 and (t.msaa == null or t.samples != samples)) {
+ if (t.msaa) |m| c.SDL_ReleaseGPUTexture(g.device, m);
+ t.msaa = try g.texture(w, h, color_format, c.SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, samples);
+ t.samples = samples;
+ t.msaa_fresh = true;
+ }
+ if (stencil and (t.stencil == null or t.stencil_samples != samples)) {
+ if (t.stencil) |s| c.SDL_ReleaseGPUTexture(g.device, s);
+ t.stencil = try g.texture(w, h, g.stencil_format, c.SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, samples);
+ t.stencil_samples = samples;
+ }
+ return t;
+}
+
+fn releaseTarget(g: *Gpu, t: Target) void {
+ c.SDL_ReleaseGPUTexture(g.device, t.texture);
+ if (t.msaa) |m| c.SDL_ReleaseGPUTexture(g.device, m);
+ if (t.stencil) |s| c.SDL_ReleaseGPUTexture(g.device, s);
+}
+
+/// Forgets an image's target, when the image itself is freed.
+pub fn forget(g: *Gpu, image: abi.Image) void {
+ const t = g.targets.fetchRemove(image) orelse return;
+ g.releaseTarget(t.value);
+}
+
+fn texture(g: *Gpu, w: u32, h: u32, format: c.SDL_GPUTextureFormat, usage: c.SDL_GPUTextureUsageFlags, samples: u8) !*c.SDL_GPUTexture {
+ var info: c.SDL_GPUTextureCreateInfo = std.mem.zeroes(c.SDL_GPUTextureCreateInfo);
+ info.type = c.SDL_GPU_TEXTURETYPE_2D;
+ info.format = format;
+ info.usage = usage;
+ info.width = w;
+ info.height = h;
+ info.layer_count_or_depth = 1;
+ info.num_levels = 1;
+ info.sample_count = sampleCount(samples);
+ return c.SDL_CreateGPUTexture(g.device, &info) orelse error.GpuTexture;
+}
+
+fn reserve(g: *Gpu, bytes: u32) !void {
+ if (bytes > g.vertex_capacity) {
+ const capacity = @max(bytes, g.vertex_capacity * 2, 64 * 1024);
+ if (g.vertices) |b| c.SDL_ReleaseGPUBuffer(g.device, b);
+ g.vertices = c.SDL_CreateGPUBuffer(g.device, &.{ .usage = c.SDL_GPU_BUFFERUSAGE_VERTEX, .size = capacity, .props = 0 }) orelse return error.GpuBuffer;
+ g.vertex_capacity = capacity;
+ }
+ if (bytes > g.upload_capacity) {
+ const capacity = @max(bytes, g.upload_capacity * 2, 64 * 1024);
+ if (g.upload) |b| c.SDL_ReleaseGPUTransferBuffer(g.device, b);
+ g.upload = c.SDL_CreateGPUTransferBuffer(g.device, &.{ .usage = c.SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, .size = capacity, .props = 0 }) orelse return error.GpuBuffer;
+ g.upload_capacity = capacity;
+ }
+}
+
+fn shader(g: *Gpu, s: abi.gpu.Shader, stage: c.SDL_GPUShaderStage, samplers: u32) !struct { *c.SDL_GPUShader, u64 } {
+ var h = std.hash.Wyhash.init(stage);
+ h.update(s.code);
+ h.update(std.mem.asBytes(&s.uniform_buffers));
+ h.update(std.mem.asBytes(&s.storage_buffers));
+ h.update(std.mem.asBytes(&samplers));
+ const key = h.final();
+ const entry = try g.shaders.getOrPut(g.gpa, key);
+ if (!entry.found_existing) {
+ errdefer _ = g.shaders.remove(key);
+ entry.value_ptr.object = c.SDL_CreateGPUShader(g.device, &.{
+ .code_size = s.code.len,
+ .code = s.code.ptr,
+ .entrypoint = "main",
+ .format = c.SDL_GPU_SHADERFORMAT_SPIRV,
+ .stage = stage,
+ .num_samplers = samplers,
+ .num_storage_textures = 0,
+ .num_storage_buffers = s.storage_buffers,
+ .num_uniform_buffers = s.uniform_buffers,
+ .props = 0,
+ }) orelse return error.GpuShader;
+ }
+ entry.value_ptr.used = g.frame;
+ return .{ entry.value_ptr.object, key };
+}
+
+fn pipeline(g: *Gpu, p: abi.gpu.Pipeline, samples: u8, stencil: bool, samplers: u32) !*c.SDL_GPUGraphicsPipeline {
+ const vertex, const vertex_key = try g.shader(p.vertex, c.SDL_GPU_SHADERSTAGE_VERTEX, 0);
+ const fragment, const fragment_key = try g.shader(p.fragment, c.SDL_GPU_SHADERSTAGE_FRAGMENT, samplers);
+ // Field by field: no padding bytes in the key.
+ var h = std.hash.Wyhash.init(vertex_key ^ (fragment_key *% 31));
+ inline for (.{ p.stride, @backingInt(p.primitive), @backingInt(p.blend), @intFromBool(p.write_color), @intFromBool(p.depth_write), if (p.depth_test) |compare| @as(u32, @backingInt(compare)) + 1 else @as(u32, 0), samples, @intFromBool(stencil) }) |v| h.update(std.mem.asBytes(&@as(u32, v)));
+ for (p.attributes) |a| inline for (.{ a.location, @backingInt(a.format), a.offset }) |v| h.update(std.mem.asBytes(&@as(u32, v)));
+ if (p.stencil) |st| inline for (.{ st.front, st.back }) |face| inline for (.{ @backingInt(face.compare), @backingInt(face.pass), @backingInt(face.fail) }) |v| h.update(std.mem.asBytes(&@as(u32, v)));
+ const key = h.final();
+ const entry = try g.pipelines.getOrPut(g.gpa, key);
+ if (!entry.found_existing) {
+ errdefer _ = g.pipelines.remove(key);
+ var attributes: [16]c.SDL_GPUVertexAttribute = undefined;
+ const count = @min(p.attributes.len, attributes.len);
+ for (p.attributes[0..count], attributes[0..count]) |a, *out| out.* = .{
+ .location = a.location,
+ .buffer_slot = 0,
+ .offset = a.offset,
+ .format = switch (a.format) {
+ .float => c.SDL_GPU_VERTEXELEMENTFORMAT_FLOAT,
+ .float2 => c.SDL_GPU_VERTEXELEMENTFORMAT_FLOAT2,
+ .float3 => c.SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3,
+ .float4 => c.SDL_GPU_VERTEXELEMENTFORMAT_FLOAT4,
+ .ubyte4_norm => c.SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4_NORM,
+ },
+ };
+ var blend: c.SDL_GPUColorTargetBlendState = std.mem.zeroes(c.SDL_GPUColorTargetBlendState);
+ blend.enable_blend = p.blend != .none;
+ blend.color_blend_op = c.SDL_GPU_BLENDOP_ADD;
+ blend.alpha_blend_op = c.SDL_GPU_BLENDOP_ADD;
+ blend.src_color_blendfactor = c.SDL_GPU_BLENDFACTOR_ONE;
+ blend.src_alpha_blendfactor = c.SDL_GPU_BLENDFACTOR_ONE;
+ const dst: c.SDL_GPUBlendFactor = if (p.blend == .additive) c.SDL_GPU_BLENDFACTOR_ONE else c.SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA;
+ blend.dst_color_blendfactor = dst;
+ blend.dst_alpha_blendfactor = dst;
+ blend.enable_color_write_mask = true;
+ blend.color_write_mask = if (p.write_color) c.SDL_GPU_COLORCOMPONENT_R | c.SDL_GPU_COLORCOMPONENT_G | c.SDL_GPU_COLORCOMPONENT_B | c.SDL_GPU_COLORCOMPONENT_A else 0;
+ const target_description: c.SDL_GPUColorTargetDescription = .{ .format = color_format, .blend_state = blend };
+ var depth_stencil: c.SDL_GPUDepthStencilState = std.mem.zeroes(c.SDL_GPUDepthStencilState);
+ depth_stencil.enable_depth_test = p.depth_test != null or p.depth_write;
+ depth_stencil.enable_depth_write = p.depth_write;
+ depth_stencil.compare_op = @as(u32, @backingInt(p.depth_test orelse .always)) + 1;
+ if (p.stencil) |st| {
+ depth_stencil.enable_stencil_test = true;
+ depth_stencil.compare_mask = 0xff;
+ depth_stencil.write_mask = 0xff;
+ depth_stencil.front_stencil_state = stencilFace(st.front);
+ depth_stencil.back_stencil_state = stencilFace(st.back);
+ }
+ var info: c.SDL_GPUGraphicsPipelineCreateInfo = std.mem.zeroes(c.SDL_GPUGraphicsPipelineCreateInfo);
+ info.vertex_shader = vertex;
+ info.fragment_shader = fragment;
+ info.vertex_input_state = .{
+ .vertex_buffer_descriptions = &.{ .slot = 0, .pitch = p.stride, .input_rate = c.SDL_GPU_VERTEXINPUTRATE_VERTEX, .instance_step_rate = 0 },
+ // No attributes: the vertex shader makes its own vertices.
+ .num_vertex_buffers = @intFromBool(count > 0),
+ .vertex_attributes = &attributes,
+ .num_vertex_attributes = @intCast(count),
+ };
+ info.primitive_type = switch (p.primitive) {
+ .triangle_list => c.SDL_GPU_PRIMITIVETYPE_TRIANGLELIST,
+ .triangle_strip => c.SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP,
+ .line_list => c.SDL_GPU_PRIMITIVETYPE_LINELIST,
+ .line_strip => c.SDL_GPU_PRIMITIVETYPE_LINESTRIP,
+ };
+ info.rasterizer_state.fill_mode = c.SDL_GPU_FILLMODE_FILL;
+ info.rasterizer_state.cull_mode = c.SDL_GPU_CULLMODE_NONE;
+ info.rasterizer_state.front_face = c.SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE;
+ info.multisample_state.sample_count = sampleCount(samples);
+ info.depth_stencil_state = depth_stencil;
+ info.target_info.color_target_descriptions = &target_description;
+ info.target_info.num_color_targets = 1;
+ info.target_info.depth_stencil_format = g.stencil_format;
+ info.target_info.has_depth_stencil_target = stencil;
+ entry.value_ptr.object = c.SDL_CreateGPUGraphicsPipeline(g.device, &info) orelse return error.GpuPipeline;
+ }
+ entry.value_ptr.used = g.frame;
+ return entry.value_ptr.object;
+}
+
+fn stencilFace(face: abi.gpu.StencilFace) c.SDL_GPUStencilOpState {
+ // Both enums follow SDL's order, after its INVALID.
+ return .{
+ .compare_op = @as(u32, @backingInt(face.compare)) + 1,
+ .pass_op = @as(u32, @backingInt(face.pass)) + 1,
+ .fail_op = @as(u32, @backingInt(face.fail)) + 1,
+ .depth_fail_op = c.SDL_GPU_STENCILOP_KEEP,
+ };
+}
+
+/// Borrowed until resize, forget, or deinit. The executor owns the texture.
+pub fn output(g: *Gpu, image: abi.Image) ?struct { texture: *c.SDL_GPUTexture, width: u32, height: u32 } {
+ const t = g.targets.get(image) orelse return null;
+ return .{ .texture = t.texture, .width = t.width, .height = t.height };
+}
diff --git a/src/gpu/scene.zig b/src/gpu/scene.zig
new file mode 100644
index 0000000..e5ff3d0
--- /dev/null
+++ b/src/gpu/scene.zig
@@ -0,0 +1,263 @@
+//! Optional, self-contained GPU frames for embedders and remote views.
+//! Version 1: "SGPU", u32 version, then Pass fields in declaration order.
+//! Version 2 appends one fullscreen PostProcess sampling that pass's output.
+//! Version 3 adds depth fields and an optional PostProcess after the pass.
+//! Integers/enums/f32 are little endian; slices have a u32 count, optionals
+//! and bools a byte (0 or 1). No pointers, native padding, or device handles.
+//! Storage buffers are not part of this version: each frame stands alone.
+const std = @import("std");
+pub const abi = @import("abi");
+pub const max_bytes = 4 << 20;
+pub const Frame = struct { pass: abi.gpu.Pass, post: ?abi.gpu.PostProcess = null };
+
+pub fn encode(w: *std.Io.Writer, pass: abi.gpu.Pass) !void {
+ try validate(pass);
+ try w.writeAll("SGPU");
+ const version: u32 = if (pass.depth) 3 else 1;
+ try w.writeInt(u32, version, .little);
+ try put(w, pass, version);
+ if (version == 3) try put(w, @as(?abi.gpu.PostProcess, null), version);
+}
+
+pub fn encodePostProcess(w: *std.Io.Writer, pass: abi.gpu.Pass, post: abi.gpu.PostProcess) !void {
+ try validate(pass);
+ try validatePostProcess(post);
+ try w.writeAll("SGPU");
+ const version: u32 = if (pass.depth) 3 else 2;
+ try w.writeInt(u32, version, .little);
+ try put(w, pass, version);
+ if (version == 3) try put(w, @as(?abi.gpu.PostProcess, post), version) else try put(w, post, version);
+}
+
+/// Allocations belong to the caller's frame arena. Never run unvalidated
+/// wire data through a driver; this checks lengths, layouts and indices.
+pub fn decode(arena: std.mem.Allocator, bytes: []const u8) !abi.gpu.Pass {
+ const frame = try decodeFrame(arena, bytes);
+ if (frame.post != null) return error.BadScene;
+ return frame.pass;
+}
+
+pub fn decodeFrame(arena: std.mem.Allocator, bytes: []const u8) !Frame {
+ if (bytes.len > max_bytes) return error.SceneTooLarge;
+ var r: std.Io.Reader = .fixed(bytes);
+ if (!std.mem.eql(u8, try r.take(4), "SGPU")) return error.BadScene;
+ const version = try r.takeInt(u32, .little);
+ if (version < 1 or version > 3) return error.BadScene;
+ var budget: usize = max_bytes * 4;
+ const pass = try get(abi.gpu.Pass, arena, &r, &budget, version);
+ const post: ?abi.gpu.PostProcess = if (version == 3) try get(?abi.gpu.PostProcess, arena, &r, &budget, version) else if (version == 2) try get(abi.gpu.PostProcess, arena, &r, &budget, version) else null;
+ if (r.end != r.seek) return error.BadScene;
+ try validate(pass);
+ if (post) |p| try validatePostProcess(p);
+ return .{ .pass = pass, .post = post };
+}
+
+fn depthField(comptime T: type, comptime name: []const u8) bool {
+ return (T == abi.gpu.Pass and std.mem.eql(u8, name, "depth")) or
+ (T == abi.gpu.Pipeline and (std.mem.eql(u8, name, "depth_test") or std.mem.eql(u8, name, "depth_write")));
+}
+
+fn put(w: *std.Io.Writer, value: anytype, version: u32) anyerror!void {
+ const T = @TypeOf(value);
+ switch (@typeInfo(T)) {
+ .int => try w.writeInt(T, value, .little),
+ .float => try w.writeInt(u32, @bitCast(value), .little),
+ .bool => try w.writeByte(@intFromBool(value)),
+ .@"enum" => try w.writeInt(u32, @intCast(@backingInt(value)), .little),
+ .optional => {
+ try w.writeByte(@intFromBool(value != null));
+ if (value) |v| try put(w, v, version);
+ },
+ .array => for (value) |v| try put(w, v, version),
+ .pointer => {
+ try w.writeInt(u32, @intCast(value.len), .little);
+ for (value) |v| try put(w, v, version);
+ },
+ .@"struct" => |s| inline for (s.field_names) |name| {
+ if (version >= 3 or !depthField(T, name)) try put(w, @field(value, name), version);
+ },
+ else => @compileError("unsupported scene field"),
+ }
+}
+
+fn get(comptime T: type, a: std.mem.Allocator, r: *std.Io.Reader, budget: *usize, version: u32) anyerror!T {
+ switch (@typeInfo(T)) {
+ .int => return r.takeInt(T, .little),
+ .float => return @bitCast(try r.takeInt(u32, .little)),
+ .bool => return switch (try r.takeByte()) {
+ 0 => false,
+ 1 => true,
+ else => error.BadScene,
+ },
+ .@"enum" => |e| {
+ const n = try r.takeInt(u32, .little);
+ inline for (e.field_names, e.field_values) |name, value| if (n == value) return @field(T, name);
+ return error.BadScene;
+ },
+ .optional => |o| return switch (try r.takeByte()) {
+ 0 => null,
+ 1 => try get(o.child, a, r, budget, version),
+ else => error.BadScene,
+ },
+ .array => |ar| {
+ var out: T = undefined;
+ for (&out) |*v| v.* = try get(ar.child, a, r, budget, version);
+ return out;
+ },
+ .pointer => |p| {
+ const n = try r.takeInt(u32, .little);
+ const size = std.math.mul(usize, n, @sizeOf(p.child)) catch return error.SceneTooLarge;
+ if (size > budget.* or n > max_bytes) return error.SceneTooLarge;
+ budget.* -= size;
+ // SPIR-V must be word aligned, including after a wire decode.
+ const out = try a.alignedAlloc(p.child, .fromByteUnits(@max(4, @alignOf(p.child))), n);
+ for (out) |*v| v.* = try get(p.child, a, r, budget, version);
+ return out;
+ },
+ .@"struct" => |s| {
+ var out: T = undefined;
+ inline for (s.field_names, s.field_types) |name, F| {
+ @field(out, name) = if (version < 3 and comptime depthField(T, name)) std.mem.zeroes(F) else try get(F, a, r, budget, version);
+ }
+ return out;
+ },
+ else => @compileError("unsupported scene field"),
+ }
+}
+
+fn shader(s: abi.gpu.Shader) !void {
+ if (s.code.len < 20 or s.code.len % 4 != 0 or std.mem.readInt(u32, s.code[0..4], .little) != 0x07230203 or s.uniform_buffers > 1 or s.storage_buffers != 0) return error.BadShader;
+}
+
+pub fn validatePostProcess(p: abi.gpu.PostProcess) !void {
+ try shader(p.vertex);
+ try shader(p.fragment);
+ if (p.vertex.uniform_buffers != 0 or p.fragment_uniforms.len > 16384 or
+ (p.fragment_uniforms.len > 0) != (p.fragment.uniform_buffers == 1)) return error.BadScene;
+}
+
+pub fn validate(p: abi.gpu.Pass) !void {
+ if (p.image != .none or p.width == 0 or p.height == 0 or p.width > 4096 or p.height > 4096 or p.pipelines.len > 64 or p.draws.len > 4096 or (p.samples != 1 and p.samples != 2 and p.samples != 4 and p.samples != 8)) return error.BadScene;
+ // Self-contained frames must not depend on an earlier view's contents.
+ const clear = p.clear orelse return error.BadScene;
+ for (clear) |v| if (!std.math.isFinite(v)) return error.BadScene;
+ for (p.pipelines) |pipe| {
+ if ((pipe.depth_test != null or pipe.depth_write) and !p.depth) return error.BadScene;
+ try shader(pipe.vertex);
+ try shader(pipe.fragment);
+ if (pipe.attributes.len > 16 or pipe.stride > 4096) return error.BadScene;
+ var locations: u32 = 0;
+ for (pipe.attributes) |attr| {
+ const size: u32 = switch (attr.format) {
+ .float, .ubyte4_norm => 4,
+ .float2 => 8,
+ .float3 => 12,
+ .float4 => 16,
+ };
+ if (attr.location >= 16 or attr.offset > pipe.stride or size > pipe.stride - attr.offset) return error.BadScene;
+ const bit = @as(u32, 1) << @intCast(attr.location);
+ if (locations & bit != 0) return error.BadScene;
+ locations |= bit;
+ }
+ }
+ var total: usize = 0;
+ for (p.draws) |d| {
+ if (d.pipeline >= p.pipelines.len or d.vertex_count > 1 << 20 or d.vertex_storage.len != 0 or d.fragment_storage.len != 0) return error.BadScene;
+ const pipe = p.pipelines[d.pipeline];
+ if (pipe.attributes.len != 0 and @as(u64, pipe.stride) * d.vertex_count > d.vertices.len) return error.BadScene;
+ if (d.vertex_uniforms.len > 16384 or d.fragment_uniforms.len > 16384 or (d.vertex_uniforms.len > 0) != (pipe.vertex.uniform_buffers == 1) or (d.fragment_uniforms.len > 0) != (pipe.fragment.uniform_buffers == 1)) return error.BadScene;
+ total += d.vertices.len;
+ if (total > max_bytes) return error.SceneTooLarge;
+ if (d.scissor) |r| inline for (.{ r.x, r.y, r.w, r.h }) |v| if (!std.math.isFinite(v) or v < 0 or v > 4096) return error.BadScene;
+ }
+}
+
+test "GPU scene roundtrip, truncated and oversized inputs are refused" {
+ const shader_bytes = std.mem.asBytes(&[_]u32{ 0x07230203, 0, 0, 0, 0 });
+ const pipelines = [_]abi.gpu.Pipeline{.{ .vertex = .{ .code = shader_bytes }, .fragment = .{ .code = shader_bytes }, .stride = 0, .attributes = &.{} }};
+ const pass: abi.gpu.Pass = .{ .image = .none, .width = 32, .height = 24, .pipelines = &pipelines, .draws = &.{.{ .pipeline = 0, .vertex_count = 3 }} };
+ var out: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer out.deinit();
+ try encode(&out.writer, pass);
+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
+ defer arena.deinit();
+ const decoded = try decode(arena.allocator(), out.written());
+ try std.testing.expectEqual(32, decoded.width);
+ try std.testing.expectEqual(3, decoded.draws[0].vertex_count);
+ for (0..out.written().len) |i| {
+ _ = decode(arena.allocator(), out.written()[0..i]) catch continue;
+ return error.AcceptedTruncatedScene;
+ }
+ var bad = pass;
+ bad.width = 4097;
+ try std.testing.expectError(error.BadScene, validate(bad));
+ var draw = pass.draws[0];
+ draw.pipeline = 1;
+ bad = pass;
+ bad.draws = &.{draw};
+ try std.testing.expectError(error.BadScene, validate(bad));
+}
+
+test "GPU postprocess keeps v1 readable and validates the complete second pass" {
+ const code = std.mem.asBytes(&[_]u32{ 0x07230203, 0, 0, 0, 0 });
+ const pipelines = [_]abi.gpu.Pipeline{.{ .vertex = .{ .code = code }, .fragment = .{ .code = code }, .stride = 0, .attributes = &.{} }};
+ const pass: abi.gpu.Pass = .{ .image = .none, .width = 32, .height = 24, .pipelines = &pipelines, .draws = &.{.{ .pipeline = 0, .vertex_count = 3 }} };
+ const post: abi.gpu.PostProcess = .{ .vertex = .{ .code = code }, .fragment = .{ .code = code } };
+ var out: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer out.deinit();
+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
+ defer arena.deinit();
+ try encode(&out.writer, pass);
+ try std.testing.expect((try decodeFrame(arena.allocator(), out.written())).post == null);
+ out.clearRetainingCapacity();
+ try encodePostProcess(&out.writer, pass, post);
+ const frame = try decodeFrame(arena.allocator(), out.written());
+ try std.testing.expectEqual(32, frame.pass.width);
+ try std.testing.expectEqualSlices(u8, code, frame.post.?.fragment.code);
+ for (0..out.written().len) |i| {
+ _ = decodeFrame(arena.allocator(), out.written()[0..i]) catch continue;
+ return error.AcceptedTruncatedScene;
+ }
+ var bad = post;
+ bad.vertex.uniform_buffers = 1;
+ try std.testing.expectError(error.BadScene, validatePostProcess(bad));
+ bad = post;
+ bad.fragment.uniform_buffers = 1;
+ try std.testing.expectError(error.BadScene, validatePostProcess(bad));
+ bad = post;
+ bad.fragment.storage_buffers = 1;
+ try std.testing.expectError(error.BadShader, validatePostProcess(bad));
+ out.written()[4] = 4;
+ try std.testing.expectError(error.BadScene, decodeFrame(arena.allocator(), out.written()));
+}
+
+test "depth uses v3 and requires an attachment; legacy frames keep depth disabled" {
+ const code = std.mem.asBytes(&[_]u32{ 0x07230203, 0, 0, 0, 0 });
+ var pipelines = [_]abi.gpu.Pipeline{.{ .vertex = .{ .code = code }, .fragment = .{ .code = code }, .stride = 0, .attributes = &.{}, .depth_test = .less, .depth_write = true }};
+ var pass: abi.gpu.Pass = .{ .image = .none, .width = 32, .height = 24, .pipelines = &pipelines, .draws = &.{.{ .pipeline = 0, .vertex_count = 3 }} };
+ try std.testing.expectError(error.BadScene, validate(pass));
+ pass.depth = true;
+ var out: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer out.deinit();
+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
+ defer arena.deinit();
+ try encode(&out.writer, pass);
+ try std.testing.expectEqual(3, out.written()[4]);
+ const decoded = try decode(arena.allocator(), out.written());
+ try std.testing.expect(decoded.depth);
+ try std.testing.expectEqual(abi.gpu.Compare.less, decoded.pipelines[0].depth_test.?);
+ try std.testing.expect(decoded.pipelines[0].depth_write);
+ const post: abi.gpu.PostProcess = .{ .vertex = .{ .code = code }, .fragment = .{ .code = code } };
+ out.clearRetainingCapacity();
+ try encodePostProcess(&out.writer, pass, post);
+ const frame = try decodeFrame(arena.allocator(), out.written());
+ try std.testing.expect(frame.post != null and frame.pass.depth);
+ pass.depth = false;
+ pipelines[0].depth_test = null;
+ pipelines[0].depth_write = false;
+ out.clearRetainingCapacity();
+ try encode(&out.writer, pass);
+ try std.testing.expectEqual(1, out.written()[4]);
+ const legacy = try decode(arena.allocator(), out.written());
+ try std.testing.expect(!legacy.depth and legacy.pipelines[0].depth_test == null and !legacy.pipelines[0].depth_write);
+}