Merge branch 'rc/1.32.4' into release

README.md

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

RELEASE_NOTES.md

@@ -7,6 +7,14 @@ 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.32.4
+
+- engine: Add support for _constant parameters_, which are constants that can be specialized after material compilation.
+- materials: improved size reduction of OpenGL/Metal shaders by ~65% when compiling materials with
+             size optimizations (`matc -S`) [⚠️ **Recompile Materials**]
+- engine: fix potential crash on Metal devices with A8X GPU (iPad Air 2) [⚠️ **Recompile Materials**]
+- opengl: support the external image on macOS
+
 ## v1.32.3
 
 - fog: added an option to disable the fog after a certain distance [⚠️ **Recompile Materials**].

android/gradle.properties

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

docs/Materials.md.html

@@ -1076,6 +1076,63 @@
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### General: constants
+
+Type
+:   array of constant objects
+
+Value
+:   Each entry is an object with the properties `name` and `type`, both of `string` type. The name
+    must be a valid GLSL identifier. Entries also have an optional `default`, which can either be a
+    `bool` or `number`, depending on the `type` of the constant. The type must be one of the types
+    described in table [materialConstantsTypes].
+
+         Type          |            Description                   |      Default
+:----------------------|:-----------------------------------------|:------------------
+int                    | A signed, 32 bit GLSL int                |         0
+float                  | A single-precision GLSL float            |         0.0
+bool                   | A GLSL bool                              |         false
+[Table [materialConstantsTypes]: Material constants types]
+
+Description
+:   Lists the constant parameters accepted by your material. These constants can be set, or
+    "specialized", at runtime when loading a material package. Multiple materials can be loaded from
+    the same material package with differing constant parameter specializations. Once a material is
+    loaded from a material package, its constant parameters cannot be changed. Compared to regular
+    parameters, constant parameters allow the compiler to generate more efficient code. Access
+    constant parameters from the shader by prefixing the name with `materialConstant_`. For example,
+    a constant parameter named `myConstant` is accessed in the shader as
+    `materialConstant_myConstant`. If a constant parameter is not set at runtime, the default is
+    used.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    constants : [
+        {
+           name : overrideAlpha,
+           type : bool
+        },
+        {
+           name : customAlpha,
+           type : float,
+           default : 0.5
+        }
+    ],
+    shadingModel : lit,
+    blending : transparent,
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        if (materialConstants_overrideAlpha) {
+            material.baseColor.a = materialConstants_customAlpha;
+            material.baseColor.rgb *= material.baseColor.a;
+        }
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ### General: variantFilter
 
 Type

filament/backend/CMakeLists.txt

@@ -96,6 +96,7 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMEN
         list(APPEND SRCS src/opengl/platforms/CocoaTouchExternalImage.mm)
     elseif (APPLE)
         list(APPEND SRCS src/opengl/platforms/PlatformCocoaGL.mm)
+        list(APPEND SRCS src/opengl/platforms/CocoaExternalImage.mm)
     elseif (WEBGL)
         list(APPEND SRCS src/opengl/platforms/PlatformWebGL.cpp)
     elseif (LINUX)

filament/backend/include/backend/DriverEnums.h

@@ -279,6 +279,15 @@ enum class UniformType : uint8_t {
     STRUCT
 };
 
+/**
+ * Supported constant parameter types
+ */
+ enum class ConstantType : uint8_t {
+  INT,
+  FLOAT,
+  BOOL
+};
+
 enum class Precision : uint8_t {
     LOW,
     MEDIUM,
@@ -1117,7 +1126,10 @@ enum class Workaround : uint16_t {
     // the whole render pass.
     ALLOW_READ_ONLY_ANCILLARY_FEEDBACK_LOOP,
     // for some uniform arrays, it's needed to do an initialization to avoid crash on adreno gpu
-    ADRENO_UNIFORM_ARRAY_CRASH
+    ADRENO_UNIFORM_ARRAY_CRASH,
+    // Workaround a Metal pipeline compilation error with the message:
+    // "Could not statically determine the target of a texture". See light_indirect.fs
+    A8X_STATIC_TEXTURE_TARGET_ERROR
 };
 
 } // namespace filament::backend

