add external sampler example

Five custom variables (varyings) are now available on the condition that
the `color` attribute is not requested.

FIXES=[404930099]

.github/workflows/presubmit.yml

@@ -92,27 +92,33 @@ jobs:
 
   test-renderdiff:
     name: test-renderdiff
-    runs-on: ubuntu-22.04-4core
-
+    runs-on: macos-14-xlarge
     steps:
       - uses: actions/checkout@v4.1.6
-      - uses: ./.github/actions/ubuntu-apt-add-src
+      - name: Set up Homebrew
+        id: set-up-homebrew
+        uses: Homebrew/actions/setup-homebrew@master
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Install python prereqs
+        run: pip install mako setuptools pyyaml
       - name: Run script
         run: |
-          echo "Disabled renderdiff due to Mesa -> Currently planned outage: 2025-03-16 -> 2025-03-22"
-#          source ./build/linux/ci-common.sh && bash test/renderdiff/test.sh
+          bash test/renderdiff/test.sh
       - uses: actions/upload-artifact@v4
         with:
           name: presubmit-renderdiff-result
           path: ./out/renderdiff_tests
 
-  validate-wgsl-pipeline:
-    name: validate-wgsl-pipeline
-    runs-on: ubuntu-22.04-4core
+  validate-wgsl-webgpu:
+    name: validate-wgsl-webgpu
+    runs-on: ubuntu-22.04-8core
 
     steps:
       - uses: actions/checkout@v4.1.6
       - name: Run build script
-        run: source ./build/linux/ci-common.sh && ./build.sh -W debug test_filamat
+        run: source ./build/linux/ci-common.sh && ./build.sh -W debug test_filamat filament
       - name: Run test
-        run: ./out/cmake-debug/libs/filamat/test_filamat --gtest_filter=MaterialCompiler.Wgsl*
+        run: ./out/cmake-debug/libs/filamat/test_filamat --gtest_filter=MaterialCompiler.Wgsl*

CMakeLists.txt

@@ -139,14 +139,14 @@ else()
     set(LINUX FALSE)
 endif()
 
-if (LINUX)
-    if (NOT FILAMENT_OSMESA_PATH STREQUAL "")
-        if (NOT EXISTS ${FILAMENT_OSMESA_PATH}/)
-            message(FATAL_ERROR "Cannot find specified OSMesa build directory: ${FILAMENT_OSMESA_PATH}")
-        endif()
-        set(FILAMENT_SUPPORTS_OSMESA TRUE)
+if (NOT FILAMENT_OSMESA_PATH STREQUAL "")
+    if (NOT EXISTS ${FILAMENT_OSMESA_PATH}/)
+        message(FATAL_ERROR "Cannot find specified OSMesa build directory: ${FILAMENT_OSMESA_PATH}")
     endif()
+    set(FILAMENT_SUPPORTS_OSMESA TRUE)
+endif()
 
+if (LINUX)
     if (FILAMENT_SUPPORTS_WAYLAND)
         add_definitions(-DFILAMENT_SUPPORTS_WAYLAND)
         set(FILAMENT_SUPPORTS_X11 FALSE)
@@ -184,6 +184,12 @@ if (NOT ANDROID AND NOT WEBGL AND NOT IOS AND NOT FILAMENT_LINUX_IS_MOBILE)
     set(IS_HOST_PLATFORM TRUE)
 endif()
 
+if (APPLE)
+    if (FILAMENT_SUPPORTS_OSMESA)
+        add_definitions(-DFILAMENT_SUPPORTS_OSMESA)
+    endif()
+endif()
+
 if (WIN32)
     # Link statically against c/c++ lib to avoid missing redistriburable such as
     # "VCRUNTIME140.dll not found. Try reinstalling the app.", but give users

NEW_RELEASE_NOTES.md

@@ -7,3 +7,6 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+
+- materials: five custom variables (varyings) are now available on the condition that the `color` attribute is not requested (b/404930099). [⚠️ **New Material Version**]
+

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.58.2'
+    implementation 'com.google.android.filament:filament-android:1.58.1'
 }
 ```
 
@@ -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.58.2'
+pod 'Filament', '~> 1.58.1'
 ```
 
 ## Documentation

android/build.gradle

