@derschmale/tiny-helix 0.1.0

package/dist/Pipeline.d.ts

@@ -0,0 +1,47 @@
+import { WebGPUContext } from './WebGPUContext';
+/**
+ * Options for creating a render pipeline
+ */
+export interface PipelineOptions {
+    /** Vertex shader WGSL code */
+    vertexShader: string;
+    /** Fragment shader WGSL code */
+    fragmentShader: string;
+    /** Vertex buffer layouts */
+    vertexBufferLayouts?: GPUVertexBufferLayout[];
+    /** Primitive topology (default: 'triangle-list') */
+    topology?: GPUPrimitiveTopology;
+    /** Bind group layouts for the pipeline */
+    bindGroupLayouts?: GPUBindGroupLayout[];
+}
+/**
+ * Wrapper for WebGPU render pipeline creation and management
+ */
+export declare class Pipeline {
+    private _context;
+    private _pipeline;
+    private _layout;
+    /**
+     * Creates a new Pipeline instance
+     * @param context - The WebGPU context to use
+     */
+    constructor(context: WebGPUContext);
+    /**
+     * Gets the underlying WebGPU render pipeline
+     */
+    get pipeline(): GPURenderPipeline | null;
+    /**
+     * Gets the pipeline layout
+     */
+    get layout(): GPUPipelineLayout | null;
+    /**
+     * Creates the render pipeline
+     * @param options - Pipeline configuration options
+     * @throws Error if device is not initialized
+     */
+    create(options: PipelineOptions): void;
+    /**
+     * Destroys the pipeline and releases resources
+     */
+    destroy(): void;
+}

package/dist/RenderPass.d.ts

@@ -0,0 +1,101 @@
+/// <reference types="@webgpu/types" />
+import { RenderTarget } from "./RenderTarget";
+import { RenderPipeline } from "./RenderPipeline";
+import { Mesh } from "./Mesh";
+import { BindGroup } from "./BindGroup";
+import { IndexedCollection } from "./utils/IndexedCollection";
+/**
+ * Lightweight wrapper around GPURenderPassEncoder. Provides a minimal API
+ * for ending the pass; higher-level helpers may be added later.
+ */
+export declare class RenderPass {
+    private readonly _inner;
+    private _renderPipeline?;
+    private _numVertices;
+    private _numIndices;
+    /**
+     * Internal accessor for the underlying GPURenderPassEncoder. Not intended for public use.
+     * @internal
+     */
+    constructor(inner: GPURenderPassEncoder);
+    /**
+     * Set the render pipeline to use for the next draw calls.
+     * @param pipeline
+     */
+    setPipeline(pipeline: RenderPipeline): this;
+    /**
+     * Sets the mesh to use for the next draw calls.
+     * @param mesh
+     */
+    setMesh(mesh: Mesh): this;
+    /**
+     * Set a bind group at the given index.
+     * @param index - bind group index in the render pipeline layout
+     * @param bindGroup - a `BindGroup` instance
+     */
+    setBindGroup(index: number, bindGroup: BindGroup): this;
+    /**
+     * Issue a draw call using the currently set pipeline and mesh.
+     */
+    draw(): this;
+    /**
+     * End the render pass. After calling end(), the underlying encoder may
+     * continue recording other passes or be finished/submitted.
+     */
+    end(): void;
+}
+/**
+ * Fluent builder for configuring and creating a render pass.
+ *
+ * Use the builder to specify color targets, clear values and labels before
+ * calling `build()` to obtain a `RenderPass` instance.
+ */
+export declare class RenderPassBuilder {
+    private _encoder;
+    private _label?;
+    private _colorTargets;
+    private _clearColors;
+    private _defaultTarget;
+    private _defaultDepthTarget?;
+    private _depthTarget?;
+    private _clearDepth?;
+    private _clearStencil?;
+    private _globalBindGroups;
+    /**
+     * Create a new builder instance. This should only be called from the CommandEncoder
+     * instance (see {@link CommandEncoder.createRenderPass}).
+     * @internal
+     */
+    constructor(commandEncoder: GPUCommandEncoder, globalBindGroups: BindGroup[], defaultTarget: RenderTarget, defaultDepthTarget?: RenderTarget);
+    /**
+     * Assign a human-readable label for the render pass (useful for GPU debuggers).
+     */
+    withLabel(label: string): this;
+    /**
+     * Add a color target to render into. If no targets are added the default
+     * backbuffer target will be used.
+     */
+    withColorTarget(target: RenderTarget): this;
+    withDepthStencilTarget(target: RenderTarget): this;
+    /**
+     * Set the clear color for the most recently added color target.
+     * Overloads allow passing an array or individual color components.
+     */
+    withClearColor(): this;
+    withClearColor(r: number[] | IndexedCollection): this;
+    withClearColor(r: number, g: number, b: number): this;
+    withClearColor(r: number, g: number, b: number, a: number): this;
+    /**
+     * Set the clear stencil value
+     */
+    withClearStencil(stencil: number): this;
+    /**
+     * Set the clear depth value
+     */
+    withClearDepth(depth: number): this;
+    /**
+     * Build and begin the render pass. Returns a `RenderPass` wrapper around
+     * the low-level GPURenderPassEncoder.
+     */
+    build(): RenderPass;
+}

