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

package/src/core/rendering/ARenderer.ts

@@ -18,7 +18,7 @@ import {
     TextureFormat,
     TextureUsage
 } from "../../api/index.ts";
-import {TextureColorSpace} from "../../api/rendering/enums.ts";
+import {ColorSpace} from "../../api/rendering/enums.ts";
 
 export abstract class ARenderer implements ITempRenderer {
 
@@ -36,6 +36,7 @@ export abstract class ARenderer implements ITempRenderer {
     private _swapChainRequiresResize: boolean = false;
     private _mainRenderPassDirty = true;
     private _clearColor: Color = Color.lightPink();
+    private _colorSpace: ColorSpace;
 
     protected _mainRenderTargetRequiresResize: boolean = false;
     protected _swapChain: ISwapChain = null!;
@@ -46,6 +47,7 @@ export abstract class ARenderer implements ITempRenderer {
     protected _mainRenderTargetPipeline?: IMainRenderTargetRenderPipeline;
     protected _renderConfiguration: IRendererConfiguration;
 
+
     /** @inheritdoc */
     public get graphicsDevice(): IGraphicsDevice {
         return this._graphicsDevice;
@@ -67,7 +69,27 @@ export abstract class ARenderer implements ITempRenderer {
     }
 
     /** @inheritdoc */
-    public readonly preferredTextureFormat: TextureFormat;
+    public get preferredTextureFormat(): TextureFormat {
+        return this._colorSpace == ColorSpace.SRGB ? TextureFormat.RGBA_8_UNORM_SRGB : TextureFormat.RGBA_8_UNORM;
+    }
+
+    /** @inheritDoc */
+    public get colorSpace(): ColorSpace {
+        return this._colorSpace;
+    }
+
+    /** @inheritDoc */
+    public set colorSpace(colorSpace: ColorSpace) {
+        if (colorSpace == this._colorSpace) {
+            return;
+        }
+        this._colorSpace = colorSpace;
+        if (this._mainRenderTargetPipeline) {
+            this._mainRenderTargetPipeline.colorSpace = colorSpace;
+            // The main render target's format follows the color space, so recreate it on the next frame.
+            this._mainRenderTargetRequiresResize = true;
+        }
+    }
 
     /** @inheritdoc */
     public get preferredDepthStencilFormat(): TextureFormat {
@@ -108,8 +130,7 @@ export abstract class ARenderer implements ITempRenderer {
         this._windowManager = framework.windowManager;
         this._currentBackBufferSize[0] = this._windowManager.canvas.width;
         this._currentBackBufferSize[1] = this._windowManager.canvas.height;
-        this.preferredTextureFormat = configuration.textureColorSpace == TextureColorSpace.SRGB
-            ? TextureFormat.RGBA_8_UNORM_SRGB : TextureFormat.RGBA_8_UNORM;
+        this._colorSpace = configuration.textureColorSpace;
     }
 
      backend: RenderingBackend = RenderingBackend.WEB_GL;
@@ -188,6 +209,7 @@ export abstract class ARenderer implements ITempRenderer {
         this._mainRenderTargetPipeline = this._framework
             .renderPipelineFactory
             .createMainFrameBufferPipeline(this._mainRenderTarget);
+        this._mainRenderTargetPipeline.colorSpace = this._colorSpace;
 
         this._createMainRenderPass();
         this._mainRenderTargetRequiresResize = false;

package/src/core/rendering/primitive/PrimitiveStateDescriptorUtilities.ts

@@ -0,0 +1,22 @@
+import {CullMode, FrontFace, type IPrimitiveStateDescriptor, PrimitiveTopology} from "../../../api/index.ts";
+
+/**
+ * A primitive state descriptor with all defaults applied.
+ * @internal
+ */
+export type ResolvedPrimitiveStateDescriptor = Required<IPrimitiveStateDescriptor>;
+
+/**
+ * Fills in the defaults for every missing field of a primitive state descriptor:
+ * TRIANGLE_LIST topology, BACK culling and CCW front face.
+ * @param desc The descriptor, possibly partial or missing.
+ * @returns A new descriptor with the defaults applied.
+ * @internal
+ */
+export function resolvePrimitiveStateDescriptor(desc?: IPrimitiveStateDescriptor): ResolvedPrimitiveStateDescriptor {
+    return {
+        topology: desc?.topology ?? PrimitiveTopology.TRIANGLE_LIST,
+        cullFace: desc?.cullFace ?? CullMode.BACK,
+        frontFace: desc?.frontFace ?? FrontFace.CCW,
+    };
+}

package/src/core/rendering/texture/TextureDescriptorUtilities.ts

@@ -0,0 +1,28 @@
+import {type ITextureDescriptor, TextureFormat, TextureUsage} from "../../../api/index.ts";
+
+/**
+ * A texture descriptor with all defaults applied. Only `data`, `blockSize` and `preferredColorSpace` stay optional.
+ * @internal
+ */
+export type ResolvedTextureDescriptor =
+    Required<Omit<ITextureDescriptor, "data" | "blockSize" | "preferredColorSpace">> & Pick<ITextureDescriptor, "data" | "blockSize" | "preferredColorSpace">;
+
+/**
+ * Fills in the defaults for every missing field of a texture descriptor.
+ * @param desc The descriptor, possibly partial or missing.
+ * @returns A new descriptor with the defaults applied.
+ * @internal
+ */
+export function resolveTextureDescriptor(desc?: ITextureDescriptor): ResolvedTextureDescriptor {
+    return {
+        width: desc?.width ?? 0,
+        height: desc?.height ?? 0,
+        textureFormat: desc?.textureFormat ?? TextureFormat.UNDEFINED,
+        textureUsage: desc?.textureUsage ?? (TextureUsage.TEXTURE_BINDING | TextureUsage.COPY_DST),
+        label: desc?.label ?? null,
+        data: desc?.data,
+        generateMipmaps: desc?.generateMipmaps ?? false,
+        blockSize: desc?.blockSize,
+        preferredColorSpace: desc?.preferredColorSpace,
+    };
+}

package/src/core/rendering/texture/texture.ts

@@ -1,12 +1,12 @@
 import {
     type ITexture2D, type ITextureView,
     State,
-    type TextureDescriptor,
     type TextureFormat,
     TextureUsage,
     TextureViewDescriptor
 } from "../../../api/index.ts";
 import {vec2} from "gl-matrix";
+import type {ResolvedTextureDescriptor} from "./TextureDescriptorUtilities.ts";
 
 /**
  * The ATexture2D class is an abstract base class that implements the ITexture2D interface. It provides common properties and a constructor for initializing a 2D texture, but it does not implement the actual texture creation and management logic, which must be provided by subclasses that extend this base class.
@@ -30,7 +30,7 @@ export abstract class ATexture2D implements ITexture2D {
      * @param descriptor - The texture descriptor.
      */
     protected constructor(
-        descriptor: TextureDescriptor,
+        descriptor: ResolvedTextureDescriptor,
     ) {
 
         if (!descriptor.textureFormat) {

package/src/main.ts

@@ -11,7 +11,7 @@ import {
   type ITexture2D,
   Rect,
   SamplerDescriptor,
-  SamplerFilter, TextureDescriptor, TextureFormat
+  SamplerFilter, type ITextureDescriptor, TextureFormat
 } from "./api/index.ts";
 
 document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
@@ -46,9 +46,10 @@ let sampler: ISampler;
 framework.addOnLoadContentListener(async () =>
 {
 
-  const texDesc = new TextureDescriptor();
-  texDesc.generateMipmaps = true;
-  texDesc.textureFormat = TextureFormat.RGBA_8_UNORM;
+  const texDesc: ITextureDescriptor = {
+    generateMipmaps: true,
+    textureFormat: TextureFormat.RGBA_8_UNORM,
+  };
 
   tex = await framework.content.loadTexture2DAsync("/assets/test.png", texDesc);
   tex2 = await framework.content.loadTexture2DAsync("/assets/cat.jpg", texDesc);

package/src/webgl/WebGlGraphicsDevice.ts

@@ -15,7 +15,7 @@ import {
     type ISampler,
     type ISwapChain,
     type IWindowManager,
-    PrimitiveStateDescriptor,
+    type IPrimitiveStateDescriptor,
     RenderPassDescriptor,
     SwapChainDescriptor
 } from "../api/index.ts";
@@ -125,8 +125,7 @@ export class WebGlGraphicsDevice extends AGraphicsDevice {
     }
 
     /** @inheritdoc */
-    public createPrimitiveState(descriptor?: PrimitiveStateDescriptor): IPrimitiveState {
-        descriptor = descriptor ?? new PrimitiveStateDescriptor();
+    public createPrimitiveState(descriptor?: IPrimitiveStateDescriptor): IPrimitiveState {
         return new WebGlPrimitiveState(this._gl, descriptor);
     }
 }

package/src/webgl/lights/WebGlLightsBuffer.ts

@@ -11,6 +11,9 @@ import {
     type LightsBufferDescriptor,
     DEFAULT_DIRECTIONAL_LIGHTS_COUNT,
 } from "../../api/index.ts";
+import {vec3} from "gl-matrix";
+
+const _v = vec3.create();
 
 /**
  * The WebGL lights buffer. Owns a std140 uniform buffer for the `LightsBuffer` block.
@@ -191,10 +194,15 @@ export class WebGlLightsBuffer implements LightsBuffer {
             this._writeColor(offset, light?.color, light?.intensity ?? 0);
             this._data[offset + 3] = 0;
 
-            // vec3 direction
-            this._data[offset + 4] = light ? light.direction[0] : 0;
-            this._data[offset + 5] = light ? light.direction[1] : 0;
-            this._data[offset + 6] = light ? light.direction[2] : 0;
+            // vec3 direction (world space, from the transform)
+            if (light) {
+                light.getDirection(_v);
+            } else {
+                vec3.zero(_v);
+            }
+            this._data[offset + 4] = _v[0];
+            this._data[offset + 5] = _v[1];
+            this._data[offset + 6] = _v[2];
             this._data[offset + 7] = 0;
         }
 
@@ -209,10 +217,15 @@ export class WebGlLightsBuffer implements LightsBuffer {
             // An empty slot keeps constant at 1 so the shader never divides by zero.
             this._data[offset + 3] = light ? light.constant : 1;
 
-            // vec3 position, float linear
-            this._data[offset + 4] = light ? light.position[0] : 0;
-            this._data[offset + 5] = light ? light.position[1] : 0;
-            this._data[offset + 6] = light ? light.position[2] : 0;
+            // vec3 position (world space, from the transform), float linear
+            if (light) {
+                light.getPosition(_v);
+            } else {
+                vec3.zero(_v);
+            }
+            this._data[offset + 4] = _v[0];
+            this._data[offset + 5] = _v[1];
+            this._data[offset + 6] = _v[2];
             this._data[offset + 7] = light ? light.linear : 0;
 
             // float quadratic, then padding to the 16-byte struct size

package/src/webgl/primitive/WebGlPrimitiveState.ts

@@ -2,9 +2,10 @@ import {
     CullMode,
     type FrontFace,
     type IPrimitiveState,
-    type PrimitiveStateDescriptor,
+    type IPrimitiveStateDescriptor,
     type PrimitiveTopology
 } from "../../api/index.ts";
+import {resolvePrimitiveStateDescriptor} from "../../core/rendering/primitive/PrimitiveStateDescriptorUtilities.ts";
 import { WebGlConverter } from "../utilities/WebGlConverter.ts";
 
 /**
@@ -19,12 +20,13 @@ export class WebGlPrimitiveState implements IPrimitiveState {
     /**
      * The constructor.
      * @param _gl The WebGL2 Rendering Context.
-     * @param descriptor The descriptor of the primitive state.
+     * @param descriptor The descriptor of the primitive state; missing fields use the defaults.
      */
-    public constructor(_gl: WebGL2RenderingContext, descriptor: PrimitiveStateDescriptor) {
-        this.topology = descriptor.topology;
-        this.cullFace = descriptor.cullFace;
-        this.frontFace = descriptor.frontFace;
+    public constructor(_gl: WebGL2RenderingContext, descriptor?: IPrimitiveStateDescriptor) {
+        const resolved = resolvePrimitiveStateDescriptor(descriptor);
+        this.topology = resolved.topology;
+        this.cullFace = resolved.cullFace;
+        this.frontFace = resolved.frontFace;
 
         this._cullingEnabled = this.cullFace != CullMode.NONE;
 

package/src/webgl/render-pipelines/WebGlMainRenderTargetRenderPipeline.ts

@@ -13,6 +13,7 @@ import {
     type ITexture2D,
     TextureFormat
 } from "../../api/index.ts";
+import {ColorSpace} from "../../api/rendering/enums.ts";
 
 /**
  * The WebGL implementation of the main render target render pipeline.
@@ -24,6 +25,7 @@ export class WebGlMainRenderTargetRenderPipeline extends AWebGlRenderPipeline im
     private _mainRenderTarget: WebGlTexture2D = null!;
 
     private _colorConversionUniformLocation: WebGLUniformLocation = null!;
+    /** The shader's `u_colorConversion`: 1 encodes linear to sRGB on output, 0 passes through. */
     private _colorSpaceValue = 0;
 
     /**
@@ -40,6 +42,18 @@ export class WebGlMainRenderTargetRenderPipeline extends AWebGlRenderPipeline im
         }
     }
 
+    /**
+     * The color space. With SRGB the main render target is sRGB (sampled back as linear) and the shader
+     * encodes to sRGB for the screen; with LINEAR the values are passed through. Takes effect on the next frame.
+     */
+    public get colorSpace(): ColorSpace {
+        return this._colorSpaceValue == 1 ? ColorSpace.SRGB : ColorSpace.LINEAR;
+    }
+
+    public set colorSpace(value: ColorSpace) {
+        this._colorSpaceValue = value == ColorSpace.SRGB ? 1 : 0;
+    }
+
     /** @inheritDoc */
     public readonly geometryFormat = GeometryFormat.POS3_COLOR4_TEXTURECOORDS2;
 

package/src/webgl/texture/WebGlTexture2D.ts

@@ -1,6 +1,5 @@
 import {WebGlUtilities} from "../utilities/WebGlUtilities.ts";
 import {
-    TextureDescriptor,
     type IFramework, State,
     type ITextureView,
     type TextureViewDescriptor, TextureUtilities
@@ -8,6 +7,7 @@ import {
 import type {WebGlGraphicsDevice} from "../WebGlGraphicsDevice.ts";
 import {ATexture2D} from "../../core/rendering/texture/texture.ts";
 import {vec2} from "gl-matrix";
+import {type ResolvedTextureDescriptor, resolveTextureDescriptor} from "../../core/rendering/texture/TextureDescriptorUtilities.ts";
 
 /**
  * The WebGL implementation of ITexture2D.
@@ -25,7 +25,7 @@ export class WebGlTexture2D extends ATexture2D {
      */
     constructor(
         private readonly _framework: IFramework,
-        textureDescriptor: TextureDescriptor
+        textureDescriptor: ResolvedTextureDescriptor
     ) {
         super(textureDescriptor);
         this._graphicsDevice = this._framework.renderer.graphicsDevice as WebGlGraphicsDevice;
@@ -121,12 +121,13 @@ export class WebGlTexture2D extends ATexture2D {
         let texture = WebGlTexture2D._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.label = "RisDefaultFilledTexture";
+            const desc = resolveTextureDescriptor({
+                width: 1,
+                height: 1,
+                data: [new Uint8Array([255, 255, 255, 255])],
+                textureFormat: framework.renderer.preferredTextureFormat,
+                label: "RisDefaultFilledTexture",
+            });
 
             texture = new WebGlTexture2D(framework, desc);
             texture.initialize();

package/src/webgl/texture/WebGlTextureFactory.ts

@@ -2,8 +2,8 @@ import {
     Color,
     type IFramework,
     type ITexture2D,
+    type ITextureDescriptor,
     type ITextureFactory,
-    TextureDescriptor,
     TextureFormat,
     TextureUsage,
     TextureUtilities
@@ -11,6 +11,8 @@ import {
 import {WebGlTexture2D} from "./WebGlTexture2D.ts";
 import {type IKtx2Texture, KtxTranscodeFlags, KtxTranscodeFormat, VkFormat} from "ris-ktx2";
 import {vec2} from "gl-matrix";
+import {ColorSpace} from "../../api/rendering/enums.ts";
+import {resolveTextureDescriptor} from "../../core/rendering/texture/TextureDescriptorUtilities.ts";
 
 export class WebGlTextureFactory implements ITextureFactory {
 
@@ -22,51 +24,57 @@ export class WebGlTextureFactory implements ITextureFactory {
     }
 
     /** @inheritDoc */
-    public createFromKtx2(ktxTexture: IKtx2Texture, descriptor?: TextureDescriptor): ITexture2D {
-        descriptor = descriptor ?? new TextureDescriptor();
+    public createFromKtx2(ktxTexture: IKtx2Texture, descriptor?: ITextureDescriptor): ITexture2D {
+        const desc = resolveTextureDescriptor(descriptor);
         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;
+        let textureFormat = desc.textureFormat;
         const gpuFeatures = this._framework.graphicsDevice.features;
 
+        // Textures always adapt to the framework's preferred color space, unless user defined it's preferred.
+        const preferSrgb = (descriptor?.preferredColorSpace ?? this._framework.renderer.colorSpace) == ColorSpace.SRGB;
+        // An explicit texture format overrides both color space preferences.
+        const userSpecifiedTextureFormat = desc.textureFormat != TextureFormat.UNDEFINED;
+
         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(desc.textureFormat == TextureFormat.UNDEFINED)
             {
                 // BC7 needs BPTC (supportsTextureCompressionBC), BC3 needs S3TC.
                 if(gpuFeatures.supportsTextureCompressionBC)
                 {
                     transcodeFormat = KtxTranscodeFormat.BC7_RGBA;
-                    textureFormat = TextureFormat.BC7_RGBA_UNORM;
+                    textureFormat = preferSrgb ? TextureFormat.BC7_RGBA_SRGB : TextureFormat.BC7_RGBA_UNORM;
                 }
                 else if(gpuFeatures.supportsTextureCompressionASTC)
                 {
                     transcodeFormat = KtxTranscodeFormat.ASTC_4X4_RGBA;
-                    textureFormat = TextureFormat.ASTC_4X4_RGBA_UNORM
+                    textureFormat = preferSrgb ? TextureFormat.ASTC_4X4_RGBA_SRGB : TextureFormat.ASTC_4X4_RGBA_UNORM;
                 }
                 else if(gpuFeatures.supportsTextureCompressionS3TC)
                 {
                     transcodeFormat = KtxTranscodeFormat.BC3_RGBA;
-                    textureFormat = TextureFormat.BC3_RGBA_UNORM;
+                    textureFormat = preferSrgb ? TextureFormat.BC3_RGBA_SRGB : TextureFormat.BC3_RGBA_UNORM;
                 }
                 else if(gpuFeatures.supportsTextureCompressionETC2)
                 {
                     transcodeFormat = KtxTranscodeFormat.ETC2_RGBA;
-                    textureFormat = TextureFormat.ETC2_RGBA8_UNORM;
+                    textureFormat = preferSrgb ? TextureFormat.ETC2_RGBA8_SRGB : TextureFormat.ETC2_RGBA8_UNORM;
                 }
                 else if(gpuFeatures.supportsTextureCompressionPVRTC)
                 {
                     transcodeFormat = KtxTranscodeFormat.PVRTC1_4_RGBA;
+                    // Does not have SRGB equivalent.
                     textureFormat = TextureFormat.PVRTC_4BPPV1_RGBA;
                 }
                 else
                 {
                     transcodeFormat = KtxTranscodeFormat.RGBA32;
-                    textureFormat = TextureFormat.RGBA_8_UNORM;
+                    textureFormat = preferSrgb ? TextureFormat.RGBA_8_UNORM_SRGB : TextureFormat.RGBA_8_UNORM;
                 }
             }
             else
@@ -75,21 +83,24 @@ export class WebGlTextureFactory implements ITextureFactory {
             }
 
             ktxTexture.transcodeBasis(transcodeFormat, KtxTranscodeFlags.HIGH_QUALITY);
-
-            // After transcoding, libktx reports the sRGB vkFormat when the file's DFD transfer function is sRGB.
-            if (descriptor.textureFormat == TextureFormat.UNDEFINED && WebGlTextureFactory._isSrgbVkFormat(ktxTexture.vkFormat))
-            {
-                textureFormat = TextureUtilities.toSrgbFormat(textureFormat);
-            }
         }
         else {
-            // No transcoding path, the vkFormat already says linear or sRGB.
+            // No transcoding path: map the vkFormat, then switch to the preferred color space variant.
             textureFormat = TextureUtilities.convertVkFormatToTextureFormat(vkFormat);
-        }
 
-        textureFormat = this._ensureSrgbSupported(textureFormat, ktxTexture.filePath);
+            if (userSpecifiedTextureFormat) {
+                // The data can only be reinterpreted as the file's format or its sRGB/linear variant.
+                textureFormat = TextureUtilities.resolveExplicitFormat(textureFormat, desc.textureFormat);
+            } else {
+                if (preferSrgb && !TextureUtilities.isSrgbFormat(textureFormat)) {
+                    textureFormat = TextureUtilities.convertToSrgbVariant(textureFormat);
+                } else if (!preferSrgb && TextureUtilities.isSrgbFormat(textureFormat)) {
+                    textureFormat = TextureUtilities.convertToLinearVariant(textureFormat);
+                }
+            }
+        }
 
-        const blockSize = TextureUtilities.getBlockSize(textureFormat);
+        const blockSize = ktxTexture.getTextureFormatInfo(ktxTexture.vkFormat);
         if (!blockSize) {
             throw new Error(`Unknown block size for texture format ${textureFormat}.`);
         }
@@ -100,40 +111,20 @@ export class WebGlTextureFactory implements ITextureFactory {
             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(blockSize[0], blockSize[1]);
+        const textureDescriptor = resolveTextureDescriptor({
+            ...desc,
+            width: ktxTexture.width,
+            height: ktxTexture.height,
+            data,
+            textureFormat,
+            blockSize: vec2.fromValues(blockSize.blockWidth, blockSize.blockHeight),
+        });
 
         const texture = new WebGlTexture2D(this._framework, textureDescriptor);
         texture.initialize();
         return texture;
     }
 
-    /** Whether the Vulkan format is an sRGB format. */
-    private static _isSrgbVkFormat(vkFormat: VkFormat): boolean {
-        const name = (VkFormat as unknown as Record<number, string>)[vkFormat];
-        return typeof name === "string" && name.includes("_SRGB");
-    }
-
-    /**
-     * Falls back to the linear variant (with a warning) when the GPU cannot sample the sRGB format.
-     * Only S3TC sRGB (BC1/BC3) has its own WebGL extension; BC7, ETC2 and ASTC sRGB ship with their base extension.
-     */
-    private _ensureSrgbSupported(textureFormat: TextureFormat, source?: string): TextureFormat {
-        const isS3tcSrgb = textureFormat === TextureFormat.BC3_RGBA_SRGB || textureFormat === TextureFormat.BC1_RGB_SRGB;
-        if (isS3tcSrgb && !this._framework.graphicsDevice.features.supportsTextureCompressionS3TCSrgb) {
-            const linear = TextureUtilities.toLinearFormat(textureFormat);
-            console.warn(`sRGB S3TC is not supported (WEBGL_compressed_texture_s3tc_srgb missing); ` +
-                `loading ${source ?? "texture"} as ${linear}. Colours will look washed out.`);
-            return linear;
-        }
-        return textureFormat;
-    }
-
     /** @inheritdoc */
     public create(
         width: number, height: number,
@@ -141,8 +132,12 @@ export class WebGlTextureFactory implements ITextureFactory {
         channels: number = 4,
         label: string | null | undefined = null,
         textureUsage = TextureUsage.COPY_DST | TextureUsage.TEXTURE_BINDING,
-        textureFormat= TextureFormat.RGBA_8_UNORM,
+        textureFormat = TextureFormat.UNDEFINED,
         useMipMaps = false): ITexture2D {
+        if (textureFormat == TextureFormat.UNDEFINED) {
+            textureFormat = this._framework.renderer.preferredTextureFormat;
+        }
+
 
         if (!data) {
             throw new Error("Data must not be null.");
@@ -155,15 +150,16 @@ export class WebGlTextureFactory implements ITextureFactory {
             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 desc = resolveTextureDescriptor({
+            width,
+            height,
+            // @ts-ignore HTMLImageElement is uploaded as-is by WebGlTexture2D.
+            data: [data],
+            textureFormat,
+            textureUsage,
+            generateMipmaps: useMipMaps,
+            label,
+        });
 
         const texture = new WebGlTexture2D(
             this._framework,
@@ -191,13 +187,14 @@ export class WebGlTextureFactory implements ITextureFactory {
             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;
+        const desc = resolveTextureDescriptor({
+            width,
+            height,
+            textureUsage,
+            textureFormat,
+            label,
+            generateMipmaps: useMipmap,
+        });
 
         // Fast path: avoid generating & uploading a big CPU-side buffer when not needed.
         if (!color || color.equals(Color.black())) {

package/src/webgl/utilities/WebGlErrorUtilities.ts

@@ -1,7 +1,8 @@
 export class WebGlErrorUtilities {
 
     private readonly _map: Record<number, string> = {
-        1282: "INVALID_OPERATION"
+        1281: "INVALID_VALUE",
+        1282: "INVALID_OPERATION",
     }
 
     /**
@@ -9,7 +10,7 @@ export class WebGlErrorUtilities {
      * @param error The error code.
      * @return The string of error code.
      */
-    public errorToStr(error: number) : string {
+    public errorToStr(error: number): string {
         return this._map[error] ?? error.toString();
     }
 }

package/src/webgl/utilities/WebGlTextureUtilities.ts

@@ -1,5 +1,5 @@
 import {WebGlConverter} from "./WebGlConverter.ts";
-import {AlignUtilities, TextureFormat} from "../../api/index.ts";
+import { TextureFormat} from "../../api/index.ts";
 import {vec2} from "gl-matrix";
 import {WebGlUtilities} from "./WebGlUtilities.ts";
 
@@ -127,6 +127,9 @@ export class WebGlTextureUtilities {
             gl.texStorage2D(gl.TEXTURE_2D, mipLevels, internalFormat, baseWidth, baseHeight);
         }
 
+        // Texture data might not be aligned to 4. So disable it.
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+
         if (data && data.length > 0) {
 
             let width = baseWidth;
@@ -140,9 +143,9 @@ export class WebGlTextureUtilities {
                     if (useTexStorage) {
                         gl.compressedTexSubImage2D(gl.TEXTURE_2D, i, 0, 0, width, height, internalFormat, mipLevelData, 0);
                     } else {
-                        const alignedWidth = AlignUtilities.align(width, blockSize[0]);
-                        const alignedHeight = AlignUtilities.align(height, blockSize[1]);
-                        gl.compressedTexImage2D(gl.TEXTURE_2D, i, internalFormat, alignedWidth, alignedHeight, 0, mipLevelData, 0);
+                        // const alignedWidth = AlignUtilities.align(width, blockSize[0]);
+                        // const alignedHeight = AlignUtilities.align(height, blockSize[1]);
+                        gl.compressedTexImage2D(gl.TEXTURE_2D, i, internalFormat, width, height, 0, mipLevelData, 0);
                     }
                 } else {
                     throw new Error("unsupported data type");
@@ -153,6 +156,9 @@ export class WebGlTextureUtilities {
             }
         }
 
+        // Restore to default.
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 4);
+
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
 

package/src/webgpu/WebGpuGraphicsDevice.ts

@@ -9,7 +9,7 @@ import {
     type ISampler,
     type ISwapChain,
     type IWindowManager,
-    PrimitiveStateDescriptor,
+    type IPrimitiveStateDescriptor,
     RenderPassDescriptor,
     SwapChainDescriptor,
 } from "../api/index.ts";
@@ -158,8 +158,8 @@ export class WebGpuGraphicsDevice extends AGraphicsDevice {
     }
 
     /** @inheritDoc */
-    public createPrimitiveState(descriptor?: PrimitiveStateDescriptor): IPrimitiveState {
-        return new WebGpuPrimitiveState(descriptor ?? new PrimitiveStateDescriptor());
+    public createPrimitiveState(descriptor?: IPrimitiveStateDescriptor): IPrimitiveState {
+        return new WebGpuPrimitiveState(descriptor);
     }
 
     /** @inheritDoc */