diff --git a/android/filament-android/src/main/java/com/google/android/filament/Engine.java b/android/filament-android/src/main/java/com/google/android/filament/Engine.java index 43224036e30..3f0130c3835 100644 --- a/android/filament-android/src/main/java/com/google/android/filament/Engine.java +++ b/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 */ diff --git a/filament/include/filament/Engine.h b/filament/include/filament/Engine.h index ed48c528467..2ab2e20d265 100644 --- a/filament/include/filament/Engine.h +++ b/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; diff --git a/filament/src/details/Engine.cpp b/filament/src/details/Engine.cpp index 642581f005a..553a24bb979 100644 --- a/filament/src/details/Engine.cpp +++ b/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)); }