Renderer.GlesRenderer
abstract class Renderer.GlesRenderer : Renderer
ListenableGlesRenderer |
This class is deprecated. Use ListenableGlesRenderer2 instead |
Renderer.GlesRenderer2 |
This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
ListenableGlesRenderer2 |
This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
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 |
|---|
|
This class is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
Public constructors |
|---|
@WorkerThreadThis function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
Public functions |
|
|---|---|
open suspend Unit |
This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
open Unit |
This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
open Unit |
This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
open suspend Unit |
This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
abstract Unit |
@UiThreadThis function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
abstract Unit |
@UiThreadThis function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
suspend Unit |
@WorkerThreadThis function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
suspend Unit |
This function is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
Public properties |
|
|---|---|
EGLContext |
This property is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
EGLConfig |
This property is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
EGLDisplay |
This property is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
EGLContext |
This property is deprecated. AndroidX watchface libraries are deprecated, use Watch Face Format instead. |
Inherited functions |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Inherited properties |
||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Public constructors
@WorkerThreadGlesRenderer(
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 funonBackgroundThreadGlContextCreated(): 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 funonDump(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 funonUiThreadGlSurfaceCreated(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 funrender(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 funrenderHighlightLayer(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 funrunBackgroundThreadGlCommands(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 funrunUiThreadGlCommands(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.