A new froxel grid vizualization for FilamentApp

filament/include/filament/View.h

@@ -27,6 +27,7 @@
 #include <utils/FixedCapacityVector.h>
 
 #include <math/mathfwd.h>
+#include <math/mat4.h>
 
 #include <utility>
 
@@ -757,6 +758,29 @@ class UTILS_PUBLIC View : public FilamentAPI {
     //! debugging: returns a Camera from the point of view of *the* dominant directional light used for shadowing.
     utils::FixedCapacityVector<Camera const*> getDirectionalShadowCameras() const noexcept;
 
+    //! 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 {

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

@@ -77,6 +77,14 @@ utils::FixedCapacityVector<Camera const*> View::getDirectionalShadowCameras() co
     return downcast(this)->getDirectionalShadowCameras();
 }
 
+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);
+                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

@@ -240,6 +240,12 @@ class FView : public View {
         return mShadowMapManager->getDirectionalShadowCameras();
     }
 
+    void setFroxelVizEnabled(bool const enabled) noexcept {
+        mFroxelVizEnabled = enabled;
+    }
+
+    FroxelConfigurationInfoWithAge getFroxelConfigurationInfo() const noexcept;
+
     void setRenderTarget(FRenderTarget* renderTarget) noexcept {
         assert_invariant(!renderTarget || !mMultiSampleAntiAliasingOptions.enabled ||
                 !renderTarget->hasSampleableDepth());
@@ -552,6 +558,8 @@ 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/src/ds/ColorPassDescriptorSet.cpp

@@ -372,12 +372,13 @@ void ColorPassDescriptorSet::prepareAmbientLight(FEngine const& engine, FIndirec
             });
 }
 
-void ColorPassDescriptorSet::prepareDynamicLights(Froxelizer& froxelizer) noexcept {
+void ColorPassDescriptorSet::prepareDynamicLights(Froxelizer& froxelizer, bool const enableFroxelViz) noexcept {
     auto& s = mUniforms.edit();
     froxelizer.updateUniforms(s);
     float const f = froxelizer.getLightFar();
     // TODO: make the falloff rate a parameter
     s.lightFarAttenuationParams = 0.5f * float2{ 10.0f, 10.0f / (f * f) };
+    s.enableFroxelViz = enableFroxelViz;
 }
 
 void ColorPassDescriptorSet::prepareShadowMapping(BufferObjectHandle shadowUniforms) noexcept {

filament/src/ds/ColorPassDescriptorSet.h

@@ -118,7 +118,7 @@ class ColorPassDescriptorSet {
     void prepareAmbientLight(FEngine const& engine,
             FIndirectLight const& ibl, float intensity, float exposure) noexcept;
 
-    void prepareDynamicLights(Froxelizer& froxelizer) noexcept;
+    void prepareDynamicLights(Froxelizer& froxelizer, bool enableFroxelViz) noexcept;
 
     void prepareShadowVSM(TextureHandle texture,
             VsmShadowOptions const& options) noexcept;

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/filabridge/include/private/filament/UibStructs.h

@@ -120,6 +120,10 @@ struct PerViewUib { // NOLINT(cppcoreguidelines-pro-type-member-init)
     math::uint3 fParams;                        // stride-x, stride-y, stride-z
     int32_t lightChannels;                      // light channel bits
     math::float2 froxelCountXY;
+    int enableFroxelViz;
+    int dynReserved0;
+    int dynReserved1;
+    int dynReserved2;
 
     // IBL
     float iblLuminance;
@@ -204,7 +208,7 @@ struct PerViewUib { // NOLINT(cppcoreguidelines-pro-type-member-init)
     float es2Reserved2;
 
     // bring PerViewUib to 2 KiB
-    math::float4 reserved[39];
+    math::float4 reserved[38];
 };
 
 // 2 KiB == 128 float4s

libs/filamat/src/shaders/UibGenerator.cpp

@@ -140,6 +140,10 @@ BufferInterfaceBlock const& UibGenerator::getPerViewUib() noexcept  {
             { "fParams",                0, Type::UINT3                   },
             { "lightChannels",          0, Type::INT                     },
             { "froxelCountXY",          0, Type::FLOAT2                  },
+            { "enableFroxelViz",        0, Type::INT                     },
+            { "dynReserved0",           0, Type::INT                     },
+            { "dynReserved1",           0, Type::INT                     },
+            { "dynReserved2",           0, Type::INT                     },
 
             { "iblLuminance",           0, Type::FLOAT,  Precision::DEFAULT, FeatureLevel::FEATURE_LEVEL_0 },
             { "iblRoughnessOneLevel",   0, Type::FLOAT,  Precision::DEFAULT, FeatureLevel::FEATURE_LEVEL_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;