ris-framework 0.2.0-dev.11 → 0.2.0-dev.12

package/shaders/glsl/main_render_target_flip_y_fs.glsl

@@ -2,8 +2,42 @@
 precision highp float;
 in vec2 v_texCoord;
 out vec4 outColor;
+
 uniform sampler2D u_texture;
+uniform int u_colorConversion;
+
+float linearToSrgb(float c)
+{
+    if (c <= 0.0)
+        return 0.0;
+
+    if (c < 0.0031308)
+        return 12.92 * c;
+
+    if (c < 1.0)
+        return 1.055 * pow(c, 1.0 / 2.4) - 0.055;
+
+    return 1.0;
+}
+
+// https://registry.khronos.org/OpenGL/specs/gl/glspec46.core.pdf
+// Chapter 17.3.7
+// Page 513
+vec3 linearToSrgb(vec3 c)
+{
+    return vec3(
+        linearToSrgb(c.r),
+        linearToSrgb(c.g),
+        linearToSrgb(c.b)
+    );
+}
+
 void main() 
 {
-    outColor = texture(u_texture, vec2(v_texCoord.x, 1.0 - v_texCoord.y));
+    vec4 color = texture(u_texture, vec2(v_texCoord.x, 1.0 - v_texCoord.y));
+    outColor.rgb = color.rgb;
+    if(u_colorConversion == 1) {
+        outColor.rgb = linearToSrgb(color.rgb);
+    }
+    outColor.a = color.a;
 }

package/shaders/wgsl/forward_blinn_phong_material.wgsl

