CanvasBufferedRenderer


@RequiresApi(value = 29)
class CanvasBufferedRenderer : AutoCloseable


Creates an instance of a hardware-accelerated renderer. This is used to render a scene built from RenderNodes to an output HardwareBuffer. There can be as many CanvasBufferedRenderer instances as desired.

Resources & lifecycle

All CanvasBufferedRenderer instances share a common render thread. Therefore CanvasBufferedRenderer will share common resources and GPU utilization with hardware accelerated rendering initiated by the UI thread of an application. The render thread contains the GPU context & resources necessary to do GPU-accelerated rendering. As such, the first CanvasBufferedRenderer created comes with the cost of also creating the associated GPU contexts, however each incremental CanvasBufferedRenderer thereafter is fairly cheap.

This is useful in situations where a scene built with RenderNode.

CanvasBufferedRenderer can optionally persist contents before each draw invocation so previous contents in the HardwareBuffer target will be preserved across renders. This is determined by the argument provided to CanvasBufferedRenderer.RenderRequest.preserveContents which is set to false by default.

Summary

Nested types

Builder used to construct a CanvasBufferedRenderer instance.

Sets the parameters that can be used to control a render request for a CanvasBufferedRenderer.

Class that contains data regarding the result of the render request.

Public functions

open Unit

Releases the resources associated with this CanvasBufferedRenderer instance.

CanvasBufferedRenderer.RenderRequest

Returns a RenderRequest that can be used to render into the provided HardwareBuffer.

Unit
releaseBuffer(hardwareBuffer: HardwareBuffer, fence: SyncFenceCompat?)

Releases the HardwareBuffer back into the allocation pool to be reused in subsequent renders.

Unit

Sets the content root to render.

Unit
setLightSourceAlpha(ambientShadowAlpha: Float, spotShadowAlpha: Float)

Configures the ambient & spot shadow alphas.

Unit
setLightSourceGeometry(
    lightX: Float,
    lightY: Float,
    lightZ: Float,
    lightRadius: Float
)

Sets the center of the light source.

Public properties

Int

Returns the HardwareBufferFormat of the buffers that are being rendered into by this CanvasBufferedRenderer

Boolean

Returns if the CanvasBufferedRenderer has already been closed.

Int

Returns the number of buffers within the swap chain used for rendering with this CanvasBufferedRenderer

Long

Returns the current usage flag hints of the buffers that are being rendered into by this CanvasBufferedRenderer

Public functions

close

Added in 1.0.2
open fun close(): Unit

Releases the resources associated with this CanvasBufferedRenderer instance. Note this does not call HardwareBuffer.close on the provided HardwareBuffer instance.

obtainRenderRequest

Added in 1.0.2
fun obtainRenderRequest(): CanvasBufferedRenderer.RenderRequest

Returns a RenderRequest that can be used to render into the provided HardwareBuffer. This is used to synchronize the RenderNode content provided by setContentRoot.

releaseBuffer

Added in 1.0.2
fun releaseBuffer(hardwareBuffer: HardwareBuffer, fence: SyncFenceCompat? = null): Unit

Releases the HardwareBuffer back into the allocation pool to be reused in subsequent renders. The HardwareBuffer instance released here must be one that was originally obtained from this CanvasBufferedRenderer instance. This method also takes in an optional SyncFenceCompat instance that will be internally waited upon before re-using the buffer. This is useful in conjunction with SurfaceControlCompat.Transaction.setBuffer where the system will return a release fence that should be waited upon before the corresponding buffer can be re-used.

Parameters
hardwareBuffer: HardwareBuffer

HardwareBuffer to return back to the allocation pool

fence: SyncFenceCompat? = null

Optional SyncFenceCompat that should be waited upon before the buffer is reused.

setContentRoot

Added in 1.0.2
fun setContentRoot(renderNode: RenderNode): Unit

Sets the content root to render. It is not necessary to call this whenever the content recording changes. Any mutations to the RenderNode content, or any of the RenderNodes contained within the content node, will be applied whenever a new RenderRequest is issued via obtainRenderRequest and RenderRequest.drawAsync.

setLightSourceAlpha

Added in 1.0.2
fun setLightSourceAlpha(ambientShadowAlpha: Float, spotShadowAlpha: Float): Unit

Configures the ambient & spot shadow alphas. This is the alpha used when the shadow has max alpha, and ramps down from the values provided to zero.

These values are typically provided by the current theme, see R.attr.spotShadowAlpha and R.attr.ambientShadowAlpha.

This must be set at least once along with setLightSourceGeometry before shadows will work.

setLightSourceGeometry

Added in 1.0.2
fun setLightSourceGeometry(
    lightX: Float,
    lightY: Float,
    lightZ: Float,
    lightRadius: Float
): Unit

Sets the center of the light source. The light source point controls the directionality and shape of shadows rendered by RenderNode Z & elevation.

The light source should be setup both as part of initial configuration, and whenever the window moves to ensure the light source stays anchored in display space instead of in window space.

This must be set at least once along with setLightSourceAlpha before shadows will work.

Public properties

bufferFormat

Added in 1.0.2
val bufferFormatInt

Returns the HardwareBufferFormat of the buffers that are being rendered into by this CanvasBufferedRenderer

isClosed

Added in 1.0.2
val isClosedBoolean

Returns if the CanvasBufferedRenderer has already been closed. That is CanvasBufferedRenderer.close has been invoked.

maxBuffers

Added in 1.0.2
val maxBuffersInt

Returns the number of buffers within the swap chain used for rendering with this CanvasBufferedRenderer

usageFlags

Added in 1.0.2
val usageFlagsLong

Returns the current usage flag hints of the buffers that are being rendered into by this CanvasBufferedRenderer