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

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

@@ -3,14 +3,16 @@ import {
     type IFramework,
     type ITexture2D,
     type ITextureFactory,
-    TextureDescriptor,
+    type ITextureDescriptor,
     TextureFormat,
     TextureUsage,
     TextureUtilities
 } from "../../api/index.ts"
 import {WebGlTexture2D} from "./WebGlTexture2D.ts";
-import {type IKtx2Texture, KtxTranscodeFlags, KtxTranscodeFormat, VkFormat} from "ris-ktx2";
+import {type IKtx2Texture, KtxDFTransfer, 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,55 @@ 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;
 
+        const srgb = ktxTexture.oetf == KtxDFTransfer.SRGB;
+        const preferSrgb = this._framework.renderer.preferredColorSpace == ColorSpace.SRGB;
+
         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 = srgb ? TextureFormat.BC7_RGBA_SRGB : TextureFormat.BC7_RGBA_UNORM;
                 }
                 else if(gpuFeatures.supportsTextureCompressionASTC)
                 {
                     transcodeFormat = KtxTranscodeFormat.ASTC_4X4_RGBA;
-                    textureFormat = TextureFormat.ASTC_4X4_RGBA_UNORM
+                    textureFormat = srgb ? TextureFormat.ASTC_4X4_RGBA_SRGB : TextureFormat.ASTC_4X4_RGBA_UNORM;
                 }
                 else if(gpuFeatures.supportsTextureCompressionS3TC)
                 {
                     transcodeFormat = KtxTranscodeFormat.BC3_RGBA;
-                    textureFormat = TextureFormat.BC3_RGBA_UNORM;
+                    textureFormat = srgb ? TextureFormat.BC3_RGBA_SRGB : TextureFormat.BC3_RGBA_UNORM;
                 }
                 else if(gpuFeatures.supportsTextureCompressionETC2)
                 {
                     transcodeFormat = KtxTranscodeFormat.ETC2_RGBA;
-                    textureFormat = TextureFormat.ETC2_RGBA8_UNORM;
+                    textureFormat = srgb ? 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 = srgb ? TextureFormat.RGBA_8_UNORM_SRGB : TextureFormat.RGBA_8_UNORM;
                 }
             }
             else
@@ -75,21 +81,19 @@ 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.
             textureFormat = TextureUtilities.convertVkFormatToTextureFormat(vkFormat);
+            if(!srgb && preferSrgb && !TextureUtilities.isSrgbFormat(textureFormat)){
+                textureFormat = TextureUtilities.convertToSrgbVariant(textureFormat);
+            }
+            else if(srgb && !preferSrgb && TextureUtilities.isSrgbFormat(textureFormat)){
+                textureFormat = TextureUtilities.convertToLinearVariant(textureFormat);
+            }
         }
 
-        textureFormat = this._ensureSrgbSupported(textureFormat, ktxTexture.filePath);
-
-        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 +104,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,
@@ -155,15 +139,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 +176,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/webgpu/texture/WebGpuTexture2D.ts

