TextureInput

class NatML.Recorders.Inputs.TextureInput

The TextureInput class provides a simple primitive for recording video frames from Texture objects. It works by performing synchronous pixel buffer readbacks from the GPU.

Prefer using AsyncTextureInput when possible because synchronous readbacks have a sizable performance cost.

Creating the Texture Input

/// <summary>
/// Create a texture input which performs synchronous readbacks.
/// </summary>
/// <param name="recorder">Media recorder to receive video frames.</param>
TextureInput (IMediaRecorder recorder);

The texture input is always created with a recorder which receives any frames committed by the input.

When creating a custom subclass of the TextureInput, the recorder can be null. But you must remember to override the frameSize property.

Inspecting the Frame Size

/// <summary>
/// Texture input frame size.
/// </summary>
virtual (int width, int height) frameSize { get; }

The texture input reports the frame size of the backing recorder. This is useful when allocating frame buffers, and computing aspect ratios.

Committing Video Frames

/// <summary>
/// Commit a video frame from a texture.
/// </summary>
/// <param name="texture">Source texture.</param>
/// <param name="timestamp">Frame timestamp in nanoseconds.</param>
virtual void CommitFrame (Texture texture, long timestamp);

This method commits a video frame from the texture to the recorder. The texture input will perform a pixel buffer readback from the GPU, then send the pixel buffer to the recorder.

The input texture does not have to be the same size as the recorder, but any differences might result in stretching in the recorded video frames.

Disposing the Recorder Input

/// <summary>
/// Stop recorder input and release resources.
/// </summary>
virtual void Dispose ();

Once you are done recording, make sure to dispose the recorder input. Any resources will be disposed.

Do not use the texture input after the Dispose method has been called.

Creating a Platform-Default Input

/// <summary>
/// Create the platform default texture input for the given recorder.
/// </summary>
/// <param name="recorder"></param>
/// <returns>Create texture input.</returns>
static TextureInput CreateDefault (IMediaRecorder recorder);

The TextureInput class defines the static CreateDefault method which creates the best texture input implementation for a given recorder and runtime platform. This method automatically selects a TextureInput implementation with the best expected runtime performance for the given recorder.

Allowing the GLESTextureInput

/// <summary>
/// Allow the `CreateDefault` method use the `GLESTextureInput` on Android.
/// </summary>
static bool UseGLESTextureInput { get; set; }

When an Android app renders with OpenGL ES3, the default TextureInput implementation can be very expensive. Enabling this flag will use the custom GLESTextureInput to accelerate pixel buffer readbacks from the GPU.

Apps that use ARFoundation will see recording performance greatly benefit from enabling this flag.

This flag only has an effect on Android when rendering with OpenGL ES3.

This flag defaults to true.