filament/backend/include/backend/platforms/PlatformCocoaGL.h

@@ -57,6 +57,10 @@ class PlatformCocoaGL : public OpenGLPlatform {
     void destroySwapChain(SwapChain* swapChain) noexcept override;
     void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
     void commit(SwapChain* swapChain) noexcept override;
+    OpenGLPlatform::ExternalTexture* createExternalImageTexture() noexcept override;
+    void destroyExternalImage(ExternalTexture* texture) noexcept override;
+    void retainExternalImage(void* externalImage) noexcept override;
+    bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept override;
 
 private:
     PlatformCocoaGLImpl* pImpl = nullptr;

filament/backend/src/metal/MetalContext.h

@@ -73,6 +73,10 @@ struct MetalContext {
         uint8_t mac;
     } highestSupportedGpuFamily;
 
+    struct {
+        bool a8xStaticTextureTargetError;
+    } bugs;
+
     // sampleCountLookup[requestedSamples] gives a <= sample count supported by the device.
     std::array<uint8_t, MAX_SAMPLE_COUNT + 1> sampleCountLookup;
 

filament/backend/src/metal/MetalDriver.mm

@@ -117,6 +117,9 @@
         sc[s] = [mContext->device supportsTextureSampleCount:s] ? s : sc[s - 1];
     }
 
+    mContext->bugs.a8xStaticTextureTargetError =
+            [mContext->device.name containsString:@"Apple A8X GPU"];
+
     mContext->commandQueue = mPlatform.createCommandQueue(mContext->device);
     mContext->pipelineStateCache.setDevice(mContext->device);
     mContext->depthStencilStateCache.setDevice(mContext->device);
@@ -719,6 +722,8 @@
             return true;
         case Workaround::ADRENO_UNIFORM_ARRAY_CRASH:
             return false;
+        case Workaround::A8X_STATIC_TEXTURE_TARGET_ERROR:
+            return mContext->bugs.a8xStaticTextureTargetError;
     }
     return false;
 }

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -1720,6 +1720,8 @@ bool OpenGLDriver::isWorkaroundNeeded(Workaround workaround) {
             return mContext.bugs.allow_read_only_ancillary_feedback_loop;
         case Workaround::ADRENO_UNIFORM_ARRAY_CRASH:
             return mContext.bugs.enable_initialize_non_used_uniform_array;
+        default:
+            return false;
     }
     return false;
 }

filament/backend/src/opengl/OpenGLProgram.cpp