@@ -0,0 +1,150 @@
+// Forward Blinn-Phong material shader (WebGPU): ambient + directional + point lights, per fragment in world space.
+// Hand-maintained, mirrors slang/forward_blinn_phong_material.slang and glsl_300_es/forward_blinn_phong_material_*.glsl.
+//
+// The light counts must match LightsBuffer.DEFAULT_*_LIGHTS_COUNT (3 directional, 5 point lights;
+// Lights = 4 + 3 * 8 + 5 * 12 = 88 floats = 352 bytes). Every member is a 16 byte aligned vec4.
+// The counts are fixed here because the WebGPU pipeline does not pass a shader config.
+//
+// Bind groups (WebGPUForwardBlinnPhongRenderPipeline), WebGPU guarantees only 4 groups:
+//   group 0: binding 0 = projection view matrix, binding 1 = model matrix (vertex)
+//   group 1: binding 0 = diffuse texture, binding 1 = sampler (fragment)
+//   group 2: binding 2 = material (fragment)
+//   group 3: binding 3 = lights, binding 4 = camera position (fragment)
+
+const DIRECTIONAL_LIGHTS_COUNT : u32 = 3u;
+const POINT_LIGHTS_COUNT : u32 = 5u;
+
+// Material colors (MTL Ka, Kd, Ks) and the specular exponent (MTL Ns).
+struct BlinnPhongMaterial
+{
+    ambientColor : vec4<f32>,
+    diffuseColor : vec4<f32>,
+    specularColorShininess : vec4<f32>, // xyz specular color, w shininess
+};
+
+struct DirectionalLight
+{
+    light : vec4<f32>,     // xyz color * intensity
+    direction : vec4<f32>, // xyz direction in which the light travels
+};
+
+struct PointLight
+{
+    lightConstant : vec4<f32>,  // xyz color * intensity, w constant attenuation
+    positionLinear : vec4<f32>, // xyz world position, w linear attenuation
+    quadratic : vec4<f32>,      // x quadratic attenuation
+};
+
+struct Lights
+{
+    ambientLight : vec4<f32>, // xyz color * intensity
+    directionalLights : array<DirectionalLight, DIRECTIONAL_LIGHTS_COUNT>,
+    pointLights : array<PointLight, POINT_LIGHTS_COUNT>,
+};
+
+struct CameraPosition
+{
+    position : vec4<f32>, // xyz world-space eye
+};
+
+@group(0) @binding(0) var<uniform> projectionView : mat4x4<f32>;
+@group(0) @binding(1) var<uniform> model : mat4x4<f32>;
+
+@group(1) @binding(0) var diffuseTexture : texture_2d<f32>;
+@group(1) @binding(1) var diffuseSampler : sampler;
+
+@group(2) @binding(2) var<uniform> material : BlinnPhongMaterial;
+
+@group(3) @binding(3) var<uniform> lights : Lights;
+@group(3) @binding(4) var<uniform> cameraPosition : CameraPosition;
+
+struct VertexInput
+{
+    @location(0) position : vec3<f32>,
+    @location(1) color : vec4<f32>,
+    @location(2) texCoord : vec2<f32>,
+    @location(3) normal : vec3<f32>,
+};
+
+struct VertexOutput
+{
+    @builtin(position) position : vec4<f32>,
+    @location(0) color : vec4<f32>,
+    @location(1) texCoord : vec2<f32>,
+    @location(2) normal : vec3<f32>,
+    @location(3) worldPosition : vec3<f32>,
+};
+
+@vertex
+fn main_vs(input : VertexInput) -> VertexOutput
+{
+    var output : VertexOutput;
+    let worldPosition = model * vec4<f32>(input.position, 1.0);
+    output.position = projectionView * worldPosition;
+    output.color = input.color;
+    output.texCoord = input.texCoord;
+    output.worldPosition = worldPosition.xyz;
+
+    // World-space normal through the normal matrix (inverse transpose of the upper 3x3 of the model matrix),
+    // correct for non-uniform scale. For M = [a b c] (columns) the cofactor matrix is [b x c, c x a, a x b];
+    // it equals the inverse transpose times det(M). The length is removed in the fragment shader, only the sign matters.
+    let a = model[0].xyz;
+    let b = model[1].xyz;
+    let c = model[2].xyz;
+    let cofactor = mat3x3<f32>(cross(b, c), cross(c, a), cross(a, b));
+    let determinantSign = select(1.0, -1.0, dot(a, cross(b, c)) < 0.0);
+    output.normal = determinantSign * (cofactor * input.normal);
+    return output;
+}
+
+fn blinnPhong(normal : vec3<f32>, lightDirection : vec3<f32>, viewDirection : vec3<f32>, lightColor : vec3<f32>,
+    diffuse : ptr<function, vec3<f32>>, specular : ptr<function, vec3<f32>>)
+{
+    let NdotL = max(dot(normal, lightDirection), 0.0);
+    *diffuse += material.diffuseColor.xyz * lightColor * NdotL;
+
+    if (NdotL > 0.0)
+    {
+        let halfway = normalize(lightDirection + viewDirection);
+        let NdotH = max(dot(normal, halfway), 0.0);
+        *specular += material.specularColorShininess.xyz * lightColor * pow(NdotH, material.specularColorShininess.w);
+    }
+}
+
+@fragment
+fn main_fs(input : VertexOutput) -> @location(0) vec4<f32>
+{
+    let normal = normalize(input.normal);
+
+    // Ambient lighting.
+    let ambient = material.ambientColor.xyz * lights.ambientLight.xyz;
+
+    let viewDirection = normalize(cameraPosition.position.xyz - input.worldPosition);
+
+    // Diffuse and Blinn-Phong specular lighting.
+    var diffuse = vec3<f32>(0.0);
+    var specular = vec3<f32>(0.0);
+
+    for (var i = 0u; i < DIRECTIONAL_LIGHTS_COUNT; i++)
+    {
+        let light = lights.directionalLights[i];
+        blinnPhong(normal, normalize(-light.direction.xyz), viewDirection, light.light.xyz, &diffuse, &specular);
+    }
+
+    // Point lights: same diffuse and specular, scaled by distance attenuation.
+    for (var i = 0u; i < POINT_LIGHTS_COUNT; i++)
+    {
+        let light = lights.pointLights[i];
+        let toLight = light.positionLinear.xyz - input.worldPosition;
+        let lightDistance = length(toLight);
+        let lightDirection = toLight / max(lightDistance, 0.0001);
+        let attenuation = 1.0 / (light.lightConstant.w
+            + light.positionLinear.w * lightDistance
+            + light.quadratic.x * lightDistance * lightDistance);
+        blinnPhong(normal, lightDirection, viewDirection, light.lightConstant.xyz * attenuation, &diffuse, &specular);
+    }
+
+    // Apply material lighting, texture and vertex color. Specular highlights are not tinted by the texture.
+    let texel = textureSample(diffuseTexture, diffuseSampler, input.texCoord) * input.color;
+    return vec4<f32>(texel.rgb * (ambient + diffuse) + specular, texel.a);
+}

