A new froxel grid vizualization for FilamentApp

FilamentApp now has debugging options to enable or disable the
camera and directional shadow frustums, as well as the new
"froxel grid" visualization.

"froxel grid" is automatically enabled when "froxel debugging" is
enabled in the debug gui in gltf_viewer.


New corresponding debugging APIs were added to View.

Author: pixelflinger

filament/include/filament/View.h

@@ -27,6 +27,7 @@
 #include <utils/FixedCapacityVector.h>
 
 #include <math/mathfwd.h>
+#include <math/mat4.h>
 
 #include <utility>
 
@@ -760,6 +761,27 @@ class UTILS_PUBLIC View : public FilamentAPI {
     //! debugging: enable or disable froxel visualisation for this view.
     void setFroxelVizEnabled(bool enabled) noexcept;
 
+    //! debugging: returns information about the froxel configuration
+    struct FroxelConfigurationInfo {
+        uint8_t width;
+        uint8_t height;
+        uint8_t depth;
+        uint32_t viewportWidth;
+        uint32_t viewportHeight;
+        math::uint2 froxelDimension;
+        float zLightFar;
+        float linearizer;
+        math::mat4f p;
+        math::float4 clipTransform;
+    };
+
+    struct FroxelConfigurationInfoWithAge {
+        FroxelConfigurationInfo info;
+        uint32_t age;
+    };
+
+    FroxelConfigurationInfoWithAge getFroxelConfigurationInfo() const noexcept;
+
     /** Result of a picking query */
     struct PickingQueryResult {
         utils::Entity renderable{};     //! RenderableManager Entity at the queried coordinates

filament/src/Froxelizer.cpp

@@ -124,6 +124,20 @@ size_t Froxelizer::getFroxelBufferByteCount(FEngine::DriverApi& driverApi) noexc
     return std::min(FROXEL_BUFFER_MAX_ENTRY_COUNT * sizeof(FroxelEntry), targetSize);
 }
 
+View::FroxelConfigurationInfo Froxelizer::getFroxelConfigurationInfo() const noexcept {
+    return { uint8_t(getFroxelCountX()),
+             uint8_t(getFroxelCountY()),
+             uint8_t(getFroxelCountZ()),
+             mViewport.width,
+             mViewport.height,
+             mFroxelDimension,
+             mZLightFar,
+             mLinearizer[0],
+             mProjection,
+             mClipTransform
+    };
+}
+
 Froxelizer::Froxelizer(FEngine& engine)
         : mArena("froxel", PER_FROXELDATA_ARENA_SIZE),
           mZLightNear(FROXEL_FIRST_SLICE_DEPTH),
@@ -198,10 +212,14 @@ void Froxelizer::setProjection(const mat4f& projection,
 bool Froxelizer::prepare(
         FEngine::DriverApi& driverApi, RootArenaScope& rootArenaScope,
         filament::Viewport const& viewport,
-        const mat4f& projection, float const projectionNear, float const projectionFar) noexcept {
+        const mat4f& projection, float const projectionNear, float const projectionFar,
+        float4 const& clipTransform) noexcept {
     setViewport(viewport);
     setProjection(projection, projectionNear, projectionFar);
 
+    // Only for debugging
+    mClipTransform = clipTransform;
+
     bool uniformsNeedUpdating = false;
     if (UTILS_UNLIKELY(mDirtyFlags)) {
         uniformsNeedUpdating = update();
@@ -361,8 +379,10 @@ bool Froxelizer::update() noexcept {
                 getFroxelBufferEntryCount(), viewport);
 
         mFroxelDimension = froxelDimension;
-        mClipToFroxelX = (0.5f * float(viewport.width))  / float(froxelDimension.x);
-        mClipToFroxelY = (0.5f * float(viewport.height)) / float(froxelDimension.y);
+        // note: because froxelDimension is a power-of-two and viewport is an integer, mClipFroxel
+        // is an exact value (which is not true for 1/mClipToFroxelX, btw)
+        mClipToFroxelX = float(viewport.width)  / float(2 * froxelDimension.x);
+        mClipToFroxelY = float(viewport.height) / float(2 * froxelDimension.y);
 
         uniformsNeedUpdating = true;
 
@@ -408,8 +428,7 @@ bool Froxelizer::update() noexcept {
         }
 
         // for the inverse-transformation (view-space z to z-slice)
-        mLinearizer = 1.0f / linearizer;
-        mZLightFar = zLightFar;
+        mLinearizer = { linearizer, 1.0f / linearizer };
 
         mParamsZ[0] = 0; // updated when camera changes
         mParamsZ[1] = 0; // updated when camera changes
@@ -466,7 +485,7 @@ bool Froxelizer::update() noexcept {
             // ==> i = log2(z_screen * (far/near)) * (-1/linearizer) + zcount
             mParamsZ[0] = mZLightFar / Pw;
             mParamsZ[1] = 0.0f;
-            mParamsZ[2] = -mLinearizer;
+            mParamsZ[2] = -mLinearizer[1];
         } else {
             // orthographic projection
             // z_view = (1 - z_screen) * (near - far) - near
@@ -476,7 +495,7 @@ bool Froxelizer::update() noexcept {
             //   Pw = far / (far - near)
             mParamsZ[0] = -1.0f / (Pz * mZLightFar);  // -(far-near) / mZLightFar
             mParamsZ[1] =    Pw / (Pz * mZLightFar);  //         far / mZLightFar
-            mParamsZ[2] = mLinearizer;
+            mParamsZ[2] = mLinearizer[1];
         }
         uniformsNeedUpdating = true;
     }
@@ -507,7 +526,7 @@ size_t Froxelizer::findSliceZ(float const z) const noexcept {
 
     // This whole function is now branch-less.
 
-    int s = int( fast::log2(-z / mZLightFar) * mLinearizer + float(mFroxelCountZ) );
+    int s = int( fast::log2(-z / mZLightFar) * mLinearizer[1] + float(mFroxelCountZ) );
 
     // there are cases where z can be negative here, e.g.:
     // - the light is visible, but its center is behind the camera

filament/src/Froxelizer.h

@@ -22,6 +22,7 @@
 #include "details/Scene.h"
 #include "details/Engine.h"
 
+#include <filament/View.h>
 #include <filament/Viewport.h>
 
 #include <backend/Handle.h>
@@ -31,6 +32,7 @@
 #include <utils/Slice.h>
 
 #include <math/mat4.h>
+#include <math/vec2.h>
 #include <math/vec4.h>
 
 namespace filament {
@@ -112,7 +114,8 @@ class Froxelizer {
      * return true if updateUniforms() needs to be called
      */
     bool prepare(backend::DriverApi& driverApi, RootArenaScope& rootArenaScope, Viewport const& viewport,
-            const math::mat4f& projection, float projectionNear, float projectionFar) noexcept;
+            const math::mat4f& projection, float projectionNear, float projectionFar,
+            math::float4 const& clipTransform) noexcept;
 
     Froxel getFroxelAt(size_t x, size_t y, size_t z) const noexcept;
     size_t getFroxelCountX() const noexcept { return mFroxelCountX; }
@@ -161,6 +164,8 @@ class Froxelizer {
 
     static size_t getFroxelBufferByteCount(FEngine::DriverApi& driverApi) noexcept;
 
+    View::FroxelConfigurationInfo getFroxelConfigurationInfo() const noexcept;
+
 private:
     size_t getFroxelBufferEntryCount() const noexcept {
         return mFroxelBufferEntryCount;
@@ -260,9 +265,10 @@ class Froxelizer {
     uint16_t mFroxelCountZ = 0;
     uint32_t mFroxelCount = 0;
     math::uint2 mFroxelDimension = {};
+    math::float4 mClipTransform = { 1, 1, 0, 0 };
 
     math::mat4f mProjection;
-    float mLinearizer = 0.0f;
+    math::float2 mLinearizer{};
     float mClipToFroxelX = 0.0f;
     float mClipToFroxelY = 0.0f;
     backend::BufferObjectHandle mRecordsBuffer;

filament/src/View.cpp

@@ -81,6 +81,10 @@ void View::setFroxelVizEnabled(bool const enabled) noexcept {
     downcast(this)->setFroxelVizEnabled(enabled);
 }
 
+View::FroxelConfigurationInfoWithAge View::getFroxelConfigurationInfo() const noexcept {
+    return downcast(this)->getFroxelConfigurationInfo();
+}
+
 void View::setShadowingEnabled(bool const enabled) noexcept {
     downcast(this)->setShadowingEnabled(enabled);
 }

filament/src/details/View.cpp

@@ -659,10 +659,12 @@ void FView::prepare(FEngine& engine, DriverApi& driver, RootArenaScope& rootAren
         if (hasDynamicLighting()) {
             auto& froxelizer = mFroxelizer;
             if (froxelizer.prepare(driver, rootArenaScope, viewport,
-                    cameraInfo.projection, cameraInfo.zn, cameraInfo.zf)) {
+                    cameraInfo.projection, cameraInfo.zn, cameraInfo.zf,
+                    cameraInfo.clipTransform)) {
                 // TODO: might be more consistent to do this in prepareLighting(), but it's not
                 //       strictly necessary
                 getColorPassDescriptorSet().prepareDynamicLights(mFroxelizer, mFroxelVizEnabled);
+                mFroxelConfigurationAge++;
             }
             // We need to pass viewMatrix by value here because it extends the scope of this
             // function.
@@ -1434,6 +1436,10 @@ void FView::setStereoscopicOptions(const StereoscopicOptions& options) noexcept
     mStereoscopicOptions = options;
 }
 
+View::FroxelConfigurationInfoWithAge FView::getFroxelConfigurationInfo() const noexcept {
+    return { mFroxelizer.getFroxelConfigurationInfo(), mFroxelConfigurationAge };
+}
+
 void FView::setMaterialGlobal(uint32_t const index, float4 const& value) {
     FILAMENT_CHECK_PRECONDITION(index < 4)
             << "material global variable index (" << +index << ") out of range";

filament/src/details/View.h

@@ -244,6 +244,8 @@ class FView : public View {
         mFroxelVizEnabled = enabled;
     }
 
+    FroxelConfigurationInfoWithAge getFroxelConfigurationInfo() const noexcept;
+
     void setRenderTarget(FRenderTarget* renderTarget) noexcept {
         assert_invariant(!renderTarget || !mMultiSampleAntiAliasingOptions.enabled ||
                 !renderTarget->hasSampleableDepth());
@@ -557,6 +559,7 @@ class FView : public View {
     mutable Froxelizer mFroxelizer;
     utils::JobSystem::Job* mFroxelizerSync = nullptr;
     bool mFroxelVizEnabled = false;
+    uint32_t mFroxelConfigurationAge = 0;
 
     Viewport mViewport;
     bool mCulling = true;

filament/test/filament_test.cpp

@@ -672,7 +672,7 @@ TEST(FilamentTest, FroxelData) {
 
     Froxelizer froxelData(*engine);
     froxelData.setOptions(5, 100);
-    froxelData.prepare(engine->getDriverApi(), scope, vp, p, 0.1, 100);
+    froxelData.prepare(engine->getDriverApi(), scope, vp, p, 0.1, 100, {1,1,0,0});
 
     Froxel f = froxelData.getFroxelAt(0,0,0);
 

libs/filamentapp/CMakeLists.txt

@@ -20,6 +20,7 @@ set(MATERIAL_DIR  "${GENERATION_ROOT}/generated/material")
 set(PUBLIC_HDRS
         include/filamentapp/Config.h
         include/filamentapp/Cube.h
+        include/filamentapp/Grid.h
         include/filamentapp/FilamentApp.h
         include/filamentapp/IBL.h
         include/filamentapp/IcoSphere.h
@@ -30,6 +31,7 @@ set(PUBLIC_HDRS
 
 set(SRCS
         src/Cube.cpp
+        src/Grid.cpp
         src/FilamentApp.cpp
         src/IBL.cpp
         src/IcoSphere.cpp

libs/filamentapp/include/filamentapp/FilamentApp.h

@@ -111,6 +111,15 @@ class FilamentApp {
 
     void loadIBL(std::string_view path);
 
+
+    // debugging: enable/disable the froxel grid
+    void setCameraFrustumEnabled(bool enabled) noexcept;
+    void setDirectionalShadowFrustumEnabled(bool enabled) noexcept;
+    void setFroxelGridEnabled(bool enabled) noexcept;
+    bool isCameraFrustumEnabled() const noexcept;
+    bool isDirectionalShadowFrustumEnabled() const noexcept;
+    bool isFroxelGridEnabled() const noexcept;
+
     FilamentApp(const FilamentApp& rhs) = delete;
     FilamentApp(FilamentApp&& rhs) = delete;
     FilamentApp& operator=(const FilamentApp& rhs) = delete;
@@ -262,6 +271,10 @@ class FilamentApp {
     float mCameraNear = 0.1f;
     float mCameraFar = 100.0f;
     bool mReconfigureCameras = false;
+    uint8_t mFroxelInfoAge = 0x42;
+    uint8_t mFroxelGridEnabled = 0;
+    uint8_t mDirectionalShadowFrustumEnabled = 0x2;
+    uint8_t mCameraFrustumEnabled = 0x2;
 
 #if defined(FILAMENT_DRIVER_SUPPORTS_VULKAN)
     filament::backend::VulkanPlatform* mVulkanPlatform = nullptr;

libs/filamentapp/include/filamentapp/Grid.h

@@ -0,0 +1,71 @@
+/*
+ * Copyright (C) 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef TNT_FILAMENT_SAMPLE_GRID_H
+#define TNT_FILAMENT_SAMPLE_GRID_H
+
+#include <filament/Engine.h>
+#include <filament/Box.h>
+#include <filament/Camera.h>
+#include <filament/Material.h>
+#include <filament/MaterialInstance.h>
+
+#include <math/mat4.h>
+#include <math/vec3.h>
+
+#include <utils/Entity.h>
+
+#include <functional>
+
+class Grid {
+public:
+
+    Grid(filament::Engine& engine, filament::Material const* material,
+        filament::math::float3 linearColor);
+
+    Grid(Grid const&) = delete;
+    Grid& operator=(Grid const&) = delete;
+
+    Grid(Grid&& rhs) noexcept;
+
+    utils::Entity getWireFrameRenderable() const {
+        return mWireFrameRenderable;
+    }
+
+    ~Grid();
+
+    using Generator = std::function<float(int index)>;
+
+    void update(uint32_t width, uint32_t height, uint32_t depth);
+
+    void update(uint32_t width, uint32_t height, uint32_t depth,
+            Generator const& genWidth, Generator const& genHeight, Generator const& genDepth);
+
+    void mapFrustum(filament::Engine& engine, filament::Camera const* camera);
+    void mapFrustum(filament::Engine& engine, filament::math::mat4 const& transform);
+    void mapAabb(filament::Engine& engine, filament::Box const& box);
+
+private:
+    filament::Engine& mEngine;
+    filament::VertexBuffer* mVertexBuffer = nullptr;
+    filament::IndexBuffer* mIndexBuffer = nullptr;
+    filament::Material const* mMaterial = nullptr;
+    filament::MaterialInstance* mMaterialInstanceWireFrame = nullptr;
+    utils::Entity mWireFrameRenderable{};
+};
+
+
+#endif // TNT_FILAMENT_SAMPLE_GRID_H