@@ -94,7 +94,7 @@ buildscript {
 
     ext.versions = [
         'jdk': 17,
-        'minSdk': 21,
+        'minSdk': 26,
         'targetSdk': 34,
         'compileSdk': 34,
         'kotlin': '2.0.21',
@@ -125,7 +125,7 @@ buildscript {
     ext.cmakeArgs = [
         "--no-warn-unused-cli",
         "-DANDROID_PIE=ON",
-        "-DANDROID_PLATFORM=21",
+        "-DANDROID_PLATFORM=26",
         "-DANDROID_STL=c++_static",
         "-DFILAMENT_DIST_DIR=${filamentPath}".toString(),
         "-DFILAMENT_SUPPORTS_VULKAN=${excludeVulkan ? 'OFF' : 'ON'}".toString(),
@@ -200,7 +200,7 @@ subprojects {
             ndkVersion versions.ndk
 
             defaultConfig {
-                minSdkVersion versions.minSdk
+                minSdkVersion 26
                 targetSdkVersion versions.targetSdk
 
                 externalNativeBuild {

android/filament-utils-android/CMakeLists.txt

@@ -4,6 +4,8 @@ project(filament-utils-android)
 set(FILAMENT_DIR ${FILAMENT_DIST_DIR})
 set(IMAGEIO_DIR ../../libs/imageio)
 
+set(CMAKE_SYSTEM_VERSION 26)
+
 add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../gltfio-android ${CMAKE_CURRENT_BINARY_DIR}/gltfio-android)
 
 add_library(camutils STATIC IMPORTED)
@@ -30,6 +32,10 @@ add_library(iblprefilter STATIC IMPORTED)
 set_target_properties(iblprefilter PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libfilament-iblprefilter.a)
 
+add_library(bluevk STATIC IMPORTED)
+set_target_properties(bluevk PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libbluevk.a)
+
 set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/libfilament-utils-jni.map")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")
 
@@ -57,7 +63,8 @@ target_include_directories(filament-utils-jni PRIVATE
         ..
         ../../filament/backend/include
         ${IMAGEIO_DIR}/include
-        ../../libs/utils/include)
+        ../../libs/utils/include
+        ../../libs/bluevk/include)
 
 set_target_properties(filament-utils-jni PROPERTIES LINK_DEPENDS
         ${CMAKE_CURRENT_SOURCE_DIR}/libfilament-utils-jni.symbols)
@@ -71,4 +78,6 @@ target_link_libraries(filament-utils-jni
         image
         ktxreader
         viewer
+        bluevk
+        android
 )

android/filament-utils-android/build.gradle

@@ -12,6 +12,10 @@ android {
         }
     }
 
+    defaultConfig {
+        minSdkVersion 26
+    }        
+
     packagingOptions {
         // No need to package up the following shared libs, which arise as a side effect of our
         // externalNativeBuild dependencies. When clients pick and choose from project-level gradle

android/filament-utils-android/src/main/cpp/Utils.cpp

@@ -14,12 +14,21 @@
  * limitations under the License.
  */
 
+
+#include <android/hardware_buffer.h>
+#include <android/hardware_buffer_jni.h>
 #include <jni.h>
 
 #include <filament/Engine.h>
 #include <filament/IndirectLight.h>
 #include <filament/Skybox.h>
 
+#include <backend/Platform.h>
+#include <backend/platforms/PlatformEGLAndroid.h>
+#include <backend/platforms/VulkanPlatformAndroid.h>
+
+#include <utils/Log.h>
+
 #include <ktxreader/Ktx1Reader.h>
 
 #include "common/NioUtils.h"
@@ -29,6 +38,8 @@ using namespace filament::math;
 using namespace image;
 using namespace ktxreader;
 
+using namespace filament::backend;
+
 jlong nCreateHDRTexture(JNIEnv* env, jclass,
         jlong nativeEngine, jobject javaBuffer, jint remaining, jint internalFormat);
 
@@ -79,6 +90,37 @@ static jboolean nGetSphericalHarmonics(JNIEnv* env, jclass, jobject javaBuffer,
     return success ? JNI_TRUE : JNI_FALSE;
 }
 
+static jlong nSetExternalImageOnTexture(JNIEnv* env, jclass, jlong nativeEngine, jlong nativeTexture,
+        jobject hardwareBuffer, jboolean srgb) {
+    utils::slog.e <<"--------- jni nSetExternalImageOnTexture" << utils::io::endl;
+    Engine* engine = (Engine*) nativeEngine;
+    Texture* texture = (Texture*) nativeTexture;
+
+    Platform* platform = engine->getPlatform();
+    AHardwareBuffer* nativeBuffer = nullptr;
+    if (__builtin_available(android 26, *)) {
+        nativeBuffer = AHardwareBuffer_fromHardwareBuffer(env, hardwareBuffer);
+    }
+
+    utils::slog.e <<"--------- jni nSetExternalImageOnTexture buf=" << nativeBuffer << utils::io::endl;    
+
+    if (!nativeBuffer) {
+        return 0;
+    }
+
+    if (engine->getBackend() == Backend::OPENGL) {
+        PlatformEGLAndroid* eglPlatform = (PlatformEGLAndroid*) platform;
+        auto ref = eglPlatform->createExternalImage(nativeBuffer, srgb == JNI_TRUE);
+        texture->setExternalImage(*engine, ref);
+    } else if (engine->getBackend() == Backend::VULKAN) {
+        VulkanPlatformAndroid* vulkanPlatform = (VulkanPlatformAndroid*) platform;
+        auto ref = vulkanPlatform->createExternalImage(nativeBuffer, srgb == JNI_TRUE);
+        texture->setExternalImage(*engine, ref);
+    }
+    return 0;    
+}
+
+
 JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void*) {
     JNIEnv* env;
     if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
@@ -108,5 +150,14 @@ JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void*) {
     rc = env->RegisterNatives(hdrloaderClass, hdrMethods, sizeof(hdrMethods) / sizeof(JNINativeMethod));
     if (rc != JNI_OK) return rc;
 
+    jclass loaderClass = env->FindClass("com/google/android/filament/utils/ExternalImage");
+    if (loaderClass == nullptr) return JNI_ERR;
+    static const JNINativeMethod methods[] = {
+        { (char*) "nSetExternalImageOnTexture", (char*) "(JJLandroid/hardware/HardwareBuffer;Z)J",
+            reinterpret_cast<void*>(nSetExternalImageOnTexture) },
+    };
+    rc = env->RegisterNatives(loaderClass, methods, sizeof(methods) / sizeof(JNINativeMethod));
+    if (rc != JNI_OK) return rc;    
+
     return JNI_VERSION_1_6;
 }

android/filament-utils-android/src/main/java/com/google/android/filament/utils/ExternalImage.kt

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2017 Romain Guy
+ *
+ * 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.
+ */
+
+package com.google.android.filament.utils
+
+import android.hardware.HardwareBuffer
+import com.google.android.filament.Engine
+import com.google.android.filament.Texture
+
+object ExternalImage {
+    fun setOnTexture(
+        engine: Engine,
+        texture: Texture,
+        buffer: HardwareBuffer,
+        srgb: Boolean,
+    ) {
+        val nativeEngine = engine.nativeObject
+        val nativeTexture = texture.nativeObject
+        val l = nSetExternalImageOnTexture(nativeEngine, nativeTexture, buffer, srgb)
+    }
+
+    private external fun nSetExternalImageOnTexture(
+        nativeEngine: Long,
+        nativeTexture: Long,
+        buffer: HardwareBuffer,
+        srgb: Boolean,
+    ): Long
+}

android/gradle.properties

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

android/samples/sample-external-image/.gitignore

@@ -0,0 +1,12 @@
+*.iml
+.gradle
+/local.properties
+/.idea/workspace.xml
+/.idea/libraries
+/.idea/caches
+/.idea/gradle.xml
+.DS_Store
+/build
+/captures
+/src/main/assets
+.externalNativeBuild

android/samples/sample-external-image/build.gradle

@@ -0,0 +1,55 @@
+plugins {
+    id 'com.android.application'
+    id 'kotlin-android'
+    id 'filament-tools-plugin'
+}
+
+project.ext.isSample = true
+
+kotlin {
+    jvmToolchain(versions.jdk)
+}
+
+filamentTools {
+    materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
+    materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
+}
+
+clean.doFirst {
+    delete "src/main/assets"
+}
+
+android {
+    namespace 'com.google.android.filament.externalimg'
+
+    compileSdkVersion versions.compileSdk
+    defaultConfig {
+        applicationId "com.google.android.filament.externalimg"
+        minSdkVersion 26
+        targetSdkVersion versions.targetSdk
+    }
+
+    // NOTE: This is a workaround required because the AGP task collectReleaseDependencies
+    //       is not configuration-cache friendly yet; this is only useful for Play publication
+    dependenciesInfo {
+        includeInApk = false
+    }
+
+    // We use the .filamat extension for materials compiled with matc
+    // Telling aapt to not compress them allows to load them efficiently
+    aaptOptions {
+        noCompress 'filamat', 'ktx'
+    }
+
+    compileOptions {
+        sourceCompatibility versions.jdk
+        targetCompatibility versions.jdk
+    }
+}
+
+dependencies {
+    implementation deps.kotlin
+    implementation deps.androidx.core
+    implementation project(':filament-android')
+    implementation project(':filament-utils-android')    
+}

android/samples/sample-external-image/src/main/AndroidManifest.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!--
+  Copyright (C) 2019 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.
+ -->
+
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <uses-permission android:name="android.permission.CAMERA" />
+
+  <uses-feature android:name="android.hardware.camera" />
+  <uses-feature android:name="android.hardware.camera.autofocus" />
+
+  <application
+      android:allowBackup="true"
+      android:icon="@mipmap/ic_launcher"
+      android:label="@string/app_name"
+      android:roundIcon="@mipmap/ic_launcher_round"
+      android:supportsRtl="true"
+      android:theme="@style/AppTheme">
+    <activity
+        android:exported="true"
+        android:name=".MainActivity">
+      <intent-filter>
+        <action android:name="android.intent.action.MAIN"/>
+
+        <category android:name="android.intent.category.LAUNCHER"/>
+      </intent-filter>
+    </activity>
+  </application>
+
+</manifest>

android/samples/sample-external-image/src/main/java/com/google/android/filament/externalimg/CameraHelper.kt

@@ -0,0 +1,247 @@
+/*
+ * Copyright (C) 2019 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.
+ */
+
+package com.google.android.filament.externalimg
+
+import android.app.Activity
+import android.content.Context
+import android.content.pm.PackageManager
+import android.graphics.SurfaceTexture
+import android.hardware.camera2.*
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import android.util.Size
+import android.view.Surface
+import androidx.core.content.ContextCompat
+
+import android.Manifest
+import android.graphics.ImageFormat
+import android.hardware.HardwareBuffer
+import android.media.ImageReader
+import android.opengl.Matrix
+import android.os.Build
+import android.os.Looper
+import androidx.annotation.RequiresApi
+
+import com.google.android.filament.*
+
+import java.util.concurrent.Semaphore
+import java.util.concurrent.TimeUnit
+
+/**
+ * Toy class that handles all interaction with the Android camera2 API.
+ * Sets the "textureTransform" and "videoTexture" parameters on the given Filament material.
+ */
+class CameraHelper(val activity: Activity, private val filamentEngine: Engine, private val filamentMaterial: MaterialInstance) {
+    private lateinit var cameraId: String
+    private lateinit var captureRequest: CaptureRequest
+
+    private val cameraOpenCloseLock = Semaphore(1)
+    private var backgroundHandler: Handler? = null
+    private var backgroundThread: HandlerThread? = null
+    private var cameraDevice: CameraDevice? = null
+    private var captureSession: CameraCaptureSession? = null
+    private var resolution = Size(640, 480)
+    private var filamentTexture: Texture? = null
+    private var filamentStream: Stream? = null
+    private val imageReader = ImageReader.newInstance(
+            resolution.width,
+            resolution.height,
+            ImageFormat.PRIVATE,
+            kImageReaderMaxImages,
+            HardwareBuffer.USAGE_GPU_SAMPLED_IMAGE)
+
+    @Suppress("deprecation")
+    private val display = if (Build.VERSION.SDK_INT >= 30) {
+        Api30Impl.getDisplay(activity)
+    } else {
+        activity.windowManager.defaultDisplay!!
+    }
+
+    @RequiresApi(30)
+    class Api30Impl {
+        companion object {
+            fun getDisplay(context: Context) = context.display!!
+        }
+    }
+
+    private val cameraCallback = object : CameraDevice.StateCallback() {
+        override fun onOpened(cameraDevice: CameraDevice) {
+            cameraOpenCloseLock.release()
+            this@CameraHelper.cameraDevice = cameraDevice
+            createCaptureSession()
+        }
+        override fun onDisconnected(cameraDevice: CameraDevice) {
+            cameraOpenCloseLock.release()
+            cameraDevice.close()
+            this@CameraHelper.cameraDevice = null
+        }
+        override fun onError(cameraDevice: CameraDevice, error: Int) {
+            onDisconnected(cameraDevice)
+            this@CameraHelper.activity.finish()
+        }
+    }
+
+    /**
+     * Fetches the latest image (if any) from ImageReader and passes its HardwareBuffer to Filament.
+     */
+    fun pushExternalImageToFilament() {
+        val stream = filamentStream
+        if (stream != null) {
+            imageReader.acquireLatestImage()?.also {
+                stream.setAcquiredImage(it.hardwareBuffer, Handler(Looper.getMainLooper())) {
+                    it.close()
+                }
+            }
+        }
+    }
+
+    /**
+     * Finds the front-facing Android camera, requests permission, and sets up a listener that will
+     * start a capture session as soon as the camera is ready.
+     */
+    fun openCamera() {
+        val manager = activity.getSystemService(Context.CAMERA_SERVICE) as CameraManager
+        try {
+            for (cameraId in manager.cameraIdList) {
+                val characteristics = manager.getCameraCharacteristics(cameraId)
+                val cameraDirection = characteristics.get(CameraCharacteristics.LENS_FACING)
+                if (cameraDirection != null && cameraDirection == CameraCharacteristics.LENS_FACING_FRONT) {
+                    continue
+                }
+
+                this.cameraId = cameraId
+                Log.i(kLogTag, "Selected camera $cameraId.")
+
+                val map = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) ?: continue
+                resolution = map.getOutputSizes(SurfaceTexture::class.java)[0]
+                Log.i(kLogTag, "Highest resolution is $resolution.")
+            }
+        } catch (e: CameraAccessException) {
+            Log.e(kLogTag, e.toString())
+        } catch (e: NullPointerException) {
+            Log.e(kLogTag, "Camera2 API is not supported on this device.")
+        }
+
+        val permission = ContextCompat.checkSelfPermission(this.activity, Manifest.permission.CAMERA)
+        if (permission != PackageManager.PERMISSION_GRANTED) {
+            activity.requestPermissions(arrayOf(Manifest.permission.CAMERA), kRequestCameraPermission)
+            return
+        }
+        if (!cameraOpenCloseLock.tryAcquire(2500, TimeUnit.MILLISECONDS)) {
+            throw RuntimeException("Time out waiting to lock camera opening.")
+        }
+        manager.openCamera(cameraId, cameraCallback, backgroundHandler)
+    }
+
+    fun onResume() {
+        backgroundThread = HandlerThread("CameraBackground").also { it.start() }
+        backgroundHandler = Handler(backgroundThread?.looper!!)
+    }
+
+    fun onPause() {
+        backgroundThread?.quitSafely()
+        try {
+            backgroundThread?.join()
+            backgroundThread = null
+            backgroundHandler = null
+        } catch (e: InterruptedException) {
+            Log.e(kLogTag, e.toString())
+        }
+    }
+
+    fun onRequestPermissionsResult(requestCode: Int, grantResults: IntArray): Boolean {
+        if (requestCode == kRequestCameraPermission) {
+            if (grantResults.size != 1 || grantResults[0] != PackageManager.PERMISSION_GRANTED) {
+                Log.e(kLogTag, "Unable to obtain camera position.")
+            }
+            return true
+        }
+        return false
+    }
+
+    private fun createCaptureSession() {
+        filamentStream?.apply { filamentEngine.destroyStream(this) }
+
+        // [Re]create the Filament Stream object that gets bound to the Texture.
+        filamentStream = Stream.Builder().build(filamentEngine)
+
+        // Create the Filament Texture object if we haven't done so already.
+        if (filamentTexture == null) {
+            filamentTexture = Texture.Builder()
+                    .sampler(Texture.Sampler.SAMPLER_EXTERNAL)
+                    .format(Texture.InternalFormat.RGB8)
+                    .build(filamentEngine)
+        }
+
+        // We are texturing a front-facing square shape so we need to generate a matrix that transforms (u, v, 0, 1)
+        // into a new UV coordinate according to the screen rotation and the aspect ratio of the camera image.
+        val aspectRatio = resolution.width.toFloat() / resolution.height.toFloat()
+        val textureTransform = FloatArray(16)
+        Matrix.setIdentityM(textureTransform, 0)
+        when (display.rotation) {
+            Surface.ROTATION_0 -> {
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.rotateM(textureTransform, 0, 90.0f, 0.0f, 0.0f, 1.0f)
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.scaleM(textureTransform, 0, -1.0f, 1.0f / aspectRatio, 1.0f)
+            }
+            Surface.ROTATION_90 -> {
+                Matrix.translateM(textureTransform, 0, 1.0f, 1.0f, 0.0f)
+                Matrix.rotateM(textureTransform, 0, 180.0f, 0.0f, 0.0f, 1.0f)
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.scaleM(textureTransform, 0, -1.0f / aspectRatio, 1.0f, 1.0f)
+            }
+            Surface.ROTATION_270 -> {
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.scaleM(textureTransform, 0, -1.0f / aspectRatio, 1.0f, 1.0f)
+            }
+        }
+
+        // Connect the Stream to the Texture and the Texture to the MaterialInstance.
+        val sampler = TextureSampler(TextureSampler.MinFilter.LINEAR, TextureSampler.MagFilter.LINEAR, TextureSampler.WrapMode.CLAMP_TO_EDGE)
+        filamentTexture!!.setExternalStream(filamentEngine, filamentStream!!)
+        filamentMaterial.setParameter("videoTexture", filamentTexture!!, sampler)
+        filamentMaterial.setParameter("textureTransform", MaterialInstance.FloatElement.MAT4, textureTransform, 0, 1)
+
+        // Start the capture session. You could also use TEMPLATE_PREVIEW here.
+        val captureRequestBuilder = cameraDevice!!.createCaptureRequest(CameraDevice.TEMPLATE_RECORD)
+        captureRequestBuilder.addTarget(imageReader.surface)
+
+        cameraDevice?.createCaptureSession(listOf(imageReader.surface),
+                object : CameraCaptureSession.StateCallback() {
+                    override fun onConfigured(cameraCaptureSession: CameraCaptureSession) {
+                        if (cameraDevice == null) return
+                        captureSession = cameraCaptureSession
+                        captureRequestBuilder.set(CaptureRequest.CONTROL_AF_MODE, CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE)
+                        captureRequest = captureRequestBuilder.build()
+                        captureSession!!.setRepeatingRequest(captureRequest, null, backgroundHandler)
+                        Log.i(kLogTag, "Created CaptureRequest.")
+                    }
+                    override fun onConfigureFailed(session: CameraCaptureSession) {
+                        Log.e(kLogTag, "onConfigureFailed")
+                    }
+                }, null)
+    }
+
+    companion object {
+        private const val kLogTag = "CameraHelper"
+        private const val kRequestCameraPermission = 1
+        private const val kImageReaderMaxImages = 7
+    }
+
+}

android/samples/sample-external-image/src/main/java/com/google/android/filament/externalimg/CameraHelper.kt~

@@ -0,0 +1,247 @@
+/*
+ * Copyright (C) 2019 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.
+ */
+
+package com.google.android.filament.externalimg
+
+import android.app.Activity
+import android.content.Context
+import android.content.pm.PackageManager
+import android.graphics.SurfaceTexture
+import android.hardware.camera2.*
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import android.util.Size
+import android.view.Surface
+import androidx.core.content.ContextCompat
+
+import android.Manifest
+import android.graphics.ImageFormat
+import android.hardware.HardwareBuffer
+import android.media.ImageReader
+import android.opengl.Matrix
+import android.os.Build
+import android.os.Looper
+import androidx.annotation.RequiresApi
+
+import com.google.android.filament.*
+
+import java.util.concurrent.Semaphore
+import java.util.concurrent.TimeUnit
+
+/**
+ * Toy class that handles all interaction with the Android camera2 API.
+ * Sets the "textureTransform" and "videoTexture" parameters on the given Filament material.
+ */
+class CameraHelper(val activity: Activity, private val filamentEngine: Engine, private val filamentMaterial: MaterialInstance) {
+    private lateinit var cameraId: String
+    private lateinit var captureRequest: CaptureRequest
+
+    private val cameraOpenCloseLock = Semaphore(1)
+    private var backgroundHandler: Handler? = null
+    private var backgroundThread: HandlerThread? = null
+    private var cameraDevice: CameraDevice? = null
+    private var captureSession: CameraCaptureSession? = null
+    private var resolution = Size(640, 480)
+    private var filamentTexture: Texture? = null
+    private var filamentStream: Stream? = null
+    private val imageReader = ImageReader.newInstance(
+            resolution.width,
+            resolution.height,
+            ImageFormat.PRIVATE,
+            kImageReaderMaxImages,
+            HardwareBuffer.USAGE_GPU_SAMPLED_IMAGE)
+
+    @Suppress("deprecation")
+    private val display = if (Build.VERSION.SDK_INT >= 30) {
+        Api30Impl.getDisplay(activity)
+    } else {
+        activity.windowManager.defaultDisplay!!
+    }
+
+    @RequiresApi(30)
+    class Api30Impl {
+        companion object {
+            fun getDisplay(context: Context) = context.display!!
+        }
+    }
+
+    private val cameraCallback = object : CameraDevice.StateCallback() {
+        override fun onOpened(cameraDevice: CameraDevice) {
+            cameraOpenCloseLock.release()
+            this@CameraHelper.cameraDevice = cameraDevice
+            createCaptureSession()
+        }
+        override fun onDisconnected(cameraDevice: CameraDevice) {
+            cameraOpenCloseLock.release()
+            cameraDevice.close()
+            this@CameraHelper.cameraDevice = null
+        }
+        override fun onError(cameraDevice: CameraDevice, error: Int) {
+            onDisconnected(cameraDevice)
+            this@CameraHelper.activity.finish()
+        }
+    }
+
+    /**
+     * Fetches the latest image (if any) from ImageReader and passes its HardwareBuffer to Filament.
+     */
+    fun pushExternalImageToFilament() {
+        val stream = filamentStream
+        if (stream != null) {
+            imageReader.acquireLatestImage()?.also {
+                stream.setAcquiredImage(it.hardwareBuffer, Handler(Looper.getMainLooper())) {
+                    it.close()
+                }
+            }
+        }
+    }
+
+    /**
+     * Finds the front-facing Android camera, requests permission, and sets up a listener that will
+     * start a capture session as soon as the camera is ready.
+     */
+    fun openCamera() {
+        val manager = activity.getSystemService(Context.CAMERA_SERVICE) as CameraManager
+        try {
+            for (cameraId in manager.cameraIdList) {
+                val characteristics = manager.getCameraCharacteristics(cameraId)
+                val cameraDirection = characteristics.get(CameraCharacteristics.LENS_FACING)
+                if (cameraDirection != null && cameraDirection == CameraCharacteristics.LENS_FACING_FRONT) {
+                    continue
+                }
+
+                this.cameraId = cameraId
+                Log.i(kLogTag, "Selected camera $cameraId.")
+
+                val map = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) ?: continue
+                resolution = map.getOutputSizes(SurfaceTexture::class.java)[0]
+                Log.i(kLogTag, "Highest resolution is $resolution.")
+            }
+        } catch (e: CameraAccessException) {
+            Log.e(kLogTag, e.toString())
+        } catch (e: NullPointerException) {
+            Log.e(kLogTag, "Camera2 API is not supported on this device.")
+        }
+
+        val permission = ContextCompat.checkSelfPermission(this.activity, Manifest.permission.CAMERA)
+        if (permission != PackageManager.PERMISSION_GRANTED) {
+            activity.requestPermissions(arrayOf(Manifest.permission.CAMERA), kRequestCameraPermission)
+            return
+        }
+        if (!cameraOpenCloseLock.tryAcquire(2500, TimeUnit.MILLISECONDS)) {
+            throw RuntimeException("Time out waiting to lock camera opening.")
+        }
+        manager.openCamera(cameraId, cameraCallback, backgroundHandler)
+    }
+
+    fun onResume() {
+        backgroundThread = HandlerThread("CameraBackground").also { it.start() }
+        backgroundHandler = Handler(backgroundThread?.looper!!)
+    }
+
+    fun onPause() {
+        backgroundThread?.quitSafely()
+        try {
+            backgroundThread?.join()
+            backgroundThread = null
+            backgroundHandler = null
+        } catch (e: InterruptedException) {
+            Log.e(kLogTag, e.toString())
+        }
+    }
+
+    fun onRequestPermissionsResult(requestCode: Int, grantResults: IntArray): Boolean {
+        if (requestCode == kRequestCameraPermission) {
+            if (grantResults.size != 1 || grantResults[0] != PackageManager.PERMISSION_GRANTED) {
+                Log.e(kLogTag, "Unable to obtain camera position.")
+            }
+            return true
+        }
+        return false
+    }
+
+    private fun createCaptureSession() {
+        filamentStream?.apply { filamentEngine.destroyStream(this) }
+
+        // [Re]create the Filament Stream object that gets bound to the Texture.
+        filamentStream = Stream.Builder().build(filamentEngine)
+
+        // Create the Filament Texture object if we haven't done so already.
+        if (filamentTexture == null) {
+            filamentTexture = Texture.Builder()
+                    .sampler(Texture.Sampler.SAMPLER_EXTERNAL)
+                    .format(Texture.InternalFormat.RGB8)
+                    .build(filamentEngine)
+        }
+
+        // We are texturing a front-facing square shape so we need to generate a matrix that transforms (u, v, 0, 1)
+        // into a new UV coordinate according to the screen rotation and the aspect ratio of the camera image.
+        val aspectRatio = resolution.width.toFloat() / resolution.height.toFloat()
+        val textureTransform = FloatArray(16)
+        Matrix.setIdentityM(textureTransform, 0)
+        when (display.rotation) {
+            Surface.ROTATION_0 -> {
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.rotateM(textureTransform, 0, 90.0f, 0.0f, 0.0f, 1.0f)
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.scaleM(textureTransform, 0, -1.0f, 1.0f / aspectRatio, 1.0f)
+            }
+            Surface.ROTATION_90 -> {
+                Matrix.translateM(textureTransform, 0, 1.0f, 1.0f, 0.0f)
+                Matrix.rotateM(textureTransform, 0, 180.0f, 0.0f, 0.0f, 1.0f)
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.scaleM(textureTransform, 0, -1.0f / aspectRatio, 1.0f, 1.0f)
+            }
+            Surface.ROTATION_270 -> {
+                Matrix.translateM(textureTransform, 0, 1.0f, 0.0f, 0.0f)
+                Matrix.scaleM(textureTransform, 0, -1.0f / aspectRatio, 1.0f, 1.0f)
+            }
+        }
+
+        // Connect the Stream to the Texture and the Texture to the MaterialInstance.
+        val sampler = TextureSampler(TextureSampler.MinFilter.LINEAR, TextureSampler.MagFilter.LINEAR, TextureSampler.WrapMode.CLAMP_TO_EDGE)
+        filamentTexture!!.setExternalStream(filamentEngine, filamentStream!!)
+        filamentMaterial.setParameter("videoTexture", filamentTexture!!, sampler)
+        filamentMaterial.setParameter("textureTransform", MaterialInstance.FloatElement.MAT4, textureTransform, 0, 1)
+
+        // Start the capture session. You could also use TEMPLATE_PREVIEW here.
+        val captureRequestBuilder = cameraDevice!!.createCaptureRequest(CameraDevice.TEMPLATE_RECORD)
+        captureRequestBuilder.addTarget(imageReader.surface)
+
+        cameraDevice?.createCaptureSession(listOf(imageReader.surface),
+                object : CameraCaptureSession.StateCallback() {
+                    override fun onConfigured(cameraCaptureSession: CameraCaptureSession) {
+                        if (cameraDevice == null) return
+                        captureSession = cameraCaptureSession
+                        captureRequestBuilder.set(CaptureRequest.CONTROL_AF_MODE, CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE)
+                        captureRequest = captureRequestBuilder.build()
+                        captureSession!!.setRepeatingRequest(captureRequest, null, backgroundHandler)
+                        Log.i(kLogTag, "Created CaptureRequest.")
+                    }
+                    override fun onConfigureFailed(session: CameraCaptureSession) {
+                        Log.e(kLogTag, "onConfigureFailed")
+                    }
+                }, null)
+    }
+
+    companion object {
+        private const val kLogTag = "CameraHelper"
+        private const val kRequestCameraPermission = 1
+        private const val kImageReaderMaxImages = 7
+    }
+
+}

android/samples/sample-external-image/src/main/java/com/google/android/filament/externalimg/ExternalImageHelper.kt

@@ -0,0 +1,193 @@
+import android.graphics.*
+import android.hardware.HardwareBuffer
+import android.media.Image
+import android.media.ImageReader
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import android.view.Surface
+import androidx.annotation.RequiresApi
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
+
+@RequiresApi(Build.VERSION_CODES.O)
+object CanvasToHardwareBufferUtil {
+    private const val TAG = "CanvasToHardwareBufferKt"
+    private const val IMAGE_READER_TIMEOUT_MS = 3000L // Timeout for waiting buffer
+
+    fun drawToHardwareBuffer(
+        width: Int,
+        height: Int,
+    ): HardwareBuffer? {
+        if (width <= 0 || height <= 0) {
+            Log.e(TAG, "Invalid dimensions: width=$width, height=$height")
+            return null
+        }
+
+        var handlerThread: HandlerThread? = null
+        var imageReader: ImageReader? = null
+        var surface: Surface? = null // Keep track for logging/debugging if needed
+        // Use var as it's assigned within the try block after future completion
+        var receivedHardwareBuffer: HardwareBuffer? = null
+
+        try {
+            // 1. Setup HandlerThread for ImageReader callbacks
+            handlerThread = HandlerThread("ImageReaderThreadKt").apply { start() }
+            val imageReaderHandler = Handler(handlerThread.looper)
+
+            // 2. Use CompletableFuture to wait for the buffer from the listener
+            val bufferFuture = CompletableFuture<HardwareBuffer>()
+
+            // 3. Create ImageReader
+            val usageFlags =
+                HardwareBuffer.USAGE_GPU_SAMPLED_IMAGE or
+                    HardwareBuffer.USAGE_GPU_COLOR_OUTPUT or
+                    HardwareBuffer.USAGE_CPU_READ_RARELY // Adjust as needed
+
+            imageReader =
+                ImageReader.newInstance(width, height, PixelFormat.RGBA_8888, 1, usageFlags)
+
+            // 4. Set Listener to capture the buffer
+            imageReader.setOnImageAvailableListener({ reader ->
+                var image: Image? = null
+                var hardwareBuffer: HardwareBuffer? = null
+                try {
+                    // Use `use` block for automatic image.close()
+                    image = reader.acquireLatestImage()
+                    if (image == null) {
+                        Log.w(TAG, "ImageReader listener fired but no image available.")
+                        // Complete exceptionally if buffer wasn't already completed.
+                        bufferFuture.completeExceptionally(
+                            RuntimeException("ImageReader listener fired but no image available"),
+                        )
+                        return@setOnImageAvailableListener
+                    }
+
+                    hardwareBuffer = image.hardwareBuffer
+                    if (hardwareBuffer != null) {
+                        // IMPORTANT: Don't close the HardwareBuffer here!
+                        // Transfer ownership via the CompletableFuture.
+                        if (!bufferFuture.isDone) { // Avoid completing more than once
+                            bufferFuture.complete(hardwareBuffer)
+                        } else {
+                            // Future was already completed (maybe exceptionally), close this buffer
+                            Log.w(TAG, "Future already done, closing redundant HardwareBuffer")
+                            hardwareBuffer.close()
+                        }
+                    } else {
+                        Log.e(TAG, "Failed to get HardwareBuffer from Image.")
+                        if (!bufferFuture.isDone) {
+                            bufferFuture.completeExceptionally(
+                                RuntimeException("Failed to get HardwareBuffer from Image"),
+                            )
+                        }
+                    }
+                } catch (e: Exception) {
+                    Log.e(TAG, "Error in ImageReader listener", e)
+                    if (!bufferFuture.isDone) {
+                        bufferFuture.completeExceptionally(e) // Propagate error
+                    }
+                    // If we got the buffer but failed elsewhere, ensure it's closed
+                    hardwareBuffer?.takeUnless { it.isClosed }?.close()
+                } finally {
+                    // image?.close() // Handled by acquiring reader itself or image.use{} if used
+                    image?.close() // Close image if not using `use` or if error before `use` finishes
+                }
+            }, imageReaderHandler)
+
+            // 5. Get the Surface to draw onto
+            surface =
+                imageReader.surface
+                    ?: throw RuntimeException("Failed to get Surface from ImageReader")
+
+            // 6. Lock Canvas and Draw
+            val canvas: Canvas? = surface.lockHardwareCanvas() // Use hardware accelerated canvas
+            if (canvas != null) {
+                try {
+                    // --- Your Drawing Code Here ---
+                    val paint =
+                        Paint().apply {
+                            isAntiAlias = true // Good practice
+                        }
+
+                    // Blue background
+                    paint.color = Color.BLUE
+                    canvas.drawRect(0f, 0f, width.toFloat(), height.toFloat(), paint)
+
+                    // White text
+                    paint.color = Color.WHITE
+                    paint.textSize = 40f
+                    paint.textAlign = Paint.Align.CENTER
+                    canvas.drawText(
+                        "Hello HardwareBuffer! (Kotlin)",
+                        width / 2f,
+                        height / 2f,
+                        paint,
+                    )
+                    // --- End Drawing Code ---
+                } finally {
+                    // 7. Unlock Canvas and Post
+                    surface.unlockCanvasAndPost(canvas)
+                }
+            } else {
+                throw RuntimeException("Failed to lock Hardware Canvas")
+            }
+
+            // 8. Wait for the listener to provide the HardwareBuffer
+            try {
+                // Wait for the buffer; this blocks the current thread.
+                receivedHardwareBuffer =
+                    bufferFuture.get(IMAGE_READER_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+                // Ownership of receivedHardwareBuffer is now transferred to the caller
+            } catch (timeout: TimeoutException) {
+                Log.e(TAG, "Timeout waiting for HardwareBuffer from ImageReader listener")
+                bufferFuture.cancel(true) // Attempt to cancel listener processing
+                throw timeout // Re-throw
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to draw to HardwareBuffer", e)
+            // Ensure buffer is closed if acquired but an error occurred before returning it
+            receivedHardwareBuffer?.takeUnless { it.isClosed }?.close()
+            return null // Indicate failure
+        } finally {
+            // 9. Cleanup
+            try {
+                imageReader?.close() // Also releases the Surface implicitly
+            } catch (e: Exception) {
+                Log.e(TAG, "Error closing ImageReader", e)
+            }
+            try {
+                handlerThread?.quitSafely()
+            } catch (e: Exception) {
+                Log.e(TAG, "Error quitting HandlerThread", e)
+            }
+            // Note: Do NOT close receivedHardwareBuffer here if returning successfully.
+            // The caller is responsible for closing the returned buffer.
+        }
+
+        // Return the buffer; caller MUST close it.
+        return receivedHardwareBuffer
+    }
+
+    // --- Example Usage (must be called from appropriate context/thread, like a coroutine) ---
+    /*
+    @RequiresApi(Build.VERSION_CODES.O)
+    suspend fun exampleUsage() = withContext(Dispatchers.IO) { // Run blocking code off main thread
+        val myBuffer: HardwareBuffer? = CanvasToHardwareBufferUtil.drawToHardwareBuffer(640, 480)
+
+        // Use the 'use' extension function for automatic closing
+        myBuffer?.use { buffer ->
+            // ... Use the buffer (e.g., create an EGLImage, pass to Vulkan, etc.) ...
+            Log.d(TAG, "Successfully created HardwareBuffer: $buffer. Now using it...")
+            // buffer.close() // 'use' handles this automatically
+
+        } ?: run {
+             Log.e(TAG, "Failed to create HardwareBuffer.")
+        }
+
+         Log.d(TAG,"HardwareBuffer processing finished (buffer closed if obtained).")
+    }
+     */
+}

android/samples/sample-external-image/src/main/java/com/google/android/filament/externalimg/ExternalImageHelper.kt~

@@ -0,0 +1,180 @@
+import android.graphics.*
+import android.hardware.HardwareBuffer
+import android.media.Image
+import android.media.ImageReader
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import android.view.Surface
+import androidx.annotation.RequiresApi
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
+
+@RequiresApi(Build.VERSION_CODES.O)
+object CanvasToHardwareBufferUtil {
+
+    private const val TAG = "CanvasToHardwareBufferKt"
+    private const val IMAGE_READER_TIMEOUT_MS = 3000L // Timeout for waiting buffer
+
+    fun drawToHardwareBuffer(width: Int, height: Int): HardwareBuffer? {
+        if (width <= 0 || height <= 0) {
+            Log.e(TAG, "Invalid dimensions: width=$width, height=$height")
+            return null
+        }
+
+        var handlerThread: HandlerThread? = null
+        var imageReader: ImageReader? = null
+        var surface: Surface? = null // Keep track for logging/debugging if needed
+        // Use var as it's assigned within the try block after future completion
+        var receivedHardwareBuffer: HardwareBuffer? = null
+
+        try {
+            // 1. Setup HandlerThread for ImageReader callbacks
+            handlerThread = HandlerThread("ImageReaderThreadKt").apply { start() }
+            val imageReaderHandler = Handler(handlerThread.looper)
+
+            // 2. Use CompletableFuture to wait for the buffer from the listener
+            val bufferFuture = CompletableFuture<HardwareBuffer>()
+
+            // 3. Create ImageReader
+            val usageFlags = HardwareBuffer.USAGE_GPU_SAMPLED_IMAGE or
+                    HardwareBuffer.USAGE_GPU_COLOR_OUTPUT or
+                    HardwareBuffer.USAGE_CPU_READ_RARELY // Adjust as needed
+
+            imageReader = ImageReader.newInstance(width, height, PixelFormat.RGBA_8888, 1, usageFlags)
+
+            // 4. Set Listener to capture the buffer
+            imageReader.setOnImageAvailableListener({ reader ->
+                var image: Image? = null
+                var hardwareBuffer: HardwareBuffer? = null
+                try {
+                    // Use `use` block for automatic image.close()
+                    image = reader.acquireLatestImage()
+                    if (image == null) {
+                        Log.w(TAG, "ImageReader listener fired but no image available.")
+                        // Complete exceptionally if buffer wasn't already completed.
+                        bufferFuture.completeExceptionally(RuntimeException("ImageReader listener fired but no image available"))
+                        return@setOnImageAvailableListener
+                    }
+
+                    hardwareBuffer = image.hardwareBuffer
+                    if (hardwareBuffer != null) {
+                        // IMPORTANT: Don't close the HardwareBuffer here!
+                        // Transfer ownership via the CompletableFuture.
+                        if (!bufferFuture.isDone) { // Avoid completing more than once
+                           bufferFuture.complete(hardwareBuffer)
+                        } else {
+                            // Future was already completed (maybe exceptionally), close this buffer
+                            Log.w(TAG, "Future already done, closing redundant HardwareBuffer")
+                            hardwareBuffer.close()
+                        }
+                    } else {
+                        Log.e(TAG, "Failed to get HardwareBuffer from Image.")
+                        if (!bufferFuture.isDone) {
+                            bufferFuture.completeExceptionally(RuntimeException("Failed to get HardwareBuffer from Image"))
+                        }
+                    }
+                } catch (e: Exception) {
+                    Log.e(TAG, "Error in ImageReader listener", e)
+                    if (!bufferFuture.isDone) {
+                        bufferFuture.completeExceptionally(e) // Propagate error
+                    }
+                    // If we got the buffer but failed elsewhere, ensure it's closed
+                    hardwareBuffer?.takeUnless { it.isClosed }?.close()
+                } finally {
+                    // image?.close() // Handled by acquiring reader itself or image.use{} if used
+                     image?.close() // Close image if not using `use` or if error before `use` finishes
+                }
+            }, imageReaderHandler)
+
+            // 5. Get the Surface to draw onto
+            surface = imageReader.surface ?: throw RuntimeException("Failed to get Surface from ImageReader")
+
+            // 6. Lock Canvas and Draw
+            val canvas: Canvas? = surface.lockHardwareCanvas() // Use hardware accelerated canvas
+            if (canvas != null) {
+                try {
+                    // --- Your Drawing Code Here ---
+                    val paint = Paint().apply {
+                        isAntiAlias = true // Good practice
+                    }
+
+                    // Blue background
+                    paint.color = Color.BLUE
+                    canvas.drawRect(0f, 0f, width.toFloat(), height.toFloat(), paint)
+
+                    // White text
+                    paint.color = Color.WHITE
+                    paint.textSize = 40f
+                    paint.textAlign = Paint.Align.CENTER
+                    canvas.drawText("Hello HardwareBuffer! (Kotlin)", width / 2f, height / 2f, paint)
+                    // --- End Drawing Code ---
+
+                } finally {
+                    // 7. Unlock Canvas and Post
+                    surface.unlockCanvasAndPost(canvas)
+                }
+            } else {
+                throw RuntimeException("Failed to lock Hardware Canvas")
+            }
+
+            // 8. Wait for the listener to provide the HardwareBuffer
+            try {
+                 // Wait for the buffer; this blocks the current thread.
+                receivedHardwareBuffer = bufferFuture.get(IMAGE_READER_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+                 // Ownership of receivedHardwareBuffer is now transferred to the caller
+            } catch(timeout: TimeoutException) {
+                 Log.e(TAG, "Timeout waiting for HardwareBuffer from ImageReader listener")
+                 bufferFuture.cancel(true) // Attempt to cancel listener processing
+                 throw timeout // Re-throw
+            }
+
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to draw to HardwareBuffer", e)
+            // Ensure buffer is closed if acquired but an error occurred before returning it
+            receivedHardwareBuffer?.takeUnless { it.isClosed }?.close()
+            return null // Indicate failure
+
+        } finally {
+            // 9. Cleanup
+            try {
+                 imageReader?.close() // Also releases the Surface implicitly
+            } catch (e: Exception) {
+                 Log.e(TAG, "Error closing ImageReader", e)
+            }
+            try {
+                 handlerThread?.quitSafely()
+            } catch (e: Exception) {
+                 Log.e(TAG, "Error quitting HandlerThread", e)
+            }
+            // Note: Do NOT close receivedHardwareBuffer here if returning successfully.
+            // The caller is responsible for closing the returned buffer.
+        }
+
+        // Return the buffer; caller MUST close it.
+        return receivedHardwareBuffer
+    }
+
+    // --- Example Usage (must be called from appropriate context/thread, like a coroutine) ---
+    /*
+    @RequiresApi(Build.VERSION_CODES.O)
+    suspend fun exampleUsage() = withContext(Dispatchers.IO) { // Run blocking code off main thread
+        val myBuffer: HardwareBuffer? = CanvasToHardwareBufferUtil.drawToHardwareBuffer(640, 480)
+
+        // Use the 'use' extension function for automatic closing
+        myBuffer?.use { buffer ->
+            // ... Use the buffer (e.g., create an EGLImage, pass to Vulkan, etc.) ...
+            Log.d(TAG, "Successfully created HardwareBuffer: $buffer. Now using it...")
+            // buffer.close() // 'use' handles this automatically
+
+        } ?: run {
+             Log.e(TAG, "Failed to create HardwareBuffer.")
+        }
+
+         Log.d(TAG,"HardwareBuffer processing finished (buffer closed if obtained).")
+    }
+    */
+}

android/samples/sample-external-image/src/main/java/com/google/android/filament/externalimg/MainActivity.kt

@@ -0,0 +1,469 @@
+/*
+ * Copyright (C) 2019 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.
+ */
+
+package com.google.android.filament.externalimg
+
+import android.animation.ValueAnimator
+import android.app.Activity
+import android.hardware.HardwareBuffer
+import android.opengl.Matrix
+import android.os.Bundle
+import android.view.Choreographer
+import android.view.Surface
+import android.view.SurfaceView
+import android.view.animation.LinearInterpolator
+import androidx.core.app.ActivityCompat
+
+import com.google.android.filament.*
+import com.google.android.filament.RenderableManager.*
+import com.google.android.filament.VertexBuffer.*
+import com.google.android.filament.android.DisplayHelper
+import com.google.android.filament.android.FilamentHelper
+import com.google.android.filament.android.UiHelper
+import com.google.android.filament.utils.ExternalImage
+import com.google.android.filament.utils.Utils
+
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.nio.channels.Channels
+
+import kotlin.math.*
+
+import android.util.Log
+
+class MainActivity : Activity(), ActivityCompat.OnRequestPermissionsResultCallback {
+    companion object {
+        init {
+            Filament.init()
+        }
+    }
+
+    private var TAG = "filament.externalimg"
+
+    private lateinit var surfaceView: SurfaceView
+    private lateinit var uiHelper: UiHelper
+    private lateinit var displayHelper: DisplayHelper
+    private lateinit var choreographer: Choreographer
+
+    private lateinit var engine: Engine
+    private lateinit var renderer: Renderer
+    private lateinit var scene: Scene
+    private lateinit var view: View
+
+    // This is the Filament camera, not the phone camera. :)
+    private lateinit var camera: Camera
+
+    private var filamentTexture: Texture? = null
+
+    // Other Filament objects:
+    private lateinit var material: Material
+    private lateinit var materialInstance: MaterialInstance
+    private lateinit var vertexBuffer: VertexBuffer
+    private lateinit var indexBuffer: IndexBuffer
+
+    // Filament entity representing a renderable object
+    @Entity private var renderable = 0
+    @Entity private var light = 0
+
+    private var myCount : Int = 0
+
+    // A swap chain is Filament's representation of a surface
+    private var swapChain: SwapChain? = null
+
+    // Performs the rendering and schedules new frames
+    private val frameScheduler = FrameCallback()
+
+    private val animator = ValueAnimator.ofFloat(0.0f, 50.0f)
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        Utils.init()
+
+        surfaceView = SurfaceView(this)
+        setContentView(surfaceView)
+
+        choreographer = Choreographer.getInstance()
+
+        displayHelper = DisplayHelper(this)
+
+        setupSurfaceView()
+        setupFilament()
+        setupView()
+        setupScene()
+
+//        ExternalImage.setOnTexture(engine,, texture, buffer, srgb)
+
+//        cameraHelper = CameraHelper(this, engine, materialInstance)
+//        cameraHelper.openCamera()
+    }
+
+    private fun setupSurfaceView() {
+        uiHelper = UiHelper(UiHelper.ContextErrorPolicy.DONT_CHECK)
+        uiHelper.renderCallback = SurfaceCallback()
+        uiHelper.attachTo(surfaceView)
+    }
+
+    private fun setupFilament() {
+        engine = Engine.create()
+        renderer = engine.createRenderer()
+        scene = engine.createScene()
+        view = engine.createView()
+        camera = engine.createCamera(engine.entityManager.create())
+
+    }
+
+    private fun setupView() {
+        scene.skybox = Skybox.Builder().color(0.035f, 0.035f, 0.035f, 1.0f).build(engine)
+        view.camera = camera
+        view.scene = scene
+    }
+
+    private fun setupScene() {
+        loadMaterial()
+        setupMaterial()
+        createMesh()
+
+        // To create a renderable we first create a generic entity
+        renderable = EntityManager.get().create()
+
+        // We then create a renderable component on that entity
+        // A renderable is made of several primitives; in this case we declare only 1
+        // If we wanted each face of the cube to have a different material, we could
+        // declare 6 primitives (1 per face) and give each of them a different material
+        // instance, setup with different parameters
+        RenderableManager.Builder(1)
+                // Overall bounding box of the renderable
+                .boundingBox(Box(0.0f, 0.0f, 0.0f, 1.0f, 1.0f, 1.0f))
+                // Sets the mesh data of the first primitive, 6 faces of 6 indices each
+                .geometry(0, PrimitiveType.TRIANGLES, vertexBuffer, indexBuffer, 0, 6 * 6)
+                // Sets the material of the first primitive
+                .material(0, materialInstance)
+                .build(engine, renderable)
+
+        // Add the entity to the scene to render it
+        scene.addEntity(renderable)
+
+        // We now need a light, let's create a directional light
+        light = EntityManager.get().create()
+
+        // Create a color from a temperature (5,500K)
+        val (r, g, b) = Colors.cct(5_500.0f)
+        LightManager.Builder(LightManager.Type.DIRECTIONAL)
+                .color(r, g, b)
+                // Intensity of the sun in lux on a clear day
+                .intensity(110_000.0f)
+                // The direction is normalized on our behalf
+                .direction(0.0f, -0.5f, -1.0f)
+                .castShadows(true)
+                .build(engine, light)
+
+        // Add the entity to the scene to light it
+        scene.addEntity(light)
+
+        // Set the exposure on the camera, this exposure follows the sunny f/16 rule
+        // Since we've defined a light that has the same intensity as the sun, it
+        // guarantees a proper exposure
+        camera.setExposure(16.0f, 1.0f / 125.0f, 100.0f)
+
+        // Move the camera back to see the object
+        camera.lookAt(0.0, 0.0, 6.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0)
+
+        startAnimation()
+    }
+
+    private fun loadMaterial() {
+        readUncompressedAsset("materials/lit.filamat").let {
+            material = Material.Builder().payload(it, it.remaining()).build(engine)
+        }
+    }
+
+    private fun setupMaterial() {
+        materialInstance = material.createInstance()
+        materialInstance.setParameter("baseColor", Colors.RgbType.SRGB, 1.0f, 0.85f, 0.57f)
+        materialInstance.setParameter("roughness", 0.3f)
+
+        val textureTransform = FloatArray(16)
+        Matrix.setIdentityM(textureTransform, 0)
+
+        filamentTexture = Texture.Builder()
+            .sampler(Texture.Sampler.SAMPLER_EXTERNAL)
+            .width(400)
+            .height(400)        
+            .format(Texture.InternalFormat.RGBA8)
+            .build(engine)
+
+        val sampler = TextureSampler(TextureSampler.MinFilter.LINEAR, TextureSampler.MagFilter.LINEAR, TextureSampler.WrapMode.CLAMP_TO_EDGE)
+        materialInstance.setParameter("videoTexture", filamentTexture!!, sampler)
+        materialInstance.setParameter("textureTransform", MaterialInstance.FloatElement.MAT4, textureTransform, 0, 1)
+    }
+
+    private fun createMesh() {
+        val floatSize = 4
+        val shortSize = 2
+        // A vertex is a position + a tangent frame:
+        // 3 floats for XYZ position, 4 floats for normal+tangents (quaternion)
+        val vertexSize = 3 * floatSize + 4 * floatSize
+
+        // Define a vertex and a function to put a vertex in a ByteBuffer
+        @Suppress("ArrayInDataClass")
+        data class Vertex(val x: Float, val y: Float, val z: Float, val tangents: FloatArray)
+        fun ByteBuffer.put(v: Vertex): ByteBuffer {
+            putFloat(v.x)
+            putFloat(v.y)
+            putFloat(v.z)
+            v.tangents.forEach { putFloat(it) }
+            return this
+        }
+
+        // 6 faces, 4 vertices per face
+        val vertexCount = 6 * 4
+
+        // Create tangent frames, one per face
+        val tfPX = FloatArray(4)
+        val tfNX = FloatArray(4)
+        val tfPY = FloatArray(4)
+        val tfNY = FloatArray(4)
+        val tfPZ = FloatArray(4)
+        val tfNZ = FloatArray(4)
+
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 0.0f, 0.0f, -1.0f,  1.0f,  0.0f,  0.0f, tfPX)
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 0.0f, 0.0f, -1.0f, -1.0f,  0.0f,  0.0f, tfNX)
+        MathUtils.packTangentFrame(-1.0f,  0.0f, 0.0f, 0.0f, 0.0f, -1.0f,  0.0f,  1.0f,  0.0f, tfPY)
+        MathUtils.packTangentFrame(-1.0f,  0.0f, 0.0f, 0.0f, 0.0f,  1.0f,  0.0f, -1.0f,  0.0f, tfNY)
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 1.0f, 0.0f,  0.0f,  0.0f,  0.0f,  1.0f, tfPZ)
+        MathUtils.packTangentFrame( 0.0f, -1.0f, 0.0f, 1.0f, 0.0f,  0.0f,  0.0f,  0.0f, -1.0f, tfNZ)
+
+        val vertexData = ByteBuffer.allocate(vertexCount * vertexSize)
+                // It is important to respect the native byte order
+                .order(ByteOrder.nativeOrder())
+                // Face -Z
+                .put(Vertex(-1.5f, -1.5f, -1.0f, tfNZ))
+                .put(Vertex(-1.5f,  1.5f, -1.0f, tfNZ))
+                .put(Vertex( 1.5f,  1.5f, -1.0f, tfNZ))
+                .put(Vertex( 1.5f, -1.5f, -1.0f, tfNZ))
+                // Face +X
+                .put(Vertex( 1.5f, -1.5f, -1.0f, tfPX))
+                .put(Vertex( 1.5f,  1.5f, -1.0f, tfPX))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPX))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfPX))
+                // Face +Z
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfPZ))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfPZ))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPZ))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfPZ))
+                // Face -X
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfNX))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfNX))
+                .put(Vertex(-1.5f,  1.5f, -1.0f, tfNX))
+                .put(Vertex(-1.5f, -1.5f, -1.0f, tfNX))
+                // Face -Y
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfNY))
+                .put(Vertex(-1.5f, -1.5f, -1.0f, tfNY))
+                .put(Vertex( 1.5f, -1.5f, -1.0f, tfNY))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfNY))
+                // Face +Y
+                .put(Vertex(-1.5f,  1.5f, -1.0f, tfPY))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfPY))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPY))
+                .put(Vertex( 1.5f,  1.5f, -1.0f, tfPY))
+                // Make sure the cursor is pointing in the right place in the byte buffer
+                .flip()
+
+        // Declare the layout of our mesh
+        vertexBuffer = VertexBuffer.Builder()
+                .bufferCount(1)
+                .vertexCount(vertexCount)
+                // Because we interleave position and color data we must specify offset and stride
+                // We could use de-interleaved data by declaring two buffers and giving each
+                // attribute a different buffer index
+                .attribute(VertexAttribute.POSITION, 0, AttributeType.FLOAT3, 0,             vertexSize)
+                .attribute(VertexAttribute.TANGENTS, 0, AttributeType.FLOAT4, 3 * floatSize, vertexSize)
+                .build(engine)
+
+        // Feed the vertex data to the mesh
+        // We only set 1 buffer because the data is interleaved
+        vertexBuffer.setBufferAt(engine, 0, vertexData)
+
+        // Create the indices
+        val indexData = ByteBuffer.allocate(6 * 2 * 3 * shortSize)
+                .order(ByteOrder.nativeOrder())
+        repeat(6) {
+            val i = (it * 4).toShort()
+            indexData
+                    .putShort(i).putShort((i + 1).toShort()).putShort((i + 2).toShort())
+                    .putShort(i).putShort((i + 2).toShort()).putShort((i + 3).toShort())
+        }
+        indexData.flip()
+
+        // 6 faces, 2 triangles per face,
+        indexBuffer = IndexBuffer.Builder()
+                .indexCount(vertexCount * 2)
+                .bufferType(IndexBuffer.Builder.IndexType.USHORT)
+                .build(engine)
+        indexBuffer.setBuffer(engine, indexData)
+    }
+
+    private fun startAnimation() {
+        // Animate the triangle
+        animator.interpolator = LinearInterpolator()
+        animator.duration = 6000
+        animator.repeatMode = ValueAnimator.RESTART
+        animator.repeatCount = ValueAnimator.INFINITE
+        animator.addUpdateListener(object : ValueAnimator.AnimatorUpdateListener {
+            val transformMatrix = FloatArray(16)
+            override fun onAnimationUpdate(animator: ValueAnimator) {
+                val t = animator.animatedValue as Float
+                val radians = sin(t) * 3.0f * PI.toFloat()
+                Matrix.setRotateM(transformMatrix, 0, radians, 0.0f, 1.0f, 0.0f)
+                val tcm = engine.transformManager
+                tcm.setTransform(tcm.getInstance(renderable), transformMatrix)
+            }
+        })
+        animator.start()
+    }
+
+    override fun onResume() {
+        super.onResume()
+        choreographer.postFrameCallback(frameScheduler)
+        animator.start()
+//        cameraHelper.onResume()
+    }
+
+    override fun onPause() {
+        super.onPause()
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel()
+//        cameraHelper.onPause()
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel()
+
+        // Always detach the surface before destroying the engine
+        uiHelper.detach()
+
+        // Cleanup all resources
+        engine.destroyEntity(light)
+        engine.destroyEntity(renderable)
+        engine.destroyRenderer(renderer)
+        engine.destroyVertexBuffer(vertexBuffer)
+        engine.destroyIndexBuffer(indexBuffer)
+        engine.destroyMaterialInstance(materialInstance)
+        engine.destroyMaterial(material)
+        engine.destroyView(view)
+        engine.destroyScene(scene)
+        engine.destroyCameraComponent(camera.entity)
+
+        // Engine.destroyEntity() destroys Filament related resources only
+        // (components), not the entity itself
+        val entityManager = EntityManager.get()
+        entityManager.destroy(light)
+        entityManager.destroy(renderable)
+        entityManager.destroy(camera.entity)
+
+        // Destroying the engine will free up any resource you may have forgotten
+        // to destroy, but it's recommended to do the cleanup properly
+        engine.destroy()
+    }
+
+    inner class FrameCallback : Choreographer.FrameCallback {
+        override fun doFrame(frameTimeNanos: Long) {
+            // Schedule the next frame
+            choreographer.postFrameCallback(this)
+
+            // This check guarantees that we have a swap chain
+            if (uiHelper.isReadyToRender) {
+
+                if (myCount < 1) {
+                    val mybuffer: HardwareBuffer? = CanvasToHardwareBufferUtil.drawToHardwareBuffer(400, 400)
+                    mybuffer?.use { buffer : HardwareBuffer ->
+                                        // ... Use the buffer (e.g., create an EGLImage, pass to Vulkan, etc.) ...
+                                    Log.d(TAG, "Successfully created HardwareBuffer: $buffer. Now using it...")
+                                    // buffer.close() // 'use' handles this automatically
+                                    ExternalImage.setOnTexture(engine, filamentTexture!!, buffer, false)                                    
+
+                    } ?: run {
+                        Log.e(TAG, "Failed to create HardwareBuffer.")
+                    }
+                }
+                myCount ++;
+
+//                cameraHelper.pushExternalImageToFilament()
+
+                // If beginFrame() returns false you should skip the frame
+                // This means you are sending frames too quickly to the GPU
+                if (renderer.beginFrame(swapChain!!, frameTimeNanos)) {
+                    renderer.render(view)
+                    renderer.endFrame()
+                }
+            }
+        }
+    }
+
+    inner class SurfaceCallback : UiHelper.RendererCallback {
+        override fun onNativeWindowChanged(surface: Surface) {
+            swapChain?.let { engine.destroySwapChain(it) }
+            swapChain = engine.createSwapChain(surface)
+            displayHelper.attach(renderer, surfaceView.display)
+        }
+
+        override fun onDetachedFromSurface() {
+            displayHelper.detach()
+            swapChain?.let {
+                engine.destroySwapChain(it)
+                // Required to ensure we don't return before Filament is done executing the
+                // destroySwapChain command, otherwise Android might destroy the Surface
+                // too early
+                engine.flushAndWait()
+                swapChain = null
+            }
+        }
+
+        override fun onResized(width: Int, height: Int) {
+            val aspect = width.toDouble() / height.toDouble()
+            camera.setProjection(45.0, aspect, 0.1, 20.0, Camera.Fov.VERTICAL)
+
+            view.viewport = Viewport(0, 0, width, height)
+
+            FilamentHelper.synchronizePendingFrames(engine)
+        }
+    }
+
+    private fun readUncompressedAsset(@Suppress("SameParameterValue") assetName: String): ByteBuffer {
+        assets.openFd(assetName).use { fd ->
+            val input = fd.createInputStream()
+            val dst = ByteBuffer.allocate(fd.length.toInt())
+
+            val src = Channels.newChannel(input)
+            src.read(dst)
+            src.close()
+
+            return dst.apply { rewind() }
+        }
+    }
+
+    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
+//        if (!cameraHelper.onRequestPermissionsResult(requestCode, grantResults)) {
+//            this.onRequestPermissionsResult(requestCode, permissions, grantResults)
+//        }
+    }
+
+}

