Merge branch 'rc/1.33.0' into release

NEW_RELEASE_NOTES.md

@@ -7,4 +7,3 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
-

README.md

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

RELEASE_NOTES.md

@@ -7,6 +7,10 @@ A new header is inserted each time a *tag* is created.
 Instead, if you are authoring a PR for the main branch, add your release note to
 [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md).
 
+## v1.33.0
+
+- materials: prepare ES2 support [⚠️ **New Material Version**]
+
 ## v1.32.4
 
 - engine: Add support for _constant parameters_, which are constants that can be specialized after material compilation.

android/gradle.properties

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

docs/Filament.html

@@ -3164,7 +3164,7 @@
 </p><p>
 
 However, in practice we're using <em class="underscore">importance sampling</em> which needs to take the \(pdf\) of the distribution
-into account and adds a term \(\frac{\left&lt;\VoH\right&gt;}{D(h_i, \alpha)\left&lt;\NoH\right&gt;}\).
+into account and adds a term \(\frac{4\left&lt;\VoH\right&gt;}{D(h_i, \alpha)\left&lt;\NoH\right&gt;}\).
 See <a href="#importancesamplingfortheibl">Importance Sampling For The IBL</a> section:
 
 </p><p>
@@ -5274,7 +5274,7 @@
 </p><p>
 
 $$\begin{equation}
-p(T_r(x)) = p(x) |J(T_r)|
+p(T_r(x)) = p(x) |J(T_r)|^{-1}
 \end{equation}$$
 
 </p><p>
@@ -5285,8 +5285,8 @@
 </p><p>
 
 $$\begin{equation}\label{iblPDF}
-p(l,v,\Theta) = D(h,\alpha) \left&lt; \NoH \right&gt; |J_{h \rightarrow l}| \\
-|J_{h \rightarrow l}| = \frac{1}{4 \left&lt; \VoH \right&gt;}
+p(l,v,\Theta) = D(h,\alpha) \left&lt; \NoH \right&gt; |J_{h \rightarrow l}|^{-1} \\
+|J_{h \rightarrow l}| = 4 \left&lt; \VoH \right&gt;
 \end{equation}$$
 
 </p>

docs/Filament.md.html

@@ -200,7 +200,7 @@
 
 ## Specular BRDF
 
-For the specular term, $f_m$ is a mirror BRDF that can be modeled with the Fresnel law, noted $F$ in the Cook-Torrance approximation of the microfacet model integration:
+For the specular term, $f_r$ is a mirror BRDF that can be modeled with the Fresnel law, noted $F$ in the Cook-Torrance approximation of the microfacet model integration:
 
 $$\begin{equation}
 f_r(v,l) = \frac{D(h, \alpha) G(v, l, \alpha) F(v, h, f0)}{4(\NoV)(\NoL)}
@@ -485,7 +485,7 @@
     // perceptually linear roughness to roughness (see parameterization)
     float roughness = perceptualRoughness * perceptualRoughness;
 
-    float D = D_GGX(NoH, a);
+    float D = D_GGX(NoH, roughness);
     vec3  F = F_Schlick(LoH, f0);
     float V = V_SmithGGXCorrelated(NoV, NoL, roughness);
 

filament/backend/CMakeLists.txt

@@ -175,6 +175,8 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/VulkanFboCache.h
             src/vulkan/VulkanHandles.cpp
             src/vulkan/VulkanHandles.h
+            src/vulkan/VulkanImageUtility.cpp
+            src/vulkan/VulkanImageUtility.h
             src/vulkan/VulkanMemory.h
             src/vulkan/VulkanMemory.cpp
             src/vulkan/VulkanPipelineCache.cpp

filament/backend/src/vulkan/VulkanBlitter.cpp

