ris-framework 0.2.0-dev.11 → 0.2.0-dev.13

package/src/webgpu/shader/WebGpuShaderModuleLoader.ts

@@ -0,0 +1,38 @@
+import type {IFramework, IShaderModule, IShaderModuleLoader} from "../../api/index.ts";
+import {shaderModuleCacheKey} from "../../webgl/shader/WebGlShaderModuleLoader.ts";
+import {WebGpuShaderModule} from "./WebGpuShaderModule.ts";
+
+/**
+ * Loads and caches WGSL shader modules by id.
+ * @internal
+ */
+export class WebGpuShaderModuleLoader implements IShaderModuleLoader {
+
+    private readonly _shaderModules = new Map<string, WebGpuShaderModule>();
+
+    /**
+     * The constructor.
+     * @param _framework The framework.
+     */
+    public constructor(private readonly _framework: IFramework) {
+    }
+
+    /** @inheritDoc */
+    public load(shaderModuleId: string, keyValueDictionary?: { [id: string]: number }): IShaderModule {
+        const key = shaderModuleCacheKey(shaderModuleId, keyValueDictionary);
+        let module = this._shaderModules.get(key);
+        if (!module) {
+            module = new WebGpuShaderModule(this._framework, shaderModuleId, keyValueDictionary);
+            this._shaderModules.set(key, module);
+        }
+        return module;
+    }
+
+    /** Disposes every cached module. */
+    public dispose(): void {
+        for (const module of this._shaderModules.values()) {
+            module.dispose();
+        }
+        this._shaderModules.clear();
+    }
+}

package/src/webgpu/shader/WgslShaderContent.ts

@@ -0,0 +1,20 @@
+import mainFrameBuffer from "../../../shaders/wgsl/main_frame_buffer.wgsl?raw";
+import mainRenderTargetFlipY from "../../../shaders/wgsl/main_render_target_flip_y.wgsl?raw";
+import unlitMaterial from "../../../shaders/wgsl/unlit_material.wgsl?raw";
+import forwardBlinnPhongMaterial from "../../../shaders/wgsl/forward_blinn_phong_material.wgsl?raw";
+import sprite from "../../../shaders/wgsl/sprite.wgsl?raw";
+import inspectTextureMips from "../../../shaders/wgsl/inspect_texture_mips.wgsl?raw";
+
+/**
+ * The framework's built-in WGSL shaders, keyed by the same ids the WebGL backend uses where one exists.
+ * Every shader has `main_vs` and `main_fs` entry points.
+ * @internal
+ */
+export const WgslShaderContent: { [id: string]: string } = {
+    "main_frame_buffer": mainFrameBuffer,
+    "main_render_target_flip_y": mainRenderTargetFlipY,
+    "unlit_material": unlitMaterial,
+    "forward_blinn_phong_material": forwardBlinnPhongMaterial,
+    "sprite": sprite,
+    "inspect_texture_mips": inspectTextureMips,
+};

package/src/webgpu/swap-chain/WebGpuSwapChain.ts

