GLFrontBufferedRenderer


@RequiresApi(value = 29)
class GLFrontBufferedRenderer<T : Any?>


Class responsible for supporting a "front buffered" rendering system. This allows for lower latency graphics by leveraging a combination of front buffered and multi buffered content layers. Active content is rendered first into the front buffered layer which is simultaneously being presented to the display. Periodically content is rendered into the multi buffered layer which will have more traditional latency guarantees, however, minimize the impact of visual artifacts due to graphical tearing.

Summary

Nested types

Provides callbacks for consumers to draw into the front and multi buffered layers as well as provide opportunities to synchronize SurfaceControlCompat.Transactions to submit the layers to the hardware compositor.

Public constructors

<T : Any?> GLFrontBufferedRenderer(
    surfaceView: SurfaceView,
    callback: GLFrontBufferedRenderer.Callback<T>,
    glRenderer: GLRenderer?,
    bufferFormat: Int
)

Public functions

Unit

Requests to cancel rendering and hides the front buffered layer.

Unit

Clears the contents of both the front and multi buffered layers.

Unit

Requests to render the entire scene to the multi buffered layer and schedules a call to Callback.onDrawMultiBufferedLayer.

Unit
execute(runnable: Runnable)

Queue a Runnable to be executed on the GL rendering thread.

Boolean

Determines whether or not the GLFrontBufferedRenderer is in a valid state.

Unit
release(cancelPending: Boolean, onReleaseComplete: (() -> Unit)?)

Releases the GLFrontBufferedRenderer and provides an optional callback that is invoked when the GLFrontBufferedRenderer is fully torn down.

Unit

Render content to the front buffered layer providing optional parameters to be consumed in Callback.onDrawFrontBufferedLayer.

Unit

Requests to render to the multi buffered layer.

Public properties

Int

format of the underlying buffers being rendered into by GLFrontBufferedRenderer.

Public constructors

GLFrontBufferedRenderer

<T : Any?> GLFrontBufferedRenderer(
    surfaceView: SurfaceView,
    callback: GLFrontBufferedRenderer.Callback<T>,
    glRenderer: GLRenderer? = null,
    bufferFormat: Int = HardwareBuffer.RGBA_8888
)
Parameters
surfaceView: SurfaceView

Target SurfaceView to act as the parent rendering layer for multi buffered content

callback: GLFrontBufferedRenderer.Callback<T>

Callbacks used to render into front and multi buffered layers as well as configuring SurfaceControlCompat.Transactions for controlling these layers in addition to other SurfaceControlCompat instances that must be updated atomically within the user interface. These callbacks are invoked on the backing GL Thread.

glRenderer: GLRenderer? = null

Optional GLRenderer instance that this GLFrontBufferedRenderer should use for coordinating requests to render content. If this parameter is specified, the caller of this API is responsible for releasing resources on GLRenderer by calling GLRenderer.stop. Otherwise GLFrontBufferedRenderer will create and manage its own GLRenderer internally and will automatically release its resources within GLFrontBufferedRenderer.release

bufferFormat: Int = HardwareBuffer.RGBA_8888

format of the underlying buffers being rendered into by GLFrontBufferedRenderer. The set of valid formats is implementation-specific and may depend on additional EGL extensions. The particular valid combinations for a given Android version and implementation should be documented by that version. HardwareBuffer.RGBA_8888 and HardwareBuffer.RGBX_8888 are guaranteed to be supported. However, consumers are recommended to query the desired HardwareBuffer configuration using HardwareBuffer.isSupported. The default is HardwareBuffer.RGBA_8888.

See: khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt and https://developer.android.com/reference/android/hardware/HardwareBuffer

Public functions

cancel

Added in 1.0.2
fun cancel(): Unit

Requests to cancel rendering and hides the front buffered layer. Unlike commit, this does not schedule a call to render into the multi buffered layer.

If this GLFrontBufferedRenderer has been released, that is isValid returns false, this call is ignored.

clear

Added in 1.0.2
fun clear(): Unit

Clears the contents of both the front and multi buffered layers. This triggers a call to Callback.onMultiBufferedLayerRenderComplete and hides the front buffered layer.