package/shaders/wgsl/inspect_texture_mips.wgsl

@@ -0,0 +1,51 @@
+// Inspect texture mips shader (WebGPU): draws a texture at an explicit mip level.
+// Hand-maintained, mirrors slang/inspect_texture_mips.slang and glsl_300_es/inspect_texture_mips_*.glsl.
+// Note: there is no WebGPU inspect pipeline yet; the layout follows the mesh pipelines.
+//
+// Bind groups:
+//   group 0: binding 0 = projection view matrix, binding 1 = model matrix (vertex)
+//   group 1: binding 0 = texture, binding 1 = sampler (fragment)
+//   group 2: binding 2 = texture constants (fragment)
+
+struct TextureConstants
+{
+    mipLevel : f32,
+};
+
+@group(0) @binding(0) var<uniform> projectionView : mat4x4<f32>;
+@group(0) @binding(1) var<uniform> model : mat4x4<f32>;
+
+@group(1) @binding(0) var diffuseTexture : texture_2d<f32>;
+@group(1) @binding(1) var diffuseSampler : sampler;
+
+@group(2) @binding(2) var<uniform> textureConstants : TextureConstants;
+
+struct VertexInput
+{
+    @location(0) position : vec3<f32>,
+    @location(1) color : vec4<f32>,
+    @location(2) texCoord : vec2<f32>,
+};
+
+struct VertexOutput
+{
+    @builtin(position) position : vec4<f32>,
+    @location(0) color : vec4<f32>,
+    @location(1) texCoord : vec2<f32>,
+};
+
+@vertex
+fn main_vs(input : VertexInput) -> VertexOutput
+{
+    var output : VertexOutput;
+    output.position = projectionView * model * vec4<f32>(input.position, 1.0);
+    output.color = input.color;
+    output.texCoord = input.texCoord;
+    return output;
+}
+
+@fragment
+fn main_fs(input : VertexOutput) -> @location(0) vec4<f32>
+{
+    return textureSampleLevel(diffuseTexture, diffuseSampler, input.texCoord, textureConstants.mipLevel) * input.color;
+}

package/shaders/wgsl/main_frame_buffer.wgsl

@@ -0,0 +1,35 @@
+// Draws the main render target texture to the screen. (WebGPU)
+// Hand-maintained, mirrors slang/main_frame_buffer.slang.
+//
+// Bind groups (WebGPUMainFrameBufferRenderPipeline):
+//   group 0: binding 0 = texture, binding 1 = sampler (fragment)
+
+@group(0) @binding(0) var diffuseTexture : texture_2d<f32>;
+@group(0) @binding(1) var diffuseSampler : sampler;
+
+struct VertexInput
+{
+    @location(0) position : vec3<f32>,
+    @location(1) texCoord : vec2<f32>,
+};
+
+struct VertexOutput
+{
+    @builtin(position) position : vec4<f32>,
+    @location(0) texCoord : vec2<f32>,
+};
+
+@vertex
+fn main_vs(input : VertexInput) -> VertexOutput
+{
+    var output : VertexOutput;
+    output.position = vec4<f32>(input.position, 1.0);
+    output.texCoord = input.texCoord;
+    return output;
+}
+
+@fragment
+fn main_fs(input : VertexOutput) -> @location(0) vec4<f32>
+{
+    return textureSample(diffuseTexture, diffuseSampler, input.texCoord);
+}

package/shaders/wgsl/main_render_target_flip_y.wgsl