android/samples/sample-external-image/src/main/java/com/google/android/filament/externalimg/MainActivity.kt~

@@ -0,0 +1,446 @@
+/*
+ * Copyright (C) 2019 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.
+ */
+
+package com.google.android.filament.externalimg
+
+import android.animation.ValueAnimator
+import android.app.Activity
+import android.hardware.HardwareBuffer
+import android.opengl.Matrix
+import android.os.Bundle
+import android.view.Choreographer
+import android.view.Surface
+import android.view.SurfaceView
+import android.view.animation.LinearInterpolator
+import androidx.core.app.ActivityCompat
+
+import com.google.android.filament.*
+import com.google.android.filament.RenderableManager.*
+import com.google.android.filament.VertexBuffer.*
+import com.google.android.filament.android.DisplayHelper
+import com.google.android.filament.android.FilamentHelper
+import com.google.android.filament.android.UiHelper
+
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.nio.channels.Channels
+
+import kotlin.math.*
+
+import android.util.Log
+
+class MainActivity : Activity(), ActivityCompat.OnRequestPermissionsResultCallback {
+    companion object {
+        init {
+            Filament.init()
+        }
+    }
+
+    private var TAG = "filament.externalimg"
+    
+    private lateinit var surfaceView: SurfaceView
+    private lateinit var uiHelper: UiHelper
+    private lateinit var displayHelper: DisplayHelper
+    private lateinit var choreographer: Choreographer
+
+    private lateinit var engine: Engine
+    private lateinit var renderer: Renderer
+    private lateinit var scene: Scene
+    private lateinit var view: View
+
+    // This is the Filament camera, not the phone camera. :)
+    private lateinit var camera: Camera
+
+    // Other Filament objects:
+    private lateinit var material: Material
+    private lateinit var materialInstance: MaterialInstance
+    private lateinit var vertexBuffer: VertexBuffer
+    private lateinit var indexBuffer: IndexBuffer
+
+    // Filament entity representing a renderable object
+    @Entity private var renderable = 0
+    @Entity private var light = 0
+
+    private var myCount : Int = 0
+
+    // A swap chain is Filament's representation of a surface
+    private var swapChain: SwapChain? = null
+
+    // Performs the rendering and schedules new frames
+    private val frameScheduler = FrameCallback()
+
+    private val animator = ValueAnimator.ofFloat(0.0f, 50.0f)
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        surfaceView = SurfaceView(this)
+        setContentView(surfaceView)
+
+        choreographer = Choreographer.getInstance()
+
+        displayHelper = DisplayHelper(this)
+
+        setupSurfaceView()
+        setupFilament()
+        setupView()
+        setupScene()
+
+//        cameraHelper = CameraHelper(this, engine, materialInstance)
+//        cameraHelper.openCamera()
+    }
+
+    private fun setupSurfaceView() {
+        uiHelper = UiHelper(UiHelper.ContextErrorPolicy.DONT_CHECK)
+        uiHelper.renderCallback = SurfaceCallback()
+        uiHelper.attachTo(surfaceView)
+    }
+
+    private fun setupFilament() {
+        engine = Engine.create()
+        renderer = engine.createRenderer()
+        scene = engine.createScene()
+        view = engine.createView()
+        camera = engine.createCamera(engine.entityManager.create())
+
+    }
+
+    private fun setupView() {
+        scene.skybox = Skybox.Builder().color(0.035f, 0.035f, 0.035f, 1.0f).build(engine)
+        view.camera = camera
+        view.scene = scene
+    }
+
+    private fun setupScene() {
+        loadMaterial()
+        setupMaterial()
+        createMesh()
+
+        // To create a renderable we first create a generic entity
+        renderable = EntityManager.get().create()
+
+        // We then create a renderable component on that entity
+        // A renderable is made of several primitives; in this case we declare only 1
+        // If we wanted each face of the cube to have a different material, we could
+        // declare 6 primitives (1 per face) and give each of them a different material
+        // instance, setup with different parameters
+        RenderableManager.Builder(1)
+                // Overall bounding box of the renderable
+                .boundingBox(Box(0.0f, 0.0f, 0.0f, 1.0f, 1.0f, 1.0f))
+                // Sets the mesh data of the first primitive, 6 faces of 6 indices each
+                .geometry(0, PrimitiveType.TRIANGLES, vertexBuffer, indexBuffer, 0, 6 * 6)
+                // Sets the material of the first primitive
+                .material(0, materialInstance)
+                .build(engine, renderable)
+
+        // Add the entity to the scene to render it
+        scene.addEntity(renderable)
+
+        // We now need a light, let's create a directional light
+        light = EntityManager.get().create()
+
+        // Create a color from a temperature (5,500K)
+        val (r, g, b) = Colors.cct(5_500.0f)
+        LightManager.Builder(LightManager.Type.DIRECTIONAL)
+                .color(r, g, b)
+                // Intensity of the sun in lux on a clear day
+                .intensity(110_000.0f)
+                // The direction is normalized on our behalf
+                .direction(0.0f, -0.5f, -1.0f)
+                .castShadows(true)
+                .build(engine, light)
+
+        // Add the entity to the scene to light it
+        scene.addEntity(light)
+
+        // Set the exposure on the camera, this exposure follows the sunny f/16 rule
+        // Since we've defined a light that has the same intensity as the sun, it
+        // guarantees a proper exposure
+        camera.setExposure(16.0f, 1.0f / 125.0f, 100.0f)
+
+        // Move the camera back to see the object
+        camera.lookAt(0.0, 0.0, 6.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0)
+
+        startAnimation()
+    }
+
+    private fun loadMaterial() {
+        readUncompressedAsset("materials/lit.filamat").let {
+            material = Material.Builder().payload(it, it.remaining()).build(engine)
+        }
+    }
+
+    private fun setupMaterial() {
+        materialInstance = material.createInstance()
+        materialInstance.setParameter("baseColor", Colors.RgbType.SRGB, 1.0f, 0.85f, 0.57f)
+        materialInstance.setParameter("roughness", 0.3f)
+    }
+
+    private fun createMesh() {
+        val floatSize = 4
+        val shortSize = 2
+        // A vertex is a position + a tangent frame:
+        // 3 floats for XYZ position, 4 floats for normal+tangents (quaternion)
+        val vertexSize = 3 * floatSize + 4 * floatSize
+
+        // Define a vertex and a function to put a vertex in a ByteBuffer
+        @Suppress("ArrayInDataClass")
+        data class Vertex(val x: Float, val y: Float, val z: Float, val tangents: FloatArray)
+        fun ByteBuffer.put(v: Vertex): ByteBuffer {
+            putFloat(v.x)
+            putFloat(v.y)
+            putFloat(v.z)
+            v.tangents.forEach { putFloat(it) }
+            return this
+        }
+
+        // 6 faces, 4 vertices per face
+        val vertexCount = 6 * 4
+
+        // Create tangent frames, one per face
+        val tfPX = FloatArray(4)
+        val tfNX = FloatArray(4)
+        val tfPY = FloatArray(4)
+        val tfNY = FloatArray(4)
+        val tfPZ = FloatArray(4)
+        val tfNZ = FloatArray(4)
+
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 0.0f, 0.0f, -1.0f,  1.0f,  0.0f,  0.0f, tfPX)
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 0.0f, 0.0f, -1.0f, -1.0f,  0.0f,  0.0f, tfNX)
+        MathUtils.packTangentFrame(-1.0f,  0.0f, 0.0f, 0.0f, 0.0f, -1.0f,  0.0f,  1.0f,  0.0f, tfPY)
+        MathUtils.packTangentFrame(-1.0f,  0.0f, 0.0f, 0.0f, 0.0f,  1.0f,  0.0f, -1.0f,  0.0f, tfNY)
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 1.0f, 0.0f,  0.0f,  0.0f,  0.0f,  1.0f, tfPZ)
+        MathUtils.packTangentFrame( 0.0f, -1.0f, 0.0f, 1.0f, 0.0f,  0.0f,  0.0f,  0.0f, -1.0f, tfNZ)
+
+        val vertexData = ByteBuffer.allocate(vertexCount * vertexSize)
+                // It is important to respect the native byte order
+                .order(ByteOrder.nativeOrder())
+                // Face -Z
+                .put(Vertex(-1.5f, -1.5f, -1.0f, tfNZ))
+                .put(Vertex(-1.5f,  1.5f, -1.0f, tfNZ))
+                .put(Vertex( 1.5f,  1.5f, -1.0f, tfNZ))
+                .put(Vertex( 1.5f, -1.5f, -1.0f, tfNZ))
+                // Face +X
+                .put(Vertex( 1.5f, -1.5f, -1.0f, tfPX))
+                .put(Vertex( 1.5f,  1.5f, -1.0f, tfPX))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPX))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfPX))
+                // Face +Z
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfPZ))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfPZ))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPZ))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfPZ))
+                // Face -X
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfNX))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfNX))
+                .put(Vertex(-1.5f,  1.5f, -1.0f, tfNX))
+                .put(Vertex(-1.5f, -1.5f, -1.0f, tfNX))
+                // Face -Y
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfNY))
+                .put(Vertex(-1.5f, -1.5f, -1.0f, tfNY))
+                .put(Vertex( 1.5f, -1.5f, -1.0f, tfNY))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfNY))
+                // Face +Y
+                .put(Vertex(-1.5f,  1.5f, -1.0f, tfPY))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfPY))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPY))
+                .put(Vertex( 1.5f,  1.5f, -1.0f, tfPY))
+                // Make sure the cursor is pointing in the right place in the byte buffer
+                .flip()
+
+        // Declare the layout of our mesh
+        vertexBuffer = VertexBuffer.Builder()
+                .bufferCount(1)
+                .vertexCount(vertexCount)
+                // Because we interleave position and color data we must specify offset and stride
+                // We could use de-interleaved data by declaring two buffers and giving each
+                // attribute a different buffer index
+                .attribute(VertexAttribute.POSITION, 0, AttributeType.FLOAT3, 0,             vertexSize)
+                .attribute(VertexAttribute.TANGENTS, 0, AttributeType.FLOAT4, 3 * floatSize, vertexSize)
+                .build(engine)
+
+        // Feed the vertex data to the mesh
+        // We only set 1 buffer because the data is interleaved
+        vertexBuffer.setBufferAt(engine, 0, vertexData)
+
+        // Create the indices
+        val indexData = ByteBuffer.allocate(6 * 2 * 3 * shortSize)
+                .order(ByteOrder.nativeOrder())
+        repeat(6) {
+            val i = (it * 4).toShort()
+            indexData
+                    .putShort(i).putShort((i + 1).toShort()).putShort((i + 2).toShort())
+                    .putShort(i).putShort((i + 2).toShort()).putShort((i + 3).toShort())
+        }
+        indexData.flip()
+
+        // 6 faces, 2 triangles per face,
+        indexBuffer = IndexBuffer.Builder()
+                .indexCount(vertexCount * 2)
+                .bufferType(IndexBuffer.Builder.IndexType.USHORT)
+                .build(engine)
+        indexBuffer.setBuffer(engine, indexData)
+    }
+
+    private fun startAnimation() {
+        // Animate the triangle
+        animator.interpolator = LinearInterpolator()
+        animator.duration = 6000
+        animator.repeatMode = ValueAnimator.RESTART
+        animator.repeatCount = ValueAnimator.INFINITE
+        animator.addUpdateListener(object : ValueAnimator.AnimatorUpdateListener {
+            val transformMatrix = FloatArray(16)
+            override fun onAnimationUpdate(animator: ValueAnimator) {
+                val t = animator.animatedValue as Float
+                val radians = sin(t) * 3.0f * PI.toFloat()
+                Matrix.setRotateM(transformMatrix, 0, radians, 0.0f, 1.0f, 0.0f)
+                val tcm = engine.transformManager
+                tcm.setTransform(tcm.getInstance(renderable), transformMatrix)
+            }
+        })
+        animator.start()
+    }
+
+    override fun onResume() {
+        super.onResume()
+        choreographer.postFrameCallback(frameScheduler)
+        animator.start()
+//        cameraHelper.onResume()
+    }
+
+    override fun onPause() {
+        super.onPause()
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel()
+//        cameraHelper.onPause()
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel()
+
+        // Always detach the surface before destroying the engine
+        uiHelper.detach()
+
+        // Cleanup all resources
+        engine.destroyEntity(light)
+        engine.destroyEntity(renderable)
+        engine.destroyRenderer(renderer)
+        engine.destroyVertexBuffer(vertexBuffer)
+        engine.destroyIndexBuffer(indexBuffer)
+        engine.destroyMaterialInstance(materialInstance)
+        engine.destroyMaterial(material)
+        engine.destroyView(view)
+        engine.destroyScene(scene)
+        engine.destroyCameraComponent(camera.entity)
+
+        // Engine.destroyEntity() destroys Filament related resources only
+        // (components), not the entity itself
+        val entityManager = EntityManager.get()
+        entityManager.destroy(light)
+        entityManager.destroy(renderable)
+        entityManager.destroy(camera.entity)
+
+        // Destroying the engine will free up any resource you may have forgotten
+        // to destroy, but it's recommended to do the cleanup properly
+        engine.destroy()
+    }
+
+    inner class FrameCallback : Choreographer.FrameCallback {
+        override fun doFrame(frameTimeNanos: Long) {
+            // Schedule the next frame
+            choreographer.postFrameCallback(this)
+
+            // This check guarantees that we have a swap chain
+            if (uiHelper.isReadyToRender) {
+
+                if (myCount < 1) {
+                    val mybuffer: HardwareBuffer? = CanvasToHardwareBufferUtil.drawToHardwareBuffer(400, 400)
+                    mybuffer?.use { buffer : HardwareBuffer ->
+                                        // ... Use the buffer (e.g., create an EGLImage, pass to Vulkan, etc.) ...
+                                    Log.d(TAG, "Successfully created HardwareBuffer: $buffer. Now using it...")
+                                    // buffer.close() // 'use' handles this automatically
+                                    
+                    } ?: run {
+                        Log.e(TAG, "Failed to create HardwareBuffer.")
+                    }
+                }
+                myCount ++;
+                
+//                cameraHelper.pushExternalImageToFilament()
+
+                // If beginFrame() returns false you should skip the frame
+                // This means you are sending frames too quickly to the GPU
+                if (renderer.beginFrame(swapChain!!, frameTimeNanos)) {
+                    renderer.render(view)
+                    renderer.endFrame()
+                }
+            }
+        }
+    }
+
+    inner class SurfaceCallback : UiHelper.RendererCallback {
+        override fun onNativeWindowChanged(surface: Surface) {
+            swapChain?.let { engine.destroySwapChain(it) }
+            swapChain = engine.createSwapChain(surface)
+            displayHelper.attach(renderer, surfaceView.display)
+        }
+
+        override fun onDetachedFromSurface() {
+            displayHelper.detach()
+            swapChain?.let {
+                engine.destroySwapChain(it)
+                // Required to ensure we don't return before Filament is done executing the
+                // destroySwapChain command, otherwise Android might destroy the Surface
+                // too early
+                engine.flushAndWait()
+                swapChain = null
+            }
+        }
+
+        override fun onResized(width: Int, height: Int) {
+            val aspect = width.toDouble() / height.toDouble()
+            camera.setProjection(45.0, aspect, 0.1, 20.0, Camera.Fov.VERTICAL)
+
+            view.viewport = Viewport(0, 0, width, height)
+
+            FilamentHelper.synchronizePendingFrames(engine)
+        }
+    }
+
+    private fun readUncompressedAsset(@Suppress("SameParameterValue") assetName: String): ByteBuffer {
+        assets.openFd(assetName).use { fd ->
+            val input = fd.createInputStream()
+            val dst = ByteBuffer.allocate(fd.length.toInt())
+
+            val src = Channels.newChannel(input)
+            src.read(dst)
+            src.close()
+
+            return dst.apply { rewind() }
+        }
+    }
+
+    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
+//        if (!cameraHelper.onRequestPermissionsResult(requestCode, grantResults)) {
+//            this.onRequestPermissionsResult(requestCode, permissions, grantResults)
+//        }
+    }
+
+}

