Renderer.GlesRenderer2

Artifact: androidx.wear.watchface:watchface

View Source

Added in 1.1.0

---

Kotlin |Java

abstract class Renderer.GlesRenderer2<SharedAssetsT : Renderer.SharedAssets> : Renderer.GlesRenderer

kotlin.Any
↳	androidx.wear.watchface.Renderer
	↳	androidx.wear.watchface.Renderer.GlesRenderer
		↳	androidx.wear.watchface.Renderer.GlesRenderer2

Known direct subclasses

ListenableGlesRenderer2

ListenableGlesRenderer2

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

---

Watch faces that require GLES20 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. OpenGL objects created by createSharedAssets will be available to all instances of the watch face on both threads.

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 and are shared by all instances of the renderer. 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.ListenableGlesRenderer2 instead.

Parameters
<SharedAssetsT : Renderer.SharedAssets>	The type extending SharedAssets returned by createSharedAssets and passed into render and renderHighlightLayer.

Throws
androidx.wear.watchface.Renderer.GlesRenderer.GlesException	If any GL calls fail during initialization.

Summary

Public constructors
@WorkerThread <SharedAssetsT : Renderer.SharedAssets> GlesRenderer2(     surfaceHolder: SurfaceHolder,     currentUserStyleRepository: CurrentUserStyleRepository,     watchState: WatchState,     interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long,     eglConfigAttribList: IntArray,     eglSurfaceAttribList: IntArray,     eglContextAttribList: IntArray ) Constructs a GlesRenderer2.
@WorkerThread <SharedAssetsT : Renderer.SharedAssets> GlesRenderer2(     surfaceHolder: SurfaceHolder,     currentUserStyleRepository: CurrentUserStyleRepository,     watchState: WatchState,     interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long,     eglConfigAttribListList: List<IntArray>,     eglSurfaceAttribList: IntArray,     eglContextAttribList: IntArray )

Public functions
final Unit	render(zonedDateTime: ZonedDateTime) Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters.
abstract Unit	@UiThread render(zonedDateTime: ZonedDateTime, sharedAssets: SharedAssetsT) Sub-classes should override this to implement their watch face rendering logic which should respect the current renderParameters.
final Unit	renderHighlightLayer(zonedDateTime: ZonedDateTime) Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters.
abstract Unit	@UiThread renderHighlightLayer(     zonedDateTime: ZonedDateTime,     sharedAssets: SharedAssetsT ) Sub-classes should override this to implement their watch face highlight layer rendering logic for the RenderParameters.highlightLayer aspect of renderParameters.

Protected functions
abstract suspend SharedAssetsT	@WorkerThread 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.

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

Inherited functions
From androidx.wear.watchface.Renderer open Rect @UiThread getMainClockElementBounds() This method is used for accessibility support to describe the portion of the screen containing the main clock element. Unit @UiThread invalidate() Schedules a call to either CanvasRenderer.render or GlesRenderer.render to draw the next frame. open Unit @UiThread onRenderParametersChanged(renderParameters: RenderParameters) Called when the RenderParameters has been updated. Unit postInvalidate() Posts a message to schedule a call to either CanvasRenderer.render or GlesRenderer.render to draw the next frame. Unit sendPreviewImageNeedsUpdateRequest() Sends a request to the system asking it to update the preview image. open Boolean @UiThread shouldAnimate() The system periodically (at least once per minute) calls onTimeTick() to trigger a display update.
From androidx.wear.watchface.Renderer.GlesRenderer open suspend Unit @WorkerThread onBackgroundThreadGlContextCreated() Called once a background thread when a new GL context is created on the background thread, before any subsequent calls to render. open Unit @CallSuper onDestroy() Called when the Renderer is destroyed. open Unit onDump(writer: PrintWriter) Called when adb shell dumpsys is invoked for the WatchFaceService, allowing the renderer to optionally record state for debugging purposes. open suspend Unit @UiThread onUiThreadGlSurfaceCreated(width: @Px Int, height: @Px Int) Called when a new GL surface is created on the UiThread, before any subsequent calls to render or in response to SurfaceHolder.Callback.surfaceChanged. suspend Unit @WorkerThread runBackgroundThreadGlCommands(commands: suspend () -> Unit) 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. suspend Unit runUiThreadGlCommands(commands: suspend () -> Unit) Inside of a Mutex this function sets the UiThread GL context as the current one, executes commands and finally unsets the GL context.

