Explicitly prevent upgrading from feature level 0

android/filament-android/src/main/java/com/google/android/filament/Engine.java

@@ -479,17 +479,23 @@ public FeatureLevel getSupportedFeatureLevel() {
     }
 
     /**
-     * Activate all features of a given feature level. By default FeatureLevel::FEATURE_LEVEL_1 is
-     * active. The selected feature level must not be higher than the value returned by
-     * getActiveFeatureLevel() and it's not possible lower the active feature level.
+     * Activate all features of a given feature level. If an explicit feature level is not specified
+     * at Engine initialization time via {@link Builder#featureLevel}, the default feature level is
+     * {@link FeatureLevel#FEATURE_LEVEL_0} on devices not compatible with GLES 3.0; otherwise, the
+     * default is {@link FeatureLevel::FEATURE_LEVEL_1}. The selected feature level must not be
+     * higher than the value returned by {@link #getActiveFeatureLevel} and it's not possible lower
+     * the active feature level. Additionally, it is not possible to modify the feature level at all
+     * if the Engine was initialized at {@link FeatureLevel#FEATURE_LEVEL_0}.
      *
-     * @param featureLevel the feature level to activate. If featureLevel is lower than
-     *                     getActiveFeatureLevel(), the current (higher) feature level is kept.
-     *                     If featureLevel is higher than getSupportedFeatureLevel(), an exception
-     *                     is thrown, or the program is terminated if exceptions are disabled.
+     * @param featureLevel the feature level to activate. If featureLevel is lower than {@link
+     *                     #getActiveFeatureLevel}, the current (higher) feature level is kept. If
+     *                     featureLevel is higher than {@link #getSupportedFeatureLevel}, or if the
+     *                     engine was initialized at feature level 0, an exception is thrown, or the
+     *                     program is terminated if exceptions are disabled.
      *
      * @return the active feature level.
      *
+     * @see Builder#featureLevel
      * @see #getSupportedFeatureLevel
      * @see #getActiveFeatureLevel
      */

filament/include/filament/Engine.h

@@ -176,7 +176,7 @@ class UTILS_PUBLIC Engine {
 
     /**
      * Config is used to define the memory footprint used by the engine, such as the
-     * command buffer size. Config can be used to customize engine requirements based 
+     * command buffer size. Config can be used to customize engine requirements based
      * on the applications needs.
      *
      *    .perRenderPassArenaSizeMB (default: 3 MiB)
@@ -500,17 +500,23 @@ class UTILS_PUBLIC Engine {
     FeatureLevel getSupportedFeatureLevel() const noexcept;
 
     /**
-     * Activate all features of a given feature level. By default FeatureLevel::FEATURE_LEVEL_1 is
-     * active. The selected feature level must not be higher than the value returned by
-     * getActiveFeatureLevel() and it's not possible lower the active feature level.
+     * Activate all features of a given feature level. If an explicit feature level is not specified
+     * at Engine initialization time via Builder::featureLevel, the default feature level is
+     * FeatureLevel::FEATURE_LEVEL_0 on devices not compatible with GLES 3.0; otherwise, the default
+     * is FeatureLevel::FEATURE_LEVEL_1. The selected feature level must not be higher than the
+     * value returned by getActiveFeatureLevel() and it's not possible lower the active feature
+     * level. Additionally, it is not possible to modify the feature level at all if the Engine was
+     * initialized at FeatureLevel::FEATURE_LEVEL_0.
      *
      * @param featureLevel the feature level to activate. If featureLevel is lower than
-     *                     getActiveFeatureLevel(), the current (higher) feature level is kept.
-     *                     If featureLevel is higher than getSupportedFeatureLevel(), an exception
-     *                     is thrown, or the program is terminated if exceptions are disabled.
+     *                     getActiveFeatureLevel(), the current (higher) feature level is kept. If
+     *                     featureLevel is higher than getSupportedFeatureLevel(), or if the engine
+     *                     was initialized at feature level 0, an exception is thrown, or the
+     *                     program is terminated if exceptions are disabled.
      *
      * @return the active feature level.
      *
+     * @see Builder::featureLevel
      * @see getSupportedFeatureLevel
      * @see getActiveFeatureLevel
      */
@@ -831,14 +837,14 @@ class UTILS_PUBLIC Engine {
 #if defined(__EMSCRIPTEN__)
     /**
       * WebGL only: Tells the driver to reset any internal state tracking if necessary.
-      * 
-      * This is only useful when integrating an external renderer into Filament on platforms 
+      *
+      * This is only useful when integrating an external renderer into Filament on platforms
       * like WebGL, where share contexts do not exist. Filament keeps track of the GL
       * state it has set (like which texture is bound), and does not re-set that state if
       * it does not think it needs to. However, if an external renderer has set different
       * state in the mean time, Filament will use that new state unknowingly.
-      * 
-      * If you are in this situation, call this function - ideally only once per frame, 
+      *
+      * If you are in this situation, call this function - ideally only once per frame,
       * immediately after calling Engine::execute().
       */
     void resetBackendState() noexcept;

filament/src/details/Engine.cpp

@@ -1170,6 +1170,8 @@ Engine::FeatureLevel FEngine::getSupportedFeatureLevel() const noexcept {
 Engine::FeatureLevel FEngine::setActiveFeatureLevel(FeatureLevel featureLevel) {
     ASSERT_PRECONDITION(featureLevel <= getSupportedFeatureLevel(),
             "Feature level %u not supported", (unsigned)featureLevel);
+    ASSERT_PRECONDITION(mActiveFeatureLevel >= FeatureLevel::FEATURE_LEVEL_1,
+            "Cannot adjust feature level beyond 0 at runtime");
     return (mActiveFeatureLevel = std::max(mActiveFeatureLevel, featureLevel));
 }