* 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
* 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
* 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>
* Implement query to check if texture format is mipmappable
This will allow Filament's users to perform check beforehand.
* add java bindings
* add javascript binding
The main goal is to allow more flexibility, allow cubemap arrays in
the future and better match vk and metal apis.
Main changes:
- remove updateCubeImage
- remove update2DImage
- update3DImage is now the only texture upload backend API
cubemaps are now treated just like a 2D array of 6 layers.
For this reason, Texture::setImage(..., FaceOFfsets) is deprecated.
Additionally, the 2D versions of Texture::setImage() become inline
helpers.
A side effect of this change is that it is now possible to update only
a single face of a cubemap, but also a region of a face (or faces).
The version of Texture::setBitmap() that tool an Android bitmap handled
callbacks differently and in certain case caused a "double release" of
the callback object. This didn't actually cause problems though.
We now use the same mechanism used elsewhere (i.e. JniCallback).
Java callbacks are now directly dispatched to their handler, instead
of first going through filament's opportunistic dispatch, reducing
callback latency.
deprecate Stream::stream(intptr_t).
This method was needed for ARCore back in the days, but there is now a
zero-copy way to achieve the same thing. This API shouldn't be used anymore.
- setImage() used the width of the texture for calculating the required
user buffer size, but this was too large when only updating a
portion of the texture. It would result in a BufferOverFlowException.
- setImage3D() had the opposite problem where it didn't take into
account the depth of the texture.
- the offset in the user buffer was called "bottom" on the C++ JNI side,
but it is called "top" on the java and filament side.
Fixes#3685
Also cleanup all setImage() error reporting. All error checks are
changed from silent to NON_FATAL_ASSERT, which means they'll throw
if exceptions are enabled or do a no-op and log a message otherwise.
Also added more precondition checks.
- we were allocating objects with a destructor in the command stream
which is always invalid because there is no guarantee that when
the callback is called, the underlaying memory is still valid
(and it wasn't).
- AutoBuffer move-ctor wasn't moving some of its state, which would
lead to destroying the same ref several times.
This adds a utility function on IndirectLight populate the reflection
map from an environment at runtime. This performs some processing
similar to cmgen, albeit at a reduced quality.
No need for a proper library, this is just a common location to simplify
JNI bindings in other projects like filamat and gltfio.
There is no need to move the one Java source file (`NioUtils.java`)
since downstream libraries will have a dependency on Filament, and
FindClass should work fine.
In this first step, we just "blindly" move everything under src/driver
to a new library libbackend.a. And all headers are moved under
private/backend.
Note that "driver" is renamed "backend", but namespaces are unchanged for now.
Later we'll have to untangle the actual private headers from public
ones and ideally not have any private headers.
Amazingly, the size field in PixelBufferDescriptor was often totally
incorrect for Java-based clients. The reason we did not notice: OpenGL
often consumes a pointer to image data without consuming a byte count
(e.g. glTexImage2D).
OpenGL infers size from dimensions + format, but Vulkan does not. This
caused texture corruption with Vulkan on Android.
This fix follows a pattern used in other places such as
FRenderer::readPixels.
* WIP Add helper to upload Android bitmaps to textures
* Add missing file
* Pass custom constants for bitmap formats
* Add sample app for texturing
* Update the README for samples
* Rename variable from callback to autoBitmap
This change will allow the skybox use a compressed texture format.
For now, the old internal format "RGBM" is still honored, but in a
forthcoming change we will replace the enum with UNUSED.
Mathias Agopian
Konstantin Sakhin
Romain Guy
Pixelflinger
Philip Rideout
Romain Guy