ris-framework 0.1.0-dev.7 → 0.1.0-dev.9

package/src/api/rendering/PowerPreference.ts

@@ -0,0 +1,15 @@
+/**
+ * The power preference when it comes to selecting GPU device.
+ * @public
+ */
+export enum PowerPreferenceType {
+
+    /** Browser selects the power preference. */
+    DEFAULT = "default",
+
+    /** The low powered device is preferred. Typically, this would be i-GPU. */
+    LOW_POWER = "low-power",
+
+    /** The high-powered device is preferred. Typically, this would be d-GPU. */
+    HIGH_PERFORMANCE = "high-performance",
+}

package/src/api/rendering/RenderingBackend.ts

@@ -0,0 +1,20 @@
+/**
+ * The renderer type.
+ */
+export enum RenderingBackend {
+
+    /**
+     * If default is set, the renderer will be chosen automatically.
+     */
+    DEFAULT = 0,
+
+    /**
+     * The WebGPU rendering backend.
+     */
+    WEB_GPU = 1,
+
+    /**
+     * The WebGL rendering backend.
+     */
+    WEB_GL = 2,
+}

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

@@ -0,0 +1,6 @@
+export * from "./IGraphicsDevice.ts";
+export * from "./IGraphicsDeviceFeatures.ts";
+export * from "./IRenderer.ts";
+export * from "./RenderingBackend.ts";
+export * from "./IGPUInfo.ts";
+export * from "./PowerPreference.ts";

package/src/api/rendering/blending/IBlendState.ts

@@ -0,0 +1,17 @@
+import type { IDisposable } from "../../core/IDisposable.ts";
+
+/**
+ * The blend state.
+ *     It is created from a blend state descriptor and contains the
+ *     actual blend state that can be applied to the graphics pipeline.
+ */
+export interface IBlendState extends IDisposable {
+
+    /**
+     * The native pointer to the blend state.
+     * This is used internally by the graphics API to apply the blend state to the pipeline.
+     * In some cases it can be null pointer, if API does not have a native representation
+     * of the blend state, but it is still usable and can be applied to the pipeline.
+     */
+    readonly nativePtr: any;
+}

package/src/api/rendering/blending/_export.ts

@@ -0,0 +1 @@
+export * from "./IBlendState.ts";

package/src/api/rendering/buffers/BufferUsage.ts

@@ -0,0 +1,56 @@
+/**
+ * The buffer usage.
+ */
+export enum BufferUsage {
+/**
+ * No buffer usage is defined.
+ */
+  NONE = 0,
+/**
+ * Allow a buffer to be the vertex buffer in a draw operation.
+ *     
+ *     The corresponding binding in WGPU is WGPU_VERTEX.
+ *     The corresponding usage in OpenGL/WebGL is GL_ELEMENT_ARRAY_BUFFER.
+ */
+  VERTEX = 1,
+/**
+ * The buffer is used as an index buffer in a draw operation.
+ */
+  INDEX = 2,
+/**
+ * Allow a buffer to be the uniform buffer in a draw operation.
+ *     
+ *     The corresponding binding in WGPU is WGPU_UNIFORM.
+ */
+  UNIFORM = 4,
+/**
+ * Allow a buffer to be the storage buffer in a draw operation.
+ *     
+ *     In WGPU this will resolve to WGPU_STORAGE.
+ *     
+ *     In OpenGL this will resolve to GL_SHADER_STORAGE_BUFFER.
+ *     
+ *     In D3D11 this will resolve to usage D3D11_USAGE_DEFAULT.
+ *     
+ *     In D3D11 this will resolve to bind flags D3D11_BIND_SHADER_RESOURCE | D3D11_BIND_UNORDERED_ACCESS.
+ *     
+ *     In D3D11 this will resolve to misc flags D3D11_RESOURCE_MISC_BUFFER_STRUCTURED.
+ */
+  STORAGE = 8,
+/**
+ * Buffer is allowed to be read from.
+ *     
+ *     A common use case is copying data from the buffer to the CPU memory.
+ *     
+ *     The corresponding binding in WGPU is WGPU_MAP_READ.
+ */
+  MAP_READ = 16,
+/**
+ * Buffer is used as a destination for copying.
+ *     
+ *     A common use case is writing data to a buffer.
+ *     
+ *     The corresponding binding in WGPU is WGPU_COPY_DST.
+ */
+  COPY_DST = 32
+}

package/src/api/rendering/buffers/IBuffer.ts

