ris-framework 0.1.0-dev.4

package/src/webgl/swap-chain/WebGlSwapChain.ts

@@ -0,0 +1,56 @@
+import { vec2 } from "gl-matrix";
+import {type IGraphicsDevice, type ISwapChain, TextureFormat} from "ris-framework-api";
+import type {WebGlGraphicsDevice} from "../WebGlGraphicsDevice.ts";
+
+/**
+ * The WebGL implementation of the ISwapChain interface, which manages the swap chain for rendering operations in a WebGL context.
+ */
+export class WebGlSwapChain implements ISwapChain {
+
+    private readonly _canvas: HTMLCanvasElement
+    private readonly _graphicsDevice: WebGlGraphicsDevice;
+
+    private _backBufferSize: vec2;
+
+    /**
+     * The WebGLSwapChain constructor.
+     * @param canvas The HTML canvas element that the swap chain will use for rendering.
+     * @param graphicsDevice The graphics device.
+     */
+    public constructor(canvas: HTMLCanvasElement, graphicsDevice: IGraphicsDevice) {
+        this._canvas = canvas;
+        this._graphicsDevice = graphicsDevice as WebGlGraphicsDevice;
+        this._backBufferSize = vec2.fromValues(this._canvas.width, this._canvas.height);
+        this._canvas.addEventListener('resize', () => {
+            this._backBufferSize[0] = this._canvas.width;
+            this._backBufferSize[1] = this._canvas.height;
+        });
+    }
+
+
+    /** @inheritdoc */
+    public get textureFormat(): TextureFormat {
+        return TextureFormat.RGBA_8_UNORM;
+    }
+
+    /** @inheritdoc */
+    public get backBufferSize(): vec2 {
+        return this._backBufferSize;
+    }
+
+    /** @inheritdoc */
+    public resize(_width: number, _height: number): void {
+        // Nothing to do here since the canvas size is managed by the application and WebGL will automatically adjust the viewport accordingly.
+    }
+
+    /** @inheritdoc */
+    public present(): void {
+       const gl = this._graphicsDevice.gl;
+       gl.viewport(0, 0, this._canvas.width, this._canvas.height);
+    }
+
+    /** @inheritdoc */
+    public dispose(): void {
+
+    }
+}

package/src/webgl/texture/WebGlTexture2D.ts

@@ -0,0 +1,133 @@
+import {WebGlUtilities} from "../utilities/WebGlUtilities.ts";
+import {
+    TextureDescriptor,
+    type IFramework, State,
+    type ITextureView,
+    type TextureViewDescriptor, TextureUtilities
+} from "ris-framework-api";
+import type {WebGlGraphicsDevice} from "../WebGlGraphicsDevice.ts";
+import {ATexture2D} from "../../core/rendering/texture/texture.ts";
+import {vec2} from "gl-matrix";
+
+/**
+ * The WebGL implementation of ITexture2D.
+ */
+export class WebGlTexture2D extends ATexture2D {
+
+    private readonly _graphicsDevice: WebGlGraphicsDevice;
+    private readonly _gl: WebGL2RenderingContext;
+    private _glTexture: WebGLTexture | null = null;
+
+    /**
+     * The constructor.
+     * @param _framework The framework instance.
+     * @param textureDescriptor The texture descriptor.
+     */
+    constructor(
+        private readonly _framework: IFramework,
+        textureDescriptor: TextureDescriptor
+    ) {
+        super(textureDescriptor);
+        this._graphicsDevice = this._framework.renderer.graphicsDevice as WebGlGraphicsDevice;
+        this._gl = this._graphicsDevice.gl!;
+    }
+
+    /**
+     * Gets the underlying WebGL texture.
+     * @returns The WebGL texture.
+     */
+    public get glTexture(): WebGLTexture {
+        return this._glTexture!;
+    }
+
+    /** @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)) {
+            this._glTexture = WebGlUtilities.texture.createCompressedTexture2D(
+                this._gl, vec2.fromValues(this.width, this.height),
+                this._blockSize, this._data, this.label, this.textureFormat, 0);
+        } else {
+            this._glTexture = WebGlUtilities.texture.createTexture2D(
+                this._gl,
+                this.width, this.height,
+                this._data,
+                this.textureFormat,
+                this._generateMipMaps,
+                0,
+                this.label
+            );
+        }
+
+        this._state = State.INITIALIZED;
+
+
+        let width = this.width;
+        let height = this.height;
+
+        // If we can generate mipmaps, we need to calculate the number of mip levels.
+        if(this._generateMipMaps) {
+            this._mipLevels = TextureUtilities.mipLevels(width, height);
+        }
+        this._size = 0;
+
+        for (let i = 0; i < this.mipLevels; i++) {
+            this._size += TextureUtilities.getVRamSize(this.textureFormat, width, height);
+            width /= 2;
+            height /= 2;
+        }
+    }
+
+    /** @inheritdoc */
+    public createView(_descriptor?: TextureViewDescriptor): ITextureView {
+        throw new Error("Method not implemented.");
+    }
+
+
+    /** @inheritdoc */
+    public dispose(): void {
+
+        if (this._state == State.DISPOSING || this._state == State.DISPOSED) {
+            return;
+        }
+
+        this._gl.deleteTexture(this._glTexture);
+        this._glTexture = null;
+        this._state = State.DISPOSED;
+
+        for (const listener of this._disposedListeners) {
+            listener(this);
+        }
+    }
+
+    private static _defaultFilled: WebGlTexture2D | null = null;
+
+    /**
+     * Creates a default 1x1 white texture if it doesn't already exist and returns it.
+     * This can be used as a placeholder texture when a texture is expected but not available.
+     * @param framework The framework instance.
+     * @returns The default 1x1 white texture.
+     */
+    public static getOrCreateDefault(framework: IFramework): WebGlTexture2D {
+        if (this._defaultFilled === null || this._defaultFilled.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.label = "RisDefaultFilledTexture";
+
+            this._defaultFilled = new WebGlTexture2D(framework, desc);
+            this._defaultFilled.initialize();
+        }
+
+        return this._defaultFilled;
+    }
+
+}

