filament/io.github.erkko68.filament/Stream

Stream

@PlatformGap(platforms = [FilamentPlatform.WEB], behavior = "setDimensions throws — FStream waits on a fence internally, which single-threaded wasm rejects; external video streams have no WebGL source anyway.")

class Stream(nativeHandle: NativePointer)

Stream is used to attach a video stream to a Filament Texture.

The Stream class is fairly platform-centric. It supports two different configurations:

NATIVE: Connects to a native OS stream (e.g., Android SurfaceTexture)
ACQUIRED: Connects to an external source (e.g., Android AHardwareBuffer)

Before explaining these different configurations, let's review the high-level structure of an AR or video application that uses Filament:

while (true) {
    // Application work: write frame data, move camera, etc.

    if (renderer.beginFrame(swapChain)) {
        renderer.render(view)
        renderer.endFrame()
    }
}

Let's say that the video image data at the time of a particular invocation of beginFrame() becomes visible to users at time A. The 3D scene state (including camera) at that same invocation becomes apparent to users at time B.

If time A matches time B, the stream is synchronized.
Filament invokes low-level graphics commands on the driver thread.
The thread that calls beginFrame() is called the main thread.

For ACQUIRED streams, Filament explicitly acquires the stream, then releases it later via a callback function. This configuration is especially useful when the Vulkan backend is enabled.

NATIVE streams are deprecated because they are backend-specific and do not make any synchronization guarantee.