android/samples/sample-external-image/src/main/materials/lit.mat

@@ -0,0 +1,73 @@
+// Simple lit material that defines 3 parameters:
+// - baseColor
+// - roughness
+// - metallic
+//
+// These parameters can be used by the application to change the appearance of the material.
+//
+// This source material must be compiled to a binary material using the matc tool.
+// The command used to compile this material is:
+// matc -p mobile -a opengl -o app/src/main/assets/lit.filamat app/src/materials/lit.mat
+//
+// See build.gradle for an example of how to compile materials automatically
+// Please refer to the documentation for more information about matc and the materials system.
+
+material {
+    name : lit,
+
+    // Dynamic lighting is enabled on this material
+    shadingModel : lit,
+
+    // We don't need to declare a "requires" array, lit materials
+    // always requires the "tangents" vertex attribute (the normal
+    // is required for lighting, tangent/bitangent for normal mapping
+    // and anisotropy)
+
+    // Custom vertex shader outputs
+    variables : [
+        uv
+    ],
+
+    // List of parameters exposed by this material
+    parameters : [
+        // The color must be passed in linear space, not sRGB
+        {
+            type : float3,
+            name : baseColor
+        },
+        {
+            type : float,
+            name : roughness
+        },
+        {
+            type : samplerExternal,
+            name : videoTexture
+        },
+        {
+            type : mat4,
+            name : textureTransform
+        }
+    ],
+}
+
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        material.uv = 0.5 * (getPosition() + vec4(1));
+    }
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.roughness = materialParams.roughness;
+        material.metallic = 0.0;
+
+        // Apply the video stream to the +Z face on the cube.
+        if (variable_uv.z >= 1.0) {
+            vec2 uv = (materialParams.textureTransform * vec4(variable_uv.xy, 0, 1)).xy;
+            material.baseColor.rgb = inverseTonemapSRGB(texture(materialParams_videoTexture, uv).rgb);
+        } else {
+            material.baseColor.rgb = materialParams.baseColor;
+        }
+    }
+}

android/samples/sample-external-image/src/main/res/drawable-v24/ic_launcher_foreground.xml

@@ -0,0 +1,34 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportHeight="108"
+    android:viewportWidth="108">
+  <path
+      android:fillType="evenOdd"
+      android:pathData="M32,64C32,64 38.39,52.99 44.13,50.95C51.37,48.37 70.14,49.57 70.14,49.57L108.26,87.69L108,109.01L75.97,107.97L32,64Z"
+      android:strokeColor="#00000000"
+      android:strokeWidth="1">
+    <aapt:attr name="android:fillColor">
+      <gradient
+          android:endX="78.5885"
+          android:endY="90.9159"
+          android:startX="48.7653"
+          android:startY="61.0927"
+          android:type="linear">
+        <item
+            android:color="#44000000"
+            android:offset="0.0"/>
+        <item
+            android:color="#00000000"
+            android:offset="1.0"/>
+      </gradient>
+    </aapt:attr>
+  </path>
+  <path
+      android:fillColor="#FFFFFF"
+      android:fillType="nonZero"
+      android:pathData="M66.94,46.02L66.94,46.02C72.44,50.07 76,56.61 76,64L32,64C32,56.61 35.56,50.11 40.98,46.06L36.18,41.19C35.45,40.45 35.45,39.3 36.18,38.56C36.91,37.81 38.05,37.81 38.78,38.56L44.25,44.05C47.18,42.57 50.48,41.71 54,41.71C57.48,41.71 60.78,42.57 63.68,44.05L69.11,38.56C69.84,37.81 70.98,37.81 71.71,38.56C72.44,39.3 72.44,40.45 71.71,41.19L66.94,46.02ZM62.94,56.92C64.08,56.92 65,56.01 65,54.88C65,53.76 64.08,52.85 62.94,52.85C61.8,52.85 60.88,53.76 60.88,54.88C60.88,56.01 61.8,56.92 62.94,56.92ZM45.06,56.92C46.2,56.92 47.13,56.01 47.13,54.88C47.13,53.76 46.2,52.85 45.06,52.85C43.92,52.85 43,53.76 43,54.88C43,56.01 43.92,56.92 45.06,56.92Z"
+      android:strokeColor="#00000000"
+      android:strokeWidth="1"/>
+</vector>

android/samples/sample-external-image/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportHeight="108"
+    android:viewportWidth="108">
+  <path
+      android:fillColor="#26A69A"
+      android:pathData="M0,0h108v108h-108z"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M9,0L9,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,0L19,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M29,0L29,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M39,0L39,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M49,0L49,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M59,0L59,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M69,0L69,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M79,0L79,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M89,0L89,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M99,0L99,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,9L108,9"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,19L108,19"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,29L108,29"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,39L108,39"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,49L108,49"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,59L108,59"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,69L108,69"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,79L108,79"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,89L108,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,99L108,99"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,29L89,29"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,39L89,39"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,49L89,49"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,59L89,59"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,69L89,69"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,79L89,79"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M29,19L29,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M39,19L39,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M49,19L49,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M59,19L59,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M69,19L69,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M79,19L79,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+</vector>

