Renderer.CanvasRenderer2

Artifact: androidx.wear.watchface:watchface

Added in 1.1.0

Kotlin |Java

abstract class Renderer.CanvasRenderer2<SharedAssetsT : Renderer.SharedAssets> : Renderer.CanvasRenderer

kotlin.Any
↳	androidx.wear.watchface.Renderer
	↳	androidx.wear.watchface.Renderer.CanvasRenderer
		↳	androidx.wear.watchface.Renderer.CanvasRenderer2

Known direct subclasses

ListenableCanvasRenderer2

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 : Renderer.SharedAssets>`	The type extending `SharedAssets` returned by `createSharedAssets` and passed into `render` and `renderHighlightLayer`.

Summary

Public constructors
`@WorkerThread <SharedAssetsT : Renderer.SharedAssets> CanvasRenderer2( surfaceHolder: SurfaceHolder, currentUserStyleRepository: CurrentUserStyleRepository, watchState: WatchState, canvasType: Int, interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long, clearWithBackgroundTintBeforeRenderingHighlightLayer: Boolean )`

Public functions
`final Unit`	`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 render( canvas: Canvas, bounds: Rect, zonedDateTime: ZonedDateTime, sharedAssets: SharedAssetsT )` Sub-classes should override this to implement their watch face rendering logic which should respect the current `renderParameters`.
`final Unit`	`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`.
`abstract Unit`	`@UiThread renderHighlightLayer( canvas: Canvas, bounds: Rect, zonedDateTime: ZonedDateTime, sharedAssets: SharedAssetsT )` Sub-classes should override this to implement their watch face highlight layer rendering logic for the `RenderParameters.highlightLayer` aspect of `renderParameters`.

Protected functions
`abstract suspend SharedAssetsT`	`@WorkerThread 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.

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.

From androidx.wear.watchface.Renderer.CanvasRenderer

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

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.

From androidx.wear.watchface.Renderer.CanvasRenderer

Boolean

clearWithBackgroundTintBeforeRenderingHighlightLayer

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

Public constructors

CanvasRenderer2

@WorkerThread
<SharedAssetsT : Renderer.SharedAssets> CanvasRenderer2(
    surfaceHolder: SurfaceHolder,
    currentUserStyleRepository: CurrentUserStyleRepository,
    watchState: WatchState,
    canvasType: Int,
    interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long,
    clearWithBackgroundTintBeforeRenderingHighlightLayer: Boolean
)

Parameters
`<SharedAssetsT : Renderer.SharedAssets>`	The type extending `SharedAssets` returned by `createSharedAssets` and passed into `render` and `renderHighlightLayer`.
`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`	Whether the `Canvas` is cleared with `RenderParameters.HighlightLayer.backgroundTint` before `renderHighlightLayer` is called. Defaults to `false`.

Public functions

render

Added in 1.3.0-alpha04

final 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

render

Added in 1.1.0

@UiThread
abstract fun render(
    canvas: Canvas,
    bounds: Rect,
    zonedDateTime: ZonedDateTime,
    sharedAssets: SharedAssetsT
): Unit

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
`sharedAssets: SharedAssetsT`	The `SharedAssetsT` returned by `createSharedAssets`

renderHighlightLayer

Added in 1.3.0-alpha04

final 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

renderHighlightLayer

Added in 1.1.0

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

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
`sharedAssets: SharedAssetsT`	The `SharedAssetsT` returned by `createSharedAssets`

Protected functions

createSharedAssets

@WorkerThread
protected abstract suspend fun createSharedAssets(): 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.

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
`SharedAssetsT`	The `SharedAssetsT` that will be passed into `render` and `renderHighlightLayer`.