ris-framework 0.1.0 → 0.2.0-dev.12

package/src/webgl/utilities/WebGlErrorUtilities.ts

@@ -0,0 +1,15 @@
+export class WebGlErrorUtilities {
+
+    private readonly _map: Record<number, string> = {
+        1282: "INVALID_OPERATION"
+    }
+
+    /**
+     * Maps the WebGL2 error code to string.
+     * @param error The error code.
+     * @return The string of error code.
+     */
+    public errorToStr(error: number) : string {
+        return this._map[error] ?? error.toString();
+    }
+}

package/src/webgl/utilities/WebGlTextureUtilities.ts

@@ -1,6 +1,7 @@
 import {WebGlConverter} from "./WebGlConverter.ts";
 import {AlignUtilities, TextureFormat} from "../../api/index.ts";
 import {vec2} from "gl-matrix";
+import {WebGlUtilities} from "./WebGlUtilities.ts";
 
 /**
  * The utilities for working with WebGL textures.
@@ -120,8 +121,8 @@ export class WebGlTextureUtilities {
         gl.bindTexture(gl.TEXTURE_2D, texture);
 
         const internalFormat = WebGlConverter.convertInternalFormat(gl, textureFormat);
-
         const useTexStorage = baseWidth % blockSize[0] == 0 && baseHeight % blockSize[1] == 0;
+
         if (useTexStorage) {
             gl.texStorage2D(gl.TEXTURE_2D, mipLevels, internalFormat, baseWidth, baseHeight);
         }
@@ -163,7 +164,9 @@ export class WebGlTextureUtilities {
 
         const error = gl.getError();
         if (error != gl.NO_ERROR) {
-            throw new Error("WebGlTextureUtilities error " + error.toString());
+            const errorStr ="WebGlTextureUtilities error " + WebGlUtilities.error.errorToStr(error);
+            console.error(errorStr);
+            throw new Error(errorStr);
         }
 
         return texture;

package/src/webgl/utilities/WebGlUtilities.ts

@@ -8,6 +8,7 @@ import { WebGLRenderbufferUtilities } from "./webgl-renderbuffer-utilities";
 import { WebGlSamplerUtilities } from "./WebGlSamplerUtilities.ts";
 import { WebGlShaderUtilities } from "./WebGlShaderUtilities.ts";
 import { WebGlTextureUtilities } from "./WebGlTextureUtilities.ts";
+import {WebGlErrorUtilities} from "./WebGlErrorUtilities.ts";
 
 /**
  * The utility class for WebGL operations.
@@ -68,4 +69,7 @@ export class WebGlUtilities {
      * The WebGL program utilities.
      */
     public static readonly program = new WebGLProgramUtilities();
+
+    /** The WebGL error utilities. Helper class for working with errors. */
+    public  static  readonly error = new WebGlErrorUtilities();
 }

package/src/webgl/utilities/webgl-filter-anisotropic-utilities.ts

