Merge branch 'rc/1.51.2' into release

NEW_RELEASE_NOTES.md

@@ -7,5 +7,3 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
-
-- engine: Add experimental APIs `Engine::builder::paused()` and `Engine::setPaused()`

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.51.1'
+    implementation 'com.google.android.filament:filament-android:1.51.2'
 }
 ```
 
@@ -51,7 +51,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.51.1'
+pod 'Filament', '~> 1.51.2'
 ```
 
 ### Snapshots

RELEASE_NOTES.md

@@ -7,6 +7,10 @@ A new header is inserted each time a *tag* is created.
 Instead, if you are authoring a PR for the main branch, add your release note to
 [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md).
 
+## v1.51.2
+
+- engine: Add experimental APIs `Engine::builder::paused()` and `Engine::setPaused()`
+
 ## v1.51.1
 
 

android/filament-android/src/main/cpp/RenderableManager.cpp

@@ -104,6 +104,14 @@ Java_com_google_android_filament_RenderableManager_nBuilderGeometry__JIIJJIIII(J
             (size_t) count);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nBuilderGeometryType(JNIEnv*, jclass,
+        jlong nativeBuilder, int type) {
+    RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
+    builder->geometryType((RenderableManager::Builder::GeometryType)type);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nBuilderMaterial(JNIEnv*, jclass,

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

@@ -243,9 +243,11 @@ public Builder featureLevel(FeatureLevel featureLevel) {
         /**
          * Sets the initial paused state of the rendering thread.
          *
+         * <p>Warning: This is an experimental API. See {@link Engine#setPaused(boolean)} for
+         * caveats.
+         *
          * @param paused Whether to start the rendering thread paused.
          * @return A reference to this Builder for chaining calls.
-         * @warning Experimental.
          */
         public Builder paused(boolean paused) {
             nSetBuilderPaused(mNativeBuilder, paused);
@@ -1209,7 +1211,16 @@ public void flush() {
 
     /**
      * Pause or resume the rendering thread.
-     * @warning Experimental.
+     *
+     * <p>Warning: This is an experimental API. In particular, note the following caveats.
+     *
+     * <ul><li>
+     * Buffer callbacks will never be called as long as the rendering thread is paused.
+     * Do not rely on a buffer callback to unpause the thread.
+     * </li><li>
+     * While the rendering thread is paused, rendering commands will continue to be queued until the
+     * buffer limit is reached. When the limit is reached, the program will abort.
+     * </li></ul>
      */
     public void setPaused(boolean paused) {
         nSetPaused(getNativeObject(), paused);

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

@@ -175,6 +175,32 @@ public Builder geometry(@IntRange(from = 0) int index, @NonNull PrimitiveType ty
             return this;
         }
 
+        /**
+         * Type of geometry for a Renderable
+         */
+        public enum GeometryType {
+            /** dynamic gemoetry has no restriction */
+            DYNAMIC,
+            /** bounds and world space transform are immutable */
+            STATIC_BOUNDS,
+            /** skinning/morphing not allowed and Vertex/IndexBuffer immutables */
+            STATIC
+        }
+
+        /**
+         * Specify whether this renderable has static bounds. In this context his means that
+         * the renderable's bounding box cannot change and that the renderable's transform is
+         * assumed immutable. Changing the renderable's transform via the TransformManager
+         * can lead to corrupted graphics. Note that skinning and morphing are not forbidden.
+         * Disabled by default.
+         * @param enable whether this renderable has static bounds. false by default.
+         */
+        @NonNull
+        public Builder geometryType(GeometryType type) {
+            nBuilderGeometryType(mNativeBuilder, type.ordinal());
+            return this;
+        }
+
         /**
          * Binds a material instance to the specified primitive.
          *
@@ -964,6 +990,7 @@ public long getNativeObject() {
     private static native void nBuilderGeometry(long nativeBuilder, int index, int value, long nativeVertexBuffer, long nativeIndexBuffer);
     private static native void nBuilderGeometry(long nativeBuilder, int index, int value, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int count);
     private static native void nBuilderGeometry(long nativeBuilder, int index, int value, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int minIndex, int maxIndex, int count);
+    private static native void nBuilderGeometryType(long nativeBuilder, int type);
     private static native void nBuilderMaterial(long nativeBuilder, int index, long nativeMaterialInstance);
     private static native void nBuilderBlendOrder(long nativeBuilder, int index, int blendOrder);
     private static native void nBuilderGlobalBlendOrderEnabled(long nativeBuilder, int index, boolean enabled);

android/gradle.properties

@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.51.1
+VERSION_NAME=1.51.2
 
 POM_DESCRIPTION=Real-time physically based rendering engine for Android.
 

build.sh

@@ -516,7 +516,7 @@ function build_android {
             if [[ "${BUILD_ANDROID_SAMPLES}" == "true" ]]; then
                 for sample in ${ANDROID_SAMPLES}; do
                     echo "Installing out/${sample}-debug.apk"
-                    cp samples/${sample}/build/outputs/apk/debug/${sample}-debug-unsigned.apk \
+                    cp samples/${sample}/build/outputs/apk/debug/${sample}-debug.apk \
                         ../out/${sample}-debug.apk
                 done
             fi

filament/backend/include/backend/Program.h

@@ -116,6 +116,8 @@ class Program {
 
     Program& cacheId(uint64_t cacheId) noexcept;
 
+    Program& multiview(bool multiview) noexcept;
+
     ShaderSource const& getShadersSource() const noexcept { return mShadersSource; }
     ShaderSource& getShadersSource() noexcept { return mShadersSource; }
 
@@ -143,6 +145,8 @@ class Program {
 
     uint64_t getCacheId() const noexcept { return mCacheId; }
 
+    bool isMultiview() const noexcept { return mMultiview; }
+
     CompilerPriorityQueue getPriorityQueue() const noexcept { return mPriorityQueue; }
 
 private:
@@ -158,6 +162,11 @@ class Program {
     utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> mAttributes;
     std::array<UniformInfo, Program::UNIFORM_BINDING_COUNT> mBindingUniformInfo;
     CompilerPriorityQueue mPriorityQueue = CompilerPriorityQueue::HIGH;
+    // Indicates the current engine was initialized with multiview stereo, and the variant for this
+    // program contains STE flag. This will be referred later for the OpenGL shader compiler to
+    // determine whether shader code replacement for the num_views should be performed.
+    // This variable could be promoted as a more generic variable later if other similar needs occur.
+    bool mMultiview = false;
 };
 
 } // namespace filament::backend

filament/backend/src/CommandBufferQueue.cpp

@@ -58,6 +58,7 @@ void CommandBufferQueue::requestExit() {
 }
 
 void CommandBufferQueue::setPaused(bool paused) {
+    std::lock_guard<utils::Mutex> const lock(mLock);
     if (paused) {
         mPaused = true;
     } else {
@@ -125,6 +126,9 @@ void CommandBufferQueue::flush() noexcept {
 #endif
 
         SYSTRACE_NAME("waiting: CircularBuffer::flush()");
+        ASSERT_POSTCONDITION(!mPaused,
+                "CommandStream is full, but since the rendering thread is paused, "
+                "the buffer cannot flush and we will deadlock. Instead, abort.");
         mCondition.wait(lock, [this, requiredSize]() -> bool {
             // TODO: on macOS, we need to call pumpEvents from time to time
             return mFreeSpace >= requiredSize;

filament/backend/src/Program.cpp

@@ -91,6 +91,11 @@ Program& Program::cacheId(uint64_t cacheId) noexcept {
     return *this;
 }
 
+Program& Program::multiview(bool multiview) noexcept {
+    mMultiview = multiview;
+    return *this;
+}
+
 io::ostream& operator<<(io::ostream& out, const Program& builder) {
     out << "Program{";
     builder.mLogger(out);

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -2472,7 +2472,9 @@ void OpenGLDriver::setTextureData(GLTexture* t, uint32_t level,
     size_t const stride = p.stride ? p.stride : width;
     size_t const bpp = PBD::computeDataSize(p.format, p.type, 1, 1, 1);
     size_t const bpr = PBD::computeDataSize(p.format, p.type, stride, 1, p.alignment);
-    void const* const buffer = static_cast<char const*>(p.buffer) + p.left * bpp + bpr * p.top;
+    size_t const bpl = bpr * height; // TODO: PBD should have a "layer stride"
+    void const* const buffer = static_cast<char const*>(p.buffer)
+            + bpp* p.left + bpr * p.top + bpl * 0; // TODO: PBD should have a p.depth
 
     switch (t->target) {
         case SamplerType::SAMPLER_EXTERNAL:

filament/backend/src/opengl/ShaderCompilerService.cpp

@@ -30,6 +30,7 @@
 #include <utils/Log.h>
 #include <utils/Systrace.h>
 
+#include <cctype>
 #include <chrono>
 #include <string>
 #include <string_view>
@@ -264,6 +265,7 @@ ShaderCompilerService::program_token_t ShaderCompilerService::createProgram(
                     compileShaders(gl,
                             std::move(program.getShadersSource()),
                             program.getSpecializationConstants(),
+                            program.isMultiview(),
                             shaders,
                             token->shaderSourceCode);
 
@@ -299,6 +301,7 @@ ShaderCompilerService::program_token_t ShaderCompilerService::createProgram(
         compileShaders(gl,
                 std::move(program.getShadersSource()),
                 program.getSpecializationConstants(),
+                program.isMultiview(),
                 token->gl.shaders,
                 token->shaderSourceCode);
 
@@ -501,6 +504,7 @@ GLuint ShaderCompilerService::initialize(program_token_t& token) noexcept {
 void ShaderCompilerService::compileShaders(OpenGLContext& context,
         Program::ShaderSource shadersSource,
         utils::FixedCapacityVector<Program::SpecializationConstant> const& specializationConstants,
+        bool multiview,
         std::array<GLuint, Program::SHADER_TYPE_COUNT>& outShaders,
         UTILS_UNUSED_IN_RELEASE std::array<CString, Program::SHADER_TYPE_COUNT>& outShaderSourceCode) noexcept {
 
@@ -514,8 +518,16 @@ void ShaderCompilerService::compileShaders(OpenGLContext& context,
     };
 
     std::string specializationConstantString;
+    int32_t numViews = 2;
     for (auto const& sc : specializationConstants) {
         appendSpecConstantString(specializationConstantString, sc);
+        if (sc.id == 8) {
+            // This constant must match
+            // ReservedSpecializationConstants::CONFIG_STEREO_EYE_COUNT
+            // which we can't use here because it's defined in EngineEnums.h.
+            // (we're breaking layering here, but it's for the good cause).
+            numViews = std::get<int32_t>(sc.value);
+        }
     }
     if (!specializationConstantString.empty()) {
         specializationConstantString += '\n';
@@ -544,17 +556,23 @@ void ShaderCompilerService::compileShaders(OpenGLContext& context,
 
         if (UTILS_LIKELY(!shadersSource[i].empty())) {
             Program::ShaderBlob& shader = shadersSource[i];
+            char* shader_src = reinterpret_cast<char*>(shader.data());
+            size_t shader_len = shader.size();
 
             // remove GOOGLE_cpp_style_line_directive
-            std::string_view const source = process_GOOGLE_cpp_style_line_directive(context,
-                    reinterpret_cast<char*>(shader.data()), shader.size());
+            process_GOOGLE_cpp_style_line_directive(context, shader_src, shader_len);
+
+            // replace the value of layout(num_views = X) for multiview extension
+            if (multiview && stage == ShaderStage::VERTEX) {
+                process_OVR_multiview2(context, numViews, shader_src, shader_len);
+            }
 
             // add support for ARB_shading_language_packing if needed
             auto const packingFunctions = process_ARB_shading_language_packing(context);
 
             // split shader source, so we can insert the specialization constants and the packing
             // functions
-            auto const [prolog, body] = splitShaderSource(source);
+            auto const [prolog, body] = splitShaderSource({ shader_src, shader_len });
 
             const std::array<const char*, 4> sources = {
                     prolog.data(),
@@ -577,7 +595,7 @@ void ShaderCompilerService::compileShaders(OpenGLContext& context,
 #ifndef NDEBUG
             // for debugging we return the original shader source (without the modifications we
             // made here), otherwise the line numbers wouldn't match.
-            outShaderSourceCode[i] = { source.data(), source.length() };
+            outShaderSourceCode[i] = { shader_src, shader_len };
 #endif
 
             outShaders[i] = shaderId;
@@ -586,15 +604,59 @@ void ShaderCompilerService::compileShaders(OpenGLContext& context,
 }
 
 // If usages of the Google-style line directive are present, remove them, as some
-// drivers don't allow the quotation marks. This happens in-place.
-std::string_view ShaderCompilerService::process_GOOGLE_cpp_style_line_directive(OpenGLContext& context,
+// drivers don't allow the quotation marks. This source modification happens in-place.
+void ShaderCompilerService::process_GOOGLE_cpp_style_line_directive(OpenGLContext& context,
         char* source, size_t len) noexcept {
     if (!context.ext.GOOGLE_cpp_style_line_directive) {
         if (UTILS_UNLIKELY(requestsGoogleLineDirectivesExtension({ source, len }))) {
             removeGoogleLineDirectives(source, len); // length is unaffected
         }
     }
-    return { source, len };
+}
+
+// Look up the `source` to replace the number of eyes for multiview with the given number. This is
+// necessary for OpenGL because OpenGL relies on the number specified in shader files to determine
+// the number of views, which is assumed as a single digit, for multiview.
+// This source modification happens in-place.
+void ShaderCompilerService::process_OVR_multiview2(OpenGLContext& context,
+        int32_t eyeCount, char* source, size_t len) noexcept {
+    // We don't use regular expression in favor of performance.
+    if (context.ext.OVR_multiview2) {
+        const std::string_view shader{ source, len };
+        const std::string_view layout = "layout";
+        const std::string_view num_views = "num_views";
+        size_t found = 0;
+        while (true) {
+            found = shader.find(layout, found);
+            if (found == std::string_view::npos) {
+                break;
+            }
+            found = shader.find_first_not_of(' ', found + layout.size());
+            if (found == std::string_view::npos || shader[found] != '(') {
+                continue;
+            }
+            found = shader.find_first_not_of(' ', found + 1);
+            if (found == std::string_view::npos) {
+                continue;
+            }
+            if (shader.compare(found, num_views.size(), num_views) != 0) {
+                continue;
+            }
+            found = shader.find_first_not_of(' ', found + num_views.size());
+            if (found == std::string_view::npos || shader[found] != '=') {
+                continue;
+            }
+            found = shader.find_first_not_of(' ', found + 1);
+            if (found == std::string_view::npos) {
+                continue;
+            }
+            // We assume the value should be one-digit number.
+            assert_invariant(eyeCount < 10);
+            assert_invariant(!::isdigit(source[found + 1]));
+            source[found] = '0' + eyeCount;
+            break;
+        }
+    }
 }
 
 // Tragically, OpenGL 4.1 doesn't support unpackHalf2x16 (appeared in 4.2) and

filament/backend/src/opengl/ShaderCompilerService.h

@@ -134,10 +134,14 @@ class ShaderCompilerService {
             OpenGLContext& context,
             Program::ShaderSource shadersSource,
             utils::FixedCapacityVector<Program::SpecializationConstant> const& specializationConstants,
+            bool multiview,
             std::array<GLuint, Program::SHADER_TYPE_COUNT>& outShaders,
             std::array<utils::CString, Program::SHADER_TYPE_COUNT>& outShaderSourceCode) noexcept;
 
-    static std::string_view process_GOOGLE_cpp_style_line_directive(OpenGLContext& context,
+    static void process_GOOGLE_cpp_style_line_directive(OpenGLContext& context,
+            char* source, size_t len) noexcept;
+
+    static void process_OVR_multiview2(OpenGLContext& context, int32_t eyeCount,
             char* source, size_t len) noexcept;
 
     static std::string_view process_ARB_shading_language_packing(OpenGLContext& context) noexcept;