* Implement grid-based world origin snapping in View
Implement a grid-based world origin snapping system in View to avoid
per-frame transform updates in the future. This will allow to
improve CPU performance and to enable future caching of acceleration
structures like BVH.
The feature is protected by the 'view.enable_grid_based_world_origin'
feature flag. The grid size can be set
manually via View::setGridSize or calculated automatically as 10%
of the camera's far plane distance.
A 50% hysteresis ratio is applied to prevent rapid origin flipping
near grid edges.
Exposed the new API to Java and JavaScript bindings and added
unit tests in filament_test.cpp.
BUGS=[504726278]
* Refine grid-based world origin snapping implementation
Refine the grid-based world origin snapping in View with several
improvements:
1. Support Orthographic Projections:
Calculate automatic grid size using projection matrix elements,
working for both perspective and ortho without assuming positive
near plane.
2. Stable Automatic Grid Size:
Only update effective grid size when a position snap occurs.
This prevents instability when frustum scale changes smoothly.
3. Immediate Manual Override:
Force an immediate snap when user manually changes grid size.
Added test cases for ortho and auto-grid size in filament_test.cpp.
* Filament Error Handling Remediation and noexcept Cleanup
- Replaced assert_invariant with FILAMENT_CHECK_PRECONDITION in
Renderer::beginFrame for caller bugs.
- Removed noexcept from Camera::setCustomProjection to allow precondition
checks to throw.
- Removed noexcept from Texture and InstanceBuffer methods using precondition
checks.
- Documented silent clamping in View::setBloomOptions.
- Clarified comment in FrameGraphResources regarding preconditions.
- Refined MaterialInstance::commit to split texture loop into check and update
passes, preventing partial state changes on precondition failure.
* backend: Propagate backend thread exceptions to the main thread.
Introduce a mechanism to catch exceptions thrown on the backend thread and
rethrow them on the main thread. This prevents deadlocks and allows the
application to handle fatal backend failures gracefully.
- Consolidate synchronization primitives in DriverBase.
- Add mHasUnrecoverableError flag to interrupt blocked fence waits.
- Optimize waitForFence to avoid extra atomic reads in common paths.
- Propagate FenceStatus::ERROR across all backends.
- CommandBufferQueue now stores a std::exception_ptr when the backend fails.
- The backend enters a "zombie" state on failure, skipping further command
execution but allowing clean shutdown.
- Public APIs in Renderer and Engine now check for stored exceptions and
rethrow them, documented with @throws.
- Guarded by __EXCEPTIONS to ensure no overhead when exceptions are disabled.
- Add unit test for fence interruption and document new APIs.
BUGS=[407545700]
* feat: harden backend exceptions and add hasUnrecoverableFailure API
- Update Renderer::beginFrame() and Renderer::shouldRenderFrame() to
return false early if an unrecoverable backend exception has been
delivered to the main thread.
- Document the new return behavior for beginFrame() and
shouldRenderFrame() in Renderer.h.
- Add Engine::hasUnrecoverableFailure() to the public API to allow
apps to check for fatal errors without relying on exceptions.
- Implement hasUnrecoverableFailure() in FEngine by delegating to
CommandBufferQueue.
- Expose Engine::hasUnrecoverableFailure() to Java bindings
(Engine.java and JNI).
- Expose Engine::hasUnrecoverableFailure() to JavaScript bindings
(jsbindings.cpp).
* java: propagate C++ Panics & exceptions to JAVA
Implemented the custom 3D LUT feature in the ColorGrading API, allowing
users to specify a custom LUT for final color mapping.
To test this feature, added a "Custom LUT" option to the color grading
settings in the gltf_viewer sample. This includes several procedurally
generated LUTs for testing purposes:
- Negative
- Grayscale
- Sepia
- Teal and Orange
Updated settings serialization (Settings.cpp) and the viewer UI
(ViewerGui.cpp) to support these options.
FIXES=[362596936]
* a new tribool type in libutils (header only)
* Support `Engine::compile` overload to generate view-dependent variants
Implemented an `Engine::compile()` method to infer and generate shader
permutations directly based on feature states from a provided `View`
alongside `tribool` settings (skinning, shadowReceiver).
- Added a new `Material::compile()` overload that directly accepts
a precalculated `FixedCapacityVector<Variant>`, decoupling the
Material compilation process from specific feature flag checks.
FIXES=[468058969]
* fp32 texture formats are not necessarily filterable
Mobile devices don't always support filtering of fp32 textures.
This PR adds a query at the driver level.
High precision EVSM is now conditional to this feature being supported.
* use MTLDevice supports32BitFloatFiltering if available
- refactoring/clecanup to make some changes easier
- VSM mipmap generation was mistakenly disable when blur radius was 0
- analytic variance was disabled because the math only worked for VSM. Fixed the math.
- better handling of large blurs when using fp32
- implement EVSM equivalent of receiver plane normal bias
- use correct EVSM clearing color
- mipmapping with point lights works much better (no seams)
- min variance is computed automatically
- custom high precision mipmaping shader for VSM
* implement some missing javascript bindings
DOCS_FORCE
* use exclusively javadoc comments in Options.h
This is because this file is currently used to generate java and
javascript bindings and doxygen can ingest javadoc.
And regenerate javascript and java bindings
* add missing java bindings
The new tone mapper, dubbed "GT7" in the code, is based on
the Gran Turismo 7 tone mapper, as described in the SIGGRAPH
2025 presentation called "Driving Toward Reality: Physically
Based Tone Mapping and Perceptual Fidelity in Gran Turismo 7".
This tone mapper exhibits fewer hue skews than the other tone
mappers, at the exception of PBR Neutral. The GT7 tone mapper
is however better at preserving the perception of high
dynamic range.
The tone mapper, as implemented, targets an SDR paper white
of 250 nits, using 100 cd/m^2 as the reference luminance (for
values of 1.0 in the linear HDR framebuffer). This can result
in an overall darker image compared to the other tone mappers
but this can be controlled through camera settings, post-
processing exposure, or lighting intensity.
The GT7 tone mapper also allows to target HDR output, and
could be made customizable via APIs if desired. The current
implementation offers a fixed aesthetic solution.
This commit introduces a significant rework of the Temporal Anti-Aliasing (TAA) system, focusing on improving reconstruction quality, robustness, and introducing flexible upscaling.
Core TAA Algorithm improvements:
- Replaced the Catmull-Rom filter with a more efficient 5-tap Lanczos filter for history sampling, which includes deringing to reduce artifacts.
- The input color buffer is now properly "unjittered" using a Lanczos reconstruction filter.
- Improved the history rejection algorithm by skipping the expensive accurate clipping when the history sample is already within the neighborhood's color gamut.
- Added a new `hdr` option to properly handle HDR content by tonemapping colors before blending and untonemapping the result.
- Removed the ineffective `VARIANCE` only history rejection method.
- Added protection against negative numbers in `sqrt()` for increased stability.
TAA Upscaling:
- Replaced the boolean `upscaling` flag with a float factor, allowing for variable upscaling ratios (e.g., 1.5x, 2x).
- Upscaling now correctly adjusts viewport and projection settings.
- The TAA shader now receives viewport and resolution information to correctly handle upscaled rendering.
API and Configuration Changes:
- Deprecated the `filterWidth` TAA option as it no longer has an effect.
- Introduced the `upscaling` float property to `TemporalAntiAliasingOptions`.
- Added the `hdr` boolean property to `TemporalAntiAliasingOptions`.
Other Changes:
- Updated UI elements in the viewer and material sandbox to reflect the new TAA options.
- Updated Javascript bindings and TypeScript definitions for the new TAA settings.
- Refactored shader code for clarity and performance.
* add support for AHardwareBuffer to the java bindings
Texture.setEXternalIamge() now can take a AHArdwreBuffer Java object
as a parameter.
* add an API to set the priority of the Skybox
by default the skybox is always drawn last (priority 7) in order to
reduce overdraw. however, when depth culling is not enabled, it
needs to be drawn first. The new Builder::priority() allows to set
an arbitrary priority for the skybox.
* add rendertarget support for external textures
This was in fact mostly already supported, we just were artificially
preventing that usage. It is supported by the EGL_external_image
extension.
It's the responsibility of the caller/user to not attempt to use an
incompatible format, which has undefined behavior.
FIXES=[466395306]
* add a new android sample to test the AHardwareBuffer as render target
---------
Co-authored-by: Powei Feng <powei@google.com>
* Add new public API to query a sampler transform name field.
This new API will let filament users query a Material object
the value of the `transformName` field of a specified sampler
parameter.
The transformName is an optional field, so if its not defined
by the user, it will return a nullptr value.
- A new test was added to test_filamat to validate the serialization.
- A new parameter was added to the test sandboxLit material to
validate the parsing a material with the new field.
* Addressing review comments
- Add java and js bindings for the new API
- Tests for querying the getParameterTransformName
* Use utils::ImmutableCString for transformName
* Updating release notes
* Review comments
* Addressing more review comments
- Fix comments
- For the java binding return an empty string when the
transform is not present.
* Add a Renderer API to force skipping frames
Renderer::skipNextFrames(size_t) can be used to force filament to
pretend the next N frames must be skipped. This is mostly useful for
debugging.
* Add DebugOptions to Settings
We still need to move the "Debug" features of gltf_viewer to this,
but this give us a framework to do it.
Currently there is one debug option that allows to set a number of
frames to skip.
ViewerGui propose a button to skip 10 frames using this framework
* Update libs/viewer/src/Settings.cpp
Co-authored-by: Powei Feng <powei@google.com>
* Update libs/viewer/src/Settings.cpp
Co-authored-by: Powei Feng <powei@google.com>
---------
Co-authored-by: Powei Feng <powei@google.com>
Users can now create a swapchain with MSAA support, which enables direct
rendering to a multi-sampled swapchain image and automatic resolution.
This is only supported by EGL(Android). Other GL platforms (GLX, WGL,
etc) don't support it because the swapchain MSAA settings must be
configured before window creation.
Support for other backends will follow.
BUGS=[433327615]
A few bugs in that area were introduced by #8391. Upscaling is
supposed to perform the final blending if needed, but it didn't.
Transparency/blending is only supported by the bilinear upscaler, which
is automatically selected in that case.
The upscaling pass itself may include a final `RCAS` pass for
sharpening, in that case, blending must be performed then. So we added
the logic for that.
Fixes#9061
- use resgen to package the DFG LUT into filament, instead of using
a large include of a C array.
- add a zstd compression step, which reduces the size from ~100KB to
~75KB.
The overhead of zstd is about 90KB uncompressed, however it will pay
for itself tenfold when we use it to compress material packages.
The new `linearFog` material property, when set to `true` enables a
simplified fog calculation. The fog equation becomes linear which is
unrealistic, but more efficient to compute. In some situations with
a shallow fog range, it doesn't make a huge difference visually.
In this mode, height falloff and in-scattering are ignored.
The linear equation slope is calculated from the regular parameters to
match the slope of the real equation at a camera height. If
`heightFalloff` is disabled, set to 0, the `density` parameter
exactly corresponds to the slope of the equation in [1/m] units.
* gl: amortize shader compilation over N frames
On platforms which don't support parallel shader compilation (e.g. Firefox), we
can sort of emulate it by queueing up any requests to `Material::compile()` and
compiling each shader over multiple frames.
Compiling over consecutive frames slows things quite noticeably. Instead, space
each compilation over a number of ticks (16 chosen arbitrarily).
If we need a program NOW, we can bump a program queued for much later to the
front. We also avoid compiling any queued programs on this same frame to limit
stuttering.
* gl: add flag to disable amortized shader compile
If this flag is on, the new amortized compile code should theoretically never be
executed.
* gl: add CompilerPriorityQueue docs, Java API
* gl: amortize shaders, z3moon feedback
* gl: update CompilerThreadPool
* materials: introduce mutable spec constants
Rationale & design of this feature has been discussed internally.
The current implementation uses a `FixedCapacityVector` to store the new program
handles, but I wouldn't object to replacing it with a hasmap as discussed
offline.
I have compiled but not tested this yet on Android, so I'm not certain that the
API bindings are correctly wired up.
* materials: mutable spec constant feedback
* materials: address mutable spec constant comments
* Add GTAO options into the struct
* Add gtao mat and shader
* Set type specific parameters in ppm
* Fix inconsistent name
* Fix incorrect param type
* Add bent normal calculation
* Fix the gui
* Adjust precision
* Use mix
* Add some comments
* Refactoring
* Update comments
* Add comments for aoOptions
* Update
* Update
* Address the comments
* Split .mat into bent and non-bent
* Update
* Update
* Use sqrt on mobile
* Omit default case
* Commit beamsplitter generated changes
* Use built-in acosFast
* Remove unused function
* Fix the mismatched parameter type
* Some optimizations
* Commit beamsplitter results
* Update the comment
* Update default value
* Commit beamsplitter changes
* Extract common parameters out
This introduces two new methods to `ToneMapper`: `isOneDimensional()` and
`isLDR()`. `ColorGrading` references these values along with other parameters
passed to the builder to determine if we can get away with only generating a
one-dimensional LUT. Meanwhile, `PostProcessManager` takes care of setting the
new spec constants and uniforms for `colorGrading.mat` and
`colorGradingAsSubpass.mat`.