@@ -0,0 +1,24 @@
+import {BufferUsage} from "./BufferUsage.ts";
+import type { IDisposable } from "../../core/IDisposable.ts";
+
+/**
+ * The common interface for all buffers.
+ */
+export interface IBuffer extends IDisposable {
+
+/**
+ * The label of the buffer.
+ */
+  readonly label?: string;
+
+/**
+ * Size of the buffer in bytes.
+ */
+  readonly byteSize: number;
+
+  /**
+   * The usage of the buffer.
+   */
+  readonly usage: BufferUsage;
+
+}

package/src/api/rendering/buffers/IBufferFactory.ts

@@ -0,0 +1,38 @@
+import type { IIndexBuffer } from "./IIndexBuffer.ts";
+import {BufferUsage} from "./BufferUsage.ts";
+import type { IUniformBuffer } from "./IUniformBuffer.ts";
+import type { IVertexBuffer } from "./IVertexBuffer.ts";
+
+/**
+ * The buffer factory interface.
+ */
+export interface IBufferFactory {
+
+    /**
+     * Creates a new index buffer and prefills it with data.
+     * @param data - The data to prefill the buffer with.
+     * @param label - The buffer label.
+     * @returns The index buffer.
+     */
+    createIndexBuffer(data: ArrayLike<number>, label?: string): IIndexBuffer;
+
+    /**
+     * Creates a new vertex buffer and prefills it with data.
+     * @param data - The data to prefill the buffer with.
+     * @param vertexStride - The stride of single vertex in bytes.
+     * @param usage - The buffer usage.
+     * @param label - The buffer label.
+     * @returns The vertex buffer.
+     */
+    createVertexBuffer(data: ArrayLike<number>, vertexStride: number, usage?: BufferUsage, label?: string): IVertexBuffer;
+
+    /**
+     * Creates a new uniform buffer.
+     * @param data - The data to fill buffer with.
+     * @param usage - The buffer usage.
+     * @param label - The optional label of the buffer.
+     * @returns The uniform buffer.
+     */
+    createUniformBuffer(data: ArrayLike<number>, usage?: BufferUsage, label?: string): IUniformBuffer;
+
+}

package/src/api/rendering/buffers/IIndexBuffer.ts

@@ -0,0 +1,37 @@
+import type { IBuffer } from "./IBuffer.ts";
+import {IndexBufferType} from "./IndexBufferType.ts";
+
+/**
+ * The index buffer.
+ */
+export interface IIndexBuffer extends IBuffer {
+
+    /**
+     * The type of buffer.
+     */
+    readonly type: IndexBufferType;
+
+    /**
+     * Size of the element.
+     *     Usually 2 or 4 bytes depending on the Type property.
+     */
+    readonly elementByteSize: number;
+
+    /**
+     * The count of indices.
+     */
+    readonly indicesCount: number;
+
+    /**
+     * Initialize the index buffer.
+     * @param data - The data to initialize with.
+     */
+    initialize(data: number[]): void;
+
+    /**
+     * Initialize the index buffer.
+     * @param data - The data to initialize with.
+     */
+    initialize(data: number[]): void;
+
+}

package/src/api/rendering/buffers/IUniformBuffer.ts

@@ -0,0 +1,21 @@
+import type { IBuffer } from "./IBuffer.ts";
+
+/**
+ * Interface for uniform buffer.
+ */
+export interface IUniformBuffer extends IBuffer  {
+
+    /**
+     * Initialize the constant buffer.
+     */
+    initialize(): void;
+
+    /**
+     * Update the constant buffer.
+     * @param data - The data array.
+     * @param offset - Defines where to start buffer write. Must be in bytes.
+     * @param length - Defines how many bytes to write. By default, -1 that means data length is used.
+     */
+    update(data: ArrayLike<number>, offset?: number, length?: number): void;
+
+}

package/src/api/rendering/buffers/IVertexBuffer.ts

@@ -0,0 +1,32 @@
+import type { IBuffer } from "./IBuffer.ts";
+
+/**
+ * Create a new vertex buffer.
+ */
+export interface IVertexBuffer extends IBuffer  {
+
+
+    /**
+     * The number of vertices.
+     */
+    readonly vertexCount: number;
+
+    /**
+     * The byte stride of the buffer.
+     */
+    readonly byteStride: number;
+
+    /**
+     * Initialize the vertex buffer.
+     */
+    initialize(): void;
+
+    /**
+     * Update the vertex buffer.
+     * @param data - The data to be written to buffer.
+     * @param offset - The offset to write data. By default, 0. This is in bytes of the buffer.
+     * @param length - The length to copy. If 0 or less, entire array is copied.
+     */
+    update(data: number[], offset?: number, length?: number): void;
+
+}

