upgrade Filament to v1.41

ios/include/AssetManager.hpp

@@ -77,6 +77,8 @@ namespace polyvox {
             MaterialProvider* _ubershaderProvider = nullptr;
             gltfio::ResourceLoader* _gltfResourceLoader = nullptr;
             gltfio::TextureProvider* _stbDecoder = nullptr;
+            gltfio::TextureProvider* _ktxDecoder = nullptr;
+        
             vector<SceneAsset> _assets;
             tsl::robin_map<EntityId, int> _entityIdLookup;
  

ios/include/backend/DriverEnums.h

@@ -106,7 +106,8 @@ static constexpr size_t CONFIG_SAMPLER_BINDING_COUNT = 4;   // This is guarantee
  * Defines the backend's feature levels.
  */
 enum class FeatureLevel : uint8_t {
-    FEATURE_LEVEL_1 = 1,  //!< OpenGL ES 3.0 features (default)
+    FEATURE_LEVEL_0 = 0,  //!< OpenGL ES 2.0 features
+    FEATURE_LEVEL_1,      //!< OpenGL ES 3.0 features (default)
     FEATURE_LEVEL_2,      //!< OpenGL ES 3.1 features + 16 textures units + cubemap arrays
     FEATURE_LEVEL_3       //!< OpenGL ES 3.1 features + 31 textures units + cubemap arrays
 };
@@ -279,6 +280,15 @@ enum class UniformType : uint8_t {
     STRUCT
 };
 
+/**
+ * Supported constant parameter types
+ */
+ enum class ConstantType : uint8_t {
+  INT,
+  FLOAT,
+  BOOL
+};
+
 enum class Precision : uint8_t {
     LOW,
     MEDIUM,
@@ -286,6 +296,14 @@ enum class Precision : uint8_t {
     DEFAULT
 };
 
+/**
+ * Shader compiler priority queue
+ */
+enum class CompilerPriorityQueue : uint8_t {
+    HIGH,
+    LOW
+};
+
 //! Texture sampler type
 enum class SamplerType : uint8_t {
     SAMPLER_2D,             //!< 2D texture
@@ -1117,7 +1135,12 @@ enum class Workaround : uint16_t {
     // the whole render pass.
     ALLOW_READ_ONLY_ANCILLARY_FEEDBACK_LOOP,
     // for some uniform arrays, it's needed to do an initialization to avoid crash on adreno gpu
-    ADRENO_UNIFORM_ARRAY_CRASH
+    ADRENO_UNIFORM_ARRAY_CRASH,
+    // Workaround a Metal pipeline compilation error with the message:
+    // "Could not statically determine the target of a texture". See light_indirect.fs
+    A8X_STATIC_TEXTURE_TARGET_ERROR,
+    // Adreno drivers sometimes aren't able to blit into a layer of a texture array.
+    DISABLE_BLIT_INTO_TEXTURE_ARRAY,
 };
 
 } // namespace filament::backend

ios/include/backend/Handle.h

@@ -39,7 +39,6 @@ struct HwRenderTarget;
 struct HwSamplerGroup;
 struct HwStream;
 struct HwSwapChain;
-struct HwSync;
 struct HwTexture;
 struct HwTimerQuery;
 struct HwVertexBuffer;
@@ -126,7 +125,6 @@ using RenderTargetHandle    = Handle<HwRenderTarget>;
 using SamplerGroupHandle    = Handle<HwSamplerGroup>;
 using StreamHandle          = Handle<HwStream>;
 using SwapChainHandle       = Handle<HwSwapChain>;
-using SyncHandle            = Handle<HwSync>;
 using TextureHandle         = Handle<HwTexture>;
 using TimerQueryHandle      = Handle<HwTimerQuery>;
 using VertexBufferHandle    = Handle<HwVertexBuffer>;

ios/include/backend/PixelBufferDescriptor.h

@@ -279,8 +279,8 @@ public:
                 break;
         }
 
-        size_t bpr = bpp * stride;
-        size_t bprAligned = (bpr + (alignment - 1)) & (~alignment + 1);
+        size_t const bpr = bpp * stride;
+        size_t const bprAligned = (bpr + (alignment - 1)) & (~alignment + 1);
         return bprAligned * height;
     }
 

ios/include/backend/Platform.h

@@ -22,6 +22,7 @@
 #include <backend/DriverEnums.h>
 
 #include <utils/compiler.h>
+#include <utils/Invocable.h>
 
 namespace filament::backend {
 
@@ -47,6 +48,8 @@ public:
         size_t handleArenaSize = 0;
     };
 
+    Platform() noexcept;
+
     virtual ~Platform() noexcept;
 
     /**
@@ -79,6 +82,85 @@ public:
      * thread, or if the platform does not need to perform any special processing.
      */
     virtual bool pumpEvents() noexcept;
+
+    /**
+     * InsertBlobFunc is an Invocable to an application-provided function that a
+     * backend implementation may use to insert a key/value pair into the
+     * cache.
+     */
+    using InsertBlobFunc = utils::Invocable<
+            void(const void* key, size_t keySize, const void* value, size_t valueSize)>;
+
+    /*
+     * RetrieveBlobFunc is an Invocable to an application-provided function that a
+     * backend implementation may use to retrieve a cached value from the
+     * cache.
+     */
+    using RetrieveBlobFunc = utils::Invocable<
+            size_t(const void* key, size_t keySize, void* value, size_t valueSize)>;
+
+    /**
+     * Sets the callback functions that the backend can use to interact with caching functionality
+     * provided by the application.
+     *
+     * Cache functions may only be specified once during the lifetime of a
+     * Platform.  The <insert> and <retrieve> Invocables may be called at any time and
+     * from any thread from the time at which setBlobFunc is called until the time that Platform
+     * is destroyed. Concurrent calls to these functions from different threads is also allowed.
+     *
+     * @param insertBlob    an Invocable that inserts a new value into the cache and associates
+     *                      it with the given key
+     * @param retrieveBlob  an Invocable that retrieves from the cache the value associated with a
+     *                      given key
+     */
+    void setBlobFunc(InsertBlobFunc&& insertBlob, RetrieveBlobFunc&& retrieveBlob) noexcept;
+
+    /**
+     * @return true if setBlobFunc was called.
+     */
+    bool hasBlobFunc() const noexcept;
+
+    /**
+     * To insert a new binary value into the cache and associate it with a given
+     * key, the backend implementation can call the application-provided callback
+     * function insertBlob.
+     *
+     * No guarantees are made as to whether a given key/value pair is present in
+     * the cache after the set call.  If a different value has been associated
+     * with the given key in the past then it is undefined which value, if any, is
+     * associated with the key after the set call.  Note that while there are no
+     * guarantees, the cache implementation should attempt to cache the most
+     * recently set value for a given key.
+     *
+     * @param key           pointer to the beginning of the key data that is to be inserted
+     * @param keySize       specifies the size in byte of the data pointed to by <key>
+     * @param value         pointer to the beginning of the value data that is to be inserted
+     * @param valueSize     specifies the size in byte of the data pointed to by <value>
+     */
+    void insertBlob(const void* key, size_t keySize, const void* value, size_t valueSize);
+
+    /**
+     * To retrieve the binary value associated with a given key from the cache, a
+     * the backend implementation can call the application-provided callback
+     * function retrieveBlob.
+     *
+     * If the cache contains a value for the given key and its size in bytes is
+     * less than or equal to <valueSize> then the value is written to the memory
+     * pointed to by <value>.  Otherwise nothing is written to the memory pointed
+     * to by <value>.
+     *
+     * @param key          pointer to the beginning of the key
+     * @param keySize      specifies the size in bytes of the binary key pointed to by <key>
+     * @param value        pointer to a buffer to receive the cached binary data, if it exists
+     * @param valueSize    specifies the size in bytes of the memory pointed to by <value>
+     * @return             If the cache contains a value associated with the given key then the
+     *                     size of that binary value in bytes is returned. Otherwise 0 is returned.
+     */
+    size_t retrieveBlob(const void* key, size_t keySize, void* value, size_t valueSize);
+
+private:
+    InsertBlobFunc mInsertBlob;
+    RetrieveBlobFunc mRetrieveBlob;
 };
 
 } // namespace filament

ios/include/backend/Program.h

@@ -48,7 +48,15 @@ public:
         ShaderStageFlags stageFlags = ShaderStageFlags::ALL_SHADER_STAGE_FLAGS;
     };
 
+    struct Uniform {
+        utils::CString name;    // full qualified name of the uniform field
+        uint16_t offset;        // offset in 'uint32_t' into the uniform buffer
+        uint8_t size;           // >1 for arrays
+        UniformType type;       // uniform type
+    };
+
     using UniformBlockInfo = std::array<utils::CString, UNIFORM_BINDING_COUNT>;
+    using UniformInfo = utils::FixedCapacityVector<Uniform>;
     using SamplerGroupInfo = std::array<SamplerGroupData, SAMPLER_BINDING_COUNT>;
     using ShaderBlob = utils::FixedCapacityVector<uint8_t>;
     using ShaderSource = std::array<ShaderBlob, SHADER_TYPE_COUNT>;
@@ -63,6 +71,8 @@ public:
 
     ~Program() noexcept;
 
+    Program& priorityQueue(CompilerPriorityQueue priorityQueue) noexcept;
+
     // sets the material name and variant for diagnostic purposes only
     Program& diagnostics(utils::CString const& name,
             utils::Invocable<utils::io::ostream&(utils::io::ostream& out)>&& logger);
@@ -78,6 +88,14 @@ public:
     Program& uniformBlockBindings(
             utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> const& uniformBlockBindings) noexcept;
 
+    // Note: This is only needed for GLES2.0, this is used to emulate UBO. This function tells
+    // the program everything it needs to know about the uniforms at a given binding
+    Program& uniforms(uint32_t index, UniformInfo const& uniforms) noexcept;
+
+    // Note: This is only needed for GLES2.0.
+    Program& attributes(
+            utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> attributes) noexcept;
+
     // sets the 'bindingPoint' sampler group descriptor for this program.
     // 'samplers' can be destroyed after this call.
     // This effectively associates a set of (BindingPoints, index) to a texture unit in the shader.
@@ -93,6 +111,7 @@ public:
     Program& specializationConstants(
             utils::FixedCapacityVector<SpecializationConstant> specConstants) noexcept;
 
+    Program& cacheId(uint64_t cacheId) noexcept;
 
     ShaderSource const& getShadersSource() const noexcept { return mShadersSource; }
     ShaderSource& getShadersSource() noexcept { return mShadersSource; }
@@ -103,6 +122,12 @@ public:
     SamplerGroupInfo const& getSamplerGroupInfo() const { return mSamplerGroups; }
     SamplerGroupInfo& getSamplerGroupInfo() { return mSamplerGroups; }
 
+    auto const& getBindingUniformInfo() const { return mBindingUniformInfo; }
+    auto& getBindingUniformInfo() { return mBindingUniformInfo; }
+
+    auto const& getAttributes() const { return mAttributes; }
+    auto& getAttributes() { return mAttributes; }
+
     utils::CString const& getName() const noexcept { return mName; }
     utils::CString& getName() noexcept { return mName; }
 
@@ -113,6 +138,10 @@ public:
         return mSpecializationConstants;
     }
 
+    uint64_t getCacheId() const noexcept { return mCacheId; }
+
+    CompilerPriorityQueue getPriorityQueue() const noexcept { return mPriorityQueue; }
+
 private:
     friend utils::io::ostream& operator<<(utils::io::ostream& out, const Program& builder);
 
@@ -120,8 +149,12 @@ private:
     SamplerGroupInfo mSamplerGroups = {};
     ShaderSource mShadersSource;
     utils::CString mName;
+    uint64_t mCacheId{};
     utils::Invocable<utils::io::ostream&(utils::io::ostream& out)> mLogger;
     utils::FixedCapacityVector<SpecializationConstant> mSpecializationConstants;
+    utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> mAttributes;
+    std::array<UniformInfo, Program::UNIFORM_BINDING_COUNT> mBindingUniformInfo;
+    CompilerPriorityQueue mPriorityQueue = CompilerPriorityQueue::HIGH;
 };
 
 } // namespace filament::backend

ios/include/backend/platforms/OpenGLPlatform.h

@@ -95,6 +95,19 @@ public:
      */
     virtual void destroySwapChain(SwapChain* swapChain) noexcept = 0;
 
+    /**
+     * Returns the set of buffers that must be preserved up to the call to commit().
+     * The default value is TargetBufferFlags::NONE.
+     * The color buffer is always preserved, however ancillary buffers, such as the depth buffer
+     * are generally discarded. The preserve flags can be used to make sure those ancillary
+     * buffers are preserved until the call to commit.
+     *
+     * @param swapChain
+     * @return buffer that must be preserved
+     * @see commit()
+     */
+    virtual TargetBufferFlags getPreservedFlags(SwapChain* swapChain) noexcept;
+
     /**
      * Called by the driver to establish the default FBO. The default implementation returns 0.
       * @return a GLuint casted to a uint32_t that is an OpenGL framebuffer object.
@@ -254,6 +267,27 @@ public:
      * @return Transformed image.
      */
     virtual AcquiredImage transformAcquiredImage(AcquiredImage source) noexcept;
+
+    // --------------------------------------------------------------------------------------------
+
+    /**
+     * Returns true if additional OpenGL contexts can be created. Default: false.
+     * @return true if additional OpenGL contexts can be created.
+     * @see createContext
+     */
+    virtual bool isExtraContextSupported() const noexcept;
+
+    /**
+     * Creates an OpenGL context with the same configuration than the main context and makes it
+     * current to the current thread. Must not be called from the main driver thread.
+     * createContext() is only supported if isExtraContextSupported() returns true.
+     * These additional contexts will be automatically terminated in terminate.
+     *
+     * @param shared whether the new context is shared with the main context.
+     * @see isExtraContextSupported()
+     * @see terminate()
+     */
+    virtual void createContext(bool shared);
 };
 
 } // namespace filament

ios/include/backend/platforms/PlatformCocoaGL.h

@@ -50,6 +50,9 @@ protected:
     // --------------------------------------------------------------------------------------------
     // OpenGLPlatform Interface
 
+    bool isExtraContextSupported() const noexcept override;
+    void createContext(bool shared) override;
+
     void terminate() noexcept override;
 
     SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
@@ -57,6 +60,10 @@ protected:
     void destroySwapChain(SwapChain* swapChain) noexcept override;
     void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
     void commit(SwapChain* swapChain) noexcept override;