@@ -32,6 +32,8 @@ using namespace utils;
 
 namespace filament::backend {
 
+using ImgUtil = VulkanImageUtility;
+
 namespace {
 
 inline void blitFast(const VkCommandBuffer cmdbuffer, VkImageAspectFlags aspect, VkFilter filter,
@@ -63,61 +65,42 @@ inline void blitFast(const VkCommandBuffer cmdbuffer, VkImageAspectFlags aspect,
             .baseArrayLayer = dst.layer,
             .layerCount = 1,
     };
-    const VkImageLayout srcLayout = getDefaultImageLayout(src.texture->usage);
-    transitionImageLayout(cmdbuffer, {
-                                             src.getImage(),
-                                             srcLayout,
-                                             VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
-                                             srcRange,
-                                             VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
-                                             0,
-                                             VK_PIPELINE_STAGE_TRANSFER_BIT,
-                                             VK_ACCESS_TRANSFER_READ_BIT,
-                                     });
-
-    transitionImageLayout(cmdbuffer, {
-                                             dst.getImage(),
-                                             VK_IMAGE_LAYOUT_UNDEFINED,
-                                             VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
-                                             dstRange,
-                                             VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
-                                             0,
-                                             VK_PIPELINE_STAGE_TRANSFER_BIT,
-                                             VK_ACCESS_TRANSFER_WRITE_BIT,
-                                     });
+
+    if constexpr (FILAMENT_VULKAN_VERBOSE) {
+        utils::slog.d << "Fast blit from=" << src.texture->getVkImage() << ",level=" << (int) src.level
+                      << "layout=" << src.getLayout()
+                      << " to=" << dst.texture->getVkImage() << ",level=" << (int) dst.level
+                      << "layout=" << dst.getLayout() << utils::io::endl;
+    }
+
+    src.texture->transitionLayout(cmdbuffer, srcRange, VulkanLayout::TRANSFER_SRC);
+    dst.texture->transitionLayout(cmdbuffer, dstRange, VulkanLayout::TRANSFER_DST);
 
     if (src.texture->samples > 1 && dst.texture->samples == 1) {
         assert_invariant(
                 aspect != VK_IMAGE_ASPECT_DEPTH_BIT && "Resolve with depth is not yet supported.");
-        vkCmdResolveImage(cmdbuffer, src.getImage(), VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
-                dst.getImage(), VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, resolveRegions);
+        vkCmdResolveImage(cmdbuffer,
+                src.getImage(), ImgUtil::getVkLayout(VulkanLayout::TRANSFER_SRC),
+                dst.getImage(), ImgUtil::getVkLayout(VulkanLayout::TRANSFER_DST),
+                1, resolveRegions);
     } else {
-        vkCmdBlitImage(cmdbuffer, src.getImage(), VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
-                dst.getImage(), VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, blitRegions, filter);
+        vkCmdBlitImage(cmdbuffer,
+                src.getImage(), ImgUtil::getVkLayout(VulkanLayout::TRANSFER_SRC),
+                dst.getImage(), ImgUtil::getVkLayout(VulkanLayout::TRANSFER_DST),
+                1, blitRegions, filter);
     }
 
-    VkImageLayout newSrcLayout = getDefaultImageLayout(src.texture->usage);
-    VkImageLayout const newDestLayout = getDefaultImageLayout(dst.texture->usage);
+    VulkanLayout newSrcLayout = ImgUtil::getDefaultLayout(src.texture->usage);
+    VulkanLayout const newDstLayout = ImgUtil::getDefaultLayout(dst.texture->usage);
 
     // In the case of blitting the depth attachment, we transition the source into GENERAL (for
     // sampling) and set the copy as ATTACHMENT_OPTIMAL (to be set as the attachment).
     if (any(src.texture->usage & TextureUsage::DEPTH_ATTACHMENT)) {
-        newSrcLayout = VK_IMAGE_LAYOUT_GENERAL;
+        newSrcLayout = VulkanLayout::DEPTH_SAMPLER;
     }
 
-    transitionImageLayout(cmdbuffer, textureTransitionHelper({
-                                             .image = src.getImage(),
-                                             .oldLayout = VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
-                                             .newLayout = newSrcLayout,
-                                             .subresources = srcRange,
-                                     }));
-
-    transitionImageLayout(cmdbuffer, textureTransitionHelper({
-                                             .image = dst.getImage(),
-                                             .oldLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
-                                             .newLayout = newDestLayout,
-                                             .subresources = dstRange,
-                                     }));
+    src.texture->transitionLayout(cmdbuffer, srcRange, newSrcLayout);
+    dst.texture->transitionLayout(cmdbuffer, dstRange, newDstLayout);
 }
 
 struct BlitterUniforms {
@@ -278,12 +261,11 @@ void VulkanBlitter::blitSlowDepth(VkImageAspectFlags aspect, VkFilter filter,
     // BEGIN RENDER PASS
     // -----------------
 
-    const VulkanDepthLayout layout =
-            fromVkImageLayout(getDefaultImageLayout(TextureUsage::DEPTH_ATTACHMENT));
+    VulkanLayout const layout = VulkanLayout::DEPTH_ATTACHMENT;
 
     const VulkanFboCache::RenderPassKey rpkey = {
         .initialColorLayoutMask = 0,
-        .initialDepthLayout = VulkanDepthLayout::UNDEFINED,
+        .initialDepthLayout = VulkanLayout::UNDEFINED,
         .renderPassDepthLayout = layout,
         .finalDepthLayout = layout,
         .depthFormat = dst.getFormat(),
@@ -377,14 +359,14 @@ void VulkanBlitter::blitSlowDepth(VkImageAspectFlags aspect, VkFilter filter,
         sampler = {
             .sampler = vksampler,
             .imageView = mContext.emptyTexture->getPrimaryImageView(),
-            .imageLayout = VK_IMAGE_LAYOUT_GENERAL
+            .imageLayout = ImgUtil::getVkLayout(VulkanLayout::READ_WRITE),
         };
     }
 
     samplers[0] = {
         .sampler = vksampler,
         .imageView = src.getImageView(VK_IMAGE_ASPECT_DEPTH_BIT),
-        .imageLayout = getDefaultImageLayout(TextureUsage::DEPTH_ATTACHMENT)
+        .imageLayout = ImgUtil::getVkLayout(VulkanLayout::DEPTH_ATTACHMENT),
     };
 
     mPipelineCache.bindSamplers(samplers,

filament/backend/src/vulkan/VulkanBuffer.cpp

@@ -74,19 +74,19 @@ void VulkanBuffer::loadFromCpu(VulkanContext& context, VulkanStagePool& stagePoo
     VkAccessFlags dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
     VkPipelineStageFlags dstStageMask = VK_PIPELINE_STAGE_TRANSFER_BIT;
     if (mUsage & VK_BUFFER_USAGE_VERTEX_BUFFER_BIT) {
-	dstAccessMask |= VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT;
-	dstStageMask |= VK_PIPELINE_STAGE_VERTEX_INPUT_BIT;
+        dstAccessMask |= VK_ACCESS_VERTEX_ATTRIBUTE_READ_BIT;
+        dstStageMask |= VK_PIPELINE_STAGE_VERTEX_INPUT_BIT;
     } else if (mUsage & VK_BUFFER_USAGE_INDEX_BUFFER_BIT) {
-	dstAccessMask |= VK_ACCESS_INDEX_READ_BIT;
-	dstStageMask |= VK_PIPELINE_STAGE_VERTEX_INPUT_BIT;
+        dstAccessMask |= VK_ACCESS_INDEX_READ_BIT;
+        dstStageMask |= VK_PIPELINE_STAGE_VERTEX_INPUT_BIT;
     } else if (mUsage & VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT) {
-	dstAccessMask |= VK_ACCESS_UNIFORM_READ_BIT;
-	// NOTE: ideally dstStageMask would include VERTEX_SHADER_BIT | FRAGMENT_SHADER_BIT, but
-	// this seems to be insufficient on Mali devices. To work around this we are using a more
-	// aggressive ALL_GRAPHICS_BIT barrier.
-	dstStageMask |= VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT;
+        dstAccessMask |= VK_ACCESS_UNIFORM_READ_BIT;
+        // NOTE: ideally dstStageMask would include VERTEX_SHADER_BIT | FRAGMENT_SHADER_BIT, but
+        // this seems to be insufficient on Mali devices. To work around this we are using a more
+        // aggressive ALL_GRAPHICS_BIT barrier.
+        dstStageMask |= VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT;
     } else if (mUsage & VK_BUFFER_USAGE_STORAGE_BUFFER_BIT) {
-	// TODO: implement me
+        // TODO: implement me
     }
 
     VkBufferMemoryBarrier barrier{

filament/backend/src/vulkan/VulkanContext.cpp

@@ -236,8 +236,8 @@ VkInstance createInstance(const char* const* ppRequiredExtensions, uint32_t requ
     if (!enabledLayers.empty()) {
         // If layers are supported, Check if VK_EXT_validation_features is supported.
         const FixedCapacityVector<VkExtensionProperties> availableExts =
-	        filament::backend::enumerate(vkEnumerateInstanceExtensionProperties,
-		        "VK_LAYER_KHRONOS_validation");
+                filament::backend::enumerate(vkEnumerateInstanceExtensionProperties,
+                        "VK_LAYER_KHRONOS_validation");
         for (const auto& extProps : availableExts) {
             if (!strcmp(extProps.extensionName, VK_EXT_VALIDATION_FEATURES_EXTENSION_NAME)) {
                 validationFeaturesSupported = true;
@@ -548,8 +548,8 @@ VkFormat VulkanAttachment::getFormat() const {
     return texture ? texture->getVkFormat() : VK_FORMAT_UNDEFINED;
 }
 
-VkImageLayout VulkanAttachment::getLayout() const {
-    return texture ? texture->getVkLayout(layer, level) : VK_IMAGE_LAYOUT_UNDEFINED;
+VulkanLayout VulkanAttachment::getLayout() const {
+    return texture ? texture->getLayout(layer, level) : VulkanLayout::UNDEFINED;
 }
 
 VkExtent2D VulkanAttachment::getExtent2D() const {
@@ -559,7 +559,27 @@ VkExtent2D VulkanAttachment::getExtent2D() const {
 
 VkImageView VulkanAttachment::getImageView(VkImageAspectFlags aspect) const {
     assert_invariant(texture);
-    return texture->getAttachmentView(level, layer, aspect);
+    return texture->getAttachmentView(getSubresourceRange(aspect));
+}
+
+VkImageSubresourceRange VulkanAttachment::getSubresourceRange(VkImageAspectFlags aspect) const {
+    assert_invariant(texture);
+    uint32_t levelCount = 1;
+    uint32_t layerCount = 1;
+    // For depth attachments, we consider all the subresource range since layout transitions of
+    // depth and stencil attachments should always be carried out for all subresources.
+    if (aspect & VK_IMAGE_ASPECT_DEPTH_BIT) {
+        auto range = texture->getPrimaryRange();
+        levelCount = range.levelCount;
+        layerCount = range.layerCount;
+    }
+    return {
+            .aspectMask = aspect,
+            .baseMipLevel = uint32_t(level),
+            .levelCount = levelCount,
+            .baseArrayLayer = uint32_t(layer),
+            .layerCount = layerCount,
+    };
 }
 
 void VulkanContext::initialize(const char* const* ppRequiredExtensions,

filament/backend/src/vulkan/VulkanContext.h

@@ -20,6 +20,7 @@
 #include "VulkanPipelineCache.h"
 #include "VulkanCommands.h"
 #include "VulkanConstants.h"
+#include "VulkanImageUtility.h"
 
 #include <utils/bitset.h>
 #include <utils/Slice.h>
@@ -41,9 +42,11 @@ struct VulkanAttachment {
     uint16_t layer = 0;
     VkImage getImage() const;
     VkFormat getFormat() const;
-    VkImageLayout getLayout() const;
+    VulkanLayout getLayout() const;
     VkExtent2D getExtent2D() const;
     VkImageView getImageView(VkImageAspectFlags aspect) const;
+    // TODO: maybe embed aspect into the attachment or texture itself.
+    VkImageSubresourceRange getSubresourceRange(VkImageAspectFlags aspect) const;
 };
 
 struct VulkanTimestamps {