@@ -7,18 +7,17 @@ export class WebGLFilterAnisotropicUtilities {
      */
     private MAX_ANISOTROPY_EXT: string = "EXT_texture_filter_anisotropic";
 
-    private _extension: any;
-
     /**
      * Gets the max anisotropy.
      * @param gl The WebGL2 rendering context.
      * @returns The maximum supported level of anisotropic filtering. `0` if not supported.
      */
     public getMaxAnisotropy(gl: WebGL2RenderingContext): number {
-        this._extension = gl.getExtension(this.MAX_ANISOTROPY_EXT);
+        // Looked up per context: this utility is a shared static, and an extension object belongs to one context.
+        const extension = gl.getExtension(this.MAX_ANISOTROPY_EXT);
 
-        if (this._extension) {
-            return gl.getParameter(this._extension.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
+        if (extension) {
+            return gl.getParameter(extension.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
         }
 
         return 0;
@@ -31,7 +30,11 @@ export class WebGLFilterAnisotropicUtilities {
      * @param anisotropy The level of anisotropic filtering
      */
     public setAnisotropy(gl: WebGL2RenderingContext, texture: WebGLTexture, anisotropy: number) {
+        const extension = gl.getExtension(this.MAX_ANISOTROPY_EXT);
+        if (!extension) {
+            return;
+        }
         gl.bindTexture(gl.TEXTURE_2D, texture);
-        gl.texParameterf(gl.TEXTURE_2D, this._extension.MAX_TEXTURE_MAX_ANISOTROPY_EXT, anisotropy);
+        gl.texParameterf(gl.TEXTURE_2D, extension.MAX_TEXTURE_MAX_ANISOTROPY_EXT, anisotropy);
     }
 }

package/src/webgpu/WebGpuGpuInfo.ts

@@ -0,0 +1,61 @@
+import {type IGPUInfo, RenderingBackend, TextureFormat} from "../api/index.ts";
+import type {GpuAdapter} from "./WebGpuTypes.ts";
+import type {WebGpuGraphicsDeviceFeatures} from "./WebGpuGraphicsDeviceFeatures.ts";
+
+/**
+ * The WebGPU GPU info, read from the adapter info.
+ * @internal
+ */
+export class WebGpuGpuInfo implements IGPUInfo {
+
+    /**
+     * The constructor.
+     * @param adapter The adapter.
+     * @param features The device features.
+     */
+    public constructor(adapter: GpuAdapter, features: WebGpuGraphicsDeviceFeatures) {
+        const info = adapter.info;
+        this.name = info?.description || info?.device || info?.architecture || "Unknown";
+        this.vendor = info?.vendor || "Unknown";
+        this.apiVersion = "WebGPU";
+        this.api = RenderingBackend.WEB_GPU;
+        // The native API behind WebGPU (Vulkan, Metal, D3D12) is hidden from the page.
+        this.underlyingBackend = RenderingBackend.DEFAULT;
+
+        // Features are read from the device (only requested features are enabled), so this lists what can be created.
+        const formats: TextureFormat[] = [];
+        if (features.supportsTextureCompressionASTC) {
+            formats.push(TextureFormat.ASTC_4X4_RGBA_UNORM, TextureFormat.ASTC_4X4_RGBA_SRGB);
+        }
+        if (features.supportsTextureCompressionS3TC) {
+            formats.push(TextureFormat.BC1_RGB_UNORM, TextureFormat.BC1_RGB_SRGB,
+                TextureFormat.BC3_RGBA_UNORM, TextureFormat.BC3_RGBA_SRGB);
+        }
+        if (features.supportsTextureCompressionETC2) {
+            formats.push(TextureFormat.ETC2_RGB8_UNORM, TextureFormat.ETC2_RGB8_SRGB,
+                TextureFormat.ETC2_RGBA8_UNORM, TextureFormat.ETC2_RGBA8_SRGB);
+        }
+        if (features.supportsTextureCompressionBC) {
+            formats.push(TextureFormat.BC7_RGBA_UNORM, TextureFormat.BC7_RGBA_SRGB);
+        }
+        this.supportedCompressedTextureFormats = formats;
+    }
+
+    /** @inheritDoc */
+    public readonly name: string;
+
+    /** @inheritDoc */
+    public readonly vendor: string;
+
+    /** @inheritDoc */
+    public readonly apiVersion: string;
+
+    /** @inheritDoc */
+    public readonly api: RenderingBackend;
+
+    /** @inheritDoc */
+    public readonly underlyingBackend: RenderingBackend;
+
+    /** @inheritDoc */
+    public readonly supportedCompressedTextureFormats: TextureFormat[];
+}

package/src/webgpu/WebGpuGraphicsDevice.ts

@@ -0,0 +1,199 @@
+import {AGraphicsDevice, type IGraphicsDeviceDescriptor} from "../core/rendering/AGraphicsDevice.ts";
+import type {BlendStateDescriptor} from "../core/rendering/blending/blend-state-descriptor.ts";
+import type {SamplerDescriptor} from "../core/rendering/sampler/sampler-descriptor.ts";
+import {
+    type IBlendState,
+    type IGPUInfo,
+    type IPrimitiveState,
+    type IRenderPass,
+    type ISampler,
+    type ISwapChain,
+    type IWindowManager,
+    PrimitiveStateDescriptor,
+    RenderPassDescriptor,
+    SwapChainDescriptor,
+} from "../api/index.ts";
+import {getNavigatorGpu, type GpuAdapter, type GpuDevice, type GpuRenderPassEncoder} from "./WebGpuTypes.ts";
+import {PowerPreferenceType} from "../api/rendering/PowerPreference.ts";
+import {WebGpuGraphicsDeviceFeatures} from "./WebGpuGraphicsDeviceFeatures.ts";
+import {WebGpuGpuInfo} from "./WebGpuGpuInfo.ts";
+import {WebGpuSwapChain} from "./swap-chain/WebGpuSwapChain.ts";
+import {WebGpuSampler} from "./sampler/WebGpuSampler.ts";
+import {WebGpuRenderPass} from "./render-pass/WebGpuRenderPass.ts";
+import {WebGpuBlendState} from "./blending/WebGpuBlendState.ts";
+import {WebGpuPrimitiveState} from "./primitive/WebGpuPrimitiveState.ts";
+
+/**
+ * The WebGPU graphics device. It requests its own adapter and device in {@link createAsync},
+ * so everything after creation is synchronous like WebGL.
+ * @internal
+ */
+export class WebGpuGraphicsDevice extends AGraphicsDevice {
+
+    private readonly _windowManager: IWindowManager;
+    private readonly _adapter: GpuAdapter;
+    private readonly _device: GpuDevice;
+    private _features: WebGpuGraphicsDeviceFeatures = null!;
+    private _gpuInfo: WebGpuGpuInfo = null!;
+    private _swapChain: WebGpuSwapChain | null = null;
+
+    /**
+     * The render pass encoder of the pass that is currently open, or null between passes.
+     * Set by {@link WebGpuRenderPass.beginPass}, like `currentRenderPassEncoder` in the C# device.
+     */
+    public currentRenderPassEncoder: GpuRenderPassEncoder | null = null;
+
+    /**
+     * Creates the graphics device: requests the WebGPU adapter and device.
+     * Throws when WebGPU is unavailable or no adapter is found.
+     * @param windowManager The window manager.
+     * @param descriptor The device descriptor.
+     * @returns The created graphics device.
+     */
+    public static async createAsync(windowManager: IWindowManager, descriptor: IGraphicsDeviceDescriptor): Promise<WebGpuGraphicsDevice> {
+        const gpu = getNavigatorGpu();
+        if (!gpu) {
+            throw new Error("WebGPU is not supported: navigator.gpu is missing.");
+        }
+        const preference = descriptor.powerPreference;
+        const adapter = await gpu.requestAdapter(
+            preference && preference !== PowerPreferenceType.DEFAULT
+                ? {powerPreference: preference as unknown as "low-power" | "high-performance"}
+                : undefined);
+        if (!adapter) {
+            throw new Error("WebGPU is not supported: no adapter was found.");
+        }
+        // WebGPU only enables the features that are requested, so ask for every compression family the adapter has.
+        const requiredFeatures = ["texture-compression-bc", "texture-compression-etc2", "texture-compression-astc"]
+            .filter(feature => adapter.features.has(feature));
+        const device = await adapter.requestDevice({label: "RisFramework WebGPU device", requiredFeatures});
+        return new WebGpuGraphicsDevice(windowManager, descriptor, adapter, device);
+    }
+
+    /**
+     * The constructor. Use {@link createAsync} to create the device.
+     * @param windowManager The window manager.
+     * @param descriptor The device descriptor.
+     * @param adapter The WebGPU adapter.
+     * @param device The WebGPU device.
+     */
+    private constructor(windowManager: IWindowManager, descriptor: IGraphicsDeviceDescriptor, adapter: GpuAdapter, device: GpuDevice) {
+        super(descriptor);
+        this._windowManager = windowManager;
+        this._adapter = adapter;
+        this._device = device;
+    }
+
+    /** The WebGPU device. */
+    public get device(): GpuDevice {
+        return this._device;
+    }
+
+    /** The WebGPU adapter. */
+    public get adapter(): GpuAdapter {
+        return this._adapter;
+    }
+
+    /** Whether the canvas should keep its alpha channel. */
+    public get alpha(): boolean {
+        return this._descriptor.alpha;
+    }
+
+    /** The swap chain, once created. */
+    public get swapChain(): WebGpuSwapChain | null {
+        return this._swapChain;
+    }
+
+    /** The window manager. */
+    public get windowManager(): IWindowManager {
+        return this._windowManager;
+    }
+
+    /** @inheritDoc */
+    public get features(): WebGpuGraphicsDeviceFeatures {
+        return this._features;
+    }
+
+    /** @inheritDoc */
+    public get gpuInfo(): IGPUInfo {
+        return this._gpuInfo;
+    }
+
+    /** The current render pass encoder. Throws when no pass is open. */
+    public get renderPassEncoder(): GpuRenderPassEncoder {
+        if (!this.currentRenderPassEncoder) {
+            throw new Error("WebGpuGraphicsDevice: no render pass is open. Draw calls must happen between beginRenderPass and endRenderPass.");
+        }
+        return this.currentRenderPassEncoder;
+    }
+
+    /** @inheritDoc */
+    public initialize(): void {
+        this._features = new WebGpuGraphicsDeviceFeatures(this._device.features);
+        this._gpuInfo = new WebGpuGpuInfo(this._adapter, this._features);
+        this.setupDebugCallback();
+        super.initialize();
+    }
+
+    /** @inheritDoc */
+    public createSwapChain(canvas: HTMLCanvasElement, descriptor: SwapChainDescriptor): ISwapChain {
+        this._swapChain?.dispose();
+        this._swapChain = new WebGpuSwapChain(canvas, this, descriptor);
+        return this._swapChain;
+    }
+
+    /** @inheritDoc */
+    public createSampler(descriptor?: SamplerDescriptor): ISampler {
+        return new WebGpuSampler(this, descriptor);
+    }
+
+    /** @inheritDoc */
+    public createRenderPass(descriptor: RenderPassDescriptor): IRenderPass {
+        return new WebGpuRenderPass(this, descriptor);
+    }
+
+    /** @inheritDoc */
+    public createBlendState(descriptor: BlendStateDescriptor): IBlendState {
+        return new WebGpuBlendState(descriptor);
+    }
+
+    /** @inheritDoc */
+    public createPrimitiveState(descriptor?: PrimitiveStateDescriptor): IPrimitiveState {
+        return new WebGpuPrimitiveState(descriptor ?? new PrimitiveStateDescriptor());
+    }
+
+    /** @inheritDoc */
+    public setupDebugCallback(): void {
+        this._device.addEventListener("uncapturederror", event => {
+            console.error(`WebGPU error: ${event.error.message}`);
+        });
+        this._device.lost.then(info => {
+            if (info.reason !== "destroyed") {
+                console.error(`WebGPU device lost (${info.reason}): ${info.message}`);
+            }
+        }).catch(() => { /* ignore */ });
+    }
+
+    /** @inheritDoc */
+    public frameEnd(): void {
+        // Command buffers are submitted at the end of every render pass, so nothing is pending here.
+    }
+
+    /** @inheritDoc */
+    public pushDebugGroup(groupName: string): void {
+        this.currentRenderPassEncoder?.pushDebugGroup(groupName);
+    }
+
+    /** @inheritDoc */
+    public popDebugGroup(): void {
+        this.currentRenderPassEncoder?.popDebugGroup();
+    }
+
+    /** @inheritDoc */
+    public dispose(): void {
+        super.dispose();
+        this._swapChain?.dispose();
+        this._swapChain = null;
+        this._device.destroy();
+    }
+}

package/src/webgpu/WebGpuGraphicsDeviceFeatures.ts

@@ -0,0 +1,41 @@
+import type {IGraphicsDeviceFeatures} from "../api/index.ts";
+import type {GpuSupportedFeatures} from "./WebGpuTypes.ts";
+
+/**
+ * The WebGPU graphics device features, read from the device's enabled features.
+ * @internal
+ */
+export class WebGpuGraphicsDeviceFeatures implements IGraphicsDeviceFeatures {
+
+    /**
+     * The constructor.
+     * @param features The device's enabled features.
+     */
+    public constructor(features: GpuSupportedFeatures) {
+        this.supportsTextureCompressionBC = features.has("texture-compression-bc");
+        // S3TC (BC1-BC3) is part of the WebGPU BC feature.
+        this.supportsTextureCompressionS3TC = this.supportsTextureCompressionBC;
+        this.supportsTextureCompressionS3TCSrgb = this.supportsTextureCompressionBC;
+        this.supportsTextureCompressionETC2 = features.has("texture-compression-etc2");
+        this.supportsTextureCompressionASTC = features.has("texture-compression-astc");
+        this.supportsTextureCompressionPVRTC = false;
+    }
+
+    /** @inheritDoc */
+    public readonly supportsTextureCompressionS3TC: boolean;
+
+    /** @inheritDoc */
+    public readonly supportsTextureCompressionS3TCSrgb: boolean;
+
+    /** @inheritDoc */
+    public readonly supportsTextureCompressionBC: boolean;
+
+    /** @inheritDoc */
+    public readonly supportsTextureCompressionETC2: boolean;
+
+    /** @inheritDoc */
+    public readonly supportsTextureCompressionASTC: boolean;
+
+    /** @inheritDoc */
+    public readonly supportsTextureCompressionPVRTC: boolean;
+}

package/src/webgpu/WebGpuRenderer.ts

@@ -0,0 +1,49 @@
+import {ARenderer} from "../core/rendering/ARenderer.ts";
+import {type IFramework, type IGraphicsDevice, type IRendererConfiguration, RenderingBackend} from "../api/index.ts";
+import {WebGpuGraphicsDevice} from "./WebGpuGraphicsDevice.ts";
+import {getNavigatorGpu} from "./WebGpuTypes.ts";
+
+/**
+ * The WebGPU renderer. WebGPU hands out the adapter and device asynchronously, so call
+ * {@link acquireDeviceAsync} (done by `Framework.initializeAsync()`) before {@link initialize}.
+ * @internal
+ */
+export class WebGpuRenderer extends ARenderer {
+
+    private _createdDevice: WebGpuGraphicsDevice | null = null;
+
+    /**
+     * The constructor.
+     * @param framework The framework.
+     * @param renderConfiguration The renderer configuration.
+     */
+    public constructor(framework: IFramework, renderConfiguration: IRendererConfiguration) {
+        super(framework, renderConfiguration);
+        this.backend = RenderingBackend.WEB_GPU;
+    }
+
+    /** Whether the browser exposes `navigator.gpu`. */
+    public static isSupported(): boolean {
+        return getNavigatorGpu() !== undefined;
+    }
+
+    /**
+     * Creates the graphics device, which requests its own adapter and device.
+     * Throws when WebGPU is unavailable or no adapter is found.
+     */
+    public async acquireDeviceAsync(): Promise<void> {
+        this._createdDevice = await WebGpuGraphicsDevice.createAsync(this._framework.windowManager, {
+            samplerFilteringPreset: this._renderConfiguration.textureFiltering,
+            alpha: this._renderConfiguration.alpha,
+            powerPreference: this._renderConfiguration.powerPreference,
+        });
+    }
+
+    /** @inheritDoc */
+    protected createGraphicsDevice(): IGraphicsDevice {
+        if (!this._createdDevice) {
+            throw new Error("WebGpuRenderer: the device is not created. Use Framework.initializeAsync() for WebGPU.");
+        }
+        return this._createdDevice;
+    }
+}