+    OpenGLPlatform::ExternalTexture* createExternalImageTexture() noexcept override;
+    void destroyExternalImage(ExternalTexture* texture) noexcept override;
+    void retainExternalImage(void* externalImage) noexcept override;
+    bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept override;
 
 private:
     PlatformCocoaGLImpl* pImpl = nullptr;

ios/include/backend/platforms/PlatformCocoaTouchGL.h

@@ -47,6 +47,9 @@ public:
 
     uint32_t createDefaultRenderTarget() noexcept override;
 
+    bool isExtraContextSupported() const noexcept override;
+    void createContext(bool shared) override;
+
     SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
     SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
     void destroySwapChain(SwapChain* swapChain) noexcept override;

ios/include/backend/platforms/PlatformEGL.h

@@ -26,6 +26,9 @@
 
 #include <backend/DriverEnums.h>
 
+#include <utility>
+#include <vector>
+
 namespace filament::backend {
 
 /**
@@ -35,8 +38,31 @@ class PlatformEGL : public OpenGLPlatform {
 public:
 
     PlatformEGL() noexcept;
+    bool isExtraContextSupported() const noexcept override;
+    void createContext(bool shared) override;
 
 protected:
+
+    // --------------------------------------------------------------------------------------------
+    // Helper for EGL configs and attributes parameters
+
+    class Config {
+    public:
+        Config();
+        Config(std::initializer_list<std::pair<EGLint, EGLint>> list);
+        EGLint& operator[](EGLint name);
+        EGLint operator[](EGLint name) const;
+        void erase(EGLint name) noexcept;
+        EGLint const* data() const noexcept {
+            return reinterpret_cast<EGLint const*>(mConfig.data());
+        }
+        size_t size() const noexcept {
+            return mConfig.size();
+        }
+    private:
+        std::vector<std::pair<EGLint, EGLint>> mConfig = {{ EGL_NONE, EGL_NONE }};
+    };
+
     // --------------------------------------------------------------------------------------------
     // Platform Interface
 
@@ -79,6 +105,8 @@ protected:
      * @param name a string giving some context on the error. Typically __func__.
      */
     static void logEglError(const char* name) noexcept;
+    static void logEglError(const char* name, EGLint error) noexcept;
+    static const char* getEglErrorName(EGLint error) noexcept;
 
     /**
      * Calls glGetError() to clear the current error flags. logs a warning to log.w if
@@ -98,6 +126,8 @@ protected:
     EGLSurface mCurrentReadSurface = EGL_NO_SURFACE;
     EGLSurface mEGLDummySurface = EGL_NO_SURFACE;
     EGLConfig mEGLConfig = EGL_NO_CONFIG_KHR;
+    Config mContextAttribs;
+    std::vector<EGLContext> mAdditionalContexts;
 
     // supported extensions detected at runtime
     struct {
@@ -105,13 +135,16 @@ protected:
             bool OES_EGL_image_external_essl3 = false;
         } gl;
         struct {
-            bool KHR_no_config_context = false;
+            bool ANDROID_recordable = false;
+            bool KHR_create_context = false;
             bool KHR_gl_colorspace = false;
+            bool KHR_no_config_context = false;
         } egl;
     } ext;
 
-private:
     void initializeGlExtensions() noexcept;
+
+private:
     EGLConfig findSwapChainConfig(uint64_t flags) const;
 };
 

ios/include/backend/platforms/PlatformWGL.h

@@ -23,9 +23,10 @@
 #include "utils/unwindows.h"
 
 #include <backend/platforms/OpenGLPlatform.h>
-
 #include <backend/DriverEnums.h>
 
+#include <vector>
+
 namespace filament::backend {
 
 /**
@@ -46,6 +47,9 @@ protected:
 
     void terminate() noexcept override;
 
+    bool isExtraContextSupported() const noexcept override;
+    void createContext(bool shared) override;
+
     SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
     SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
     void destroySwapChain(SwapChain* swapChain) noexcept override;
@@ -57,6 +61,8 @@ protected:
     HWND mHWnd = NULL;
     HDC mWhdc = NULL;
     PIXELFORMATDESCRIPTOR mPfd = {};
+    std::vector<HGLRC> mAdditionalContexts;
+    std::vector<int> mAttribs;
 };
 
 } // namespace filament::backend

ios/include/backend/platforms/VulkanPlatform.h

@@ -19,31 +19,220 @@
 
 #include <backend/Platform.h>
 
+#include <bluevk/BlueVK.h>
+#include <utils/FixedCapacityVector.h>
+#include <utils/PrivateImplementation.h>
+
+#include <tuple>
+#include <unordered_set>
+
 namespace filament::backend {
 
+using SwapChain = Platform::SwapChain;
+
+/**
+ * Private implementation details for the provided vulkan platform.
+ */
+struct VulkanPlatformPrivate;
+
 /**
  * A Platform interface that creates a Vulkan backend.
  */
-
-class VulkanPlatform : public Platform {
+class VulkanPlatform : public Platform, utils::PrivateImplementation<VulkanPlatformPrivate> {
 public:
-    struct SurfaceBundle {
-        void* surface;
-        // On certain platforms, the extent of the surface cannot be queried from Vulkan. In those
-        // situations, we allow the frontend to pass in the extent to use in creating the swap
-        // chains. Platform implementation should set extent to 0 if they do not expect to set the
-        // swap chain extent.
-        uint32_t width;
-        uint32_t height;
+
+    /**
+     * A collection of handles to objects and metadata that comprises a Vulkan context. The client
+     * can instantiate this struct and pass to Engine::Builder::sharedContext if they wishes to
+     * share their vulkan context. This is specifically necessary if the client wishes to override
+     * the swapchain API.
+     */
+    struct VulkanSharedContext {
+        VkInstance instance = VK_NULL_HANDLE;
+        VkPhysicalDevice physicalDevice = VK_NULL_HANDLE;
+        VkDevice logicalDevice = VK_NULL_HANDLE;
+        uint32_t graphicsQueueFamilyIndex = 0xFFFFFFFF;
+        // In the usual case, the client needs to allocate at least one more graphics queue
+        // for Filament, and this index is the param to pass into vkGetDeviceQueue. In the case
+        // where the gpu only has one graphics queue. Then the client needs to ensure that no
+        // concurrent access can occur.
+        uint32_t graphicsQueueIndex = 0xFFFFFFFF;
     };
 
-    // Given a Vulkan instance and native window handle, creates the platform-specific surface.
-    virtual SurfaceBundle createVkSurfaceKHR(void* nativeWindow, void* instance,
-        uint64_t flags) noexcept = 0;
+    /**
+     * Shorthand for the pointer to the Platform SwapChain struct, we use it also as a handle (i.e.
+     * identifier for the swapchain).
+     */
+    using SwapChainPtr = Platform::SwapChain*;
 
-   ~VulkanPlatform() override;
+    /**
+     * Collection of images, formats, and extent (width/height) that defines the swapchain.
+     */
+    struct SwapChainBundle {
+        utils::FixedCapacityVector<VkImage> colors;
+        VkImage depth = VK_NULL_HANDLE;
+        VkFormat colorFormat = VK_FORMAT_UNDEFINED;
+        VkFormat depthFormat = VK_FORMAT_UNDEFINED;
+        VkExtent2D extent = {0, 0};
+    };
+
+    VulkanPlatform();
+
+    ~VulkanPlatform() override;
+
+    Driver* createDriver(void* sharedContext,
+            Platform::DriverConfig const& driverConfig) noexcept override;
+
+    int getOSVersion() const noexcept override {
+        return 0;
+    }
+
+    // ----------------------------------------------------
+    // ---------- Platform Customization options ----------
+    /**
+     * The client preference can be stored within the struct.  We allow for two specification of
+     * preference:
+     *     1) A substring to match against `VkPhysicalDeviceProperties.deviceName`.
+     *     2) Index of the device in the list as returned by vkEnumeratePhysicalDevices.
+     */
+    struct GPUPreference {
+        std::string deviceName;
+        int8_t index = -1;
+    };
+
+    /**
+     * Client can provide a preference over the GPU to use in the vulkan instance
+     * @return            `GPUPreference` struct that indicates the client's preference
+     */
+    virtual GPUPreference getPreferredGPU() noexcept {
+        return {};
+    }
+    // -------- End platform customization options --------
+    // ----------------------------------------------------
+
+    /**
+     * Returns whether the platform supports sRGB swapchain. This is true by default, and the client
+     * needs to override this method to specify otherwise.
+     * @return            Whether the platform supports sRGB swapchain.
+     */
+    virtual bool isSRGBSwapChainSupported() const {
+        return true;
+    }
+
+    /**
+     * Get the images handles and format of the memory backing the swapchain. This should be called
+     * after createSwapChain() or after recreateIfResized().
+     * @param swapchain   The handle returned by createSwapChain()
+     * @return            An array of VkImages
+     */
+    virtual SwapChainBundle getSwapChainBundle(SwapChainPtr handle);
+
+    /**
+     * Acquire the next image for rendering. The `index` will be written with an non-negative
+     * integer that the backend can use to index into the `SwapChainBundle.colors` array. The
+     * corresponding VkImage will be used as the output color attachment. The client should signal
+     * the `clientSignal` semaphore when the image is ready to be used by the backend.
+     * @param handle         The handle returned by createSwapChain()
+     * @param clientSignal   The semaphore that the client will signal to indicate that the backend
+     *                       may render into the image.
+     * @param index          Pointer to memory that will be filled with the index that corresponding
+     *                       to an image in the `SwapChainBundle.colors` array.
+     * @return               Result of acquire
+     */
+    virtual VkResult acquire(SwapChainPtr handle, VkSemaphore clientSignal, uint32_t* index);
+
+    /**
+     * Present the image corresponding to `index` to the display. The client should wait on
+     * `finishedDrawing` before presenting.
+     * @param handle             The handle returned by createSwapChain()
+     * @param index              Index that corresponding to an image in the
+     *                           `SwapChainBundle.colors` array.
+     * @param finishedDrawing    Backend passes in a semaphore that the client will signal to
+     *                           indicate that the client may render into the image.
+     * @return                   Result of present
+     */
+    virtual VkResult present(SwapChainPtr handle, uint32_t index, VkSemaphore finishedDrawing);
+
+    /**
+     * Check if the surface size has changed.
+     * @param handle             The handle returned by createSwapChain()
+     * @return                   Whether the swapchain has been resized
+     */
+    virtual bool hasResized(SwapChainPtr handle);
+
+    /**
+     * Carry out a recreation of the swapchain.
+     * @param handle             The handle returned by createSwapChain()
+     * @return                   Result of the recreation
+     */
+    virtual VkResult recreate(SwapChainPtr handle);
+
+    /**
+     * Create a swapchain given a platform window, or if given a null `nativeWindow`, then we
+     * try to create a headless swapchain with the given `extent`.
+     * @param flags     Optional parameters passed to the client as defined in
+     *                  Filament::SwapChain.h.
+     * @param extent    Optional width and height that indicates the size of the headless swapchain.
+     * @return          Result of the operation
+     */
+    virtual SwapChainPtr createSwapChain(void* nativeWindow, uint64_t flags = 0,
+            VkExtent2D extent = {0, 0});
+
+    /**
+     * Destroy the swapchain.
+     * @param handle    The handle returned by createSwapChain()
+     */
+    virtual void destroy(SwapChainPtr handle);
+
+    /**
+     * Clean up any resources owned by the Platform. For example, if the Vulkan instance handle was
+     * generated by the platform, we need to clean it up in this method.
+     */
+    virtual void terminate();
+
+    /**
+     * @return The instance (VkInstance) for the Vulkan backend.
+     */
+    VkInstance getInstance() const noexcept;
+
+    /**
+     * @return The logical device (VkDevice) that was selected as the backend device.
+     */
+    VkDevice getDevice() const noexcept;
+
+    /**
+     * @return The physical device (i.e gpu) that was selected as the backend physical device.
+     */
+    VkPhysicalDevice getPhysicalDevice() const noexcept;
+
+    /**
+     * @return The family index of the graphics queue selected for the Vulkan backend.
+     */
+    uint32_t getGraphicsQueueFamilyIndex() const noexcept;
+
+    /**
+     * @return The index of the graphics queue (if there are multiple graphics queues)
+     *         selected for the Vulkan backend.
+     */
+    uint32_t getGraphicsQueueIndex() const noexcept;
+
+    /**
+     * @return The queue that was selected for the Vulkan backend.
+     */
+    VkQueue getGraphicsQueue() const noexcept;
+
+private:
+    // Platform dependent helper methods
+    using ExtensionSet = std::unordered_set<std::string_view>;
+    static ExtensionSet getRequiredInstanceExtensions();
+
+    using SurfaceBundle = std::tuple<VkSurfaceKHR, VkExtent2D>;
+    static SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
+            uint64_t flags) noexcept;
+
+    friend struct VulkanPlatformPrivate;
 };
 
-} // namespace filament::backend
+}// namespace filament::backend
 
-#endif //TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORM_H
+#endif// TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORM_H

ios/include/filamat/Enums.h

@@ -34,6 +34,7 @@ using ParameterPrecision = MaterialBuilder::ParameterPrecision;
 using OutputTarget = MaterialBuilder::OutputTarget;
 using OutputQualifier = MaterialBuilder::VariableQualifier;
 using OutputType = MaterialBuilder::OutputType;
+using ConstantType = MaterialBuilder::ConstantType;
 
 // Convenience methods to convert std::string to Enum and also iterate over Enum values.
 class Enums {
@@ -77,6 +78,7 @@ private:
     static std::unordered_map<std::string, OutputTarget> mStringToOutputTarget;
     static std::unordered_map<std::string, OutputQualifier> mStringToOutputQualifier;
     static std::unordered_map<std::string, OutputType> mStringToOutputType;
+    static std::unordered_map<std::string, ConstantType> mStringToConstantType;
 };
 
 template<typename T>

ios/include/filamat/MaterialBuilder.h

@@ -39,6 +39,7 @@
 #include <string>
 #include <utility>
 #include <vector>
+#include <variant>
 
 #include <stddef.h>
 #include <stdint.h>
@@ -141,13 +142,6 @@ protected:
         TargetLanguage targetLanguage;
     };
     std::vector<CodeGenParams> mCodeGenPermutations;