package/dist/RenderPipeline.d.ts

@@ -0,0 +1,77 @@
+/// <reference types="@webgpu/types" />
+import { Shader } from "./Shader";
+import { WebGPUContext } from "./WebGPUContext";
+import { Mesh } from "./Mesh";
+import { CompareFunction, CullMode, TextureFormat } from "./enums";
+import { BlendMode } from "./BlendMode";
+/**
+ * Thin wrapper around GPURenderPipeline exposing a small helper for attribute
+ * location lookup. The underlying pipeline and shader are available for advanced use.
+ */
+export declare class RenderPipeline {
+    /** @internal */
+    readonly _inner: GPURenderPipeline;
+    private _shader;
+    constructor(inner: GPURenderPipeline, shader: Shader);
+    /**
+     * Helper to get the shader-declared attribute location for a named attribute.
+     */
+    getVertexAttributeLocation(name: string): number | undefined;
+}
+/**
+ * Fluent builder for creating a GPURenderPipeline. Attach a `Shader` and
+ * optionally a `Mesh` (to derive vertex buffer layouts) before calling `build()`.
+ */
+export declare class RenderPipelineBuilder {
+    private _ctx;
+    private _shader?;
+    private _colorTargets;
+    private _defaultColorState;
+    private _depthState?;
+    private _defaultDepthState?;
+    private _vertexEntry;
+    private _fragmentEntry;
+    private _label;
+    private _overrideConstants;
+    private _cullMode;
+    private _mesh;
+    constructor(ctx: WebGPUContext, defaultDepthFormat?: TextureFormat);
+    /** Assign a human-readable label for the pipeline (useful in graphics debuggers). */
+    withLabel(label: string): this;
+    /** Set face-culling mode. Default is `Back`. */
+    withCullMode(value: CullMode): this;
+    /** Provide a Mesh to automatically derive vertex buffer layouts. */
+    withMesh(mesh: Mesh): this;
+    /** Attach a compiled Shader to the pipeline. */
+    withShader(shader: Shader): this;
+    /** Select the shader entry point for the vertex stage. */
+    withVertexShader(entry: string): this;
+    /** Select the shader entry point for the fragment stage. */
+    withFragmentShader(entry: string): this;
+    /** Add a color target with the given texture format. */
+    withColorTarget(format: TextureFormat): this;
+    /**
+     * Add a depth target with the given texture format.
+     */
+    withDepthTarget(format: TextureFormat): this;
+    /**
+     * Set the depth compare function. Default is `less`.
+     * @param compare
+     */
+    withDepthCompare(compare: CompareFunction): this;
+    /**
+     * Enable or disable depth writes. Default is `true`.
+     * @param enabled
+     */
+    withDepthWrite(enabled: boolean): this;
+    /** Override a shader constant for specialization. */
+    withOverrideConstant(id: string, value: number): this;
+    /** Set the blend mode for the last assigned (or default) color target. */
+    withBlendMode(blendMode: BlendMode): this;
+    /**
+     * Build and create the `RenderPipeline`. Throws if required pieces (shader/vertices)
+     * are missing.
+     */
+    build(): RenderPipeline;
+    private get lastColorTarget();
+}