package/src/api/rendering/buffers/IVertexBufferLayout.ts

@@ -0,0 +1,27 @@
+import {VertexStepMode} from "./VertexStepMode.ts";
+import {VertexAttribute} from "./VertexAttribute.ts";
+
+/**
+ * The vertex buffer layout.
+ */
+export interface IVertexBufferLayout {
+
+/**
+ * The stride, in bytes, between elements of the vertex buffer.
+ *     This is also known as the "vertex size". It is the size of one vertex in the vertex buffer.
+ */
+  arrayStride: number;
+
+/**
+ * The step mode of the vertex buffer.
+ *     It defines how the vertex buffer is stepped through when rendering.
+ */
+  stepMode: VertexStepMode;
+
+/**
+ * The attributes of the vertex buffer.
+ *     It defines the layout of the vertex buffer, and how the vertex shader will read the vertex data.
+ */
+  attributes: VertexAttribute[];
+
+}

package/src/api/rendering/buffers/IndexBufferType.ts

@@ -0,0 +1,13 @@
+/**
+ * The type of index buffer.
+ */
+export enum IndexBufferType {
+/**
+ * Indices are 2 bytes unsigned integers.
+ */
+  UINT_16 = 0,
+/**
+ * Indices are 4 bytes unsigned integers.
+ */
+  UINT_32 = 1
+}

package/src/api/rendering/buffers/VertexAttribute.ts

@@ -0,0 +1,26 @@
+
+import {VertexFormat} from "../../geometry/VertexFormat.ts";
+
+/**
+ * The vertex attribute class.
+ * A vertex attribute defines a single attribute of a vertex, such as position, normal, color, etc.
+ * It is used to define the layout of the vertex buffer, and how the vertex shader will read the vertex data.
+ */
+export class VertexAttribute {
+
+    /**
+     * The format of the vertex attribute.
+     * It defines the type and size of the attribute, such as float3 for position, float2 for UV, etc.
+     */
+    public format = VertexFormat.FLOAT_32;
+
+    /**
+     * The offset, in bytes, of the vertex attribute from the start of the vertex.
+     */
+    public offset = 0;
+
+    /**
+     * The shader location of the vertex attribute.
+     */
+    public shaderLocation = 0;
+}

package/src/api/rendering/buffers/VertexStepMode.ts

@@ -0,0 +1,13 @@
+/**
+ * The step mode of a buffer layout.
+ */
+export enum VertexStepMode {
+/**
+ * Step per vertex.
+ */
+  VERTEX = 0,
+/**
+ * Step per instance.
+ */
+  INSTANCE = 1
+}

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

@@ -0,0 +1,11 @@
+
+export * from "./BufferUsage.ts";
+export * from "./IBuffer.ts";
+export * from "./IIndexBuffer.ts";
+export * from "./IVertexBuffer.ts";
+export * from "./IVertexBufferLayout.ts";
+export * from "./IBufferFactory.ts";
+export * from "./IndexBufferType.ts";
+export * from "./IUniformBuffer.ts";
+export * from "./VertexAttribute.ts";
+export * from "./VertexStepMode.ts";

package/src/api/rendering/primitive/CullMode.ts

@@ -0,0 +1,17 @@
+/**
+ * The culling mode.
+ */
+export enum CullMode {
+/**
+ * The culling is disabled. Both front and back faces will be rendered.
+ */
+  NONE = 0,
+/**
+ * The back faces will be culled. Only front faces will be rendered.
+ */
+  BACK = 1,
+/**
+ * The front faces will be culled. Only back faces will be rendered.
+ */
+  FRONT = 2
+}

package/src/api/rendering/primitive/FrontFace.ts

@@ -0,0 +1,13 @@
+/**
+ * The front face winding order.
+ */
+export enum FrontFace {
+/**
+ * The clockwise winding order.
+ */
+  CW = 0,
+/**
+ * The counter-clockwise winding order.
+ */
+  CCW = 1
+}

package/src/api/rendering/primitive/IPrimitiveState.ts