@@ -0,0 +1,93 @@
+import {vec2} from "gl-matrix";
+import {type ISwapChain, SwapChainDescriptor, TextureFormat} from "../../api/index.ts";
+import type {WebGpuGraphicsDevice} from "../WebGpuGraphicsDevice.ts";
+import {GpuTextureUsage, type GpuCanvasContext, type GpuTextureView} from "../WebGpuTypes.ts";
+
+/**
+ * The WebGPU swap chain, backed by the canvas' `webgpu` context.
+ *
+ * The canvas is configured as `rgba8unorm` instead of `navigator.gpu.getPreferredCanvasFormat()` (often `bgra8unorm`),
+ * because the framework's {@link TextureFormat} has no BGRA format and the main render target uses the swap chain format.
+ * @internal
+ */
+export class WebGpuSwapChain implements ISwapChain {
+
+    private readonly _canvas: HTMLCanvasElement;
+    private readonly _graphicsDevice: WebGpuGraphicsDevice;
+    private readonly _context: GpuCanvasContext;
+    private readonly _backBufferSize: vec2;
+    private _currentView: GpuTextureView | null = null;
+
+    /**
+     * The constructor.
+     * @param canvas The canvas.
+     * @param graphicsDevice The graphics device.
+     * @param _descriptor The swap chain descriptor. WebGPU canvases always present with FIFO.
+     */
+    public constructor(canvas: HTMLCanvasElement, graphicsDevice: WebGpuGraphicsDevice, _descriptor?: SwapChainDescriptor) {
+        this._canvas = canvas;
+        this._graphicsDevice = graphicsDevice;
+        const context = canvas.getContext("webgpu" as "webgl2") as unknown as GpuCanvasContext | null;
+        if (!context) {
+            throw new Error("WebGPU canvas context is not available.");
+        }
+        this._context = context;
+        this._backBufferSize = vec2.fromValues(canvas.width, canvas.height);
+        this._configure();
+    }
+
+    private _configure(): void {
+        this._context.configure({
+            device: this._graphicsDevice.device,
+            format: "rgba8unorm",
+            usage: GpuTextureUsage.RENDER_ATTACHMENT,
+            alphaMode: this._graphicsDevice.alpha ? "premultiplied" : "opaque",
+        });
+    }
+
+    /** @inheritDoc */
+    public get textureFormat(): TextureFormat {
+        return TextureFormat.RGBA_8_UNORM;
+    }
+
+    /** @inheritDoc */
+    public get backBufferSize(): vec2 {
+        return this._backBufferSize;
+    }
+
+    /**
+     * The view of the current canvas texture. Acquired once per frame and released on {@link present}.
+     */
+    public get currentTextureView(): GpuTextureView {
+        if (!this._currentView) {
+            this._currentView = this._context.getCurrentTexture().createView();
+        }
+        return this._currentView;
+    }
+
+    /** @inheritDoc */
+    public resize(width: number, height: number): void {
+        if (width <= 0 || height <= 0) {
+            return;
+        }
+        this._currentView = null;
+        this._canvas.width = width;
+        this._canvas.height = height;
+        this._backBufferSize[0] = width;
+        this._backBufferSize[1] = height;
+    }
+
+    /** @inheritDoc */
+    public present(): void {
+        // The browser presents the canvas texture after the task; the next frame needs a fresh texture.
+        this._currentView = null;
+        this._backBufferSize[0] = this._canvas.width;
+        this._backBufferSize[1] = this._canvas.height;
+    }
+
+    /** @inheritDoc */
+    public dispose(): void {
+        this._currentView = null;
+        this._context.unconfigure();
+    }
+}

package/src/webgpu/texture/WebGpuTexture2D.ts