package/src/webgl/texture/WebGlTextureFactory.ts

@@ -0,0 +1,184 @@
+import {
+    Color,
+    type IFramework,
+    type ITexture2D,
+    type ITextureFactory,
+    TextureDescriptor,
+    TextureFormat,
+    TextureUsage,
+    TextureUtilities
+} from "ris-framework-api"
+import {WebGlTexture2D} from "./WebGlTexture2D.ts";
+import {type IKtx2Texture, KtxTranscodeFlags, KtxTranscodeFormat, TextureFormatInfo, VkFormat} from "ris-ktx2-api";
+import {vec2} from "gl-matrix";
+
+export class WebGlTextureFactory implements ITextureFactory {
+
+    /**
+     * The constructor for the WebGLTextureFactory class.
+     * @param _framework The framework instance.
+     */
+    constructor(private readonly _framework: IFramework) {
+    }
+
+    /** @inheritDoc */
+    public createFromKtx2(ktxTexture: IKtx2Texture, descriptor?: TextureDescriptor): ITexture2D {
+        descriptor = descriptor ?? new TextureDescriptor();
+        const vkFormat = ktxTexture.vkFormat;
+
+        // Ktx2 will have different cases, for now we consider simple 2d case.
+        const numLevels = ktxTexture.numLevels;
+        let transcodeFormat = KtxTranscodeFormat.NO_SELECTION;
+        let textureFormat = descriptor.textureFormat;
+        const gpuFeatures = this._framework.graphicsDevice.features;
+        let texFormatInfo: TextureFormatInfo | null = null;
+
+        if (ktxTexture.needsTranscoding && vkFormat == VkFormat.UNDEFINED)
+        {
+            // If descriptor format is UNDEFINED, we will use format according to the GPU features.
+            if(descriptor.textureFormat == TextureFormat.UNDEFINED)
+            {
+                if(gpuFeatures.supportsTextureCompressionBC)
+                {
+                    transcodeFormat = KtxTranscodeFormat.BC7_RGBA;
+                    textureFormat = TextureFormat.BC7_RGBA_UNORM;
+                }
+                else if(gpuFeatures.supportsTextureCompressionASTC)
+                {
+                    transcodeFormat = KtxTranscodeFormat.ASTC_4X4_RGBA;
+                    textureFormat = TextureFormat.ASTC_4X4_RGBA
+                }
+                else if(gpuFeatures.supportsTextureCompressionS3TC)
+                {
+                    transcodeFormat = KtxTranscodeFormat.BC3_RGBA;
+                    textureFormat = TextureFormat.BC3_RGBA_UNORM;
+                }
+                else if(gpuFeatures.supportsTextureCompressionETC2)
+                {
+                    transcodeFormat = KtxTranscodeFormat.ETC2_RGBA;
+                    textureFormat = TextureFormat.ETC2_RGBA8_UNORM;
+                }
+            }
+            else
+            {
+                transcodeFormat = TextureUtilities.convertTextureFormatToKtxTranscodeFormat(textureFormat);
+            }
+
+            ktxTexture.transcodeBasis(transcodeFormat, KtxTranscodeFlags.HIGH_QUALITY);
+            texFormatInfo = ktxTexture.getTextureFormatInfo(transcodeFormat);
+        }
+        else {
+            // No transcoding path, but still get info about the texture format.
+            textureFormat = TextureUtilities.convertVkFormatToTextureFormat(vkFormat);
+            texFormatInfo = ktxTexture.getTextureFormatInfo(vkFormat);
+        }
+
+        const data: Uint8Array[] = [];
+        for (let i = 0; i < numLevels; i++)
+        {
+            data.push(ktxTexture.getImage(i));
+        }
+
+        const textureDescriptor = new TextureDescriptor();
+        textureDescriptor.width = ktxTexture.width;
+        textureDescriptor.height = ktxTexture.height;
+        textureDescriptor.data = data;
+        textureDescriptor.textureFormat = textureFormat;
+        textureDescriptor.generateMipmaps = descriptor.generateMipmaps;
+        textureDescriptor.blockSize = vec2.fromValues(texFormatInfo.blockWidth, texFormatInfo.blockHeight);
+
+        const texture = new WebGlTexture2D(this._framework, textureDescriptor);
+        texture.initialize();
+        return texture;
+    }
+
+    /** @inheritdoc */
+    public create(
+        width: number, height: number,
+        data?: Uint8Array | HTMLImageElement,
+        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.");
+        }
+
+        const desc = new TextureDescriptor();
+        desc.width = width;
+        desc.height = height;
+        // @ts-ignore
+        desc.data = data ? [data] : null;
+        desc.textureFormat = textureFormat;
+        desc.textureUsage = textureUsage;
+        desc.generateMipmaps = useMipMaps;
+        desc.label = label;
+
+        const texture = new WebGlTexture2D(
+            this._framework,
+         desc
+        );
+
+        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;
+
+        // Fast path: avoid generating & uploading a big CPU-side buffer when not needed.
+        if (!color || color.equals(Color.black())) {
+            const texture = new WebGlTexture2D(
+                this._framework,
+               desc
+            );
+
+            texture.initialize();
+            return texture;
+        }
+
+        // Fill CPU-side pixels (BGRA layout to match TextureFormat.BGRA_8_Unorm usage elsewhere).
+        const byteSize = width * height * 4;
+        const bytes = new Uint8Array(byteSize);
+
+        for (let i = 0; i < byteSize; i += 4) {
+            bytes[i + 0] = color.b * 255;
+            bytes[i + 1] = color.g * 255;
+            bytes[i + 2] = color.r * 255;
+            bytes[i + 3] = color.a * 255;
+        }
+
+        return this.create( width, height, bytes, 4, label, textureUsage, textureFormat, useMipmap );
+    }
+}