@@ -0,0 +1,25 @@
+import {FrontFace} from "./FrontFace.ts";
+import {CullMode} from "./CullMode.ts";
+import {PrimitiveTopology} from "./PrimitiveTopology.ts";
+
+/**
+ * The primitive state.
+ *     Describes the primitive to be rendered and how it should be rendered.
+ */
+export interface IPrimitiveState {
+
+    /**
+     * The topology of the primitive.
+     */
+    readonly topology: PrimitiveTopology;
+
+    /**
+     * The culling mode.
+     */
+    readonly cullFace: CullMode;
+
+    /**
+     * The front face.
+     */
+    readonly frontFace: FrontFace;
+}

package/src/api/rendering/primitive/PrimitiveStateDescriptor.ts

@@ -0,0 +1,27 @@
+import {PrimitiveTopology} from "./PrimitiveTopology.ts";
+import {CullMode} from "./CullMode.ts";
+import {FrontFace} from "./FrontFace.ts";
+
+/**
+ * Describes the state of a primitive.
+ */
+export class PrimitiveStateDescriptor {
+
+    /**
+     * The topology of the primitive.
+     * By default, it is set to TRIANGLE_LIST.
+     */
+    public topology: PrimitiveTopology = PrimitiveTopology.TRIANGLE_LIST;
+
+    /**
+     * The culling mode.
+     * By default, it is set to BACK.
+     */
+    public cullFace: CullMode = CullMode.BACK;
+
+    /**
+     * The front face.
+     * By default, it is set to CCW(counter clock-wise).
+     */
+    public frontFace: FrontFace = FrontFace.CCW;
+}

package/src/api/rendering/primitive/PrimitiveTopology.ts

@@ -0,0 +1,25 @@
+/**
+ * The primitive topology.
+ */
+export enum PrimitiveTopology {
+/**
+ * Each consecutive pair of two vertices defines a line primitive.
+ */
+  LINE_LIST = 0,
+/**
+ * Each vertex after the first defines a line primitive between it and the previous vertex.
+ */
+  LINE_STRIP = 1,
+/**
+ * Each vertex defines a point primitive.
+ */
+  POINT_LIST = 2,
+/**
+ * Each consecutive triplet of three vertices defines a triangle primitive.
+ */
+  TRIANGLE_LIST = 3,
+/**
+ * Each vertex after the first two defines a triangle primitive between it and the previous two vertices.
+ */
+  TRIANGLE_STRIP = 4
+}

package/src/api/rendering/primitive/_export.ts

@@ -0,0 +1,5 @@
+export * from "./CullMode.ts"
+export * from "./FrontFace.ts"
+export * from "./IPrimitiveState.ts"
+export * from "./PrimitiveTopology.ts"
+export * from "./PrimitiveStateDescriptor.ts"

package/src/api/rendering/render-pipelines/IInspectTextureMipsRenderPipeline.ts

@@ -0,0 +1,38 @@
+import type { ITexture2D } from "../texture/ITexture2D.ts";
+import type { ISampler } from "../sampler/ISampler.ts";
+import type { IUniformBuffer } from "../buffers/IUniformBuffer.ts";
+import type { IRenderPipeline } from "./IRenderPipeline.ts";
+
+/**
+ * The pipeline for inspecting texture mip levels.
+ */
+export interface IInspectTextureMipsRenderPipeline extends IRenderPipeline {
+
+    /**
+     * The diffuse texture.
+     */
+    spriteTexture: ITexture2D;
+
+    /**
+     * The texture sampler.
+     */
+    textureSampler?: ISampler;
+
+    /**
+     * The projection view uniform buffer.
+     * Contains a single matrix representing the projection view matrix.
+     */
+    projectionViewBuffer: IUniformBuffer;
+
+    /**
+     * The world matrix uniform buffer.
+     * Contains a single matrix representing the world matrix.
+     */
+    modelBuffer: IUniformBuffer;
+
+    /**
+     * The buffer of texture constants.
+     * For now, it is just a single float value representing the mip level.
+     */
+    textureConstantsBuffer: IUniformBuffer;
+}

package/src/api/rendering/render-pipelines/IMainRenderTargetRenderPipeline.ts

@@ -0,0 +1,21 @@
+import type { IRenderPipeline } from "./IRenderPipeline.ts";
+import type { ITexture2D } from "../texture/ITexture2D.ts";
+
+/**
+ * Pipeline that is used in renderer as
+ * a pass that renders from the main frame buffer to the screen.
+ */
+export interface IMainRenderTargetRenderPipeline extends IRenderPipeline {
+
+    /**
+     * The texture that is used as a main frame buffer.
+     * The pipeline will render this texture to the screen.
+     */
+    readonly mainRenderTarget: ITexture2D;
+
+    /**
+     * Render to the screen.
+     */
+    render(): void;
+
+}

