Renderer.GlesRenderer
abstract class Renderer.GlesRenderer : Renderer
ListenableGlesRenderer |
This class is deprecated. Use ListenableGlesRenderer2 instead |
Renderer.GlesRenderer2 |
Watch faces that require |
ListenableGlesRenderer2 |
|
Watch faces that require GLES20 rendering should extend their Renderer from this class or GlesRenderer2 if they can take advantage of SharedAssets to save memory when editing (there can be more than once WatchFace instance when editing).
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.ListenableGlesRenderer instead.
Summary
Nested types |
|---|
|
Exception thrown if a GL call fails |
Public constructors |
|---|
@WorkerThreadConstructs a |
Public functions |
|
|---|---|
open suspend Unit |
Called once a background thread when a new GL context is created on the background thread, before any subsequent calls to |
open Unit |
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 |
Called when a new GL surface is created on the UiThread, before any subsequent calls to |
abstract Unit |
@UiThreadSub-classes should override this to implement their watch face rendering logic which should respect the current |
abstract Unit |
@UiThreadSub-classes should override this to implement their watch face highlight layer rendering logic for the |
suspend Unit |
@WorkerThreadInside of a |
suspend Unit |
runUiThreadGlCommands(commands: suspend () -> Unit)Inside of a |
Public properties |
|
|---|---|
EGLContext |
The GlesRenderer's background Thread |
EGLConfig |
The GlesRenderer's |
EGLDisplay |
The GlesRenderer's |
EGLContext |
The GlesRenderer's UiThread |
Inherited functions |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Inherited properties |
||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Public constructors
@WorkerThread
GlesRenderer(
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 GlesRenderer, it is recommended that new code uses GlesRenderer2 instead.
| Parameters | |
|---|---|
surfaceHolder: SurfaceHolder |
The |
currentUserStyleRepository: CurrentUserStyleRepository |
The associated |
watchState: WatchState |
The associated |
interactiveDrawModeUpdateDelayMillis: @IntRange(from = 0, to = 60000) Long |
The interval in milliseconds between frames in interactive |
eglConfigAttribList: IntArray = EGL_CONFIG_ATTRIB_LIST |
Attributes for |
eglSurfaceAttribList: IntArray = EGL_SURFACE_ATTRIB_LIST |
The attributes to be passed to |
eglContextAttribList: IntArray = EGL_CONTEXT_ATTRIB_LIST |
The attributes to be passed to |
| Throws | |
|---|---|
androidx.wear.watchface.Renderer.GlesRenderer.GlesException |
If any GL calls fail during initialization. |
Public functions
@WorkerThread
open suspend fun onBackgroundThreadGlContextCreated(): Unit
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.
onDump
open fun onDump(writer: PrintWriter): Unit
Called when adb shell dumpsys is invoked for the WatchFaceService, allowing the renderer to optionally record state for debugging purposes.
@UiThread
open suspend fun onUiThreadGlSurfaceCreated(width: @Px Int, height: @Px Int): Unit
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.
@UiThread
abstract 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 |
@UiThread
abstract 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 |
@WorkerThread
suspend fun runBackgroundThreadGlCommands(commands: suspend () -> Unit): 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.
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. If you need to call this method from java, consider using androidx.wear.watchface.ListenableGlesRenderer which provides an overload taking a Runnable.
| Throws | |
|---|---|
kotlin.IllegalStateException |
if the calls to |
suspend fun runUiThreadGlCommands(commands: suspend () -> Unit): Unit
Inside of a Mutex this function sets the UiThread GL context as the current one, executes commands 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).
If you need to call this method from java, consider using androidx.wear.watchface.ListenableGlesRenderer which provides an overload taking a Runnable.
| Throws | |
|---|---|
kotlin.IllegalStateException |
if the calls to |
Public properties
var eglConfig: EGLConfig
The GlesRenderer's EGLConfig.
| Throws | |
|---|---|
kotlin.UnsupportedOperationException |
setEglConfig is unsupported. |
var eglDisplay: EGLDisplay
The GlesRenderer's EGLDisplay.
| Throws | |
|---|---|
kotlin.UnsupportedOperationException |
setEglDisplay is unsupported. |
val eglUiThreadContext: EGLContext
The GlesRenderer's UiThread EGLContext. Note this not available until after WatchFaceService.createWatchFace has completed.