Renderer.CanvasRenderer

Added in 1.0.0
Deprecated in 1.1.0

abstract class Renderer.CanvasRenderer : Renderer

Known direct subclasses
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

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

Perform UiThread specific initialization.

open Unit

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.

Inherited functions

From androidx.wear.watchface.Renderer
open Rect

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

Unit

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

open Unit

Called when the Renderer is destroyed.

open Unit

Called when the RenderParameters has been updated.

Unit

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

Unit

Sends a request to the system asking it to update the preview image.

open Boolean

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

Inherited properties

From androidx.wear.watchface.Renderer
Collection<Pair<IntContentDescriptionLabel>>

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

@Px Float

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

@Px Float

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

Long

The interval in milliseconds between frames in interactive DrawModes.

RenderParameters

The current RenderParameters.

Rect

The bounds of the SurfaceHolder this Renderer renders into.

SurfaceHolder

The SurfaceHolder that renderInternal will draw into.

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 Bitmaps with Bitmap.Config.HARDWARE must be avoided.

interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long

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.

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-alpha04
Deprecated in 1.3.0-alpha04
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 clearWithBackgroundTintBeforeRenderingHighlightLayerBoolean

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