GLFrontBufferedRenderer.Callback

public interface GLFrontBufferedRenderer.Callback<T extends Object>


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.

Summary

Public methods

abstract void
@WorkerThread
onDrawFrontBufferedLayer(
    @NonNull EGLManager eglManager,
    int width,
    int height,
    @NonNull BufferInfo bufferInfo,
    @NonNull float[] transform,
    @NonNull T param
)

Callback invoked to render content into the front buffered layer with the specified parameters.

abstract void
@WorkerThread
onDrawMultiBufferedLayer(
    @NonNull EGLManager eglManager,
    int width,
    int height,
    @NonNull BufferInfo bufferInfo,
    @NonNull float[] transform,
    @NonNull Collection<@NonNull T> params
)

Callback invoked to render content into the multi buffered layer with the specified parameters.

default void

Optional callback invoked when rendering to the front buffered layer is complete but before the buffers are submitted to the hardware compositor.

default void
@WorkerThread
onMultiBufferedLayerRenderComplete(
    @NonNull SurfaceControlCompat frontBufferedLayerSurfaceControl,
    @NonNull SurfaceControlCompat multiBufferedLayerSurfaceControl,
    @NonNull SurfaceControlCompat.Transaction transaction
)

Optional callback invoked when rendering to the multi buffered layer is complete but before the buffers are submitted to the hardware compositor.

Public methods

onDrawFrontBufferedLayer

Added in 1.0.0-beta01
@WorkerThread
abstract void onDrawFrontBufferedLayer(
    @NonNull EGLManager eglManager,
    int width,
    int height,
    @NonNull BufferInfo bufferInfo,
    @NonNull float[] transform,
    @NonNull T param
)

Callback invoked to render content into the front buffered layer with the specified parameters.

Parameters
@NonNull EGLManager eglManager

EGLManager useful in configuring EGL objects to be used when issuing OpenGL commands to render into the front buffered layer

int width

Logical width of the content to render. This dimension matches what is provided from SurfaceHolder.Callback.surfaceChanged

int height

Logical height of the content to render. This dimension matches what is provided from SurfaceHolder.Callback.surfaceChanged

@NonNull BufferInfo bufferInfo

BufferInfo about the buffer that is being rendered into. This includes the width and height of the buffer which can be different than the corresponding dimensions of the SurfaceView provided to the GLFrontBufferedRenderer as pre-rotation can occasionally swap width and height parameters in order to avoid GPU composition to rotate content. This should be used as input to GLES20.glViewport. Additionally this also contains a frame buffer identifier that can be used to retarget rendering operations to the original destination after rendering into intermediate scratch buffers.

@NonNull float[] transform

Matrix that should be applied to the rendering in this callback. This should be consumed as input to any vertex shader implementations. Buffers are pre-rotated in advance in order to avoid unnecessary overhead of GPU composition to rotate content in the same install orientation of the display. This is a 4 x 4 matrix is represented as a flattened array of 16 floating point values. Consumers are expected to leverage Matrix.multiplyMM with this parameter alongside any additional transformations that are to be applied. For example:

val myMatrix = FloatArray(16)
Matrix.orthoM(
myMatrix, // matrix
0, // offset starting index into myMatrix
0f, // left
bufferInfo.bufferWidth.toFloat(), // right
0f, // bottom
bufferInfo.bufferHeight.toFloat(), // top
-1f, // near
1f, // far
)
val result = FloatArray(16)
Matrix.multiplyMM(result, 0, myMatrix, 0, transform, 0)
@NonNull T param

optional parameter provided the corresponding GLFrontBufferedRenderer.renderFrontBufferedLayer method that triggered this request to render into the front buffered layer

onDrawMultiBufferedLayer

@WorkerThread
abstract void onDrawMultiBufferedLayer(
    @NonNull EGLManager eglManager,
    int width,
    int height,
    @NonNull BufferInfo bufferInfo,
    @NonNull float[] transform,
    @NonNull Collection<@NonNull T> params
)

Callback invoked to render content into the multi buffered layer with the specified parameters.

Parameters
@NonNull EGLManager eglManager

EGLManager useful in configuring EGL objects to be used when issuing OpenGL commands to render into the multi buffered layer

int width

Logical width of the content to render. This dimension matches what is provided from SurfaceHolder.Callback.surfaceChanged

int height

Logical height of the content to render. This dimension matches what is provided from SurfaceHolder.Callback.surfaceChanged

@NonNull BufferInfo bufferInfo