Inherited properties
From androidx.wear.watchface.Renderer Collection<Pair<Int, ContentDescriptionLabel>> additionalContentDescriptionLabels Accessibility ContentDescriptionLabel for any rendered watch face elements other than the time and ComplicationSlots which are generated automatically. @Px Float centerX The center x coordinate of the SurfaceHolder this Renderer renders into. @Px Float centerY The center y coordinate of the SurfaceHolder this Renderer renders into. Long interactiveDrawModeUpdateDelayMillis The interval in milliseconds between frames in interactive DrawModes. RenderParameters renderParameters The current RenderParameters. Rect screenBounds The bounds of the SurfaceHolder this Renderer renders into. SurfaceHolder surfaceHolder The SurfaceHolder that renderInternal will draw into. WatchFaceColors? @WatchFaceExperimental watchfaceColors Representative WatchFaceColors which are made available to system clients via androidx.wear.watchface.client.InteractiveWatchFaceClient.OnWatchFaceColorsListener.
From androidx.wear.watchface.Renderer.GlesRenderer EGLContext eglBackgroundThreadContext The GlesRenderer's background Thread EGLContext. EGLConfig eglConfig The GlesRenderer's EGLConfig. EGLDisplay eglDisplay The GlesRenderer's EGLDisplay. EGLContext eglUiThreadContext The GlesRenderer's UiThread EGLContext.

Public constructors

GlesRenderer2

@WorkerThread
<SharedAssetsT : Renderer.SharedAssets> GlesRenderer2(
    surfaceHolder: SurfaceHolder,
    currentUserStyleRepository: CurrentUserStyleRepository,
    watchState: WatchState,
    interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long,
    eglConfigAttribList: IntArray = EGL_CONFIG_ATTRIB_LIST,
    eglSurfaceAttribList: IntArray = EGL_SURFACE_ATTRIB_LIST,
    eglContextAttribList: IntArray = EGL_CONTEXT_ATTRIB_LIST
)

Constructs a GlesRenderer2.

Parameters
<SharedAssetsT : Renderer.SharedAssets>	The type extending SharedAssets returned by createSharedAssets and passed into render and renderHighlightLayer.
surfaceHolder: SurfaceHolder	The SurfaceHolder whose android.view.Surface will draw into.
currentUserStyleRepository: CurrentUserStyleRepository	The associated CurrentUserStyleRepository.
watchState: WatchState	The associated WatchState.
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 frame rate inorder to sleep when not animating.
eglConfigAttribList: IntArray = EGL_CONFIG_ATTRIB_LIST	Attributes for EGL14.eglChooseConfig. By default this selects an RGBA8888 back buffer.
eglSurfaceAttribList: IntArray = EGL_SURFACE_ATTRIB_LIST	The attributes to be passed to EGL14.eglCreateWindowSurface. By default this is empty.
eglContextAttribList: IntArray = EGL_CONTEXT_ATTRIB_LIST	The attributes to be passed to EGL14.eglCreateContext. By default this selects EGL14.EGL_CONTEXT_CLIENT_VERSION 2.

Throws
androidx.wear.watchface.Renderer.GlesRenderer.GlesException	If any GL calls fail during initialization.

GlesRenderer2

@WorkerThread
<SharedAssetsT : Renderer.SharedAssets> GlesRenderer2(
    surfaceHolder: SurfaceHolder,
    currentUserStyleRepository: CurrentUserStyleRepository,
    watchState: WatchState,
    interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long,
    eglConfigAttribListList: List<IntArray>,
    eglSurfaceAttribList: IntArray,
    eglContextAttribList: IntArray
)

