Renderer


public sealed class Renderer

Renderer.CanvasRenderer

This class is deprecated. CanvasRenderer is deprecated

Renderer.GlesRenderer

This class is deprecated. GlesRenderer is deprecated

ListenableCanvasRenderer2

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

ListenableCanvasRenderer

This class is deprecated. Use ListenableCanvasRenderer2 instead

ListenableGlesRenderer2

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

ListenableGlesRenderer

This class is deprecated. Use ListenableGlesRenderer2 instead

Renderer.CanvasRenderer2

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Renderer.GlesRenderer2

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.


The base class for CanvasRenderer, CanvasRenderer2, GlesRenderer, GlesRenderer2. Where possible it is recommended to use CanvasRenderer2 or GlesRenderer2 which allow memory to be saved during editing because there can be more than one watchface instance during editing.

Renderers are constructed on a background thread but all rendering is done on the UiThread. There is a memory barrier between construction and rendering so no special threading primitives are required.

It is recommended to set watchfaceColors with representative WatchFaceColors this is used by compatible systems to influence the system's color scheme.

Please note android.graphics.drawable.AnimatedImageDrawable and similar classes which rely on android.graphics.drawable.Drawable.Callback do not animate properly out of the box unless you register an implementation with android.graphics.drawable.Drawable.setCallback that calls invalidate. Even then these classes are not recommend because the ZonedDateTime passed to Renderer.CanvasRenderer.render or Renderer.GlesRenderer.render is not guaranteed to match the system time (e.g. for taking screenshots). In addition care is needed when implementing android.graphics.drawable.Drawable.Callback to ensure it does not animate in ambient mode which could lead to a significant power regression.

use Watch Face Format instead

Summary

Nested types

public abstract class Renderer.CanvasRenderer extends Renderer

This class is deprecated. CanvasRenderer is deprecated

public abstract class Renderer.CanvasRenderer2<SharedAssetsT extends Renderer.SharedAssets> extends Renderer.CanvasRenderer

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

public abstract class Renderer.GlesRenderer extends Renderer

This class is deprecated. GlesRenderer is deprecated

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

public abstract class Renderer.GlesRenderer2<SharedAssetsT extends Renderer.SharedAssets> extends Renderer.GlesRenderer

This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

public interface Renderer.SharedAssets

This interface is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Protected constructors

@WorkerThread
Renderer(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis
)

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Public methods

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

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final float

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final float

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final long

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

@NonNull Rect

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final @NonNull RenderParameters

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final @NonNull Rect

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final @NonNull SurfaceHolder

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final WatchFaceColors

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

abstract void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final void
setInteractiveDrawModeUpdateDelayMillis(
    long interactiveDrawModeUpdateDelayMillis
)

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

boolean

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Protected methods

void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

final void

This method is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead.

Protected constructors

Renderer

@WorkerThread
protected Renderer(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis
)
Parameters
@NonNull SurfaceHolder surfaceHolder

The SurfaceHolder that renderInternal will draw into.

@NonNull CurrentUserStyleRepository currentUserStyleRepository

The associated CurrentUserStyleRepository.

@NonNull WatchState watchState

The associated WatchState.

@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 frame rate inorder to sleep when not animating. In ambient mode the watch face will be rendered once per minute.

Public methods

getAdditionalContentDescriptionLabels

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final @NonNull Collection<@NonNull Pair<@NonNull Integer, @NonNull ContentDescriptionLabel>> getAdditionalContentDescriptionLabels()

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.

getCenterX

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final float getCenterX()

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

getCenterY

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final float getCenterY()

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

getInteractiveDrawModeUpdateDelayMillis

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final long getInteractiveDrawModeUpdateDelayMillis()

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. In ambient mode the watch face will be rendered once per minute.

getMainClockElementBounds

Added in 1.0.0
Deprecated in 1.3.0-alpha06
@UiThread
public @NonNull Rect getMainClockElementBounds()

This method is used for accessibility support to describe the portion of the screen containing the main clock element. By default we assume this is contained in the central half of the watch face. Watch faces should override this to return the correct bounds for the main clock element.