@@ -0,0 +1,197 @@
+import {
+    type IFramework,
+    State,
+    TextureDescriptor,
+    TextureUsage,
+    TextureUtilities,
+    type ITextureView,
+    TextureViewDescriptor,
+    TextureViewDimension,
+} from "../../api/index.ts";
+import {ATexture2D} from "../../core/rendering/texture/texture.ts";
+import type {WebGpuGraphicsDevice} from "../WebGpuGraphicsDevice.ts";
+import {GpuTextureUsage, type GpuTexture, type GpuTextureView} from "../WebGpuTypes.ts";
+import {WebGpuConverter} from "../utilities/WebGpuConverter.ts";
+import {WebGpuTextureView} from "./WebGpuTextureView.ts";
+
+/**
+ * The WebGPU 2D texture.
+ *
+ * Supports uncompressed formats with `Uint8Array` mip levels or an `HTMLImageElement`.
+ * Mipmap generation and compressed (KTX2) formats are not implemented for WebGPU yet.
+ * @internal
+ */
+export class WebGpuTexture2D extends ATexture2D {
+
+    private readonly _graphicsDevice: WebGpuGraphicsDevice;
+    private readonly _image?: HTMLImageElement;
+    private _gpuTexture: GpuTexture | null = null;
+    private _gpuDefaultView: GpuTextureView | null = null;
+
+    /**
+     * The constructor.
+     * @param framework The framework.
+     * @param descriptor The texture descriptor.
+     * @param image An optional image to upload instead of `descriptor.data`.
+     */
+    public constructor(framework: IFramework, descriptor: TextureDescriptor, image?: HTMLImageElement) {
+        super(descriptor);
+        this._graphicsDevice = framework.renderer.graphicsDevice as WebGpuGraphicsDevice;
+        this._image = image;
+    }
+
+    /** The WebGPU texture. */
+    public get gpuTexture(): GpuTexture {
+        if (!this._gpuTexture) {
+            throw new Error("WebGpuTexture2D: the texture is not initialized or is disposed.");
+        }
+        return this._gpuTexture;
+    }
+
+    /** The default WebGPU view of the whole texture. */
+    public get gpuDefaultView(): GpuTextureView {
+        if (!this._gpuDefaultView) {
+            throw new Error("WebGpuTexture2D: the texture is not initialized or is disposed.");
+        }
+        return this._gpuDefaultView;
+    }
+
+    /** @inheritDoc */
+    public initialize(): void {
+        if (this._state == State.INITIALIZED) {
+            throw new Error("Texture is already initialized.");
+        } else if (this._state == State.DISPOSED) {
+            throw new Error("Texture is already disposed.");
+        }
+
+        if (TextureUtilities.isCompressedTextureFormat(this.textureFormat)) {
+            throw new Error("Compressed textures are not implemented for WebGPU.");
+        }
+        if (this._generateMipMaps) {
+            console.warn("WebGpuTexture2D: mipmap generation is not implemented for WebGPU; only the base level is used.");
+            this._generateMipMaps = false;
+        }
+
+        const hasData = !!this._data && this._data.length > 0;
+        let usage = WebGpuConverter.convertTextureUsage(this.textureUsage);
+        // Uploading needs COPY_DST; copyExternalImageToTexture also needs RENDER_ATTACHMENT.
+        if (hasData || this._image) {
+            usage |= GpuTextureUsage.COPY_DST;
+        }
+        if (this._image) {
+            usage |= GpuTextureUsage.RENDER_ATTACHMENT;
+        }
+
+        const device = this._graphicsDevice.device;
+        this._gpuTexture = device.createTexture({
+            label: this.label ?? `WebGpuTexture2D ${this.id}`,
+            size: {width: this.width, height: this.height, depthOrArrayLayers: 1},
+            mipLevelCount: this._mipLevels,
+            format: WebGpuConverter.convertTextureFormat(this.textureFormat),
+            usage,
+        });
+
+        if (this._image) {
+            device.queue.copyExternalImageToTexture(
+                {source: this._image},
+                {texture: this._gpuTexture},
+                {width: this.width, height: this.height});
+        } else if (hasData) {
+            let width = this.width;
+            let height = this.height;
+            for (let level = 0; level < this._data!.length; level++) {
+                const levelData = this._data![level];
+                const bytesPerPixel = TextureUtilities.getVRamSize(this.textureFormat, 1, 1);
+                device.queue.writeTexture(
+                    {texture: this._gpuTexture, mipLevel: level},
+                    levelData,
+                    {bytesPerRow: width * bytesPerPixel, rowsPerImage: height},
+                    {width, height});
+                width = Math.max(1, Math.floor(width / 2));
+                height = Math.max(1, Math.floor(height / 2));
+            }
+        }
+
+        this._gpuDefaultView = this._gpuTexture.createView({label: `${this.label ?? "WebGpuTexture2D"} default view`});
+        // ATexture2D declares the default view readonly and sets it to null; fill it in here.
+        (this as { defaultTextureView: ITextureView }).defaultTextureView =
+            new WebGpuTextureView(this._gpuDefaultView, this.textureFormat);
+        this._handle = this._gpuTexture;
+
+        this._state = State.INITIALIZED;
+
+        let width = this.width;
+        let height = this.height;
+        this._size = 0;
+        for (let i = 0; i < this.mipLevels; i++) {
+            this._size += TextureUtilities.getVRamSize(this.textureFormat, width, height);
+            width = Math.max(1, Math.floor(width / 2));
+            height = Math.max(1, Math.floor(height / 2));
+        }
+    }
+
+    /** @inheritDoc */
+    public createView(descriptor?: TextureViewDescriptor): ITextureView {
+        descriptor = descriptor ?? new TextureViewDescriptor();
+        if (descriptor.dimension !== TextureViewDimension.DIMENSION_2D) {
+            throw new Error("Only 2D texture views are implemented for WebGPU.");
+        }
+        const view = this.gpuTexture.createView({
+            label: descriptor.label,
+            format: WebGpuConverter.convertTextureFormat(descriptor.textureFormat),
+            dimension: "2d",
+        });
+        return new WebGpuTextureView(view, descriptor.textureFormat, descriptor.dimension);
+    }
+
+    /** @inheritDoc */
+    public dispose(): void {
+        if (this._state == State.DISPOSING || this._state == State.DISPOSED) {
+            return;
+        }
+        this._gpuTexture?.destroy();
+        this._gpuTexture = null;
+        this._gpuDefaultView = null;
+        this.defaultTextureView?.dispose();
+        this._state = State.DISPOSED;
+
+        for (const listener of this._disposedListeners.slice()) {
+            listener(this);
+        }
+    }
+
+    /** One default texture per framework. */
+    private static readonly _defaultFilled = new WeakMap<IFramework, WebGpuTexture2D>();
+
+    /**
+     * Returns the framework's 1x1 white texture, creating it on first use.
+     * Used when a pipeline has no texture set.
+     * @param framework The framework.
+     */
+    public static getOrCreateDefault(framework: IFramework): WebGpuTexture2D {
+        let texture = WebGpuTexture2D._defaultFilled.get(framework);
+        if (!texture || texture.state === State.DISPOSED) {
+            const desc = new TextureDescriptor();
+            desc.width = 1;
+            desc.height = 1;
+            desc.data = [new Uint8Array([255, 255, 255, 255])];
+            desc.textureFormat = framework.renderer.preferredTextureFormat;
+            desc.textureUsage = TextureUsage.TEXTURE_BINDING | TextureUsage.COPY_DST;
+            desc.label = "RisDefaultFilledTexture";
+            texture = new WebGpuTexture2D(framework, desc);
+            texture.initialize();
+            WebGpuTexture2D._defaultFilled.set(framework, texture);
+        }
+        return texture;
+    }
+
+    /**
+     * Disposes and forgets the framework's default texture. Called from `Framework.dispose()`.
+     * @param framework The framework.
+     */
+    public static disposeDefault(framework: IFramework): void {
+        const texture = WebGpuTexture2D._defaultFilled.get(framework);
+        WebGpuTexture2D._defaultFilled.delete(framework);
+        texture?.dispose();
+    }
+}

