Package 

Class Stream

  • 
public class Stream

    Stream is used to attach a native video stream to a filament Texture. Stream supports three different configurations:

    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.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      public enum Stream.StreamType

      Represents the immutable stream type.
      public class Stream.Builder

      Use Builder to construct an Stream object instance.By default, Stream objects are ACQUIRED and must have external images pushed to them via setAcquiredImage.To create a NATIVE stream, call the 

      stream
      method on the builder.

    • Method Summary

      Modifier and Type Method Description
      Stream.StreamType getStreamType() Indicates whether this Stream is NATIVE or ACQUIRED.
      void setAcquiredImage(Object hwbuffer, Object handler, 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 callbackwhen it is done with it.
      void setDimensions(@IntRange(from = 0) int width, @IntRange(from = 0) int height) Updates the size of the incoming stream.
      long getTimestamp() Returns the presentation time of the currently displayed frame in nanosecond.This value can change at any time.
      long getNativeObject()

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • setAcquiredImage

         void setAcquiredImage(Object hwbuffer, Object handler, 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 callbackwhen 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 streammultiple times in a single frame, only the final image is honored, but all callbacks areinvoked.This method should be called on the same thread that calls beginFrame, which isalso where the callback is invoked. This method can only be used for streams that wereconstructed 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

         void setDimensions(@IntRange(from = 0) int width, @IntRange(from = 0) int height)

        Updates the size of the incoming stream. Whether this value is used isstream dependent. On Android, it must be set when using stream

        Parameters:
        width - new width of the incoming stream
        height - new height of the incoming stream

      • getTimestamp

         long getTimestamp()

        Returns the presentation time of the currently displayed frame in nanosecond.This value can change at any time.