@@ -0,0 +1,35 @@
+// Draws the main render target texture to the screen, flipped on Y. (WebGPU)
+// Hand-maintained, mirrors slang/main_render_target_flip_y.slang.
+//
+// Bind groups (WebGPUMainFrameBufferRenderPipeline):
+//   group 0: binding 0 = texture, binding 1 = sampler (fragment)
+
+@group(0) @binding(0) var diffuseTexture : texture_2d<f32>;
+@group(0) @binding(1) var diffuseSampler : sampler;
+
+struct VertexInput
+{
+    @location(0) position : vec3<f32>,
+    @location(1) texCoord : vec2<f32>,
+};
+
+struct VertexOutput
+{
+    @builtin(position) position : vec4<f32>,
+    @location(0) texCoord : vec2<f32>,
+};
+
+@vertex
+fn main_vs(input : VertexInput) -> VertexOutput
+{
+    var output : VertexOutput;
+    output.position = vec4<f32>(input.position, 1.0);
+    output.texCoord = input.texCoord;
+    return output;
+}
+
+@fragment
+fn main_fs(input : VertexOutput) -> @location(0) vec4<f32>
+{
+    return textureSample(diffuseTexture, diffuseSampler, vec2<f32>(input.texCoord.x, 1.0 - input.texCoord.y));
+}

package/shaders/wgsl/sprite.wgsl

@@ -0,0 +1,40 @@
+// Sprite batch shader (WebGPU). Hand-maintained, mirrors slang/sprite.slang and glsl_300_es/sprite_*.glsl.
+//
+// Bind groups (WebGPUSpriteRenderPipeline):
+//   group 0: binding 0 = projection view matrix (vertex)
+//   group 1: binding 0 = sprite texture, binding 1 = sampler (fragment)
+
+@group(0) @binding(0) var<uniform> projectionView : mat4x4<f32>;
+
+@group(1) @binding(0) var diffuseTexture : texture_2d<f32>;
+@group(1) @binding(1) var diffuseSampler : sampler;
+
+struct VertexInput
+{
+    @location(0) position : vec3<f32>,
+    @location(1) color : vec4<f32>,
+    @location(2) texCoord : vec2<f32>,
+};
+
+struct VertexOutput
+{
+    @builtin(position) position : vec4<f32>,
+    @location(0) color : vec4<f32>,
+    @location(1) texCoord : vec2<f32>,
+};
+
+@vertex
+fn main_vs(input : VertexInput) -> VertexOutput
+{
+    var output : VertexOutput;
+    output.position = projectionView * vec4<f32>(input.position, 1.0);
+    output.color = input.color;
+    output.texCoord = input.texCoord;
+    return output;
+}
+
+@fragment
+fn main_fs(input : VertexOutput) -> @location(0) vec4<f32>
+{
+    return textureSample(diffuseTexture, diffuseSampler, input.texCoord) * input.color;
+}

package/shaders/wgsl/unlit_material.wgsl