package/src/api/rendering/render-pipelines/IRenderPipeline.ts

@@ -0,0 +1,47 @@
+import type { IBlendState } from "../blending/IBlendState.ts";
+import type { IDisposable } from "../../core/IDisposable.ts";
+import type { IPrimitiveState } from "../primitive/IPrimitiveState.ts";
+import type { IVertexBufferLayout } from "../buffers/IVertexBufferLayout.ts";
+import type { IIndexBuffer } from "../buffers/IIndexBuffer.ts";
+import type { IVertexBuffer } from "../buffers/IVertexBuffer.ts";
+
+/**
+ * The render pipeline interface.
+ * Render pipelines are responsible for defining the rendering process, including the shaders,
+ * the vertex buffer layout, the render targets, and the draw calls.
+ */
+export interface IRenderPipeline extends IDisposable {
+
+    /**
+     * The blend state of the render pipeline.
+     */
+    readonly blendState: IBlendState;
+
+    /**
+     * The primitive state of the render pipeline.
+     */
+    readonly primitiveState: IPrimitiveState;
+
+    /**
+     * The vertex buffer layout of the render pipeline.
+     */
+    readonly vertexBufferLayouts: IVertexBufferLayout[];
+
+    /**
+     * Initializes the render pipeline.
+     *     This method is called by the renderer when the pipeline is added to the renderer.
+     */
+    initialize(): void;
+
+    /**
+     * Draw the pipeline.
+     * @param vertexBuffer - The vertex buffer.
+     * @param indexBuffer - The index buffer.
+     * @param indicesCount - The number of indices to draw. If -1 draws all indices.
+     * @param indicesOffset - Indices offset. By default, 0 for no offset.
+     */
+    render(vertexBuffer: IVertexBuffer, indexBuffer: IIndexBuffer,
+           indicesCount?: number, indicesOffset?: number): void;
+
+
+}

package/src/api/rendering/render-pipelines/IRenderPipelineFactory.ts

@@ -0,0 +1,52 @@
+import type { ITexture2D } from "../texture/ITexture2D.ts";
+import type { IMainRenderTargetRenderPipeline } from "./IMainRenderTargetRenderPipeline.ts";
+import type { IUniformBuffer } from "../buffers/IUniformBuffer.ts";
+import type { ISpriteRenderPipeline } from "./ISpriteRenderPipeline.ts";
+import type { IInspectTextureMipsRenderPipeline } from "./IInspectTextureMipsRenderPipeline.ts";
+import type { IUnlitRenderPipeline } from "./IUnlitRenderPipeline.ts";
+import type { IPrimitiveState } from "../primitive/IPrimitiveState.ts";
+
+/**
+ * The pipeline factory.
+ */
+export interface IRenderPipelineFactory {
+
+    /**
+     * Creates the main render target pipeline.
+     * @param mainFrameBuffer - The texture acting as a main frame buffer.
+     * @returns The main render target render pipeline.
+     */
+    createMainFrameBufferPipeline(mainFrameBuffer: ITexture2D): IMainRenderTargetRenderPipeline;
+
+    /**
+     * Creates the sprite render pipeline.
+     * @param projectionViewBuffer - The projection view buffer.
+     * @returns The sprite render pipeline.
+     */
+    createSpriteRenderPipeline(projectionViewBuffer: IUniformBuffer): ISpriteRenderPipeline;
+
+    /**
+     * Creates the inspect texture mip level pipeline.
+     * @param projectionViewBuffer - The projection view buffer.
+     * @param modelBuffer - The world buffer.
+     * @param textureConstantsBuffer - The texture constants buffer.
+     * @returns The inspect texture mips render pipeline.
+     */
+    createInspectTextureMipsRenderPipeline(projectionViewBuffer: IUniformBuffer, modelBuffer: IUniformBuffer, textureConstantsBuffer: IUniformBuffer): IInspectTextureMipsRenderPipeline;
+
+
+    /**
+     * Creates the unlit render pipeline.
+     * @param projectionViewBuffer - The projection view buffer.
+     * @param modelBuffer - The world buffer.
+     * @param materialBuffer - The material buffer.
+     * @param primitiveState - The primitive state.
+     * @returns The unlit render pipeline.
+     */
+    createUnlitRenderPipeline(projectionViewBuffer: IUniformBuffer,
+                              modelBuffer: IUniformBuffer,
+                              materialBuffer: IUniformBuffer,
+                              primitiveState?: IPrimitiveState
+                              ): IUnlitRenderPipeline;
+
+}