Renderer.CanvasRenderer

public abstract class Renderer.CanvasRenderer extends Renderer

Object
   ↳ Renderer
     ↳ Renderer.CanvasRenderer
Known direct subclasses
ListenableCanvasRenderer

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


Watch faces that require Canvas rendering 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.ListenableCanvasRenderer instead.

Summary

Public constructors

CanvasRenderer(
    SurfaceHolder surfaceHolder,
    CurrentUserStyleRepository currentUserStyleRepository,
    WatchState watchState,
    @CanvasType int canvasType,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis
)

Public methods

@UiThread 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.

abstract @UiThread void
render(Canvas canvas, Rect bounds, ZonedDateTime zonedDateTime)

Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters.

abstract @UiThread void
renderHighlightLayer(
    Canvas canvas,
    Rect bounds,
    ZonedDateTime zonedDateTime
)

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

Inherited methods

From class Renderer
@UiThread @NonNull Rect

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

final @UiThread void

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

@UiThread void

Called when the Renderer is destroyed.

final void

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

@UiThread boolean

The system periodically (at least once per minute) calls onTimeTick() to trigger a display update.

Public constructors

CanvasRenderer

@WorkerThread
public final CanvasRenderer(
    SurfaceHolder surfaceHolder,
    CurrentUserStyleRepository currentUserStyleRepository,
    WatchState watchState,
    @CanvasType int canvasType,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis
)
Parameters
SurfaceHolder surfaceHolder

The SurfaceHolder from which a Canvas to will be obtained and passed into render.

CurrentUserStyleRepository currentUserStyleRepository

The watch face's associated CurrentUserStyleRepository.

WatchState watchState

The watch face's associated WatchState.

@CanvasType int canvasType

The type of canvas to request.

@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.

Public methods

init

@UiThread
public void init()

Perform UiThread specific initialization. Will be called once during initialization before any subsequent calls to render. If you need to override this method in java, consider using androidx.wear.watchface.ListenableCanvasRenderer instead.

onDump

public void onDump(PrintWriter writer)

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

render

@UiThread
public abstract void render(Canvas canvas, Rect bounds, 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.