@@ -1,7 +1,6 @@
 import {
     type IFramework,
     State,
-    TextureDescriptor,
     TextureUsage,
     TextureUtilities,
     type ITextureView,
@@ -13,6 +12,7 @@ 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";
+import {type ResolvedTextureDescriptor, resolveTextureDescriptor} from "../../core/rendering/texture/TextureDescriptorUtilities.ts";
 
 /**
  * The WebGPU 2D texture.
@@ -34,7 +34,7 @@ export class WebGpuTexture2D extends ATexture2D {
      * @param descriptor The texture descriptor.
      * @param image An optional image to upload instead of `descriptor.data`.
      */
-    public constructor(framework: IFramework, descriptor: TextureDescriptor, image?: HTMLImageElement) {
+    public constructor(framework: IFramework, descriptor: ResolvedTextureDescriptor, image?: HTMLImageElement) {
         super(descriptor);
         this._graphicsDevice = framework.renderer.graphicsDevice as WebGpuGraphicsDevice;
         this._image = image;
@@ -171,13 +171,14 @@ export class WebGpuTexture2D extends ATexture2D {
     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";
+            const desc = resolveTextureDescriptor({
+                width: 1,
+                height: 1,
+                data: [new Uint8Array([255, 255, 255, 255])],
+                textureFormat: framework.renderer.preferredTextureFormat,
+                textureUsage: TextureUsage.TEXTURE_BINDING | TextureUsage.COPY_DST,
+                label: "RisDefaultFilledTexture",
+            });
             texture = new WebGpuTexture2D(framework, desc);
             texture.initialize();
             WebGpuTexture2D._defaultFilled.set(framework, texture);

package/src/webgpu/texture/WebGpuTextureFactory.ts

@@ -3,12 +3,13 @@ import {
     type IFramework,
     type ITexture2D,
     type ITextureFactory,
-    TextureDescriptor,
+    type ITextureDescriptor,
     TextureFormat,
     TextureUsage,
 } from "../../api/index.ts";
 import type {IKtx2Texture} from "ris-ktx2";
 import {WebGpuTexture2D} from "./WebGpuTexture2D.ts";
+import {resolveTextureDescriptor} from "../../core/rendering/texture/TextureDescriptorUtilities.ts";
 
 /**
  * The WebGPU texture factory.
@@ -24,7 +25,7 @@ export class WebGpuTextureFactory implements ITextureFactory {
     }
 
     /** @inheritDoc */
-    public createFromKtx2(_ktxTexture: IKtx2Texture, _descriptor?: TextureDescriptor): ITexture2D {
+    public createFromKtx2(_ktxTexture: IKtx2Texture, _descriptor?: ITextureDescriptor): ITexture2D {
         throw new Error("createFromKtx2 is not implemented for WebGPU.");
     }
 
@@ -51,13 +52,14 @@ export class WebGpuTextureFactory implements ITextureFactory {
             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;
+        const desc = resolveTextureDescriptor({
+            width,
+            height,
+            textureFormat,
+            textureUsage,
+            generateMipmaps: useMipMaps,
+            label: label ?? null,
+        });
 
         let image: HTMLImageElement | undefined;
         if (typeof HTMLImageElement !== "undefined" && data instanceof HTMLImageElement) {
@@ -90,13 +92,14 @@ export class WebGpuTextureFactory 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,
+        });
 
         // 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)) {

package/dist/api/rendering/texture/TextureDescriptor.d.ts

@@ -1,42 +0,0 @@
-import { TextureFormat } from "./TextureFormat.js";
-import { vec2 } from "gl-matrix";
-/**
- * The texture descriptor.
- */
-export declare class TextureDescriptor {
-    /**
-     * The texture width.
-     */
-    width: number;
-    /**
-     * The texture height.
-     */
-    height: number;
-    /**
-     * The texture format.
-     * By default, it is UNDEFINED.
-     */
-    textureFormat: TextureFormat;
-    /**
-     * The texture usage.
-     * By default, it is TEXTURE_BINDING | COPY_DST.
-     */
-    textureUsage: number;
-    /**
-     * The texture label.
-     */
-    label: string | null;
-    /**
-     * The data per mip level.
-     */
-    data?: Uint8Array[];
-    /**
-     * Should mipmaps be generated.
-     */
-    generateMipmaps: boolean;
-    /**
-     * The block size of a texture, which must be set for compressed textures.
-     */
-    blockSize?: vec2;
-}
-//# sourceMappingURL=TextureDescriptor.d.ts.map

package/dist/api/rendering/texture/TextureDescriptor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"TextureDescriptor.d.ts","sourceRoot":"","sources":["../../../../src/api/rendering/texture/TextureDescriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAE/B;;GAEG;AACH,qBAAa,iBAAiB;IAE1B;;OAEG;IACI,KAAK,EAAE,MAAM,CAAK;IAEzB;;OAEG;IACI,MAAM,EAAE,MAAM,CAAK;IAE1B;;;OAGG;IACI,aAAa,gBAA2B;IAE/C;;;OAGG;IACI,YAAY,SAAwD;IAE3E;;OAEG;IACI,KAAK,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEnC;;OAEG;IACI,IAAI,CAAC,EAAE,UAAU,EAAE,CAAa;IAEvC;;OAEG;IACI,eAAe,UAAS;IAE/B;;OAEG;IACI,SAAS,CAAC,EAAE,IAAI,CAAC;CAE3B"}

package/src/api/rendering/texture/TextureDescriptor.ts

@@ -1,52 +0,0 @@
-import {TextureFormat} from "./TextureFormat.ts";
-import {TextureUsage} from "./TextureUsage.ts";
-import {vec2} from "gl-matrix";
-
-/**
- * The texture descriptor.
- */
-export class TextureDescriptor {
-
-    /**
-     * The texture width.
-     */
-    public width: number = 0;
-
-    /**
-     * The texture height.
-     */
-    public height: number = 0;
-
-    /**
-     * The texture format.
-     * By default, it is UNDEFINED.
-     */
-    public textureFormat = TextureFormat.UNDEFINED;
-
-    /**
-     * The texture usage.
-     * By default, it is TEXTURE_BINDING | COPY_DST.
-     */
-    public textureUsage = TextureUsage.TEXTURE_BINDING | TextureUsage.COPY_DST;
-
-    /**
-     * The texture label.
-     */
-    public label: string | null = null;
-
-    /**
-     * The data per mip level.
-     */
-    public data?: Uint8Array[] = undefined;
-
-    /**
-     * Should mipmaps be generated.
-     */
-    public generateMipmaps = false;
-
-    /**
-     * The block size of a texture, which must be set for compressed textures.
-     */
-    public blockSize?: vec2;
-
-}