package/dist/RenderTarget.d.ts

@@ -0,0 +1,44 @@
+/// <reference types="@webgpu/types" />
+import { Texture } from "./Texture";
+import { TextureFormat } from "./enums";
+/**
+ * Lightweight wrapper around a GPUTextureView representing a render target.
+ * Use `view()` to get the underlying GPUTextureView when building render passes.
+ */
+export declare class RenderTarget {
+    readonly _inner: GPUTextureView;
+    private _format;
+    constructor(view: GPUTextureView, format: TextureFormat);
+    get format(): TextureFormat;
+}
+/**
+ * Builder for creating a `RenderTarget` from a `Texture`.
+ *
+ * The builder produces a GPUTextureView configured with a sensible default
+ * descriptor and wraps it in a `RenderTarget` helper.
+ */
+export declare class RenderTargetBuilder {
+    private _texture;
+    private _baseMipLevel;
+    private _baseArrayLayer;
+    /**
+     * Create a new RenderTargetBuilder for the given texture. This should only be called
+     * from the TinyHelix instance (see {@link TinyHelix.createRenderTarget}).
+     * @param texture
+     *
+     * @internal
+     */
+    constructor(texture: Texture);
+    /**
+     * Set the base mip level to use for the render target. Defaults to 0.
+     */
+    withMipLevel(level: number): this;
+    /**
+     * Set the base array layer to use for the render target. Defaults to 0.
+     */
+    withArrayLayer(layer: number): this;
+    /**
+     * Create and return a new `RenderTarget` instance.
+     */
+    build(): RenderTarget;
+}

package/dist/Renderer.d.ts

@@ -0,0 +1,44 @@
+import { WebGPUContext } from './WebGPUContext';
+/**
+ * Basic WebGPU renderer for managing render passes
+ */
+export declare class Renderer {
+    private _context;
+    private _clearColor;
+    /**
+     * Creates a new Renderer instance
+     * @param context - The WebGPU context to render with
+     */
+    constructor(context: WebGPUContext);
+    /**
+     * Gets the WebGPU context
+     */
+    get context(): WebGPUContext;
+    /**
+     * Gets or sets the clear color
+     */
+    get clearColor(): GPUColor;
+    set clearColor(color: GPUColor);
+    /**
+     * Begins a new render frame and returns a command encoder
+     * @returns The command encoder for this frame
+     * @throws Error if device or context is not available
+     */
+    beginFrame(): GPUCommandEncoder;
+    /**
+     * Creates a render pass for the current frame
+     * @param commandEncoder - The command encoder to use
+     * @returns The render pass encoder
+     * @throws Error if context is not configured
+     */
+    beginRenderPass(commandEncoder: GPUCommandEncoder): GPURenderPassEncoder;
+    /**
+     * Ends the current frame and submits commands
+     * @param commandEncoder - The command encoder to submit
+     */
+    endFrame(commandEncoder: GPUCommandEncoder): void;
+    /**
+     * Clears the canvas with the current clear color
+     */
+    clear(): void;
+}

package/dist/Sampler.d.ts

@@ -0,0 +1,31 @@
+/// <reference types="@webgpu/types" />
+import { WebGPUContext } from "./WebGPUContext";
+import { AddressMode, FilterMode } from "./enums";
+export declare class Sampler {
+    readonly _inner: GPUSampler;
+    private static DEFAULT_TRILINEAR;
+    constructor(inner: GPUSampler);
+}
+export declare class SamplerBuilder {
+    private _ctx;
+    private _addressModeU?;
+    private _addressModeV?;
+    private _addressModeW?;
+    private _minFilter?;
+    private _magFilter?;
+    private _mipmapFilter?;
+    private _minMipLevel?;
+    private _maxMipLevel?;
+    private _maxAnisotropy?;
+    private _compare?;
+    constructor(ctx: WebGPUContext);
+    withAddressMode(u: AddressMode, v?: AddressMode, w?: AddressMode): this;
+    withFiltering(minFilter: FilterMode, magFilter?: FilterMode, mipmapFilter?: FilterMode): this;
+    withTrilinearFiltering(): this;
+    withNearestFiltering(): this;
+    withAnisotropicFiltering(maxAnisotropy: number): this;
+    withMinMipLevel(level: number): this;
+    withMaxMipLevel(level: number): this;
+    withCompareFunction(compare: GPUCompareFunction): this;
+    build(): Sampler;
+}

