Renderer.CanvasRenderer

Artifact: androidx.wear.watchface:watchface

Added in 1.0.0

Deprecated in 1.1.0

Kotlin |Java

public abstract class Renderer.CanvasRenderer extends Renderer

java.lang.Object
↳	androidx.wear.watchface.Renderer
	↳	androidx.wear.watchface.Renderer.CanvasRenderer

Known direct subclasses

ListenableCanvasRenderer, Renderer.CanvasRenderer2

`ListenableCanvasRenderer`	This class is deprecated. Use ListenableCanvasRenderer2 instead
`Renderer.CanvasRenderer2`	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.

Known indirect subclasses

ListenableCanvasRenderer2

ListenableCanvasRenderer2

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

Watch faces that require Canvas rendering should extend their Renderer from this class or CanvasRenderer2 if they can take advantage of SharedAssets to save memory when editing (there can be more than once WatchFace instance when editing).

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
`@WorkerThread CanvasRenderer( @NonNull SurfaceHolder surfaceHolder, @NonNull CurrentUserStyleRepository currentUserStyleRepository, @NonNull WatchState watchState, int canvasType, @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis, boolean clearWithBackgroundTintBeforeRenderingHighlightLayer )`

Public methods
`final boolean`	`getClearWithBackgroundTintBeforeRenderingHighlightLayer()` Whether the `Canvas` is cleared with `RenderParameters.HighlightLayer.backgroundTint` before `renderHighlightLayer` is called.
`void`	`@UiThread init()` Perform UiThread specific initialization.
`void`	`onDump(@NonNull PrintWriter writer)` Called when adb shell dumpsys is invoked for the WatchFaceService, allowing the renderer to optionally record state for debugging purposes.
`abstract void`	`@UiThread 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 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 androidx.wear.watchface.Renderer

`final @NonNull Collection<@NonNull Pair<@NonNull Integer, @NonNull ContentDescriptionLabel>>`	`getAdditionalContentDescriptionLabels()` Accessibility `ContentDescriptionLabel` for any rendered watch face elements other than the time and `ComplicationSlot`s which are generated automatically.
`final float`	`getCenterX()` The center x coordinate of the `SurfaceHolder` this Renderer renders into.
`final float`	`getCenterY()` The center y coordinate of the `SurfaceHolder` this Renderer renders into.
`final long`	`getInteractiveDrawModeUpdateDelayMillis()` The interval in milliseconds between frames in interactive `DrawMode`s.
`@NonNull Rect`	`@UiThread getMainClockElementBounds()` This method is used for accessibility support to describe the portion of the screen containing the main clock element.
`final @NonNull RenderParameters`	`getRenderParameters()` The current `RenderParameters`.
`final @NonNull Rect`	`getScreenBounds()` The bounds of the `SurfaceHolder` this Renderer renders into.
`final @NonNull SurfaceHolder`	`getSurfaceHolder()` The `SurfaceHolder` that `renderInternal` will draw into.
`final WatchFaceColors`	`@WatchFaceExperimental getWatchfaceColors()` Representative `WatchFaceColors` which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.
`final void`	`@UiThread invalidate()` Schedules a call to either `CanvasRenderer.render` or `GlesRenderer.render` to draw the next frame.
`void`	`@UiThread onDestroy()` Called when the Renderer is destroyed.
`void`	`@UiThread onRenderParametersChanged(@NonNull RenderParameters renderParameters)` Called when the `RenderParameters` has been updated.
`final void`	`postInvalidate()` Posts a message to schedule a call to either `CanvasRenderer.render` or `GlesRenderer.render` to draw the next frame.
`final void`	`sendPreviewImageNeedsUpdateRequest()` Sends a request to the system asking it to update the preview image.
`final void`	`setAdditionalContentDescriptionLabels( @NonNull Collection<@NonNull Pair<@NonNull Integer, @NonNull ContentDescriptionLabel>> additionalContentDescriptionLabels )` Accessibility `ContentDescriptionLabel` for any rendered watch face elements other than the time and `ComplicationSlot`s which are generated automatically.
`final void`	`setInteractiveDrawModeUpdateDelayMillis( long interactiveDrawModeUpdateDelayMillis )`
`final void`	`setSurfaceHolder(@NonNull SurfaceHolder surfaceHolder)` The `SurfaceHolder` that `renderInternal` will draw into.
`final void`	`@WatchFaceExperimental setWatchfaceColors( @WatchFaceExperimental WatchFaceColors watchfaceColors )` Representative `WatchFaceColors` which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.
`boolean`	`@UiThread shouldAnimate()` The system periodically (at least once per minute) calls onTimeTick() to trigger a display update.

Public constructors

CanvasRenderer

Added in 1.1.0

Deprecated in 1.1.0

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

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`.
`int canvasType`	The `CanvasTypeIntDef` to request. Note even if `CanvasType.HARDWARE` is used, screenshots will taken using the software rendering pipeline, as such `Bitmap`s with `Bitmap.Config.HARDWARE` must be avoided.
`@IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis`	The interval in milliseconds between frames in interactive `DrawMode`s. 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

getClearWithBackgroundTintBeforeRenderingHighlightLayer

Added in 1.1.0

Deprecated in 1.1.0

public final boolean getClearWithBackgroundTintBeforeRenderingHighlightLayer()

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

init

Added in 1.0.0

Deprecated in 1.1.0

@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

Added in 1.3.0-alpha04

Deprecated in 1.3.0-alpha04

public void onDump(@NonNull PrintWriter writer)

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

render

Added in 1.0.0

Deprecated in 1.1.0

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

renderHighlightLayer

Added in 1.0.0

Deprecated in 1.1.0

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