ris-framework 0.1.0-dev.7 → 0.1.0

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

@@ -0,0 +1,25 @@
+import type { IUniformBuffer } from "../buffers/IUniformBuffer.ts";
+import type { ITexture2D } from "../texture/ITexture2D.ts";
+import type { ISampler } from "../sampler/ISampler.ts";
+import type { IRenderPipeline } from "./IRenderPipeline.ts";
+
+/**
+ * The pipeline for sprite rendering.
+ */
+export interface ISpriteRenderPipeline extends IRenderPipeline {
+
+    /**
+     * The diffuse texture.
+     */
+    spriteTexture: ITexture2D;
+
+    /**
+     * The sampler.
+     */
+    textureSampler?: ISampler;
+
+    /**
+     * The projection view uniform buffer.
+     */
+    projectionViewBuffer: IUniformBuffer;
+}

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

@@ -0,0 +1,38 @@
+import type { ITexture2D } from "../texture/ITexture2D.ts";
+import type { ISampler } from "../sampler/ISampler.ts";
+import type { IRenderPipeline } from "./IRenderPipeline.ts";
+import type { IUniformBuffer } from "../buffers/IUniformBuffer.ts";
+
+/**
+ * The unlit render pipeline.
+ */
+export interface IUnlitRenderPipeline extends IRenderPipeline {
+
+    /**
+     * The diffuse texture.
+     */
+    diffuseTexture: ITexture2D;
+
+    /**
+     * The texture sampler.
+     */
+    diffuseTextureSampler?: 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 material buffer that contains the material properties.
+     * - vec4 diffuseColor
+     */
+    materialBuffer: IUniformBuffer;
+}

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

@@ -0,0 +1,6 @@
+export * from "./ISpriteRenderPipeline.ts";
+export * from "./IMainRenderTargetRenderPipeline.ts";
+export * from "./IRenderPipelineFactory.ts";
+export * from "./IRenderPipeline.ts";
+export * from "./IInspectTextureMipsRenderPipeline.ts"
+export * from "./IUnlitRenderPipeline.ts"

package/src/{core/renderer → api/rendering}/renderer-interface.ts

@@ -1,27 +1,33 @@
 import { vec2 } from "gl-matrix";
-import { TextureSamplerFilteringPreset } from "../rendering/enums";
+import { TextureSamplerFilteringPreset } from "../../core/rendering/enums.ts";
 import type {RenderingLimits} from "./rendering-limits.ts";
-import type {Color, IGraphicsDevice, IRenderer} from "ris-framework-api";
-import type {TextureFormat} from "ris-framework-api";
+import type {Color, IGraphicsDevice, IRenderer} from "../index.ts";
+import type {TextureFormat} from "../index.ts";
+import {PowerPreferenceType} from "./PowerPreference.ts";
 
 export const RenderConfigurationSymbol = Symbol("RenderConfiguration");
 
 /**
  * The configuration for the renderer. This is used to initialize the renderer.
+ * @internal
  */