package/src/webgpu/texture/WebGpuTextureFactory.ts

@@ -0,0 +1,118 @@
+import {
+    Color,
+    type IFramework,
+    type ITexture2D,
+    type ITextureFactory,
+    TextureDescriptor,
+    TextureFormat,
+    TextureUsage,
+} from "../../api/index.ts";
+import type {IKtx2Texture} from "ris-ktx2";
+import {WebGpuTexture2D} from "./WebGpuTexture2D.ts";
+
+/**
+ * The WebGPU texture factory.
+ * @internal
+ */
+export class WebGpuTextureFactory implements ITextureFactory {
+
+    /**
+     * The constructor.
+     * @param _framework The framework.
+     */
+    public constructor(private readonly _framework: IFramework) {
+    }
+
+    /** @inheritDoc */
+    public createFromKtx2(_ktxTexture: IKtx2Texture, _descriptor?: TextureDescriptor): ITexture2D {
+        throw new Error("createFromKtx2 is not implemented for WebGPU.");
+    }
+
+    /** @inheritDoc */
+    public create(
+        width: number, height: number,
+        data?: number[] | HTMLImageElement | ArrayBufferView,
+        channels: number = 4,
+        label: string | null | undefined = null,
+        textureUsage = TextureUsage.COPY_DST | TextureUsage.TEXTURE_BINDING,
+        textureFormat = TextureFormat.RGBA_8_UNORM,
+        useMipMaps = false): ITexture2D {
+
+        if (!data) {
+            throw new Error("Data must not be null.");
+        }
+        if (width == 0 || height == 0) {
+            throw new Error("width and height must be greater than 0.");
+        }
+        if (channels == 0) {
+            throw new Error("channels must be greater than 0.");
+        }
+        if (textureFormat == TextureFormat.UNDEFINED) {
+            textureFormat = this._framework.renderer.preferredTextureFormat;
+        }
+
+        const desc = new TextureDescriptor();
+        desc.width = width;
+        desc.height = height;
+        desc.textureFormat = textureFormat;
+        desc.textureUsage = textureUsage;
+        desc.generateMipmaps = useMipMaps;
+        desc.label = label ?? null;
+
+        let image: HTMLImageElement | undefined;
+        if (typeof HTMLImageElement !== "undefined" && data instanceof HTMLImageElement) {
+            image = data;
+        } else if (Array.isArray(data)) {
+            desc.data = [new Uint8Array(data)];
+        } else {
+            const view = data as ArrayBufferView;
+            desc.data = [new Uint8Array(view.buffer, view.byteOffset, view.byteLength)];
+        }
+
+        const texture = new WebGpuTexture2D(this._framework, desc, image);
+        texture.initialize();
+        return texture;
+    }
+
+    /** @inheritDoc */
+    public createEmpty(
+        width: number, height: number,
+        color: Color | null = null,
+        textureUsage = TextureUsage.COPY_DST | TextureUsage.TEXTURE_BINDING,
+        textureFormat = TextureFormat.UNDEFINED,
+        label: string | null = null,
+        useMipmap = false): ITexture2D {
+
+        if (width == 0 || height == 0) {
+            throw new Error("Width and height must be greater than 0.");
+        }
+        if (textureFormat == TextureFormat.UNDEFINED) {
+            textureFormat = this._framework.renderer.preferredTextureFormat;
+        }
+
+        const desc = new TextureDescriptor();
+        desc.width = width;
+        desc.height = height;
+        desc.textureUsage = textureUsage;
+        desc.textureFormat = textureFormat;
+        desc.label = label;
+        desc.generateMipmaps = useMipmap;
+
+        // WebGPU zero-initializes textures, so transparent black needs no upload; neither do depth textures.
+        if (!color || (color.r === 0 && color.g === 0 && color.b === 0 && color.a === 0)) {
+            const texture = new WebGpuTexture2D(this._framework, desc);
+            texture.initialize();
+            return texture;
+        }
+
+        const byteSize = width * height * 4;
+        const bytes = new Uint8Array(byteSize);
+        for (let i = 0; i < byteSize; i += 4) {
+            bytes[i] = color.r * 255;
+            bytes[i + 1] = color.g * 255;
+            bytes[i + 2] = color.b * 255;
+            bytes[i + 3] = color.a * 255;
+        }
+        return this.create(width, height, bytes, 4, label, textureUsage, textureFormat, useMipmap);
+    }
+}