Returns
@NonNull Rect

A Rect describing the bounds of the watch faces' main clock element

getRenderParameters

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final @NonNull RenderParameters getRenderParameters()

The current RenderParameters. Updated before every onDraw call.

getScreenBounds

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final @NonNull Rect getScreenBounds()

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.

getSurfaceHolder

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final @NonNull SurfaceHolder getSurfaceHolder()

The SurfaceHolder that renderInternal will draw into.

getWatchfaceColors

Added in 1.2.0
Deprecated in 1.3.0-alpha06
@WatchFaceExperimental
public final WatchFaceColors getWatchfaceColors()

Representative WatchFaceColors which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.

Initially this value is null signifying that the colors are unknown. When possible the watchFace should assign non null WatchFaceColors and keep this updated when the colors change (e.g. due to a style change).

invalidate

Added in 1.0.0
Deprecated in 1.3.0-alpha06
@UiThread
public final void invalidate()

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

onDestroy

Added in 1.0.0
Deprecated in 1.3.0-alpha06
@UiThread
public void onDestroy()

Called when the Renderer is destroyed.

onDump

Added in 1.0.0
Deprecated in 1.3.0-alpha06
@UiThread
public abstract 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.

postInvalidate

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final void postInvalidate()

Posts a message to schedule a call to either CanvasRenderer.render or GlesRenderer.render to draw the next frame. Unlike invalidate, this method is thread-safe and may be called on any thread.

sendPreviewImageNeedsUpdateRequest

Added in 1.2.0
Deprecated in 1.3.0-alpha06
public final void sendPreviewImageNeedsUpdateRequest()

Sends a request to the system asking it to update the preview image. This is useful for watch faces with configuration outside of the UserStyleSchema E.g. a watchface with a selectable background.

The system may choose to rate limit this method for performance reasons and the system is free to schedule when the update occurs.

Requires a compatible system to work (if the system is incompatible this does nothing). This can be called from any thread.

setAdditionalContentDescriptionLabels

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public 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 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.

setInteractiveDrawModeUpdateDelayMillis

Added in 1.0.0
Deprecated in 1.3.0-alpha06
public final void setInteractiveDrawModeUpdateDelayMillis(
    long interactiveDrawModeUpdateDelayMillis
)
Parameters
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. In ambient mode the watch face will be rendered once per minute.

setWatchfaceColors

Added in 1.2.0
Deprecated in 1.3.0-alpha06
@WatchFaceExperimental
public final void setWatchfaceColors(
    @WatchFaceExperimental WatchFaceColors watchfaceColors
)

Representative WatchFaceColors which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.

Initially this value is null signifying that the colors are unknown. When possible the watchFace should assign non null WatchFaceColors and keep this updated when the colors change (e.g. due to a style change).

shouldAnimate

Added in 1.0.0
Deprecated in 1.3.0-alpha06
@UiThread
public boolean shouldAnimate()

The system periodically (at least once per minute) calls onTimeTick() to trigger a display update. If the watch face needs to animate with an interactive frame rate, calls to invalidate must be scheduled. This method controls whether or not we should do that and if shouldAnimate returns true we inhibit entering DrawMode.AMBIENT.

By default we remain at an interactive frame rate when the watch face is visible and we're not in ambient mode. Watch faces with animated transitions for entering ambient mode may need to override this to ensure they play smoothly.

Returns
boolean

Whether we should schedule an onDraw call to maintain an interactive frame rate

Protected methods

onRenderParametersChanged

Added in 1.0.0
Deprecated in 1.3.0-alpha06
@UiThread
protected void onRenderParametersChanged(@NonNull RenderParameters renderParameters)

Called when the RenderParameters has been updated. Will always be called before the first call to CanvasRenderer.render or GlesRenderer.render.

setSurfaceHolder

Added in 1.2.0
Deprecated in 1.3.0-alpha06
protected final void setSurfaceHolder(@NonNull SurfaceHolder surfaceHolder)

The SurfaceHolder that renderInternal will draw into.