-    // For finding properties and running semantic analysis, we always use the same code gen
-    // permutation. This is the first permutation generated with default arguments passed to matc.
-    static constexpr const CodeGenParams mSemanticCodeGenParams = {
-            .shaderModel = ShaderModel::MOBILE,
-            .targetApi = TargetApi::OPENGL,
-            .targetLanguage = TargetLanguage::SPIRV
-    };
 
     // Keeps track of how many times MaterialBuilder::init() has been called without a call to
     // MaterialBuilder::shutdown(). Internally, glslang does something similar. We keep track for
@@ -237,11 +231,14 @@ public:
     using TransparencyMode = filament::TransparencyMode;
     using SpecularAmbientOcclusion = filament::SpecularAmbientOcclusion;
 
+    using AttributeType = filament::backend::UniformType;
     using UniformType = filament::backend::UniformType;
+    using ConstantType = filament::backend::ConstantType;
     using SamplerType = filament::backend::SamplerType;
     using SubpassType = filament::backend::SubpassType;
     using SamplerFormat = filament::backend::SamplerFormat;
     using ParameterPrecision = filament::backend::Precision;
+    using Precision = filament::backend::Precision;
     using CullingMode = filament::backend::CullingMode;
     using FeatureLevel = filament::backend::FeatureLevel;
 
@@ -270,6 +267,9 @@ public:
     };
     using PreprocessorDefineList = std::vector<PreprocessorDefine>;
 
+
+    MaterialBuilder& noSamplerValidation(bool enabled) noexcept;
+
     //! Set the name of this material.
     MaterialBuilder& name(const char* name) noexcept;
 
@@ -290,6 +290,15 @@ public:
     MaterialBuilder& parameter(const char* name, size_t size, UniformType type,
             ParameterPrecision precision = ParameterPrecision::DEFAULT) noexcept;
 
+    //! Add a constant parameter to this material.
+    template<typename T>
+    using is_supported_constant_parameter_t = typename std::enable_if<
+            std::is_same<int32_t, T>::value ||
+            std::is_same<float, T>::value ||
+            std::is_same<bool, T>::value>::type;
+    template<typename T, typename = is_supported_constant_parameter_t<T>>
+    MaterialBuilder& constant(const char *name, ConstantType type, T defaultValue = 0);
+
     /**
      * Add a sampler parameter to this material.
      *
@@ -390,7 +399,10 @@ public:
 
     MaterialBuilder& featureLevel(FeatureLevel featureLevel) noexcept;
 
-    //! Set the blending mode for this material.
+    /**
+     * Set the blending mode for this material. When set to MASKED, alpha to coverage is turned on.
+     * You can override this behavior using alphaToCoverage(false).
+     */
     MaterialBuilder& blending(BlendingMode blending) noexcept;
 
     /**
@@ -436,6 +448,14 @@ public:
      */
     MaterialBuilder& maskThreshold(float threshold) noexcept;
 
+    /**
+     * Enables or disables alpha-to-coverage. When enabled, the coverage of a fragment is based
+     * on its alpha value. This parameter is only useful when MSAA is in use. Alpha to coverage
+     * is enabled automatically when the blend mode is set to MASKED; this behavior can be
+     * overridden by calling alphaToCoverage(false).
+     */
+    MaterialBuilder& alphaToCoverage(bool enable) noexcept;
+
     //! The material output is multiplied by the shadowing factor (UNLIT model only).
     MaterialBuilder& shadowMultiplier(bool shadowMultiplier) noexcept;
 
@@ -556,7 +576,7 @@ public:
     MaterialBuilder& shaderDefine(const char* name, const char* value) noexcept;
 
     //! Add a new fragment shader output variable. Only valid for materials in the POST_PROCESS domain.
-    MaterialBuilder& output(VariableQualifier qualifier, OutputTarget target,
+    MaterialBuilder& output(VariableQualifier qualifier, OutputTarget target, Precision precision,
             OutputType type, const char* name, int location = -1) noexcept;
 
     MaterialBuilder& enableFramebufferFetch() noexcept;
@@ -630,17 +650,28 @@ public:
     struct Output {
         Output() noexcept = default;
         Output(const char* outputName, VariableQualifier qualifier, OutputTarget target,
-                OutputType type, int location) noexcept
-                : name(outputName), qualifier(qualifier), target(target), type(type),
-                  location(location) { }
+                Precision precision, OutputType type, int location) noexcept
+                : name(outputName), qualifier(qualifier), target(target), precision(precision),
+                  type(type), location(location) { }
 
         utils::CString name;
         VariableQualifier qualifier;
         OutputTarget target;
+        Precision precision;
         OutputType type;
         int location;
     };
 
+    struct Constant {
+        utils::CString name;
+        ConstantType type;
+        union {
+            int32_t i;
+            float f;
+            bool b;
+        } defaultValue;
+    };
+
     static constexpr size_t MATERIAL_PROPERTIES_COUNT = filament::MATERIAL_PROPERTIES_COUNT;
     using Property = filament::Property;
 
@@ -668,6 +699,7 @@ public:
     using ParameterList = Parameter[MAX_PARAMETERS_COUNT];
     using SubpassList = Parameter[MAX_SUBPASS_COUNT];
     using BufferList = std::vector<std::unique_ptr<filament::BufferInterfaceBlock>>;
+    using ConstantList = std::vector<Constant>;
 
     // returns the number of parameters declared in this material
     uint8_t getParameterCount() const noexcept { return mParameterCount; }
@@ -683,22 +715,47 @@ public:
 
     filament::UserVariantFilterMask getVariantFilter() const { return mVariantFilter; }
 
+    FeatureLevel getFeatureLevel() const noexcept { return mFeatureLevel; }
     /// @endcond
 
+    struct Attribute {
+        std::string_view name;
+        AttributeType type;
+        MaterialBuilder::VertexAttribute location;
+        std::string getAttributeName() const noexcept {
+            return "mesh_" + std::string{ name };
+        }
+        std::string getDefineName() const noexcept {
+            std::string uppercase{ name };
+            transform(uppercase.cbegin(), uppercase.cend(), uppercase.begin(), ::toupper);
+            return "HAS_ATTRIBUTE_" + uppercase;
+        }
+    };
+
+    using AttributeDatabase = std::array<Attribute, filament::backend::MAX_VERTEX_ATTRIBUTE_COUNT>;
+
+    static inline AttributeDatabase const& getAttributeDatabase() noexcept {
+        return sAttributeDatabase;
+    }
+
 private:
+    static const AttributeDatabase sAttributeDatabase;
+
     void prepareToBuild(MaterialInfo& info) noexcept;
 
     // Return true if the shader is syntactically and semantically valid.
     // This method finds all the properties defined in the fragment and
     // vertex shaders of the material.
-    bool findAllProperties() noexcept;
+    bool findAllProperties(CodeGenParams const& semanticCodeGenParams) noexcept;
 
     // Multiple calls to findProperties accumulate the property sets across fragment
     // and vertex shaders in mProperties.
     bool findProperties(filament::backend::ShaderStage type,
-            MaterialBuilder::PropertyList& p) noexcept;
+            MaterialBuilder::PropertyList& allProperties,
+            CodeGenParams const& semanticCodeGenParams) noexcept;
 
-    bool runSemanticAnalysis(MaterialInfo const& info) noexcept;
+    bool runSemanticAnalysis(MaterialInfo const& info,
+            CodeGenParams const& semanticCodeGenParams) noexcept;
 
     bool checkLiteRequirements() noexcept;
 
@@ -751,6 +808,7 @@ private:
 
     PropertyList mProperties;
     ParameterList mParameters;
+    ConstantList mConstants;
     SubpassList mSubpasses;
     VariableList mVariables;
     OutputList mOutputs;
@@ -791,6 +849,8 @@ private:
     bool mInstanced = false;
     bool mDepthWrite = true;
     bool mDepthWriteSet = false;
+    bool mAlphaToCoverage = false;
+    bool mAlphaToCoverageSet = false;
 
     bool mSpecularAntiAliasing = false;
     bool mClearCoatIorChange = true;
@@ -814,6 +874,8 @@ private:
     PreprocessorDefineList mDefines;
 
     filament::UserVariantFilterMask mVariantFilter = {};
+
+    bool mNoSamplerValidation = false;
 };
 
 } // namespace filamat

ios/include/filament-iblprefilter/IBLPrefilterContext.h

@@ -58,6 +58,10 @@ class Texture;
 class UTILS_PUBLIC IBLPrefilterContext {
 public:
 
+    enum class Kernel : uint8_t {
+        D_GGX,        // Trowbridge-reitz distribution
+    };
+
     /**
      * Creates an IBLPrefilter context.
      * @param engine filament engine to use
@@ -109,7 +113,7 @@ public:
          *                          - Must be allocated with all mip levels.
          *                          - Must be SAMPLEABLE
          * @param outCubemap        Output cubemap. If null the texture is automatically created
-         *                          with default parameters (size of 256 with 5 levels).
+         *                          with default parameters (size of 256 with 9 levels).
          *                          - Must be a cubemap
          *                          - Must have SAMPLEABLE and COLOR_ATTACHMENT usage bits
          * @return returns outCubemap
@@ -123,6 +127,100 @@ public:
         filament::Material* mEquirectMaterial = nullptr;
     };
 
+    /**
+     * IrradianceFilter is a GPU based implementation of the diffuse probe pre-integration filter.
+     * An instance of IrradianceFilter is needed per filter configuration. A filter configuration
+     * contains the filter's kernel and sample count.
+     */
+    class IrradianceFilter {
+    public:
+        using Kernel = Kernel;
+
+        /**
+         * Filter configuration.
+         */
+        struct Config {
+            uint16_t sampleCount = 1024u;   //!< filter sample count (max 2048)
+            Kernel kernel = Kernel::D_GGX;  //!< filter kernel
+        };
+
+        /**
+         * Filtering options for the current environment.
+         */
+        struct Options {
+            float hdrLinear = 1024.0f;   //!< no HDR compression up to this value
+            float hdrMax = 16384.0f;     //!< HDR compression between hdrLinear and hdrMax
+            float lodOffset = 2.0f;      //!< Good values are 2.0 or 3.0. Higher values help with heavily HDR inputs.
+            bool generateMipmap = true;  //!< set to false if the input environment map already has mipmaps
+        };
+
+        /**
+         * Creates a IrradianceFilter processor.
+         * @param context IBLPrefilterContext to use
+         * @param config  Configuration of the filter
+         */
+        IrradianceFilter(IBLPrefilterContext& context, Config config);
+
+        /**
+         * Creates a filter with the default configuration.
+         * @param context IBLPrefilterContext to use
+         */
+        explicit IrradianceFilter(IBLPrefilterContext& context);
+
+        /**
+         * Destroys all GPU resources created during initialization.
+         */
+        ~IrradianceFilter() noexcept;
+
+        IrradianceFilter(IrradianceFilter const&) = delete;
+        IrradianceFilter& operator=(IrradianceFilter const&) = delete;
+        IrradianceFilter(IrradianceFilter&& rhs) noexcept;
+        IrradianceFilter& operator=(IrradianceFilter&& rhs) noexcept;
+
+        /**
+         * Generates an irradiance cubemap. Mipmaps are not generated even if present.
+         * @param options                   Options for this environment
+         * @param environmentCubemap        Environment cubemap (input). Can't be null.
+         *                                  This cubemap must be SAMPLEABLE and must have all its
+         *                                  levels allocated. If Options.generateMipmap is true,
+         *                                  the mipmap levels will be overwritten, otherwise
+         *                                  it is assumed that all levels are correctly initialized.
+         * @param outIrradianceTexture      Output irradiance texture or, if null, it is
+         *                                  automatically created with some default parameters.
+         *                                  outIrradianceTexture must be a cubemap, it must have
+         *                                  at least COLOR_ATTACHMENT and SAMPLEABLE usages.
+         *
+         * @return returns outIrradianceTexture
+         */
+        filament::Texture* operator()(Options options,
+                filament::Texture const* environmentCubemap,
+                filament::Texture* outIrradianceTexture = nullptr);
+
+        /**
+         * Generates a prefiltered cubemap.
+         * @param environmentCubemap        Environment cubemap (input). Can't be null.
+         *                                  This cubemap must be SAMPLEABLE and must have all its
+         *                                  levels allocated. If Options.generateMipmap is true,
+         *                                  the mipmap levels will be overwritten, otherwise
+         *                                  it is assumed that all levels are correctly initialized.
+         * @param outIrradianceTexture      Output irradiance texture or, if null, it is
+         *                                  automatically created with some default parameters.
+         *                                  outIrradianceTexture must be a cubemap, it must have
+         *                                  at least COLOR_ATTACHMENT and SAMPLEABLE usages.
+         *
+         * @return returns outReflectionsTexture
+         */
+        filament::Texture* operator()(
+                filament::Texture const* environmentCubemap,
+                filament::Texture* outIrradianceTexture = nullptr);
+
+    private:
+        filament::Texture* createIrradianceTexture();
+        IBLPrefilterContext& mContext;
+        filament::Material* mKernelMaterial = nullptr;
+        filament::Texture* mKernelTexture = nullptr;
+        uint32_t mSampleCount = 0u;
+    };
 
     /**
      * SpecularFilter is a GPU based implementation of the specular probe pre-integration filter.
@@ -131,9 +229,7 @@ public:
      */
     class SpecularFilter {
     public:
-        enum class Kernel : uint8_t {
-            D_GGX,        // Trowbridge-reitz distribution
-        };
+        using Kernel = Kernel;
 
         /**
          * Filter configuration.
@@ -151,7 +247,7 @@ public:
             float hdrLinear = 1024.0f;   //!< no HDR compression up to this value
             float hdrMax = 16384.0f;     //!< HDR compression between hdrLinear and hdrMax
             float lodOffset = 1.0f;      //!< Good values are 1.0 or 2.0. Higher values help with heavily HDR inputs.
-            bool generateMipmap = true;  //!< set to false if the environment map already has mipmaps
+            bool generateMipmap = true;  //!< set to false if the input environment map already has mipmaps
         };
 
         /**
@@ -237,6 +333,7 @@ private:
     utils::Entity mCameraEntity{};
     filament::View* mView{};
     filament::Material* mIntegrationMaterial{};
+    filament::Material* mIrradianceIntegrationMaterial{};
 };
 
 #endif //TNT_IBL_PREFILTER_IBLPREFILTER_H

ios/include/filament/Box.h

@@ -104,22 +104,24 @@ public:
     }
 
     /**
-     * Computes the bounding box of a box transformed by a rigid transform
+     * Transform a Box by a linear transform and a translation.
+     *
+     * @param m a 3x3 matrix, the linear transform
+     * @param t a float3, the translation
      * @param box the box to transform
-     * @param m a 4x4 matrix that must be a rigid transform
-     * @return the bounding box of the transformed box.
-     *         Result is undefined if \p m is not a rigid transform
+     * @return the bounding box of the transformed box
      */
-    friend Box rigidTransform(Box const& box, const math::mat4f& m) noexcept;
+    static Box transform(const math::mat3f& m, math::float3 const& t, const Box& box) noexcept {
+        return { m * box.center + t, abs(m) * box.halfExtent };
+    }
 
     /**
-     * Computes the bounding box of a box transformed by a rigid transform
-     * @param box the box to transform
-     * @param m a 3x3 matrix that must be a rigid transform
-     * @return the bounding box of the transformed box.
-     *         Result is undefined if \p m is not a rigid transform
+     * @deprecated Use transform() instead
+     * @see transform()
      */
-    friend Box rigidTransform(Box const& box, const math::mat3f& m) noexcept;
+    friend Box rigidTransform(Box const& box, const math::mat4f& m) noexcept {
+        return transform(m.upperLeft(), m[3].xyz, box);
+    }
 };
 
 /**
@@ -174,7 +176,18 @@ struct UTILS_PUBLIC Aabb {
     /**
      * Returns the 8 corner vertices of the AABB.
      */
-    Corners getCorners() const;
+    Corners getCorners() const {
+        return Aabb::Corners{ .vertices = {
+                { min.x, min.y, min.z },
+                { max.x, min.y, min.z },
+                { min.x, max.y, min.z },
+                { max.x, max.y, min.z },
+                { min.x, min.y, max.z },
+                { max.x, min.y, max.z },
+                { min.x, max.y, max.z },
+                { max.x, max.y, max.z },
+        }};
+    }
 
     /**
      * Returns whether the box contains a given point.
@@ -182,15 +195,44 @@ struct UTILS_PUBLIC Aabb {
      * @param p the point to test
      * @return the maximum signed distance to the box. Negative if p is in the box
      */
-    float contains(math::float3 p) const noexcept;
+    float contains(math::float3 p) const noexcept {
+        float d = min.x - p.x;
+        d = std::max(d, min.y - p.y);
+        d = std::max(d, min.z - p.z);
+        d = std::max(d, p.x - max.x);
+        d = std::max(d, p.y - max.y);
+        d = std::max(d, p.z - max.z);
+        return d;
+    }
 
     /**
      * Applies an affine transformation to the AABB.
      *
-     * @param m the 4x4 transformation to apply
+     * @param m the 3x3 transformation to apply
+     * @param t the translation
      * @return the transformed box
      */
-    Aabb transform(const math::mat4f& m) const noexcept;
+    static Aabb transform(const math::mat3f& m, math::float3 const& t, const Aabb& box) noexcept {
+        // Fast AABB transformation per Jim Arvo in Graphics Gems (1990).
+        Aabb result{ t, t };
+        for (size_t col = 0; col < 3; ++col) {
+            for (size_t row = 0; row < 3; ++row) {
+                const float a = m[col][row] * box.min[col];
+                const float b = m[col][row] * box.max[col];
+                result.min[row] += a < b ? a : b;
+                result.max[row] += a < b ? b : a;
+            }
+        }
+        return result;
+    }
+
+    /**
+     * @deprecated Use transform() instead
+     * @see transform()
+     */
+    Aabb transform(const math::mat4f& m) const noexcept {
+        return transform(m.upperLeft(), m[3].xyz, *this);
+    }
 };
 
 } // namespace filament

