Renderer.GlesRenderer2
public abstract class Renderer.GlesRenderer2<SharedAssetsT extends Renderer.SharedAssets> extends Renderer.GlesRenderer
| java.lang.Object | |||
| ↳ | androidx.wear.watchface.Renderer | ||
| ↳ | androidx.wear.watchface.Renderer.GlesRenderer | ||
| ↳ | androidx.wear.watchface.Renderer.GlesRenderer2 | ||
ListenableGlesRenderer2 |
|
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 extends Renderer.SharedAssets> |
The type extending |
| Throws | |
|---|---|
androidx.wear.watchface.Renderer.GlesRenderer.GlesException |
If any GL calls fail during initialization. |
Summary
Public constructors |
|---|
@WorkerThreadConstructs a |
@WorkerThread |
Public methods |
|
|---|---|
final int |
If an eglConfigAttribListList is specified then each list of attributes will be tried in turn by |
final void |
render(@NonNull ZonedDateTime zonedDateTime)Sub-classes should override this to implement their watch face rendering logic which should respect the current |
abstract void |
@UiThreadSub-classes should override this to implement their watch face rendering logic which should respect the current |
final void |
renderHighlightLayer(@NonNull ZonedDateTime zonedDateTime)Sub-classes should override this to implement their watch face highlight layer rendering logic for the |
abstract void |
@UiThreadSub-classes should override this to implement their watch face highlight layer rendering logic for the |
Protected methods |
|
|---|---|
abstract @NonNull SharedAssetsT |
When editing multiple |
Inherited methods |
||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||||||||||||||||||||||||||||||||||
|
Public constructors
GlesRenderer2
@WorkerThread
public <SharedAssetsT extends Renderer.SharedAssets> GlesRenderer2(
@NonNull SurfaceHolder surfaceHolder,
@NonNull CurrentUserStyleRepository currentUserStyleRepository,
@NonNull WatchState watchState,
@IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis,
@NonNull int[] eglConfigAttribList,
@NonNull int[] eglSurfaceAttribList,
@NonNull int[] eglContextAttribList
)
Constructs a GlesRenderer2.
| Parameters | |
|---|---|
<SharedAssetsT extends Renderer.SharedAssets> |
The type extending |
@NonNull SurfaceHolder surfaceHolder |
The |
@NonNull CurrentUserStyleRepository currentUserStyleRepository |
The associated |
@NonNull WatchState watchState |
The associated |
@IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis |
The interval in milliseconds between frames in interactive |
@NonNull int[] eglConfigAttribList |
Attributes for |
@NonNull int[] eglSurfaceAttribList |
The attributes to be passed to |
@NonNull int[] eglContextAttribList |
The attributes to be passed to |
| Throws | |
|---|---|
androidx.wear.watchface.Renderer.GlesRenderer.GlesException |
If any GL calls fail during initialization. |
GlesRenderer2
@WorkerThread
public <SharedAssetsT extends Renderer.SharedAssets> GlesRenderer2(
@NonNull SurfaceHolder surfaceHolder,
@NonNull CurrentUserStyleRepository currentUserStyleRepository,
@NonNull WatchState watchState,
@IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis,
@NonNull List<@NonNull int[]> eglConfigAttribListList,
@NonNull int[] eglSurfaceAttribList,
@NonNull int[] eglContextAttribList
)
| Parameters | |
|---|---|
<SharedAssetsT extends Renderer.SharedAssets> |
The type extending |
@NonNull SurfaceHolder surfaceHolder |
The |
@NonNull CurrentUserStyleRepository currentUserStyleRepository |
The associated |
@NonNull WatchState watchState |
The associated |
@IntRange(from = 0, to = 60000) long interactiveDrawModeUpdateDelayMillis |
The interval in milliseconds between frames in interactive |
@NonNull List<@NonNull int[]> eglConfigAttribListList |
A list of attributes to be tried in turn by |
@NonNull int[] eglSurfaceAttribList |
The attributes to be passed to |
@NonNull int[] eglContextAttribList |
The attributes to be passed to |
Public methods
getSelectedEglConfigAttribListIndex
public final int getSelectedEglConfigAttribListIndex()
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.
render
public final void render(@NonNull ZonedDateTime zonedDateTime)
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 | |
|---|---|
@NonNull ZonedDateTime zonedDateTime |
The zonedDateTime |
render
@UiThread
public abstract void 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. 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 | |
|---|---|
@NonNull ZonedDateTime zonedDateTime |
The zonedDateTime |
@NonNull SharedAssetsT sharedAssets |
The |
renderHighlightLayer
public final void renderHighlightLayer(@NonNull ZonedDateTime zonedDateTime)
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 | |
|---|---|
@NonNull ZonedDateTime zonedDateTime |
The zonedDateTime |
renderHighlightLayer
@UiThread
public abstract void 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. 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 | |
|---|---|
@NonNull ZonedDateTime zonedDateTime |
The zonedDateTime |
@NonNull SharedAssetsT sharedAssets |
The |
Protected methods
createSharedAssets
@WorkerThread
protected abstract @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 |