android/samples/sample-external-image/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@drawable/ic_launcher_background"/>
+  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
+</adaptive-icon>

android/samples/sample-external-image/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@drawable/ic_launcher_background"/>
+  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
+</adaptive-icon>

android/samples/sample-external-image/src/main/res/values/colors.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <color name="colorPrimary">#3F51B5</color>
+  <color name="colorPrimaryDark">#303F9F</color>
+  <color name="colorAccent">#FF4081</color>
+</resources>

android/samples/sample-external-image/src/main/res/values/strings.xml

@@ -0,0 +1,3 @@
+<resources>
+  <string name="app_name">External Image</string>
+</resources>

android/samples/sample-external-image/src/main/res/values/strings.xml~

@@ -0,0 +1,3 @@
+<resources>
+  <string name="app_name">Hello Camera</string>
+</resources>

android/samples/sample-external-image/src/main/res/values/styles.xml

@@ -0,0 +1,8 @@
+<resources>
+
+  <!-- Base application theme. -->
+  <style name="AppTheme" parent="android:Theme.Material.Light.DarkActionBar">
+    <!-- Customize your theme here. -->
+  </style>
+
+</resources>

android/settings.gradle

@@ -18,5 +18,6 @@ include ':samples:sample-stream-test'
 include ':samples:sample-texture-view'
 include ':samples:sample-textured-object'
 include ':samples:sample-transparent-view'
+include ':samples:sample-external-image'
 
 rootProject.name = 'filament'

build/linux/ci-common.sh

@@ -31,7 +31,7 @@ if [[ "$GITHUB_WORKFLOW" ]]; then
     sudo apt-get install mesa-common-dev libxi-dev libxxf86vm-dev
 
     # For dawn
-    sudo apt-get install libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev
+    sudo apt-get install libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libx11-xcb-dev
 
     sudo update-alternatives --install /usr/bin/cc cc /usr/bin/clang-${GITHUB_CLANG_VERSION} 100
     sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++-${GITHUB_CLANG_VERSION} 100

docs/Materials.md.html