ios/include/filament/ColorSpace.h

@@ -191,7 +191,7 @@ private:
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  * // Declares a "linear sRGB" color space.
- * ColorSpace myColorSpace = Rec709-Linear-sRGB;
+ * ColorSpace myColorSpace = Rec709-Linear-D65;
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  */
 class PartialColorSpace {

ios/include/filament/Engine.h

@@ -17,6 +17,8 @@
 #ifndef TNT_FILAMENT_ENGINE_H
 #define TNT_FILAMENT_ENGINE_H
 
+#include <filament/FilamentAPI.h>
+
 #include <backend/Platform.h>
 
 #include <utils/compiler.h>
@@ -49,6 +51,7 @@ class SwapChain;
 class Texture;
 class VertexBuffer;
 class View;
+class InstanceBuffer;
 
 class LightManager;
 class RenderableManager;
@@ -164,6 +167,7 @@ class TransformManager;
  * @see Renderer
  */
 class UTILS_PUBLIC Engine {
+    struct BuilderDetails;
 public:
     using Platform = backend::Platform;
     using Backend = backend::Backend;
@@ -265,96 +269,124 @@ public:
         uint32_t perFrameCommandsSizeMB = FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB;
     };
 
+
+#if UTILS_HAS_THREADING
+    using CreateCallback = void(void* user, void* token);
+#endif
+
     /**
-     * Creates an instance of Engine
-     *
-     * @param backend           Which driver backend to use.
-     *
-     * @param platform          A pointer to an object that implements Platform. If this is
-     *                          provided, then this object is used to create the hardware context
-     *                          and expose platform features to it.
-     *
-     *                          If not provided (or nullptr is used), an appropriate Platform
-     *                          is created automatically.
-     *
-     *                          All methods of this interface are called from filament's
-     *                          render thread, which is different from the main thread.
-     *
-     *                          The lifetime of \p platform must exceed the lifetime of
-     *                          the Engine object.
-     *
-     *  @param sharedGLContext  A platform-dependant OpenGL context used as a shared context
-     *                          when creating filament's internal context.
-     *                          Setting this parameter will force filament to use the OpenGL
-     *                          implementation (instead of Vulkan for instance).
-     *
-     * @param config            A pointer to optional parameters to specify memory size
-     *                          configuration options.  If nullptr, then defaults used.
-     *
-     * @return A pointer to the newly created Engine, or nullptr if the Engine couldn't be created.
-     *
-     * nullptr if the GPU driver couldn't be initialized, for instance if it doesn't
-     * support the right version of OpenGL or OpenGL ES.
-     *
-     * @exception utils::PostConditionPanic can be thrown if there isn't enough memory to
-     * allocate the command buffer. If exceptions are disabled, this condition if fatal and
-     * this function will abort.
-     *
-     * \remark
-     * This method is thread-safe.
+     * Engine::Builder is used to create a new filament Engine.
      */
-    static Engine* create(Backend backend = Backend::DEFAULT,
-            Platform* platform = nullptr, void* sharedGLContext = nullptr,
-            const Config* config = nullptr);
+    class Builder : public BuilderBase<BuilderDetails> {
+        friend struct BuilderDetails;
+        friend class FEngine;
+    public:
+        Builder() noexcept;
+        Builder(Builder const& rhs) noexcept;
+        Builder(Builder&& rhs) noexcept;
+        ~Builder() noexcept;
+        Builder& operator=(Builder const& rhs) noexcept;
+        Builder& operator=(Builder&& rhs) noexcept;
+
+        /**
+         * @param backend Which driver backend to use
+         * @return A reference to this Builder for chaining calls.
+         */
+        Builder& backend(Backend backend) noexcept;
+
+        /**
+         * @param platform A pointer to an object that implements Platform. If this is
+         *                 provided, then this object is used to create the hardware context
+         *                 and expose platform features to it.
+         *
+         *                 If not provided (or nullptr is used), an appropriate Platform
+         *                 is created automatically.
+         *
+         *                 All methods of this interface are called from filament's
+         *                 render thread, which is different from the main thread.
+         *
+         *                 The lifetime of \p platform must exceed the lifetime of
+         *                 the Engine object.
+         *
+         * @return A reference to this Builder for chaining calls.
+         */
+        Builder& platform(Platform* platform) noexcept;
+
+        /**
+         * @param config    A pointer to optional parameters to specify memory size
+         *                  configuration options.  If nullptr, then defaults used.
+         *
+         * @return A reference to this Builder for chaining calls.
+         */
+        Builder& config(const Config* config) noexcept;
+
+        /**
+         * @param sharedContext A platform-dependant context used as a shared context
+         *                      when creating filament's internal context.
+         *
+         * @return A reference to this Builder for chaining calls.
+         */
+        Builder& sharedContext(void* sharedContext) noexcept;
+
+#if UTILS_HAS_THREADING
+        /**
+         * Creates the filament Engine asynchronously.
+         *
+         * @param callback  Callback called once the engine is initialized and it is safe to
+         *                  call Engine::getEngine().
+         */
+        void build(utils::Invocable<void(void* token)>&& callback) const;
+#endif
+
+        /**
+         * Creates an instance of Engine.
+         *
+         * @return  A pointer to the newly created Engine, or nullptr if the Engine couldn't be
+         *          created.
+         *          nullptr if the GPU driver couldn't be initialized, for instance if it doesn't
+         *          support the right version of OpenGL or OpenGL ES.
+         *
+         * @exception   utils::PostConditionPanic can be thrown if there isn't enough memory to
+         *              allocate the command buffer. If exceptions are disabled, this condition if
+         *              fatal and this function will abort.
+         */
+        Engine* build() const;
+    };
+
+    /**
+     * Backward compatibility helper to create an Engine.
+     * @see Builder
+     */
+    static inline Engine* create(Backend backend = Backend::DEFAULT,
+            Platform* platform = nullptr, void* sharedContext = nullptr,
+            const Config* config = nullptr) {
+        return Engine::Builder()
+                .backend(backend)
+                .platform(platform)
+                .sharedContext(sharedContext)
+                .config(config)
+                .build();
+    }
+
 
 #if UTILS_HAS_THREADING
     /**
-     * A callback used with Engine::createAsync() called once the engine is initialized and it is
-     * safe to call Engine::getEngine(token). This callback is invoked from an arbitrary worker
-     * thread. Engine::getEngine() CANNOT be called from that thread, instead it must be called
-     * from the same thread than Engine::createAsync() was called from.
-     *
-     * @param user   User provided parameter given in createAsync().
-     *
-     * @param token  An opaque token used to call Engine::getEngine().
+     * Backward compatibility helper to create an Engine asynchronously.
+     * @see Builder
      */
-    using CreateCallback = void(void* user, void* token);
-
-    /**
-     * Creates an instance of Engine asynchronously
-     *
-     * @param callback          Callback called once the engine is initialized and it is safe to
-     *                          call Engine::getEngine.
-     *
-     * @param user              A user provided pointer that is given back to callback unmodified.
-     *
-     * @param backend           Which driver backend to use.
-     *
-     * @param platform          A pointer to an object that implements Platform. If this is
-     *                          provided, then this object is used to create the hardware context
-     *                          and expose platform features to it.
-     *
-     *                          If not provided (or nullptr is used), an appropriate Platform
-     *                          is created automatically.
-     *
-     *                          All methods of this interface are called from filament's
-     *                          render thread, which is different from the main thread.
-     *
-     *                          The lifetime of \p platform must exceed the lifetime of
-     *                          the Engine object.
-     *
-     *  @param sharedGLContext  A platform-dependant OpenGL context used as a shared context
-     *                          when creating filament's internal context.
-     *                          Setting this parameter will force filament to use the OpenGL
-     *                          implementation (instead of Vulkan for instance).
-     * 
-     * @param config            A pointer to optional parameters to specify memory size
-     *                          configuration options
-     */
-    static void createAsync(CreateCallback callback, void* user,
+    static inline void createAsync(CreateCallback callback, void* user,
             Backend backend = Backend::DEFAULT,
-            Platform* platform = nullptr, void* sharedGLContext = nullptr,
-            const Config* config = nullptr);
+            Platform* platform = nullptr, void* sharedContext = nullptr,
+            const Config* config = nullptr) {
+        Engine::Builder()
+                .backend(backend)
+                .platform(platform)
+                .sharedContext(sharedContext)
+                .config(config)
+                .build([callback, user](void* token) {
+                    callback(user, token);
+                });
+    }
 
     /**
      * Retrieve an Engine* from createAsync(). This must be called from the same thread than
@@ -371,6 +403,7 @@ public:
     static Engine* getEngine(void* token);
 #endif
 
+
     /**
      * Destroy the Engine instance and all associated resources.
      *
@@ -464,6 +497,21 @@ public:
      */
     FeatureLevel getActiveFeatureLevel() const noexcept;
 
+    /**
+     * Queries the maximum number of GPU instances that Filament creates when automatic instancing
+     * is enabled. This value is also the limit for the number of transforms that can be stored in
+     * an InstanceBuffer. This value may depend on the device and platform, but will remain constant
+     * during the lifetime of this Engine.
+     *
+     * This value does not apply when using the instances(size_t) method on
+     * RenderableManager::Builder.
+     *
+     * @return the number of max automatic instances
+     * @see setAutomaticInstancingEnabled
+     * @see RenderableManager::Builder::instances(size_t)
+     * @see RenderableManager::Builder::instances(size_t, InstanceBuffer*)
+     */
+    size_t getMaxAutomaticInstances() const noexcept;
 
     /**
      * @return EntityManager used by filament
@@ -625,8 +673,28 @@ public:
     bool destroy(const Texture* p);             //!< Destroys a Texture object.
     bool destroy(const RenderTarget* p);        //!< Destroys a RenderTarget object.
     bool destroy(const View* p);                //!< Destroys a View object.
+    bool destroy(const InstanceBuffer* p);      //!< Destroys an InstanceBuffer object.
     void destroy(utils::Entity e);              //!< Destroys all filament-known components from this entity
 
+    bool isValid(const BufferObject* p);        //!< Tells whether a BufferObject object is valid
+    bool isValid(const VertexBuffer* p);        //!< Tells whether an VertexBuffer object is valid
+    bool isValid(const Fence* p);               //!< Tells whether a Fence object is valid
+    bool isValid(const IndexBuffer* p);         //!< Tells whether an IndexBuffer object is valid
+    bool isValid(const SkinningBuffer* p);      //!< Tells whether a SkinningBuffer object is valid
+    bool isValid(const MorphTargetBuffer* p);   //!< Tells whether a MorphTargetBuffer object is valid
+    bool isValid(const IndirectLight* p);       //!< Tells whether an IndirectLight object is valid
+    bool isValid(const Material* p);            //!< Tells whether an IndirectLight object is valid
+    bool isValid(const Renderer* p);            //!< Tells whether a Renderer object is valid
+    bool isValid(const Scene* p);               //!< Tells whether a Scene object is valid
+    bool isValid(const Skybox* p);              //!< Tells whether a SkyBox object is valid
+    bool isValid(const ColorGrading* p);        //!< Tells whether a ColorGrading object is valid
+    bool isValid(const SwapChain* p);           //!< Tells whether a SwapChain object is valid
+    bool isValid(const Stream* p);              //!< Tells whether a Stream object is valid
+    bool isValid(const Texture* p);             //!< Tells whether a Texture object is valid
+    bool isValid(const RenderTarget* p);        //!< Tells whether a RenderTarget object is valid
+    bool isValid(const View* p);                //!< Tells whether a View object is valid
+    bool isValid(const InstanceBuffer* p);      //!< Tells whether an InstanceBuffer object is valid
+
     /**
      * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until
      * all commands to this point are executed. Note that does guarantee that the

ios/include/filament/InstanceBuffer.h

@@ -0,0 +1,98 @@
+/*
+* Copyright (C) 2023 The Android Open Source Project
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*      http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+#ifndef TNT_FILAMENT_INSTANCEBUFFER_H
+#define TNT_FILAMENT_INSTANCEBUFFER_H
+
+#include <filament/FilamentAPI.h>
+
+#include <filament/Engine.h>
+
+#include <math/mathfwd.h>
+
+namespace filament {
+
+/**
+ * InstanceBuffer holds draw (GPU) instance transforms. These can be provided to a renderable to
+ * "offset" each draw instance.
+ *
+ * @see RenderableManager::Builder::instances(size_t, InstanceBuffer*)
+ */
+class UTILS_PUBLIC InstanceBuffer : public FilamentAPI {
+    struct BuilderDetails;
+
+public:
+    class Builder : public BuilderBase<BuilderDetails> {
+        friend struct BuilderDetails;
+
+    public:
+
+        /**
+         * @param instanceCount the number of instances this InstanceBuffer will support, must be
+         *                      >= 1 and <= \c Engine::getMaxAutomaticInstances()
+         * @see Engine::getMaxAutomaticInstances
+         */
+        Builder(size_t instanceCount) noexcept;
+
+        Builder(Builder const& rhs) noexcept;
+        Builder(Builder&& rhs) noexcept;
+        ~Builder() noexcept;
+        Builder& operator=(Builder const& rhs) noexcept;
+        Builder& operator=(Builder&& rhs) noexcept;
+
+        /**
+         * Provide an initial local transform for each instance. Each local transform is relative to
+         * the transform of the associated renderable. This forms a parent-child relationship
+         * between the renderable and its instances, so adjusting the renderable's transform will
+-        * affect all instances.
+         *
+         * The array of math::mat4f must have length instanceCount, provided when constructing this
+         * Builder.
+         *
+         * @param localTransforms an array of math::mat4f with length instanceCount, must remain
+         *                        valid until after build() is called
+         */
+        Builder& localTransforms(math::mat4f const* localTransforms) noexcept;
+
+        /**
+         * Creates the InstanceBuffer object and returns a pointer to it.
+         */
+        InstanceBuffer* build(Engine& engine);
+
+    private:
+        friend class FInstanceBuffer;
+    };
+
+    /**
+     * Returns the instance count specified when building this InstanceBuffer.
+     */
+    size_t getInstanceCount() const noexcept;
+
+    /**
+     * Sets the local transform for each instance. Each local transform is relative to the transform
+     * of the associated renderable. This forms a parent-child relationship between the renderable
+     * and its instances, so adjusting the renderable's transform will affect all instances.
+     *
+     * @param localTransforms an array of math::mat4f with length count, need not outlive this call
+     * @param count the number of local transforms
+     * @param offset index of the first instance to set local transforms
+     */
+    void setLocalTransforms(math::mat4f const* localTransforms, size_t count, size_t offset = 0);
+};
+
+} // namespace filament
+
+#endif //TNT_FILAMENT_INSTANCEBUFFER_H

