# `nupp.gpu.spi` Shared interfaces for resident GPU implementations. The `nupp.gpu` module selects a device implementation during initialization. `open` is a receiver-free function; it returns a closeable `KernelContext`. Implementations define private records satisfying the shared context, buffer, kernel, and binding interfaces. Reuse the exported types here rather than creating nominal substitutes. Context-bound buffers and kernels preserve their borrows, and every close keeps its non-suspending guarantee. Generated artifacts and layout facts constrain binding formats, counts, scalar uniforms, and target features. A provider may choose a compatible device, but it cannot change the representation compiled into a kernel. Device and artifact failures must be reported before incompatible operations are published or run. The facade exports the retained open function directly. ## Types ### `ArtifactSet` _record_ ```nupp record ArtifactSet ... ``` Generated shader formats and entrypoint accepted by provider compilation. #### Members | Name | Kind | Description | | --- | --- | --- | | [`spirv`](#nupp.gpu.spi.ArtifactSet.spirv) | field | Optional SPIR-V artifact bytes. | | [`wgsl`](#nupp.gpu.spi.ArtifactSet.wgsl) | field | Optional WGSL shader source. | | [`entrypoint`](#nupp.gpu.spi.ArtifactSet.entrypoint) | field | Name of the entry point within the supplied artifacts. | | [`sourceFile`](#nupp.gpu.spi.ArtifactSet.sourceFile) | field | Authored kernel identity carried into optional execution cost records. | | [`sourceLine`](#nupp.gpu.spi.ArtifactSet.sourceLine) | field | | | [`artifactId`](#nupp.gpu.spi.ArtifactSet.artifactId) | field | | | [`readonlyNames`](#nupp.gpu.spi.ArtifactSet.readonlyNames) | field | | | [`writableNames`](#nupp.gpu.spi.ArtifactSet.writableNames) | field | | #### `spirv` _field_ ```nupp spirv: string? ``` `@readonly` Optional SPIR-V artifact bytes. #### `wgsl` _field_ ```nupp wgsl: string? ``` `@readonly` Optional WGSL shader source. #### `entrypoint` _field_ ```nupp entrypoint: string ``` `@readonly` Name of the entry point within the supplied artifacts. #### `sourceFile` _field_ ```nupp sourceFile: string? ``` `@readonly` Authored kernel identity carried into optional execution cost records. #### `sourceLine` _field_ ```nupp sourceLine: integer? ``` `@readonly` #### `artifactId` _field_ ```nupp artifactId: string? ``` `@readonly` #### `readonlyNames` _field_ ```nupp readonlyNames: {string}? ``` `@readonly` #### `writableNames` _field_ ```nupp writableNames: {string}? ``` `@readonly` ### `Binding` _interface_ ```nupp interface Binding ... ``` Canonical kernel invocation with buffer slots and uniform dispatch. #### Members | Name | Kind | Description | | --- | --- | --- | | [`close`](#nupp.gpu.spi.Binding.close) | method | Releases the binding's attachments without suspending. | | [`count`](#nupp.gpu.spi.Binding.count) | field | Number of logical elements dispatched. | | [`setRead`](#nupp.gpu.spi.Binding.setRead) | method | Attaches a same-context buffer to a zero-based read slot. | | [`setWrite`](#nupp.gpu.spi.Binding.setWrite) | method | Attaches a same-context, injective buffer to a zero-based writable slot. | | [`dispatchWords`](#nupp.gpu.spi.Binding.dispatchWords) | method | Dispatches using the generated scalar uniform words. | | [`dispatchPacked`](#nupp.gpu.spi.Binding.dispatchPacked) | method | Dispatches from the exact packed uniform layout and byte count. | #### `close` _method_ ```nupp close: @nosuspend function(borrows self: Binding): nil ``` `@readonly` Releases the binding's attachments without suspending. The kernel and buffers it named remain their owners'. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Binding` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `count` _field_ ```nupp count: integer ``` `@readonly` Number of logical elements dispatched. #### `setRead` _method_ ```nupp setRead: function( borrows self: Binding, slot: integer, borrows buffer: gpu.Buffer, matchCount: boolean ): nil ``` `@readonly` Attaches a same-context buffer to a zero-based read slot. `matchCount` requires a dense buffer element per dispatched element. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Binding` | | | `slot` | `integer` | | | `borrows buffer` | `gpu.Buffer\` | | | `matchCount` | `boolean` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `setWrite` _method_ ```nupp setWrite: function( borrows self: Binding, slot: integer, borrows buffer: gpu.Buffer, matchCount: boolean ): nil ``` `@readonly` Attaches a same-context, injective buffer to a zero-based writable slot. `matchCount` also requires a dense element per dispatched element. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Binding` | | | `slot` | `integer` | | | `borrows buffer` | `gpu.Buffer\` | | | `matchCount` | `boolean` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `dispatchWords` _method_ ```nupp dispatchWords: function(borrows self: Binding, scalars: {uint32}): nil ``` `@readonly` Dispatches using the generated scalar uniform words. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Binding` | | | `scalars` | `{uint32}` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `dispatchPacked` _method_ ```nupp dispatchPacked: function(borrows self: Binding, uniforms: any, uniformBytes: integer): nil ``` `@readonly` Dispatches from the exact packed uniform layout and byte count. The provider must validate the byte count against the compiled kernel. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Binding` | | | `uniforms` | `any` | | | `uniformBytes` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `Buffer` _interface_ ```nupp interface Buffer is nupp.Closeable ... ``` Canonical typed resident buffer/view borrowing its context. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Members | Name | Kind | Description | | --- | --- | --- | | [`close`](#nupp.gpu.spi.Buffer.close) | method | Releases a root buffer's allocation, or ends a view, without suspending. | | [`count`](#nupp.gpu.spi.Buffer.count) | field | Number of logical elements in this buffer or view. | | [`dimensions`](#nupp.gpu.spi.Buffer.dimensions) | method | Returns the logical shape in elements. | | [`strides`](#nupp.gpu.spi.Buffer.strides) | method | Returns the element strides for the logical view. | | [`subview`](#nupp.gpu.spi.Buffer.subview) | method | Creates a context-borrowed view at a zero-based origin with the requested shape. | | [`layout`](#nupp.gpu.spi.Buffer.layout) | method | Returns the canonical tensor layout for this view. | | [`isDense`](#nupp.gpu.spi.Buffer.isDense) | method | Reports whether this buffer or view occupies one dense element range. | | [`isInjective`](#nupp.gpu.spi.Buffer.isInjective) | method | Reports whether every logical element maps to a distinct storage element. | | [`view`](#nupp.gpu.spi.Buffer.view) | method | Creates a view using the supplied checked layout without copying storage. | #### `close` _method_ ```nupp close: @nosuspend function(takes self: Buffer): nil ``` Releases a root buffer's allocation, or ends a view, without suspending. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `Buffer\` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `count` _field_ ```nupp count: integer ``` `@readonly` Number of logical elements in this buffer or view. #### `dimensions` _method_ ```nupp dimensions: function(borrows self: Buffer): {integer} ``` `@readonly` Returns the logical shape in elements. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Buffer\` | | ##### Returns | Type | Description | | --- | --- | | `{integer}` | | #### `strides` _method_ ```nupp strides: function(borrows self: Buffer): {integer} ``` `@readonly` Returns the element strides for the logical view. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Buffer\` | | ##### Returns | Type | Description | | --- | --- | | `{integer}` | | #### `subview` _method_ ```nupp subview: function( borrows self: Buffer, origin: {integer}, shape: {integer} ): affine(Buffer) borrows (self) ``` `@readonly` Creates a context-borrowed view at a zero-based origin with the requested shape. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Buffer\` | | | `origin` | `{integer}` | | | `shape` | `{integer}` | | ##### Returns | Type | Description | | --- | --- | | `affine(Buffer\) borrows (self)` | | #### `layout` _method_ ```nupp layout: function(borrows self: Buffer): TensorLayout ``` `@readonly` Returns the canonical tensor layout for this view. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Buffer\` | | ##### Returns | Type | Description | | --- | --- | | `TensorLayout` | | #### `isDense` _method_ ```nupp isDense: function(borrows self: Buffer): boolean ``` `@readonly` Reports whether this buffer or view occupies one dense element range. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Buffer\` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `isInjective` _method_ ```nupp isInjective: function(borrows self: Buffer): boolean ``` `@readonly` Reports whether every logical element maps to a distinct storage element. A false result also covers a stride proof that was inconclusive. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Buffer\` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `view` _method_ ```nupp view: function(borrows self: Buffer, layout: TensorLayout): affine(Buffer) borrows (self) ``` `@readonly` Creates a view using the supplied checked layout without copying storage. The layout must fit within the root allocation. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Buffer\` | | | `layout` | `TensorLayout` | | ##### Returns | Type | Description | | --- | --- | | `affine(Buffer\) borrows (self)` | | ### `Context` _interface_ ```nupp interface Context is gpu.Context ... ``` Complete shared context protocol, including generated-kernel operations. #### Members | Name | Kind | Description | | --- | --- | --- | | [`compileGenerated`](#nupp.gpu.spi.Context.compileGenerated) | method | Compiles compatible artifacts with exact read/write slot counts and uniform size. | | [`bindKernel`](#nupp.gpu.spi.Context.bindKernel) | method | Creates a binding for count elements using this context's live kernel. | #### `compileGenerated` _method_ ```nupp compileGenerated: function( borrows self: Context, artifacts: gpu.ArtifactSet, readonlyBuffers: integer, writableBuffers: integer, uniformBytes: integer, threads: integer? ): gpu.Kernel borrows (self) ``` `@readonly` Compiles compatible artifacts with exact read/write slot counts and uniform size. threads carries the generated workgroup requirement when specified. Reject unsupported layouts or device limits before returning a kernel. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Context` | | | `artifacts` | `gpu.ArtifactSet` | | | `readonlyBuffers` | `integer` | | | `writableBuffers` | `integer` | | | `uniformBytes` | `integer` | | | `threads` | `integer?` | | ##### Returns | Type | Description | | --- | --- | | `gpu.Kernel borrows (self)` | | #### `bindKernel` _method_ ```nupp bindKernel: function( borrows self: Context, borrows kernel: gpu.Kernel, count: integer ): gpu.Binding borrows (self) ``` `@readonly` Creates a binding for count elements using this context's live kernel. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Context` | | | `borrows kernel` | `gpu.Kernel` | | | `count` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `gpu.Binding borrows (self)` | | ### `Kernel` _interface_ ```nupp interface Kernel ... ``` Canonical opaque kernel handle borrowing its context. #### Members | Name | Kind | Description | | --- | --- | --- | | [`close`](#nupp.gpu.spi.Kernel.close) | method | Releases the compiled kernel without suspending. | #### `close` _method_ ```nupp close: @nosuspend function(borrows self: Kernel): nil ``` `@readonly` Releases the compiled kernel without suspending. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Kernel` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `Provider` _interface_ ```nupp interface Provider ... ``` #### Members | Name | Kind | Description | | --- | --- | --- | | [`priority`](#nupp.gpu.spi.Provider.priority) | field | | | [`available`](#nupp.gpu.spi.Provider.available) | method | Reports whether open can answer a device now, without raising. | | [`open`](#nupp.gpu.spi.Provider.open) | method | Opens an owned, closeable device context. | #### `priority` _field_ ```nupp priority: integer? ``` `@readonly` #### `available` _method_ ```nupp available: function(): boolean ``` `@readonly` Reports whether `open` can answer a device now, without raising. ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `open` _method_ ```nupp open: function(): types.KernelContext ``` `@readonly` Opens an owned, closeable device context. Raises if the host cannot provide a compatible device. ##### Returns | Type | Description | | --- | --- | | `types.KernelContext` | |