@@ -13,7 +13,7 @@ This document is part of the [Filament project](https://github.com/google/filame
 ## Authors
 
 - [Romain Guy](https://github.com/romainguy), [@romainguy](https://twitter.com/romainguy)
-- [Mathias Agopian](https://github.com/pixelflinger), [@darthmoosious](https://twitter.com/darthmoosious)
+- [Mathias Agopian](https://github.com/pixelflinger), [@pixelflinger](https://bsky.app/profile/pixelflinger.bsky.social)
 
 # Overview
 
@@ -78,26 +78,27 @@ in table [standardProperties].
         Property        |      Definition
 -----------------------:|:---------------------
 **baseColor**           | Diffuse albedo for non-metallic surfaces, and specular color for metallic surfaces
-**metallic**            | Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1)
 **roughness**           | Perceived smoothness (1.0) or roughness (0.0) of a surface. Smooth surfaces exhibit sharp reflections
+**metallic**            | Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1)
 **reflectance**         | Fresnel reflectance at normal incidence for dielectric surfaces. This directly controls the strength of the reflections
-**sheenColor**          | Strength of the sheen layer
-**sheenRoughness**      | Perceived smoothness or roughness of the sheen layer
+**ambientOcclusion**    | Defines how much of the ambient light is accessible to a surface point. It is a per-pixel shadowing factor between 0.0 and 1.0
 **clearCoat**           | Strength of the clear coat layer
 **clearCoatRoughness**  | Perceived smoothness or roughness of the clear coat layer
+**clearCoatNormal**     | A detail normal used to perturb the clear coat layer using _bump mapping_ (_normal mapping_)
 **anisotropy**          | Amount of anisotropy in either the tangent or bitangent direction
 **anisotropyDirection** | Local surface direction in tangent space
-**ambientOcclusion**    | Defines how much of the ambient light is accessible to a surface point. It is a per-pixel shadowing factor between 0.0 and 1.0
-**normal**              | A detail normal used to perturb the surface using _bump mapping_ (_normal mapping_)
-**bentNormal**          | A normal pointing in the average unoccluded direction. Can be used to improve indirect lighting quality
-**clearCoatNormal**     | A detail normal used to perturb the clear coat layer using _bump mapping_ (_normal mapping_)
-**emissive**            | Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass
-**postLightingColor**   | Additional color that can be blended with the result of the lighting computations. See `postLightingBlending`
-**ior**                 | Index of refraction, either for refractive objects or as an alternative to reflectance
-**transmission**        | Defines how much of the diffuse light of a dielectric is transmitted through the object, in other words this defines how transparent an object is
-**absorption**          | Absorption factor for refractive objects
-**microThickness**      | Thickness of the thin layer of refractive objects
 **thickness**           | Thickness of the solid volume of refractive objects
+**sheenColor**          | Strength of the sheen layer
+**sheenRoughness**      | Perceived smoothness or roughness of the sheen layer
+**emissive**            | Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass
+**normal**              | A detail normal used to perturb the surface using _bump mapping_ (_normal mapping_)
+**postLightingColor**   | Additional color that can be blended with the result of the lighting computations. See `postLightingBlending`
+**absorption**          | Absorption factor for refractive objects
+**transmission**        | Defines how much of the diffuse light of a dielectric is transmitted through the object, in other words this defines how transparent an object is
+**ior**                 | Index of refraction, either for refractive objects or as an alternative to reflectance
+**microThickness**      | Thickness of the thin layer of refractive objects
+**bentNormal**          | A normal pointing in the average unoccluded direction. Can be used to improve indirect lighting quality
+**shadowStrength**      | Strength factor between 0 and 1 for all shadows received by this material
 [Table [standardProperties]: Properties of the standard model]
 
 The type and range of each property is described in table [standardPropertiesTypes].
@@ -1272,6 +1273,9 @@ Description
       when selecting any shading model that is not `unlit`. See the shader sections of this document
       for more information on how to access these attributes from the shaders.
 
+!!! Note: Interaction with custom variables
+    When the `color` attribute is specified, only four custom variables are available instead of five.
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
     parameters : [
@@ -1302,7 +1306,7 @@ Type
 :    array of `string`
 
 Value
-:     Up to 4 strings, each must be a valid GLSL identifier.
+:     Up to 5 strings, each must be a valid GLSL identifier.
 
 Description
 :     Defines custom interpolants (or variables) that are output by the material's vertex shader.
@@ -1318,6 +1322,10 @@ Description
       particular if `default` is specified the default precision is used is the fragment shader
       (`mediump`) and in the vertex shader (`highp`).
 
+!!! Warning: Interaction with required attributes
+    If the `color` attribute is specified in the `required` list, then only four variables can be used
+    instead of five.
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
     name : Skybox,

filament/backend/CMakeLists.txt

@@ -108,8 +108,12 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3)
         list(APPEND SRCS src/opengl/platforms/PlatformCocoaTouchGL.mm)
         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)
+        if (FILAMENT_SUPPORTS_OSMESA)
+            list(APPEND SRCS src/opengl/platforms/PlatformOSMesa.cpp)
+        else()
+            list(APPEND SRCS src/opengl/platforms/PlatformCocoaGL.mm)
+            list(APPEND SRCS src/opengl/platforms/CocoaExternalImage.mm)
+        endif()
     elseif (WEBGL)
         list(APPEND SRCS src/opengl/platforms/PlatformWebGL.cpp)
     elseif (LINUX)
@@ -173,10 +177,12 @@ endif()
 if (FILAMENT_SUPPORTS_VULKAN)
     list(APPEND SRCS
             include/backend/platforms/VulkanPlatform.h
-            src/vulkan/caching/VulkanDescriptorSetManager.cpp
-            src/vulkan/caching/VulkanDescriptorSetManager.h
-            src/vulkan/caching/VulkanPipelineLayoutCache.cpp
-            src/vulkan/caching/VulkanPipelineLayoutCache.h
+            src/vulkan/VulkanDescriptorSetCache.cpp
+            src/vulkan/VulkanDescriptorSetCache.h
+            src/vulkan/VulkanDescriptorSetLayoutCache.cpp
+            src/vulkan/VulkanDescriptorSetLayoutCache.h
+            src/vulkan/VulkanPipelineLayoutCache.cpp
+            src/vulkan/VulkanPipelineLayoutCache.h
             src/vulkan/memory/ResourceManager.cpp
             src/vulkan/memory/ResourceManager.h
             src/vulkan/memory/ResourcePointer.h
@@ -416,9 +422,12 @@ set(LINUX_LINKER_OPTIMIZATION_FLAGS
         -Wl,--exclude-libs,bluegl
 )
 
-if (LINUX AND FILAMENT_SUPPORTS_OSMESA)
-    set(OSMESA_COMPILE_FLAGS
-        -I${FILAMENT_OSMESA_PATH}/include/GL)
+if (FILAMENT_SUPPORTS_OSMESA)
+    if (LINUX)
+        set(OSMESA_COMPILE_FLAGS -I${FILAMENT_OSMESA_PATH}/include/GL)
+    elseif (APPLE)
+        set(OSMESA_COMPILE_FLAGS -I${FILAMENT_OSMESA_PATH}/include)
+    endif()
 endif()
 
 if (MSVC)

filament/backend/include/backend/DriverEnums.h

@@ -256,18 +256,16 @@ struct DescriptorSetLayoutBinding {
     DescriptorFlags flags = DescriptorFlags::NONE;
     uint16_t count = 0;
 
-    //  TODO: uncomment when needed.  Note that this class is used as hash key.  We need to ensure
-    //  no uninitialized padding bytes.
-    //    uint8_t externalSamplerDataIndex = EXTERNAL_SAMPLER_DATA_INDEX_UNUSED;
+    uint8_t externalSamplerDataIndex = EXTERNAL_SAMPLER_DATA_INDEX_UNUSED;
 
-    friend inline bool operator==(DescriptorSetLayoutBinding const& lhs,
+    friend inline bool operator==(
+            DescriptorSetLayoutBinding const& lhs,
             DescriptorSetLayoutBinding const& rhs) noexcept {
         return lhs.type == rhs.type &&
                lhs.flags == rhs.flags &&
                lhs.count == rhs.count &&
-               lhs.stageFlags == rhs.stageFlags;
-//               lhs.stageFlags == rhs.stageFlags &&
-//               lhs.externalSamplerDataIndex == rhs.externalSamplerDataIndex;
+               lhs.stageFlags == rhs.stageFlags &&
+               lhs.externalSamplerDataIndex == rhs.externalSamplerDataIndex;
     }
 };
 
@@ -1140,9 +1138,7 @@ static_assert(sizeof(ExternalSamplerDatum) == 12);
 
 struct DescriptorSetLayout {
     utils::FixedCapacityVector<DescriptorSetLayoutBinding> bindings;
-
-//  TODO: uncomment when needed
-//    utils::FixedCapacityVector<ExternalSamplerDatum> externalSamplerData;
+    utils::FixedCapacityVector<ExternalSamplerDatum> externalSamplerData;
 };
 
 //! blending equation function

filament/backend/include/backend/Platform.h

@@ -149,13 +149,6 @@ public:
          *      - PlatformEGLAndroid
          */
         bool assertNativeWindowIsValid = false;
-
-        /**
-         * The action to take if a Drawable cannot be acquired. If true, the
-         * frame is aborted instead of panic. This is only supported for:
-         *      - PlatformMetal
-         */
-        bool metalDisablePanicOnDrawableFailure = false;
     };
 
     Platform() noexcept;

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

@@ -33,7 +33,7 @@ public:
     PlatformCocoaGL();
     ~PlatformCocoaGL() noexcept override;
 
-    ExternalImageHandle createExternalImage(void* cvPixelBuffer) noexcept;
+    ExternalImageHandle UTILS_PUBLIC createExternalImage(void* cvPixelBuffer) noexcept;
 
 protected:
     // --------------------------------------------------------------------------------------------

filament/backend/include/backend/platforms/PlatformCocoaTouchGL.h

@@ -32,7 +32,7 @@ public:
     PlatformCocoaTouchGL();
     ~PlatformCocoaTouchGL() noexcept override;
 
-    ExternalImageHandle createExternalImage(void* cvPixelBuffer) noexcept;
+    ExternalImageHandle UTILS_PUBLIC createExternalImage(void* cvPixelBuffer) noexcept;
 
     // --------------------------------------------------------------------------------------------
     // Platform Interface

filament/backend/include/backend/platforms/PlatformEGL.h

@@ -50,7 +50,7 @@ public:
     /**
      * Creates an ExternalImage from a EGLImageKHR
      */
-    ExternalImageHandle createExternalImage(EGLImageKHR eglImage) noexcept;
+    ExternalImageHandle UTILS_PUBLIC createExternalImage(EGLImageKHR eglImage) noexcept;
 
 protected:
     // --------------------------------------------------------------------------------------------

filament/backend/include/backend/platforms/PlatformEGLAndroid.h

@@ -47,16 +47,16 @@ public:
     /**
      * Creates an ExternalImage from a EGLImageKHR
      */
-    ExternalImageHandle createExternalImage(AHardwareBuffer const* buffer, bool sRGB) noexcept;
+    ExternalImageHandle UTILS_PUBLIC createExternalImage(AHardwareBuffer const* buffer, bool sRGB) noexcept;
 
-    struct ExternalImageDescAndroid {
+    struct UTILS_PUBLIC ExternalImageDescAndroid {
         uint32_t width;      // Texture width
         uint32_t height;     // Texture height
         TextureFormat format;// Texture format
         TextureUsage usage;  // Texture usage flags
     };
 
-    ExternalImageDescAndroid getExternalImageDesc(ExternalImageHandle externalImage) noexcept;
+    ExternalImageDescAndroid UTILS_PUBLIC getExternalImageDesc(ExternalImageHandle externalImage) noexcept;
 
 protected:
     // --------------------------------------------------------------------------------------------

filament/backend/include/backend/platforms/PlatformOSMesa.h

@@ -21,7 +21,12 @@
 
 #include "bluegl/BlueGL.h"
 
+#if defined(__linux__)
 #include <osmesa.h>
+#elif defined(__APPLE__)
+#undef GLAPI
+#include <GL/osmesa.h>
+#endif
 
 #include <backend/platforms/OpenGLPlatform.h>
 #include <backend/DriverEnums.h>

filament/backend/include/backend/platforms/VulkanPlatformAndroid.h

@@ -26,6 +26,20 @@ namespace filament::backend {
 
 class VulkanPlatformAndroid : public VulkanPlatform {
 public:
+    Platform::ExternalImageHandle UTILS_PUBLIC createExternalImage(AHardwareBuffer const* buffer,
+            bool sRGB) noexcept;
+
+    struct UTILS_PUBLIC ExternalImageDescAndroid {
+        uint32_t width;      // Texture width
+        uint32_t height;     // Texture height
+        TextureFormat format;// Texture format
+        TextureUsage usage;  // Texture usage flags
+    };
+
+    ExternalImageDescAndroid UTILS_PUBLIC getExternalImageDesc(
+            ExternalImageHandleRef externalImage) const noexcept;
+
+protected:
     struct ExternalImageVulkanAndroid : public Platform::ExternalImage {
         AHardwareBuffer* aHardwareBuffer = nullptr;
         bool sRGB = false;
@@ -38,9 +52,6 @@ public:
         ~ExternalImageVulkanAndroid() override;
     };
 
-    Platform::ExternalImageHandle createExternalImage(AHardwareBuffer const* buffer,
-            bool sRGB) noexcept;
-
     virtual ExternalImageMetadata getExternalImageMetadata(ExternalImageHandleRef externalImage);
 
     using ImageData = VulkanPlatform::ImageData;
@@ -48,7 +59,6 @@ public:
             const ExternalImageMetadata& metadata, uint32_t memoryTypeIndex,
             VkImageUsageFlags usage);
 
-protected:
     virtual ExtensionSet getSwapchainInstanceExtensions() const;
 
     using SurfaceBundle = VulkanPlatform::SurfaceBundle;

filament/backend/src/PlatformFactory.cpp

@@ -19,6 +19,11 @@
 #include <utils/Systrace.h>
 #include <utils/debug.h>
 
+// We need to keep this up top for the linux (X11) name collisions.
+#if defined(FILAMENT_SUPPORTS_WEBGPU)
+    #include "backend/platforms/WebGPUPlatform.h"
+#endif
+
 #if defined(__ANDROID__)
     #include <sys/system_properties.h>
     #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
@@ -30,7 +35,11 @@
     #endif
 #elif defined(__APPLE__)
     #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
-        #include <backend/platforms/PlatformCocoaGL.h>
+        #if defined(FILAMENT_SUPPORTS_OSMESA)
+            #include <backend/platforms/PlatformOSMesa.h>
+        #else
+            #include <backend/platforms/PlatformCocoaGL.h>
+        #endif
     #endif
 #elif defined(__linux__)
     #if defined(FILAMENT_SUPPORTS_X11)
@@ -69,9 +78,6 @@ filament::backend::Platform* createDefaultMetalPlatform();
 #endif
 
 #include "noop/PlatformNoop.h"
-#if defined(FILAMENT_SUPPORTS_WEBGPU)
-    #include "backend/platforms/WebGPUPlatform.h"
-#endif
 
 namespace filament::backend {
 
@@ -140,7 +146,11 @@ Platform* PlatformFactory::create(Backend* backend) noexcept {
         #elif defined(FILAMENT_IOS)
             return new PlatformCocoaTouchGL();
         #elif defined(__APPLE__)
-            return new PlatformCocoaGL();
+            #if defined(FILAMENT_SUPPORTS_OSMESA)
+                return new PlatformOSMesa();
+            #else
+                return new PlatformCocoaGL();
+            #endif
         #elif defined(__linux__)
             #if defined(FILAMENT_SUPPORTS_X11)
                 return new PlatformGLX();

filament/backend/src/metal/PlatformMetal.mm

@@ -45,9 +45,6 @@ PlatformMetal::~PlatformMetal() noexcept {
 }
 
 Driver* PlatformMetal::createDriver(void* /*sharedContext*/, const Platform::DriverConfig& driverConfig) noexcept {
-    pImpl->mDrawableFailureBehavior = driverConfig.metalDisablePanicOnDrawableFailure
-            ? DrawableFailureBehavior::ABORT_FRAME
-            : DrawableFailureBehavior::PANIC;
     return MetalDriverFactory::create(this, driverConfig);
 }
 

filament/backend/src/noop/NoopDriver.cpp

@@ -241,7 +241,7 @@ size_t NoopDriver::getMaxUniformBufferSize() {
 }
 
 size_t NoopDriver::getMaxTextureSize(SamplerType target) {
-    return 4096u;
+    return 2048u;
 }
 
 size_t NoopDriver::getMaxArrayTextureLayers() {

filament/backend/src/noop/PlatformNoop.cpp

@@ -20,7 +20,7 @@
 
 namespace filament::backend {
 
-Driver* PlatformNoop::createDriver(void* const sharedGLContext, const Platform::DriverConfig& driverConfig) noexcept {
+Driver* PlatformNoop::createDriver(void* sharedGLContext, const Platform::DriverConfig& driverConfig) noexcept {
     return NoopDriver::create();
 }
 

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -148,8 +148,8 @@ using namespace utils;
 namespace filament::backend {
 
 Driver* OpenGLDriverFactory::create(
-        OpenGLPlatform* const platform,
-        void* const sharedGLContext,
+        OpenGLPlatform* platform,
+        void* sharedGLContext,
         const Platform::DriverConfig& driverConfig) noexcept {
     return OpenGLDriver::create(platform, sharedGLContext, driverConfig);
 }
@@ -159,10 +159,10 @@ using namespace GLUtils;
 // ------------------------------------------------------------------------------------------------
 
 UTILS_NOINLINE
-OpenGLDriver* OpenGLDriver::create(OpenGLPlatform* const platform,
-        void* const /*sharedGLContext*/, const Platform::DriverConfig& driverConfig) noexcept {
+OpenGLDriver* OpenGLDriver::create(OpenGLPlatform* platform,
+        void* /*sharedGLContext*/, const Platform::DriverConfig& driverConfig) noexcept {
     assert_invariant(platform);
-    OpenGLPlatform* const ec = platform;
+    OpenGLPlatform* ec = platform;
 
 #if 0
     // this is useful for development, but too verbose even for debug builds
@@ -230,7 +230,7 @@ OpenGLDriver* OpenGLDriver::create(OpenGLPlatform* const platform,
     constexpr size_t defaultSize = FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB * 1024U * 1024U;
     Platform::DriverConfig validConfig{ driverConfig };
     validConfig.handleArenaSize = std::max(driverConfig.handleArenaSize, defaultSize);
-    OpenGLDriver* const driver = new(std::nothrow) OpenGLDriver(ec, validConfig);
+    OpenGLDriver* driver = new(std::nothrow) OpenGLDriver(ec, validConfig);
     return driver;
 }
 

filament/backend/src/opengl/platforms/PlatformCocoaTouchGL.mm

@@ -64,7 +64,7 @@ PlatformCocoaTouchGL::~PlatformCocoaTouchGL() noexcept {
     delete pImpl;
 }
 
-Driver* PlatformCocoaTouchGL::createDriver(void* const sharedGLContext, const Platform::DriverConfig& driverConfig) noexcept {
+Driver* PlatformCocoaTouchGL::createDriver(void* sharedGLContext, const Platform::DriverConfig& driverConfig) noexcept {
     EAGLSharegroup* sharegroup = (__bridge EAGLSharegroup*) sharedGLContext;
 
     EAGLContext *context = [[EAGLContext alloc] initWithAPI:kEAGLRenderingAPIOpenGLES3 sharegroup:sharegroup];

filament/backend/src/opengl/platforms/PlatformGLX.cpp

@@ -128,7 +128,7 @@ namespace filament::backend {
 
 using namespace backend;
 
-Driver* PlatformGLX::createDriver(void* const sharedGLContext,
+Driver* PlatformGLX::createDriver(void* sharedGLContext,
         const DriverConfig& driverConfig) noexcept {
     loadLibraries();
     // Get the display device

filament/backend/src/opengl/platforms/PlatformOSMesa.cpp

@@ -22,9 +22,11 @@
 #include <dlfcn.h>
 #include <memory>
 
+#if defined(__linux__)
 // This is to ensure that linking during compilation will not fail even if
 // OSMesaGetProcAddress is not linked.
 __attribute__((weak)) OSMESAproc OSMesaGetProcAddress(char const*);
+#endif
 
 namespace filament::backend {
 
@@ -48,20 +50,27 @@ struct OSMesaSwapchain {
 
 struct OSMesaAPI {
 private:
-    using CreateContextFunc = OSMesaContext (*)(GLenum format, OSMesaContext);
+    using CreateContextAttribsFunc = OSMesaContext (*)(const int *, OSMesaContext);
     using DestroyContextFunc = GLboolean (*)(OSMesaContext);
     using MakeCurrentFunc = GLboolean (*)(OSMesaContext ctx, void* buffer, GLenum type,
             GLsizei width, GLsizei height);
     using GetProcAddressFunc = OSMESAproc (*)(const char* funcName);
 
 public:
-    CreateContextFunc fOSMesaCreateContext;
+    CreateContextAttribsFunc fOSMesaCreateContextAttribs;
     DestroyContextFunc fOSMesaDestroyContext;
     MakeCurrentFunc fOSMesaMakeCurrent;
     GetProcAddressFunc fOSMesaGetProcAddress;
 
     OSMesaAPI() {
-        constexpr char const* libraryNames[] = {"libOSMesa.so", "libosmesa.so"};
+        static constexpr char const* libraryNames[] = {
+#if defined(__linux__)
+            "libOSMesa.so",
+            "libosmesa.so",
+#elif defined(__APPLE__)
+            "libOSMesa.dylib",
+#endif
+        };
         for (char const* libName: libraryNames) {
             mLib = dlopen(libName, RTLD_GLOBAL | RTLD_NOW);
             if (mLib) {
@@ -71,22 +80,24 @@ public:
         if (mLib) {
             // Loading from a libosmesa.os
             fOSMesaGetProcAddress = (GetProcAddressFunc) dlsym(mLib, "OSMesaGetProcAddress");
-        } else {
+        }
+#if defined(__linux__)
+        else {
             // Filament is built into a .so
             fOSMesaGetProcAddress = (GetProcAddressFunc) dlsym(RTLD_LOCAL, "OSMesaGetProcAddress");
         }
-
         if (!fOSMesaGetProcAddress) {
             // Statically linking osmesa
             fOSMesaGetProcAddress = OSMesaGetProcAddress;
         }
+#endif // __linux__
 
         FILAMENT_CHECK_PRECONDITION(fOSMesaGetProcAddress)
                 << "Unable to link against libOSMesa to create a software GL context";
 
-        fOSMesaCreateContext = (CreateContextFunc) fOSMesaGetProcAddress("OSMesaCreateContext");
-        fOSMesaDestroyContext =
-                (DestroyContextFunc) fOSMesaGetProcAddress("OSMesaDestroyContext");
+        fOSMesaCreateContextAttribs =
+                (CreateContextAttribsFunc) fOSMesaGetProcAddress("OSMesaCreateContextAttribs");
+        fOSMesaDestroyContext = (DestroyContextFunc) fOSMesaGetProcAddress("OSMesaDestroyContext");
         fOSMesaMakeCurrent = (MakeCurrentFunc) fOSMesaGetProcAddress("OSMesaMakeCurrent");
     }
 
@@ -101,14 +112,24 @@ private:
 
 }// anonymous namespace
 
-Driver* PlatformOSMesa::createDriver(void* const sharedGLContext,
+Driver* PlatformOSMesa::createDriver(void* sharedGLContext,
         const DriverConfig& driverConfig) noexcept {
+
     OSMesaAPI* api = new OSMesaAPI();
     mOsMesaApi = api;
 
+    static constexpr int attribs[] = {
+        OSMESA_FORMAT, GL_RGBA,
+        OSMESA_DEPTH_BITS, 24,
+        OSMESA_STENCIL_BITS, 8,
+        OSMESA_ACCUM_BITS, 0,
+        OSMESA_PROFILE, OSMESA_CORE_PROFILE,
+        0,
+    };
+
     FILAMENT_CHECK_PRECONDITION(sharedGLContext == nullptr)
             << "shared GL context is not supported with PlatformOSMesa";
-    mContext = api->fOSMesaCreateContext(GL_RGBA, NULL);
+    mContext = api->fOSMesaCreateContextAttribs(attribs, NULL);
 
     // We need to do a no-op makecurrent here so that the context will be in a correct state before
     // any GL calls.

filament/backend/src/opengl/platforms/PlatformWGL.cpp

@@ -75,7 +75,7 @@ struct WGLSwapChain {
 
 static PFNWGLCREATECONTEXTATTRIBSARBPROC wglCreateContextAttribs = nullptr;
 
-Driver* PlatformWGL::createDriver(void* const sharedGLContext,
+Driver* PlatformWGL::createDriver(void* sharedGLContext,
         const Platform::DriverConfig& driverConfig) noexcept {
     int result = 0;
     int pixelFormat = 0;

filament/backend/src/opengl/platforms/PlatformWebGL.cpp

@@ -20,7 +20,7 @@ namespace filament::backend {
 
 using namespace backend;
 
-Driver* PlatformWebGL::createDriver(void* const sharedGLContext,
+Driver* PlatformWebGL::createDriver(void* sharedGLContext,
         const Platform::DriverConfig& driverConfig) noexcept {
     return OpenGLPlatform::createDefaultDriver(this, sharedGLContext, driverConfig);
 }

filament/backend/src/vulkan/VulkanConstants.h

@@ -93,7 +93,7 @@
 #endif
 
 #ifndef NDEBUG
-#define FVK_DEBUG_FLAGS (FVK_DEBUG_PERFORMANCE | FVK_DEBUG_FORWARDED_FLAG)
+#define FVK_DEBUG_FLAGS (FVK_DEBUG_PERFORMANCE | FVK_DEBUG_FORWARDED_FLAG | FVK_DEBUG_VALIDATION)
 #else
 #define FVK_DEBUG_FLAGS 0
 #endif

filament/backend/src/vulkan/VulkanDescriptorSetCache.cpp

@@ -14,35 +14,25 @@
  * limitations under the License.
  */
 
-#include "VulkanDescriptorSetManager.h"
+#include "VulkanDescriptorSetCache.h"
 
-#include "vulkan/VulkanCommands.h"
-#include "vulkan/VulkanHandles.h"
-#include "vulkan/VulkanConstants.h"
+#include "VulkanCommands.h"
+#include "VulkanHandles.h"
+#include "VulkanConstants.h"
 
 #include <utils/FixedCapacityVector.h>
 #include <utils/Panic.h>
 
-#include <math.h>
-
 #include <algorithm>
 #include <memory>
-#include <type_traits>
 #include <vector>
 
 namespace filament::backend {
 
 namespace {
 
-using BitmaskGroup = VulkanDescriptorSetLayout::Bitmask;
 using DescriptorCount = VulkanDescriptorSetLayout::Count;
-using DescriptorSetLayoutArray = VulkanDescriptorSetManager::DescriptorSetLayoutArray;
-using BitmaskGroupHashFn = utils::hash::MurmurHashFn<BitmaskGroup>;
-struct BitmaskGroupEqual {
-    bool operator()(BitmaskGroup const& k1, BitmaskGroup const& k2) const {
-        return k1 == k2;
-    }
-};
+using DescriptorSetLayoutArray = VulkanDescriptorSetCache::DescriptorSetLayoutArray;
 
 // We create a pool for each layout as defined by the number of descriptors of each type. For
 // example, a layout of
@@ -199,72 +189,12 @@ struct Equal {
     }
 };
 
-template<typename Bitmask>
-uint32_t createBindings(VkDescriptorSetLayoutBinding* toBind, uint32_t count, VkDescriptorType type,
-        Bitmask const& mask) {
-    Bitmask alreadySeen;
-    mask.forEachSetBit([&](size_t index) {
-        VkShaderStageFlags stages = 0;
-        uint32_t binding = 0;
-        if (index < fvkutils::getFragmentStageShift<Bitmask>()) {
-            binding = (uint32_t) index;
-            stages |= VK_SHADER_STAGE_VERTEX_BIT;
-            auto fragIndex = index + fvkutils::getFragmentStageShift<Bitmask>();
-            if (mask.test(fragIndex)) {
-                stages |= VK_SHADER_STAGE_FRAGMENT_BIT;
-                alreadySeen.set(fragIndex);
-            }
-        } else if (!alreadySeen.test(index)) {
-            // We are in fragment stage bits
-            binding = (uint32_t) (index - fvkutils::getFragmentStageShift<Bitmask>());
-            stages |= VK_SHADER_STAGE_FRAGMENT_BIT;
-        }
-
-        if (stages) {
-            toBind[count++] = {
-                .binding = binding,
-                .descriptorType = type,
-                .descriptorCount = 1,
-                .stageFlags = stages,
-            };
-        }
-    });
-    return count;
-}
-
-inline VkDescriptorSetLayout createLayout(VkDevice device, BitmaskGroup const& bitmaskGroup) {
-    // Note that the following *needs* to be static so that VkDescriptorSetLayoutCreateInfo will not
-    // refer to stack memory.
-    VkDescriptorSetLayoutBinding toBind[VulkanDescriptorSetLayout::MAX_BINDINGS];
-    uint32_t count = 0;
-
-    count = createBindings(toBind, count, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC,
-            bitmaskGroup.dynamicUbo);
-    count = createBindings(toBind, count, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, bitmaskGroup.ubo);
-    count = createBindings(toBind, count, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
-            bitmaskGroup.sampler);
-    count = createBindings(toBind, count, VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT,
-            bitmaskGroup.inputAttachment);
-
-    assert_invariant(count != 0 && "Need at least one binding for descriptor set layout.");
-    VkDescriptorSetLayoutCreateInfo dlinfo = {
-            .sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO,
-            .pNext = nullptr,
-            .bindingCount = count,
-            .pBindings = toBind,
-    };
-
-    VkDescriptorSetLayout layout;
-    vkCreateDescriptorSetLayout(device, &dlinfo, VKALLOC, &layout);
-    return layout;
-}
-
 } // anonymous namespace
 
 // This is an ever-expanding pool of sets where it
 //    1. Keeps a list of smaller pools of different layout-dimensions.
 //    2. Will add a pool if existing pool are not compatible with the requested layout o runs out.
-class VulkanDescriptorSetManager::DescriptorInfinitePool {
+class VulkanDescriptorSetCache::DescriptorInfinitePool {
 private:
     static constexpr uint16_t EXPECTED_SET_COUNT = 10;
     static constexpr float SET_COUNT_GROWTH_FACTOR = 1.5;
@@ -319,61 +249,34 @@ private:
     std::vector<std::unique_ptr<DescriptorPool>> mPools;
 };
 
-class VulkanDescriptorSetManager::DescriptorSetLayoutManager {
-public:
-    DescriptorSetLayoutManager(VkDevice device)
-        : mDevice(device) {}
 
-    VkDescriptorSetLayout getVkLayout(VulkanDescriptorSetLayout::Bitmask const& bitmasks) {
-        if (auto itr = mVkLayouts.find(bitmasks); itr != mVkLayouts.end()) {
-            return itr->second;
-        }
-        auto vklayout = createLayout(mDevice, bitmasks);
-        mVkLayouts[bitmasks] = vklayout;
-        return vklayout;
-    }
-
-    ~DescriptorSetLayoutManager() {
-        for (auto& itr: mVkLayouts) {
-            vkDestroyDescriptorSetLayout(mDevice, itr.second, VKALLOC);
-        }
-    }
-
-private:
-    VkDevice mDevice;
-    tsl::robin_map<BitmaskGroup, VkDescriptorSetLayout, BitmaskGroupHashFn, BitmaskGroupEqual>
-            mVkLayouts;
-};
-
-VulkanDescriptorSetManager::VulkanDescriptorSetManager(VkDevice device,
+VulkanDescriptorSetCache::VulkanDescriptorSetCache(VkDevice device,
         fvkmemory::ResourceManager* resourceManager)
     : mDevice(device),
       mResourceManager(resourceManager),
-      mLayoutManager(std::make_unique<DescriptorSetLayoutManager>(device)),
       mDescriptorPool(std::make_unique<DescriptorInfinitePool>(device)) {}
 
-VulkanDescriptorSetManager::~VulkanDescriptorSetManager() = default;
+VulkanDescriptorSetCache::~VulkanDescriptorSetCache() = default;
 
-void VulkanDescriptorSetManager::terminate() noexcept{
-    mLayoutManager.reset();
+void VulkanDescriptorSetCache::terminate() noexcept{
     mDescriptorPool.reset();
     clearHistory();
 }
 
 // bind() is not really binding the set but just stashing until we have all the info
 // (pipelinelayout).
-void VulkanDescriptorSetManager::bind(uint8_t setIndex,
+void VulkanDescriptorSetCache::bind(uint8_t setIndex,
         fvkmemory::resource_ptr<VulkanDescriptorSet> set,
         backend::DescriptorSetOffsetArray&& offsets) {
     set->setOffsets(std::move(offsets));
     mStashedSets[setIndex] = set;
 }
 
-void VulkanDescriptorSetManager::unbind(uint8_t setIndex) {
+void VulkanDescriptorSetCache::unbind(uint8_t setIndex) {
     mStashedSets[setIndex] = {};
 }
 
-void VulkanDescriptorSetManager::commit(VulkanCommandBuffer* commands,
+void VulkanDescriptorSetCache::commit(VulkanCommandBuffer* commands,
         VkPipelineLayout pipelineLayout, fvkutils::DescriptorSetMask const& setMask) {
     // setMask indicates the set of descriptor sets the driver wants to bind, curMask is the
     // actual set of sets that *needs* to be bound.
@@ -412,7 +315,7 @@ void VulkanDescriptorSetManager::commit(VulkanCommandBuffer* commands,
     };
 }
 
-void VulkanDescriptorSetManager::updateBuffer(fvkmemory::resource_ptr<VulkanDescriptorSet> set,
+void VulkanDescriptorSetCache::updateBuffer(fvkmemory::resource_ptr<VulkanDescriptorSet> set,
         uint8_t binding, fvkmemory::resource_ptr<VulkanBufferObject> bufferObject,
         VkDeviceSize offset, VkDeviceSize size) noexcept {
     VkDescriptorBufferInfo const info = {
@@ -438,7 +341,7 @@ void VulkanDescriptorSetManager::updateBuffer(fvkmemory::resource_ptr<VulkanDesc
     set->acquire(bufferObject);
 }
 
-void VulkanDescriptorSetManager::updateSampler(fvkmemory::resource_ptr<VulkanDescriptorSet> set,
+void VulkanDescriptorSetCache::updateSampler(fvkmemory::resource_ptr<VulkanDescriptorSet> set,
         uint8_t binding, fvkmemory::resource_ptr<VulkanTexture> texture,
         VkSampler sampler) noexcept {
     VkDescriptorImageInfo info{
@@ -470,13 +373,13 @@ void VulkanDescriptorSetManager::updateSampler(fvkmemory::resource_ptr<VulkanDes
     set->acquire(texture);
 }
 
-void VulkanDescriptorSetManager::updateInputAttachment(
+void VulkanDescriptorSetCache::updateInputAttachment(
         fvkmemory::resource_ptr<VulkanDescriptorSet> set,
         VulkanAttachment const& attachment) noexcept {
-    // TOOD: fill-in this region
+    // TOOD: fill this in.
 }
 
-fvkmemory::resource_ptr<VulkanDescriptorSet> VulkanDescriptorSetManager::createSet(
+fvkmemory::resource_ptr<VulkanDescriptorSet> VulkanDescriptorSetCache::createSet(
         Handle<HwDescriptorSet> handle, fvkmemory::resource_ptr<VulkanDescriptorSetLayout> layout) {
     auto const vkSet = mDescriptorPool->obtainSet(layout);
     auto const& count = layout->count;
@@ -492,12 +395,7 @@ fvkmemory::resource_ptr<VulkanDescriptorSet> VulkanDescriptorSetManager::createS
             });
 }
 
-void VulkanDescriptorSetManager::initVkLayout(
-        fvkmemory::resource_ptr<VulkanDescriptorSetLayout> layout) {
-    layout->setVkLayout(mLayoutManager->getVkLayout(layout->bitmask));
-}
-
-void VulkanDescriptorSetManager::clearHistory() {
+void VulkanDescriptorSetCache::clearHistory() {
     mStashedSets = {};
 }
 

filament/backend/src/vulkan/VulkanDescriptorSetCache.h

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 
-#ifndef TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETMANAGER_H
-#define TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETMANAGER_H
+#ifndef TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETCACHE_H
+#define TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETCACHE_H
 
-#include "vulkan/VulkanHandles.h"
+#include "VulkanHandles.h"
 #include "vulkan/memory/ResourcePointer.h"
 #include "vulkan/utils/Definitions.h"  // For DescriptorSetMask
 
@@ -34,20 +34,16 @@
 
 namespace filament::backend {
 
-// [GDSR]: Great-Descriptor-Set-Refactor: As of 03/20/24, the Filament frontend is planning to
-// introduce descriptor set. This PR will arrive before that change is complete. As such, some of
-// the methods introduced here will be obsolete, and certain logic will be generalized.
-
-// Abstraction over the pool and the layout cache.
-class VulkanDescriptorSetManager {
+// Abstraction over the descriptor set pool.
+class VulkanDescriptorSetCache {
 public:
     static constexpr uint8_t UNIQUE_DESCRIPTOR_SET_COUNT =
             VulkanDescriptorSetLayout::UNIQUE_DESCRIPTOR_SET_COUNT;
 
     using DescriptorSetLayoutArray = VulkanDescriptorSetLayout::DescriptorSetLayoutArray;
 
-    VulkanDescriptorSetManager(VkDevice device, fvkmemory::ResourceManager* resourceManager);
-    ~VulkanDescriptorSetManager();
+    VulkanDescriptorSetCache(VkDevice device, fvkmemory::ResourceManager* resourceManager);
+    ~VulkanDescriptorSetCache();
 
     void terminate() noexcept;
 
@@ -72,12 +68,9 @@ public:
     fvkmemory::resource_ptr<VulkanDescriptorSet> createSet(Handle<HwDescriptorSet> handle,
             fvkmemory::resource_ptr<VulkanDescriptorSetLayout> layout);
 
-    void initVkLayout(fvkmemory::resource_ptr<VulkanDescriptorSetLayout> layout);
-
     void clearHistory();
 
 private:
-    class DescriptorSetLayoutManager;
     class DescriptorInfinitePool;
 
     using DescriptorSetArray =
@@ -85,7 +78,6 @@ private:
 
     VkDevice mDevice;
     fvkmemory::ResourceManager* mResourceManager;
-    std::unique_ptr<DescriptorSetLayoutManager> mLayoutManager;
     std::unique_ptr<DescriptorInfinitePool> mDescriptorPool;
     std::pair<VulkanAttachment, VkDescriptorImageInfo> mInputAttachment;
     DescriptorSetArray mStashedSets = {};
@@ -99,4 +91,4 @@ private:
 
 }// namespace filament::backend
 
-#endif// TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETMANAGER_H
+#endif// TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETCACHE_H

filament/backend/src/vulkan/VulkanDescriptorSetLayoutCache.cpp

@@ -0,0 +1,110 @@
+/*
+ * Copyright (C) 2025 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.
+ */
+
+#include "VulkanDescriptorSetLayoutCache.h"
+
+#include "VulkanHandles.h"
+
+namespace filament::backend {
+
+namespace {
+
+using BitmaskGroup = VulkanDescriptorSetLayout::Bitmask;
+
+template<typename Bitmask>
+uint32_t appendBindings(VkDescriptorSetLayoutBinding* toBind, VkDescriptorType type,
+        Bitmask const& mask) {
+    uint32_t count = 0;
+    Bitmask alreadySeen;
+    mask.forEachSetBit([&](size_t index) {
+        VkShaderStageFlags stages = 0;
+        uint32_t binding = 0;
+        if (index < fvkutils::getFragmentStageShift<Bitmask>()) {
+            binding = (uint32_t) index;
+            stages |= VK_SHADER_STAGE_VERTEX_BIT;
+            auto fragIndex = index + fvkutils::getFragmentStageShift<Bitmask>();
+            if (mask.test(fragIndex)) {
+                stages |= VK_SHADER_STAGE_FRAGMENT_BIT;
+                alreadySeen.set(fragIndex);
+            }
+        } else if (!alreadySeen.test(index)) {
+            // We are in fragment stage bits
+            binding = (uint32_t) (index - fvkutils::getFragmentStageShift<Bitmask>());
+            stages |= VK_SHADER_STAGE_FRAGMENT_BIT;
+        }
+
+        if (stages) {
+            toBind[count++] = {
+                .binding = binding,
+                .descriptorType = type,
+                .descriptorCount = 1,
+                .stageFlags = stages,
+            };
+        }
+    });
+    return count;
+}
+
+} // anonymous namespace
+
+VulkanDescriptorSetLayoutCache::VulkanDescriptorSetLayoutCache(VkDevice device,
+        fvkmemory::ResourceManager* resourceManager)
+    : mDevice(device),
+      mResourceManager(resourceManager) {}
+
+VulkanDescriptorSetLayoutCache::~VulkanDescriptorSetLayoutCache() = default;
+
+void VulkanDescriptorSetLayoutCache::terminate() noexcept {
+    for (auto& itr: mVkLayouts) {
+        vkDestroyDescriptorSetLayout(mDevice, itr.second, VKALLOC);
+    }
+}
+
+fvkmemory::resource_ptr<VulkanDescriptorSetLayout> VulkanDescriptorSetLayoutCache::createLayout(
+        Handle<HwDescriptorSetLayout> handle, backend::DescriptorSetLayout&& info) {
+    auto layout = fvkmemory::resource_ptr<VulkanDescriptorSetLayout>::make(mResourceManager, handle,
+            info);
+    VkDescriptorSetLayout vklayout = VK_NULL_HANDLE;
+    auto const& bitmasks = layout->bitmask;
+    if (auto itr = mVkLayouts.find(bitmasks); itr != mVkLayouts.end()) {
+        vklayout = itr->second;
+    } else {
+        VkDescriptorSetLayoutBinding toBind[VulkanDescriptorSetLayout::MAX_BINDINGS];
+        uint32_t count = 0;
+        count += appendBindings(&toBind[count], VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC,
+                bitmasks.dynamicUbo);
+        count += appendBindings(&toBind[count], VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, bitmasks.ubo);
+        count += appendBindings(&toBind[count], VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
+                bitmasks.sampler);
+        count += appendBindings(&toBind[count], VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT,
+                bitmasks.inputAttachment);
+
+        assert_invariant(count != 0 && "Need at least one binding for descriptor set layout.");
+        VkDescriptorSetLayoutCreateInfo dlinfo = {
+            .sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO,
+            .pNext = nullptr,
+            .bindingCount = count,
+            .pBindings = toBind,
+        };
+
+        vkCreateDescriptorSetLayout(mDevice, &dlinfo, VKALLOC, &vklayout);
+        mVkLayouts[bitmasks] = vklayout;
+    }
+    layout->setVkLayout(vklayout);
+    return layout;
+}
+
+} // namespace filament::backend

filament/backend/src/vulkan/VulkanDescriptorSetLayoutCache.h

@@ -0,0 +1,63 @@
+/*
+ * Copyright (C) 2025 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 TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETLAYOUTCACHE_H
+#define TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETLAYOUTCACHE_H
+
+#include "VulkanHandles.h"
+
+#include "vulkan/memory/ResourcePointer.h"
+
+#include <backend/DriverEnums.h>
+#include <backend/Program.h>
+#include <backend/TargetBufferInfo.h>
+
+#include <utils/bitset.h>
+
+#include <bluevk/BlueVK.h>
+#include <tsl/robin_map.h>
+
+#include <memory>
+
+namespace filament::backend {
+
+class VulkanDescriptorSetLayoutCache {
+public:
+    VulkanDescriptorSetLayoutCache(VkDevice device, fvkmemory::ResourceManager* resourceManager);
+    ~VulkanDescriptorSetLayoutCache();
+
+    void terminate() noexcept;
+
+    fvkmemory::resource_ptr<VulkanDescriptorSetLayout> createLayout(
+            Handle<HwDescriptorSetLayout> handle, backend::DescriptorSetLayout&& info);
+
+private:
+    VkDevice mDevice;
+    fvkmemory::ResourceManager* mResourceManager;
+
+    using BitmaskGroup = VulkanDescriptorSetLayout::Bitmask;
+    using BitmaskGroupHashFn = utils::hash::MurmurHashFn<BitmaskGroup>;
+    struct BitmaskGroupEqual {
+        bool operator()(BitmaskGroup const& k1, BitmaskGroup const& k2) const { return k1 == k2; }
+    };
+
+    tsl::robin_map<BitmaskGroup, VkDescriptorSetLayout, BitmaskGroupHashFn, BitmaskGroupEqual>
+            mVkLayouts;
+};
+
+} // namespace filament::backend
+
+#endif// TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETLAYOUTCACHE_H

filament/backend/src/vulkan/VulkanDriver.cpp

@@ -17,7 +17,6 @@
 #include "VulkanDriver.h"
 
 #include "CommandStreamDispatcher.h"
-#include "DataReshaper.h"
 #include "SystraceProfile.h"
 #include "VulkanAsyncHandles.h"
 #include "VulkanBuffer.h"
@@ -35,7 +34,6 @@
 #include <backend/platforms/VulkanPlatform.h>
 
 #include <utils/CString.h>
-#include <utils/FixedCapacityVector.h>
 #include <utils/Panic.h>
 
 #ifndef NDEBUG
@@ -44,8 +42,6 @@
 
 using namespace bluevk;
 
-using utils::FixedCapacityVector;
-
 #if defined(__clang__)
 // Vulkan functions often immediately dereference pointers, so it's fine to pass in a pointer
 // to a stack-allocated variable.
@@ -219,7 +215,8 @@ VulkanDriver::VulkanDriver(VulkanPlatform* platform, VulkanContext const& contex
       mSamplerCache(mPlatform->getDevice()),
       mBlitter(mPlatform->getPhysicalDevice(), &mCommands),
       mReadPixels(mPlatform->getDevice()),
-      mDescriptorSetManager(mPlatform->getDevice(), &mResourceManager),
+      mDescriptorSetLayoutCache(mPlatform->getDevice(), &mResourceManager),
+      mDescriptorSetCache(mPlatform->getDevice(), &mResourceManager),
       mQueryManager(mPlatform->getDevice()),
       mIsSRGBSwapChainSupported(mPlatform->getCustomization().isSRGBSwapChainSupported),
       mStereoscopicType(driverConfig.stereoscopicType) {
@@ -329,7 +326,8 @@ void VulkanDriver::terminate() {
     mPipelineCache.terminate();
     mFramebufferCache.reset();
     mSamplerCache.terminate();
-    mDescriptorSetManager.terminate();
+    mDescriptorSetLayoutCache.terminate();
+    mDescriptorSetCache.terminate();
     mPipelineLayoutCache.terminate();
 
     // Before terminating ResourceManager, we must make sure all of the resource_ptrs have been unset.
@@ -365,7 +363,7 @@ void VulkanDriver::collectGarbage() {
     FVK_SYSTRACE_SCOPE();
     // Command buffers need to be submitted and completed before other resources can be gc'd.
     mCommands.gc();
-    mDescriptorSetManager.clearHistory();
+    mDescriptorSetCache.clearHistory();
     mStagePool.gc();
     mFramebufferCache.gc();
     mPipelineCache.gc();
@@ -408,7 +406,7 @@ void VulkanDriver::updateDescriptorSetBuffer(
     FVK_SYSTRACE_SCOPE();
     auto set = resource_ptr<VulkanDescriptorSet>::cast(&mResourceManager, dsh);
     auto buffer = resource_ptr<VulkanBufferObject>::cast(&mResourceManager, boh);
-    mDescriptorSetManager.updateBuffer(set, binding, buffer, offset, size);
+    mDescriptorSetCache.updateBuffer(set, binding, buffer, offset, size);
 }
 
 void VulkanDriver::updateDescriptorSetTexture(
@@ -421,7 +419,7 @@ void VulkanDriver::updateDescriptorSetTexture(
     auto texture = resource_ptr<VulkanTexture>::cast(&mResourceManager, th);
 
     VkSampler const vksampler = mSamplerCache.getSampler(params);
-    mDescriptorSetManager.updateSampler(set, binding, texture, vksampler);
+    mDescriptorSetCache.updateSampler(set, binding, texture, vksampler);
 }
 
 void VulkanDriver::flush(int) {
@@ -778,8 +776,7 @@ void VulkanDriver::createTimerQueryR(Handle<HwTimerQuery> tqh, int) {
 
 void VulkanDriver::createDescriptorSetLayoutR(Handle<HwDescriptorSetLayout> dslh,
         backend::DescriptorSetLayout&& info) {
-    auto layout = resource_ptr<VulkanDescriptorSetLayout>::make(&mResourceManager, dslh, info);
-    mDescriptorSetManager.initVkLayout(layout);
+    auto layout = mDescriptorSetLayoutCache.createLayout(dslh, std::move(info));
     layout.inc();
 }
 
@@ -788,7 +785,7 @@ void VulkanDriver::createDescriptorSetR(Handle<HwDescriptorSet> dsh,
     FVK_SYSTRACE_SCOPE();
     fvkmemory::resource_ptr<VulkanDescriptorSetLayout> layout =
             fvkmemory::resource_ptr<VulkanDescriptorSetLayout>::cast(&mResourceManager, dslh);
-    auto set = mDescriptorSetManager.createSet(dsh, layout);
+    auto set = mDescriptorSetCache.createSet(dsh, layout);
     set.inc();
 }
 
@@ -1149,7 +1146,7 @@ size_t VulkanDriver::getMaxUniformBufferSize() {
 
 size_t VulkanDriver::getMaxTextureSize(SamplerType) {
     // TODO: return the actual size instead of hardcoded value
-    return 4096;
+    return 2048;
 }
 
 size_t VulkanDriver::getMaxArrayTextureLayers() {
@@ -1493,7 +1490,7 @@ void VulkanDriver::nextSubpass(int) {
 
     if (mCurrentRenderPass.params.subpassMask & 0x1) {
         VulkanAttachment& subpassInput = renderTarget->getColor0();
-        mDescriptorSetManager.updateInputAttachment({}, subpassInput);
+        mDescriptorSetCache.updateInputAttachment({}, subpassInput);
     }
 }
 
@@ -1820,9 +1817,9 @@ void VulkanDriver::bindDescriptorSet(
         backend::DescriptorSetOffsetArray&& offsets) {
     if (dsh) {
         auto set = resource_ptr<VulkanDescriptorSet>::cast(&mResourceManager, dsh);
-        mDescriptorSetManager.bind(setIndex, set, std::move(offsets));
+        mDescriptorSetCache.bind(setIndex, set, std::move(offsets));
     } else {
-        mDescriptorSetManager.unbind(setIndex);
+        mDescriptorSetCache.unbind(setIndex);
     }
 }
 
@@ -1830,7 +1827,7 @@ void VulkanDriver::draw2(uint32_t indexOffset, uint32_t indexCount, uint32_t ins
     FVK_SYSTRACE_SCOPE();
     VkCommandBuffer cmdbuffer = mCurrentRenderPass.commandBuffer->buffer();
 
-    mDescriptorSetManager.commit(mCurrentRenderPass.commandBuffer,
+    mDescriptorSetCache.commit(mCurrentRenderPass.commandBuffer,
             mBoundPipeline.pipelineLayout,
             mBoundPipeline.descriptorSetMask);
 

filament/backend/src/vulkan/VulkanDriver.h

@@ -27,8 +27,9 @@
 #include "VulkanSamplerCache.h"
 #include "VulkanStagePool.h"
 #include "VulkanQueryManager.h"
-#include "vulkan/caching/VulkanDescriptorSetManager.h"
-#include "vulkan/caching/VulkanPipelineLayoutCache.h"
+#include "vulkan/VulkanDescriptorSetCache.h"
+#include "vulkan/VulkanDescriptorSetLayoutCache.h"
+#include "vulkan/VulkanPipelineLayoutCache.h"
 #include "vulkan/memory/ResourceManager.h"
 #include "vulkan/memory/ResourcePointer.h"
 #include "vulkan/utils/Definitions.h"
@@ -137,7 +138,8 @@ private:
     VulkanSamplerCache mSamplerCache;
     VulkanBlitter mBlitter;
     VulkanReadPixels mReadPixels;
-    VulkanDescriptorSetManager mDescriptorSetManager;
+    VulkanDescriptorSetLayoutCache mDescriptorSetLayoutCache;
+    VulkanDescriptorSetCache mDescriptorSetCache;
     VulkanQueryManager mQueryManager;
 
     // This is necessary for us to write to push constants after binding a pipeline.

filament/backend/src/vulkan/VulkanPipelineCache.cpp

@@ -15,15 +15,12 @@
  */
 
 #include "VulkanPipelineCache.h"
-#include "VulkanMemory.h"
-#include "caching/VulkanDescriptorSetManager.h"
 
 #include <utils/Log.h>
 #include <utils/Panic.h>
 
 #include "VulkanConstants.h"
 #include "VulkanHandles.h"
-#include "VulkanTexture.h"
 #include "vulkan/utils/Conversion.h"
 
 #if defined(__clang__)

filament/backend/src/vulkan/VulkanPipelineLayoutCache.h

@@ -17,7 +17,8 @@
 #ifndef TNT_FILAMENT_BACKEND_VULKANPIPELINELAYOUTCACHE_H
 #define TNT_FILAMENT_BACKEND_VULKANPIPELINELAYOUTCACHE_H
 
-#include <vulkan/VulkanHandles.h>
+#include "VulkanHandles.h"
+
 #include <bluevk/BlueVK.h>
 
 #include <utils/Hash.h>

filament/backend/src/vulkan/platform/VulkanPlatformAndroid.cpp

@@ -223,6 +223,19 @@ Platform::ExternalImageHandle VulkanPlatformAndroid::createExternalImage(
     return Platform::ExternalImageHandle{};
 }
 
+VulkanPlatformAndroid::ExternalImageDescAndroid VulkanPlatformAndroid::getExternalImageDesc(
+        ExternalImageHandleRef externalImage) const noexcept {
+    auto const* fvkExternalImage =
+            static_cast<ExternalImageVulkanAndroid const*>(externalImage.get());
+
+    return {
+        .width = fvkExternalImage->width,
+        .height = fvkExternalImage->height,
+        .format = fvkExternalImage->format,
+        .usage = fvkExternalImage->usage,
+    };
+}
+
 VulkanPlatform::ExternalImageMetadata VulkanPlatformAndroid::getExternalImageMetadata(
         ExternalImageHandleRef externalImage) {
     auto const* fvkExternalImage =

filament/backend/src/webgpu/platform/WebGPUPlatform.cpp

@@ -143,7 +143,7 @@ wgpu::Device WebGPUPlatform::requestDevice(wgpu::Adapter const& adapter) {
     return device;
 }
 
-Driver* WebGPUPlatform::createDriver(void* const sharedContext,
+Driver* WebGPUPlatform::createDriver(void* sharedContext,
         const Platform::DriverConfig& /*driverConfig*/) noexcept {
     if (sharedContext) {
         FWGPU_LOGW << "sharedContext is ignored/unused in the WebGPU backend. A non-null "

filament/backend/src/webgpu/platform/WebGPUPlatformLinux.cpp

@@ -15,6 +15,8 @@
  */
 #include <backend/platforms/WebGPUPlatform.h>
 
+#include <backend/DriverEnums.h>
+
 #include <utils/Panic.h>
 
 #include <webgpu/webgpu_cpp.h>
@@ -118,7 +120,9 @@ wgpu::Surface WebGPUPlatform::createSurface(void* nativeWindow, uint64_t flags)
         if (useXcb) {
             wgpu::SurfaceSourceXCBWindow surfaceSourceXcb{};
             surfaceSourceXcb.connection = g_x11.connection;
-            surfaceSourceXcb.window = reinterpret_cast<uint32_t>(nativeWindow);
+
+            // TODO: this looks really wrong, please fix!!
+            surfaceSourceXcb.window = *((uint32_t*) nativeWindow);
             wgpu::SurfaceDescriptor surfaceDescriptor{
                 .nextInChain = &surfaceSourceXcb,
                 .label = "linux_xcb_surface"

filament/include/filament/Engine.h

@@ -317,15 +317,6 @@ public:
          */
         size_t metalUploadBufferSizeBytes = 512 * 1024;
 
-        /**
-         * The action to take if a Drawable cannot be acquired.
-         *
-         * Each frame rendered requires a CAMetalDrawable texture, which is
-         * presented on-screen at the completion of each frame. These are
-         * limited and provided round-robin style by the system.
-         */
-        bool metalDisablePanicOnDrawableFailure = false;
-
         /**
          * Set to `true` to forcibly disable parallel shader compilation in the backend.
          * Currently only honored by the GL and Metal backends.

filament/src/details/ColorGrading.cpp

@@ -664,8 +664,7 @@ FColorGrading::FColorGrading(FEngine& engine, const Builder& builder) {
     // spaces are the same, but we currently don't check that. We must revise these conditions if we
     // ever handle this case.
     mIsOneDimensional = !builder->hasAdjustments && !builder->luminanceScaling
-            && builder->toneMapper->isOneDimensional()
-            && engine.features.engine.color_grading.use_1d_lut;
+            && builder->toneMapper->isOneDimensional();
     mIsLDR = mIsOneDimensional && builder->toneMapper->isLDR();
 
     const Config config = {

filament/src/details/Engine.cpp

@@ -138,7 +138,6 @@ Engine* FEngine::create(Builder const& builder) {
                 .forceGLES2Context = instance->getConfig().forceGLES2Context,
                 .stereoscopicType = instance->getConfig().stereoscopicType,
                 .assertNativeWindowIsValid = instance->features.backend.opengl.assert_native_window_is_valid,
-                .metalDisablePanicOnDrawableFailure = instance->getConfig().metalDisablePanicOnDrawableFailure,
         };
         instance->mDriver = platform->createDriver(sharedContext, driverConfig);
 
@@ -734,7 +733,6 @@ int FEngine::loop() {
             .forceGLES2Context = mConfig.forceGLES2Context,
             .stereoscopicType =  mConfig.stereoscopicType,
             .assertNativeWindowIsValid = features.backend.opengl.assert_native_window_is_valid,
-            .metalDisablePanicOnDrawableFailure = mConfig.metalDisablePanicOnDrawableFailure,
     };
     mDriver = mPlatform->createDriver(mSharedGLContext, driverConfig);
 

filament/src/details/Engine.h

@@ -687,9 +687,6 @@ public:
 
     struct {
         struct {
-            struct {
-                bool use_1d_lut = false;
-            } color_grading;
             struct {
                 bool use_shadow_atlas = false;
             } shadows;
@@ -722,9 +719,6 @@ public:
             { "backend.opengl.assert_native_window_is_valid",
               "Asserts that the ANativeWindow is valid when rendering starts.",
               &features.backend.opengl.assert_native_window_is_valid, true },
-            { "engine.color_grading.use_1d_lut",
-              "Uses a 1D LUT for color grading.",
-              &features.engine.color_grading.use_1d_lut, false },
             { "engine.shadows.use_shadow_atlas",
               "Uses an array of atlases to store shadow maps.",
               &features.engine.shadows.use_shadow_atlas, false },

ios/CocoaPods/Filament.podspec

@@ -1,12 +1,12 @@
 Pod::Spec.new do |spec|
   spec.name = "Filament"
-  spec.version = "1.58.2"
+  spec.version = "1.58.1"
   spec.license = { :type => "Apache 2.0", :file => "LICENSE" }
   spec.homepage = "https://google.github.io/filament"
   spec.authors = "Google LLC."
   spec.summary = "Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WASM/WebGL."
   spec.platform = :ios, "11.0"
-  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.58.2/filament-v1.58.2-ios.tgz" }
+  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.58.1/filament-v1.58.1-ios.tgz" }
 
   # Fix linking error with Xcode 12; we do not yet support the simulator on Apple silicon.
   spec.pod_target_xcconfig = {

libs/bluegl/CMakeLists.txt

@@ -31,13 +31,17 @@ if (WIN32)
         set(SRCS ${SRCS} src/BlueGLCoreWindowsImpl.S)
     endif()
 elseif (APPLE AND NOT IOS)
-    set(SRCS ${SRCS} src/BlueGLDarwin.cpp)
+    if (FILAMENT_SUPPORTS_OSMESA)
+        set(SRCS ${SRCS} src/BlueGLOSMesa.cpp)
+    else()
+        set(SRCS ${SRCS} src/BlueGLDarwin.cpp)
+    endif()
     set(SRCS ${SRCS} src/BlueGLCoreDarwinUniversalImpl.S)
 elseif(LINUX)
-    if(FILAMENT_SUPPORTS_EGL_ON_LINUX)
+    if (FILAMENT_SUPPORTS_EGL_ON_LINUX)
         set(SRCS ${SRCS} src/BlueGLLinuxEGL.cpp)
-    elseif(FILAMENT_SUPPORTS_OSMESA)
-        set(SRCS ${SRCS} src/BlueGLLinuxOSMesa.cpp)
+    elseif (FILAMENT_SUPPORTS_OSMESA)
+        set(SRCS ${SRCS} src/BlueGLOSMesa.cpp)
     else()
         set(SRCS ${SRCS} src/BlueGLLinux.cpp)
     endif()
@@ -53,7 +57,11 @@ include_directories(${PUBLIC_HDR_DIR})
 add_library(${TARGET} STATIC ${PUBLIC_HDRS} ${SRCS})
 
 if(FILAMENT_SUPPORTS_OSMESA)
-    target_compile_options(${TARGET} PRIVATE -I${FILAMENT_OSMESA_PATH}/include/GL)
+    if (APPLE)
+        target_compile_options(${TARGET} PRIVATE -I${FILAMENT_OSMESA_PATH}/include)
+    else()
+        target_compile_options(${TARGET} PRIVATE -I${FILAMENT_OSMESA_PATH}/include/GL)
+    endif()
 endif()
 
 # specify where the public headers of this library are

libs/bluegl/src/BlueGLOSMesa.cpp

@@ -17,42 +17,64 @@
 #include <dlfcn.h>
 #include <string.h>
 
+#if defined(__linux__)
+
 #include <osmesa.h>
 
+// This is to ensure that linking during compilation will not fail even if
+// OSMesaGetProcAddress is not linked.
+__attribute__((weak)) OSMESAproc OSMesaGetProcAddress(char const*);
+
+#elif defined(__APPLE__)
+
+#include <GL/osmesa.h>
+
+#endif // __linux__
+
+#if defined(__linux__)
+#endif
+
 namespace bluegl {
 
 namespace {
 using ProcAddressFunc = void*(*)(char const* funcName);
 }
 
-// This is to ensure that linking during compilation will not fail even if
-// OSMesaGetProcAddress is not linked.
-__attribute__((weak)) OSMESAproc OSMesaGetProcAddress(char const*);
-
 struct Driver {
     ProcAddressFunc OSMesaGetProcAddress;
     void* library;
 } g_driver = {nullptr, nullptr};
 
 bool initBinder() {
-    constexpr char const* libraryNames[] = {"libOSMesa.so", "libosmesa.so"};
+    static constexpr char const* libraryNames[] = {
+#if defined(__linux__)
+        "libOSMesa.so",
+        "libosmesa.so",
+#elif defined(__APPLE__)
+        "libOSMesa.dylib",
+#endif
+    };
     for (char const* name: libraryNames) {
         g_driver.library = dlopen(name, RTLD_GLOBAL | RTLD_NOW);
         if (g_driver.library) {
             break;
         }
     }
-    if (!g_driver.library) {
-        // The library has been linked explicitly during compile.
-        g_driver.OSMesaGetProcAddress = (ProcAddressFunc) dlsym(RTLD_LOCAL, "OSMesaGetProcAddress");
-    } else {
+    if (g_driver.library) {
+        // Linking against a libosmesa.so.
         g_driver.OSMesaGetProcAddress =
                 (ProcAddressFunc) dlsym(g_driver.library, "OSMesaGetProcAddress");
     }
-
+#if defined(__linux__)
+    else {
+        // If Filament was built as a dynamic library.
+        g_driver.OSMesaGetProcAddress = (ProcAddressFunc) dlsym(RTLD_LOCAL, "OSMesaGetProcAddress");
+    }
     if (!g_driver.OSMesaGetProcAddress) {
+        // If statically linking OSMesa.
         g_driver.OSMesaGetProcAddress = (ProcAddressFunc) OSMesaGetProcAddress;
     }
+#endif
 
     return g_driver.OSMesaGetProcAddress;
 }

libs/filabridge/include/filament/MaterialEnums.h

@@ -28,7 +28,7 @@
 namespace filament {
 
 // update this when a new version of filament wouldn't work with older materials
-static constexpr size_t MATERIAL_VERSION = 58;
+static constexpr size_t MATERIAL_VERSION = 57;
 
 /**
  * Supported shading models
@@ -203,7 +203,7 @@ enum class ReflectionMode : uint8_t {
 // can't really use std::underlying_type<AttributeIndex>::type because the driver takes a uint32_t
 using AttributeBitset = utils::bitset32;
 
-static constexpr size_t MATERIAL_PROPERTIES_COUNT = 29;
+static constexpr size_t MATERIAL_PROPERTIES_COUNT = 30;
 enum class Property : uint8_t {
     BASE_COLOR,              //!< float4, all shading models
     ROUGHNESS,               //!< float,  lit shading models only
@@ -234,6 +234,7 @@ enum class Property : uint8_t {
     BENT_NORMAL,             //!< float3, all shading models only, except unlit
     SPECULAR_FACTOR,         //!< float, lit shading models only, except subsurface and cloth
     SPECULAR_COLOR_FACTOR,   //!< float3, lit shading models only, except subsurface and cloth
+    SHADOW_STRENGTH,         //!< float, [0, 1] strength of shadows received by this material
 
     // when adding new Properties, make sure to update MATERIAL_PROPERTIES_COUNT
 };

libs/filamat/include/filamat/MaterialBuilder.h

@@ -217,12 +217,13 @@ public:
     MaterialBuilder(MaterialBuilder&& rhs) noexcept = default;
     MaterialBuilder& operator=(MaterialBuilder&& rhs) noexcept = default;
 
-    static constexpr size_t MATERIAL_VARIABLES_COUNT = 4;
+    static constexpr size_t MATERIAL_VARIABLES_COUNT = 5;
     enum class Variable : uint8_t {
         CUSTOM0,
         CUSTOM1,
         CUSTOM2,
-        CUSTOM3
+        CUSTOM3,
+        CUSTOM4, // CUSTOM4 is only available if the vertex attribute `color` is not required.
         // when adding more variables, make sure to update MATERIAL_VARIABLES_COUNT
     };
 

libs/filamat/src/Enums.cpp

@@ -49,7 +49,8 @@ std::unordered_map<std::string, Property> Enums::mStringToProperty = {
         { "microThickness",      Property::MICRO_THICKNESS },
         { "bentNormal",          Property::BENT_NORMAL },
         { "specularFactor",      Property::SPECULAR_FACTOR },
-        { "specularColorFactor",  Property::SPECULAR_COLOR_FACTOR }
+        { "specularColorFactor", Property::SPECULAR_COLOR_FACTOR },
+        { "shadowStrength",       Property::SHADOW_STRENGTH }
 };
 
 template <>

libs/filamat/src/MaterialBuilder.cpp

@@ -252,6 +252,7 @@ MaterialBuilder& MaterialBuilder::variable(Variable v, const char* name) noexcep
         case Variable::CUSTOM1:
         case Variable::CUSTOM2:
         case Variable::CUSTOM3:
+        case Variable::CUSTOM4:
             assert(size_t(v) < MATERIAL_VARIABLES_COUNT);
             mVariables[size_t(v)] = { CString(name), Precision::DEFAULT, false };
             break;
@@ -266,6 +267,7 @@ MaterialBuilder& MaterialBuilder::variable(Variable v,
         case Variable::CUSTOM1:
         case Variable::CUSTOM2:
         case Variable::CUSTOM3:
+        case Variable::CUSTOM4:
             assert(size_t(v) < MATERIAL_VARIABLES_COUNT);
             mVariables[size_t(v)] = { CString(name), precision, true };
             break;
@@ -1254,6 +1256,15 @@ error:
                 OutputTarget::COLOR, Precision::DEFAULT, OutputType::FLOAT4, "color");
     }
 
+    if (mMaterialDomain == MaterialDomain::SURFACE) {
+        if (mRequiredAttributes[VertexAttribute::COLOR] &&
+            !mVariables[int(Variable::CUSTOM4)].name.empty()) {
+            // both the color attribute and the custom4 variable are present, that's not supported
+            slog.e << "Error: when the 'color' attribute is required 'Variable::CUSTOM4' is not supported." << io::endl;
+            goto error;
+        }
+    }
+
     // TODO: maybe check MaterialDomain::COMPUTE has outputs
 
     // Resolve all the #include directives within user code.

libs/filamat/src/shaders/CodeGenerator.cpp

@@ -1218,6 +1218,7 @@ char const* CodeGenerator::getConstantName(MaterialBuilder::Property property) n
         case Property::BENT_NORMAL:                 return "BENT_NORMAL";
         case Property::SPECULAR_FACTOR:             return "SPECULAR_FACTOR";
         case Property::SPECULAR_COLOR_FACTOR:       return "SPECULAR_COLOR_FACTOR";
+        case Property::SHADOW_STRENGTH:             return "SHADOW_STRENGTH";
     }
 }
 

libs/filamat/tests/test_filamat.cpp

@@ -696,6 +696,25 @@ TEST_F(MaterialCompiler, StaticCodeAnalyzerBentNormal) {
     EXPECT_TRUE(PropertyListsMatch(expected, properties));
 }
 
+TEST_F(MaterialCompiler, StaticCodeAnalyzerShadowStrength) {
+    std::string fragmentCode(R"(
+        void material(inout MaterialInputs material) {
+            prepareMaterial(material);
+            material.shadowStrength = 0.1;
+        }
+    )");
+
+    std::string shaderCode = shaderWithAllProperties(*jobSystem, ShaderStage::FRAGMENT,
+            fragmentCode);
+
+    GLSLTools glslTools;
+    MaterialBuilder::PropertyList properties{ false };
+    glslTools.findProperties(ShaderStage::FRAGMENT, shaderCode, properties);
+    MaterialBuilder::PropertyList expected{ false };
+    expected[size_t(filamat::MaterialBuilder::Property::SHADOW_STRENGTH)] = true;
+    EXPECT_TRUE(PropertyListsMatch(expected, properties));
+}
+
 TEST_F(MaterialCompiler, StaticCodeAnalyzerOutputFactor) {
     std::string fragmentCode(R"(
         void material(inout MaterialInputs material) {
@@ -759,6 +778,48 @@ TEST_F(MaterialCompiler, Uv0AndUv1) {
     EXPECT_TRUE(result.isValid());
 }
 
+TEST_F(MaterialCompiler, FiveCustomVariables) {
+    filamat::MaterialBuilder builder;
+    builder.variable(MaterialBuilder::Variable::CUSTOM0, "custom0");
+    builder.variable(MaterialBuilder::Variable::CUSTOM1, "custom1");
+    builder.variable(MaterialBuilder::Variable::CUSTOM2, "custom2");
+    builder.variable(MaterialBuilder::Variable::CUSTOM3, "custom3");
+    builder.variable(MaterialBuilder::Variable::CUSTOM4, "custom4");
+    filamat::Package result = builder.build(*jobSystem);
+    EXPECT_TRUE(result.isValid());
+}
+
+TEST_F(MaterialCompiler, FourCustomVariablesAndColorAttribute) {
+    filamat::MaterialBuilder builder;
+    builder.require(filament::VertexAttribute::COLOR);
+    builder.variable(MaterialBuilder::Variable::CUSTOM0, "custom0");
+    builder.variable(MaterialBuilder::Variable::CUSTOM1, "custom1");
+    builder.variable(MaterialBuilder::Variable::CUSTOM2, "custom2");
+    builder.variable(MaterialBuilder::Variable::CUSTOM3, "custom3");
+    filamat::Package result = builder.build(*jobSystem);
+    EXPECT_TRUE(result.isValid());
+}
+
+TEST_F(MaterialCompiler, FiveCustomVariablesAndColorAttributeFails) {
+    filamat::MaterialBuilder builder;
+    builder.require(filament::VertexAttribute::COLOR);
+    builder.variable(MaterialBuilder::Variable::CUSTOM0, "custom0");
+    builder.variable(MaterialBuilder::Variable::CUSTOM1, "custom1");
+    builder.variable(MaterialBuilder::Variable::CUSTOM2, "custom2");
+    builder.variable(MaterialBuilder::Variable::CUSTOM3, "custom3");
+    builder.variable(MaterialBuilder::Variable::CUSTOM4, "custom4");
+    filamat::Package result = builder.build(*jobSystem);
+    EXPECT_FALSE(result.isValid());
+}
+
+TEST_F(MaterialCompiler, CustomVariable4AndColorAttributeFails) {
+    filamat::MaterialBuilder builder;
+    builder.require(filament::VertexAttribute::COLOR);
+    builder.variable(MaterialBuilder::Variable::CUSTOM4, "custom4");
+    filamat::Package result = builder.build(*jobSystem);
+    EXPECT_FALSE(result.isValid());
+}
+
 TEST_F(MaterialCompiler, Arrays) {
     filamat::MaterialBuilder builder;
 

shaders/src/post_process_inputs.vs

@@ -20,6 +20,9 @@ struct PostProcessVertexInputs {
 #ifdef VARIABLE_CUSTOM3
     vec4 VARIABLE_CUSTOM3;
 #endif
+#ifdef VARIABLE_CUSTOM4
+    vec4 VARIABLE_CUSTOM4;
+#endif
 };
 
 void initPostProcessMaterialVertex(out PostProcessVertexInputs inputs) {
@@ -35,4 +38,7 @@ void initPostProcessMaterialVertex(out PostProcessVertexInputs inputs) {
 #ifdef VARIABLE_CUSTOM3
     inputs.VARIABLE_CUSTOM3 = vec4(0.0);
 #endif
+#ifdef VARIABLE_CUSTOM4
+    inputs.VARIABLE_CUSTOM4 = vec4(0.0);
+#endif
 }

shaders/src/post_process_main.vs

@@ -39,6 +39,9 @@ void main() {
 #if defined(VARIABLE_CUSTOM3)
     VARIABLE_CUSTOM_AT3 = inputs.VARIABLE_CUSTOM3;
 #endif
+#if defined(VARIABLE_CUSTOM4)
+    VARIABLE_CUSTOM_AT4 = inputs.VARIABLE_CUSTOM4;
+#endif
 
     // some PowerVR drivers crash when gl_Position is written more than once
     gl_Position = inputs.position;

shaders/src/surface_light_directional.fs

@@ -58,6 +58,9 @@ void evaluateDirectionalLight(const MaterialInputs material,
         if (hasDirectionalShadows && cascadeHasVisibleShadows) {
             highp vec4 shadowPosition = getShadowPosition(cascade);
             visibility = shadow(true, sampler0_shadowMap, cascade, shadowPosition, 0.0);
+#if defined(MATERIAL_HAS_SHADOW_STRENGTH)
+            applyShadowStrength(visibility, material.shadowStrength);
+#endif
             // shadow far attenuation
             highp vec3 v = getWorldPosition() - getWorldCameraPosition();
             // (viewFromWorld * v).z == dot(transpose(viewFromWorld), v)

shaders/src/surface_light_punctual.fs

@@ -222,6 +222,9 @@ void evaluatePunctualLights(const MaterialInputs material,
                 highp vec4 shadowPosition = getShadowPosition(shadowIndex, light.direction, light.zLight);
                 visibility = shadow(false, sampler0_shadowMap, shadowIndex,
                         shadowPosition, light.zLight);
+#if defined(MATERIAL_HAS_SHADOW_STRENGTH)
+                applyShadowStrength(visibility, material.shadowStrength);
+#endif
             }
             if (light.contactShadows && visibility > 0.0) {
                 if ((object_uniforms_flagsChannels & FILAMENT_OBJECT_CONTACT_SHADOWS_BIT) != 0) {

shaders/src/surface_main.vs

@@ -151,6 +151,9 @@ void main() {
 #if defined(VARIABLE_CUSTOM3)
     VARIABLE_CUSTOM_AT3 = material.VARIABLE_CUSTOM3;
 #endif
+#if defined(VARIABLE_CUSTOM4) && !defined(HAS_ATTRIBUTE_COLOR)
+    VARIABLE_CUSTOM_AT4 = material.VARIABLE_CUSTOM4;
+#endif
 
     // The world position can be changed by the user in materialVertex()
     vertex_worldPosition.xyz = material.worldPosition.xyz;

shaders/src/surface_material_inputs.fs

@@ -98,6 +98,10 @@ struct MaterialInputs {
     vec3 specularColorFactor;
 #endif
 
+#if defined(MATERIAL_HAS_SHADOW_STRENGTH)
+    float shadowStrength;
+#endif
+
 };
 
 void initMaterial(out MaterialInputs material) {
@@ -195,6 +199,9 @@ void initMaterial(out MaterialInputs material) {
     material.specularColorFactor = vec3(1.0);
 #endif
 
+#if defined(MATERIAL_HAS_SHADOW_STRENGTH)
+    material.shadowStrength = 0.0;
+#endif
 }
 
 #if defined(MATERIAL_HAS_CUSTOM_SURFACE_SHADING)

shaders/src/surface_material_inputs.vs

@@ -20,6 +20,9 @@ struct MaterialVertexInputs {
 #ifdef VARIABLE_CUSTOM3
     vec4 VARIABLE_CUSTOM3;
 #endif
+#if defined(VARIABLE_CUSTOM4) && !defined(HAS_ATTRIBUTE_COLOR)
+    vec4 VARIABLE_CUSTOM4;
+#endif
 #ifdef HAS_ATTRIBUTE_TANGENTS
     vec3 worldNormal;
 #endif
@@ -74,6 +77,9 @@ void initMaterialVertex(out MaterialVertexInputs material) {
 #endif
 #ifdef VARIABLE_CUSTOM3
     material.VARIABLE_CUSTOM3 = vec4(0.0);
+#endif
+#if defined(VARIABLE_CUSTOM4) && !defined(HAS_ATTRIBUTE_COLOR)
+    material.VARIABLE_CUSTOM4 = vec4(0.0);
 #endif
     material.worldPosition = computeWorldPosition();
 #ifdef VERTEX_DOMAIN_DEVICE

shaders/src/surface_shading_unlit.fs

@@ -47,6 +47,9 @@ vec4 evaluateMaterial(const MaterialInputs material) {
     if (hasDirectionalShadows && cascadeHasVisibleShadows) {
         highp vec4 shadowPosition = getShadowPosition(cascade);
         visibility = shadow(true, sampler0_shadowMap, cascade, shadowPosition, 0.0);
+#if defined(MATERIAL_HAS_SHADOW_STRENGTH)
+        applyShadowStrength(visibility, material.shadowStrength);
+#endif
         // shadow far attenuation
         highp vec3 v = getWorldPosition() - getWorldCameraPosition();
         // (viewFromWorld * v).z == dot(transpose(viewFromWorld), v)

shaders/src/surface_shadowing.fs

@@ -511,6 +511,12 @@ int getPointLightFace(const highp vec3 r) {
     }
 }
 
+#if defined(MATERIAL_HAS_SHADOW_STRENGTH)
+void applyShadowStrength(inout float visibility, float strength) {
+    visibility = 1.0 - (1.0 - visibility) * strength;
+}
+#endif
+
 // PCF sampling
 float shadow(const bool DIRECTIONAL,
         const mediump sampler2DArrayShadow shadowMap,

shaders/src/surface_varyings.glsl

@@ -2,30 +2,30 @@
 // Varyings
 //------------------------------------------------------------------------------
 
-LAYOUT_LOCATION(4) VARYING highp vec4 vertex_worldPosition;
-
-#if defined(HAS_ATTRIBUTE_TANGENTS)
-LAYOUT_LOCATION(5) SHADING_INTERPOLATION VARYING mediump vec3 vertex_worldNormal;
-#if defined(MATERIAL_NEEDS_TBN)
-LAYOUT_LOCATION(6) SHADING_INTERPOLATION VARYING mediump vec4 vertex_worldTangent;
-#endif
-#endif
-
-LAYOUT_LOCATION(7) VARYING highp vec4 vertex_position;
-
-#if defined(FILAMENT_HAS_FEATURE_INSTANCING)
-LAYOUT_LOCATION(8) flat VARYING highp int instance_index;
-highp int logical_instance_index;
-#endif
-
 #if defined(HAS_ATTRIBUTE_COLOR)
-LAYOUT_LOCATION(9) VARYING mediump vec4 vertex_color;
+LAYOUT_LOCATION(4) VARYING mediump vec4 vertex_color;
 #endif
 
 #if defined(HAS_ATTRIBUTE_UV0) && !defined(HAS_ATTRIBUTE_UV1)
-LAYOUT_LOCATION(10) VARYING highp vec2 vertex_uv01;
+LAYOUT_LOCATION(5) VARYING highp vec2 vertex_uv01;
 #elif defined(HAS_ATTRIBUTE_UV1)
-LAYOUT_LOCATION(10) VARYING highp vec4 vertex_uv01;
+LAYOUT_LOCATION(5) VARYING highp vec4 vertex_uv01;
+#endif
+
+LAYOUT_LOCATION(6) VARYING highp vec4 vertex_worldPosition;
+
+#if defined(HAS_ATTRIBUTE_TANGENTS)
+LAYOUT_LOCATION(7) SHADING_INTERPOLATION VARYING mediump vec3 vertex_worldNormal;
+#if defined(MATERIAL_NEEDS_TBN)
+LAYOUT_LOCATION(8) SHADING_INTERPOLATION VARYING mediump vec4 vertex_worldTangent;
+#endif
+#endif
+
+LAYOUT_LOCATION(9) VARYING highp vec4 vertex_position;
+
+#if defined(FILAMENT_HAS_FEATURE_INSTANCING)
+LAYOUT_LOCATION(10) flat VARYING highp int instance_index;
+highp int logical_instance_index;
 #endif
 
 #if defined(VARIANT_HAS_SHADOWING) && defined(VARIANT_HAS_DIRECTIONAL_LIGHTING)

test/renderdiff/src/run.py

@@ -46,7 +46,12 @@ def render_test(gltf_viewer, test_config, output_dir,
     for backend in test_config.backends:
       env = None
       if backend == 'opengl' and opengl_lib and os.path.isdir(opengl_lib):
-        env = {'LD_LIBRARY_PATH': opengl_lib}
+        env = {
+          'LD_LIBRARY_PATH': opengl_lib,
+
+           # for macOS
+          'DYLD_LIBRARY_PATH': opengl_lib,
+        }
 
       for model in test.models:
         model_path = test_config.models[model]

test/renderdiff/test.sh

@@ -18,11 +18,19 @@ OUTPUT_DIR="$(pwd)/out/renderdiff_tests"
 RENDERDIFF_TEST_DIR="$(pwd)/test/renderdiff"
 TEST_UTILS_DIR="$(pwd)/test/utils"
 MESA_DIR="$(pwd)/mesa/out/"
-MESA_LIB_DIR="${MESA_DIR}/lib/x86_64-linux-gnu"
+
+os_name=$(uname -s)
+if [[ "$os_name" == "Linux" ]]; then
+    MESA_LIB_DIR="${MESA_DIR}lib/x86_64-linux-gnu"
+elif [[ "$os_name" == "Darwin" ]]; then
+    MESA_LIB_DIR="${MESA_DIR}lib"
+else
+    echo "Unsupported platform for renderdiff tests"
+    exit 1
+fi
 
 function prepare_mesa() {
     if [ ! -d ${MESA_LIB_DIR} ]; then
-        rm -rf mesa
         bash ${TEST_UTILS_DIR}/get_mesa.sh
     fi
 }