Renderer.CanvasRenderer2

public abstract class Renderer.CanvasRenderer2<SharedAssetsT extends Renderer.SharedAssets> extends Renderer.CanvasRenderer

java.lang.Object
   ↳ androidx.wear.watchface.Renderer
     ↳ androidx.wear.watchface.Renderer.CanvasRenderer
       ↳ androidx.wear.watchface.Renderer.CanvasRenderer2
Known direct subclasses
ListenableCanvasRenderer2

ListenableFuture-based compatibility wrapper around Renderer.CanvasRenderer2's suspending methods.

Watch faces that require Canvas rendering and are able to take advantage of SharedAssets to save memory (there can be more than once instance when editing), should extend their Renderer from this class.

A CanvasRenderer is expected to be constructed on the background thread associated with WatchFaceService.getBackgroundThreadHandler inside a call to WatchFaceService.createWatchFace. All rendering is be done on the UiThread. There is a memory barrier between construction and rendering so no special threading primitives are required.

In Java it may be easier to extend androidx.wear.watchface.ListenableCanvasRenderer2 instead.

Parameters
<SharedAssetsT extends Renderer.SharedAssets>

The type extending SharedAssets returned by createSharedAssets and passed into render and renderHighlightLayer.

Summary

Public constructors
@WorkerThread
<SharedAssetsT extends Renderer.SharedAssets> CanvasRenderer2(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    int canvasType,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis,
    boolean clearWithBackgroundTintBeforeRenderingHighlightLayer
)

Public methods
final void
render(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime
)

Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters.
abstract void
@UiThread
render(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull SharedAssetsT sharedAssets
)

Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters.
final void
renderHighlightLayer(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime
)

Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters.
abstract void
@UiThread
renderHighlightLayer(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull SharedAssetsT sharedAssets
)

Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters.

Protected methods
abstract @NonNull SharedAssetsT

When editing multiple WatchFaceService instances and hence Renderers can exist concurrently (e.g. a headless instance and an interactive instance) and using SharedAssets allows memory to be saved by sharing immutable data (e.g. Bitmaps, shaders, etc...) between them.

Inherited methods
From androidx.wear.watchface.Renderer
final @NonNull Collection<@NonNull Pair<@NonNull Integer, @NonNull ContentDescriptionLabel>>

Accessibility ContentDescriptionLabel for any rendered watch face elements other than the time and ComplicationSlots which are generated automatically.
final float

The center x coordinate of the SurfaceHolder this Renderer renders into.
final float

The center y coordinate of the SurfaceHolder this Renderer renders into.
final long

The interval in milliseconds between frames in interactive DrawModes.
@NonNull Rect

This method is used for accessibility support to describe the portion of the screen containing the main clock element.
final @NonNull RenderParameters

The current RenderParameters.
final @NonNull Rect

The bounds of the SurfaceHolder this Renderer renders into.
final @NonNull SurfaceHolder

The SurfaceHolder that renderInternal will draw into.
final WatchFaceColors

Representative WatchFaceColors which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.
final void

Schedules a call to either CanvasRenderer.render or GlesRenderer.render to draw the next frame.
void

Called when the Renderer is destroyed.
void

Called when the RenderParameters has been updated.
final void

Posts a message to schedule a call to either CanvasRenderer.render or GlesRenderer.render to draw the next frame.
final void

Sends a request to the system asking it to update the preview image.
final void

Accessibility ContentDescriptionLabel for any rendered watch face elements other than the time and ComplicationSlots which are generated automatically.
final void
setInteractiveDrawModeUpdateDelayMillis(
    long interactiveDrawModeUpdateDelayMillis
)
final void

The SurfaceHolder that renderInternal will draw into.
final void

Representative WatchFaceColors which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.
boolean

The system periodically (at least once per minute) calls onTimeTick() to trigger a display update.
From androidx.wear.watchface.Renderer.CanvasRenderer
final boolean

Whether the Canvas is cleared with RenderParameters.HighlightLayer.backgroundTint before renderHighlightLayer is called.
void

Perform UiThread specific initialization.
void

Called when adb shell dumpsys is invoked for the WatchFaceService, allowing the renderer to optionally record state for debugging purposes.

Public constructors

CanvasRenderer2

@WorkerThread
public <SharedAssetsT extends Renderer.SharedAssets> CanvasRenderer2(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    int canvasType,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis,
    boolean clearWithBackgroundTintBeforeRenderingHighlightLayer
)
Parameters
<SharedAssetsT extends Renderer.SharedAssets>

The type extending SharedAssets returned by createSharedAssets and passed into render and renderHighlightLayer.
@NonNull SurfaceHolder surfaceHolder

The SurfaceHolder from which a Canvas to will be obtained and passed into render.
@NonNull CurrentUserStyleRepository currentUserStyleRepository

The watch face's associated CurrentUserStyleRepository.
@NonNull WatchState watchState

The watch face's associated WatchState.
int canvasType

The CanvasTypeIntDef to request. Note even if CanvasType.HARDWARE is used, screenshots will taken using the software rendering pipeline, as such Bitmaps with Bitmap.Config.HARDWARE must be avoided.
@IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis

