Renderer

public class Renderer

Known direct subclasses
Renderer.CanvasRenderer

Watch faces that require Canvas rendering should extend their Renderer from this class.

Renderer.GlesRenderer

Watch faces that require GLES20 rendering should extend their Renderer from this class.


The base class for CanvasRenderer and GlesRenderer. 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.

Summary

Nested types

Renderer.CanvasRenderer

Watch faces that require Canvas rendering should extend their Renderer from this class.

Renderer.GlesRenderer

Watch faces that require GLES20 rendering should extend their Renderer from this class.

Renderer.GlesRenderer.GlesException

Exception thrown if a GL call fails

Public fields

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

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

final @Px float

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

final @Px float

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

final long

The interval in milliseconds between frames in interactive DrawModes.

final @NonNull RenderParameters

The current RenderParameters.

final @NonNull Rect

The bounds of the SurfaceHolder this Renderer renders into.

final @NonNull SurfaceHolder

The SurfaceHolder that renderInternal will draw into.

Public methods

@UiThread @NonNull Rect

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

final @UiThread void

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

@UiThread void

Called when the Renderer is destroyed.

final void

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

@UiThread boolean

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

Public fields

additionalContentDescriptionLabels

@NonNull
public final @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.

centerX

@Px
@NonNull
public final @Px float centerX

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

centerY

@Px
@NonNull
public final @Px float centerY

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

interactiveDrawModeUpdateDelayMillis

@NonNull
public final 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.

renderParameters

@NonNull
public final @NonNull RenderParameters renderParameters

The current RenderParameters. Updated before every onDraw call.

screenBounds

@NonNull
public final @NonNull Rect screenBounds

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.

surfaceHolder

@NonNull
public final @NonNull SurfaceHolder surfaceHolder

The SurfaceHolder that renderInternal will draw into.

Public methods

getMainClockElementBounds

@UiThread
@NonNull
public @UiThread 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
@UiThread Rect

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

invalidate

@UiThread
@NonNull
public final @UiThread void invalidate()

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

onDestroy

@UiThread
@NonNull
public @UiThread void onDestroy()

Called when the Renderer is destroyed.

postInvalidate

@NonNull
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.

shouldAnimate

@UiThread
@NonNull
public @UiThread 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
@UiThread boolean

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