BufferInfo about the buffer that is being rendered into. This includes the width and height of the buffer which can be different than the corresponding dimensions of the SurfaceView provided to the GLFrontBufferedRenderer as pre-rotation can occasionally swap width and height parameters in order to avoid GPU composition to rotate content. This should be used as input to GLES20.glViewport. Additionally this also contains a frame buffer identifier that can be used to retarget rendering operations to the original destination after rendering into intermediate scratch buffers.

@NonNull float[] transform

Matrix that should be applied to the rendering in this callback. This should be consumed as input to any vertex shader implementations. Buffers are pre-rotated in advance in order to avoid unnecessary overhead of GPU composition to rotate content in the same install orientation of the display. This is a 4 x 4 matrix is represented as a flattened array of 16 floating point values. Consumers are expected to leverage Matrix.multiplyMM with this parameter alongside any additional transformations that are to be applied. For example:

val myMatrix = FloatArray(16)
Matrix.orthoM(
myMatrix, // matrix
0, // offset starting index into myMatrix
0f, // left
bufferInfo.bufferWidth.toFloat(), // right
0f, // bottom
bufferInfo.bufferHeight.toFloat(), // top
-1f, // near
1f, // far
)
val result = FloatArray(16)
Matrix.multiplyMM(result, 0, myMatrix, 0, transform, 0)
@NonNull Collection<@NonNull T> params

optional parameter provided to render the entire scene into the multi buffered layer. This is a collection of all parameters provided in consecutive invocations to GLFrontBufferedRenderer.renderFrontBufferedLayer since the last call to GLFrontBufferedRenderer.commit has been made. After GLFrontBufferedRenderer.commit is invoked, this collection is cleared and new parameters are added on each subsequent call to GLFrontBufferedRenderer.renderFrontBufferedLayer.

Consider the following example:

myFrontBufferedRenderer.renderFrontBufferedLayer(1) myFrontBufferedRenderer.renderFrontBufferedLayer(2) myFrontBufferedRenderer.renderFrontBufferedLayer(3) myFrontBufferedRenderer.commit()

This will generate a callback to this method with the params collection containing values 1, 2, 3

myFrontBufferedRenderer.renderFrontBufferedLayer(4) myFrontBufferedRenderer.renderFrontBufferedLayer(5) myFrontBufferedRenderer.commit()

This will generate a callback to this method with the params collection containing values 4, 5

By default GLES20.glViewport is invoked with the correct dimensions of the buffer that is being rendered into taking into account pre-rotation transformations

onFrontBufferedLayerRenderComplete

Added in 1.0.0-beta01
@WorkerThread
default void onFrontBufferedLayerRenderComplete(
    @NonNull SurfaceControlCompat frontBufferedLayerSurfaceControl,
    @NonNull SurfaceControlCompat.Transaction transaction
)

Optional callback invoked when rendering to the front buffered layer is complete but before the buffers are submitted to the hardware compositor. This provides consumers a mechanism for synchronizing the transaction with other SurfaceControlCompat objects that maybe rendered within the scene.

Parameters
@NonNull SurfaceControlCompat frontBufferedLayerSurfaceControl

Handle to the SurfaceControlCompat where the front buffered layer content is drawn. This can be used to configure various properties of the SurfaceControlCompat like z-ordering or visibility with the corresponding SurfaceControlCompat.Transaction.

@NonNull SurfaceControlCompat.Transaction transaction

Current SurfaceControlCompat.Transaction to apply updated buffered content to the front buffered layer.

onMultiBufferedLayerRenderComplete

Added in 1.0.0-beta01
@WorkerThread
default void onMultiBufferedLayerRenderComplete(
    @NonNull SurfaceControlCompat frontBufferedLayerSurfaceControl,
    @NonNull SurfaceControlCompat multiBufferedLayerSurfaceControl,
    @NonNull SurfaceControlCompat.Transaction transaction
)

Optional callback invoked when rendering to the multi buffered layer is complete but before the buffers are submitted to the hardware compositor. This provides consumers a mechanism for synchronizing the transaction with other SurfaceControlCompat objects that maybe rendered within the scene.

Parameters
@NonNull SurfaceControlCompat frontBufferedLayerSurfaceControl

Handle to the SurfaceControlCompat where the front buffered layer content is drawn. This can be used to configure various properties of the SurfaceControlCompat like z-ordering or visibility with the corresponding SurfaceControlCompat.Transaction.

@NonNull SurfaceControlCompat multiBufferedLayerSurfaceControl

Handle to the SurfaceControlCompat where the front buffered layer content is drawn. This can be used to configure various properties of the SurfaceControlCompat like z-ordering or visibility with the corresponding SurfaceControlCompat.Transaction.

@NonNull SurfaceControlCompat.Transaction transaction

Current SurfaceControlCompat.Transaction to apply updated buffered content to the multi buffered layer.