The interval in milliseconds between frames in interactive DrawModes. To render at 60hz set to 16. Note when battery is low, the frame rate will be clamped to 10fps. Watch faces are recommended to use lower frame rates if possible for better battery life. Variable frame rates can also help preserve battery life, e.g. if a watch face has a short animation once per second it can adjust the framerate inorder to sleep when not animating.
boolean clearWithBackgroundTintBeforeRenderingHighlightLayer

Whether the Canvas is cleared with RenderParameters.HighlightLayer.backgroundTint before renderHighlightLayer is called. Defaults to false.

Public methods

render

Added in 1.3.0-alpha04
public final void render(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime
)

Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters. Please note WatchState.isAmbient may not match the RenderParameters.drawMode and should not be used to decide what to render. E.g. when editing from the companion phone while the watch is ambient, renders may be requested with DrawMode.INTERACTIVE.

Any highlights due to RenderParameters.highlightLayer should be rendered by renderHighlightLayer instead where possible. For correct behavior this function must use the supplied ZonedDateTime in favor of any other ways of getting the time.

Before any calls to render, init will be called once.

Parameters
@NonNull Canvas canvas

The Canvas to render into. Don't assume this is always the canvas from the SurfaceHolder backing the display
@NonNull Rect bounds

A Rect describing the bonds of the canvas to draw into
@NonNull ZonedDateTime zonedDateTime

The ZonedDateTime to render with

render

Added in 1.1.0
@UiThread
public abstract void render(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull SharedAssetsT sharedAssets
)

Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters. Please note WatchState.isAmbient may not match the RenderParameters.drawMode and should not be used to decide what to render. E.g. when editing from the companion phone while the watch is ambient, renders may be requested with DrawMode.INTERACTIVE.

Any highlights due to RenderParameters.highlightLayer should be rendered by renderHighlightLayer instead where possible. For correct behavior this function must use the supplied ZonedDateTime in favor of any other ways of getting the time.

Before any calls to render, init will be called once.

Parameters
@NonNull Canvas canvas

The Canvas to render into. Don't assume this is always the canvas from the SurfaceHolder backing the display
@NonNull Rect bounds

A Rect describing the bonds of the canvas to draw into
@NonNull ZonedDateTime zonedDateTime

The ZonedDateTime to render with
@NonNull SharedAssetsT sharedAssets

The SharedAssetsT returned by createSharedAssets

renderHighlightLayer

Added in 1.3.0-alpha04
public final void renderHighlightLayer(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime
)

Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters. Typically the implementation will clear canvas to RenderParameters.HighlightLayer.backgroundTint before rendering a transparent highlight or a solid outline around the RenderParameters.HighlightLayer.highlightedElement. This will be composited as needed on top of the results of render. For correct behavior this function must use the supplied ZonedDateTime in favor of any other ways of getting the time.

Note if clearWithBackgroundTintBeforeRenderingHighlightLayer is true then canvas will cleared with RenderParameters.HighlightLayer.backgroundTint before renderHighlightLayer is called. Otherwise it is up to the overridden function to clear the Canvas if necessary.

Parameters
@NonNull Canvas canvas

The Canvas to render into. Don't assume this is always the canvas from the SurfaceHolder backing the display
@NonNull Rect bounds

A Rect describing the bonds of the canvas to draw into
@NonNull ZonedDateTime zonedDateTime

the ZonedDateTime to render with

renderHighlightLayer

Added in 1.1.0
@UiThread
public abstract void renderHighlightLayer(
    @NonNull Canvas canvas,
    @NonNull Rect bounds,
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull SharedAssetsT sharedAssets
)

Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters. Typically the implementation will clear canvas to RenderParameters.HighlightLayer.backgroundTint before rendering a transparent highlight or a solid outline around the RenderParameters.HighlightLayer.highlightedElement. This will be composited as needed on top of the results of render. For correct behavior this function must use the supplied ZonedDateTime in favor of any other ways of getting the time.

Note if clearWithBackgroundTintBeforeRenderingHighlightLayer is true then canvas will cleared with RenderParameters.HighlightLayer.backgroundTint before renderHighlightLayer is called. Otherwise it is up to the overridden function to clear the Canvas if necessary.

Parameters
@NonNull Canvas canvas

The Canvas to render into. Don't assume this is always the canvas from the SurfaceHolder backing the display
@NonNull Rect bounds

A Rect describing the bonds of the canvas to draw into
@NonNull ZonedDateTime zonedDateTime

the ZonedDateTime to render with
@NonNull SharedAssetsT sharedAssets

The SharedAssetsT returned by createSharedAssets

Protected methods

createSharedAssets

@WorkerThread
protected abstract @NonNull SharedAssetsT createSharedAssets()

When editing multiple WatchFaceService instances and hence Renderers can exist concurrently (e.g. a headless instance and an interactive instance) and using SharedAssets allows memory to be saved by sharing immutable data (e.g. Bitmaps, shaders, etc...) between them.

To take advantage of SharedAssets, override this method. The constructed SharedAssets are passed into the render as an argument (NB you'll have to cast this to your type).

When all instances using SharedAssets have been closed, SharedAssets.onDestroy will be called.

Note that while SharedAssets are constructed on a background thread, they'll typically be used on the main thread and subsequently destroyed there.

Returns
@NonNull SharedAssetsT

The SharedAssetsT that will be passed into render and renderHighlightLayer.