Package 

Class SwapChain

  • 
public class SwapChain

    A SwapChain represents an Operating System's native renderable surface.

    Typically it's a native window or a view. Because a SwapChain is initialized from a native object, it is given to filament as an Object, which must be of the proper type for each platform filament is running on.

    SwapChain swapChain = engine.createSwapChain(nativeWindow);

    The nativeWindow parameter above must be of type:

    ExamplesAndroid

    A Surface can be retrieved from a SurfaceView or SurfaceHolder easily using SurfaceHolder.getSurface() and/or SurfaceView.getHolder().

    To use a Textureview as a SwapChain, it is necessary to first get its SurfaceTexture, for instance using SurfaceTextureListener and then create a Surface:

     // using a TextureView.SurfaceTextureListener:
 public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int width, int height) {
     mSurface = new Surface(surfaceTexture);
     // mSurface can now be used with Engine.createSwapChain()
 }

    • Method Detail

      • isProtectedContentSupported

         static boolean isProtectedContentSupported(@NonNull() Engine engine)

        Return whether createSwapChain supports the CONFIG_PROTECTED_CONTENT flag.The default implementation returns false.

        Parameters:
        engine - A reference to the filament Engine

      • isSRGBSwapChainSupported

         static boolean isSRGBSwapChainSupported(@NonNull() Engine engine)

        Return whether createSwapChain supports the CONFIG_SRGB_COLORSPACE flag.The default implementation returns false.

        Parameters:
        engine - A reference to the filament Engine

      • isMSAASwapChainSupported

         static boolean isMSAASwapChainSupported(@NonNull() Engine engine, int samples)

        Return whether createSwapChain supports the CONFIG_MSAA_*_SAMPLES flag.The default implementation returns false.

        Parameters:
        engine - A reference to the filament Engine
        samples - The number of samples

      • setFrameCompletedCallback

         void setFrameCompletedCallback(@NonNull() Object handler, @NonNull() Runnable callback)

        FrameCompletedCallback is a callback function that notifies an application when a frame'scontents have completed rendering on the GPU.

        Use setFrameCompletedCallback to set a callback on an individual SwapChain. Each time a framecompletes GPU rendering, the callback will be called.

        Warning: Only Filament's Metal backend supports frame callbacks. Other backends ignore thecallback (which will never be called) and proceed normally.

        Parameters:
        handler - A Executor.
        callback - The Runnable callback to invoke.

      • setFrameScheduledCallback

         void setFrameScheduledCallback(@NonNull() Object handler, @NonNull() Runnable callback)

        FrameScheduledCallback is a callback function that notifies an application about the statusof a frame after Filament has finished its processing.

        The exact timing and semantics of this callback differ depending on the graphics backend inuse.

        Metal Backend

        With the Metal backend, this callback signifies that Filament has completed all CPU-sideprocessing for a frame and the frame is ready to be scheduled for presentation.

        Typically, Filament is responsible for scheduling the frame's presentation to the SwapChain.If a FrameScheduledCallback is set, however, the application bears the responsibility ofscheduling the frame for presentation by calling the PresentCallable passed to the callbackfunction. In this mode, Filament will not automatically schedule the frame for presentation.

        When using the Metal backend, if your application delays the call to the PresentCallable(e.g., by invoking it on a separate thread), you must ensure all PresentCallables have beencalled before shutting down the Filament Engine. You can guarantee this by callingEngine.flushAndWait() before Engine.shutdown(). This is necessary to ensure the Engine hasa chance to clean up all memory related to frame presentation.

        Other Backends (OpenGL, Vulkan, WebGPU)

        On other backends, this callback serves as a notification that Filament has completed allCPU-side processing for a frame. Filament proceeds with its normal presentation logicautomatically, and the PresentCallable passed to the callback is a no-op that can be safelyignored.

        General Behavior

        A FrameScheduledCallback can be set on an individual SwapChain throughsetFrameScheduledCallback. Each SwapChain can have only one callback set per frame. IfsetFrameScheduledCallback is called multiple times on the same SwapChain beforeRenderer.endFrame(), the most recent call effectively overwrites any previously set callback.

        The callback set by setFrameScheduledCallback is "latched" when Renderer.endFrame() isexecuted. At this point, the callback is fixed for the frame that was just encoded.Subsequent calls to setFrameScheduledCallback after endFrame() will apply to the next frame.

        Use setFrameScheduledCallback() (with default arguments) to unset the callback.

        Parameters:
        handler - A Executor.
        callback - The Runnable callback to invoke when frame processing is complete.

      • isFrameScheduledCallbackSet

         boolean isFrameScheduledCallbackSet()

        Returns whether this SwapChain currently has a FrameScheduledCallback set.