@@ -0,0 +1,49 @@
+// Unlit material shader (WebGPU). Hand-maintained, mirrors slang/unlit_material.slang and glsl_300_es/unlit_material_*.glsl.
+//
+// Bind groups (WebGPUUnlitRenderPipeline):
+//   group 0: binding 0 = projection view matrix, binding 1 = model matrix (vertex)
+//   group 1: binding 0 = diffuse texture, binding 1 = sampler (fragment)
+//   group 2: binding 2 = material (fragment)
+
+struct Material
+{
+    diffuseColor : vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> projectionView : mat4x4<f32>;
+@group(0) @binding(1) var<uniform> model : mat4x4<f32>;
+
+@group(1) @binding(0) var diffuseTexture : texture_2d<f32>;
+@group(1) @binding(1) var diffuseSampler : sampler;
+
+@group(2) @binding(2) var<uniform> material : Material;
+
+struct VertexInput
+{
+    @location(0) position : vec3<f32>,
+    @location(1) color : vec4<f32>,
+    @location(2) texCoord : vec2<f32>,
+};
+
+struct VertexOutput
+{
+    @builtin(position) position : vec4<f32>,
+    @location(0) color : vec4<f32>,
+    @location(1) texCoord : vec2<f32>,
+};
+
+@vertex
+fn main_vs(input : VertexInput) -> VertexOutput
+{
+    var output : VertexOutput;
+    output.position = projectionView * model * vec4<f32>(input.position, 1.0);
+    output.color = input.color;
+    output.texCoord = input.texCoord;
+    return output;
+}
+
+@fragment
+fn main_fs(input : VertexOutput) -> @location(0) vec4<f32>
+{
+    return textureSample(diffuseTexture, diffuseSampler, input.texCoord) * material.diffuseColor * input.color;
+}

package/src/Framework.ts

@@ -1,36 +1,35 @@
 import {WebGlAmbientLightFactory} from "./webgl/lights/WebGlAmbientLightFactory.ts";
 import {WindowManager} from "./api/window/WindowManager.ts";
-import {FrameworkConfiguration} from "./api/FrameworkConfiguration.ts";
-import {type IRendererConfiguration} from "./api/rendering/renderer-interface.ts";
 import {GeometryBuilder} from "./api/geometry/GeometryBuilder.ts";
 import {ContentManager} from "./api/content/ContentManager.ts";
+import {ObjLoader} from "./api/loaders/ObjLoader.ts";
 import {WebGlRenderer} from "./webgl/WebGlRenderer.ts";
 import {WebGlBuffersFactory} from "./webgl/buffers/WebGlBuffersFactory.ts";
 import {
-    type ICameraFactory,
-    type IContentManager,
-    type IFramework, IFrameworkConfiguration,
-    type IImageLoader,
-    type IRenderer,
-    type IRenderPipelineFactory,
-    type IWindowManager
-} from "./api/index.ts";
-import {
+    type AmbientLightFactory,
     CameraFactory,
     CpuImageProcessor,
     GameTime,
     type IBufferFactory,
+    type ICameraFactory,
+    type IContentManager,
+    type IFramework,
+    IFrameworkConfiguration,
     type IGeometryBuilder,
     type IGraphicsDevice,
+    type IImageLoader,
     type IImageProcessor,
     type IInputManager,
     ImageLoader,
     type IMaterialFactory,
-    type AmbientLightFactory,
     type IMeshFactory,
+    type IRenderer,
+    type IRendererConfiguration,
+    type IRenderPipelineFactory,
     type ISpriteBatch,
     type ITextureFactory,
     type ITimeManager,
+    type IWindowManager,
     MaterialFactory,
     MeshFactory,
     RenderingBackend,
@@ -48,7 +47,16 @@ import type {IKtx2Factory} from "ris-ktx2";
 import {Ktx2Factory} from "ris-ktx2";
 import {PowerPreferenceType} from "./api/rendering/PowerPreference.ts";
 import {vec2} from "gl-matrix";
-
+import {ARenderer} from "./core/rendering/ARenderer.ts";
+import {WebGpuRenderer} from "./webgpu/WebGpuRenderer.ts";
+import {WebGpuTextureFactory} from "./webgpu/texture/WebGpuTextureFactory.ts";
+import {WebGpuRenderPipelineFactory} from "./webgpu/render-pipelines/WebGpuRenderPipelineFactory.ts";
+import {WebGpuShaderModuleLoader} from "./webgpu/shader/WebGpuShaderModuleLoader.ts";
+import {WebGpuBuffersFactory} from "./webgpu/buffers/WebGpuBuffersFactory.ts";
+import {WebGpuTexture2D} from "./webgpu/texture/WebGpuTexture2D.ts";
+import {TextureColorSpace} from "./api/rendering/enums.ts";
+
+/** The Ris framework */
 export class Framework implements IFramework {
 
     private readonly _onLoadContentListeners: (() => void)[] = [];
@@ -56,46 +64,63 @@ export class Framework implements IFramework {
     private readonly _onUpdateListeners: ((gameTime: GameTime) => void)[] = [];
     private readonly _onRenderListeners: (() => void)[] = [];
 
-    private readonly _textureFactory: ITextureFactory;
-    private readonly _buffersFactory: IBufferFactory;
-    private readonly _contentManager: IContentManager;
+    private _configuration: IFrameworkConfiguration;
+    private _textureFactory: ITextureFactory = null!;
+    private _buffersFactory: IBufferFactory = null!;
+    private _contentManager: IContentManager = null!;
+    private readonly _rendererConfiguration: IRendererConfiguration = null!;
+    private _renderer: IRenderer = null!;
     private readonly _geometryBuilder: IGeometryBuilder;
     private readonly _meshFactory: IMeshFactory;
     private _disposed = false;
 
     /**
      * The constructor for the Framework class.
-     * @param options The optional framework configuration. When omitted, a default `FrameworkConfiguration` is used.
+     * @param configuration The optional framework configuration. When omitted, a default `FrameworkConfiguration` is used.
      */
-    constructor(options?: IFrameworkConfiguration) {
-        options = options ?? new FrameworkConfiguration();
+    constructor(configuration?: IFrameworkConfiguration) {
+
+        this._configuration = configuration ?? {}
+
+        if(!this._configuration.backBufferSize){
+            this._configuration.backBufferSize = vec2.fromValues(800, 600);
+        }
 
         // Without a canvas, WindowManager creates one and appends it to document.body.
-        if(!options.canvas){
+        if(!this._configuration.canvas){
             console.warn("Canvas not provided. Creating canvas and appending it to document.body.")
         }
-        options.backBufferSize = options.backBufferSize ?? vec2.fromValues(800, 600);
+        this._configuration.backBufferSize = this._configuration.backBufferSize ?? vec2.fromValues(800, 600);
 
-        this.windowManager = new WindowManager(options.canvas ?? null);
+        this.windowManager = new WindowManager(this._configuration.canvas ?? null);
 
         // Services are created here and get their dependencies through their constructors.
-        const rendererConfig: IRendererConfiguration = {
-            backBufferSize: options.backBufferSize,
-            textureFiltering: options.textureFiltering ?? TextureSamplerFilteringPreset.BILINEAR,
-            alpha: options.alpha ?? false,
-            powerPreference: options.powerPreference ?? PowerPreferenceType.DEFAULT
+        this._rendererConfiguration  = {
+            backBufferSize: this._configuration.backBufferSize,
+            textureFiltering: this._configuration.textureFiltering ?? TextureSamplerFilteringPreset.BILINEAR,
+            alpha: this._configuration.alpha ?? false,
+            powerPreference: this._configuration.powerPreference ?? PowerPreferenceType.DEFAULT,
+            textureColorSpace: this._configuration.textureColorSpace ?? TextureColorSpace.SRGB
         };
-        this.renderer = new WebGlRenderer(this, rendererConfig);
-        this.renderingBackend = RenderingBackend.WEB_GL;
-        this._textureFactory = new WebGlTextureFactory(this);
+
+
+        // The renderer, texture, pipeline, shader and buffer services depend on the backend.
+        let backend = this._configuration.renderingBackend ?? RenderingBackend.WEB_GL;
+        if (backend === RenderingBackend.DEFAULT) {
+            backend = RenderingBackend.WEB_GL;
+        }
+        if (backend === RenderingBackend.WEB_GPU && !WebGpuRenderer.isSupported()) {
+            console.warn("WebGPU was requested, but navigator.gpu is missing. Falling back to WebGL.");
+            backend = RenderingBackend.WEB_GL;
+        }
+        this.renderingBackend = backend;
+        this._setupBackendServices(backend);
+
         this._geometryBuilder = new GeometryBuilder();
-        this.renderPipelineFactory = new WebGlRenderPipelineFactory(this);
-        this._contentManager = new ContentManager(this, new WebGlShaderModuleLoader(this));
         this._meshFactory = new MeshFactory(this);
         this.materialFactory = new MaterialFactory(this);
         this.lightsFactory = new WebGlAmbientLightFactory(this);
 
-        this._buffersFactory = new WebGlBuffersFactory(this);
         this.spriteBatch = new SpriteBatch(this);
         this.cameraFactory = new CameraFactory(this);
         this.timeManager = new TimeManager();
@@ -103,7 +128,7 @@ export class Framework implements IFramework {
         this.imageProcessor = new CpuImageProcessor();
         this.imageLoader = new ImageLoader(this);
 
-        if(options.useKtx2){
+        if(this._configuration.useKtx2){
             this.ktx2Factory = new Ktx2Factory();
         }
     }
@@ -117,7 +142,30 @@ export class Framework implements IFramework {
     public readonly imageProcessor :IImageProcessor;
 
     /** @inheritDoc */
-    public readonly renderer : IRenderer;
+    public get renderer(): IRenderer {
+        return this._renderer;
+    }
+
+    /**
+     * Creates the backend-specific services: renderer, texture factory, pipeline factory, shader loader and buffers factory.
+     * @param backend WEB_GL or WEB_GPU.
+     */
+    private _setupBackendServices(backend: RenderingBackend): void {
+        this.renderingBackend = backend;
+        if (backend === RenderingBackend.WEB_GPU) {
+            this._renderer = new WebGpuRenderer(this, this._rendererConfiguration);
+            this._textureFactory = new WebGpuTextureFactory(this);
+            this.renderPipelineFactory = new WebGpuRenderPipelineFactory(this);
+            this._contentManager = new ContentManager(this, new WebGpuShaderModuleLoader(this));
+            this._buffersFactory = new WebGpuBuffersFactory(this);
+        } else {
+            this._renderer = new WebGlRenderer(this, this._rendererConfiguration);
+            this._textureFactory = new WebGlTextureFactory(this);
+            this.renderPipelineFactory = new WebGlRenderPipelineFactory(this);
+            this._contentManager = new ContentManager(this, new WebGlShaderModuleLoader(this));
+            this._buffersFactory = new WebGlBuffersFactory(this);
+        }
+    }
 
     /** @inheritDoc */
     public readonly spriteBatch: ISpriteBatch;
@@ -185,7 +233,7 @@ export class Framework implements IFramework {
     }
 
     /** @inheritdoc */
-    public renderPipelineFactory: IRenderPipelineFactory;
+    public renderPipelineFactory: IRenderPipelineFactory = null!;
 
     /** @inheritdoc */
     get geometryBuilder(): IGeometryBuilder {
@@ -215,6 +263,9 @@ export class Framework implements IFramework {
         return this._meshFactory;
     }
 
+    /** @inheritDoc */
+    public readonly objLoader: ObjLoader = new ObjLoader(this);
+
     /** @inheritDoc */
     public readonly materialFactory: IMaterialFactory;
 
@@ -230,11 +281,43 @@ export class Framework implements IFramework {
     /** @inheritdoc */
     public initialize(): void {
 
+        // WebGPU needs an async device request; initialize() keeps the synchronous WebGL path.
+        if (this.renderingBackend === RenderingBackend.WEB_GPU) {
+            console.warn("WebGPU needs Framework.initializeAsync(). initialize() falls back to WebGL.");
+            this._setupBackendServices(RenderingBackend.WEB_GL);
+        }
+
         if(this.ktx2Factory) {
             this.ktx2Factory.initializeAsync();
         }
 
-        (this.renderer as WebGlRenderer).initialize();
+        this._initializeCore();
+    }
+
+    /**
+     * Initializes the framework and starts the event loop. Required for WebGPU, which requests its adapter
+     * and device asynchronously; for WebGL it behaves like {@link initialize}.
+     * If the WebGPU device cannot be acquired, the framework falls back to WebGL with a warning.
+     */
+    public async initializeAsync(): Promise<void> {
+        if (this.renderingBackend === RenderingBackend.WEB_GPU) {
+            try {
+                await (this._renderer as WebGpuRenderer).acquireDeviceAsync();
+            } catch (error) {
+                console.warn(`WebGPU could not be initialized (${(error as Error)?.message ?? error}). Falling back to WebGL.`);
+                this._setupBackendServices(RenderingBackend.WEB_GL);
+            }
+        }
+
+        if (this.ktx2Factory) {
+            this.ktx2Factory.initializeAsync();
+        }
+
+        this._initializeCore();
+    }
+
+    private _initializeCore(): void {
+        (this._renderer as ARenderer).initialize();
         this.spriteBatch.initialize();
         this.input.initialize();
 
@@ -297,6 +380,7 @@ export class Framework implements IFramework {
         this._onRenderListeners.length = 0;
 
         WebGlTexture2D.disposeDefault(this);
+        WebGpuTexture2D.disposeDefault(this);
         (this._contentManager as Partial<IDisposable>).dispose?.();
         // Only exists after initialize(); it owns the default sampler and blend state.
         (this.renderer.graphicsDevice as IGraphicsDevice | undefined)?.dispose();