commit

Added in 1.0.2
fun commit(): Unit

Requests to render the entire scene to the multi buffered layer and schedules a call to Callback.onDrawMultiBufferedLayer. The parameters provided to Callback.onDrawMultiBufferedLayer will include each argument provided to every renderFrontBufferedLayer call since the last call to commit has been made.

If this GLFrontBufferedRenderer has been released, that is isValid returns false, this call is ignored.

execute

Added in 1.0.2
fun execute(runnable: Runnable): Unit

Queue a Runnable to be executed on the GL rendering thread. Note it is important this Runnable does not block otherwise it can stall the GL thread.

Parameters
runnable: Runnable

to be executed

isValid

Added in 1.0.2
fun isValid(): Boolean

Determines whether or not the GLFrontBufferedRenderer is in a valid state. That is the release method has not been called. If this returns false, then subsequent calls to renderFrontBufferedLayer, commit, and release are ignored

Returns
Boolean

true if this GLFrontBufferedRenderer has been released, false otherwise

release

Added in 1.0.2
fun release(cancelPending: Boolean, onReleaseComplete: (() -> Unit)? = null): Unit

Releases the GLFrontBufferedRenderer and provides an optional callback that is invoked when the GLFrontBufferedRenderer is fully torn down. If the cancelPending flag is true, all pending requests to render into the front or multi buffered layers will be processed before the GLFrontBufferedRenderer is torn down. Otherwise all in process requests are ignored. If the GLFrontBufferedRenderer is already released, that is isValid returns false, this method does nothing.

Parameters
cancelPending: Boolean

Flag indicating that requests to render should be processed before the GLFrontBufferedRenderer is released

onReleaseComplete: (() -> Unit)? = null

Optional callback invoked when the GLFrontBufferedRenderer has been released. This callback is invoked on the backing GLThread

renderFrontBufferedLayer

Added in 1.0.2
fun renderFrontBufferedLayer(param: T): Unit

Render content to the front buffered layer providing optional parameters to be consumed in Callback.onDrawFrontBufferedLayer. Additionally the parameter provided here will also be consumed in Callback.onDrawMultiBufferedLayer when the corresponding commit method is invoked, which will include all params in each call made to this method up to the corresponding commit call.

If this GLFrontBufferedRenderer has been released, that is isValid returns false, this call is ignored.

Parameters
param: T

Optional parameter to be consumed when rendering content into the commit layer

renderMultiBufferedLayer

fun renderMultiBufferedLayer(params: Collection<T>): Unit

Requests to render to the multi buffered layer. This schedules a call to Callback.onDrawMultiBufferedLayer with the parameters provided. If the front buffered layer is visible, this will hide this layer after rendering to the multi buffered layer is complete. This is equivalent to calling GLFrontBufferedRenderer.renderFrontBufferedLayer for each parameter provided in the collection followed by a single call to GLFrontBufferedRenderer.commit. This is useful for re-rendering the multi buffered scene when the corresponding Activity is being resumed from the background in which the contents should be re-drawn. Additionally this allows for applications to decide to dynamically render to either front or multi buffered layers.

If this GLFrontBufferedRenderer has been released, that is isValid returns 'false', this call is ignored.

Parameters
params: Collection<T>

Parameters that to be consumed when rendering to the multi buffered layer. These parameters will be provided in the corresponding call to Callback.onDrawMultiBufferedLayer

Public properties

bufferFormat

Added in 1.0.2
val bufferFormatInt

format of the underlying buffers being rendered into by GLFrontBufferedRenderer. The set of valid formats is implementation-specific and may depend on additional EGL extensions. The particular valid combinations for a given Android version and implementation should be documented by that version. HardwareBuffer.RGBA_8888 and HardwareBuffer.RGBX_8888 are guaranteed to be supported. However, consumers are recommended to query the desired HardwareBuffer configuration using HardwareBuffer.isSupported. The default is HardwareBuffer.RGBA_8888.

See: khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt and https://developer.android.com/reference/android/hardware/HardwareBuffer