ListenableGlesRenderer2

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


ListenableFuture-based compatibility wrapper around Renderer.GlesRenderer's suspending methods.

Summary

Public constructors

<SharedAssetsT extends Renderer.SharedAssets> ListenableGlesRenderer2(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis,
    @NonNull int[] eglConfigAttribList,
    @NonNull int[] eglSurfaceAttribList
)

Public methods

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

final void

Called once a background thread when a new GL context is created on the background thread, before any subsequent calls to render.

final void
onUiThreadGlSurfaceCreated(@Px int width, @Px int height)

Called when a new GL surface is created on the UiThread, before any subsequent calls to render or in response to SurfaceHolder.Callback.surfaceChanged.

final void

Inside of a Mutex this function sets the GL context associated with the WatchFaceService.getBackgroundThreadHandler's looper thread as the current one, executes runnable and finally unsets the GL context.

final void

Inside of a Mutex this function sets the UiThread GL context as the current one, executes runnable and finally unsets the GL context.

Protected methods

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

@NonNull ListenableFuture<Unit>

Called once a background thread when a new GL context is created on the background thread, before any subsequent calls to render.

@NonNull ListenableFuture<Unit>
@UiThread
onUiThreadGlSurfaceCreatedFuture(@Px int width, @Px int height)

Called when a new GL surface is created on the UiThread, before any subsequent calls to render and in response to SurfaceHolder.Callback.surfaceChanged.

Inherited methods

From androidx.wear.watchface.Renderer
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 float

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

final float

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

final long

The interval in milliseconds between frames in interactive DrawModes.

@NonNull Rect

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

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.

final WatchFaceColors

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

final void

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

void

Called when the RenderParameters has been updated.

final void

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

final void

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

final void

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

final void
setInteractiveDrawModeUpdateDelayMillis(
    long interactiveDrawModeUpdateDelayMillis
)
final void

The SurfaceHolder that renderInternal will draw into.

final void

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

boolean

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

From androidx.wear.watchface.Renderer.GlesRenderer
final @NonNull EGLContext

The GlesRenderer's background Thread EGLContext.

final @NonNull EGLConfig

The GlesRenderer's EGLConfig.

final @NonNull EGLDisplay

The GlesRenderer's EGLDisplay.

final @NonNull EGLContext

The GlesRenderer's UiThread EGLContext.

void

Called when the Renderer is destroyed.

void

Called when adb shell dumpsys is invoked for the WatchFaceService, allowing the renderer to optionally record state for debugging purposes.

final void

Inside of a Mutex this function sets the GL context associated with the WatchFaceService.getBackgroundThreadHandler's looper thread as the current one, executes commands and finally unsets the GL context.

final void
runUiThreadGlCommands(@NonNull SuspendFunction0<Unit> commands)

Inside of a Mutex this function sets the UiThread GL context as the current one, executes commands and finally unsets the GL context.

final void

This method is deprecated. It's not intended for eglConfig to be set

final void

This method is deprecated. It's not intended for eglDisplay to be set

From androidx.wear.watchface.Renderer.GlesRenderer2
final int

If an eglConfigAttribListList is specified then each list of attributes will be tried in turn by EGL14.eglChooseConfig.

final void
render(@NonNull ZonedDateTime zonedDateTime)

Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters.

abstract void
@UiThread
render(
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull SharedAssetsT sharedAssets
)

Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters.

final void

Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters.

abstract void
@UiThread
renderHighlightLayer(
    @NonNull ZonedDateTime zonedDateTime,
    @NonNull SharedAssetsT sharedAssets
)

Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters.

Public constructors

ListenableGlesRenderer2

public <SharedAssetsT extends Renderer.SharedAssets> ListenableGlesRenderer2(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis,
    @NonNull int[] eglConfigAttribList,
    @NonNull int[] eglSurfaceAttribList
)

Public methods

createSharedAssetsFuture

Added in 1.1.0
@WorkerThread
public abstract @NonNull ListenableFuture<@NonNull SharedAssetsT> createSharedAssetsFuture()

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). It is safe to make GLES calls within this method.

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. The watch face library constructs shared GLES contexts to allow resource sharing between threads.