ios/include/filament/Material.h

@@ -22,9 +22,11 @@
 #include <filament/MaterialEnums.h>
 #include <filament/MaterialInstance.h>
 
+#include <backend/CallbackHandler.h>
 #include <backend/DriverEnums.h>
 
 #include <utils/compiler.h>
+#include <utils/Invocable.h>
 
 #include <math/mathfwd.h>
 
@@ -105,6 +107,34 @@ public:
          */
         Builder& package(const void* payload, size_t size);
 
+        template<typename T>
+        using is_supported_constant_parameter_t = typename std::enable_if<
+                std::is_same<int32_t, T>::value ||
+                std::is_same<float, T>::value ||
+                std::is_same<bool, T>::value>::type;
+
+        /**
+         * Specialize a constant parameter specified in the material definition with a concrete
+         * value for this material. Once build() is called, this constant cannot be changed.
+         * Will throw an exception if the name does not match a constant specified in the
+         * material definition or if the type provided does not match.
+         *
+         * @tparam T The type of constant parameter, either int32_t, float, or bool.
+         * @param name The name of the constant parameter specified in the material definition, such
+         *             as "myConstant".
+         * @param nameLength Length in `char` of the name parameter.
+         * @param value The value to use for the constant parameter, must match the type specified
+         *              in the material definition.
+         */
+        template<typename T, typename = is_supported_constant_parameter_t<T>>
+        Builder& constant(const char* name, size_t nameLength, T value);
+
+        /** inline helper to provide the constant name as a null-terminated C string */
+        template<typename T, typename = is_supported_constant_parameter_t<T>>
+        inline Builder& constant(const char* name, T value) {
+            return constant(name, strlen(name), value);
+        }
+
         /**
          * Creates the Material object and returns a pointer to it.
          *
@@ -122,6 +152,60 @@ public:
         friend class FMaterial;
     };
 
+    using CompilerPriorityQueue = backend:: CompilerPriorityQueue;
+
+    /**
+     * Asynchronously ensures that a subset of this Material's variants are compiled. After issuing
+     * several Material::compile() calls in a row, it is recommended to call Engine::flush()
+     * such that the backend can start the compilation work as soon as possible.
+     * The provided callback is guaranteed to be called on the main thread after all specified
+     * variants of the material are compiled. This can take hundreds of milliseconds.
+     *
+     * If all the material's variants are already compiled, the callback will be scheduled as
+     * soon as possible, but this might take a few dozen millisecond, corresponding to how
+     * many previous frames are enqueued in the backend. This also varies by backend. Therefore,
+     * it is recommended to only call this method once per material shortly after creation.
+     *
+     * If the same variant is scheduled for compilation multiple times, the first scheduling
+     * takes precedence; later scheduling are ignored.
+     *
+     * caveat: A consequence is that if a variant is scheduled on the low priority queue and later
+     * scheduled again on the high priority queue, the later scheduling is ignored.
+     * Therefore, the second callback could be called before the variant is compiled.
+     * However, the first callback, if specified, will trigger as expected.
+     *
+     * The callback is guaranteed to be called. If the engine is destroyed while some material
+     * variants are still compiling or in the queue, these will be discarded and the corresponding
+     * callback will be called. In that case however the Material pointer passed to the callback
+     * is guaranteed to be invalid (either because it's been destroyed by the user already, or,
+     * because it's been cleaned-up by the Engine).
+     *
+     * @param priority      Which priority queue to use, LOW or HIGH.
+     * @param variants      Variants to include to the compile command.
+     * @param handler       Handler to dispatch the callback or nullptr for the default handler
+     * @param callback      callback called on the main thread when the compilation is done on
+     *                      by backend.
+     */
+    void compile(CompilerPriorityQueue priority,
+            UserVariantFilterMask variants,
+            backend::CallbackHandler* handler = nullptr,
+            utils::Invocable<void(Material*)>&& callback = {}) noexcept;
+
+    inline void compile(CompilerPriorityQueue priority,
+            UserVariantFilterBit variants,
+            backend::CallbackHandler* handler = nullptr,
+            utils::Invocable<void(Material*)>&& callback = {}) noexcept {
+        compile(priority, UserVariantFilterMask(variants), handler,
+                std::forward<utils::Invocable<void(Material*)>>(callback));
+    }
+
+    inline void compile(CompilerPriorityQueue priority,
+            backend::CallbackHandler* handler = nullptr,
+            utils::Invocable<void(Material*)>&& callback = {}) noexcept {
+        compile(priority, UserVariantFilterBit::ALL, handler,
+                std::forward<utils::Invocable<void(Material*)>>(callback));
+    }
+
     /**
      * Creates a new instance of this material. Material instances should be freed using
      * Engine::destroy(const MaterialInstance*).
@@ -171,6 +255,9 @@ public:
     //! Indicates whether this material is double-sided.
     bool isDoubleSided() const noexcept;
 
+    //! Indicates whether this material uses alpha to coverage.
+    bool isAlphaToCoverageEnabled() const noexcept;
+
     //! Returns the alpha mask threshold used when the blending mode is set to masked.
     float getMaskThreshold() const noexcept;
 

ios/include/filament/MaterialChunkType.h

@@ -47,10 +47,14 @@ enum UTILS_PUBLIC ChunkType : uint64_t {
     MaterialShaderModels = charTo64bitNum("MAT_SMDL"),
     MaterialSamplerBindings = charTo64bitNum("MAT_SAMP"),
     MaterialUniformBindings = charTo64bitNum("MAT_UNIF"),
+    MaterialBindingUniformInfo = charTo64bitNum("MAT_UFRM"),
+    MaterialAttributeInfo = charTo64bitNum("MAT_ATTR"),
     MaterialProperties = charTo64bitNum("MAT_PROP"),
+    MaterialConstants = charTo64bitNum("MAT_CONS"),
 
     MaterialName = charTo64bitNum("MAT_NAME"),
     MaterialVersion = charTo64bitNum("MAT_VERS"),
+    MaterialCacheId = charTo64bitNum("MAT_UUID"),
     MaterialFeatureLevel = charTo64bitNum("MAT_FEAT"),
     MaterialShading = charTo64bitNum("MAT_SHAD"),
     MaterialBlendingMode = charTo64bitNum("MAT_BLEN"),
@@ -67,15 +71,17 @@ enum UTILS_PUBLIC ChunkType : uint64_t {
     MaterialReflectionMode = charTo64bitNum("MAT_REFL"),
 
     MaterialRequiredAttributes = charTo64bitNum("MAT_REQA"),
-    MaterialDepthWriteSet = charTo64bitNum("MAT_DEWS"),
     MaterialDoubleSidedSet = charTo64bitNum("MAT_DOSS"),
     MaterialDoubleSided = charTo64bitNum("MAT_DOSI"),
 
     MaterialColorWrite = charTo64bitNum("MAT_CWRIT"),
+    MaterialDepthWriteSet = charTo64bitNum("MAT_DEWS"),
     MaterialDepthWrite = charTo64bitNum("MAT_DWRIT"),
     MaterialDepthTest = charTo64bitNum("MAT_DTEST"),
     MaterialInstanced = charTo64bitNum("MAT_INSTA"),
     MaterialCullingMode = charTo64bitNum("MAT_CUMO"),
+    MaterialAlphaToCoverageSet = charTo64bitNum("MAT_A2CS"),
+    MaterialAlphaToCoverage = charTo64bitNum("MAT_A2CO"),
 
     MaterialHasCustomDepthShader =charTo64bitNum("MAT_CSDP"),
 

ios/include/filament/MaterialEnums.h

@@ -20,6 +20,7 @@
 #define TNT_FILAMENT_MATERIAL_ENUM_H
 
 #include <utils/bitset.h>
+#include <utils/BitmaskEnum.h>
 
 #include <stddef.h>
 #include <stdint.h>
@@ -27,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 = 31;
+static constexpr size_t MATERIAL_VERSION = 41;
 
 /**
  * Supported shading models
@@ -232,7 +233,9 @@ enum class Property : uint8_t {
     // when adding new Properties, make sure to update MATERIAL_PROPERTIES_COUNT
 };
 
-enum class UserVariantFilterBit : uint32_t {
+using UserVariantFilterMask = uint32_t;
+
+enum class UserVariantFilterBit : UserVariantFilterMask {
     DIRECTIONAL_LIGHTING        = 0x01,
     DYNAMIC_LIGHTING            = 0x02,
     SHADOW_RECEIVER             = 0x04,
@@ -240,10 +243,12 @@ enum class UserVariantFilterBit : uint32_t {
     FOG                         = 0x10,
     VSM                         = 0x20,
     SSR                         = 0x40,
+    ALL                         = 0x7F,
 };
 
-using UserVariantFilterMask = uint32_t;
-
 } // namespace filament
 
+template<> struct utils::EnableBitMaskOperators<filament::UserVariantFilterBit>
+        : public std::true_type {};
+
 #endif

ios/include/filament/MaterialInstance.h

@@ -52,6 +52,7 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI {
 public:
     using CullingMode = filament::backend::CullingMode;
     using TransparencyMode = filament::TransparencyMode;
+    using DepthFunc = filament::backend::SamplerCompareFunc;
     using StencilCompareFunc = filament::backend::SamplerCompareFunc;
     using StencilOperation = filament::backend::StencilOperation;
     using StencilFace = filament::backend::StencilFace;
@@ -367,6 +368,16 @@ public:
      */
     void setDepthCulling(bool enable) noexcept;
 
+    /**
+     * Overrides the default depth function state that was set on the material.
+     */
+    void setDepthFunc(DepthFunc depthFunc) noexcept;
+
+    /**
+     * Returns the depth function state.
+     */
+    DepthFunc getDepthFunc() const noexcept;
+
     /**
      * Returns whether depth culling is enabled.
      */

ios/include/filament/Options.h

@@ -21,6 +21,8 @@
 
 #include <stdint.h>
 