package/dist/Shader.d.ts

@@ -0,0 +1,77 @@
+/// <reference types="@webgpu/types" />
+import { WebGPUContext } from "./WebGPUContext";
+import BindGroupLayoutBuilder, { BindGroupBuilder, BindGroupLayout } from "./BindGroup";
+type AttributeMap = Map<string, number>;
+/**
+ * Wrapper around GPUShaderModule. Keeps a map of vertex attribute names to
+ * shader locations to aid pipeline construction.
+ */
+export declare class Shader {
+    /** @internal */
+    readonly _inner: GPUShaderModule;
+    /** @internal */
+    readonly _bindGroupLayouts: BindGroupLayout[] | undefined;
+    private _vertexAttributes;
+    private _ctx;
+    /**
+     * @internal
+     */
+    constructor(inner: GPUShaderModule, ctx: WebGPUContext, vertexAttributes: AttributeMap, bindGroupLayouts?: BindGroupLayout[]);
+    /**
+     * Get the shader location for a named vertex attribute. Returns undefined if the attribute
+     * is not declared by the shader.
+     */
+    getVertexAttributeLocation(name: string): number | undefined;
+    /**
+     * Returns true if the shader declares a vertex attribute with the given name.
+     * @param name
+     */
+    hasVertexAttribute(name: string): boolean;
+    /**
+     * Create a BindGroupBuilder for the shader's bind group at the given index.
+     * @param group - index of the bind group declared by the shader
+     */
+    createBindGroup(group: number): BindGroupBuilder;
+}
+/**
+ * Builder for creating shader modules and declaring attribute locations used by the helper
+ * pipeline builder.
+ */
+export declare class ShaderBuilder {
+    private _code?;
+    private _label?;
+    private _ctx;
+    private _vertexAttributes;
+    private _bindGroupLayouts;
+    private _includes;
+    /**
+     * @internal
+     */
+    constructor(ctx: WebGPUContext);
+    /** Optional label for the underlying GPUShaderModule. */
+    withLabel(label: string): this;
+    /** Set WGSL or other shader code to compile into a GPUShaderModule. */
+    withCode(code: string): this;
+    /**
+     * Add a named include to the shader code. The include will be expanded
+     * in the shader code before compilation. The include name must be unique
+     * within the shader code. This allows using `#include<name>` in the shader
+     * code to include other files. While this is not standard WGSL, it's too
+     * useful not to support.
+     *
+     * @param name - The name as used in the `#include<name>` directive.
+     * @param code - The code the include should expand to.
+     */
+    withInclude(name: string, code: string): this;
+    /** Declare a named vertex attribute and the location it maps to in the shader. */
+    withVertexAttribute(name: string, location: number): this;
+    /**
+     * Declare a bind group layout used by this shader. The provided builder
+     * callback is used to construct the layout description.
+     */
+    withBindGroup(index: number, layout: BindGroupLayout): this;
+    withBindGroup(index: number, buildFunc: (builder: BindGroupLayoutBuilder) => void): this;
+    /** Compile the shader module and return a `Shader` instance. */
+    build(): Shader;
+}
+export {};

package/dist/Texture.d.ts