Returns
@NonNull ListenableFuture<@NonNull SharedAssetsT>

A ListenableFuture for the SharedAssetsT that will be passed into render and renderHighlightLayer

onBackgroundThreadGlContextCreated

Added in 1.1.0
public final void onBackgroundThreadGlContextCreated()

Called once a background thread when a new GL context is created on the background thread, before any subsequent calls to render. Note this function is called inside a lambda passed to runBackgroundThreadGlCommands which has synchronized access to the GL context.

If you need to override this method in java, consider using androidx.wear.watchface.ListenableGlesRenderer instead.

onUiThreadGlSurfaceCreated

Added in 1.1.0
public final void onUiThreadGlSurfaceCreated(@Px int width, @Px int height)

Called when a new GL surface is created on the UiThread, before any subsequent calls to render or in response to SurfaceHolder.Callback.surfaceChanged. Note this function is called inside a lambda passed to runUiThreadGlCommands which has synchronized access to the GL context.

If you need to override this method in java, consider using androidx.wear.watchface.ListenableGlesRenderer instead.

Parameters
@Px int width

width of surface in pixels

@Px int height

height of surface in pixels

runBackgroundThreadGlCommands

Added in 1.1.0
@WorkerThread
public final void runBackgroundThreadGlCommands(@NonNull Runnable runnable)

Inside of a Mutex this function sets the GL context associated with the WatchFaceService.getBackgroundThreadHandler's looper thread as the current one, executes runnable and finally unsets the GL context.

Access to the GL context this way is necessary because GL contexts are not shared between renderers and there can be multiple watch face instances existing concurrently (e.g. headless and interactive, potentially from different watch faces if an APK contains more than one WatchFaceService).

NB this function is called by the library before running runBackgroundThreadGlCommands so there's no need to use this directly in client code unless you need to make GL calls outside of those methods.

Throws
kotlin.IllegalStateException

if the calls to EGL14.eglMakeCurrent fails

runUiThreadGlCommands

Added in 1.1.0
@UiThread
public final void runUiThreadGlCommands(@NonNull Runnable runnable)

Inside of a Mutex this function sets the UiThread GL context as the current one, executes runnable and finally unsets the GL context.

Access to the GL context this way is necessary because GL contexts are not shared between renderers and there can be multiple watch face instances existing concurrently (e.g. headless and interactive, potentially from different watch faces if an APK contains more than one WatchFaceService).

Throws
kotlin.IllegalStateException

if the calls to EGL14.eglMakeCurrent fails

Protected methods

createSharedAssets

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

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). It is safe to make GLES calls within this method.

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. The watch face library constructs shared GLES contexts to allow resource sharing between threads.

Returns
@NonNull SharedAssetsT

The SharedAssetsT that will be passed into render and renderHighlightLayer.

onBackgroundThreadGlContextCreatedFuture

Added in 1.1.0
protected @NonNull ListenableFuture<UnitonBackgroundThreadGlContextCreatedFuture()

Called once a background thread when a new GL context is created on the background thread, before any subsequent calls to render. Note this function is called inside a lambda passed to runBackgroundThreadGlCommands which has synchronized access to the GL context. Note cancellation of the returned future is not supported.

Returns
@NonNull ListenableFuture<Unit>

A ListenableFuture which is resolved when background thread work has completed. Rendering will be blocked until this has resolved.

onUiThreadGlSurfaceCreatedFuture

Added in 1.1.0
@UiThread
protected @NonNull ListenableFuture<UnitonUiThreadGlSurfaceCreatedFuture(@Px int width, @Px int height)

Called when a new GL surface is created on the UiThread, before any subsequent calls to render and in response to SurfaceHolder.Callback.surfaceChanged. Note this function is called inside a lambda passed to Renderer.GlesRenderer.runUiThreadGlCommands which has synchronized access to the GL context. Note cancellation of the returned future is not supported.

Parameters
@Px int width

width of surface in pixels

@Px int height

height of surface in pixels

Returns
@NonNull ListenableFuture<Unit>

A ListenableFuture which is resolved when UI thread work has completed. Rendering will be blocked until this has resolved.