Renderer.GlesRenderer

public abstract class Renderer.GlesRenderer extends Renderer

Object
   ↳ Renderer
     ↳ Renderer.GlesRenderer
Known direct subclasses
ListenableGlesRenderer

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


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

A GlesRenderer 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.

Two linked EGLContexts are created eglBackgroundThreadContext and eglUiThreadContext which are associated with background and UiThread respectively. OpenGL objects created on (e.g. shaders and textures) can be used on the other.

If you need to make any OpenGl calls outside of render, onBackgroundThreadGlContextCreated or onUiThreadGlSurfaceCreated then you must use either runUiThreadGlCommands or runBackgroundThreadGlCommands to execute a Runnable inside of the corresponding context. Access to the GL contexts 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). In addition most drivers do not support concurrent access.

In Java it may be easier to extend androidx.wear.watchface.ListenableGlesRenderer instead.

Throws
androidx.wear.watchface.Renderer.GlesRenderer.GlesException

If any GL calls fail during initialization.

Summary

Nested types

Renderer.GlesRenderer.GlesException

Exception thrown if a GL call fails

Public fields

lateinit final @NonNull EGLContext

The GlesRenderer's background Thread EGLContext.

final @NonNull EGLConfig

The GlesRenderer's EGLConfig.

final @NonNull EGLDisplay

The GlesRenderer's EGLDisplay.

lateinit final @NonNull EGLContext

The GlesRenderer's UiThread EGLContext.

Public constructors

GlesRenderer(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull WatchState watchState,
    @IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis,
    @NonNull int[] eglConfigAttribList,
    @NonNull int[] eglSurfaceAttribList
)

Public methods

@WorkerThread void

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

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

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

abstract @UiThread void
render(@NonNull ZonedDateTime zonedDateTime)

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

abstract @UiThread void

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

final @WorkerThread 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

Inside of a Mutex this function sets the UiThread GL context as the current one, executes