Add new public API to query a sampler transform name field. (#9320)

rafadevai · web-flow · commit 9da29e3ab778 · 2025-10-21T23:55:25.000Z
* Add new public API to query a sampler transform name field.

This new API will let filament users query a Material object
the value of the `transformName` field of a specified sampler
parameter.

The transformName is an optional field, so if its not defined
by the user, it will return a nullptr value.

- A new test was added to test_filamat to validate the serialization.
- A new parameter was added to the test sandboxLit material to
validate the parsing a material with the new field.

* Addressing review comments

- Add java and js bindings for the new API
- Tests for querying the getParameterTransformName

* Use utils::ImmutableCString for transformName

* Updating release notes

* Review comments

* Addressing more review comments

- Fix comments
- For the java binding return an empty string when the
transform is not present.
diff --git a/NEW_RELEASE_NOTES.md b/NEW_RELEASE_NOTES.md
@@ -6,3 +6,6 @@
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+
+- materials: Add a new API getParameterTransformName that will return the value of the transformName field of a sampler
+parameter. [⚠️ **Recompile Materials**]
diff --git a/android/filament-android/src/main/cpp/Material.cpp b/android/filament-android/src/main/cpp/Material.cpp
@@ -279,6 +279,17 @@ Java_com_google_android_filament_Material_nHasParameter(JNIEnv* env, jclass,
     return (jboolean) hasParameter;
 }
 
+extern "C" JNIEXPORT jstring JNICALL
+Java_com_google_android_filament_Material_nGetParameterTransformName(JNIEnv* env, jclass,
+        jlong nativeMaterial, jstring samplerName_) {
+    Material* material = (Material*) nativeMaterial;
+    const char* samplerName = env->GetStringUTFChars(samplerName_, 0);
+    const char* transformName = material->getParameterTransformName(samplerName);
+    jstring transformName_ = env->NewStringUTF(transformName ? transformName : "");
+    env->ReleaseStringUTFChars(samplerName_, samplerName);
+    return transformName_;
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_Material_nCompile(JNIEnv *env, jclass clazz,
diff --git a/android/filament-android/src/main/java/com/google/android/filament/Material.java b/android/filament-android/src/main/java/com/google/android/filament/Material.java
@@ -787,6 +787,21 @@ public boolean hasParameter(@NonNull String name) {
         return nHasParameter(getNativeObject(), name);
     }
 
+    /**
+     * 
+     * Returns the name of the transform parameter associated with the given sampler parameter.
+     * In the case the parameter doesn't have a transform name field, it will return an empty string.
+     * 
+     * @param samplerName the name of the sampler parameter to query.
+     * 
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/general:parameters">
+     * General: parameters</a>
+     */
+    public String getParameterTransformName(@NonNull String samplerName) {
+        return nGetParameterTransformName(getNativeObject(), samplerName);
+    }
+
     /**
      * Sets the value of a bool parameter on this material's default instance.
      *
@@ -1111,4 +1126,5 @@ private static native void nGetParameters(long nativeMaterial,
     private static native int nGetRequiredAttributes(long nativeMaterial);
 
     private static native boolean nHasParameter(long nativeMaterial, @NonNull String name);
+    private static native String nGetParameterTransformName(long nativeMaterial, @NonNull String samplerName);
 }
diff --git a/filament/include/filament/Material.h b/filament/include/filament/Material.h
@@ -350,6 +350,19 @@ class UTILS_PUBLIC Material : public FilamentAPI {
     //! Indicates whether an existing parameter is a sampler or not.
     bool isSampler(const char* UTILS_NONNULL name) const noexcept;
 
+
+    /**
+     *
+     * Gets the name of the transform field associated for the given sampler parameter.
+     * In the case where the parameter does not have a transform name field, it will return nullptr.
+     *
+     * @param samplerName the name of the sampler parameter to query.
+     *
+     * @return If exists, the transform name value otherwise returns a nullptr.
+     */
+    const char* UTILS_NULLABLE getParameterTransformName(
+            const char* UTILS_NONNULL samplerName) const noexcept;
+
     /**
      * Sets the value of the given parameter on this material's default instance.
      *
diff --git a/filament/src/Material.cpp b/filament/src/Material.cpp
@@ -146,6 +146,10 @@ bool Material::isSampler(const char* name) const noexcept {
     return downcast(this)->isSampler(name);
 }
 
+const char* Material::getParameterTransformName(const char* samplerName) const noexcept {
+    return downcast(this)->getParameterTransformName(samplerName);
+}
+
 MaterialInstance* Material::getDefaultInstance() noexcept {
     return downcast(this)->getDefaultInstance();
 }
diff --git a/filament/src/MaterialParser.cpp b/filament/src/MaterialParser.cpp
@@ -542,6 +542,7 @@ bool ChunkSamplerInterfaceBlock::unflatten(Unflattener& unflattener,
         uint8_t fieldPrecision = 0;
         bool fieldFilterable = false;
         bool fieldMultisample = false;
+        CString fieldTransformName;
 
         if (!unflattener.read(&fieldName)) {
             return false;
@@ -571,13 +572,18 @@ bool ChunkSamplerInterfaceBlock::unflatten(Unflattener& unflattener,
             return false;
         }
 
+        if (!unflattener.read(&fieldTransformName)) {
+            return false;
+        }
+
         builder.add({ fieldName.data(), fieldName.size() },
                 SamplerInterfaceBlock::Binding(fieldBinding),
                 SamplerInterfaceBlock::Type(fieldType),
                 SamplerInterfaceBlock::Format(fieldFormat),
                 SamplerInterfaceBlock::Precision(fieldPrecision),
                 fieldFilterable,
-                fieldMultisample);
+                fieldMultisample,
+                { fieldTransformName.data(), fieldTransformName.size() });
     }
 
     *sib = builder.build();
diff --git a/filament/src/details/Material.cpp b/filament/src/details/Material.cpp
@@ -822,6 +822,15 @@ descriptor_binding_t FMaterial::getSamplerBinding(
     return mDefinition.samplerInterfaceBlock.getSamplerInfo(name)->binding;
 }
 
+const char* FMaterial::getParameterTransformName(std::string_view samplerName) const noexcept {
+    auto const& sib = getSamplerInterfaceBlock();
+    SamplerInterfaceBlock::SamplerInfo const* info = sib.getSamplerInfo(samplerName);
+    if (!info || info->transformName.empty()) {
+        return nullptr;
+    }
+    return info->transformName.c_str();
+}
+
 template bool FMaterial::setConstant<int32_t>(uint32_t id, int32_t value) noexcept;
 template bool FMaterial::setConstant<float>(uint32_t id, float value) noexcept;
 template bool FMaterial::setConstant<bool>(uint32_t id, bool value) noexcept;
diff --git a/filament/src/details/Material.h b/filament/src/details/Material.h
@@ -213,6 +213,8 @@ class FMaterial : public Material {
     backend::descriptor_binding_t getSamplerBinding(
             std::string_view const& name) const;
 
+    const char* getParameterTransformName(std::string_view samplerName) const noexcept;
+
     bool hasMaterialProperty(Property property) const noexcept {
         return bool(mDefinition.materialProperties & uint64_t(property));
     }
diff --git a/filament/test/CMakeLists.txt b/filament/test/CMakeLists.txt
@@ -16,7 +16,9 @@ file(MAKE_DIRECTORY ${RESOURCE_DIR})
 get_resgen_vars(${RESOURCE_DIR} filament_test_resources)
 
 set(RESOURCE_BINS
-        ${CMAKE_CURRENT_SOURCE_DIR}/test_material.filamat)
+        ${CMAKE_CURRENT_SOURCE_DIR}/test_material.filamat
+        ${CMAKE_CURRENT_SOURCE_DIR}/test_material_transformname.filamat
+)
 
 add_custom_command(
         OUTPUT ${RESGEN_OUTPUTS}
@@ -75,3 +77,11 @@ target_link_libraries(test_material_parser PRIVATE filament gtest)
 target_compile_options(test_material_parser PRIVATE ${COMPILER_FLAGS})
 target_include_directories(test_material_parser PRIVATE ${RESOURCE_DIR})
 set_target_properties(test_material_parser PROPERTIES FOLDER Tests)
+
+add_executable(test_material
+        filament_test_material.cpp
+        ${RESGEN_SOURCE})
+target_link_libraries(test_material PRIVATE filament gtest)
+target_compile_options(test_material PRIVATE ${COMPILER_FLAGS})
+target_include_directories(test_material PRIVATE ${RESOURCE_DIR})
+set_target_properties(test_material PROPERTIES FOLDER Tests)
diff --git a/filament/test/filament_test_material.cpp b/filament/test/filament_test_material.cpp
@@ -0,0 +1,90 @@
+/*
+ * 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 <gtest/gtest.h>
+
+#include <filament/Engine.h>
+#include <filament/Material.h>
+
+#include "filament_test_resources.h"
+
+using namespace filament;
+
+TEST(MaterialTransformName, QuerySamplerWithTransform) {
+    Engine* engine = Engine::create(Engine::Backend::DEFAULT);
+
+    Material* material = Material::Builder()
+                                 .package(FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_DATA,
+                                         FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_SIZE)
+                                 .build(*engine);
+    ASSERT_NE(material, nullptr);
+
+    EXPECT_STREQ(material->getParameterTransformName("sampler"), "transform");
+
+    engine->destroy(material);
+    Engine::destroy(engine);
+}
+
+TEST(MaterialTransformName, QueryMultipleSamplersWithTransforms) {
+    Engine* engine = Engine::create(Engine::Backend::DEFAULT);
+
+    Material* material = Material::Builder()
+                                 .package(FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_DATA,
+                                         FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_SIZE)
+                                 .build(*engine);
+    ASSERT_NE(material, nullptr);
+
+    EXPECT_STREQ(material->getParameterTransformName("sampler"), "transform");
+    EXPECT_STREQ(material->getParameterTransformName("videoTexture"), "videoTransform");
+
+    engine->destroy(material);
+    Engine::destroy(engine);
+}
+
+TEST(MaterialTransformName, QuerySamplerWithoutTransform) {
+    Engine* engine = Engine::create(Engine::Backend::DEFAULT);
+    Material* material = Material::Builder()
+                                 .package(FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_DATA,
+                                         FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_SIZE)
+                                 .build(*engine);
+    ASSERT_NE(material, nullptr);
+
+    EXPECT_EQ(material->getParameterTransformName("sampler2"), nullptr);
+
+    engine->destroy(material);
+    Engine::destroy(engine);
+}
+
+TEST(MaterialTransformName, QueryMultipleSamplersWithoutTransforms) {
+    Engine* engine = Engine::create(Engine::Backend::DEFAULT);
+
+    Material* material = Material::Builder()
+                                 .package(FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_DATA,
+                                         FILAMENT_TEST_RESOURCES_TEST_MATERIAL_TRANSFORMNAME_SIZE)
+                                 .build(*engine);
+    ASSERT_NE(material, nullptr);
+
+    EXPECT_EQ(material->getParameterTransformName("sampler1"), nullptr);
+    EXPECT_EQ(material->getParameterTransformName("sampler3"), nullptr);
+
+    engine->destroy(material);
+    Engine::destroy(engine);
+}
+
+int main(int argc, char** argv) {
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}
diff --git a/filament/test/test_material_transformname.filamat b/filament/test/test_material_transformname.filamat
diff --git a/filament/test/update_test_material.sh b/filament/test/update_test_material.sh
@@ -6,11 +6,12 @@ set -ex
 # This script updates the test material used to verify old materials can still be parsed.
 # See filament_test_material_parser.cpp.
 
-OUTPUT="filament/test/test_material.filamat"
+OUTPUT_DIR="filament/test/"
 
 ./build.sh -p desktop release matc
 MATC=out/cmake-release/tools/matc/matc
-${MATC} --platform all --api all -o ${OUTPUT} samples/materials/sandboxLit.mat
+${MATC} --platform all --api all -o ${OUTPUT_DIR}/test_material.filamat samples/materials/sandboxLit.mat
+${MATC} --platform all --api all -o ${OUTPUT_DIR}/test_material_transformname.filamat samples/materials/sandboxTransformName.mat
 
 set +x
 
diff --git a/libs/filabridge/include/private/filament/SamplerInterfaceBlock.h b/libs/filabridge/include/private/filament/SamplerInterfaceBlock.h
@@ -22,6 +22,7 @@
 
 #include <utils/CString.h>
 #include <utils/FixedCapacityVector.h>
+#include <utils/ImmutableCString.h>
 
 #include <private/filament/DescriptorSets.h>
 
@@ -55,15 +56,18 @@ class SamplerInterfaceBlock {
     using ShaderStageFlags = backend::ShaderStageFlags;
 
     struct SamplerInfo { // NOLINT(cppcoreguidelines-pro-type-member-init)
-        utils::CString name;        // name of this sampler
-        utils::CString uniformName; // name of the uniform holding this sampler (needed for glsl/MSL)
-        Binding binding;            // binding in the descriptor set
-        Type type;                  // type of this sampler
-        Format format;              // format of this sampler
-        Precision precision;        // precision of this sampler
-        bool filterable;            // whether the sampling should be filterable.
-        bool multisample;           // multisample capable
-        ShaderStageFlags stages;    // stages the sampler can be accessed from
+        utils::CString name;                    // name of this sampler
+        utils::CString uniformName;             // name of the uniform holding this
+                                                // sampler (needed for glsl/MSL)
+        Binding binding;                        // binding in the descriptor set
+        Type type;                              // type of this sampler
+        Format format;                          // format of this sampler
+        Precision precision;                    // precision of this sampler
+        bool filterable;                        // whether the sampling should be filterable.
+        bool multisample;                       // multisample capable
+        ShaderStageFlags stages;                // stages the sampler can be accessed from
+        utils::ImmutableCString transformName;  // name of the uniform holding the transform
+                                                // matrix for this sampler
     };
 
     using SamplerInfoList = utils::FixedCapacityVector<SamplerInfo>;
@@ -87,6 +91,8 @@ class SamplerInterfaceBlock {
             bool filterable;                // whether the sampling should be filterable.
             bool multisample;               // multisample capable
             ShaderStageFlags stages;        // shader stages using this sampler
+            std::string_view transformName; // name of the uniform holding the transform matrix for
+                                            // this sampler
         };
 
         // Give a name to this sampler interface block
@@ -97,7 +103,7 @@ class SamplerInterfaceBlock {
         // Add a sampler
         Builder& add(std::string_view samplerName, Binding binding, Type type, Format format,
                 Precision precision = Precision::MEDIUM, bool filterable = true,
-                bool multisample = false,
+                bool multisample = false, std::string_view transformName = "",
                 ShaderStageFlags stages = ShaderStageFlags::ALL_SHADER_STAGE_FLAGS) noexcept;
 
         // Add multiple samplers
diff --git a/libs/filabridge/src/SamplerInterfaceBlock.cpp b/libs/filabridge/src/SamplerInterfaceBlock.cpp
@@ -51,11 +51,19 @@ SamplerInterfaceBlock::Builder::stageFlags(backend::ShaderStageFlags stageFlags)
 
 SamplerInterfaceBlock::Builder& SamplerInterfaceBlock::Builder::add(std::string_view samplerName,
         Binding binding, Type type, Format format, Precision precision, bool filterable,
-        bool multisample, ShaderStageFlags stages) noexcept {
+        bool multisample, std::string_view transformName, ShaderStageFlags stages) noexcept {
     mEntries.push_back({
         { samplerName.data(), samplerName.size() }, // name
         {},                                         // uniform name
-        binding, type, format, precision, filterable, multisample, stages });
+        binding,
+        type,
+        format,
+        precision,
+        filterable,
+        multisample,
+        stages,
+        { transformName.data(), transformName.size() },
+    });
     return *this;
 }
 
@@ -66,8 +74,8 @@ SamplerInterfaceBlock SamplerInterfaceBlock::Builder::build() {
 SamplerInterfaceBlock::Builder& SamplerInterfaceBlock::Builder::add(
         std::initializer_list<ListEntry> list) noexcept {
     for (auto& e: list) {
-        add(e.name, e.binding, e.type, e.format, e.precision, e.filterable, e.multisample,
-                e.stages);
+        add(e.name, e.binding, e.type, e.format, e.precision, e.filterable,
+                e.multisample, e.transformName, e.stages);
     }
     return *this;
 }
diff --git a/libs/filamat/src/MaterialBuilder.cpp b/libs/filamat/src/MaterialBuilder.cpp
@@ -672,7 +672,7 @@ void MaterialBuilder::prepareToBuild(MaterialInfo& info) noexcept {
             ShaderStageFlags stages = param.stages.value_or(defaultShaderStages);
             sbb.add({ param.name.data(), param.name.size() }, binding, param.samplerType,
                     param.format, param.precision, param.filterable, param.multisample,
-                    stages);
+                    { param.transformName.data(), param.transformName.size() }, stages);
             if (!param.transformName.empty()) {
                 ibb.add({ { { param.transformName.data(), param.transformName.size() },
                     uint8_t(binding), 0, UniformType::MAT3, Precision::DEFAULT,
diff --git a/libs/filamat/src/eiff/MaterialInterfaceBlockChunk.cpp b/libs/filamat/src/eiff/MaterialInterfaceBlockChunk.cpp
@@ -79,6 +79,7 @@ void MaterialSamplerInterfaceBlockChunk::flatten(Flattener& f) {
         f.writeUint8(static_cast<uint8_t>(sInfo.precision));
         f.writeBool(sInfo.filterable);
         f.writeBool(sInfo.multisample);
+        f.writeString(sInfo.transformName.c_str_safe());
     }
 }
 
diff --git a/libs/filamat/tests/test_filamat.cpp b/libs/filamat/tests/test_filamat.cpp
diff --git a/samples/CMakeLists.txt b/samples/CMakeLists.txt
diff --git a/samples/materials/sandboxTransformName.mat b/samples/materials/sandboxTransformName.mat
diff --git a/web/filament-js/jsbindings.cpp b/web/filament-js/jsbindings.cpp

Original file line number	Diff line number	Diff line change
`@@ -146,6 +146,10 @@ bool Material::isSampler(const char* name) const noexcept {`
`146`	`146`	`return downcast(this)->isSampler(name);`
`147`	`147`	`}`
`148`	`148`
	`149`	`+const char* Material::getParameterTransformName(const char* samplerName) const noexcept {`
	`150`	`+ return downcast(this)->getParameterTransformName(samplerName);`
	`151`	`+}`
	`152`	`+`
`149`	`153`	`MaterialInstance* Material::getDefaultInstance() noexcept {`
`150`	`154`	`return downcast(this)->getDefaultInstance();`
`151`	`155`	`}`
Original file line number	Diff line number	Diff line change
`@@ -213,6 +213,8 @@ class FMaterial : public Material {`
`213`	`213`	`backend::descriptor_binding_t getSamplerBinding(`
`214`	`214`	`std::string_view const& name) const;`
`215`	`215`
	`216`	`+ const char* getParameterTransformName(std::string_view samplerName) const noexcept;`
	`217`	`+`
`216`	`218`	`bool hasMaterialProperty(Property property) const noexcept {`
`217`	`219`	`return bool(mDefinition.materialProperties & uint64_t(property));`
`218`	`220`	`}`