+#include <math.h>
+
 namespace filament {
 
 class Texture;
@@ -151,19 +153,120 @@ struct BloomOptions {
 };
 
 /**
- * Options to control fog in the scene
+ * Options to control large-scale fog in the scene
  */
 struct FogOptions {
-    float distance = 0.0f;                 //!< distance in world units from the camera where the fog starts ( >= 0.0 )
-    float maximumOpacity = 1.0f;           //!< fog's maximum opacity between 0 and 1
-    float height = 0.0f;                   //!< fog's floor in world units
-    float heightFalloff = 1.0f;            //!< how fast fog dissipates with altitude
-    LinearColor color = {0.5f, 0.5f, 0.5f};//!< fog's color (linear), see fogColorFromIbl
-    float density = 0.1f;                  //!< fog's density at altitude given by 'height'
-    float inScatteringStart = 0.0f;        //!< distance in world units from the camera where in-scattering starts
-    float inScatteringSize = -1.0f;        //!< size of in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100).
-    bool fogColorFromIbl = false;          //!< Fog color will be modulated by the IBL color in the view direction.
-    bool enabled = false;                  //!< enable or disable fog
+    /**
+     * Distance in world units [m] from the camera to where the fog starts ( >= 0.0 )
+     */
+    float distance = 0.0f;
+
+    /**
+     * Distance in world units [m] after which the fog calculation is disabled.
+     * This can be used to exclude the skybox, which is desirable if it already contains clouds or
+     * fog. The default value is +infinity which applies the fog to everything.
+     *
+     * Note: The SkyBox is typically at a distance of 1e19 in world space (depending on the near
+     * plane distance and projection used though).
+     */
+    float cutOffDistance = INFINITY;
+
+    /**
+     * fog's maximum opacity between 0 and 1
+     */
+    float maximumOpacity = 1.0f;
+
+    /**
+     * Fog's floor in world units [m]. This sets the "sea level".
+     */
+    float height = 0.0f;
+
+    /**
+     * How fast the fog dissipates with altitude. heightFalloff has a unit of [1/m].
+     * It can be expressed as 1/H, where H is the altitude change in world units [m] that causes a
+     * factor 2.78 (e) change in fog density.
+     *
+     * A falloff of 0 means the fog density is constant everywhere and may result is slightly
+     * faster computations.
+     */
+    float heightFalloff = 1.0f;
+
+    /**
+     *  Fog's color is used for ambient light in-scattering, a good value is
+     *  to use the average of the ambient light, possibly tinted towards blue
+     *  for outdoors environments. Color component's values should be between 0 and 1, values
+     *  above one are allowed but could create a non energy-conservative fog (this is dependant
+     *  on the IBL's intensity as well).
+     *
+     *  We assume that our fog has no absorption and therefore all the light it scatters out
+     *  becomes ambient light in-scattering and has lost all directionality, i.e.: scattering is
+     *  isotropic. This somewhat simulates Rayleigh scattering.
+     *
+     *  This value is used as a tint instead, when fogColorFromIbl is enabled.
+     *
+     *  @see fogColorFromIbl
+     */
+    LinearColor color = { 1.0f, 1.0f, 1.0f };
+
+    /**
+     * Extinction factor in [1/m] at altitude 'height'. The extinction factor controls how much
+     * light is absorbed and out-scattered per unit of distance. Each unit of extinction reduces
+     * the incoming light to 37% of its original value.
+     *
+     * Note: The extinction factor is related to the fog density, it's usually some constant K times
+     * the density at sea level (more specifically at fog height). The constant K depends on
+     * the composition of the fog/atmosphere.
+     *
+     * For historical reason this parameter is called `density`.
+     */
+    float density = 0.1f;
+
+    /**
+     * Distance in world units [m] from the camera where the Sun in-scattering starts.
+     */
+    float inScatteringStart = 0.0f;
+
+    /**
+     * Very inaccurately simulates the Sun's in-scattering. That is, the light from the sun that
+     * is scattered (by the fog) towards the camera.
+     * Size of the Sun in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100).
+     * Smaller values result is a larger scattering size.
+     */
+    float inScatteringSize = -1.0f;
+
+    /**
+     * The fog color will be sampled from the IBL in the view direction and tinted by `color`.
+     * Depending on the scene this can produce very convincing results.
+     *
+     * This simulates a more anisotropic phase-function.
+     *
+     * `fogColorFromIbl` is ignored when skyTexture is specified.
+     *
+     * @see skyColor
+     */
+    bool fogColorFromIbl = false;
+
+    /**
+     * skyTexture must be a mipmapped cubemap. When provided, the fog color will be sampled from
+     * this texture, higher resolution mip levels will be used for objects at the far clip plane,
+     * and lower resolution mip levels for objects closer to the camera. The skyTexture should
+     * typically be heavily blurred; a typical way to produce this texture is to blur the base
+     * level with a strong gaussian filter or even an irradiance filter and then generate mip
+     * levels as usual. How blurred the base level is somewhat of an artistic decision.
+     *
+     * This simulates a more anisotropic phase-function.
+     *
+     * `fogColorFromIbl` is ignored when skyTexture is specified.
+     *
+     * @see Texture
+     * @see fogColorFromIbl
+     */
+    Texture* skyColor = nullptr;    //!< %codegen_skip_json% %codegen_skip_javascript%
+
+    /**
+     * Enable or disable large-scale fog
+     */
+    bool enabled = false;
 };
 
 /**

ios/include/filament/RenderTarget.h

@@ -91,8 +91,6 @@ public:
         /**
          * Sets a texture to a given attachment point.
          *
-         * All RenderTargets must have a non-null COLOR attachment.
-         *
          * When using a DEPTH attachment, it is important to always disable post-processing
          * in the View. Failing to do so will cause the DEPTH attachment to be ignored in most
          * cases.

ios/include/filament/RenderableManager.h

@@ -45,6 +45,7 @@ class Renderer;
 class SkinningBuffer;
 class VertexBuffer;
 class Texture;
+class InstanceBuffer;
 
 class FEngine;
 class FRenderPrimitive;
@@ -119,6 +120,12 @@ public:
     public:
         enum Result { Error = -1, Success = 0  };
 
+        /**
+         * Default render channel
+         * @see Builder::channel()
+         */
+        static constexpr uint8_t DEFAULT_CHANNEL = 2u;
+
         /**
          * Creates a builder for renderable components.
          *
@@ -231,10 +238,13 @@ public:
         /**
          * Set the channel this renderable is associated to. There can be 4 channels.
          * All renderables in a given channel are rendered together, regardless of anything else.
-         * They are sorted as usual withing a channel.
+         * They are sorted as usual within a channel.
          * Channels work similarly to priorities, except that they enforce the strongest ordering.
          *
-         * @param channel clamped to the range [0..3], defaults to 0.
+         * Channels 0 and 1 may not have render primitives using a material with `refractionType`
+         * set to `screenspace`.
+         *
+         * @param channel clamped to the range [0..3], defaults to 2.
          *
          * @return Builder reference for chaining calls.
          *
@@ -293,6 +303,14 @@ public:
          */
         Builder& enableSkinningBuffers(bool enabled = true) noexcept;
 
+        /**
+         * Controls if this renderable is affected by the large-scale fog.
+         * @param enabled If true, enables large-scale fog on this object. Disables it otherwise.
+         *                True by default.
+         * @return A reference to this Builder for chaining calls.
+         */
+        Builder& fog(bool enabled = true) noexcept;
+
         /**
          * Enables GPU vertex skinning for up to 255 bones, 0 by default.
          *
@@ -399,20 +417,47 @@ public:
          */
         Builder& globalBlendOrderEnabled(size_t primitiveIndex, bool enabled) noexcept;
 
-
         /**
-         * Specifies the number of draw instance of this renderable. The default is 1 instance and
-         * the maximum number of instances allowed is 65535. 0 is invalid.
+         * Specifies the number of draw instances of this renderable. The default is 1 instance and
+         * the maximum number of instances allowed is 32767. 0 is invalid.
+         *
          * All instances are culled using the same bounding box, so care must be taken to make
          * sure all instances render inside the specified bounding box.
+         *
          * The material must set its `instanced` parameter to `true` in order to use
          * getInstanceIndex() in the vertex or fragment shader to get the instance index and
          * possibly adjust the position or transform.
          *
-         * @param instanceCount the number of instances silently clamped between 1 and 65535.
+         * @param instanceCount the number of instances silently clamped between 1 and 32767.
          */
         Builder& instances(size_t instanceCount) noexcept;
 
+        /**
+         * Specifies the number of draw instances of this renderable and an \c InstanceBuffer
+         * containing their local transforms. The default is 1 instance and the maximum number of
+         * instances allowed when supplying transforms is given by
+         * \c Engine::getMaxAutomaticInstances (64 on most platforms). 0 is invalid. The
+         * \c InstanceBuffer must not be destroyed before this renderable.
+         *
+         * All instances are culled using the same bounding box, so care must be taken to make
+         * sure all instances render inside the specified bounding box.
+         *
+         * The material must set its `instanced` parameter to `true` in order to use
+         * \c getInstanceIndex() in the vertex or fragment shader to get the instance index.
+         *
+         * Only the \c VERTEX_DOMAIN_OBJECT vertex domain is supported.
+         *
+         * The local transforms of each instance can be updated with
+         * \c InstanceBuffer::setLocalTransforms.
+         *
+         * \see InstanceBuffer
+         * \see instances(size_t, * math::mat4f const*)
+         * @param instanceCount the number of instances, silently clamped between 1 and
+         *                      the result of Engine::getMaxAutomaticInstances().
+         * @param instanceBuffer an InstanceBuffer containing at least instanceCount transforms
+         */
+        Builder& instances(size_t instanceCount, InstanceBuffer* instanceBuffer) noexcept;
+
         /**
          * Adds the Renderable component to an entity.
          *
@@ -499,6 +544,19 @@ public:
      */
     void setCulling(Instance instance, bool enable) noexcept;
 
+    /**
+     * Changes whether or not the large-scale fog is applied to this renderable
+     * @see Builder::fog()
+     */
+    void setFogEnabled(Instance instance, bool enable) noexcept;
+
+    /**
+     * Returns whether large-scale fog is enabled for this renderable.
+     * @return True if fog is enabled for this renderable.
+     * @see Builder::fog()
+     */
+    bool getFogEnabled(Instance instance) const noexcept;
+
     /**
      * Enables or disables a light channel.
      * Light channel 0 is enabled by default.

ios/include/filament/View.h

@@ -707,6 +707,9 @@ public:
          * The viewport, projection and model matrices can be obtained from Camera. Because
          * pick() has some latency, it might be more accurate to obtain these values at the
          * time the View::pick() call is made.
+         *
+         * Note: if the Engine is running at FEATURE_LEVEL_0, the precision or `depth` and
+         *       `fragCoords.z` is only 8-bits.
          */
         math::float3 fragCoords;        //! screen space coordinates in GL convention
     };
@@ -803,6 +806,37 @@ public:
     PickingQuery& pick(uint32_t x, uint32_t y, backend::CallbackHandler* handler,
             PickingQueryResultCallback callback) noexcept;
 
+    /**
+     * Set the value of material global variables. There are up-to four such variable each of
+     * type float4. These variables can be read in a user Material with
+     * `getMaterialGlobal{0|1|2|3}()`. All variable start with a default value of { 0, 0, 0, 1 }
+     *
+     * @param index index of the variable to set between 0 and 3.
+     * @param value new value for the variable.
+     * @see getMaterialGlobal
+     */
+    void setMaterialGlobal(uint32_t index, math::float4 const& value);
+
+    /**
+     * Get the value of the material global variables.
+     * All variable start with a default value of { 0, 0, 0, 1 }
+     *
+     * @param index index of the variable to set between 0 and 3.
+     * @return current value of the variable.
+     * @see setMaterialGlobal
+     */
+    math::float4 getMaterialGlobal(uint32_t index) const;
+
+    /**
+     * Get an Entity representing the large scale fog object.
+     * This entity is always inherited by the View's Scene.
+     *
+     * It is for example possible to create a TransformManager component with this
+     * Entity and apply a transformation globally on the fog.
+     *
+     * @return an Entity representing the large scale fog object.
+     */
+    utils::Entity getFogEntity() const noexcept;
 
     /**
      * List of available ambient occlusion techniques

ios/include/geometry/TangentSpaceMesh.h

@@ -20,7 +20,6 @@
 #include <math/quat.h>
 #include <math/vec3.h>
 #include <math/vec4.h>
-#include <utils/compiler.h>
 
 namespace filament {
 namespace geometry {
@@ -28,8 +27,7 @@ namespace geometry {
 struct TangentSpaceMeshInput;
 struct TangentSpaceMeshOutput;
 
- /* WARNING: WORK-IN-PROGRESS, PLEASE DO NOT USE */
-/**
+ /**
  * This class builds Filament-style TANGENTS buffers given an input mesh.
  *
  * This class enables the client to chose between several algorithms. The client can retrieve the
@@ -140,8 +138,8 @@ public:
          */
         Builder& operator=(Builder&& that) noexcept;
 
-        Builder(const Builder&) = delete;
-        Builder& operator=(const Builder&) = delete;
+        Builder(Builder const&) = delete;
+        Builder& operator=(Builder const&) = delete;
 
         /**
          * Client must provide this parameter
@@ -155,7 +153,7 @@ public:
          * @param stride The stride for iterating through `normals`
          * @return Builder
          */
-        Builder& normals(const filament::math::float3* normals, size_t stride = 0) noexcept;
+        Builder& normals(filament::math::float3 const* normals, size_t stride = 0) noexcept;
 
         /**
          * @param tangents The input tangents. The `w` component is for use with
@@ -163,25 +161,25 @@ public:
          * @param stride The stride for iterating through `tangents`
          * @return Builder
          */
-        Builder& tangents(const filament::math::float4* tangents, size_t stride = 0) noexcept;
+        Builder& tangents(filament::math::float4 const* tangents, size_t stride = 0) noexcept;
 
         /**
          * @param uvs The input uvs
          * @param stride The stride for iterating through `uvs`
          * @return Builder
          */
-        Builder& uvs(const filament::math::float2* uvs, size_t stride = 0) noexcept;
+        Builder& uvs(filament::math::float2 const* uvs, size_t stride = 0) noexcept;
 
         /**
          * @param positions The input positions
          * @param stride The stride for iterating through `positions`
          * @return Builder
          */
-        Builder& positions(const filament::math::float3* positions, size_t stride = 0) noexcept;
+        Builder& positions(filament::math::float3 const* positions, size_t stride = 0) noexcept;
 
         Builder& triangleCount(size_t triangleCount) noexcept;
-        Builder& triangles(const filament::math::uint3* triangles) noexcept;
-        Builder& triangles(const filament::math::ushort3* triangles) noexcept;
+        Builder& triangles(filament::math::uint3 const* triangles) noexcept;
+        Builder& triangles(filament::math::ushort3 const* triangles) noexcept;
 
         Builder& algorithm(Algorithm algorithm) noexcept;
 
@@ -216,8 +214,8 @@ public:
      */
     TangentSpaceMesh& operator=(TangentSpaceMesh&& that) noexcept;
 
