new API to return a Material's supported variants

FIXES=[297456590]

NEW_RELEASE_NOTES.md

@@ -8,4 +8,5 @@ appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
 
-- engine: remove `BloomOptions::anamorphism` which wasn't working well in most cases [**API CHANGE**] 
+- engine: remove `BloomOptions::anamorphism` which wasn't working well in most cases [**API CHANGE**] 
+- engine: new API to return a Material's supported variants, C++ only (b/297456590)

filament/include/filament/Material.h

@@ -237,6 +237,9 @@ class UTILS_PUBLIC Material : public FilamentAPI {
     //! Returns the vertex domain of this material.
     VertexDomain getVertexDomain() const noexcept;
 
+    //! Returns the material's supported variants
+    UserVariantFilterMask getSupportedVariants() const noexcept;
+
     //! Returns the material domain of this material.
     //! The material domain determines how the material is used.
     MaterialDomain getMaterialDomain() const noexcept;

filament/src/Material.cpp

@@ -141,5 +141,9 @@ void Material::compile(CompilerPriorityQueue priority, UserVariantFilterMask var
     downcast(this)->compile(priority, variantFilter, handler, std::move(callback));
 }
 
+UserVariantFilterMask Material::getSupportedVariants() const noexcept {
+    return downcast(this)->getSupportedVariants();
+}
+
 
 } // namespace filament

filament/src/MaterialParser.cpp

@@ -259,6 +259,13 @@ bool MaterialParser::getVertexDomain(VertexDomain* value) const noexcept {
     return mImpl.getFromSimpleChunk(ChunkType::MaterialVertexDomain, reinterpret_cast<uint8_t*>(value));
 }
 
