- **Key Minification**: Refactored serialization to use short keys
(e.g., `p`, `c`, `w`) instead of verbose property names, reducing URL
size by ~50%.
- **State Optimization**: Removed redundant `sunDirection` from
serialized state.
- **Cleanup**: Removed backward compatibility for verbose keys
- **Bug Fix**: Fixed a regression where UI sliders failed to update on
load by ensuring array properties (e.g., `sunHalo`) are mutated
in-place rather than replaced.
DOCS_FORCE
- **State Management**:
- Refactored main.js to expose local UI parameter objects as class
properties for serialization.
- Implemented getURLState() to capture complete scene configuration
(Sky, Clouds, Water, Stars, Camera, Bloom).
- Implemented applyURLState() to restore settings and synchronize
the UI.
- **URL Sharing**:
- Added "Share Configuration" button to the UI.
- Configuration is Base64-encoded into a `config` URL query parameter.
- App now automatically parses and applies the `config` parameter
on startup, allowing for stateful deep linking.
DOCS_FORCE
* engine: add program cache
This is another chunky change.
The core of this change is to cache programs in MaterialCache according to a
"specialization" (ProgramSpecialization) which is defined as the program cache
ID (the same key used for the OpenGL binary blob cache), the variant, and the
set of spec constants.
As part of this change, a lot of the implementation details of shader
compilation were refactored from Material to MaterialDefinition. The resulting
flow is a lot cleaner and easier to reason about, since shader compilation is
now a pure function of the MaterialDefinition + ProgramSpecialization.
Since the global cache program lookups might take a bit of time to compute
hashes, etc, I left the set of cached programs in Material as well, which kind
of acts like an L1 cache. The effect is that prepareProgram() and getProgram()
should be no slower than HEAD, even with the more complex caching requirements.
I'm planning on writing a document about this (and all changes up until this
point), but I'm being asked to work on higher priority things and I wanted to
have this PR out for review in the meantime so it doesn't bitrot.
* engine: fix unit tests
* engine: fix spec constants intern pool memory leak
* engine: address program cache comments
* engine: address more program cache comments
* engine: matdbg support for program cache
* engine: reinstate descriptorLayout calls
* engine: address bitrot
* engine: add feature flag to disable program cache
* engine: use material CRC32 for program cache
The "cache ID" of a material is supposed to uniquely identify a shader program
and all its variants. This is true to a certain extent, but does not account for
the code generation that happens at runtime. Two materials may have "identical"
shader programs, but due to each material's differing unique metadata, the final
compiled programs may end up very different. Unfortunately, this means we cannot
rely on the "cache ID" alone to determine a shader program's reusability.
Ideally, we should hash this "cache ID" with the exact set of changes to each
shader program so that we could reuse programs across materials. Instead, as a
stopgap solution, use the material's CRC32 instead.
* engine: fix double-free in program cache
* engine: address comments
* engine: assert_invariant empty material cache
- we were setting the tag of the descriptor set to its layout, so
both tags were incorrect.
- added in debug build we now store the tag of the bound descriptor
sets in the current bindings structure.
This change upgrades AtlasAllocator from a simple linear allocator
(reset-only) to a full Buddy Allocator capable of both allocation and
deallocation. This enables persistent shadow map management where
individual shadow maps can be updated or resized without rebuilding the
entire atlas every frame.
Key changes:
- Implemented AtlasAllocator::free():
- Uses the existing QuadTree structure to track allocations.
- Automatically coalesces empty sibling nodes back into larger
parent blocks (standard Buddy Allocator behavior).
- Optimized to be allocation-free and recursion-free, using direct
array indexing.
- Added comprehensive unit tests
Updated documentation.
The QuadTreeArray implementation remains unchanged but is now fully
utilized for bidirectional tree traversal (down for alloc, up for free).
This change will later allow us to cache shadow-maps.
The AtlasAlocator is currently disabled by a feature flag.
In the cases where a frame takes more than the vsync
time, we start seeing some rendering artifacts because
we write to a buffer that is currently in flight.
Not 100% sure why the current approach fails but for
now, the staging buffer is bypassed only when the buffer
is not in use or referenced by any other resource.
FIXED=[445455050]
FIXED=[477305399]
- Extended Settings to include properties for Camera, Animation, Lights,
and Render options.
- Moved camera options from Viewer options to Camera options
- Implemented generic JSON parsing for these new settings in Settings.cpp.
- Updated AutomationEngine to apply these settings, including dynamic
creation of lights.
- Fixed a JSON parsing bug in AutomationSpec that failed on nested objects.
- Updated gltf_viewer to use the new settings and correctly initialize
AutomationEngine context.
- Add test for new json changes
- Add README to libs/viewer
- Link libs/viewer/README.md to official doc
- Remove unused libs/viewer/schemas
- Updated remote web assets (because the viewer/settings json needs to
match)
- **Stars**:
- Implemented procedural stars using hash-based noise.
- Added UI controls for Star Density and Enable/Disable.
- Tuned star brightness (reduced intensity) and refined twilight fade timing (visible during nautical twilight).
- Improved compositing with aggressive cloud occlusion and non-linear fade.
- Added star reflections to water, strictly masked to the horizon line.
- **Heat Shimmer**:
- Fixed horizon artifacts by decoupling shimmer from atmospheric density (Mie scattering).
- Implemented FBM-based view distortion for heat waves.
- Added sun elevation fade (shimmer fades out as sun rises > 30°).
- **Water**:
- Implemented Finite Difference normal calculation as a high-quality fallback when "Derivative Trick" is disabled.
- Added "Octaves" parameter to control wave detail.
- Refined reflection logic to handle stars and sun disk properly.
- **System**:
- Updated [simulated_skybox.mat](cci:7://file:///Users/mathias/sources/git/filament/docs_src/src_raw/wip/sky/simulated_skybox.mat:0:0-0:0) with new material parameters (`starControl`, `waterControl`).
- Refactored JS bindings in [SimulatedSkybox.js](cci:7://file:///Users/mathias/sources/git/filament/docs_src/src_raw/wip/sky/SimulatedSkybox.js:0:0-0:0) and organized `main.js` UI into logical folders.
DOCS_FORCE
PerformanceHint manager needs a java thread during initialization,
so we need to attach a jvm to the thread that's going to be used.
That thread is the filament backend thread, not necessarily the thread
the platform is created on.
So we make sure to do that from the backend thread.
FIXES=[427945768]
Currently, in Vulkan, we set the pipeline layout when binding the
pipeline, which doesn't happen until draw time when external samplers
are present. In cases like that, we push constants with the layout
VK_NULL_HANDLE, which is not valid. Instead, we can wait until the
pipeline layout is known, and then flush all push constants.
The command batching logic in RenderPass::Executor::execute calculates a
conservative `maxCommandSizeInBytes` to determine how many commands can
safely fit in the driver's circular buffer.
However, this calculation failed to account for the dynamic memory
allocation incurred by the Per-Material descriptor set binding (via
`MaterialInstance::use`). This binding allocates a `DescriptorSetOffsetArray`
in the command stream, which was unbudgeted.
In scenarios with frequent material and scissor changes, the accumulated
deficit from these unbudgeted allocations could exceed the buffer
capacity, leading to a crash.
This change:
1. Adds the missing accounting for the Per-Material dynamic allocation
to `maxCommandSizeInBytes`.
2. Adds a 20% safety margin to the calculated size to robustly handle
alignment padding and worst-case scenarios.
FIXES=[474264976]
- Add plumbing to add more information about rendertargets
(including discard flags and pass id) to the fgviewer pass
struct.
- Add UI to display information about a selected pass
- Highlight a selected resource or pass
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.
- Add documentation for specgen along with proper math rendering
- Adjust the heading size, capitalization of various READMEs.
- Add backend test README to the doc
- Rename the CI related tests to have prefix "CI:"
Introduces a new sample application demonstrating asynchronous resource
management. It shows how to asynchronously create and update Filament
resources (Textures, VertexBuffers, IndexBuffers) and provides examples
of managing chains of asynchronous operations effectively.
BUGS=[442921995]
- Pick a default view when database is filled.
- Fix d3, d3-graphviz depdency.
- reduce the size into a smaller table (to avoid scrolling)
- slant the pass items to allow smaller cells for the table.
- make subresource rendering the same as regular resource
rendering with a color hint.
- Use color-only to indicate resource/pass interaction (read,
write, read-write, no-access)
- add tooltip to indicate resource action
Right now, if a material is destroyed just after creation, it's possible
for prewarm to attempt to use destroyed shader modules. This ensures
that the resources are kept until after any queued jobs have run.
While it is likely ideal to properly cancel the prewarm if the program
has been destroyed, this seems like a rare occurrence in practice.
When an asynchronous object is destroyed immediately after creation, the
background creation process may still be active, holding a reference to
the object. We now defer destruction in these cases until the creation
process completes to ensure the reference remains valid.
Implementation details:
1. Add a mechanism to stop the ServiceThread to drain pending
asynchronous tasks earlier. This ensures the mCreationComplete flag
in the frontend object is set to true.
2. Later, the engine's terminate performs garbage collection for the
deferred destruction. All of them must be successfully processed.
BUGS=[442921995]
- Reorder the release-related documents into one heading.
- Added CocoaPods README as part of the documentation.
- Fixed typo for renderdiff doc
- Added backend test doc
Certain older compilers (e.g. clang in NDK 25.1.8937393) cannot
handle the c++ stylistic changes that were recently added
(though they are correct by spec).
- In Engine.cpp, .find() cannot automatically infer the right type
(std::string_view vs. utils::CString).
- In fg/framegraph, various templated short-hands still require
typename.
