Add cube sample for Web using Feature Level 0 (#9699)

z3moon · web-flow · commit e832805faf80 · 2026-02-11T09:59:25.000-08:00
Introduce a new cube sample that utilizes the feature level 0 (FL0) on
the web. The `Engine.create` method accepts `config` as an argument,
allowing users to explicitly request a GLES 2.0 context.

In addition, this change helps a future implementation of asynchronous
support for web, allowing the asynchronous mode to be turned on via the
configuration setting.

BUGS=[476134614]
diff --git a/web/filament-js/extensions.js b/web/filament-js/extensions.js
@@ -79,7 +79,7 @@ Filament.loadClassExtensions = function() {
     /// canvas ::argument:: the canvas DOM element
     /// options ::argument:: optional WebGL 2.0 context configuration
     /// ::retval:: an instance of [Engine]
-    Filament.Engine.create = function(canvas, options) {
+    Filament.Engine.create = function (canvas, options, config) {
         const defaults = {
             majorVersion: 2,
             minorVersion: 0,
@@ -103,7 +103,9 @@ Filament.loadClassExtensions = function() {
         window.filament_glContext = ctx;
 
         // Register the GL context with emscripten and create the Engine.
-        const engine = Filament.Engine._create();
+        const defaultConfig = Filament.Engine.createDefaultConfig();
+        const finalConfig = Object.assign(defaultConfig, config);
+        const engine = Filament.Engine._create(finalConfig);
 
         // Annotate the engine with the GL context to support multiple canvases.
         engine.context = window.filament_glContext;
diff --git a/web/filament-js/jsbindings.cpp b/web/filament-js/jsbindings.cpp
@@ -312,6 +312,28 @@ value_object<filament::Aabb>("Aabb")
     .field("min", &filament::Aabb::min)
     .field("max", &filament::Aabb::max);
 
+value_object<filament::Engine::Config>("Engine$Config")
+    .field("commandBufferSizeMB", &filament::Engine::Config::commandBufferSizeMB)
+    .field("perRenderPassArenaSizeMB", &filament::Engine::Config::perRenderPassArenaSizeMB)
+    .field("driverHandleArenaSizeMB", &filament::Engine::Config::driverHandleArenaSizeMB)
+    .field("minCommandBufferSizeMB", &filament::Engine::Config::minCommandBufferSizeMB)
+    .field("perFrameCommandsSizeMB", &filament::Engine::Config::perFrameCommandsSizeMB)
+    .field("jobSystemThreadCount", &filament::Engine::Config::jobSystemThreadCount)
+    .field("metalUploadBufferSizeBytes", &filament::Engine::Config::metalUploadBufferSizeBytes)
+    .field("metalDisablePanicOnDrawableFailure", &filament::Engine::Config::metalDisablePanicOnDrawableFailure)
+    .field("disableParallelShaderCompile", &filament::Engine::Config::disableParallelShaderCompile)
+    .field("stereoscopicType", &filament::Engine::Config::stereoscopicType)
+    .field("stereoscopicEyeCount", &filament::Engine::Config::stereoscopicEyeCount)
+    .field("resourceAllocatorCacheSizeMB", &filament::Engine::Config::resourceAllocatorCacheSizeMB)
+    .field("resourceAllocatorCacheMaxAge", &filament::Engine::Config::resourceAllocatorCacheMaxAge)
+    .field("disableHandleUseAfterFreeCheck", &filament::Engine::Config::disableHandleUseAfterFreeCheck)
+    .field("preferredShaderLanguage", &filament::Engine::Config::preferredShaderLanguage)
+    .field("forceGLES2Context", &filament::Engine::Config::forceGLES2Context)
+    .field("assertNativeWindowIsValid", &filament::Engine::Config::assertNativeWindowIsValid)
+    .field("gpuContextPriority", &filament::Engine::Config::gpuContextPriority)
+    .field("sharedUboInitialSizeInBytes", &filament::Engine::Config::sharedUboInitialSizeInBytes)
+    .field("asynchronousMode", &filament::Engine::Config::asynchronousMode);
+
 value_object<filament::Renderer::ClearOptions>("Renderer$ClearOptions")
     .field("clearColor", &filament::Renderer::ClearOptions::clearColor)
     .field("clear", &filament::Renderer::ClearOptions::clear)
@@ -376,19 +398,48 @@ register_vector<allow_raw_pointer<MaterialInstance*>>("MaterialInstanceVector");
 // CORE FILAMENT CLASSES
 // ---------------------
 
+enum_<Engine::StereoscopicType>("StereoscopicType")
+    .value("NONE", Engine::StereoscopicType::NONE)
+    .value("INSTANCED", Engine::StereoscopicType::INSTANCED)
+    .value("MULTIVIEW", Engine::StereoscopicType::MULTIVIEW);
+
+enum_<Engine::GpuContextPriority>("GpuContextPriority")
+    .value("DEFAULT", Engine::GpuContextPriority::DEFAULT)
+    .value("LOW", Engine::GpuContextPriority::LOW)
+    .value("MEDIUM", Engine::GpuContextPriority::MEDIUM)
+    .value("HIGH", Engine::GpuContextPriority::HIGH)
+    .value("REALTIME", Engine::GpuContextPriority::REALTIME);
+
+enum_<Engine::AsynchronousMode>("AsynchronousMode")
+    .value("NONE", Engine::AsynchronousMode::NONE)
+    .value("THREAD_PREFERRED", Engine::AsynchronousMode::THREAD_PREFERRED)
+    .value("AMORTIZATION", Engine::AsynchronousMode::AMORTIZATION);
+
+enum_<Engine::Config::ShaderLanguage>("ShaderLanguage")
+    .value("DEFAULT", Engine::Config::ShaderLanguage::DEFAULT)
+    .value("MSL", Engine::Config::ShaderLanguage::MSL)
+    .value("METAL_LIBRARY", Engine::Config::ShaderLanguage::METAL_LIBRARY);
+
 /// Engine ::core class:: Central manager and resource owner.
 class_<Engine>("Engine")
-    .class_function("_create", (Engine* (*)()) [] {
+    .class_function("_create", (Engine* (*)(Engine::Config)) [] (Engine::Config config) {
         EM_ASM_INT({
             const options = window.filament_glOptions;
             const context = window.filament_glContext;
             const handle = GL.registerContext(context, options);
             window.filament_contextHandle = handle;
             GL.makeContextCurrent(handle);
         });
-        return Engine::create();
+        return Engine::create(Engine::Backend::DEFAULT, nullptr, nullptr, &config);
     }, allow_raw_pointers())
 
+    // Create a default Engine configuration. This is for internal use to ensure that engine
+    // creation logic in 'extensions.js' does not have to populate the default configuration
+    // variables manually.
+    .class_function("createDefaultConfig", (Engine::Config (*)()) [] {
+        return Engine::Config();
+    })
+
     .class_function("getSteadyClockTimeNano", &Engine::getSteadyClockTimeNano)
 
     .function("unprotected", &Engine::unprotected)
@@ -409,6 +460,8 @@ class_<Engine>("Engine")
 
     .class_function("getMaxStereoscopicEyes", &Engine::getMaxStereoscopicEyes)
 
+    .function("getConfig", &Engine::getConfig)
+
     .function("_execute", EMBIND_LAMBDA(void, (Engine* engine), {
         EM_ASM_INT({
             const handle = window.filament_contextHandle;
diff --git a/web/samples/CMakeLists.txt b/web/samples/CMakeLists.txt
@@ -22,6 +22,10 @@ set(MATERIAL_NAMES
     textured
     nonlit)
 
+set(MATERIAL_FL0_NAMES
+    nonlit
+)
+
 set(MATC_FLAGS -a opengl -p mobile)
 if (NOT CMAKE_BUILD_TYPE MATCHES Release)
     set(MATC_FLAGS -g ${MATC_FLAGS})
@@ -32,14 +36,28 @@ foreach (NAME ${MATERIAL_NAMES})
     set(mat_src "materials/${NAME}.mat")
     get_filename_component(localname "${mat_src}" NAME_WE)
     get_filename_component(fullname "${mat_src}" ABSOLUTE)
-    set(output_bin "${SERVER_DIR}/${localname}.filamat")
+    set(output_path "${SERVER_DIR}/${localname}.filamat")
     add_custom_command(
-            OUTPUT ${output_bin}
-            COMMAND matc ${MATC_FLAGS} -o ${output_bin} ${fullname}
+            OUTPUT ${output_path}
+            COMMAND matc ${MATC_FLAGS} -o ${output_path} ${fullname}
             MAIN_DEPENDENCY ${mat_src}
             DEPENDS matc
             COMMENT "Compiling material ${mat_src} to ${output_path}")
-    list(APPEND MATERIAL_BINS ${output_bin})
+    list(APPEND MATERIAL_BINS ${output_path})
+
+    # --- Feature Level 0 variant ---
+    list(FIND MATERIAL_FL0_NAMES ${NAME} index)
+    if (${index} GREATER -1 AND FILAMENT_ENABLE_FEATURE_LEVEL_0)
+        string(REGEX REPLACE "[.]filamat$" "_fl0.filamat" output_path_fl0 ${output_path})
+        add_custom_command(
+                OUTPUT ${output_path_fl0}
+                COMMAND matc ${MATC_FLAGS} -PfeatureLevel=0 -o ${output_path_fl0} ${fullname}
+                MAIN_DEPENDENCY ${fullname}
+                DEPENDS matc
+                COMMENT "Compiling material ${fullname} (FL0)"
+        )
+        list(APPEND MATERIAL_BINS ${output_path_fl0})
+    endif()
 endforeach()
 
 add_custom_target(sample_materials DEPENDS ${MATERIAL_BINS})
@@ -196,6 +214,7 @@ endif()
 
 set(HTML_FILES
     animation.html
+    cube_fl0.html
     helmet.html
     morphing.html
     parquet.html
diff --git a/web/samples/cube_fl0.html b/web/samples/cube_fl0.html
@@ -0,0 +1,187 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <title>Filament Cube</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,user-scalable=no,initial-scale=1">
+  <link href="favicon.png" rel="icon" type="image/x-icon" />
+  <style>
+    body {
+      margin: 0;
+      overflow: hidden;
+    }
+
+    canvas {
+      touch-action: none;
+      width: 100%;
+      height: 100%;
+    }
+  </style>
+</head>
+
+<body>
+  <canvas></canvas>
+  <script src="filament.js"></script>
+  <script src="gl-matrix-min.js"></script>
+  <script>
+
+    Filament.init(['nonlit_fl0.filamat'], () => {
+      window.VertexAttribute = Filament.VertexAttribute;
+      window.AttributeType = Filament.VertexBuffer$AttributeType;
+      window.Projection = Filament.Camera$Projection;
+      window.Fov = Filament.Camera$Fov;
+      window.app = new App(document.getElementsByTagName('canvas')[0]);
+    });
+
+    class App {
+      constructor(canvas) {
+        this.canvas = canvas;
+        const engine = this.engine = Filament.Engine.create(this.canvas, {}, { forceGLES2Context: true });
+        console.log("Engine Config forceGLES2Context:", engine.getConfig().forceGLES2Context);
+        this.scene = engine.createScene();
+        this.cube = Filament.EntityManager.get().create();
+        this.scene.addEntity(this.cube);
+
+        const CUBE_POSITIONS = new Float32Array([
+          // Front face
+          -1.0, -1.0, 1.0,
+          1.0, -1.0, 1.0,
+          1.0, 1.0, 1.0,
+          -1.0, 1.0, 1.0,
+
+          // Back face
+          -1.0, -1.0, -1.0,
+          -1.0, 1.0, -1.0,
+          1.0, 1.0, -1.0,
+          1.0, -1.0, -1.0,
+
+          // Top face
+          -1.0, 1.0, -1.0,
+          -1.0, 1.0, 1.0,
+          1.0, 1.0, 1.0,
+          1.0, 1.0, -1.0,
+
+          // Bottom face
+          -1.0, -1.0, -1.0,
+          1.0, -1.0, -1.0,
+          1.0, -1.0, 1.0,
+          -1.0, -1.0, 1.0,
+
+          // Right face
+          1.0, -1.0, -1.0,
+          1.0, 1.0, -1.0,
+          1.0, 1.0, 1.0,
+          1.0, -1.0, 1.0,
+
+          // Left face
+          -1.0, -1.0, -1.0,
+          -1.0, -1.0, 1.0,
+          -1.0, 1.0, 1.0,
+          -1.0, 1.0, -1.0,
+        ]);
+
+        const CUBE_COLORS = new Uint32Array([
+          // Front face (red)
+          0xff0000ff, 0xff0000ff, 0xff0000ff, 0xff0000ff,
+          // Back face (green)
+          0xff00ff00, 0xff00ff00, 0xff00ff00, 0xff00ff00,
+          // Top face (blue)
+          0xffff0000, 0xffff0000, 0xffff0000, 0xffff0000,
+          // Bottom face (yellow)
+          0xff00ffff, 0xff00ffff, 0xff00ffff, 0xff00ffff,
+          // Right face (magenta)
+          0xffff00ff, 0xffff00ff, 0xffff00ff, 0xffff00ff,
+          // Left face (cyan)
+          0xffffff00, 0xffffff00, 0xffffff00, 0xffffff00,
+        ]);
+
+        const CUBE_INDICES = new Uint16Array([
+          0, 1, 2, 0, 2, 3,    // front
+          4, 5, 6, 4, 6, 7,    // back
+          8, 9, 10, 8, 10, 11,    // top
+          12, 13, 14, 12, 14, 15,    // bottom
+          16, 17, 18, 16, 18, 19,    // right
+          20, 21, 22, 20, 22, 23,    // left
+        ]);
+
+        this.vb = Filament.VertexBuffer.Builder()
+          .vertexCount(24)
+          .bufferCount(2)
+          .attribute(VertexAttribute.POSITION, 0, AttributeType.FLOAT3, 0, 12)
+          .attribute(VertexAttribute.COLOR, 1, AttributeType.UBYTE4, 0, 4)
+          .normalized(VertexAttribute.COLOR)
+          .build(engine);
+
+        this.vb.setBufferAt(engine, 0, CUBE_POSITIONS);
+        this.vb.setBufferAt(engine, 1, CUBE_COLORS);
+
+        this.ib = Filament.IndexBuffer.Builder()
+          .indexCount(36)
+          .bufferType(Filament.IndexBuffer$IndexType.USHORT)
+          .build(engine);
+
+        this.ib.setBuffer(engine, CUBE_INDICES);
+
+        const mat = engine.createMaterial('nonlit_fl0.filamat');
+        const matinst = mat.getDefaultInstance();
+        Filament.RenderableManager.Builder(1)
+          .boundingBox({ center: [-1, -1, -1], halfExtent: [1, 1, 1] })
+          .material(0, matinst)
+          .geometry(0, Filament.RenderableManager$PrimitiveType.TRIANGLES, this.vb, this.ib)
+          .build(engine, this.cube);
+
+        this.swapChain = engine.createSwapChain();
+        this.renderer = engine.createRenderer();
+        this.camera = engine.createCamera(Filament.EntityManager.get().create());
+
+        this.view = engine.createView();
+        this.view.setSampleCount(4);
+        this.view.setCamera(this.camera);
+        this.view.setScene(this.scene);
+        this.view.setPostProcessingEnabled(false);
+
+        this.renderer.setClearOptions({ clearColor: [0.0, 0.1, 0.2, 1.0], clear: true });
+
+        this.resize();
+        this.render = this.render.bind(this);
+        this.resize = this.resize.bind(this);
+        window.addEventListener('resize', this.resize);
+        window.requestAnimationFrame(this.render);
+      }
+
+      render() {
+        const radians = Date.now() / 1000;
+
+        // Combine rotations around Y and X axes for a spinning effect
+        const transformY = mat4.fromRotation(mat4.create(), radians, [0, 1, 0]);
+        const transformX = mat4.fromRotation(mat4.create(), radians * 0.5, [1, 0, 0]);
+        const transform = mat4.multiply(mat4.create(), transformY, transformX);
+
+        const tcm = this.engine.getTransformManager();
+        const inst = tcm.getInstance(this.cube);
+        tcm.setTransform(inst, transform);
+        inst.delete();
+
+        this.renderer.render(this.swapChain, this.view);
+        window.requestAnimationFrame(this.render);
+      }
+
+      resize() {
+        const dpr = window.devicePixelRatio;
+        const width = this.canvas.width = window.innerWidth * dpr;
+        const height = this.canvas.height = window.innerHeight * dpr;
+        this.view.setViewport([0, 0, width, height]);
+
+        const eye = [0, 0, 5], center = [0, 0, 0], up = [0, 1, 0];
+        this.camera.lookAt(eye, center, up);
+
+        const aspect = width / height;
+        const fov = aspect < 1 ? Fov.HORIZONTAL : Fov.VERTICAL;
+        this.camera.setProjectionFov(90, aspect, 1.0, 10.0, fov);
+      }
+    }
+  </script>
+</body>
+
+</html>