@@ -40,25 +40,37 @@ static void logCompilationError(utils::io::ostream& out,
 static void logProgramLinkError(utils::io::ostream& out,
         const char* name, GLuint program) noexcept;
 
+static inline std::string to_string(bool b) noexcept {
+    return b ? "true" : "false";
+}
+
+static inline std::string to_string(int i) noexcept {
+    return std::to_string(i);
+}
+
+static inline std::string to_string(float f) noexcept {
+    return "float(" + std::to_string(f) + ")";
+}
+
 OpenGLProgram::OpenGLProgram() noexcept
     : mInitialized(false), mValid(true), mLazyInitializationData(nullptr) {
 }
 
-OpenGLProgram::OpenGLProgram(OpenGLDriver& gld, Program&& programBuilder) noexcept
-        : HwProgram(std::move(programBuilder.getName())),
+OpenGLProgram::OpenGLProgram(OpenGLDriver& gld, Program&& program) noexcept
+        : HwProgram(std::move(program.getName())),
           mInitialized(false), mValid(true),
           mLazyInitializationData{ new(LazyInitializationData) } {
 
     OpenGLContext& context = gld.getContext();
 
-    mLazyInitializationData->uniformBlockInfo = std::move(programBuilder.getUniformBlockBindings());
-    mLazyInitializationData->samplerGroupInfo = std::move(programBuilder.getSamplerGroupInfo());
+    mLazyInitializationData->uniformBlockInfo = std::move(program.getUniformBlockBindings());
+    mLazyInitializationData->samplerGroupInfo = std::move(program.getSamplerGroupInfo());
 
     // this cannot fail because we check compilation status after linking the program
     // shaders[] is filled with id of shader stages present.
     OpenGLProgram::compileShaders(context,
-            std::move(programBuilder.getShadersSource()),
-            programBuilder.getSpecializationConstants(),
+            std::move(program.getShadersSource()),
+            program.getSpecializationConstants(),
             gl.shaders,
             mLazyInitializationData->shaderSourceCode);
 
@@ -109,7 +121,7 @@ void OpenGLProgram::compileShaders(OpenGLContext& context,
     for (auto const& sc : specializationConstants) {
         specializationConstantString += "#define SPIRV_CROSS_CONSTANT_ID_" + std::to_string(sc.id) + ' ';
         specializationConstantString += std::visit([](auto&& arg) {
-            return std::to_string(arg);
+            return to_string(arg);
         }, sc.value);
         specializationConstantString += '\n';
     }

filament/backend/src/opengl/OpenGLProgram.h

@@ -38,7 +38,7 @@ class OpenGLProgram : public HwProgram {
 public:
 
     OpenGLProgram() noexcept;
-    OpenGLProgram(OpenGLDriver& gld, Program&& builder) noexcept;
+    OpenGLProgram(OpenGLDriver& gld, Program&& program) noexcept;
     ~OpenGLProgram() noexcept;
 
     bool isValid() const noexcept { return mValid; }

filament/backend/src/opengl/platforms/CocoaExternalImage.h

@@ -0,0 +1,90 @@
+/*
+ * Copyright (C) 2023 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.
+ */
+
+#ifndef FILAMENT_DRIVER_OPENGL_COCOA_EXTERNAL_IMAGE
+#define FILAMENT_DRIVER_OPENGL_COCOA_EXTERNAL_IMAGE
+
+#include <backend/platforms/OpenGLPlatform.h>
+#include <CoreVideo/CoreVideo.h>
+
+#include "../gl_headers.h"
+
+namespace filament::backend {
+
+class CocoaExternalImage final : public OpenGLPlatform::ExternalTexture {
+public:
+    /**
+     * GL objects that can be shared across multiple instances of CocoaExternalImage.
+     */
+    class SharedGl {
+    public:
+        SharedGl() noexcept;
+        ~SharedGl() noexcept;
+
+        SharedGl(const SharedGl&) = delete;
+        SharedGl& operator=(const SharedGl&) = delete;
+
+        GLuint program = 0;
+        GLuint sampler = 0;
+        GLuint fragmentShader = 0;
+        GLuint vertexShader = 0;
+    };
+
+    CocoaExternalImage(const CVOpenGLTextureCacheRef textureCache,
+            const SharedGl& sharedGl) noexcept;
+    ~CocoaExternalImage() noexcept;
+
+    /**
+     * Set this external image to the passed-in CVPixelBuffer.
+     * Afterwards, calling glGetTexture returns the GL texture name backed by the CVPixelBuffer.
+     */
+    bool set(CVPixelBufferRef p) noexcept;
+
+    GLuint getGlTexture() const noexcept;
+    GLuint getInternalFormat() const noexcept;
+    GLuint getTarget() const noexcept;
+
+private:
+    void release() noexcept;
+    CVOpenGLTextureRef createTextureFromImage(CVPixelBufferRef image) noexcept;
+    GLuint encodeCopyRectangleToTexture2D(GLuint rectangle, size_t width, size_t height) noexcept;
+
+    class State {
+    public:
+        void save() noexcept;
+        void restore() noexcept;
+
+    private:
+        GLint activeTexture = 0;
+        GLint textureBinding = { 0 };
+        GLint samplerBinding = { 0 };
+        GLint framebuffer = 0;
+        GLint viewport[4] = { 0 };
+        GLint vertexAttrib = 0;
+    } mState;
+
+    GLuint mFBO = 0;
+    const SharedGl& mSharedGl;
+    GLuint mRgbaTexture = 0;
+
+    const CVOpenGLTextureCacheRef mTextureCache;
+    CVPixelBufferRef mImage = nullptr;
+    CVOpenGLTextureRef mTexture = nullptr;
+};
+
+} // namespace filament::backend
+
+#endif