@@ -0,0 +1,55 @@
+/// <reference types="@webgpu/types" />
+import { WebGPUContext } from "./WebGPUContext";
+import { TextureFormat } from "./enums";
+import { IBuffer } from "./buffers/IBuffer";
+import { TextureUsage } from "./buffers/Buffer";
+/**
+ * Small wrapper around GPUTexture providing convenience constructors and
+ * an internal accessor for low-level interop.
+ */
+export declare class Texture implements IBuffer {
+    /** @internal */
+    readonly _inner: GPUTexture;
+    private _format;
+    /**
+     * Create a Texture wrapper from an existing GPUTexture.
+     * @param texture - The underlying GPUTexture
+     */
+    static from_webgpu(texture: GPUTexture, format: TextureFormat): Texture;
+    constructor(inner: GPUTexture, format: TextureFormat);
+    createView(): TextureViewBuilder;
+    get format(): TextureFormat;
+    _getBufferResource(): GPUBindingResource;
+}
+export declare class TextureBuilder {
+    private _ctx;
+    private _size;
+    private _data;
+    private _format;
+    private _usage;
+    constructor(ctx: WebGPUContext);
+    withSize(width: number, height: number, depthOrArrayLayers?: number): this;
+    withData(data: GPUAllowSharedBufferSource): this;
+    withFormat(format: TextureFormat): this;
+    withImage(data: ImageBitmap): this;
+    withUsage(usage: TextureUsage): this;
+    build(): Texture;
+}
+export declare class TextureView {
+    /** @internal */
+    _inner: GPUTextureView;
+    constructor(inner: GPUTextureView);
+}
+export declare class TextureViewBuilder {
+    private _texture;
+    private _desc;
+    /**
+     * @internal
+     */
+    constructor(texture: Texture);
+    withSingleMip(level: number): this;
+    withMipRange(start: number, end: number): this;
+    withSingleLayer(layer: number): this;
+    withLayerRange(start: number, end: number): this;
+    build(): TextureView;
+}

package/dist/TinyHelix.d.ts

