Renderer.CanvasRenderer

Artifact: androidx.wear.watchface:watchface

Added in 1.0.0

Deprecated in 1.1.0

Kotlin |Java

abstract class Renderer.CanvasRenderer : Renderer

kotlin.Any
↳	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( surfaceHolder: SurfaceHolder, currentUserStyleRepository: CurrentUserStyleRepository, watchState: WatchState, canvasType: Int, interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long, clearWithBackgroundTintBeforeRenderingHighlightLayer: Boolean )`

Public functions
`open suspend Unit`	`@UiThread init()` Perform UiThread specific initialization.
`open Unit`	`onDump(writer: PrintWriter)` Called when adb shell dumpsys is invoked for the WatchFaceService, allowing the renderer to optionally record state for debugging purposes.
`abstract Unit`	`@UiThread render(canvas: Canvas, bounds: Rect, zonedDateTime: ZonedDateTime)` Sub-classes should override this to implement their watch face rendering logic which should respect the current `renderParameters`.
`abstract Unit`	`@UiThread renderHighlightLayer( canvas: Canvas, bounds: Rect, zonedDateTime: ZonedDateTime )` Sub-classes should override this to implement their watch face highlight layer rendering logic for the `RenderParameters.highlightLayer` aspect of `renderParameters`.

Public properties
`Boolean`	`clearWithBackgroundTintBeforeRenderingHighlightLayer` Whether the `Canvas` is cleared with `RenderParameters.HighlightLayer.backgroundTint` before `renderHighlightLayer` is called.

Inherited functions

From androidx.wear.watchface.Renderer

`open Rect`	`@UiThread getMainClockElementBounds()` This method is used for accessibility support to describe the portion of the screen containing the main clock element.
`Unit`	`@UiThread invalidate()` Schedules a call to either `CanvasRenderer.render` or `GlesRenderer.render` to draw the next frame.
`open Unit`	`@UiThread onDestroy()` Called when the Renderer is destroyed.
`open Unit`	`@UiThread onRenderParametersChanged(renderParameters: RenderParameters)` Called when the `RenderParameters` has been updated.
`Unit`	`postInvalidate()` Posts a message to schedule a call to either `CanvasRenderer.render` or `GlesRenderer.render` to draw the next frame.
`Unit`	`sendPreviewImageNeedsUpdateRequest()` Sends a request to the system asking it to update the preview image.
`open Boolean`	`@UiThread shouldAnimate()` The system periodically (at least once per minute) calls onTimeTick() to trigger a display update.

Inherited properties

From androidx.wear.watchface.Renderer

`Collection<Pair<Int, ContentDescriptionLabel>>`	`additionalContentDescriptionLabels` Accessibility `ContentDescriptionLabel` for any rendered watch face elements other than the time and `ComplicationSlot`s which are generated automatically.
`@Px Float`	`centerX` The center x coordinate of the `SurfaceHolder` this Renderer renders into.
`@Px Float`	`centerY` The center y coordinate of the `SurfaceHolder` this Renderer renders into.
`Long`	`interactiveDrawModeUpdateDelayMillis` The interval in milliseconds between frames in interactive `DrawMode`s.
`RenderParameters`	`renderParameters` The current `RenderParameters`.
`Rect`	`screenBounds` The bounds of the `SurfaceHolder` this Renderer renders into.
`SurfaceHolder`	`surfaceHolder` The `SurfaceHolder` that `renderInternal` will draw into.
`WatchFaceColors?`	`@WatchFaceExperimental watchfaceColors` Representative `WatchFaceColors` which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.

Public constructors

CanvasRenderer

Added in 1.1.0

Deprecated in 1.1.0

@WorkerThread
CanvasRenderer(
    surfaceHolder: SurfaceHolder,
    currentUserStyleRepository: CurrentUserStyleRepository,
    watchState: WatchState,
    canvasType: Int,
    interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long,
    clearWithBackgroundTintBeforeRenderingHighlightLayer: Boolean = false
)

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`	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.
`interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long`	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.
`clearWithBackgroundTintBeforeRenderingHighlightLayer: Boolean = false`	Whether the `Canvas` is cleared with `RenderParameters.HighlightLayer.backgroundTint` before `renderHighlightLayer` is called. Defaults to `false`.

Public functions

init

Added in 1.0.0

Deprecated in 1.1.0

@UiThread
open suspend fun init(): Unit

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-alpha03

Deprecated in 1.3.0-alpha03

open fun onDump(writer: PrintWriter): Unit

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
abstract fun render(canvas: Canvas, bounds: Rect, zonedDateTime: ZonedDateTime): Unit

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
`canvas: Canvas`	The `Canvas` to render into. Don't assume this is always the canvas from the `SurfaceHolder` backing the display
`bounds: Rect`	A `Rect` describing the bonds of the canvas to draw into
`zonedDateTime: ZonedDateTime`	The `ZonedDateTime` to render with

renderHighlightLayer

Added in 1.0.0

Deprecated in 1.1.0

@UiThread
abstract fun renderHighlightLayer(
    canvas: Canvas,
    bounds: Rect,
    zonedDateTime: ZonedDateTime
): Unit

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
`canvas: Canvas`	The `Canvas` to render into. Don't assume this is always the canvas from the `SurfaceHolder` backing the display
`bounds: Rect`	A `Rect` describing the bonds of the canvas to draw into
`zonedDateTime: ZonedDateTime`	the `ZonedDateTime` to render with

Public properties

clearWithBackgroundTintBeforeRenderingHighlightLayer

Added in 1.1.0

Deprecated in 1.1.0

val clearWithBackgroundTintBeforeRenderingHighlightLayer: Boolean

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