Renderer.CanvasRenderer

public abstract class Renderer.CanvasRenderer extends Renderer

Object
   ↳ Renderer
     ↳ Renderer.CanvasRenderer

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.

Summary

Public fields

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 @Px float

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

final @Px float

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

final long

The interval in milliseconds between frames in interactive DrawModes.

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.

Public constructors

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

Public methods

@UiThread void

Perform UiThread specific initialization.

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

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 fields

additionalContentDescriptionLabels

@NonNull
public final @NonNull Collection<@NonNull Pair<@NonNull Integer, @NonNull ContentDescriptionLabel>> additionalContentDescriptionLabels

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

The Int in the Pair<Int, ContentDescriptionLabel> is used to sort the ContentDescriptionLabels. Note the time piece has an accessibility traversal index of -1 and each ComplicationSlot's index is defined by its ComplicationSlot.accessibilityTraversalIndex.

centerX

@Px
@NonNull
public final @Px float centerX

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

centerY

@Px
@NonNull
public final @Px float centerY

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

interactiveDrawModeUpdateDelayMillis

@NonNull
public final 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 frame rate inorder to sleep when not animating.

renderParameters

@NonNull
public final @NonNull RenderParameters renderParameters

The current RenderParameters. Updated before every onDraw call.

screenBounds

@NonNull
public final @NonNull Rect screenBounds

The bounds of the SurfaceHolder this Renderer renders into. Depending on the shape of the device's screen not all of these pixels may be visible to the user (see Configuration.isScreenRound). Note also that API level 27+ devices draw indicators in the top and bottom 24dp of the screen, avoid rendering anything important there.

surfaceHolder

@NonNull
public final @NonNull SurfaceHolder surfaceHolder

The SurfaceHolder that renderInternal will draw into.

Public constructors

CanvasRenderer

@WorkerThread
public final CanvasRenderer(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    @CanvasType int canvasType,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis
)
Parameters
@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.

@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
@NonNull
public @UiThread void init()

Perform UiThread specific initialization. Will be called once during initialization before any subsequent calls to render.

render

@UiThread
@NonNull
public abstract @UiThread 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. 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

renderHighlightLayer

@UiThread
@NonNull
public abstract @UiThread 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.

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