@@ -0,0 +1,163 @@
+import { WebGPUContextOptions } from './WebGPUContext';
+import { CommandEncoder } from "./CommandEncoder";
+import { Texture, TextureBuilder } from "./Texture";
+import { RenderTarget, RenderTargetBuilder } from "./RenderTarget";
+import { ShaderBuilder } from "./Shader";
+import { RenderPipelineBuilder } from "./RenderPipeline";
+import { MeshBuilder } from "./Mesh";
+import { UniformBuffer, UniformBufferLayout, UniformBufferLayoutBuilder } from "./buffers/UniformBuffer";
+import BindGroupLayoutBuilder, { BindGroup, BindGroupBuilder, BindGroupLayout } from "./BindGroup";
+import { SamplerBuilder } from "./Sampler";
+import { ComputePipelineBuilder } from "./ComputePipeline";
+import { ColorSpace, TextureFormat } from "./enums";
+import { BufferBuilder } from "./buffers/Buffer";
+/**
+ * Options for initializing TinyHelix
+ */
+export interface TinyHelixOptions extends WebGPUContextOptions {
+    /** Optional format to use for the depth/stencil buffer */
+    depthStencilFormat?: TextureFormat;
+}
+/**
+ * Main entry point for the tiny-helix API. Manages the WebGPU context,
+ * backbuffer and provides helpers to create render targets and command encoders.
+ */
+export declare class TinyHelix {
+    private _context;
+    private _options;
+    private _backbuffer?;
+    private _backbufferTarget?;
+    private _depthStencil?;
+    private _depthStencilTarget?;
+    private _shaderIncludes;
+    private _canvas;
+    private _globalBindBufferLayouts;
+    private _globalBindBuffers;
+    /**
+     * Create a new TinyHelix instance. Call `initialize()` before rendering.
+     */
+    constructor(canvas: HTMLCanvasElement);
+    /**
+     * Initializes the underlying WebGPU context and prepares resources.
+     * @param options - Configuration options forwarded to the WebGPU context
+     * @example await tiny.initialize({ canvas: myCanvas });
+     */
+    initialize(options?: TinyHelixOptions): Promise<void>;
+    resize(width: number, height: number): void;
+    /**
+     * Add a named include for all shader code. The include will be expanded
+     * in any shader code created through {@link TinyHelix.createShader}.
+     * The include name must be unique within the shader code. This allows
+     * using `#include<name>` in the shader code to include other files.
+     * While this is not standard WGSL, it's too useful not to support.
+     '
+     * @param name - The name as used in the `#include<name>` directive.
+     * @param source - The code the include should expand to.
+     */
+    addShaderInclude(name: string, source: string): this;
+    /**
+     * Return the chosen depth/stencil format if configured.
+     */
+    get depthStencilFormat(): TextureFormat | undefined;
+    /**
+     * The current frame's backbuffer texture. Valid after `startFrame()` has been
+     * called.
+     * @throws Error if accessed before startFrame()
+     */
+    get backbuffer(): Texture;
+    /**
+     * The RenderTarget wrapper for the current backbuffer. Valid after `startFrame()`.
+     * @throws Error if accessed before startFrame()
+     */
+    get backbufferTarget(): RenderTarget;
+    get colorSpace(): ColorSpace;
+    get backbufferFormat(): TextureFormat;
+    /**
+     * The width of the current backbuffer. Valid after `startFrame()`.
+     */
+    get backbufferWidth(): number;
+    /**
+     * The height of the current backbuffer. Valid after `startFrame()`.
+     */
+    get backbufferHeight(): number;
+    /**
+     * Needs to be called before rendering each frame. Updates internal backbuffer
+     * references to the current swapchain texture.
+     * @example tiny.startFrame();
+     */
+    startFrame(): void;
+    /**
+     * Create a RenderTargetBuilder for a given texture.
+     */
+    createRenderTarget(target: Texture): RenderTargetBuilder;
+    /**
+     * Create a ShaderBuilder for creating a Shader.
+     */
+    createShader(): ShaderBuilder;
+    /**
+     * Create a BindGroupLayoutBuilder for creating a BindGroupLayout.
+     */
+    createBindGroupLayout(): BindGroupLayoutBuilder;
+    /**
+     * Create a BindGroupBuilder for creating a BindGroup.
+     */
+    createBindGroup(layout: BindGroupLayout): BindGroupBuilder;
+    /**
+     * Create a MeshBuilder for creating a Mesh.
+     */
+    createMesh(): MeshBuilder;
+    /**
+     * Create a RenderPipelineBuilder for creating a RenderPipeline.
+     */
+    createRenderPipeline(): RenderPipelineBuilder;
+    /**
+     * Create a ComputePipelineBuilder for creating a ComputePipeline.
+     */
+    createComputePipeline(): ComputePipelineBuilder;
+    /**
+     * Create a SamplerBuilder for creating a Sampler.
+     */
+    createSampler(): SamplerBuilder;
+    /**
+     * Create a TextureBuilder for creating a Texture.
+     */
+    createTexture(): TextureBuilder;
+    /**
+     * Creates a command encoder for recording GPU commands for the current frame.
+     * @param label - Optional debug label to assign to the encoder
+     */
+    createCommandEncoder(label?: string): CommandEncoder;
+    /**
+     * Create a UniformBufferLayoutBuilder for creating a UniformBufferLayout.
+     */
+    createUniformBufferLayout(): UniformBufferLayoutBuilder;
+    /**
+     * Create a UniformBuffer for the given layout.
+     */
+    createUniformBuffer(layout: UniformBufferLayout): UniformBuffer;
+    /**
+     * Create a BufferBuilder to construct raw buffers.
+     */
+    createBuffer(): BufferBuilder;
+    /**
+     * Allows setting a global bind group for all render passes. This is useful
+     * for setting bind groups that are used by all passes. These buffers will
+     * automatically be set for all render and compute passes.
+     * @param index - The index of the bind group in the render pipeline layout.
+     * @param buffer - The bind group to set.
+     */
+    setGlobalBindGroup(index: number, layout: BindGroupLayout, buffer: BindGroup): this;
+    /**
+     * Destroy the TinyHelix instance and release all GPU resources.
+     */
+    destroy(): void;
+    /**
+     * Returns the current depth/stencil texture if configured.
+     */
+    depthStencilTexture(): Texture | undefined;
+    /**
+     * Returns the current depth/stencil RenderTarget if configured.
+     */
+    depthStencilTarget(): RenderTarget | undefined;
+    private _createDepthStencil;
+}