SurfaceHolderFrameWriter

@ExperimentalApi
class SurfaceHolderFrameWriter : FrameWriter, SurfaceHolder.Callback

A FrameWriter that outputs frames to a SurfaceHolder.

Summary

Nested types

A listener for SurfaceHolderFrameWriter events.

Public functions
Unit

Blocks until all resources are released.
Unit
configure(format: Format!, @Frame.Usage usage: Long)

Format and usage support can be Info#isSupported(Format, long) checked on the before configuring.
java-static SurfaceHolderFrameWriter!
@RequiresApi(value = 33)
create(
    surfaceHolder: SurfaceHolder?,
    surfaceHolderExecutor: Executor!,
    listener: SurfaceHolderFrameWriter.Listener!,
    listenerExecutor: Executor!
)

Creates a new instance that returns HardwareBufferFrames that are directly dequeued from an ImageWriter linked to the output getSurface.
java-static SurfaceHolderFrameWriter!
create(
    surfaceHolder: SurfaceHolder?,
    surfaceHolderExecutor: Executor!,
    listener: SurfaceHolderFrameWriter.Listener!,
    listenerExecutor: Executor!,
    hardwareBufferNativeHelpers: HardwareBufferNativeHelpers!
)

Creates a new instance that returns video frames that will be written to the output getSurface.
AsyncFrame?
dequeueInputFrame(wakeupExecutor: Executor!, wakeupListener: Runnable!)

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.
Unit
queueInputFrame(frame: Frame!, writeCompleteFence: SyncFenceWrapper?)

Queues a filled frame for further processing.
Unit

Sets the SurfaceHolder to which frames will be written.
Unit

Notifies this FrameWriter that the current stream has ended.
Unit
surfaceChanged(holder: SurfaceHolder!, format: Int, width: Int, height: Int)
Unit
Unit

Inherited functions
From java.lang.AutoCloseable
abstract Unit

Public functions

close

fun close(): Unit

Blocks until all resources are released.

configure

fun configure(format: Format!, @Frame.Usage usage: Long): Unit

Format and usage support can be Info#isSupported(Format, long) checked on the before configuring.

Must be called before #dequeueInputFrame.

If pixelFormat is unset (i.e. NO_VALUE), it defaults to YV12 below API 28, RGBA_1010102 for HDR on API 28+, or RGBA_8888 for SDR on API 28+.

create

@RequiresApi(value = 33)
java-static fun create(
    surfaceHolder: SurfaceHolder?,
    surfaceHolderExecutor: Executor!,
    listener: SurfaceHolderFrameWriter.Listener!,
    listenerExecutor: Executor!
): SurfaceHolderFrameWriter!

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

Parameters
surfaceHolder: SurfaceHolder?

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

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

The Listener.
listenerExecutor: Executor!

The Executor on which the listener methods will be called.

create

java-static fun create(
    surfaceHolder: SurfaceHolder?,
    surfaceHolderExecutor: Executor!,
    listener: SurfaceHolderFrameWriter.Listener!,
    listenerExecutor: Executor!,
    hardwareBufferNativeHelpers: HardwareBufferNativeHelpers!
): SurfaceHolderFrameWriter!

Creates a new instance that returns video frames that will be written to the output getSurface.

Below API 28, dequeueInputFrame returns an ImagePlanesFrame wrapping an ImageWriter buffer without intermediate copying, and hardwareBufferNativeHelpers is ignored.

On API 28 to 32 (inclusive), dequeueInputFrame returns a pre-allocated HardwareBufferFrame. It is copied to the ImageWriter (via HardwareBufferNativeHelpers) after the caller fills and queues it.

On API 33 and above, dequeueInputFrame returns a HardwareBufferFrame directly dequeued from the ImageWriter without intermediate copying, and hardwareBufferNativeHelpers is ignored.

Parameters
surfaceHolder: SurfaceHolder?

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

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

The Listener.
listenerExecutor: Executor!

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

The HardwareBufferNativeHelpers used to copy intermediate HardwareBuffers to HardwareBuffers dequeued from ImageWriter on API 28 to 32; ignored on other API levels.

dequeueInputFrame

fun dequeueInputFrame(wakeupExecutor: Executor!, wakeupListener: Runnable!): AsyncFrame?

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
wakeupExecutor: Executor!

The Executor on which the wakeupListener is invoked.
wakeupListener: Runnable!

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

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

if configure has not been called.

getInfo

fun getInfo(): FrameWriter.Info!

Returns the Info for this FrameWriter.

queueInputFrame

fun queueInputFrame(frame: Frame!, writeCompleteFence: SyncFenceWrapper?): Unit

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.
writeCompleteFence: SyncFenceWrapper?

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

setSurfaceHolder

fun setSurfaceHolder(surfaceHolder: SurfaceHolder?): Unit

Sets the SurfaceHolder to which frames will be written.

Parameters
surfaceHolder: SurfaceHolder?

The SurfaceHolder, or null to clear the output.

signalEndOfStream

fun signalEndOfStream(): Unit

Notifies this FrameWriter that the current stream has ended.

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

surfaceChanged

fun surfaceChanged(holder: SurfaceHolder!, format: Int, width: Int, height: Int): Unit

surfaceCreated

fun surfaceCreated(holder: SurfaceHolder!): Unit

surfaceDestroyed

fun surfaceDestroyed(holder: SurfaceHolder!): Unit