SurfaceHolderFrameWriter

@RequiresApi(value = 28)
@ExperimentalApi
public final class SurfaceHolderFrameWriter implements FrameWriter, SurfaceHolder.Callback

A FrameWriter that outputs frames to a SurfaceHolder.

Summary

Nested types

A listener for SurfaceHolderFrameWriter events.

Public methods
void

Blocks until all resources are released.
void
configure(Format format, @Frame.Usage long usage)

Format and usage support can be checked on the Info before configuring.
static SurfaceHolderFrameWriter
@RequiresApi(value = 33)
create(
    @Nullable SurfaceHolder surfaceHolder,
    Executor surfaceHolderExecutor,
    SurfaceHolderFrameWriter.Listener listener,
    Executor listenerExecutor
)

Creates a new instance that returns video frames that are directly dequeued from an ImageWriter linked to the output getSurface.
static SurfaceHolderFrameWriter
create(
    @Nullable SurfaceHolder surfaceHolder,
    Executor surfaceHolderExecutor,
    SurfaceHolderFrameWriter.Listener listener,
    Executor listenerExecutor,
    HardwareBufferNativeHelpers hardwareBufferNativeHelpers
)

Creates a new instance, that will allocate intermediate HardwareBufferFrames that are filled by the caller, and are then copied to HardwareBuffers dequeued from an ImageWriter linked to the output getSurface.
@Nullable AsyncFrame
dequeueInputFrame(Executor wakeupExecutor, Runnable wakeupListener)

Dequeues an AsyncFrame storing a Frame of the configured format and usage, and a SyncFenceWrapper that must be waited on before filling the frame.
FrameWriter.Info

Returns the Info for this FrameWriter.
void
queueInputFrame(
    Frame frame,
    @Nullable SyncFenceWrapper writeCompleteFence
)

Queues a filled frame for further processing.
void

Sets the SurfaceHolder to which frames will be written.
void

Notifies this FrameWriter that the current stream has ended.
void
surfaceChanged(SurfaceHolder holder, int format, int width, int height)
void
void

Inherited methods
From java.lang.AutoCloseable
abstract void

Public methods

close

public void close()

Blocks until all resources are released.

configure

public void configure(Format format, @Frame.Usage long usage)

Format and usage support can be checked on the Info before configuring.

Must be called before dequeueInputFrame.

Parameters
Format format

The format to configure.
@Frame.Usage long usage

The @FrameUsage flags describing how the frame will be used.
Throws
java.lang.IllegalStateException

if any frames are dequeued at the point this method is called.
java.lang.IllegalArgumentException

if the format or usage is unsupported.

create

@RequiresApi(value = 33)
public static SurfaceHolderFrameWriter create(
    @Nullable SurfaceHolder surfaceHolder,
    Executor surfaceHolderExecutor,
    SurfaceHolderFrameWriter.Listener listener,
    Executor listenerExecutor
)

Creates a new instance that returns video frames that are directly dequeued from an ImageWriter linked to the output getSurface.

Parameters
@Nullable SurfaceHolder surfaceHolder

The SurfaceHolder to which frames will be written, or null if not yet available.
Executor surfaceHolderExecutor

The Executor on which the surface holder methods will be called.
SurfaceHolderFrameWriter.Listener listener

The Listener.
Executor listenerExecutor

The Executor on which the listener methods will be called.

create

public static SurfaceHolderFrameWriter create(
    @Nullable SurfaceHolder surfaceHolder,
    Executor surfaceHolderExecutor,
    SurfaceHolderFrameWriter.Listener listener,
    Executor listenerExecutor,
    HardwareBufferNativeHelpers hardwareBufferNativeHelpers
)

Creates a new instance, that will allocate intermediate HardwareBufferFrames that are filled by the caller, and are then copied to HardwareBuffers dequeued from an ImageWriter linked to the output getSurface.

Parameters
@Nullable SurfaceHolder surfaceHolder

The SurfaceHolder to which frames will be written, or null if not yet available.
Executor surfaceHolderExecutor

The Executor on which the surface holder methods will be called.
SurfaceHolderFrameWriter.Listener listener

The Listener.
Executor listenerExecutor

The Executor on which the listener methods will be called.
HardwareBufferNativeHelpers hardwareBufferNativeHelpers

The HardwareBufferNativeHelpers used to copy intermediate HardwareBuffers to HardwareBuffers dequeued from ImageWriter.

dequeueInputFrame

public @Nullable AsyncFrame dequeueInputFrame(Executor wakeupExecutor, Runnable wakeupListener)

Dequeues an AsyncFrame storing a Frame of the configured format and usage, and a SyncFenceWrapper that must be waited on before filling the frame.

The returned frame must be filled and queued back for processing.

If the FrameWriter is at capacity, this method returns null and will notify the listener when capacity is available, and it can be called again.

Only the most recent wakeupListener will be notified when capacity is available.

Parameters
Executor wakeupExecutor

The Executor on which the wakeupListener is invoked.
Runnable wakeupListener

A Runnable to be invoked when capacity becomes available.
Returns
@Nullable AsyncFrame

The dequeued frame, or null if the writer is at capacity.
Throws
java.lang.IllegalStateException

if configure has not been called.

getInfo

public FrameWriter.Info getInfo()

Returns the Info for this FrameWriter.

queueInputFrame

public void queueInputFrame(
    Frame frame,
    @Nullable SyncFenceWrapper writeCompleteFence
)

Queues a filled frame for further processing.

The queued frame must have been previously dequeued from this writer.

Parameters
Frame frame

The filled frame to queue.
@Nullable SyncFenceWrapper writeCompleteFence

A SyncFenceWrapper that will signal when the caller has finished writing to the frame, or null if the write was synchronous.

setSurfaceHolder

public void setSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)

Sets the SurfaceHolder to which frames will be written.

Parameters
@Nullable SurfaceHolder surfaceHolder

The SurfaceHolder, or null to clear the output.

signalEndOfStream

public void signalEndOfStream()

Notifies this FrameWriter that the current stream has ended.

More frames may be queued after calling this method, if the current stream changes.

surfaceChanged

public void surfaceChanged(SurfaceHolder holder, int format, int width, int height)

surfaceCreated

public void surfaceCreated(SurfaceHolder holder)

surfaceDestroyed

public void surfaceDestroyed(SurfaceHolder holder)