-    TangentSpaceMesh(const TangentSpaceMesh&) = delete;
-    TangentSpaceMesh& operator=(const TangentSpaceMesh&) = delete;
+    TangentSpaceMesh(TangentSpaceMesh const&) = delete;
+    TangentSpaceMesh& operator=(TangentSpaceMesh const&) = delete;
 
     /**
      * Number of output vertices

ios/include/ktxreader/Ktx2Reader.h

@@ -142,7 +142,7 @@ class Ktx2Reader {
 
         protected:
             Async() noexcept = default;
-            ~Async() = default;
+            virtual ~Async();
 
         public:
             Async(Async const&) = delete;

ios/include/material/image.S

@@ -8,5 +8,5 @@ IMAGE_PACKAGE:
 IMAGE_IMAGE_OFFSET:
     .int 0
 IMAGE_IMAGE_SIZE:
-    .int 44497
+    .int 17687
 

ios/include/material/image.apple.S

@@ -8,5 +8,5 @@ _IMAGE_PACKAGE:
 _IMAGE_IMAGE_OFFSET:
     .int 0
 _IMAGE_IMAGE_SIZE:
-    .int 44497
+    .int 17687
 

ios/include/math/mat3.h

@@ -430,8 +430,21 @@ constexpr TQuaternion<T> TMat33<T>::packTangentFrame(const TMat33<T>& m, size_t
     return q;
 }
 
+
 }  // namespace details
 
+/**
+ * Pre-scale a matrix m by the inverse of the largest scale factor to avoid large post-transform
+ * magnitudes in the shader. This is useful for normal transformations, to avoid large
+ * post-transform magnitudes in the shader, especially in the fragment shader, where we use
+ * medium precision.
+ */
+template<typename T>
+constexpr details::TMat33<T> prescaleForNormals(const details::TMat33<T>& m) noexcept {
+    return m * details::TMat33<T>(
+                    1.0 / std::sqrt(max(float3{length2(m[0]), length2(m[1]), length2(m[2])})));
+}
+
 // ----------------------------------------------------------------------------------------
 
 typedef details::TMat33<double> mat3;

ios/include/mikktspace/mikktspace.h

@@ -0,0 +1,145 @@
+/** \file mikktspace/mikktspace.h
+ *  \ingroup mikktspace
+ */
+/**
+ *  Copyright (C) 2011 by Morten S. Mikkelsen
+ *
+ *  This software is provided 'as-is', without any express or implied
+ *  warranty.  In no event will the authors be held liable for any damages
+ *  arising from the use of this software.
+ *
+ *  Permission is granted to anyone to use this software for any purpose,
+ *  including commercial applications, and to alter it and redistribute it
+ *  freely, subject to the following restrictions:
+ *
+ *  1. The origin of this software must not be misrepresented; you must not
+ *     claim that you wrote the original software. If you use this software
+ *     in a product, an acknowledgment in the product documentation would be
+ *     appreciated but is not required.
+ *  2. Altered source versions must be plainly marked as such, and must not be
+ *     misrepresented as being the original software.
+ *  3. This notice may not be removed or altered from any source distribution.
+ */
+
+#ifndef __MIKKTSPACE_H__
+#define __MIKKTSPACE_H__
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Author: Morten S. Mikkelsen
+ * Version: 1.0
+ *
+ * The files mikktspace.h and mikktspace.c are designed to be
+ * stand-alone files and it is important that they are kept this way.
+ * Not having dependencies on structures/classes/libraries specific
+ * to the program, in which they are used, allows them to be copied
+ * and used as is into any tool, program or plugin.
+ * The code is designed to consistently generate the same
+ * tangent spaces, for a given mesh, in any tool in which it is used.
+ * This is done by performing an internal welding step and subsequently an order-independent evaluation
+ * of tangent space for meshes consisting of triangles and quads.
+ * This means faces can be received in any order and the same is true for
+ * the order of vertices of each face. The generated result will not be affected
+ * by such reordering. Additionally, whether degenerate (vertices or texture coordinates)
+ * primitives are present or not will not affect the generated results either.
+ * Once tangent space calculation is done the vertices of degenerate primitives will simply
+ * inherit tangent space from neighboring non degenerate primitives.
+ * The analysis behind this implementation can be found in my master's thesis
+ * which is available for download --> http://image.diku.dk/projects/media/morten.mikkelsen.08.pdf
+ * Note that though the tangent spaces at the vertices are generated in an order-independent way,
+ * by this implementation, the interpolated tangent space is still affected by which diagonal is
+ * chosen to split each quad. A sensible solution is to have your tools pipeline always
+ * split quads by the shortest diagonal. This choice is order-independent and works with mirroring.
+ * If these have the same length then compare the diagonals defined by the texture coordinates.
+ * XNormal which is a tool for baking normal maps allows you to write your own tangent space plugin
+ * and also quad triangulator plugin.
+ */
+
+
+typedef int tbool;
+typedef struct SMikkTSpaceContext SMikkTSpaceContext;
+
+typedef struct {
+	// Returns the number of faces (triangles/quads) on the mesh to be processed.
+	int (*m_getNumFaces)(const SMikkTSpaceContext * pContext);
+
+	// Returns the number of vertices on face number iFace
+	// iFace is a number in the range {0, 1, ..., getNumFaces()-1}
+	int (*m_getNumVerticesOfFace)(const SMikkTSpaceContext * pContext, const int iFace);
+
+	// returns the position/normal/texcoord of the referenced face of vertex number iVert.
+	// iVert is in the range {0,1,2} for triangles and {0,1,2,3} for quads.
+	void (*m_getPosition)(const SMikkTSpaceContext * pContext, float fvPosOut[], const int iFace, const int iVert);
+	void (*m_getNormal)(const SMikkTSpaceContext * pContext, float fvNormOut[], const int iFace, const int iVert);
+	void (*m_getTexCoord)(const SMikkTSpaceContext * pContext, float fvTexcOut[], const int iFace, const int iVert);
+
+	// either (or both) of the two setTSpace callbacks can be set.
+	// The call-back m_setTSpaceBasic() is sufficient for basic normal mapping.
+
+	// This function is used to return the tangent and fSign to the application.
+	// fvTangent is a unit length vector.
+	// For normal maps it is sufficient to use the following simplified version of the bitangent which is generated at pixel/vertex level.
+	// bitangent = fSign * cross(vN, tangent);
+	// Note that the results are returned unindexed. It is possible to generate a new index list
+	// But averaging/overwriting tangent spaces by using an already existing index list WILL produce INCRORRECT results.
+	// DO NOT! use an already existing index list.
+	void (*m_setTSpaceBasic)(const SMikkTSpaceContext * pContext, const float fvTangent[], const float fSign, const int iFace, const int iVert);
+
+	// This function is used to return tangent space results to the application.
+	// fvTangent and fvBiTangent are unit length vectors and fMagS and fMagT are their
+	// true magnitudes which can be used for relief mapping effects.
+	// fvBiTangent is the "real" bitangent and thus may not be perpendicular to fvTangent.
+	// However, both are perpendicular to the vertex normal.
+	// For normal maps it is sufficient to use the following simplified version of the bitangent which is generated at pixel/vertex level.
+	// fSign = bIsOrientationPreserving ? 1.0f : (-1.0f);
+	// bitangent = fSign * cross(vN, tangent);
+	// Note that the results are returned unindexed. It is possible to generate a new index list
+	// But averaging/overwriting tangent spaces by using an already existing index list WILL produce INCRORRECT results.
+	// DO NOT! use an already existing index list.
+	void (*m_setTSpace)(const SMikkTSpaceContext * pContext, const float fvTangent[], const float fvBiTangent[], const float fMagS, const float fMagT,
+						const tbool bIsOrientationPreserving, const int iFace, const int iVert);
+} SMikkTSpaceInterface;
+
+struct SMikkTSpaceContext
+{
+	SMikkTSpaceInterface * m_pInterface;	// initialized with callback functions
+	void * m_pUserData;						// pointer to client side mesh data etc. (passed as the first parameter with every interface call)
+};
+
+// these are both thread safe!
+tbool genTangSpaceDefault(const SMikkTSpaceContext * pContext);	// Default (recommended) fAngularThreshold is 180 degrees (which means threshold disabled)
+tbool genTangSpace(const SMikkTSpaceContext * pContext, const float fAngularThreshold);
+
+
+// To avoid visual errors (distortions/unwanted hard edges in lighting), when using sampled normal maps, the
+// normal map sampler must use the exact inverse of the pixel shader transformation.
+// The most efficient transformation we can possibly do in the pixel shader is
+// achieved by using, directly, the "unnormalized" interpolated tangent, bitangent and vertex normal: vT, vB and vN.
+// pixel shader (fast transform out)
+// vNout = normalize( vNt.x * vT + vNt.y * vB + vNt.z * vN );
+// where vNt is the tangent space normal. The normal map sampler must likewise use the
+// interpolated and "unnormalized" tangent, bitangent and vertex normal to be compliant with the pixel shader.
+// sampler does (exact inverse of pixel shader):
+// float3 row0 = cross(vB, vN);
+// float3 row1 = cross(vN, vT);
+// float3 row2 = cross(vT, vB);
+// float fSign = dot(vT, row0)<0 ? -1 : 1;
+// vNt = normalize( fSign * float3(dot(vNout,row0), dot(vNout,row1), dot(vNout,row2)) );
+// where vNout is the sampled normal in some chosen 3D space.
+//
+// Should you choose to reconstruct the bitangent in the pixel shader instead
+// of the vertex shader, as explained earlier, then be sure to do this in the normal map sampler also.
+// Finally, beware of quad triangulations. If the normal map sampler doesn't use the same triangulation of
+// quads as your renderer then problems will occur since the interpolated tangent spaces will differ
+// eventhough the vertex level tangent spaces match. This can be solved either by triangulating before
+// sampling/exporting or by using the order-independent choice of diagonal for splitting quads suggested earlier.
+// However, this must be used both by the sampler and your tools/rendering pipeline.
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

ios/include/utils/BitmaskEnum.h

@@ -141,5 +141,4 @@ inline constexpr bool any(Enum lhs) noexcept {
     return !none(lhs);
 }
 
-
 #endif // TNT_UTILS_BITMASKENUM_H

ios/include/utils/Path.h

@@ -253,6 +253,12 @@ public:
      */
     static Path getTemporaryDirectory();
 
+    /**
+     * @return a path representing a directory where settings files can be stored,
+     *         it is recommended to append an app specific folder name to that path
+     */
+    static Path getUserSettingsDirectory();
+
     /**
      * Creates a directory denoted by the given path.
      * This is not recursive and doesn't create intermediate directories.

ios/include/utils/SingleInstanceComponentManager.h

@@ -60,16 +60,19 @@ private:
 protected:
     static constexpr size_t ENTITY_INDEX = sizeof ... (Elements);
 
+
 public:
     using SoA = StructureOfArrays<Elements ..., Entity>;
 
+    using Structure = typename SoA::Structure;
+
     using Instance = EntityInstanceBase::Type;
 
     SingleInstanceComponentManager() noexcept {
         // We always start with a dummy entry because index=0 is reserved. The component
         // at index = 0, is guaranteed to be default-initialized.
         // Sub-classes can use this to their advantage.
-        mData.push_back();
+        mData.push_back(Structure{});
     }
 
     SingleInstanceComponentManager(SingleInstanceComponentManager&&) noexcept {/* = default */}
