Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/android/graphics/HardwareRenderer#nestedclasses) \| [Constants](https://developer.android.com/reference/android/graphics/HardwareRenderer#constants) \| [Ctors](https://developer.android.com/reference/android/graphics/HardwareRenderer#pubctors) \| [Methods](https://developer.android.com/reference/android/graphics/HardwareRenderer#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/graphics/HardwareRenderer#inhmethods)
# HardwareRenderer
*** ** * ** ***
[Kotlin](https://developer.android.com/reference/kotlin/android/graphics/HardwareRenderer "View this page in Kotlin") \|Java
`
public
class
HardwareRenderer
`
`
extends https://developer.android.com/reference/java/lang/Object
`
`
`
|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.graphics.HardwareRenderer |
*** ** * ** ***
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`'s to an output `https://developer.android.com/reference/android/view/Surface`. There can be as many
HardwareRenderer instances as desired.
### Resources \& lifecycle
All HardwareRenderer instances share a common render thread. The render thread contains
the GPU context \& resources necessary to do GPU-accelerated rendering. As such, the first
HardwareRenderer created comes with the cost of also creating the associated GPU contexts,
however each incremental HardwareRenderer thereafter is fairly cheap. The expected usage
is to have a HardwareRenderer instance for every active `https://developer.android.com/reference/android/view/Surface`. For example
when an Activity shows a Dialog the system internally will use 2 hardware renderers, both
of which may be drawing at the same time.
NOTE: Due to the shared, cooperative nature of the render thread it is critical that
any `https://developer.android.com/reference/android/view/Surface` used must have a prompt, reliable consuming side. System-provided
consumers such as `https://developer.android.com/reference/android/view/SurfaceView`,
`https://developer.android.com/reference/android/view/Window#takeSurface(android.view.SurfaceHolder.Callback2)`,
or `https://developer.android.com/reference/android/view/TextureView` all fit this requirement. However if custom consumers
are used such as when using `https://developer.android.com/reference/android/graphics/SurfaceTexture` or `https://developer.android.com/reference/android/media/ImageReader`
it is the app's responsibility to ensure that they consume updates promptly and rapidly.
Failure to do so will cause the render thread to stall on that surface, blocking all
HardwareRenderer instances.
## Summary
| ### Nested classes ||
|---|---|
| ` class` | `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest` Sets the parameters that can be used to control a render request for a `https://developer.android.com/reference/android/graphics/HardwareRenderer`. |
| ### Constants ||
|---|---|
| `int` | `https://developer.android.com/reference/android/graphics/HardwareRenderer#SYNC_CONTEXT_IS_STOPPED` The hardware renderer has been set to a "stopped" state. |
| `int` | `https://developer.android.com/reference/android/graphics/HardwareRenderer#SYNC_FRAME_DROPPED` The content was synced but the renderer has declined to produce a frame in this vsync interval. |
| `int` | `https://developer.android.com/reference/android/graphics/HardwareRenderer#SYNC_LOST_SURFACE_REWARD_IF_FOUND` The hardware renderer no longer has a valid `https://developer.android.com/reference/android/view/Surface` to render to. |
| `int` | `https://developer.android.com/reference/android/graphics/HardwareRenderer#SYNC_OK` Nothing interesting to report. |
| `int` | `https://developer.android.com/reference/android/graphics/HardwareRenderer#SYNC_REDRAW_REQUESTED` The renderer is requesting a redraw. |
| ### Public constructors ||
|---|---|
| ` https://developer.android.com/reference/android/graphics/HardwareRenderer#HardwareRenderer()() ` |
| ### Public methods ||
|---|---|
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#clearContent()() ` Destroys all the display lists associated with the current rendering content. |
| ` https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#createRenderRequest()() ` Returns a `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest` that can be used to render a new frame. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#destroy()() ` Destroys the rendering context of this HardwareRenderer. |
| ` static boolean` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#isDrawingEnabled()() ` Returns true if HardwareRender will produce output. |
| ` boolean` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#isOpaque()() ` Whether or not the renderer is set to be opaque. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#notifyFramePending()() ` Notifies the hardware renderer that a call to `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest#syncAndDraw()` will be coming soon. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#setContentRoot(android.graphics.RenderNode)(https://developer.android.com/reference/android/graphics/RenderNode content) ` Sets the content root to render. |
| ` static void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#setDrawingEnabled(boolean)(boolean drawingEnabled) ` Toggles whether or not HardwareRenderer will produce drawing output globally in the current process. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#setLightSourceAlpha(float,%20float)(float ambientShadowAlpha, float spotShadowAlpha) ` Configures the ambient \& spot shadow alphas. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#setLightSourceGeometry(float,%20float,%20float,%20float)(float lightX, float lightY, float lightZ, float lightRadius) ` Sets the center of the light source. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#setName(java.lang.String)(https://developer.android.com/reference/java/lang/String name) ` Sets a name for this renderer. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#setOpaque(boolean)(boolean opaque) ` Change the HardwareRenderer's opacity. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#setSurface(android.view.Surface)(https://developer.android.com/reference/android/view/Surface surface) `
The surface to render into. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#start()() ` Resumes rendering into the surface. |
| ` void` | ` https://developer.android.com/reference/android/graphics/HardwareRenderer#stop()() ` Hard stops rendering into the surface. |
| ### Inherited methods |
|---|---|
| From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | ||
## Constants
### SYNC_CONTEXT_IS_STOPPED
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static final int SYNC_CONTEXT_IS_STOPPED
```
The hardware renderer has been set to a "stopped" state. If this is returned then the
rendering content has been synced, however a frame was not produced.
Constant Value:
4
(0x00000004)
### SYNC_FRAME_DROPPED
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static final int SYNC_FRAME_DROPPED
```
The content was synced but the renderer has declined to produce a frame in this vsync
interval. This can happen if a frame was already drawn in this vsync or if the renderer
is outrunning the frame consumer. The renderer will internally re-schedule itself
to render a frame in the next vsync signal, so the caller does not need to do anything
in response to this signal.
Constant Value:
8
(0x00000008)
### SYNC_LOST_SURFACE_REWARD_IF_FOUND
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static final int SYNC_LOST_SURFACE_REWARD_IF_FOUND
```
The hardware renderer no longer has a valid `https://developer.android.com/reference/android/view/Surface` to render to.
This can happen if `https://developer.android.com/reference/android/view/Surface#release()` was called. The user should no longer
attempt to call syncAndDraw until a new surface has been provided by calling
setSurface.
Spoiler: the reward is GPU-accelerated drawing, better find that Surface!
Constant Value:
2
(0x00000002)
### SYNC_OK
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static final int SYNC_OK
```
Nothing interesting to report. Sync \& draw kicked off
Constant Value:
0
(0x00000000)
### SYNC_REDRAW_REQUESTED
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static final int SYNC_REDRAW_REQUESTED
```
The renderer is requesting a redraw. This can occur if there's an animation that's running
in the RenderNode tree and the hardware renderer is unable to self-animate.
If this is returned from syncAndDraw the expectation is that syncAndDraw
will be called again on the next vsync signal.
Constant Value:
1
(0x00000001)
## Public constructors
### HardwareRenderer
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public HardwareRenderer ()
```
## Public methods
### clearContent
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void clearContent ()
```
Destroys all the display lists associated with the current rendering content.
This includes releasing a reference to the current content root RenderNode. It will
therefore be necessary to call `https://developer.android.com/reference/android/graphics/HardwareRenderer#setContentRoot(android.graphics.RenderNode)` in order to resume
rendering after calling this, along with re-recording the display lists for the
RenderNode tree.
It is recommended, but not necessary, to use this in combination with lifecycle events
such as `https://developer.android.com/reference/android/app/Activity#onStop()` and `https://developer.android.com/reference/android/app/Activity#onStart()` or in response to
`https://developer.android.com/reference/android/content/ComponentCallbacks2#onTrimMemory(int)` signals such as
`https://developer.android.com/reference/android/content/ComponentCallbacks2#TRIM_MEMORY_UI_HIDDEN`
See also `https://developer.android.com/reference/android/graphics/HardwareRenderer#stop()`.
### createRenderRequest
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public HardwareRenderer.FrameRenderRequest createRenderRequest ()
```
Returns a `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest` that can be used to render a new frame. This is used
to synchronize the RenderNode content provided by `https://developer.android.com/reference/android/graphics/HardwareRenderer#setContentRoot(android.graphics.RenderNode)` with
the RenderThread and then renders a single frame to the Surface set with
`https://developer.android.com/reference/android/graphics/HardwareRenderer#setSurface(android.view.Surface)`.
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest` | An instance of `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest`. 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`.
|
### destroy
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void destroy ()
```
Destroys the rendering context of this HardwareRenderer. This destroys the resources
associated with this renderer and releases the currently set `https://developer.android.com/reference/android/view/Surface`. This must
be called when this HardwareRenderer is no longer needed.
The renderer may be restored from this state by setting a new `https://developer.android.com/reference/android/view/Surface`, setting
new rendering content with `https://developer.android.com/reference/android/graphics/HardwareRenderer#setContentRoot(android.graphics.RenderNode)`, and resuming
rendering by issuing a new `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest`.
It is recommended to call this in response to callbacks such as
`https://developer.android.com/reference/android/view/SurfaceHolder.Callback#surfaceDestroyed(android.view.SurfaceHolder)`.
Note that if there are any outstanding frame commit callbacks they may never being
invoked if the frame was deferred to a later vsync.
### isDrawingEnabled
Added in [API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static boolean isDrawingEnabled ()
```
Returns true if HardwareRender will produce output.
This value is global to the process and affects all uses of HardwareRenderer,
including
those created by the system such as those used by the View tree when using hardware
accelerated rendering.
Default is true in all production environments, but may be false in testing-focused
emulators or if `https://developer.android.com/reference/android/graphics/HardwareRenderer#setDrawingEnabled(boolean)` is used.
| Returns ||
|---|---|
| `boolean` |
|
### isOpaque
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public boolean isOpaque ()
```
Whether or not the renderer is set to be opaque. See `https://developer.android.com/reference/android/graphics/HardwareRenderer#setOpaque(boolean)`
| Returns ||
|---|---|
| `boolean` | true if the renderer is opaque, false otherwise
|
### notifyFramePending
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void notifyFramePending ()
```
Notifies the hardware renderer that a call to `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest#syncAndDraw()` will
be coming soon. This is used to help schedule when RenderThread-driven animations will
happen as the renderer wants to avoid producing more than one frame per vsync signal.
### setContentRoot
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 RenderNode's
contained within the content node, will be applied whenever a new `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest`
is issued via `https://developer.android.com/reference/android/graphics/HardwareRenderer#createRenderRequest()` and `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest#syncAndDraw()`.
| Parameters ||
|---|---|
| `content` | `RenderNode`: The content to set as the root RenderNode. If null the content root is removed and the renderer will draw nothing.
|
### setDrawingEnabled
Added in [API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static void setDrawingEnabled (boolean drawingEnabled)
```
Toggles whether or not HardwareRenderer will produce drawing output globally in the current
process.
This applies to all HardwareRenderer instances, including those created by the platform such
as those used by the system for hardware accelerated View rendering.
The capability to disable drawing output is intended for test environments, primarily
headless ones. By setting this to false, tests that launch activities or interact with Views
can be quicker with less RAM usage by skipping the final step of View drawing. All View
lifecycle events will occur as normal, only the final step of rendering on the GPU to the
display will be skipped.
This can be toggled on and off at will, so screenshot tests can also run in this same
environment by toggling drawing back on and forcing a frame to be drawn such as by calling
view#invalidate(). Once drawn and the screenshot captured, this can then be turned back off.
| Parameters ||
|---|---|
| `drawingEnabled` | `boolean`
|
### setLightSourceAlpha
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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
`https://developer.android.com/reference/android/R.attr#spotShadowAlpha` and `https://developer.android.com/reference/android/R.attr#ambientShadowAlpha`.
This must be set at least once along with
`https://developer.android.com/reference/android/graphics/HardwareRenderer#setLightSourceGeometry(float,%20float,%20float,%20float)` 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 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 platform's recommendation is to set lightX to 'displayWidth / 2f - windowLeft', set
lightY to 0 - windowTop, lightZ set to 600dp, and lightRadius to 800dp.
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/android/graphics/HardwareRenderer#setLightSourceAlpha(float,%20float)`
before shadows will work.
| Parameters ||
|---|---|
| `lightX` | `float`: The X position of the light source
|
| `lightY` | `float`: The Y position of the light source
|
| `lightZ` | `float`: The Z position of the light source. Must be \>= 0.
|
| `lightRadius` | `float`: The radius of the light source. Smaller radius will have sharper edges, larger radius will have softer shadows.
|
### setName
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void setName (String name)
```
Sets a name for this renderer. This is used to identify this renderer instance
when reporting debug information such as the per-window frame time metrics
reported by 'adb shell dumpsys gfxinfo \[package\] framestats'
| Parameters ||
|---|---|
| `name` | `String`: The debug name to use for this HardwareRenderer instance. This value cannot be `null`.
|
### setOpaque
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void setOpaque (boolean opaque)
```
Change the HardwareRenderer's opacity. Will take effect on the next frame produced.
If the renderer is set to opaque it is the app's responsibility to ensure that the
content renders to every pixel of the Surface, otherwise corruption may result. Note that
this includes ensuring that the first draw of any given pixel does not attempt to blend
against the destination. If this is false then the hardware renderer will clear to
transparent at the start of every frame.
| Parameters ||
|---|---|
| `opaque` | `boolean`: true if the content rendered is opaque, false if the renderer should clear to transparent before rendering
|
### setSurface
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void setSurface (Surface surface)
```
The surface to render into. The surface is assumed to be associated with the display and
as such is still driven by vsync signals such as those from
`https://developer.android.com/reference/android/view/Choreographer` and that it has a native refresh rate matching that of
the display's (typically 60hz).
NOTE: Due to the shared, cooperative nature of the render thread it is critical that
any `https://developer.android.com/reference/android/view/Surface` used must have a prompt, reliable consuming side. System-provided
consumers such as `https://developer.android.com/reference/android/view/SurfaceView`,
`https://developer.android.com/reference/android/view/Window#takeSurface(android.view.SurfaceHolder.Callback2)`,
or `https://developer.android.com/reference/android/view/TextureView` all fit this requirement. However if custom consumers
are used such as when using `https://developer.android.com/reference/android/graphics/SurfaceTexture` or `https://developer.android.com/reference/android/media/ImageReader`
it is the app's responsibility to ensure that they consume updates promptly and rapidly.
Failure to do so will cause the render thread to stall on that surface, blocking all
HardwareRenderer instances.
| Parameters ||
|---|---|
| `surface` | `Surface`: The surface to render into. If null then rendering will be stopped. If non-null then `https://developer.android.com/reference/android/view/Surface#isValid()` must be true.
|
### start
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void start ()
```
Resumes rendering into the surface. Any pending rendering requests
will produce a new frame at the next vsync signal.
This is useful in combination with lifecycle events such as `https://developer.android.com/reference/android/app/Activity#onStart()`.
See `https://developer.android.com/reference/android/graphics/HardwareRenderer#stop()` for stopping rendering.
### stop
Added in [API level 29](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void stop ()
```
Hard stops rendering into the surface. If the renderer is stopped it will
block any attempt to render. Calls to `https://developer.android.com/reference/android/graphics/HardwareRenderer.FrameRenderRequest#syncAndDraw()` will
still sync over the latest rendering content, however they will not render and instead
`https://developer.android.com/reference/android/graphics/HardwareRenderer#SYNC_CONTEXT_IS_STOPPED` will be returned.
This is useful in combination with lifecycle events such as `https://developer.android.com/reference/android/app/Activity#onStop()`.
See `https://developer.android.com/reference/android/graphics/HardwareRenderer#start()` for resuming rendering.