tiny.gpu.BackendHandle

1pub const BackendHandle = struct {2    ptr: *anyopaque,3    vtable: *const BackendVTable,4    kind: ?BackendKind = null,56    pub fn backendKind(self: BackendHandle) ?BackendKind {7        return self.kind;8    }910    pub fn queryCapabilities(self: BackendHandle) BackendError!BackendCapabilities {11        return self.vtable.query_capabilities(self.ptr);12    }1314    pub fn createArtifact(self: BackendHandle, request: CompileRequest) BackendError!KernelArtifact {15        const caps = try self.queryCapabilities();16        try caps.validateCompileRequest(request);1718        const create = self.vtable.create_artifact orelse return error.UnsupportedOperation;19        var artifact = try create(self.ptr, request);20        artifact.interface = .{21            .features = request.required_features,22            .subgroup = request.required_subgroup,23            .push_constants = request.push_constants,24        };25        return artifact;26    }2728    pub fn loadArtifact(self: BackendHandle, artifact: *const KernelArtifact) BackendError!LoadedArtifact {29        try self.expectArtifactBackend(artifact);30        if (!artifact.interface.push_constants.valid()) return error.InvalidArtifact;31        const caps = try self.queryCapabilities();32        if (!caps.supportsFeatures(artifact.interface.features)) return error.CapabilityMismatch;33        if (!caps.supportsSubgroup(artifact.interface.subgroup)) return error.CapabilityMismatch;34        const load = self.vtable.load_artifact orelse return error.UnsupportedOperation;35        return load(self.ptr, artifact);36    }3738    pub fn createRenderArtifact(self: BackendHandle, desc: RenderPipelineDesc) BackendError!RenderArtifact {39        const caps = try self.queryCapabilities();40        try caps.validateRenderPipelineDesc(desc);4142        const create = self.vtable.create_render_artifact orelse return error.UnsupportedOperation;43        var artifact = try create(self.ptr, desc);44        errdefer artifact.deinit();45        try self.expectRenderArtifactBackend(&artifact);46        if (artifact.format != desc.format) return error.InvalidRenderArtifact;47        if (artifact.target_format != desc.target_format) return error.InvalidRenderArtifact;48        if (artifact.blend_mode != desc.blend_mode) return error.InvalidRenderArtifact;49        if (artifact.topology != desc.topology) return error.InvalidRenderArtifact;50        return artifact;51    }5253    pub fn loadRenderArtifact(self: BackendHandle, artifact: *const RenderArtifact) BackendError!LoadedRenderArtifact {54        try self.expectRenderArtifactBackend(artifact);55        if (artifact.push_extent > artifact.push_constant_bytes) return error.PushConstantRangeExceeded;56        const load = self.vtable.load_render_artifact orelse return error.UnsupportedOperation;57        const loaded = try load(self.ptr, artifact);58        try self.expectLoadedRenderArtifactBackend(loaded);59        const expected = LoadedRenderArtifact.describing(artifact, loaded.id);60        if (!std.meta.eql(loaded, expected)) return error.InvalidRenderArtifact;61        return loaded;62    }6364    pub fn createRenderBindings(self: BackendHandle, request: RenderBindingsRequest) BackendError!RenderBindings {65        try self.expectRenderArtifactBackend(request.artifact);66        try self.expectLoadedRenderArtifactBackend(request.pipeline);67        for (request.resources) |resource| switch (resource) {68            .uniform_buffer, .storage_buffer => |buffer| try self.expectBufferBackend(buffer),69            .sampled_texture => |sampled| try self.expectTextureBackend(sampled.texture),70            .storage_texture => |texture| try self.expectTextureBackend(texture),71        };72        const caps = try self.queryCapabilities();73        try caps.validateRenderBindings(request);74        const create = self.vtable.create_render_bindings orelse return error.UnsupportedOperation;75        const bindings = try create(self.ptr, request);76        if (self.kind) |kind| {77            if (bindings.backend != kind) return error.CapabilityMismatch;78        }79        if (bindings.pipeline != request.pipeline.id) return error.InvalidRenderArtifact;80        return bindings;81    }8283    pub fn allocateBuffer(self: BackendHandle, request: BufferAllocation) BackendError!BufferHandle {84        const caps = try self.queryCapabilities();85        try caps.validateBufferAllocation(request);86        const allocate = self.vtable.allocate_buffer orelse return error.UnsupportedOperation;87        const handle = try allocate(self.ptr, request);88        try self.expectBufferBackend(handle);89        if (handle.byte_size < request.byte_size) return error.InvalidBuffer;90        return handle;91    }9293    /// A caller uses this to hand its own memory to a backend as a buffer without copying it. The94    /// call binds the caller's bytes and returns a buffer whose ownership is `borrowed_external`95    /// and whose size equals the length of the caller's bytes. The call first checks the size,96    /// element type and alignment against the backend's limits, and returns `error.InvalidBuffer`97    /// when the pointer lacks the requested alignment. A backend that does not offer imports98    /// returns `error.UnsupportedOperation`, and at present only the CPU backend offers them.99    pub fn importBuffer(self: BackendHandle, request: BufferImport) BackendError!BufferHandle {100        const caps = try self.queryCapabilities();101        try caps.validateBufferAllocation(.{102            .byte_size = request.bytes.len,103            .alignment = request.alignment,104            .dtype = request.dtype,105            .element_count = request.element_count,106        });107        std.debug.assert(std.math.isPowerOfTwo(request.alignment));108        if (!std.mem.isAligned(@intFromPtr(request.bytes.ptr), request.alignment)) {109            return error.InvalidBuffer;110        }111        const import_fn = self.vtable.import_buffer orelse return error.UnsupportedOperation;112        const handle = try import_fn(self.ptr, request);113        try self.expectBufferBackend(handle);114        if (handle.ownership != .borrowed_external) return error.InvalidBuffer;115        if (handle.byte_size != request.bytes.len) return error.InvalidBuffer;116        return handle;117    }118119    pub fn allocateTexture(self: BackendHandle, request: TextureAllocation) BackendError!TextureHandle {120        const caps = try self.queryCapabilities();121        try caps.validateTextureAllocation(request);122        const allocate = self.vtable.allocate_texture orelse return error.UnsupportedOperation;123        const handle = try allocate(self.ptr, request);124        try self.expectTextureBackend(handle);125        if (!sameTextureExtent(handle.extent, request.extent)) return error.InvalidTexture;126        if (handle.format != request.format) return error.InvalidTexture;127        if (!handle.usage.containsAll(request.usage)) return error.InvalidTexture;128        if (handle.sample_count != request.sample_count) return error.InvalidTexture;129        return handle;130    }131132    pub fn createSurface(self: BackendHandle, request: SurfaceCreationRequest) BackendError!SurfaceHandle {133        const caps = try self.queryCapabilities();134        try caps.validateSurfaceCreation(request);135        const create = self.vtable.create_surface orelse return error.UnsupportedOperation;136        const handle = try create(self.ptr, request);137        try self.expectSurfaceBackend(handle);138        if (handle.platform != request.platform.kind()) return error.InvalidSurface;139        if (!caps.surfaces.supportsExtent(handle.extent)) return error.InvalidSurface;140        if (handle.format != request.format) return error.InvalidSurface;141        if (handle.color_space != request.color_space) return error.InvalidSurface;142        if (handle.present_mode != request.present_mode) return error.InvalidSurface;143        return handle;144    }145146    pub fn destroySurface(self: BackendHandle, surface: SurfaceHandle) BackendError!void {147        try self.expectSurfaceBackend(surface);148        const destroy = self.vtable.destroy_surface orelse return error.UnsupportedOperation;149        return destroy(self.ptr, surface);150    }151152    pub fn destroyTexture(self: BackendHandle, texture: TextureHandle) BackendError!void {153        try self.expectTextureBackend(texture);154        const destroy = self.vtable.destroy_texture orelse return error.UnsupportedOperation;155        return destroy(self.ptr, texture);156    }157158    pub fn acquireSurfaceFrame(self: BackendHandle, request: SurfaceFrameAcquireRequest) BackendError!SurfaceFrame {159        try self.expectSurfaceBackend(request.surface);160        const acquire = self.vtable.acquire_surface_frame orelse return error.UnsupportedOperation;161        const frame = try acquire(self.ptr, request);162        try self.expectSurfaceFrameBackend(frame);163        try expectFrameMatchesSurface(frame, request.surface);164        return frame;165    }166167    pub fn presentSurfaceFrame(self: BackendHandle, request: PresentRequest) BackendError!void {168        try self.expectSurfaceBackend(request.surface);169        try self.expectSurfaceFrameBackend(request.frame);170        try expectFrameMatchesSurface(request.frame, request.surface);171        for (request.wait_events) |event| try self.expectEventBackend(event);172        if (request.signal_event) |event| try self.expectEventBackend(event);173        const present = self.vtable.present_surface_frame orelse return error.UnsupportedOperation;174        return present(self.ptr, request);175    }176177    pub fn writeSurfaceFrame(self: BackendHandle, request: SurfaceFrameWriteRequest) BackendError!void {178        try self.expectSurfaceBackend(request.surface);179        try self.expectSurfaceFrameBackend(request.frame);180        try expectFrameMatchesSurface(request.frame, request.surface);181        try expectSurfaceFrameWriteRequest(request);182        for (request.operations) |op| switch (op) {183            .clear => {},184            .copy_buffer => |buffer| try self.expectBufferBackend(buffer),185        };186        for (request.wait_events) |event| try self.expectEventBackend(event);187        if (request.signal_event) |event| try self.expectEventBackend(event);188        const write = self.vtable.write_surface_frame orelse return error.UnsupportedOperation;189        return write(self.ptr, request);190    }191192    pub fn createStream(self: BackendHandle, request: StreamAllocation) BackendError!StreamHandle {193        const caps = try self.queryCapabilities();194        try caps.validateRuntimeRequirements(.{ .streams = true });195        const create = self.vtable.create_stream orelse return error.UnsupportedOperation;196        return create(self.ptr, request);197    }198199    pub fn createEvent(self: BackendHandle, request: EventAllocation) BackendError!EventHandle {200        const caps = try self.queryCapabilities();201        try caps.validateRuntimeRequirements(.{ .events = true });202        const create = self.vtable.create_event orelse return error.UnsupportedOperation;203        return create(self.ptr, request);204    }205206    pub fn writeBuffer(self: BackendHandle, request: BufferWriteRequest) BackendError!void {207        try self.expectBufferBackend(request.handle);208        const write = self.vtable.write_buffer orelse return error.UnsupportedOperation;209        return write(self.ptr, request);210    }211212    pub fn fillBuffer(self: BackendHandle, request: BufferFillRequest) BackendError!void {213        try self.expectBufferBackend(request.handle);214        const fill = self.vtable.fill_buffer orelse return error.UnsupportedOperation;215        return fill(self.ptr, request);216    }217218    pub fn readBuffer(self: BackendHandle, request: BufferReadRequest) BackendError!void {219        try self.expectBufferBackend(request.handle);220        if (request.bytes.len < request.handle.byte_size) return error.ReadBufferDestinationTooSmall;221        const read = self.vtable.read_buffer orelse return error.UnsupportedOperation;222        return read(self.ptr, request);223    }224225    pub fn launch(self: BackendHandle, request: LaunchRequest) BackendError!void {226        try self.expectLaunchBackends(request);227        try expectLaunchArgumentCount(request);228        const caps = try self.queryCapabilities();229        try caps.validateLaunchGeometry(request.geometry);230        try caps.validateLaunchRuntime(request);231232        const launch_fn = self.vtable.launch orelse return error.UnsupportedOperation;233        return launch_fn(self.ptr, request);234    }235236    pub fn render(self: BackendHandle, request: RenderRequest) BackendError!void {237        try self.expectRenderPassBackends(request.pass);238        try self.expectSubmitBackends(request.stream, request.wait_events, request.signal_event);239        const caps = try self.queryCapabilities();240        try caps.validateRenderPass(request.pass);241        try caps.validateSubmitRuntime(request.stream, request.wait_events, request.signal_event);242243        const render_fn = self.vtable.render orelse return error.UnsupportedOperation;244        return render_fn(self.ptr, request);245    }246247    pub fn recordRenderBundle(self: BackendHandle, pass: RenderPass) BackendError!RenderBundle {248        try self.expectRenderPassBackends(pass);249        const caps = try self.queryCapabilities();250        try caps.validateRenderPass(pass);251        const record = self.vtable.record_render_bundle orelse return error.UnsupportedOperation;252        const bundle = try record(self.ptr, pass);253        if (self.kind) |kind| {254            if (bundle.backend != kind) return error.CapabilityMismatch;255        }256        if (bundle.draw_count != pass.draws.len) return error.RenderFailed;257        return bundle;258    }259260    pub fn submitRenderBundle(self: BackendHandle, request: RenderBundleSubmit) BackendError!void {261        if (self.kind) |kind| {262            if (request.bundle.backend != kind) return error.RenderArgumentMismatch;263        }264        try self.expectSubmitBackends(request.stream, request.wait_events, request.signal_event);265        const caps = try self.queryCapabilities();266        try caps.validateSubmitRuntime(request.stream, request.wait_events, request.signal_event);267        const submit = self.vtable.submit_render_bundle orelse return error.UnsupportedOperation;268        return submit(self.ptr, request);269    }270271    pub fn writeTexture(self: BackendHandle, request: TextureWriteRequest) BackendError!void {272        try self.expectTextureBackend(request.texture);273        try BackendCapabilities.validateTextureTransfer(request.texture, request.bytes.len, .{ .copy_dst = true });274        const write = self.vtable.write_texture orelse return error.UnsupportedOperation;275        return write(self.ptr, request);276    }277278    pub fn readTexture(self: BackendHandle, request: TextureReadRequest) BackendError!void {279        try self.expectTextureBackend(request.texture);280        try BackendCapabilities.validateTextureTransfer(request.texture, request.bytes.len, .{ .copy_src = true });281        const read = self.vtable.read_texture orelse return error.UnsupportedOperation;282        return read(self.ptr, request);283    }284285    pub fn synchronize(self: BackendHandle, request: SyncRequest) BackendError!void {286        if (!request.valid()) return error.UnsupportedOperation;287        try self.expectSyncBackends(request);288        const caps = try self.queryCapabilities();289        try caps.validateSyncRuntime(request);290        const sync = self.vtable.synchronize orelse return error.UnsupportedOperation;291        return sync(self.ptr, request);292    }293294    pub fn queryEvent(self: BackendHandle, request: EventQueryRequest) BackendError!bool {295        try self.expectEventBackend(request.event);296        const caps = try self.queryCapabilities();297        try caps.validateRuntimeRequirements(.{ .events = true });298        const query = self.vtable.query_event orelse return error.UnsupportedOperation;299        return query(self.ptr, request);300    }301302    pub fn recordEvent(self: BackendHandle, request: EventRecordRequest) BackendError!void {303        try self.expectStreamBackend(request.stream);304        try self.expectEventBackend(request.event);305        const caps = try self.queryCapabilities();306        try caps.validateRuntimeRequirements(.{ .streams = true, .events = true });307        const record = self.vtable.record_event orelse return error.UnsupportedOperation;308        return record(self.ptr, request);309    }310311    pub fn elapsedEventNs(self: BackendHandle, request: EventElapsedRequest) BackendError!u64 {312        try self.expectEventBackend(request.start);313        try self.expectEventBackend(request.end);314        const caps = try self.queryCapabilities();315        try caps.validateRuntimeRequirements(.{ .events = true });316        const elapsed = self.vtable.elapsed_event_ns orelse return error.UnsupportedOperation;317        return elapsed(self.ptr, request);318    }319320    /// A caller uses this to release a buffer, queue, event or loaded code that this backend handle321    /// created. The call releases one object this handle created. Before the call, the caller makes322    /// sure all launches, copies, queues and events still in flight have finished using the object.323    /// The call leaves state unchanged on a backend lacking a release function.324    pub fn destroyObject(self: BackendHandle, id: BackendObjectId) void {325        if (self.vtable.destroy_object) |destroy| destroy(self.ptr, id);326    }327328    pub fn deinit(self: BackendHandle, allocator: Allocator) void {329        if (self.vtable.deinit) |deinit_fn| deinit_fn(self.ptr, allocator);330    }331332    fn expectArtifactBackend(self: BackendHandle, artifact: *const KernelArtifact) BackendError!void {333        const kind = self.kind orelse return;334        if (artifact.backend != kind) return error.CapabilityMismatch;335    }336337    fn expectLoadedArtifactBackend(self: BackendHandle, loaded: LoadedArtifact) BackendError!void {338        const kind = self.kind orelse return;339        if (loaded.backend != kind) return error.InvalidArtifact;340    }341342    fn expectRenderArtifactBackend(self: BackendHandle, artifact: *const RenderArtifact) BackendError!void {343        const kind = self.kind orelse return;344        if (artifact.backend != kind) return error.CapabilityMismatch;345    }346347    fn expectLoadedRenderArtifactBackend(self: BackendHandle, loaded: LoadedRenderArtifact) BackendError!void {348        const kind = self.kind orelse return;349        if (loaded.backend != kind) return error.InvalidRenderArtifact;350    }351352    fn expectBufferBackend(self: BackendHandle, handle: BufferHandle) BackendError!void {353        const kind = self.kind orelse return;354        if (handle.backend != kind) return error.InvalidBuffer;355    }356357    fn expectSurfaceBackend(self: BackendHandle, handle: SurfaceHandle) BackendError!void {358        const kind = self.kind orelse return;359        if (handle.backend != kind) return error.InvalidSurface;360    }361362    fn expectTextureBackend(self: BackendHandle, handle: TextureHandle) BackendError!void {363        const kind = self.kind orelse return;364        if (handle.backend != kind) return error.InvalidTexture;365    }366367    fn expectTextureViewBackend(self: BackendHandle, view: TextureView) BackendError!void {368        try self.expectTextureBackend(view.texture);369    }370371    fn expectSurfaceFrameBackend(self: BackendHandle, frame: SurfaceFrame) BackendError!void {372        const kind = self.kind orelse return;373        if (frame.backend != kind) return error.InvalidSurfaceFrame;374        try self.expectSurfaceBackend(frame.surface);375        try self.expectTextureBackend(frame.texture);376        try self.expectTextureViewBackend(frame.view);377    }378379    fn expectStreamBackend(self: BackendHandle, handle: StreamHandle) BackendError!void {380        const kind = self.kind orelse return;381        if (handle.backend != kind) return error.InvalidStream;382    }383384    fn expectEventBackend(self: BackendHandle, handle: EventHandle) BackendError!void {385        const kind = self.kind orelse return;386        if (handle.backend != kind) return error.InvalidEvent;387    }388389    fn expectLaunchBackends(self: BackendHandle, request: LaunchRequest) BackendError!void {390        try self.expectArtifactBackend(request.artifact);391        if (request.loaded_artifact) |loaded| {392            try self.expectLoadedArtifactBackend(loaded);393            if (loaded.backend != request.artifact.backend or loaded.format != request.artifact.format) {394                return error.InvalidArtifact;395            }396        }397        for (request.buffers) |binding| {398            try self.expectBufferBackend(binding.handle);399        }400        if (request.stream) |stream| try self.expectStreamBackend(stream);401        for (request.wait_events) |event| try self.expectEventBackend(event);402        if (request.signal_event) |event| try self.expectEventBackend(event);403    }404405    fn expectRenderPassBackends(self: BackendHandle, pass: RenderPass) BackendError!void {406        try self.expectTextureViewBackend(pass.color.view);407        if (pass.depth) |depth| try self.expectTextureViewBackend(depth.view);408        for (pass.draws) |draw| {409            try self.expectLoadedRenderArtifactBackend(draw.pipeline);410            if (draw.bindings) |bindings| {411                if (self.kind) |kind| {412                    if (bindings.backend != kind) return error.RenderArgumentMismatch;413                }414            }415            for (draw.vertex_buffers) |range| try self.expectBufferBackend(range.buffer);416            if (draw.index_buffer) |range| try self.expectBufferBackend(range.buffer);417        }418    }419420    fn expectSubmitBackends(421        self: BackendHandle,422        stream: ?StreamHandle,423        wait_events: []const EventHandle,424        signal_event: ?EventHandle,425    ) BackendError!void {426        if (stream) |handle| try self.expectStreamBackend(handle);427        for (wait_events) |event| try self.expectEventBackend(event);428        if (signal_event) |event| try self.expectEventBackend(event);429    }430431    fn expectLaunchArgumentCount(request: LaunchRequest) BackendError!void {432        const actual = request.buffers.len + request.scalar_arguments.len;433        const expected: usize = @intCast(request.artifact.argument_count);434        if (actual != expected) return error.LaunchArgumentMismatch;435    }436437    fn expectSyncBackends(self: BackendHandle, request: SyncRequest) BackendError!void {438        switch (request.scope) {439            .default_stream, .device => {},440            .stream => if (request.stream) |stream| try self.expectStreamBackend(stream),441            .event => if (request.event) |event| try self.expectEventBackend(event),442        }443    }444};

1pub const BackendHandle = contract.BackendHandle;