-export class RenderConfiguration {
+export interface IRendererConfiguration {
 
-    /**
-     * The size of the main frame buffer. This is used to initialize the main render target.
-     */
-    backBufferSize: vec2 = vec2.fromValues(800, 600);
+    /**The size of the main frame buffer. */
+    backBufferSize: vec2;
+
+    /** Should back buffer use alpha. */
+    alpha: boolean;
+
+    /** The preference when it comes to selecting GPU device. Only makes sense to set on multi-GPU devices. */
+    powerPreference: PowerPreferenceType;
 
     /**
      * The preset for texture sampler filtering.
      *  This is used to configure the default texture sampler in the graphics device. 
      * The default texture sampler is used when a texture is sampled without a specific sampler being bound.
      */
-    textureFiltering = TextureSamplerFilteringPreset.BILINEAR;
+    textureFiltering: TextureSamplerFilteringPreset;
 }
 
 /**

package/src/api/rendering/renderpass/IRenderPass.ts

@@ -0,0 +1,18 @@
+import type { IDisposable } from "../../core/IDisposable.ts";
+
+/**
+ * The render pass interface.
+ */
+export interface IRenderPass extends IDisposable {
+
+/**
+ * Begins the render pass. This will set up the necessary state and resources for the render pass to be executed.
+ */
+  beginPass(): void;
+
+/**
+ * Ends the render pass. This will finalize the render pass and submit the recorded commands for execution.
+ */
+  endPass(): void;
+
+}

package/src/api/rendering/renderpass/LoadAction.ts

@@ -0,0 +1,32 @@
+/**
+ * Specifies the action to take with the attachment contents at the beginning of a render pass.
+ */
+export enum LoadAction {
+/**
+ * The attachment is cleared to a specified clear value at the start of the render pass.
+ *     
+ *     On tile-based renderers (especially mobile),  is usually much cheaper than 
+ *     because it avoids loading data from main memory into tile memory.
+ *     
+ *     Recommended when the previous contents don't matter (e.g. rendering a skybox, full-screen quad, or when you know you'll overwrite everything).
+ *     
+ *     Corresponds to WebGPU clear operation.
+ */
+  CLEAR = 0,
+/**
+ * The existing contents of the attachment are loaded into the render pass.
+ *     
+ *     Corresponds to WebGPU load operation.
+ */
+  LOAD = 1,
+/**
+ * The attachment contents at the start of the render pass are undefined.
+ *     This is the fastest possible load operation if you guarantee that **every pixel** will be written before it is read.
+ *     Warning: Reading from any pixel (including via blending) before writing to it results in undefined behavior.
+ *     
+ *     Backends that do not natively support "don't care" will fall back to another load operation (implementation-defined).
+ *     
+ *     Corresponds to WebGPU undefined / discard (historically "dontcare").
+ */
+  UNDEFINED = 2
+}

package/src/api/rendering/renderpass/RenderPassColorAttachment.ts

@@ -0,0 +1,61 @@
+import type { ISwapChain } from "../swapchain/ISwapChain.ts";
+import {Color} from "../../data/Color.ts";
+import type { ITexture2D } from "../texture/ITexture2D.ts";
+import type { ITextureView } from "../texture/ITextureView.ts";
+import {StoreAction} from "./StoreAction.ts";
+import {LoadAction} from "./LoadAction.ts";
+
+/**
+ * Color attachment for a render pass.
+ */
+export class RenderPassColorAttachment {
+
+    /**
+     * The swap chain to which the render pass will write for this attachment.
+     */
+    public swapChain?: ISwapChain;
+
+    /**
+     * The texture to which the render pass will write for this attachment.
+     * Must be defined if view is not defined.
+     */
+    public texture?: ITexture2D;
+
+    /**
+     * The view into  to which the render pass will write for this attachment.
+     * Must be defined if texture is not defined.
+     */
+    public view?: ITextureView;
+
+    /**
+     * Whether data will be written to through this attachment.
+     * Note that resolve textures (if specified) are always written to, regardless of this setting.
+     * By default, it is set to STORE, which means that the data will be stored in memory after the render pass and can be read later.
+     */
+    public storeAction: StoreAction = StoreAction.STORE;
+
+    /**
+     * How data should be read through this attachment.
+     *  By default, it is set to CLEAR, which means that the data will be cleared at the beginning of the render pass.
+     */
+    public loadAction: LoadAction = LoadAction.CLEAR;
+
+    /**
+     * The texture that will receive the resolved output if multisampling is used.
+     * If set, it is always written to, regardless of how Self::ops is configured.
+     *
+     * Can be used instead of  if texture has default view or rendering
+     * backend does not support .
+     */
+    public resolveTexture?: ITexture2D;
+
+    /**
+     * The texture view that will receive the resolved output if multisampling is used.
+     * If set, it is always written to, regardless of how Self::ops is configured.
+     * Can be used instead of  if rendering backend supports .
+     */
+    public resolveView?: ITextureView;
+
+    /** Clear color for the attachment. */
+    public clearColor = Color.transparent();
+}

package/src/api/rendering/renderpass/RenderPassDepthStencilAttachment.ts

@@ -0,0 +1,76 @@
+
+import type { ITextureView } from "../texture/ITextureView.ts";
+import {LoadAction} from "./LoadAction.ts";
+import type { ITexture2D } from "../texture/ITexture2D.ts";
+import {StoreAction} from "./StoreAction.ts";
+
+
+/**
+ * Describes a depth/stencil attachment used in a render pass.
+ * Controls how depth and stencil buffers are loaded, cleared, and stored.
+ */
+export class RenderPassDepthStencilAttachment {
+
+    /**
+     * The constructor.
+     */
+    public constructor() {
+        this.depthLoadAction = LoadAction.CLEAR;
+        this.depthStoreAction = StoreAction.DISCARD;
+        this.depthClearValue = 1.0;
+        this.stencilLoadAction = LoadAction.CLEAR;
+        this.stencilStoreAction = StoreAction.DISCARD;
+        this.stencilClearValue = 0;
+    }
+
+    /**
+     * The view into depth/stencil render target.
+     */
+    public view?: ITextureView;
+
+    /**
+     * The texture used as depth/stencil render target.
+     * Can be used instead of 'view' property if 'view' is not supported
+     *  for the rendering backend.
+     */
+    public texture?: ITexture2D;
+
+    /**
+     * What happens to the depth buffer at the start of the render pass.
+     *     By default, it is set to , which means that the depth buffer will be cleared at the beginning of the render pass.
+     */
+    public depthLoadAction: LoadAction;
+
+    /**
+     * What happens to the depth buffer at the end of the render pass.
+     *     By default, it is set to , which means that the depth buffer will be discarded after the render pass and cannot be read later.
+     */
+    public depthStoreAction: StoreAction;
+
+    /**
+     * Depth value used when DepthLoadAction is Clear.
+     *     Typically, 1.0 (far plane).
+     *     Ignored otherwise.
+     */
+    public depthClearValue: number;
+
+
+    /**
+     * What happens to the stencil buffer at the start of the render pass.
+     *     By default, it is set to , which means that the stencil buffer will be cleared at the beginning of the render pass.
+     */
+    public stencilLoadAction: LoadAction;
+
+
+    /**
+     * What happens to the stencil buffer at the end of the render pass.
+     *     By default, it is set to , which means that the stencil buffer will be discarded after the render pass and cannot be read later.
+     */
+    public stencilStoreAction: StoreAction;
+
+    /**
+     * Stencil value used when StencilLoadAction is Clear.
+     *     Ignored otherwise.
+     */
+    public stencilClearValue: number;
+}

package/src/api/rendering/renderpass/RenderPassDescriptor.ts

@@ -0,0 +1,26 @@
+import {RenderPassDepthStencilAttachment} from "./RenderPassDepthStencilAttachment.ts";
+import {RenderPassColorAttachment} from "./RenderPassColorAttachment.ts";
+
+/**
+ * The render pass.
+ */
+export class RenderPassDescriptor {
+
+/**
+ * The color attachments of the render pass.
+ */
+  public colorAttachments?: RenderPassColorAttachment[];
+
+/**
+ * The depth-stencil attachment of the render pass.
+ */
+  public  depthStencilAttachment?: RenderPassDepthStencilAttachment;
+
+/**
+ * The label of the render pass.
+ * This is used for debugging purposes and can be set to any string that helps identify the render pass in graphics debuggers or profiling tools.
+ * It does not affect the functionality of the render pass and can be left empty if not needed.
+ */
+  public label?: string;
+
+}

package/src/api/rendering/renderpass/StoreAction.ts

@@ -0,0 +1,23 @@
+/**
+ * Specifies the action to take with the attachment contents at the end of a render pass.
+ */
+export enum StoreAction {
+/**
+ * The attachment contents generated during the render pass are written back to memory.
+ *     
+ *     Corresponds to WebGPU store operation.
+ */
+  STORE = 0,
+/**
+ * The attachment contents are discarded after the render pass.
+ *     The texture becomes uninitialized (undefined) afterward.
+ *     
+ *     On tile-based GPUs (most mobile/Apple Silicon), this is significantly faster because it avoids writing data back to main memory.
+ *     Use this whenever the attachment will not be read by subsequent render passes.
+ *     
+ *     Note: If only the depth or stencil aspect is discarded, the other aspect is preserved.
+ *     
+ *     Corresponds to WebGPU discard operation.
+ */
+  DISCARD = 1
+}

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

@@ -0,0 +1,6 @@
+export * from "./IRenderPass.ts";
+export * from "./LoadAction.ts";
+export * from "./RenderPassColorAttachment.ts";
+export * from "./RenderPassDepthStencilAttachment.ts";
+export * from "./RenderPassDescriptor.ts";
+export * from "./StoreAction.ts";

package/src/api/rendering/sampler/ISampler.ts

@@ -0,0 +1,52 @@
+import {SamplerFilter} from "./SamplerFilter.ts";
+import {MipMapSamplerFilter} from "./MipMapSamplerFilter.ts";
+import type { IDisposable } from "../../core/IDisposable.ts";
+import {SamplerAddressMode} from "./SamplerAddressMode.ts";
+
+/**
+ * The sampler is used to sample textures in shaders.
+ * It defines how the texture is sampled, such as the filtering mode and the address mode.
+ */
+export interface ISampler extends IDisposable {
+
+/**
+ * The id of a sampler.
+ */
+  readonly id: number;
+
+/**
+ * The min filter of the sampler.
+ */
+  readonly minFilter: SamplerFilter;
+
+/**
+ * The mag filter of the sampler.
+ */
+  readonly magFilter: SamplerFilter;
+
+/**
+ * The mipmap filter of the sampler.
+ */
+  readonly mipmapFilter: MipMapSamplerFilter;
+
+/**
+ * The address mode of the sampler for the U coordinate.
+ */
+  readonly addressModeU: SamplerAddressMode;
+
+/**
+ * The address mode of the sampler for the V coordinate.
+ */
+  readonly addressModeV: SamplerAddressMode;
+
+/**
+ * The address mode of the sampler for the W coordinate.
+ */
+  readonly addressModeW: SamplerAddressMode;
+
+/**
+ * The underlying handle of the sampler, specific to the graphics API being used (e.g., OpenGL, DirectX, Vulkan, WebGPU).
+ */
+  readonly handle: any;
+
+}

package/src/api/rendering/sampler/MipMapSamplerFilter.ts

@@ -0,0 +1,17 @@
+/**
+ * The mipmap sampler filter.
+ */
+export enum MipMapSamplerFilter {
+/**
+ * Mipmap filtering is disabled. The mipmap level 0 will be used for sampling.
+ */
+  NONE = 0,
+/**
+ * The nearest mipmap filtering method. The mipmap level will be selected using the value of the nearest mipmap level.
+ */
+  NEAREST = 1,
+/**
+ * The linear mipmap filtering method. The mipmap level will be selected using the weighted average of the two nearest mipmap levels.
+ */
+  LINEAR = 2
+}

package/src/api/rendering/sampler/SamplerAddressMode.ts

@@ -0,0 +1,23 @@
+/**
+ * The address mode of the sampler.
+ */
+export enum SamplerAddressMode {
+/**
+ * The repeat address mode.
+ *     The texture will be repeated when the texture coordinates are outside the range [0, 1].
+ */
+  REPEAT = 0,
+/**
+ * The mirror repeat address mode.
+ */
+  MIRROR_REPEAT = 1,
+/**
+ * The clamp to edge address mode.
+ */
+  CLAMP_TO_EDGE = 2,
+/**
+ * The clamp to border address mode. 
+ *     The texture will be clamped to a border color when the texture coordinates are outside the range [0, 1].
+ */
+  CLAMP_TO_BORDER = 3
+}

package/src/api/rendering/sampler/SamplerDescriptor.ts

@@ -0,0 +1,46 @@
+import {SamplerAddressMode} from "./SamplerAddressMode.ts";
+import {SamplerFilter} from "./SamplerFilter.ts";
+import {MipMapSamplerFilter} from "./MipMapSamplerFilter.ts";
+
+/**
+ * The descriptor for creating a sampler.
+ * It contains the parameters for creating a sampler, such as the address mode and filter mode.
+ */
+export class SamplerDescriptor {
+
+    /**
+     * The address mode for U coordinate.
+     * It determines how texture coordinates outside the [0, 1] range are handled in the U direction.
+     */
+    public addressModeU = SamplerAddressMode.REPEAT;
+
+    /**
+     * The address mode for V coordinate.
+     * It determines how texture coordinates outside the [0, 1] range are handled in the V direction.
+     */
+    public addressModeV = SamplerAddressMode.REPEAT;
+
+    /**
+     * The address mode for W coordinate.
+     * It determines how texture coordinates outside the [0, 1] range are handled in the W direction.
+     */
+    public addressModeW = SamplerAddressMode.REPEAT;
+
+    /**
+     * The minification filter of the sampler.
+     * It determines how the texture is sampled when it is minified (i.e., when the texture is smaller than the area it is being mapped to).
+     */
+    public minFilter = SamplerFilter.LINEAR;
+
+    /**
+     * The magnification filter of the sampler.
+     * It determines how the texture is sampled when it is magnified (i.e., when the texture is larger than the area it is being mapped to).
+     */
+    public magFilter = SamplerFilter.LINEAR;
+
+    /**
+     * The mipmap filter of the sampler.
+     * It determines how the texture is sampled when mipmapping is used (i.e., when the texture has multiple levels of detail).
+     */
+    public mipMapFilter = MipMapSamplerFilter.NONE;
+}

package/src/api/rendering/sampler/SamplerFilter.ts

@@ -0,0 +1,13 @@
+/**
+ * The sampler filter.
+ */
+export enum SamplerFilter {
+/**
+ * The nearest filtering method. The texture will be sampled using the value of the nearest texel.
+ */
+  NEAREST = 0,
+/**
+ * The linear filtering method. The texture will be sampled using the weighted average of the four nearest texels.
+ */
+  LINEAR = 1
+}

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

@@ -0,0 +1,5 @@
+export * from "./SamplerDescriptor.ts";
+export * from "./ISampler.ts";
+export * from "./MipMapSamplerFilter.ts";
+export * from "./SamplerAddressMode.ts";
+export * from "./SamplerFilter.ts";

package/src/api/rendering/sampler/sampler-enums.ts

@@ -0,0 +1,20 @@
+
+
+/**
+ * The compare function to use when sampling a texture. This is used for depth textures and determines how the sampled depth value is compared to the reference value.
+ */
+export enum SamplerCompareFunction {
+
+    /**
+     * The comparison never passes.
+     * WebGlSamplerUtilities treats this value as "no comparison" and leaves TEXTURE_COMPARE_MODE at NONE.
+     */
+    Never,
+
+    /**
+     * The comparison passes if the reference value is less than or equal to the sampled depth value.
+     */
+    LessEqual,
+
+
+}

package/src/api/rendering/swapchain/ISwapChain.ts

@@ -0,0 +1,33 @@
+import {TextureFormat} from "../texture/TextureFormat.ts";
+import type { IDisposable } from "../../core/IDisposable.ts";
+import {vec2} from "gl-matrix";
+
+/**
+ * The interface for a swap chain, which is used to present the rendered image to the screen.
+ */
+export interface ISwapChain extends IDisposable {
+
+    /**
+     * The size of the back buffer.
+     */
+    readonly backBufferSize: vec2;
+
+    /**
+     * The texture format of the back buffer.
+     */
+    readonly textureFormat: TextureFormat;
+
+    /**
+     * Sets the back buffer size.
+     * This is used to resize the back buffer when the window is resized.
+     * @param width - The new width.
+     * @param height - The new height.
+     */
+    resize(width: number, height: number): void;
+
+    /**
+     * Presents the back buffer to the screen.
+     * This is called after rendering is done, and will swap the back buffer with the front buffer to display the rendered image on the screen.
+     */
+    present(): void;
+}

package/src/api/rendering/swapchain/SurfacePresentMode.ts

@@ -0,0 +1,22 @@
+/**
+ * The presentation mode of the surface.
+ */
+export enum SurfacePresentMode {
+/**
+ * "vsync off"
+ *     Draws the frame immediately, without waiting for the screen refresh.
+ */
+  IMMEDIATE = 0,
+/**
+ * "vsync on"
+ *     Multiple frames can be queued for presentation, but only the last one is displayed.
+ *     Typically it is double buffered, which means that the application can queue one frame while the other one is being displayed,
+ *     but it can be triple buffered as well, which means that the application can queue two frames while the other one is being displayed.
+ */
+  FIFO = 1,
+/**
+ * "fast vsync"
+ *     Multiple frames can be queued for presentation, and the first one is displayed.
+ */
+  MAILBOX = 2
+}

package/src/api/rendering/swapchain/SwapChainDescriptor.ts

@@ -0,0 +1,23 @@
+/**
+ * The description of a swap chain, which is used to create a swap chain for the graphics device.
+ */
+import {SurfacePresentMode} from "./SurfacePresentMode.ts";
+
+export class SwapChainDescriptor {
+
+    /**
+     * The width of the back buffer.
+     */
+    public width: number = 0;
+
+    /**
+     * The height of the back buffer.
+     */
+    public height: number = 0;
+
+    /**
+     * The presentation mode of the swap chain.
+     * This determines how the swap chain presents the back buffer to the screen.
+     */
+    public desiredPresentationMode: SurfacePresentMode = SurfacePresentMode.FIFO;
+}

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

@@ -0,0 +1,3 @@
+export * from "./ISwapChain.ts";
+export * from "./SurfacePresentMode.ts";
+export * from "./SwapChainDescriptor.ts";