ris-framework 0.1.0-dev.7 → 0.1.0

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

@@ -0,0 +1,100 @@
+import type { ITextureView } from "./ITextureView.ts";
+import type { IContent } from "../../content/IContent.ts";
+import {TextureUsage} from "./TextureUsage.ts";
+import {State} from "../../data/State.ts";
+import {TextureViewDescriptor} from "./TextureViewDescriptor.ts";
+import {TextureFormat} from "./TextureFormat.ts";
+
+/**
+ * The texture 2D interface.
+ */
+export interface ITexture2D extends IContent {
+
+    /**
+     * The default texture view.
+     * It is created with default parameters and can be used when no specific view is needed.
+     */
+    readonly defaultTextureView: ITextureView;
+
+    /**
+     * The texture usage.
+     */
+    readonly textureUsage: TextureUsage;
+
+    /**
+     * The texture format.
+     */
+    readonly textureFormat: TextureFormat;
+
+    /**
+     * The texture view format.
+     * In most cases it will be the same as the texture format, but in some cases it can be different.
+     *
+     * Case where it might differ is if texture is used as depth texture and shader binding.
+     */
+    readonly textureViewFormat: TextureFormat;
+
+    /**
+     * The id of the texture.
+     */
+    readonly id: number;
+
+    /**
+     * The handle of the underlying graphics API texture object.
+     */
+    readonly handle?: any;
+
+    /**
+     * The label.
+     */
+    readonly label: string | null;
+
+    /**
+     * The current state.
+     */
+    readonly textureState: State;
+
+    /**
+     * The size of this texture in RAM.
+     * Note that size if rough approximation as real size can depend on driver implementation.
+     */
+    readonly size: number;
+
+    /**
+     * The width of the texture.
+     */
+    readonly width: number;
+
+    /**
+     * The height of the texture.
+     */
+    readonly height: number;
+
+    /**
+     * The number of mipmap levels.
+     */
+    readonly mipLevels: number;
+
+    /**
+     * The event that is raised when the texture is disposed.
+     */
+    addOnDisposedListener(event: (obj: ITexture2D) => void): void;
+
+    /**
+     * The event that is raised when the texture is disposed.
+     */
+    removeOnDisposedListener(event: (obj: ITexture2D) => void): void;
+
+    /**
+     * Creates the texture view with the specified description.
+     * @param descriptor - The texture view descriptor.
+     * @returns The texture view.
+     */
+    createView(descriptor?: TextureViewDescriptor): ITextureView;
+
+    /**
+     * Initializes the texture.
+     */
+    initialize(): void;
+
+}

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

@@ -0,0 +1,56 @@
+import {Color} from "../../data/Color.ts";
+import {TextureUsage} from "./TextureUsage.ts";
+import {TextureFormat} from "./TextureFormat.ts";
+import type { ITexture2D } from "./ITexture2D.ts";
+import {TextureDescriptor} from "./TextureDescriptor.ts";
+import type {IKtx2Texture} from "ris-ktx2";
+
+/**
+ * The texture factory.
+ */
+export interface ITextureFactory {
+
+    /**
+     * Creates empty texture.
+     * @param width The texture width.
+     * @param height The texture height.
+     * @param defaultColor The optional color.
+     * @param textureUsage Texture usage.
+     * @param textureFormat Texture format.
+     * @param label The label.
+     */
+    createEmpty(
+        width: number, height: number,
+        defaultColor?: Color,
+        textureUsage?: TextureUsage,
+        textureFormat?: TextureFormat,
+        label?: string): ITexture2D;
+
+    /**
+     * Creates a texture from image data.
+     * @param width - The width of the image.
+     * @param height - The height of the image.
+     * @param data - The image data.
+     * @param channels - The number of channels.
+     * @param label - The label.
+     * @param usage - Texture usage. By default, it is COPY_DST | TEXTURE_BINDING.
+     * @param textureFormat - The texture format. By default, it is undefined. If so, the preferred texture format is used.
+     * @param generateMipMaps - Indicates if texture should generate mipmap levels.
+     * @returns The texture.
+     */
+    create(width: number, height: number,
+           data?: number[] | HTMLImageElement | ArrayBufferView,
+           channels?: number,
+           label?: string,
+           usage?: TextureUsage,
+           textureFormat?: TextureFormat,
+           generateMipMaps?: boolean): ITexture2D;
+
+    /**
+     * Create a texture from a KTX2 file.
+     * @param ktxTexture - The ktx2 texture.
+     * @param descriptor - The optional texture descriptor.
+     * @returns The 2D texture.
+     */
+    createFromKtx2(ktxTexture: IKtx2Texture, descriptor?: TextureDescriptor): ITexture2D;
+}

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