+bool MaterialParser::getMaterialVariantFilterMask(UserVariantFilterMask* value) const noexcept {
+    static_assert(sizeof(UserVariantFilterMask) == sizeof(uint32_t),
+            "UserVariantFilterMask expected size is wrong");
+    return mImpl.getFromSimpleChunk(ChunkType::MaterialVariantFilterMask,
+            reinterpret_cast<UserVariantFilterMask*>(value));
+}
+
 bool MaterialParser::getMaterialDomain(MaterialDomain* value) const noexcept {
     static_assert(sizeof(MaterialDomain) == sizeof(uint8_t),
             "MaterialDomain expected size is wrong");

filament/src/MaterialParser.h

@@ -98,6 +98,7 @@ class MaterialParser {
     bool getInterpolation(Interpolation* value) const noexcept;
     bool getVertexDomain(VertexDomain* value) const noexcept;
     bool getMaterialDomain(MaterialDomain* domain) const noexcept;
+    bool getMaterialVariantFilterMask(UserVariantFilterMask* userVariantFilterMask) const noexcept;
 
     bool getShading(Shading*) const noexcept;
     bool getBlendingMode(BlendingMode*) const noexcept;

filament/src/details/Material.cpp

@@ -309,6 +309,7 @@ FMaterial::FMaterial(FEngine& engine, const Material::Builder& builder)
     parser->getInterpolation(&mInterpolation);
     parser->getVertexDomain(&mVertexDomain);
     parser->getMaterialDomain(&mMaterialDomain);
+    parser->getMaterialVariantFilterMask(&mVariantFilterMask);
     parser->getRequiredAttributes(&mRequiredAttributes);
     parser->getRefractionMode(&mRefractionMode);
     parser->getRefractionType(&mRefractionType);

filament/src/details/Material.h

@@ -117,6 +117,10 @@ class FMaterial : public Material {
     backend::RasterState getRasterState() const noexcept  { return mRasterState; }
     uint32_t getId() const noexcept { return mMaterialId; }
 
+    UserVariantFilterMask getSupportedVariants() const noexcept {
+        return UserVariantFilterMask(UserVariantFilterBit::ALL) & ~mVariantFilterMask;
+    }
+
     Shading getShading() const noexcept { return mShading; }
     Interpolation getInterpolation() const noexcept { return mInterpolation; }
     BlendingMode getBlendingMode() const noexcept { return mBlendingMode; }
@@ -220,6 +224,7 @@ class FMaterial : public Material {
     MaterialDomain mMaterialDomain = MaterialDomain::SURFACE;
     CullingMode mCullingMode = CullingMode::NONE;
     AttributeBitset mRequiredAttributes;
+    UserVariantFilterMask mVariantFilterMask = 0;
     RefractionMode mRefractionMode = RefractionMode::NONE;
     RefractionType mRefractionType = RefractionType::SOLID;
     ReflectionMode mReflectionMode = ReflectionMode::DEFAULT;

libs/filabridge/include/filament/MaterialChunkType.h

@@ -66,6 +66,7 @@ enum UTILS_PUBLIC ChunkType : uint64_t {
     MaterialSpecularAntiAliasingThreshold = charTo64bitNum("MAT_STHR"),
     MaterialClearCoatIorChange = charTo64bitNum("MAT_CIOR"),
     MaterialDomain = charTo64bitNum("MAT_DOMN"),
+    MaterialVariantFilterMask = charTo64bitNum("MAT_VFLT"),
     MaterialRefraction = charTo64bitNum("MAT_REFM"),
     MaterialRefractionType = charTo64bitNum("MAT_REFT"),
     MaterialReflectionMode = charTo64bitNum("MAT_REFL"),

libs/filamat/src/MaterialBuilder.cpp

@@ -1141,17 +1141,7 @@ Package MaterialBuilder::build(JobSystem& jobSystem) noexcept {
 
     info.samplerBindings.init(mMaterialDomain, info.sib);
 
-    // Create chunk tree.
-    ChunkContainer container;
-    writeCommonChunks(container, info);
-    if (mMaterialDomain == MaterialDomain::SURFACE) {
-        writeSurfaceChunks(container);
-    }
-
-    info.useLegacyMorphing = mUseLegacyMorphing;
-
-    // Generate all shaders and write the shader chunks.
-
+    // adjust variant-filter for feature level *before* we start writing into the container
     if (mFeatureLevel == filament::backend::FeatureLevel::FEATURE_LEVEL_0) {
         // at feature level 0, many variants are not supported
         mVariantFilter |= uint32_t(UserVariantFilterBit::DIRECTIONAL_LIGHTING);
@@ -1163,6 +1153,17 @@ Package MaterialBuilder::build(JobSystem& jobSystem) noexcept {
         mVariantFilter |= uint32_t(UserVariantFilterBit::STE);
     }
 
+    // Create chunk tree.
+    ChunkContainer container;
+    writeCommonChunks(container, info);
+    if (mMaterialDomain == MaterialDomain::SURFACE) {
+        writeSurfaceChunks(container);
+    }
+
+    info.useLegacyMorphing = mUseLegacyMorphing;
+
+    // Generate all shaders and write the shader chunks.
+
     std::vector<Variant> variants;
     switch (mMaterialDomain) {
         case MaterialDomain::SURFACE:
@@ -1373,6 +1374,11 @@ void MaterialBuilder::writeCommonChunks(ChunkContainer& container, MaterialInfo&
     container.emplace<uint32_t>(ChunkType::MaterialShaderModels, mShaderModels.getValue());
     container.emplace<uint8_t>(ChunkType::MaterialDomain, static_cast<uint8_t>(mMaterialDomain));
 
+    // if that ever needed to change, this would require a material version bump
+    static_assert(sizeof(uint32_t) >= sizeof(UserVariantFilterMask));
+
+    container.emplace<uint32_t>(ChunkType::MaterialVariantFilterMask, mVariantFilter);
+
     using namespace filament;
 
     if (info.featureLevel == FeatureLevel::FEATURE_LEVEL_0) {

libs/filamat/src/MaterialVariants.cpp

@@ -24,7 +24,7 @@ std::vector<Variant> determineSurfaceVariants(
         filament::UserVariantFilterMask userVariantFilter, bool isLit, bool shadowMultiplier) {
     std::vector<Variant> variants;
     for (size_t k = 0; k < filament::VARIANT_COUNT; k++) {
-        filament::Variant variant(k);
+        filament::Variant const variant(k);
         if (filament::Variant::isReserved(variant)) {
             continue;
         }
@@ -52,7 +52,7 @@ std::vector<Variant> determinePostProcessVariants() {
     // TODO: add a way to filter out post-process variants (e.g., the transparent variant if only
     // opaque is needed)
     for (filament::Variant::type_t k = 0; k < filament::POST_PROCESS_VARIANT_COUNT; k++) {
-        filament::Variant variant(k);
+        filament::Variant const variant(k);
         variants.emplace_back(variant, filament::backend::ShaderStage::VERTEX);
         variants.emplace_back(variant, filament::backend::ShaderStage::FRAGMENT);
     }

libs/matdbg/src/JsonWriter.cpp

@@ -90,6 +90,7 @@ static bool printMaterial(ostream& json, const ChunkContainer& container) {
     json << "\"shading\": {\n";
     printChunk<Shading, uint8_t>(json, container, MaterialShading, "model");
     printChunk<MaterialDomain, uint8_t>(json, container, ChunkType::MaterialDomain, "material_domain");
+    printChunk<UserVariantFilterMask, uint8_t>(json, container, ChunkType::MaterialVariantFilterMask, "variant_filter_mask");
     printChunk<VertexDomain, uint8_t>(json, container, MaterialVertexDomain, "vertex_domain");
     printChunk<Interpolation, uint8_t>(json, container, MaterialInterpolation, "interpolation");
     printChunk<bool, bool>(json, container, MaterialShadowMultiplier, "shadow_multiply");
@@ -112,7 +113,7 @@ static bool printMaterial(ostream& json, const ChunkContainer& container) {
     return true;
 }
 
-static bool printParametersInfo(ostream& json, const ChunkContainer& container) {
+static bool printParametersInfo(ostream&, const ChunkContainer&) {
     // TODO
     return true;
 }

libs/matdbg/src/TextWriter.cpp

@@ -112,6 +112,7 @@ static bool printMaterial(ostream& text, const ChunkContainer& container) {
     text << "Shading:" << endl;
     printChunk<Shading, uint8_t>(text, container, MaterialShading, "Model: ");
     printChunk<MaterialDomain, uint8_t>(text, container, ChunkType::MaterialDomain, "Material domain: ");
+    printChunk<UserVariantFilterMask, uint32_t>(text, container, ChunkType::MaterialVariantFilterMask, "Material Variant Filter: ");
     printChunk<VertexDomain, uint8_t>(text, container, MaterialVertexDomain, "Vertex domain: ");
     printChunk<Interpolation, uint8_t>(text, container, MaterialInterpolation, "Interpolation: ");
     printChunk<bool, bool>(text, container, MaterialShadowMultiplier, "Shadow multiply: ");