@@ -269,7 +272,7 @@ SingleInstanceComponentManager<Elements ...>::addComponent(Entity e) {
     if (!e.isNull()) {
         if (!hasComponent(e)) {
             // this is like a push_back(e);
-            mData.push_back().template back<ENTITY_INDEX>() = e;
+            mData.push_back(Structure{}).template back<ENTITY_INDEX>() = e;
             // index 0 is used when the component doesn't exist
             ci = Instance(mData.size() - 1);
             mInstanceMap[e] = ci;

ios/include/utils/StructureOfArrays.h

@@ -41,11 +41,13 @@ class StructureOfArraysBase {
     static constexpr const size_t kArrayCount = sizeof...(Elements);
 
 public:
-    using SoA = StructureOfArraysBase<Allocator, Elements ...>;
+    using SoA = StructureOfArraysBase<Allocator, Elements...>;
+
+    using Structure = std::tuple<Elements...>;
 
     // Type of the Nth array
     template<size_t N>
-    using TypeAt = typename std::tuple_element_t<N, std::tuple<Elements...>>;
+    using TypeAt = typename std::tuple_element_t<N, Structure>;
 
     // Number of arrays
     static constexpr size_t getArrayCount() noexcept { return kArrayCount; }
@@ -57,7 +59,7 @@ public:
 
     // --------------------------------------------------------------------------------------------
 
-    class Structure;
+    class IteratorValue;
     template<typename T> class Iterator;
     using iterator = Iterator<StructureOfArraysBase*>;
     using const_iterator = Iterator<StructureOfArraysBase const*>;
@@ -69,45 +71,45 @@ public:
      * In other words, it's the return type of iterator::operator*(), and since it
      * cannot be a C++ reference (&), it's an object that acts like it.
      */
-    class StructureRef {
-        friend class Structure;
+    class IteratorValueRef {
+        friend class IteratorValue;
         friend iterator;
         friend const_iterator;
         StructureOfArraysBase* const UTILS_RESTRICT soa;
         size_t const index;
 
-        StructureRef(StructureOfArraysBase* soa, size_t index) : soa(soa), index(index) { }
+        IteratorValueRef(StructureOfArraysBase* soa, size_t index) : soa(soa), index(index) { }
 
         // assigns a value_type to a reference (i.e. assigns to what's pointed to by the reference)
         template<size_t ... Is>
-        StructureRef& assign(Structure const& rhs, std::index_sequence<Is...>);
+        IteratorValueRef& assign(IteratorValue const& rhs, std::index_sequence<Is...>);
 
         // assigns a value_type to a reference (i.e. assigns to what's pointed to by the reference)
         template<size_t ... Is>
-        StructureRef& assign(Structure&& rhs, std::index_sequence<Is...>) noexcept;
+        IteratorValueRef& assign(IteratorValue&& rhs, std::index_sequence<Is...>) noexcept;
 
         // objects pointed to by reference can be swapped, so provide the special swap() function.
-        friend void swap(StructureRef lhs, StructureRef rhs) {
+        friend void swap(IteratorValueRef lhs, IteratorValueRef rhs) {
             lhs.soa->swap(lhs.index, rhs.index);
         }
 
     public:
         // references can be created by copy-assignment only
-        StructureRef(StructureRef const& rhs) noexcept : soa(rhs.soa), index(rhs.index) { }
+        IteratorValueRef(IteratorValueRef const& rhs) noexcept : soa(rhs.soa), index(rhs.index) { }
 
         // copy the content of a reference to the content of this one
-        StructureRef& operator=(StructureRef const& rhs);
+        IteratorValueRef& operator=(IteratorValueRef const& rhs);
 
         // move the content of a reference to the content of this one
-        StructureRef& operator=(StructureRef&& rhs) noexcept;
+        IteratorValueRef& operator=(IteratorValueRef&& rhs) noexcept;
 
         // copy a value_type to the content of this reference
-        StructureRef& operator=(Structure const& rhs) {
+        IteratorValueRef& operator=(IteratorValue const& rhs) {
             return assign(rhs, std::make_index_sequence<kArrayCount>());
         }
 
         // move a value_type to the content of this reference
-        StructureRef& operator=(Structure&& rhs) noexcept {
+        IteratorValueRef& operator=(IteratorValue&& rhs) noexcept {
             return assign(rhs, std::make_index_sequence<kArrayCount>());
         }
 
@@ -122,36 +124,36 @@ public:
      * Internally we're using a tuple<> to store the data.
      * This object is not trivial to construct, as it copies an entry of the SoA.
      */
-    class Structure {
-        friend class StructureRef;
+    class IteratorValue {
+        friend class IteratorValueRef;
         friend iterator;
         friend const_iterator;
         using Type = std::tuple<typename std::decay<Elements>::type...>;
         Type elements;
 
         template<size_t ... Is>
-        static Type init(StructureRef const& rhs, std::index_sequence<Is...>) {
+        static Type init(IteratorValueRef const& rhs, std::index_sequence<Is...>) {
             return Type{ rhs.soa->template elementAt<Is>(rhs.index)... };
         }
 
         template<size_t ... Is>
-        static Type init(StructureRef&& rhs, std::index_sequence<Is...>) noexcept {
+        static Type init(IteratorValueRef&& rhs, std::index_sequence<Is...>) noexcept {
             return Type{ std::move(rhs.soa->template elementAt<Is>(rhs.index))... };
         }
 
     public:
-        Structure(Structure const& rhs) = default;
-        Structure(Structure&& rhs) noexcept = default;
-        Structure& operator=(Structure const& rhs) = default;
-        Structure& operator=(Structure&& rhs) noexcept = default;
+        IteratorValue(IteratorValue const& rhs) = default;
+        IteratorValue(IteratorValue&& rhs) noexcept = default;
+        IteratorValue& operator=(IteratorValue const& rhs) = default;
+        IteratorValue& operator=(IteratorValue&& rhs) noexcept = default;
 
         // initialize and assign from a StructureRef
-        Structure(StructureRef const& rhs)
+        IteratorValue(IteratorValueRef const& rhs)
                 : elements(init(rhs, std::make_index_sequence<kArrayCount>())) {}
-        Structure(StructureRef&& rhs) noexcept
+        IteratorValue(IteratorValueRef&& rhs) noexcept
                 : elements(init(rhs, std::make_index_sequence<kArrayCount>())) {}
-        Structure& operator=(StructureRef const& rhs) { return operator=(Structure(rhs)); }
-        Structure& operator=(StructureRef&& rhs) noexcept { return operator=(Structure(rhs)); }
+        IteratorValue& operator=(IteratorValueRef const& rhs) { return operator=(IteratorValue(rhs)); }
+        IteratorValue& operator=(IteratorValueRef&& rhs) noexcept { return operator=(IteratorValue(rhs)); }
 
         // access the elements of this value_Type (i.e. the "fields" of the structure)
         template<size_t I> TypeAt<I> const& get() const { return std::get<I>(elements); }
@@ -174,9 +176,9 @@ public:
         Iterator(CVQualifiedSOAPointer soa, size_t index) : soa(soa), index(index) {}
 
     public:
-        using value_type = Structure;
-        using reference = StructureRef;
-        using pointer = StructureRef*;    // FIXME: this should be a StructurePtr type
+        using value_type = IteratorValue;
+        using reference = IteratorValueRef;
+        using pointer = IteratorValueRef*;    // FIXME: this should be a StructurePtr type
         using difference_type = ptrdiff_t;
         using iterator_category = std::random_access_iterator_tag;
 
@@ -335,6 +337,11 @@ public:
         return *this;
     }
 
+    StructureOfArraysBase& push_back(Structure&& args) noexcept {
+        ensureCapacity(mSize + 1);
+        return push_back_unsafe(std::forward<Structure>(args));
+    }
+
     StructureOfArraysBase& push_back(Elements const& ... args) noexcept {
         ensureCapacity(mSize + 1);
         return push_back_unsafe(args...);
@@ -349,23 +356,29 @@ public:
     struct PushBackUnsafeClosure {
         size_t last;
         std::tuple<Elements...> args;
-        inline explicit PushBackUnsafeClosure(size_t last, Elements&& ... args)
-                : last(last), args(std::forward<Elements>(args)...) {}
-        inline explicit PushBackUnsafeClosure(size_t last, Elements const& ... args)
-                : last(last), args(args...) {}
+        inline explicit PushBackUnsafeClosure(size_t last, Structure&& args)
+                : last(last), args(std::forward<Structure>(args)) {}
         template<size_t I>
         inline void operator()(TypeAt<I>* p) {
             new(p + last) TypeAt<I>{ std::get<I>(args) };
         }
     };
 
+    StructureOfArraysBase& push_back_unsafe(Structure&& args) noexcept {
+        for_each_index(mArrays,
+                PushBackUnsafeClosure{ mSize++, std::forward<Structure>(args) });
+        return *this;
+    }
+
     StructureOfArraysBase& push_back_unsafe(Elements const& ... args) noexcept {
-        for_each_index(mArrays, PushBackUnsafeClosure{ mSize++, args... });
+        for_each_index(mArrays,
+                PushBackUnsafeClosure{ mSize++, { args... } });
         return *this;
     }
 
     StructureOfArraysBase& push_back_unsafe(Elements&& ... args) noexcept {
-        for_each_index(mArrays, PushBackUnsafeClosure{ mSize++, std::forward<Elements>(args)... });
+        for_each_index(mArrays,
+                PushBackUnsafeClosure{ mSize++, { std::forward<Elements>(args)... }});
         return *this;
     }
 
@@ -562,8 +575,10 @@ private:
         forEach([from, to](auto p) {
             using T = typename std::decay<decltype(*p)>::type;
             // note: scalar types like int/float get initialized to zero
-            for (size_t i = from; i < to; i++) {
-                new(p + i) T();
+            if constexpr (!std::is_trivially_default_constructible_v<T>) {
+                for (size_t i = from; i < to; i++) {
+                    new(p + i) T();
+                }
             }
         });
     }
@@ -571,8 +586,10 @@ private:
     void destroy_each(size_t from, size_t to) noexcept {
         forEach([from, to](auto p) {
             using T = typename std::decay<decltype(*p)>::type;
-            for (size_t i = from; i < to; i++) {
-                p[i].~T();
+            if constexpr (!std::is_trivially_destructible_v<T>) {
+                for (size_t i = from; i < to; i++) {
+                    p[i].~T();
+                }
             }
         });
     }
@@ -592,15 +609,17 @@ private:
                         reinterpret_cast<T*>(uintptr_t(b) + offsets[index]);
 
                 // for trivial cases, just call memcpy()
-                if (std::is_trivially_copyable<T>::value &&
-                    std::is_trivially_destructible<T>::value) {
+                if constexpr (std::is_trivially_copyable_v<T> &&
+                              std::is_trivially_destructible_v<T>) {
                     memcpy(arrayPointer, p, size * sizeof(T));
                 } else {
                     for (size_t i = 0; i < size; i++) {
                         // we move an element by using the in-place move-constructor
                         new(arrayPointer + i) T(std::move(p[i]));
-                        // and delete them by calling the destructor directly
-                        p[i].~T();
+                        if constexpr (!std::is_trivially_destructible_v<T>) {
+                            // and delete them by calling the destructor directly
+                            p[i].~T();
+                        }
                     }
                 }
                 index++;
@@ -626,27 +645,27 @@ private:
 
 template<typename Allocator, typename... Elements>
 inline
-typename StructureOfArraysBase<Allocator, Elements...>::StructureRef&
-StructureOfArraysBase<Allocator, Elements...>::StructureRef::operator=(
-        StructureOfArraysBase::StructureRef const& rhs) {
-    return operator=(Structure(rhs));
+typename StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef&
+StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef::operator=(
+        StructureOfArraysBase::IteratorValueRef const& rhs) {
+    return operator=(IteratorValue(rhs));
 }
 
 template<typename Allocator, typename... Elements>
 inline
-typename StructureOfArraysBase<Allocator, Elements...>::StructureRef&
-StructureOfArraysBase<Allocator, Elements...>::StructureRef::operator=(
-        StructureOfArraysBase::StructureRef&& rhs) noexcept {
-    return operator=(Structure(rhs));
+typename StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef&
+StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef::operator=(
+        StructureOfArraysBase::IteratorValueRef&& rhs) noexcept {
+    return operator=(IteratorValue(rhs));
 }
 
 template<typename Allocator, typename... Elements>
 template<size_t... Is>
 inline
-typename StructureOfArraysBase<Allocator, Elements...>::StructureRef&
-StructureOfArraysBase<Allocator, Elements...>::StructureRef::assign(
-        StructureOfArraysBase::Structure const& rhs, std::index_sequence<Is...>) {
-    // implements StructureRef& StructureRef::operator=(Structure const& rhs)
+typename StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef&
+StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef::assign(
+        StructureOfArraysBase::IteratorValue const& rhs, std::index_sequence<Is...>) {
+    // implements IteratorValueRef& IteratorValueRef::operator=(IteratorValue const& rhs)
     auto UTILS_UNUSED l = { (soa->elementAt<Is>(index) = std::get<Is>(rhs.elements), 0)... };
     return *this;
 }
@@ -654,10 +673,10 @@ StructureOfArraysBase<Allocator, Elements...>::StructureRef::assign(
 template<typename Allocator, typename... Elements>
 template<size_t... Is>
 inline
-typename StructureOfArraysBase<Allocator, Elements...>::StructureRef&
-StructureOfArraysBase<Allocator, Elements...>::StructureRef::assign(
-        StructureOfArraysBase::Structure&& rhs, std::index_sequence<Is...>) noexcept {
-    // implements StructureRef& StructureRef::operator=(Structure&& rhs) noexcept
+typename StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef&
+StructureOfArraysBase<Allocator, Elements...>::IteratorValueRef::assign(
+        StructureOfArraysBase::IteratorValue&& rhs, std::index_sequence<Is...>) noexcept {
+    // implements IteratorValueRef& IteratorValueRef::operator=(IteratorValue&& rhs) noexcept
     auto UTILS_UNUSED l = {
             (soa->elementAt<Is>(index) = std::move(std::get<Is>(rhs.elements)), 0)... };
     return *this;

ios/include/utils/compiler.h

@@ -54,6 +54,12 @@
 #    define UTILS_NORETURN
 #endif
 
+#if __has_attribute(fallthrough)
+#   define UTILS_FALLTHROUGH [[fallthrough]]
+#else
+#   define UTILS_FALLTHROUGH
+#endif
+
 #if __has_attribute(visibility)
 #    ifndef TNT_DEV
 #        define UTILS_PRIVATE __attribute__((visibility("hidden")))

ios/include/utils/ostream.h

@@ -107,7 +107,7 @@ private:
     friend ostream& flush(ostream& s) noexcept;
 
     enum type {
-        SHORT, USHORT, CHAR, UCHAR, INT, UINT, LONG, ULONG, LONG_LONG, ULONG_LONG, DOUBLE,
+        SHORT, USHORT, CHAR, UCHAR, INT, UINT, LONG, ULONG, LONG_LONG, ULONG_LONG, FLOAT, DOUBLE,
         LONG_DOUBLE
     };
 

ios/include/viewer/Settings.h

@@ -82,7 +82,7 @@ using LightManager = filament::LightManager;
 void applySettings(Engine* engine, const ViewSettings& settings, View* dest);
 void applySettings(Engine* engine, const MaterialSettings& settings, MaterialInstance* dest);
 void applySettings(Engine* engine, const LightSettings& settings, IndirectLight* ibl, utils::Entity sunlight,
-        utils::Entity* sceneLights, size_t sceneLightCount, LightManager* lm, Scene* scene, View* view);
+        const utils::Entity* sceneLights, size_t sceneLightCount, LightManager* lm, Scene* scene, View* view);
 void applySettings(Engine* engine, const ViewerOptions& settings, Camera* camera, Skybox* skybox,
         Renderer* renderer);
 
@@ -160,6 +160,10 @@ struct DynamicLightingSettings {
     float zLightFar = 100;
 };
 
+struct FogSettings {
+    Texture* fogColorTexture = nullptr;
+};
+
 // This defines fields in the same order as the setter methods in filament::View.
 struct ViewSettings {
     // standalone View settings
@@ -185,6 +189,7 @@ struct ViewSettings {
     // Custom View Options
     ColorGradingSettings colorGrading;
     DynamicLightingSettings dynamicLighting;
+    FogSettings fogSettings;
 };
 
 template <typename T>
@@ -204,6 +209,9 @@ struct LightSettings {
     LightManager::ShadowOptions shadowOptions;
     SoftShadowOptions softShadowOptions;
     float sunlightIntensity = 100000.0f;
+    float sunlightHaloSize = 10.0f;
+    float sunlightHaloFalloff = 80.0f;
+    float sunlightAngularRadius = 1.9f;
     math::float3 sunlightDirection = {0.6, -1.0, -0.8};
     math::float3 sunlightColor = filament::Color::toLinear<filament::ACCURATE>({ 0.98, 0.92, 0.89});
     float iblIntensity = 30000.0f;
@@ -214,6 +222,8 @@ struct ViewerOptions {
     float cameraAperture = 16.0f;
     float cameraSpeed = 125.0f;
     float cameraISO = 100.0f;
+    float cameraNear = 0.1f;
+    float cameraFar = 100.0f;
     float groundShadowStrength = 0.75f;
     bool groundPlaneEnabled = false;
     bool skyboxEnabled = true;

ios/include/viewer/ViewerGui.h

@@ -234,8 +234,6 @@ public:
 private:
     using SceneMask = gltfio::NodeManager::SceneMask;
 
-    void updateIndirectLight();
-
     bool isRemoteMode() const { return mAsset == nullptr; }
 
     void sceneSelectionUI();