compress the DFG LUT with zstd

- use resgen to package the DFG LUT into filament, instead of using
  a large include of a C array.

- add a zstd compression step, which reduces the size from ~100KB to
  ~75KB.

The overhead of zstd is about 90KB uncompressed, however it will pay
for itself tenfold when we use it to compress material packages.

Author: pixelflinger

android/filament-android/CMakeLists.txt

@@ -67,6 +67,10 @@ add_library(abseil STATIC IMPORTED)
 set_target_properties(abseil PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libabseil.a)
 
+add_library(zstd STATIC IMPORTED)
+set_target_properties(zstd PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libzstd.a)
+
 if (FILAMENT_ENABLE_FGVIEWER)
     add_library(fgviewer STATIC IMPORTED)
     set_target_properties(fgviewer PROPERTIES IMPORTED_LOCATION
@@ -142,6 +146,7 @@ target_link_libraries(filament-jni
     PRIVATE utils
     PRIVATE perfetto
     PRIVATE abseil
+    PRIVATE zstd
 
     # libgeometry is PUBLIC because gltfio uses it.
     PUBLIC geometry

filament/CMakeLists.txt

@@ -152,6 +152,7 @@ set(SRCS
         src/fg/PassNode.cpp
         src/fg/ResourceNode.cpp
         src/fsr.cpp
+        src/ZstdHelper.cpp
 )
 
 set(PRIVATE_HDRS
@@ -235,6 +236,7 @@ set(PRIVATE_HDRS
         src/materials/fsr/ffx_a.h
         src/materials/fsr/ffx_fsr1.h
         src/materials/fsr/ffx_fsr1_mobile.fs
+        src/ZstdHelper.h
 )
 
 set(MATERIAL_SRCS
@@ -605,6 +607,28 @@ add_custom_command(
         APPEND
 )
 
+file(MAKE_DIRECTORY "${GENERATION_ROOT}/generated/data/")
+
+set(output_path_dfg_bin "${GENERATION_ROOT}/generated/data/dfg.bin")
+add_custom_command(
+        OUTPUT ${output_path_dfg_bin}
+        COMMAND cmgen --quiet --size=${DFG_LUT_SIZE} --ibl-dfg-multiscatter --ibl-dfg-cloth --ibl-dfg=${output_path_dfg_bin}
+        DEPENDS cmgen
+        COMMENT "Generating DFG LUT to ${output_path_dfg_bin}"
+)
+
+set(dfg_package_name "dfg")
+get_resgen_vars(${RESOURCE_DIR} ${dfg_package_name})
+add_custom_command(
+        OUTPUT ${RESGEN_OUTPUTS}
+        COMMAND resgen ${RESGEN_FLAGS} -Z ${output_path_dfg_bin}
+        DEPENDS resgen
+        DEPENDS ${output_path_dfg_bin}
+        COMMENT "Generating DFG resource package for ${dfg_package_name}"
+)
+list(APPEND GENERATED_RESOURCE_HDRS ${RESGEN_HEADER})
+list(APPEND GENERATED_RESOURCE_SRCS ${RESGEN_SOURCE})
+
 # Add the generated resource files to the source and header lists.
 list(APPEND PRIVATE_HDRS ${GENERATED_RESOURCE_HDRS})
 list(APPEND SRCS ${GENERATED_RESOURCE_SRCS})
@@ -613,16 +637,6 @@ if (DEFINED RESGEN_SOURCE_FLAGS)
     set_source_files_properties(${GENERATED_RESOURCE_SRCS} PROPERTIES COMPILE_FLAGS ${RESGEN_SOURCE_FLAGS})
 endif()
 
-file(MAKE_DIRECTORY "${GENERATION_ROOT}/generated/data/")
-
-set(output_path "${GENERATION_ROOT}/generated/data/dfg.inc")
-add_custom_command(
-        OUTPUT ${output_path}
-        COMMAND cmgen --quiet --size=${DFG_LUT_SIZE} --ibl-dfg-multiscatter --ibl-dfg-cloth --ibl-dfg=${output_path}
-        DEPENDS cmgen
-        COMMENT "Generating DFG LUT ${output_path}"
-)
-list(APPEND DATA_BINS ${output_path})
 
 # ==================================================================================================
 # Includes & target definition
@@ -633,7 +647,7 @@ include_directories(${GENERATION_ROOT})
 include_directories(src)
 
 # we're building a library
-add_library(${TARGET} STATIC ${PRIVATE_HDRS} ${PUBLIC_HDRS} ${SRCS} ${DATA_BINS})
+add_library(${TARGET} STATIC ${PRIVATE_HDRS} ${PUBLIC_HDRS} ${SRCS})
 
 # specify where the public headers of this library are
 target_include_directories(${TARGET} PUBLIC ${PUBLIC_HDR_DIR})
@@ -650,6 +664,7 @@ target_link_libraries(${TARGET} PUBLIC math)
 target_link_libraries(${TARGET} PUBLIC utils)
 target_link_libraries(${TARGET} PUBLIC filaflat)
 target_link_libraries(${TARGET} PUBLIC filabridge)
+target_link_libraries(${TARGET} PRIVATE zstd)
 
 if (FILAMENT_USE_ABSEIL_LOGGING)
     target_link_libraries(${TARGET} PUBLIC absl::log)

filament/src/DFG.cpp

@@ -16,32 +16,66 @@
 
 #include "DFG.h"
 
+#include "ZstdHelper.h"
+
 #include "details/Engine.h"
 #include "details/Texture.h"
 
-namespace filament {
+#include <filament/Texture.h>
+
+#include <backend/DriverEnums.h>
+
+#include <utils/debug.h>
+#include <utils/compiler.h>
+#include <utils/Panic.h>
 
-const uint16_t DFG::DFG_LUT[] = {
-#include "generated/data/dfg.inc"
-};
+#include <cstdlib>
+#include <cstdint>
+#include <cstddef>
+#include <utility>
+
+#include "generated/resources/dfg.h"
+
+namespace filament {
 
-void DFG::init(FEngine& engine) noexcept {
+void DFG::init(FEngine& engine) {
     constexpr size_t fp16Count = DFG_LUT_SIZE * DFG_LUT_SIZE * 3;
     constexpr size_t byteCount = fp16Count * sizeof(uint16_t);
 
-    static_assert(sizeof(DFG_LUT) == byteCount, "DFG_LUT_SIZE doesn't match size of the DFG LUT");
-
-    Texture* lut = Texture::Builder()
+    Texture::Builder builder = Texture::Builder()
             .width(DFG_LUT_SIZE)
             .height(DFG_LUT_SIZE)
-            .format(backend::TextureFormat::RGB16F)
-            .build(engine);
+            .format(backend::TextureFormat::RGB16F);
+
+    if (ZstdHelper::isCompressed(DFG_PACKAGE, DFG_DFG_SIZE)) {
+        const size_t decodedSize = ZstdHelper::getDecodedSize(DFG_PACKAGE, byteCount);
+        assert_invariant(decodedSize == byteCount);
+
+        // If the LUT is Zstd compressed, decompress it.
+        void* decodedData = malloc(decodedSize);
 
-    Texture::PixelBufferDescriptor buffer(DFG_LUT, byteCount,
-            Texture::Format::RGB, Texture::Type::HALF);
+        FILAMENT_CHECK_POSTCONDITION(decodedData)
+                << "Couldn't allocate " << decodedSize << " bytes for DFG LUT decompression.";
 
-    lut->setImage(engine, 0, std::move(buffer));
+        if (UTILS_LIKELY(decodedData)) {
+            bool const success = ZstdHelper::decompress(
+                    decodedData, decodedSize, DFG_PACKAGE, byteCount);
+
+            FILAMENT_CHECK_POSTCONDITION(success) << "Couldn't decompress DFG LUT.";
+
+            // Use decodedData for the texture
+            Texture* lut = builder.build(engine);
+            lut->setImage(engine, 0, { decodedData, decodedSize,
+                    Texture::Format::RGB, Texture::Type::HALF,
+                    +[](void* buffer, size_t, void*) { free(buffer); } });
+            mLUT = downcast(lut);
+            return;
+        }
+    }
 
+    assert_invariant(DFG_DFG_SIZE == byteCount);
+    Texture* lut = builder.build(engine);
+    lut->setImage(engine, 0, { DFG_PACKAGE, byteCount, Texture::Format::RGB, Texture::Type::HALF });
     mLUT = downcast(lut);
 }
 

filament/src/DFG.h

@@ -23,6 +23,9 @@
 
 #include <utils/compiler.h>
 
+#include <cstdint>
+#include <cstddef>
+
 namespace filament {
 
 class FEngine;
@@ -40,7 +43,7 @@ class DFG {
     DFG& operator=(DFG const& rhs) = delete;
     DFG& operator=(DFG&& rhs) = delete;
 
-    void init(FEngine& engine) noexcept;
+    void init(FEngine& engine);
 
     size_t getLutSize() const noexcept {
         return DFG_LUT_SIZE;
@@ -61,9 +64,6 @@ class DFG {
 
     // make sure to use the right size here
     static constexpr size_t DFG_LUT_SIZE = FILAMENT_DFG_LUT_SIZE;
-
-    // this lookup table is generated with cmgen
-    static const uint16_t DFG_LUT[];
 };
 
 #undef FILAMENT_DFG_LUT_SIZE

filament/src/ZstdHelper.cpp

@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+
+#include "ZstdHelper.h"
+
+#include <zstd.h>
+
+#include <cstddef>
+#include <cstdint>
+
+namespace filament {
+
+bool ZstdHelper::isCompressed(const void* src, size_t src_size) noexcept {
+    if (src_size < 4) {
+        return false;
+    }
+    const uint32_t magic = *static_cast<const uint32_t*>(src);
+    return magic == ZSTD_MAGICNUMBER;
+}
+
+size_t ZstdHelper::getDecodedSize(const void* src, size_t src_size) noexcept {
+    return ZSTD_getFrameContentSize(src, src_size);
+}
+
+size_t ZstdHelper::decompress(void* dst, size_t dst_size, const void* src, size_t src_size) noexcept {
+    return ZSTD_decompress(dst, dst_size, src, src_size);
+}
+
+} // namespace filament

filament/src/ZstdHelper.h

@@ -0,0 +1,55 @@
+/*
+ * 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_ZSTD_HELPER_H
+#define TNT_FILAMENT_ZSTD_HELPER_H
+
+#include <stddef.h>
+
+namespace filament {
+
+class ZstdHelper {
+public:
+    /**
+     * Checks if the given binary blob is Zstd compressed.
+     * @param src Pointer to the source data.
+     * @param src_size Size of the source data.
+     * @return True if the data is Zstd compressed, false otherwise.
+     */
+    static bool isCompressed(const void* src, size_t src_size) noexcept;
+
+    /**
+     * Returns the decompressed size of a Zstd compressed blob.
+     * @param src Pointer to the source data.
+     * @param src_size Size of the source data.
+     * @return The decompressed size, or 0 if an error occurs.
+     */
+    static size_t getDecodedSize(const void* src, size_t src_size) noexcept;
+
+    /**
+     * Decompresses a Zstd compressed blob into a pre-allocated buffer.
+     * @param dst Pointer to the destination buffer.
+     * @param dst_size Size of the destination buffer.
+     * @param src Pointer to the source data.
+     * @param src_size Size of the source data.
+     * @return The number of bytes decompressed, or 0 if an error occurs.
+     */
+    static size_t decompress(void* dst, size_t dst_size, const void* src, size_t src_size) noexcept;
+};
+
+} // namespace filament
+
+#endif // TNT_FILAMENT_ZSTD_HELPER_H

ios/samples/app-template.yml

@@ -21,7 +21,7 @@ targetTemplates:
             base:
                 OTHER_LDFLAGS: ["-lfilament", "-lbackend", "-lfilaflat", "-lktxreader",
                                 "-lfilabridge", "-lutils", "-lsmol-v", "-lgeometry", "-libl",
-                                "-labseil"]
+                                "-labseil", "-lzstd"]
                 ENABLE_BITCODE: NO
                 CLANG_CXX_LANGUAGE_STANDARD: gnu++17
                 # This allows users to not have to specify a unique bundle ID when building the sample apps.

ios/samples/backend-test/backend-test.xcodeproj/project.pbxproj

@@ -255,6 +255,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lfilamat",
 					"-force_load ../../../out/ios-debug/filament/lib/arm64/libbackend_test.a",
 				);
@@ -363,6 +364,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lfilamat",
 					"-force_load ../../../out/ios-debug/filament/lib/arm64/libbackend_test.a",
 				);
@@ -464,6 +466,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lfilamat",
 					"-force_load ../../../out/ios-debug/filament/lib/arm64/libbackend_test.a",
 				);
@@ -510,6 +513,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lfilamat",
 					"-force_load ../../../out/ios-debug/filament/lib/arm64/libbackend_test.a",
 				);

ios/samples/gltf-viewer/gltf-viewer.xcodeproj/project.pbxproj

@@ -426,6 +426,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lgltfio_core",
 					"-luberarchive",
 					"-limage",
@@ -482,6 +483,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lgltfio_core",
 					"-luberarchive",
 					"-limage",
@@ -600,6 +602,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lgltfio_core",
 					"-luberarchive",
 					"-limage",
@@ -656,6 +659,7 @@
 					"-lgeometry",
 					"-libl",
 					"-labseil",
+					"-lzstd",
 					"-lgltfio_core",
 					"-luberarchive",
 					"-limage",