DeferrableSurface

@RequiresApi(21) abstract class DeferrableSurface
kotlin.Any
   ↳ androidx.camera.core.impl.DeferrableSurface

A class for creating and tracking use of a Surface in an asynchronous manner.

Once the deferrable surface has been closed via close() and is no longer in use (decrementUseCount() has been called equal to the number of times to incrementUseCount()), then the surface is considered terminated.

Resources managed by this class can be safely cleaned up upon completion of the ListenableFuture returned by getTerminationFuture().

Summary

Nested classes

The exception that is returned by the ListenableFuture of getSurface() if the deferrable surface is unable to produce a Surface.

Public constructors

Creates a new DeferrableSurface which has no use count.

DeferrableSurface(@NonNull size: Size, format: Int)

Creates a new DeferrableSurface which has no use count.

Public methods
Unit

Close the surface.

open Unit

Decrements the use count.

open Class<*>?

Returns the Class that contains this DeferrableSurface to provide more context about it.

open Size

open Int

ListenableFuture<Surface!>

Returns a Surface that is wrapped in a ListenableFuture.

open ListenableFuture<Void!>

Returns a future which completes when the deferrable surface is terminated.

open Unit

Increments the use count of the surface.

open Unit
setContainerClass(@NonNull containerClass: Class<*>)

Set the Class that contains this DeferrableSurface to provide more context about it.

Protected methods
abstract ListenableFuture<Surface!>

Returns a Surface that is wrapped in a ListenableFuture when the DeferrableSurface has not yet been closed.

Properties
static Size!

Public constructors

DeferrableSurface

DeferrableSurface()

Creates a new DeferrableSurface which has no use count.

DeferrableSurface

DeferrableSurface(
    @NonNull size: Size,
    format: Int)

Creates a new DeferrableSurface which has no use count.

Parameters
size Size: the Size of the surface
format Int: the stream configuration format that the provided Surface will be used on.

Public methods

close

fun close(): Unit

Close the surface.

After closing, getSurface() and incrementUseCount() will return a SurfaceClosedException.

If the surface is not being used, then this will also complete the future returned by getTerminationFuture(). If the surface is in use, then the future not be completed until decrementUseCount() has bee called the appropriate number of times.

This method is idempotent. Subsequent calls after the first invocation will have no effect.

decrementUseCount

open fun decrementUseCount(): Unit

Decrements the use count.

If this causes the use count to go to zero and the surface has been closed, this will complete the future returned by getTerminationFuture().

getContainerClass

@Nullable open fun getContainerClass(): Class<*>?

Returns the Class that contains this DeferrableSurface to provide more context about it.

getPrescribedSize

@NonNull open fun getPrescribedSize(): Size
Return
Size the Size of the surface

getPrescribedStreamFormat

open fun getPrescribedStreamFormat(): Int
Return
Int the stream configuration format that the provided Surface will be used on.

getSurface

@NonNull fun getSurface(): ListenableFuture<Surface!>

Returns a Surface that is wrapped in a ListenableFuture.

Return
ListenableFuture<Surface!> Will return a ListenableFuture with an exception if the DeferrableSurface is already closed.

getTerminationFuture

@NonNull open fun getTerminationFuture(): ListenableFuture<Void!>

Returns a future which completes when the deferrable surface is terminated.

A deferrable surface is considered terminated once it has been closed by close() and it is marked as no longer in use via decrementUseCount().

Once a deferrable surface has been terminated, it is safe to release all resources which may have been created for the surface.

Return
ListenableFuture<Void!> A future signalling the deferrable surface has terminated. Cancellation of this future is a no-op.

incrementUseCount

open fun incrementUseCount(): Unit

Increments the use count of the surface.

If the surface has been closed and was not previously in use, this will fail and throw a SurfaceClosedException and the use count will not be incremented.

Exceptions
SurfaceClosedException if the surface has been closed.

setContainerClass

open fun setContainerClass(@NonNull containerClass: Class<*>): Unit

Set the Class that contains this DeferrableSurface to provide more context about it.

Protected methods

provideSurface

@NonNull protected abstract fun provideSurface(): ListenableFuture<Surface!>

Returns a Surface that is wrapped in a ListenableFuture when the DeferrableSurface has not yet been closed.

Properties

SIZE_UNDEFINED

static val SIZE_UNDEFINED: Size!