Package com.google.android.filament

Class Stream

  • public class Stream
extends java.lang.Object
    Stream is used to attach a native video stream to a filament Texture. Stream supports three different configurations:
    ACQUIRED
    connects to an Android AHardwareBuffer
    NATIVE
    connects to an Android SurfaceTexture

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

     while (true) {

     // Misc application work occurs here, such as:
     // - Writing the image data for a video frame into a Stream
     // - Moving the Filament Camera

     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 the camera) at the time of that same invocation becomes apparent to users at time B.

    • If time A matches time B, we say that 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, there is no need to perform the copy because Filament explictly acquires the stream, then releases it later via a callback function. This configuration is especially useful when the Vulkan backend is enabled.

    For NATIVE streams, Filament does not make any synchronization guarantee. However they are simple to use and do not incur a copy. These are often appropriate in video applications.

    Please see sample-stream-test and sample-hello-camera for usage examples.

    See Also:
    Texture.setExternalStream(com.google.android.filament.Engine, com.google.android.filament.Stream), Engine.destroyStream(com.google.android.filament.Stream)

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Stream.Builder
      Use Builder to construct an Stream object instance.
      static class  Stream.StreamType
      Represents the immutable stream type.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      long getNativeObject()  
      Stream.StreamType getStreamType()
      Indicates whether this Stream is NATIVE or ACQUIRED.
      long getTimestamp()
      Returns the presentation time of the currently displayed frame in nanosecond.
      void setAcquiredImage​(java.lang.Object hwbuffer, java.lang.Object handler, java.lang.Runnable callback)
      Updates an
      void setDimensions​(int width, int height)
      Updates the size of the incoming stream.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • getStreamType

        public Stream.StreamType getStreamType()
        Indicates whether this Stream is NATIVE or ACQUIRED.

      • setAcquiredImage

        public void setAcquiredImage​(java.lang.Object hwbuffer,
                             java.lang.Object handler,
                             java.lang.Runnable callback)
        Updates an 
        ACQUIRED
        stream with an image that is guaranteed to be used in the next frame. This method tells Filament to immediately "acquire" the image and trigger a callback when it is done with it. This should be called by the user outside of beginFrame / endFrame, and should be called only once per frame. If the user pushes images to the same stream multiple times in a single frame, only the final image is honored, but all callbacks are invoked. This method should be called on the same thread that calls Renderer.beginFrame(com.google.android.filament.SwapChain, long), which is also where the callback is invoked. This method can only be used for streams that were constructed without calling the Builder.stream method. See Stream for more information about NATIVE and ACQUIRED configurations.
        Parameters:
        hwbuffer - HardwareBuffer (requires API level 26)
        handler - Executor or Handler.
        callback - a callback invoked by handler when the hwbuffer can be released.

      • setDimensions

        public void setDimensions​(@IntRange(from=0L)
                          int width,
                          @IntRange(from=0L)
                          int height)
        Updates the size of the incoming stream. Whether this value is used is stream dependent. On Android, it must be set when using Builder#stream(long)
        Parameters:
        width - new width of the incoming stream
        height - new height of the incoming stream

      • getTimestamp

        public long getTimestamp()
        Returns the presentation time of the currently displayed frame in nanosecond. This value can change at any time.
        Returns:
        timestamp in nanosecond.

      • getNativeObject

        public long getNativeObject()