Parameters
<SharedAssetsT : Renderer.SharedAssets>	The type extending SharedAssets returned by createSharedAssets and passed into render and renderHighlightLayer.
surfaceHolder: SurfaceHolder	The SurfaceHolder whose android.view.Surface will draw into.
currentUserStyleRepository: CurrentUserStyleRepository	The associated CurrentUserStyleRepository.
watchState: WatchState	The associated WatchState.
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 frame rate inorder to sleep when not animating.
eglConfigAttribListList: List<IntArray>	A list of attributes to be tried in turn by EGL14.eglChooseConfig. The first one to succeed is chosen and its index is wrtten to selectedEglConfigAttribListIndex. If none succeed then a GlesRenderer.GlesException will be thrown. An example use of this is to define a config with MSAA (anti-aliasing) and to fall back to one without where that's not available.
eglSurfaceAttribList: IntArray	The attributes to be passed to EGL14.eglCreateWindowSurface. By default this is empty.
eglContextAttribList: IntArray	The attributes to be passed to EGL14.eglCreateContext. By default this selects EGL14.EGL_CONTEXT_CLIENT_VERSION 2.

Public functions

render

Added in 1.3.0-alpha04

final fun render(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.

Note this function is called inside a lambda passed to runUiThreadGlCommands which has synchronized access to the GL context.

Note also GLES20.glBlendFunc(GLES20.GL_ONE, GLES20.GL_ZERO) is called by the library before this method.

Before any calls to this function onBackgroundThreadGlContextCreated and onUiThreadGlSurfaceCreated will have been called once on their respective threads.

Parameters
zonedDateTime: ZonedDateTime	The zonedDateTime ZonedDateTime to render with

render

Added in 1.1.0

@UiThread
abstract fun render(zonedDateTime: ZonedDateTime, sharedAssets: SharedAssetsT): 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.

Note this function is called inside a lambda passed to runUiThreadGlCommands which has synchronized access to the GL context.

Note also GLES20.glBlendFunc(GLES20.GL_ONE, GLES20.GL_ZERO) is called by the library before this method.

Before any calls to this function onBackgroundThreadGlContextCreated and onUiThreadGlSurfaceCreated will have been called once on their respective threads. In addition if SharedAssets hasn't already been created, then a call to createSharedAssets will have been completed before calling render.

Parameters
zonedDateTime: ZonedDateTime	The zonedDateTime ZonedDateTime to render with
sharedAssets: SharedAssetsT	The SharedAssetsT returned by createSharedAssets

renderHighlightLayer

Added in 1.3.0-alpha04

final fun renderHighlightLayer(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 the buffer 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 this function is called inside a lambda passed to runUiThreadGlCommands which has synchronized access to the GL context.

Note also GLES20.glBlendFunc(GLES20.GL_ONE, GLES20.GL_ZERO) is called by the library before this method.

Parameters
zonedDateTime: ZonedDateTime	The zonedDateTime ZonedDateTime to render with

renderHighlightLayer

Added in 1.1.0

@UiThread
abstract fun renderHighlightLayer(
    zonedDateTime: ZonedDateTime,
    sharedAssets: SharedAssetsT
): 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 the buffer 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 this function is called inside a lambda passed to runUiThreadGlCommands which has synchronized access to the GL context.

Note also GLES20.glBlendFunc(GLES20.GL_ONE, GLES20.GL_ZERO) is called by the library before this method.

Parameters
zonedDateTime: ZonedDateTime	The zonedDateTime ZonedDateTime to render with
sharedAssets: SharedAssetsT	The SharedAssetsT returned by createSharedAssets

Protected functions

createSharedAssets

@WorkerThread
protected abstract suspend fun createSharedAssets(): 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.

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
SharedAssetsT	The SharedAssetsT that will be passed into render and renderHighlightLayer.

Public properties

selectedEglConfigAttribListIndex

Added in 1.3.0-alpha04

val selectedEglConfigAttribListIndex: Int

If an eglConfigAttribListList is specified then each list of attributes will be tried in turn by EGL14.eglChooseConfig. The first one to succeed is chosen and its index is written to selectedEglConfigAttribListIndex.

If an eglConfigAttribListList was not specified this will be zero. If this is accessed before the constructor has finished an exception will be thrown.