RELEASE_NOTES.md
This file contains one line summaries of commits that are worthy of mentioning in release notes. A new header is inserted each time a tag is created.
Do not edit this file unless you are performing a release or cherry-picking into an rc/ branch. Instead, if you are authoring a PR for the main branch, add your release note to NEW_RELEASE_NOTES.md.
KHR_materials_dispersion extension, which adds dispersion for refractive objectssetPresentationTime with the Metal backend.View::getLastDynamicResolutionScale() (b/457753622)debugUpdateStat (b/431665753).SwapChain::CONFIG_MSAA_4_SAMPLES flag.setFrameScheduledCallback now works on all backends (frame presentation scheduling is still only
available on Metal). Non-Metal backends can use the callback to be notified when Filament has
finished processing a frame on the CPU.getEyeFromViewMatrix() for vertex shader [⚠️ Recompile Materials]--workarounds=none the default [Recompile Materials to take effect]lighting: the intermediate froxel record buffer is now dynamically sized [⚠️ New Material Version]
linearFog material parameter. [⚠️ New Material Version]Material::compile() is called on a platform which doesn't support parallel compilation, shaders are automatically compiled over a number of framesuseDefaultDepthVariant material parameter to force Filament to use its default variant for
depth-only passes. [Requires recompiling materials]LOW_QUALITY mode. [Requires recompiling materials] to take effect.sampler parameter unfilterable to filterable [⚠️ New Material Version]Renderer::shouldRenderFrame()Texture::generatePrefilterMipmap, a new libfilament-generatePrefilterMipmap library can be used in its stead [⚠️ API BREAKAGE]VARIANT_DEPTH, defined when a material is compiled for depth variants
(e.g., shadows) [Requires recompiling materials]unfilterable field to Filament Material's sampler [⚠️ New Material Version]color attribute is not requested (b/404930099). [⚠️ New Material Version]transformName field to sampler material parameters. [⚠️ New Material Version]fix crash: the 'target_node' of Animation Channel may be nullpointer.
name API to Filament objects for debugging handle use-after-free assertionsstereoscopicType material parameter. [⚠️ New Material Version]getEyeIndex vertex APIGL_TEXTURE_EXTERNAL_OES textures.setFrameScheduledCallback now takes a utils::Invocable.isPaused()GL_TEXTURE_EXTERNAL_OES textures.Engine::builder::paused() and Engine::setPaused()SwapChain::getFrameScheduledCallbackatan2 overload which had a typo and wasn't useful. Fixes b/320856413.SpinLock. Fixes b/321101014.-1 to disable generation of ESSL 1.0 code in Feature Level 0 materialsEngine::Config::stereoscopicEyeCount. [⚠️ Recompile Materials]Engine::Builder::featureLevelGL_OES_standard_derivatives extension in ESSL 1.0 shadersMaterial::getFeatureLevel()Material::getReflectionMode() method in JavaFILAMENT_ENABLE_FEATURE_LEVEL_0 build-time option optionally allow building Filament
without FL0 support.AgXTonemapper.Renderer::getClearOptions() [b/243846268]BloomOptions::anamorphism which wasn't working well in most cases [API CHANGE]emissive property was not applied properly to MASKED materials, and could cause
dark fringes to appear (recompile materials)MASKEDEXC_BAD_ACCESS with Metal backend: b/297059776setFrameCompletedCallback now takes a backend::CallbackHandler.Engine::isValid)setDepthFunc for MaterialInstancevariant-filter flagMaterial::compile() when a callback is specifiedgetMaxAutomaticInstances() API on Engine to get max supported automatic instances.TextureView is resized (fixes b\282220665)Material::compile API.Platform blob cache APIs, typically used to cache programs [⚠️ Recompile materials]OpenGLPlatform to preserve ancillary buffersvec4 visible by all materials [⚠️ Recompile Materials]matc -S) [⚠️ Recompile Materials]unlit materials [⚠️ Recompile Materials].getUserWorldFromWorldMatrix() and getUserWorldPosition() to retrieve the
API-level (user) world position in materials. Deprecated getWorldOffset(). [⚠️ Recompile
Materials]shading_view in large scenesResourceLoader::addResourceData.SwapChain.hColorGrading. This API currently has limitations,
please refer to the documentation for more detailsEngine.destroygetNormalizedViewportCoord() now returns the logical (i.e. user) viewport
normalized position and keeps z reversed [⚠️ Recompile Materials]MaterialInstanceColorGrading JS bindingsCullingMode::FRONT_AND_BACK are now skipped.FilamentInstance [⚠️ API Change]FilamentInstance [⚠️ API Change]Engine::resetBackendState(), available only in WebGL buildsrecomputeBoundingBoxes [⚠️ API Change]Engine::getSupportedFeatureLevel()View and stencil state APIs to MaterialInstance [NEW API].vertexDomain:Device [⚠️ Recompile Materials]clipSpaceTransform is now only available with vertexDomain:Device [⚠️ API Change]AssetLoader::createAsset() method [⚠️ API Change]CONFIG_MINSPEC_UBO_SIZE as a nicer way to allow exceeding the ES3.0 minspec.MaterialInstance public API friendly to std::string_view parametersCamera::getNear() and Camera::getCullingFar() now return doublesRenderer::getUserTime() now returns seconds as documented (#5722) [⚠️ API Fix]Engine::setAutomaticInstancingEnabled(bool)MTLTexture formatting when importing external textures.instanced material parameter that is now mandatory in order to call getInstanceIndex()RenderPrimitives together.ResourceAllocator performance a bit by reserving 128 cache entries.std::hash<T> definitions for libutils types. Use T::Hasher explicitly instead. [⚠️ API Change]attachSkin / detachSkin method to FilamentAsset.OPAQUE.blendOrder.RenderManager::setGeometryAt(index, count). [⚠️ API Change]ssctStartTraceDistance to ssctShadowDistance. [⚠️ API Change]blendingMode to blendMode. [⚠️ API Change]half floating-point arithmetic when possible for improved performance. [⚠️ Recompile Materials]RendererisTextureFormatSupported for ETC2 formats.KTXLoader Kotlin class to KTX1Loader. [⚠️ API Change].Ktx2Reader and BasisEncoder to support Basis-encoded KTX2 files.Stream APIs, see Texture::import() for an alternative [⚠️ API Change].resetBoneMatrices() method.TextureProvider interface. [⚠️ API Change].FilamentAsset.Viewport::scale() [⚠️ API Change].MorphTargetBuffer.SwapChain.bluegl on all platforms.FilamentAsset.math::quat::fromDirectedRotation [NEW API].Stream::SetAcquiredImage is ignored and leaked.Scene::forEach API to iterate through a scene's entities.FilamentViewers.readPixels when dimensions are greater than the render target's.libibl on mobile.Engine#destroySkinningBuffer method.RenderTarget without depth attachment.readPixels on a SwapChain must be called within beginFrame / endFrame [⚠️ API
Change].com.google.android.filament.xxx
where xxx is the property name. See android/build.gradle for a complete list [⚠️]filament_tools_dir (now called
com.google.android.filament.tools-dir) does not have a default value anymore. Please specify one
in your gradle.properties if you reuse the Gradle plugin in your projects [⚠️]SurfaceOrientation functions.MultiSampleAntiAliasingOptions and HDR-aware MSAA resolve. When customResolve
is enabled, improves anti-aliasing quality [NEW API].CallbackHandler*, a new
interface that provides more flexibility around callback dispatch [NEW API].DepthOfFieldOptions.View [⚠️ Materials need to be rebuilt to access this new feature].Engine::pumpMessageQueues() method can be used to trigger all pending user
callbacks right away [NEW API].{Pixel}BufferDescriptor.readPixels.readPixels.endFrame.filament-utils-android 'lite' flavor.IBLPrefilter.endFrame that caused stuttering on some Android
devices.ColorGrading. This API can be used to create an effect that
that simulates color and brightness shifts in human vision in low-light conditions.MEDIUM, HIGH and ULTRA now all use AMD FidelityFX FSR1.ColorGrading to enable or disable gamut mapping at will [New API].double precision translation support in TransformManager. Disabled by default.
Augment model (and view) matrix on Camera to accept double precision matrices. When enabled,
double precision translations allow filament to handle a very large world space [New API].inverseTonemap API is now an exact inverse of the Filmic tonemapper.ColorGrading::Builder::toneMapper(const ToneMapper*).GenericToneMapper, a configurable tone mapper.ColorGrading::Builder::toneMapping(ColorGrading::ToneMapping) is now deprecated.REINHARD tonemap operator[⚠️ API Change].SkinningBuffer API allows bone sharing between
renderables.transparentShadow : true in the material file.SamplerPrecision
to ParameterPrecicion. [⚠️ API Change]KHR_materials_volume.RenderTarget java bindings.TextureFormat::DEPTH24_STENCIL8 now maps to a 32 bit depth format on iOS.getAssetAPI to FilamentInstance.Backend::DEFAULT now selects the most appropriate backend for the platform, rather than
always OPENGL. On Android the default is OPENGL, on Apple platforms the default is METAL and
on all other platforms that default is VULKAN.BindingType TypeScript definition.debug.filament.backend system property to select the desired backend.LightManager::getFalloff.KHR_materials_ior.IBLPrefilterContext.KTXLoader.getSphericalHarmonics JNI bindinggetPlatform API to Engine.LightManager.MaterialInstance.populateTangentQuaternions [⚠️ API change].Stream::Builder::stream(intptr_t) [⚠️ API Change].Camera::setScaling, Engine::destroy(Camera*),
Engine::createCamera, Renderer::beginFrame(SwapChain*, uint64_t, backend::FrameScheduledCallback, void*), and View::setShadowsEnabled [⚠️ API Change].focusDistance from View::BloomOptions [⚠️ API Change].FILAMENT_SUPPORTS_OPENGL CMake option to enable/disable OpenGL support.Texture::Builder::import().EVILS (name will most likely change).LightManager.getIntensity.libiblprefilter.quality property.Engine::getEntityManager().libgeometry).iblprefilter library to compute IBL pre-integration on the GPU using filament.getNormalizedViewportCoord.Renderer::renderStandaloneView() is a new method that can be used outside of
beginFrame/endFrame on Views that have a RenderTarget associated. This can be used as a
pseudo-compute API.TransformManager.getParent(int).<canvas> elements.shadowMultiplier.Camera to translate the viewport and emulate a tilt/shift lens.Camera::setCustomProjection() now allows to set a different projection for culling and rendering.SimpleViewer now exposes more rendering parameters, including ColorGrading.gltfio: Add ResourceLoader evict API. gltfio: Fix ResourceLoader cache bug. iOS: Disable exceptions to reduce binary size.
getVertexIndex() API for vertex shaders.-l flag to build universal binaries.sheenColor and sheenRoughness properties to materials to create cloth/fabric.libfilamat is now multi-threaded.MaterialBuilder::build() now expects a reference to a JobSystem to multi-thread shaders
generation. A JobSystem can be obtained with Engine::getJobSystem() when using Filament,
or created directly otherwise. (⚠️ API change)KHR_materials_sheen.highlight for setBloomOptions in JavaScript.View::setViewport frequently.libibl_lite library.EXC_BAD_INSTRUCTION seen when using headless SwapChains on macOS with OpenGL.SwapChain.Skybox material size.UiHelper now supports managing a SurfaceHolderFIndirectLightShadowOptions control to render Variance Shadow Maps (VSM) with MSAA (experimental)CoroutineScope job should be canceled before destroyMASKED mode now leaves destination alpha intact (useful for transparent targets).MASKED mode now benefit from smoothing in unlit materials.KHR_materials_transmission to use the FADE blending mode.View.setTemporalAntiAliasingOptions().Skybox and IndirectLight (C++, Java, JavaScript).View.setAmbientOcclusion() is deprecated in favor of View.setAmbientOcclusionOptions
(⚠️ API change).Engine asynchronously.Texture::setImage().View::setVisibleLayers().View::setToneMapping is deprecated, use View::setColorGrading instead. (⚠️ API change)BufferDescriptor and PixelBufferDescriptors not being called on
the application thread.getNormalizedViewportCoord shader API.Entities.Camera entity leaks.CreateEliminateDeadMembersPass, which broke UBO layout.flushAndWait().gltfio: AssetLoader now loads names for mesh-free nodesgltfio: Material names are now preserved in ubershader modeMaterialBuilder from Java.MaterialBuilder::refractionMode().
and MaterialBuilder::refractionType() instad of materialRefraction() and
materialRefractionType() (️⚠️ API change).beginFrame() now accepts a v-sync timestamp for accurate frame time measurement (used for
frame skipping and dynamic resolution). You can pass 0 to get the old behavior (⚠️ API change).View::setClearColor(), a similar functionality is now handled by Renderer::setClearOptions()
and Skybox, the later now can be set to a constant color (⚠️ API breakage).intensityCandela and setIntensityCandela API to LightManager for setting a punctual
light's intensity in candela.ShadowOptions were not being respected when passed to
LightManager::Builder.filament-utils library.⚠️ This release breaks compiled materials, use matc to recompile.
filament-utils library with TextureLoader, ModelViewer, and Java bindings for camutils.setMediaOverlay API to UiHelper for controlling surface ordering.TransformManager.<iostream> from math headers.SAMPLER_EXTERNAL texture before setting an external image no longer results in GPU errors.roughness = 1 instead of Spherical HarmonicsMaterialInstance.Camera::setExposure.Camera::setExposure(float) to directly control the camera's exposure.RenderTarget class.CVPixelBuffer external images with the OpenGL backend.gltf_bloom Android sample to show gltfio and the RenderTarget API.getMaterialInstanceAt to the Java version of RenderableManager..mat files.RGB_11_11_10RGBM (warning: source compatibility breakage)Texture::generatePrefilterMipmap can be used for runtime generation of a reflection cubemapScene.addEntities() to the Java / Kotlin bindings.RenderTarget API that allows View to reference an offscreen render target.lucy_bloom sample to demonstrate the new RenderTarget API.multiply and screencurvatureToRoughness has been replaced with specularAntiAliasing.
This new specular anti-aliasing solution offers more control via two new properties:
specularAntiAliasingVariance and specularAntiAliasingThreshold. They can also be set on
material instances if neededspecularAmbientOcclusion property in materials)multiBounceAmbientOcclusion property in materials)filamat binary size by removing reliance on stdlib.filamat library, filamat_lite. Material optimization and
compiling for non-OpenGL backends have been removed in favor of a smaller binary size.SurfaceOrientation robustness when using UVs to generate tangents.RELEASE_NOTES.md file, to be updated with significant PRs.