package/src/webgpu/texture/WebGpuTextureView.ts

@@ -0,0 +1,43 @@
+import {type ITextureView, TextureFormat, TextureViewDimension} from "../../api/index.ts";
+import type {GpuTextureView} from "../WebGpuTypes.ts";
+
+/**
+ * The WebGPU texture view.
+ * @internal
+ */
+export class WebGpuTextureView implements ITextureView {
+
+    private _gpuTextureView: GpuTextureView | null;
+
+    /**
+     * The constructor.
+     * @param gpuTextureView The WebGPU view.
+     * @param textureFormat The view format.
+     * @param dimension The view dimension.
+     */
+    public constructor(gpuTextureView: GpuTextureView, textureFormat: TextureFormat, dimension = TextureViewDimension.DIMENSION_2D) {
+        this._gpuTextureView = gpuTextureView;
+        this.textureFormat = textureFormat;
+        this.dimension = dimension;
+    }
+
+    /** @inheritDoc */
+    public readonly textureFormat: TextureFormat;
+
+    /** @inheritDoc */
+    public readonly dimension: TextureViewDimension;
+
+    /** The WebGPU view. */
+    public get gpuTextureView(): GpuTextureView {
+        if (!this._gpuTextureView) {
+            throw new Error("WebGpuTextureView: the view is disposed.");
+        }
+        return this._gpuTextureView;
+    }
+
+    /** @inheritDoc */
+    public dispose(): void {
+        // Views have no destroy() in WebGPU; dropping the reference is enough.
+        this._gpuTextureView = null;
+    }
+}