HardwareBufferRenderer

public class HardwareBufferRenderer
extends Object implements AutoCloseable

java.lang.Object
   ↳ android.graphics.HardwareBufferRenderer


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 HardwareBufferRenderer instances as desired.

Resources & lifecycle

All HardwareBufferRenderer and HardwareRenderer instances share a common render thread. Therefore HardwareBufferRenderer 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 HardwareBufferRenderer created comes with the cost of also creating the associated GPU contexts, however each incremental HardwareBufferRenderer thereafter is fairly cheap. The expected usage is to have a HardwareBufferRenderer instance for every active HardwareBuffer.

This is useful in situations where a scene built with RenderNodes can be consumed directly by the system compositor through SurfaceControl.Transaction#setBuffer(SurfaceControl, HardwareBuffer). HardwareBufferRenderer will never clear contents before each draw invocation so previous contents in the HardwareBuffer target will be preserved across renders.

Summary

Nested classes

class HardwareBufferRenderer.RenderRequest

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

class HardwareBufferRenderer.RenderResult

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

Public constructors

HardwareBufferRenderer(HardwareBuffer buffer)

Creates a new instance of HardwareBufferRenderer with the provided HardwareBuffer as the output of the rendered scene.

Public methods

void close()

Releases the resources associated with this HardwareBufferRenderer instance.

boolean isClosed()

Returns if the HardwareBufferRenderer has already been closed.

HardwareBufferRenderer.RenderRequest obtainRenderRequest()

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

void setContentRoot(RenderNode content)

Sets the content root to render.

void setLightSourceAlpha(float ambientShadowAlpha, float spotShadowAlpha)

Configures the ambient & spot shadow alphas.

void setLightSourceGeometry(float lightX, float lightY, float lightZ, float lightRadius)

Sets the center of the light source.

Inherited methods

Public constructors

HardwareBufferRenderer

Added in API level 34
public HardwareBufferRenderer (HardwareBuffer buffer)

Creates a new instance of HardwareBufferRenderer with the provided HardwareBuffer as the output of the rendered scene.

Parameters
buffer HardwareBuffer: This value cannot be null.

Public methods

close

Added in API level 34
public void close ()

Releases the resources associated with this HardwareBufferRenderer instance. **Note** this does not call HardwareBuffer#close() on the provided HardwareBuffer instance

isClosed

Added in API level 34
public boolean isClosed ()

Returns if the HardwareBufferRenderer has already been closed. That is HardwareBufferRenderer#close() has been invoked.

Returns
boolean True if the HardwareBufferRenderer has been closed, false otherwise.

obtainRenderRequest

Added in API level 34
public HardwareBufferRenderer.RenderRequest obtainRenderRequest ()

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

Returns
HardwareBufferRenderer.RenderRequest An instance of RenderRequest. The instance may be reused for every frame, so the caller should not hold onto it for longer than a single render request. This value cannot be null.

setContentRoot

Added in API level 34
public void setContentRoot (RenderNode content)

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#draw(Executor, Consumer).

Parameters
content RenderNode: The content to set as the root RenderNode. If null the content root is removed and the renderer will draw nothing.

setLightSourceAlpha

Added in API level 34
public void setLightSourceAlpha (float ambientShadowAlpha, 
                float spotShadowAlpha)

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(float, float, float, float) before shadows will work.

Parameters
ambientShadowAlpha float: The alpha for the ambient shadow. If unsure, a reasonable default is 0.039f. Value is between 0.0f and 1.0f inclusive

spotShadowAlpha float: The alpha for the spot shadow. If unsure, a reasonable default is 0.19f. Value is between 0.0f and 1.0f inclusive

setLightSourceGeometry

Added in API level 34
public void setLightSourceGeometry (float lightX, 
                float lightY, 
                float lightZ, 
                float lightRadius)

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(float, float) before shadows will work.

Parameters
lightX float: The X position of the light source. If unsure, a reasonable default is 'displayWidth / 2f - windowLeft'.

lightY float: The Y position of the light source. If unsure, a reasonable default is '0 - windowTop'

lightZ float: The Z position of the light source. Must be >= 0. If unsure, a reasonable default is 600dp. Value is 0f or greater

lightRadius float: The radius of the light source. Smaller radius will have sharper edges, larger radius will have softer shadows. If unsure, a reasonable default is 800 dp. Value is 0f or greater