package/src/webgl/utilities/WebGlBufferUtilities.ts

@@ -0,0 +1,124 @@
+import { WebGlConverter } from "./WebGlConverter.ts";
+import type {BufferUsage} from "ris-framework-api";
+
+/**
+ * This file contains utility functions for working with WebGL buffers, 
+ * such as creating and managing vertex buffers, index buffers, and uniform buffers.
+ * It provides a higher-level abstraction over the raw WebGL API to simplify buffer management in a WebGL application.
+ */
+export class WebGlBufferUtilities {
+
+    /**
+     * Creates a vertex buffer in WebGL with the given data and usage.
+     * @param gl The WebGL2RenderingContext to use for creating the buffer.
+     * @param dataOrByteSize The data to upload to the vertex buffer, typically a Float32Array containing vertex attributes, or a number representing the byte size of the buffer to create.
+     * @param usage The intended usage of the buffer, which can affect how the buffer is created and optimized by the graphics API. For example, a vertex buffer may be optimized for use as a vertex buffer in rendering operations.
+     * @returns The created WebGLBuffer object that represents the vertex buffer in WebGL.
+     */
+    public createVertexBuffer(gl: WebGL2RenderingContext, dataOrByteSize: Float32Array | number, usage: BufferUsage): WebGLBuffer {
+        const buffer = gl.createBuffer();
+        if (!buffer) {
+            throw new Error("Failed to create vertex buffer.");
+        }
+
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        if (typeof dataOrByteSize === "number") {
+            gl.bufferData(gl.ARRAY_BUFFER, dataOrByteSize, WebGlConverter.convertBufferUsage(usage));
+        } else {
+            gl.bufferData(gl.ARRAY_BUFFER, dataOrByteSize, WebGlConverter.convertBufferUsage(usage));
+        }
+
+        gl.bindBuffer(gl.ARRAY_BUFFER, null);
+        return buffer;
+    }
+
+    /**
+     * Creates an index buffer in WebGL with the given data and usage.
+     * @param gl The WebGL2RenderingContext to use for creating the buffer.
+     * @param dataOrByteSize The data to upload to the index buffer, typically a Uint16Array or Uint32Array containing index data, or a number representing the byte size of the buffer to create.
+     * @param usage The intended usage of the buffer, which can affect how the buffer is created and optimized by the graphics API. For example, an index buffer may be optimized for use as an index buffer in rendering operations.
+     * @param label The label.
+     * @returns The created WebGLBuffer object that represents the index buffer in WebGL.
+     */
+    public createIndexBuffer(gl: WebGL2RenderingContext,
+                             dataOrByteSize: Uint16Array | Uint32Array | number,
+                             usage: BufferUsage,
+                             label?: string
+    ): WebGLBuffer {
+        const buffer = gl.createBuffer();
+        if (!buffer) {
+            throw new Error("Failed to create index buffer.");
+        }
+
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, buffer);
+        if (typeof dataOrByteSize === "number") {
+            gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, dataOrByteSize, WebGlConverter.convertBufferUsage(usage));
+        } else {
+            gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, dataOrByteSize, WebGlConverter.convertBufferUsage(usage));
+        }
+
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, null);
+
+        if(label) {
+            // @ts-ignore
+            buffer["__SPECTOR_Metadata"] = {
+                "name": label,
+            };
+        }
+
+        return buffer;
+    }
+
+    /**
+     * Creates a uniform buffer in WebGL with the given data and usage.
+     * @param gl The WebGL2RenderingContext to use for creating the buffer.
+     * @param dataOrByteSize The data to upload to the uniform buffer, typically an ArrayBuffer or a TypedArray containing uniform data, or a number representing the byte size of the buffer to create.
+     * @param usage The intended usage of the buffer, which can affect how the buffer is created and optimized by the graphics API. For example, a uniform buffer may be optimized for use as a uniform buffer in rendering operations.
+     * @param label An optional label for the buffer, which can be used for debugging purposes to identify the buffer in graphics debugging tools. 
+    * @returns The created WebGLBuffer object that represents the uniform buffer in WebGL.
+     */
+    public createUniformBuffer(gl: WebGL2RenderingContext, dataOrByteSize: ArrayBuffer | ArrayBufferView | number, usage: BufferUsage, label?: string): WebGLBuffer {
+        const buffer = gl.createBuffer();
+        if (!buffer) {
+            throw new Error("Failed to create uniform buffer.");
+        }
+
+        if(label) {
+            (buffer as any)["__SPECTOR_Metadata"] = { name: label };
+        }
+
+        gl.bindBuffer(gl.UNIFORM_BUFFER, buffer);
+        if (typeof dataOrByteSize === "number") {
+            gl.bufferData(gl.UNIFORM_BUFFER, dataOrByteSize, WebGlConverter.convertBufferUsage(usage));
+        } else {
+            gl.bufferData(gl.UNIFORM_BUFFER, dataOrByteSize, WebGlConverter.convertBufferUsage(usage));
+        }
+
+        gl.bindBuffer(gl.UNIFORM_BUFFER, null);
+        return buffer;
+    }
+
+    /**
+     * Updates the vertex buffer.
+     * @param gl
+     * @param buffer
+     * @param data The data.
+     * @param destOffset Offset into destination.
+     * @param srcOffset
+     * @param srcLength
+     */
+    public updateVertexBuffer(
+        gl: WebGL2RenderingContext,
+        buffer: WebGLBuffer,
+        data: Float32Array,
+        destOffset: number = 0,
+        srcOffset: number = 0,
+        srcLength: number = 0) {
+
+        srcLength = srcLength > 0 ? srcLength : data.length;
+
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, destOffset, data, srcOffset, srcLength );
+        gl.bindBuffer(gl.ARRAY_BUFFER, null);
+    }
+}