# CanvasBufferedRenderer

Artifact: [androidx.graphics:graphics-core](https://developer.android.com/jetpack/androidx/releases/graphics) [View Source](https://cs.android.com/search?q=file:androidx/graphics/CanvasBufferedRenderer.kt+class:androidx.graphics.CanvasBufferedRenderer) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

*** ** * ** ***


```
@RequiresApi(value = 29)
class CanvasBufferedRenderer : AutoCloseable
```

<br />

*** ** * ** ***

Creates an instance of a hardware-accelerated renderer. This is used to render a scene built from `https://developer.android.com/reference/android/graphics/RenderNode.html`s to an output `https://developer.android.com/reference/android/hardware/HardwareBuffer.html`. There can be as many `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` instances as desired.

Resources \& lifecycle

All `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` instances share a common render thread. Therefore `https://developer.android.com/reference/kotlin/androidx/graphics/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 `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` created comes with the cost of also creating the associated GPU contexts, however each incremental `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` thereafter is fairly cheap.

This is useful in situations where a scene built with `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setBuffer(androidx.graphics.surface.SurfaceControlCompat,android.hardware.HardwareBuffer,androidx.hardware.SyncFenceCompat,kotlin.Function1)`.

`https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` can optionally persist contents before each draw invocation so previous contents in the `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` target will be preserved across renders. This is determined by the argument provided to `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderRequest#preserveContents(kotlin.Boolean)` which is set to `false` by default.

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.Builder` Builder used to construct a `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` instance. |
| `inner class https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderRequest` Sets the parameters that can be used to control a render request for a `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer`. |
| `class https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderResult` Class that contains data regarding the result of the render request. |

| ### Public functions |
|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#close()()` Releases the resources associated with this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` instance. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderRequest` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#obtainRenderRequest()()` Returns a `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderRequest` that can be used to render into the provided HardwareBuffer. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#releaseBuffer(android.hardware.HardwareBuffer,androidx.hardware.SyncFenceCompat)(hardwareBuffer: https://developer.android.com/reference/android/hardware/HardwareBuffer.html, fence: https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat?)` Releases the `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` back into the allocation pool to be reused in subsequent renders. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#setContentRoot(android.graphics.RenderNode)(renderNode: https://developer.android.com/reference/android/graphics/RenderNode.html)` Sets the content root to render. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#setLightSourceAlpha(kotlin.Float,kotlin.Float)(ambientShadowAlpha: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, spotShadowAlpha: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)` Configures the ambient \& spot shadow alphas. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#setLightSourceGeometry(kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float)( lightX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, lightY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, lightZ: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, lightRadius: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html )` Sets the center of the light source. |

| ### Public properties |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#bufferFormat()` Returns the `https://developer.android.com/reference/kotlin/androidx/hardware/HardwareBufferFormat` of the buffers that are being rendered into by this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#isClosed()` Returns if the `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` has already been closed. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#maxBuffers()` Returns the number of buffers within the swap chain used for rendering with this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#usageFlags()` Returns the current usage flag hints of the buffers that are being rendered into by this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` |

## Public functions

### close

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
open fun close(): Unit
```

Releases the resources associated with this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` instance. **Note** this does not call `https://developer.android.com/reference/android/hardware/HardwareBuffer.html#close()` on the provided `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` instance.

### obtainRenderRequest

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun obtainRenderRequest(): CanvasBufferedRenderer.RenderRequest
```

Returns a `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderRequest` that can be used to render into the provided HardwareBuffer. This is used to synchronize the RenderNode content provided by `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#setContentRoot(android.graphics.RenderNode)`.

### releaseBuffer

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun releaseBuffer(hardwareBuffer: HardwareBuffer, fence: SyncFenceCompat? = null): Unit
```

Releases the `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` back into the allocation pool to be reused in subsequent renders. The `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` instance released here must be one that was originally obtained from this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` instance. This method also takes in an optional `https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat` instance that will be internally waited upon before re-using the buffer. This is useful in conjunction with `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setBuffer(androidx.graphics.surface.SurfaceControlCompat,android.hardware.HardwareBuffer,androidx.hardware.SyncFenceCompat,kotlin.Function1)` where the system will return a release fence that should be waited upon before the corresponding buffer can be re-used.

| Parameters |
|---|---|
| `hardwareBuffer: https://developer.android.com/reference/android/hardware/HardwareBuffer.html` | `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` to return back to the allocation pool |
| `fence: https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat? = null` | Optional `https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat` that should be waited upon before the buffer is reused. |

### setContentRoot

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
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 `https://developer.android.com/reference/android/graphics/RenderNode.html` content, or any of the `https://developer.android.com/reference/android/graphics/RenderNode.html`s contained within the content node, will be applied whenever a new `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderRequest` is issued via `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#obtainRenderRequest()` and `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer.RenderRequest#drawAsync(java.util.concurrent.Executor,androidx.core.util.Consumer)`.

### setLightSourceAlpha

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
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 `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#setLightSourceGeometry(kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float)` before shadows will work.

### setLightSourceGeometry

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
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 `https://developer.android.com/reference/android/graphics/RenderNode.html` 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 `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#setLightSourceAlpha(kotlin.Float,kotlin.Float)` before shadows will work.

## Public properties

### bufferFormat

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
val bufferFormat: Int
```

Returns the `https://developer.android.com/reference/kotlin/androidx/hardware/HardwareBufferFormat` of the buffers that are being rendered into by this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer`

Value is one of the following:

- `1`
- `22`
- `43`
- `2`
- `3`
- `4`
- `33`
- `35`
- `48`
- `49`
- `50`
- `51`
- `52`
- `53`
- `54`

<br />

### isClosed

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
val isClosed: Boolean
```

Returns if the `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer` has already been closed. That is `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer#close()` has been invoked.

### maxBuffers

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
val maxBuffers: Int
```

Returns the number of buffers within the swap chain used for rendering with this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer`

### usageFlags

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
val usageFlags: Long
```

Returns the current usage flag hints of the buffers that are being rendered into by this `https://developer.android.com/reference/kotlin/androidx/graphics/CanvasBufferedRenderer`

Value is one of the following:

- `2`
- `3`
- `32`
- `48`
- `256`
- `512`
- `2048`
- `16384`
- `65536`
- `16777216`
- `8388608`
- `33554432`
- `67108864`
- `4294967296`

<br />