@@ -0,0 +1,20 @@
+import {TextureFormat} from "./TextureFormat.ts";
+import type { IDisposable } from "../../core/IDisposable.ts";
+import {TextureViewDimension} from "./TextureViewDimension.ts";
+
+/**
+ * The interface for texture views.
+ */
+export interface ITextureView extends IDisposable {
+
+/**
+ * The texture format of the texture view.
+ */
+  readonly textureFormat: TextureFormat;
+
+/**
+ * The dimension of the texture view.
+ */
+  readonly dimension: TextureViewDimension;
+
+}

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

@@ -0,0 +1,52 @@
+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;
+
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The texture format.
+ */
+export enum TextureFormat {
+    /**
+     * Default value.
+     For unknown texture format.
+     */
+    UNDEFINED = 0,
+
+    /**
+     * Red, green, blue, and alpha channels.
+     * 8-bit integer per channel.
+     * [0, 255] converted to/from float [0, 1] in shader.
+     * */
+    RGBA_8_UNORM = 1,
+
+    /**
+     * Red, green, blue, and alpha channels.
+     * 8-bit integer per channel.
+     * Srgb-color [0, 255] converted to/from linear-color float [0, 1] in shader.
+     */
+    RGBA_8_UNORM_SRGB = 2,
+
+    /**
+     * Depth 24 and stencil 8.
+     */
+    DEPTH_24_STENCIL_8 = 3,
+
+    /**
+     * The depth 32 float.
+     */
+    DEPTH_32_FLOAT = 4,
+
+    RED_32_FLOAT = 5,
+    /**
+     * The 32-bit float format with one red component. It is typeless.
+
+     Valid only for D3D11.
+     */
+    RED_32_TYPELESS = 6,
+    /**
+     * The BC7 compressed format with four 8-bit normalized unsigned integer components in RGBA order.
+     */
+    BC7_RGBA_UNORM = 7,
+    /**
+     * The BC3 compressed format with four 8-bit normalized unsigned integer components in RGBA order.
+     */
+    BC3_RGBA_UNORM = 8,
+    /**
+     * The ETC2 compressed format with four 8-bit normalized unsigned integer components in RGBA order.
+     */
+    ETC2_RGBA8_UNORM = 9,
+    /**
+     * The ASTC 4x4 compressed format with four 8-bit normalized unsigned integer components in RGBA order.
+     */
+    ASTC_4X4_RGBA = 10
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The usage of the texture.
+ */
+export enum TextureUsage {
+/**
+ * Can be used in case where it's not relevant, such as in OpenGL.
+ */
+  NONE = 1,
+/**
+ * Texture can be read from but has no other usages.
+ *     
+ *     Corresponds to WGPU_COPY_SRC in WebGPU.
+ *     
+ *     In D3D11 can be translated to following properties:
+ *     D3D11_BIND_SHADER_RESOURCED3D11_USAGE_STAGINGD3D11_BIND_FLAG_NONE
+ */
+  COPY_SRC = 2,
+/**
+ * The texture is used as a destination for copying.
+ *     To upload data.
+ */
+  COPY_DST = 4,
+/**
+ * The texture is used as a source for texture binding.
+ *     Can be read in shader.
+ *     
+ *     The corresponding binding in D3D11 is D3D11_BIND_SHADER_RESOURCE.
+ */
+  TEXTURE_BINDING = 8,
+/**
+ * The texture is used as a storage texture.
+ *     Can be written in shader.
+ */
+  STORAGE_BINDING = 16,
+/**
+ * The texture is used as a render attachment.
+ *     
+ *     The corresponding binding in D3D11 is D3D11_BIND_RENDER_TARGET.
+ */
+  RENDER_ATTACHMENT = 32
+}

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

@@ -0,0 +1,149 @@
+import {TextureFormat} from "./TextureFormat.ts";
+import {KtxTranscodeFormat, TextureFormatInfo, VkFormat} from "ris-ktx2";
+import {AlignUtilities} from "../../utilities/AlignUtilities.ts";
+
+/**
+ * The texture utilities.
+ */
+export class TextureUtilities {
+
+    private static readonly _compressedTextureFormats = [
+        TextureFormat.ASTC_4X4_RGBA,
+        TextureFormat.BC3_RGBA_UNORM,
+        TextureFormat.BC7_RGBA_UNORM,
+        TextureFormat.ETC2_RGBA8_UNORM
+    ];
+    private static readonly _vkFormatTextureFormat: { [key: number]: number } = {
+        [VkFormat.R8G8B8A8_UNORM]: TextureFormat.RGBA_8_UNORM,
+        [VkFormat.R8G8B8A8_SRGB]: TextureFormat.RGBA_8_UNORM_SRGB,
+        [VkFormat.BC7_UNORM_BLOCK]: TextureFormat.BC7_RGBA_UNORM,
+        [VkFormat.ASTC_4X4_UNORM_BLOCK]: TextureFormat.ASTC_4X4_RGBA,
+        [VkFormat.BC3_UNORM_BLOCK]: TextureFormat.BC3_RGBA_UNORM,
+        [VkFormat.ETC2_R8G8B8A8_UNORM_BLOCK]: TextureFormat.ETC2_RGBA8_UNORM,
+    }
+
+    private static readonly _textureFormatVkFormat: { [key: number]: number } = {
+        [TextureFormat.RGBA_8_UNORM]: VkFormat.R8G8B8A8_UNORM,
+        [TextureFormat.RGBA_8_UNORM_SRGB]: VkFormat.R8G8B8A8_SRGB,
+        [TextureFormat.DEPTH_24_STENCIL_8]: VkFormat.D24_UNORM_S8_UINT,
+        [TextureFormat.BC3_RGBA_UNORM]: VkFormat.BC3_UNORM_BLOCK,
+        [TextureFormat.BC7_RGBA_UNORM]: VkFormat.BC7_UNORM_BLOCK,
+        [TextureFormat.ASTC_4X4_RGBA]: VkFormat.ASTC_4X4_UNORM_BLOCK,
+        [TextureFormat.ETC2_RGBA8_UNORM] : VkFormat.ETC2_R8G8B8A8_UNORM_BLOCK,
+    };
+
+    private static readonly _mapTextureFormatKtxTranscodeFormat: { [key: number]: number } = {
+        [TextureFormat.RGBA_8_UNORM]: KtxTranscodeFormat.RGBA32,
+        [TextureFormat.ASTC_4X4_RGBA]: KtxTranscodeFormat.ASTC_4X4_RGBA,
+        [TextureFormat.BC3_RGBA_UNORM]: KtxTranscodeFormat.BC3_RGBA,
+        [TextureFormat.BC7_RGBA_UNORM]: KtxTranscodeFormat.BC7_RGBA,
+        [TextureFormat.ETC2_RGBA8_UNORM]: KtxTranscodeFormat.ETC2_RGBA,
+    };
+
+    private static readonly _mapKtxTranscodeFormatVkFormat: { [key: number]: number } = {
+        [KtxTranscodeFormat.KTX_TTF_ETC1_RGB]: VkFormat.ETC2_R8G8B8_UNORM_BLOCK,
+        [KtxTranscodeFormat.ETC2_RGBA]: VkFormat.ETC2_R8G8B8A8_UNORM_BLOCK,
+        [KtxTranscodeFormat.KTX_TTF_BC1_RGB]: VkFormat.BC1_RGB_UNORM_BLOCK,
+        [KtxTranscodeFormat.BC3_RGBA]: VkFormat.BC3_UNORM_BLOCK,
+        [KtxTranscodeFormat.KTX_TTF_BC4_R]: VkFormat.BC4_UNORM_BLOCK,
+        [KtxTranscodeFormat.KTX_TTF_BC5_RG]: VkFormat.BC5_UNORM_BLOCK,
+        [KtxTranscodeFormat.BC7_RGBA]: VkFormat.BC7_UNORM_BLOCK,
+        [KtxTranscodeFormat.KTX_TTF_PVRTC1_4_RGB]: VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG,
+        [KtxTranscodeFormat.KTX_TTF_PVRTC1_4_RGBA]: VkFormat.PVRTC1_4BPP_UNORM_BLOCK_IMG,
+        [KtxTranscodeFormat.ASTC_4X4_RGBA]: VkFormat.ASTC_4X4_UNORM_BLOCK,
+        [KtxTranscodeFormat.RGBA32]: VkFormat.R8G8B8A8_UNORM,
+        [KtxTranscodeFormat.KTX_TTF_RGB565]: VkFormat.R5G6B5_UNORM_PACK16,
+        [KtxTranscodeFormat.KTX_TTF_BGR565]: VkFormat.B5G6R5_UNORM_PACK16,
+        [KtxTranscodeFormat.KTX_TTF_RGBA4444]: VkFormat.R4G4B4A4_UNORM_PACK16,
+        [KtxTranscodeFormat.KTX_TTF_PVRTC2_4_RGB]: VkFormat.PVRTC2_4BPP_UNORM_BLOCK_IMG,
+        [KtxTranscodeFormat.KTX_TTF_PVRTC2_4_RGBA]: VkFormat.PVRTC2_4BPP_UNORM_BLOCK_IMG,
+        [KtxTranscodeFormat.KTX_TTF_ETC2_EAC_R11]: VkFormat.EAC_R11_UNORM_BLOCK,
+        [KtxTranscodeFormat.KTX_TTF_ETC2_EAC_RG11]: VkFormat.EAC_R11G11_UNORM_BLOCK,
+    };
+
+    /**
+     * Checks if the given texture format is a compressed texture format.
+     * @param format - The texture format to check.
+     * @returns true if a texture format is a compressed texture format.
+     */
+    public static isCompressedTextureFormat(format: TextureFormat): boolean {
+        return this._compressedTextureFormats.indexOf(format) !== -1;
+    }
+
+    /**
+     * Gets the number of mip levels for the given width and height.
+     *
+     * @param width The width.
+     * @param height The height.
+     * @returns The number of mip levels.
+     */
+    public static mipLevels(width: number, height: number): number {
+        return Math.floor(Math.log2(Math.max(width, height))) + 1;
+    }
+
+    /**
+     * Gets the number of VRAM reserved for a given texture format of a given size.
+     *
+     * @param textureFormat The texture format.
+     * @param width Texture width.
+     * @param height Texture height.
+     * @returns The number of bytes per pixel.
+     */
+    public static getVRamSize(textureFormat: TextureFormat, width: number, height: number): number {
+        let vkFormat = this._textureFormatVkFormat[textureFormat];
+        if (!vkFormat) {
+            throw new Error(`Not implemented: ${textureFormat}`);
+        }
+
+        const texInfo = TextureFormatInfo.fromVkFormat(vkFormat);
+
+        if(texInfo.blockWidth > 1){
+            width = AlignUtilities.align(width, texInfo.blockWidth);
+        }
+        if(texInfo.blockHeight > 1){
+            height = AlignUtilities.align(height, texInfo.blockHeight);
+        }
+
+        return width * height * texInfo.pixelSize;
+    }
+
+    /**
+     * Converts the VkFormat to TextureFormat.
+     * @param vkFormat The VK format.
+     * @returns The texture format.
+     */
+    public static convertVkFormatToTextureFormat(vkFormat: VkFormat): TextureFormat {
+        const format = this._vkFormatTextureFormat[vkFormat];
+        if (!format) {
+            throw new Error(`Not implemented: ${vkFormat}`);
+        }
+        return format;
+    }
+
+    /**
+     * Maps the Texture Format to Ktx Transcode Format.
+     * @param textureFormat The texture format.
+     * @returns The Ktx Transcode Format.
+     */
+    public static convertTextureFormatToKtxTranscodeFormat(textureFormat: TextureFormat): KtxTranscodeFormat {
+        const format = this._mapTextureFormatKtxTranscodeFormat[textureFormat];
+        if (!format) {
+            throw new Error(`Not implemented: ${textureFormat}`);
+        }
+        return format;
+    }
+
+    /**
+     * Converts the Ktx Transcode Format to VkFormat.
+     * @param transcodeFormat The KTX transcode format.
+     * @returns The VkFormat.
+     */
+    public static convertKtxTranscodeFormatToVkFormat(transcodeFormat: KtxTranscodeFormat): VkFormat {
+        const format = this._mapKtxTranscodeFormatVkFormat[transcodeFormat];
+        if (!format) {
+            throw new Error(`Not implemented: ${transcodeFormat}`);
+        }
+        return format;
+    }
+
+}

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

@@ -0,0 +1,25 @@
+/**
+ * The descriptor for the texture view.
+ *     It contains the parameters that are used to create a texture view.
+ */
+import {TextureViewDimension} from "./TextureViewDimension.ts";
+import {TextureFormat} from "./TextureFormat.ts";
+
+export class TextureViewDescriptor {
+
+    /**
+     * The label of the texture view.
+     */
+    public label?: string;
+
+    /**
+     * The dimension of the texture view.
+     *     It is used to specify the type of the texture view and how it will be used in shaders.
+     */
+    public dimension: TextureViewDimension = TextureViewDimension.DIMENSION_2D;
+
+    /**
+     * The texture format of the texture view.
+     */
+    public textureFormat: TextureFormat = TextureFormat.RGBA_8_UNORM;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * The texture view dimension.
+ */
+export enum TextureViewDimension {
+  DIMENSIONUNDEFINED = 0,
+  DIMENSION1D = 1,
+/**
+ * Texture view dimension for 2D textures, including multisampled 2D textures.
+ */
+  DIMENSION_2D = 2,
+  DIMENSION2DARRAY = 3,
+  DIMENSIONCUBE = 4,
+  DIMENSIONCUBEARRAY = 5,
+  DIMENSION3D = 6,
+  DIMENSIONFORCE32 = 2147483647
+}

package/src/api/rendering/texture/_export-texture.ts

@@ -0,0 +1,9 @@
+export * from "./ITexture2D.ts";
+export * from "./TextureUsage.ts";
+export * from "./TextureViewDescriptor.ts";
+export * from "./TextureViewDimension.ts";
+export * from "./TextureFormat.ts";
+export * from "./ITextureView.ts";
+export * from "./ITextureFactory.ts";
+export * from "./TextureDescriptor.ts";
+export * from "./TextureUtilities.ts";

package/src/api/shader/IShaderModule.ts

@@ -0,0 +1,23 @@
+import type { IContent } from "../content/IContent.ts";
+import {ShaderStage} from "./ShaderStage.ts";
+
+/**
+ * The shader module.
+ This is the main interface for shaders.
+ It represents a compiled shader that can be used to create shader pipelines.
+ */
+export interface IShaderModule extends IContent {
+
+    /**
+     * The stages of the shader.
+     * A shader module can contain multiple shader stages, such as vertex shader and fragment shader.
+     */
+    readonly stages: ShaderStage[];
+
+    /**
+     * The native handle of the shader module.
+     * In the case of OpenGL (ES), it is the shader program ID.
+      *In the case of WebGPU, it is the shader module.
+     */
+    readonly nativeHandle?: any;
+}

package/src/api/shader/IShaderModuleLoader.ts

@@ -0,0 +1,15 @@
+import type { IShaderModule } from "./IShaderModule.ts";
+
+/**
+ * The loader for shader modules.
+ */
+export interface IShaderModuleLoader {
+
+/**
+ * Loads a shader module.
+ * @param shaderModuleId - The shader module id.
+ * @returns The shader module.
+ */
+  load(shaderModuleId: string): IShaderModule;
+
+}

package/src/api/shader/ShaderStage.ts

@@ -0,0 +1,9 @@
+/**
+ * The shader stage.
+ */
+export enum ShaderStage {
+  NONE = 0,
+  VERTEX = 1,
+  FRAGMENT = 2,
+  COMPUTE = 4
+}

package/src/api/shader/_export-shader.ts

@@ -0,0 +1,3 @@
+export * from "./ShaderStage.ts";
+export * from "./IShaderModule.ts";
+export * from "./IShaderModuleLoader.ts";

package/src/{core → api}/shader/shader-loader.ts

@@ -1,4 +1,4 @@
-import {RenderingBackend, type ShaderStage} from "ris-framework-api";
+import {RenderingBackend, type ShaderStage} from "../index.ts";
 
 export class ShaderLoader {