docs/android/dokka/filament-android/com.google.android.filament.android/-ui-helper/index.md
//filament-android/com.google.android.filament.android/UiHelper
[main]
open class UiHelper
UiHelper is a simple class that can manage either a SurfaceView, TextureView, or a SurfaceHolder so it can be used to render into with Filament. Here is a simple example with a SurfaceView. The code would be exactly the same with a TextureView:
public class FilamentActivity extends Activity {
private UiHelper mUiHelper;
private SurfaceView mSurfaceView;
// Filament specific APIs
private Engine mEngine;
private Renderer mRenderer;
private View mView; // com.google.android.filament.View, not android.view.View
private SwapChain mSwapChain;
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Create a SurfaceView and add it to the activity
mSurfaceView = new SurfaceView(this);
setContentView(mSurfaceView);
// Create the Filament UI helper
mUiHelper = new UiHelper(UiHelper.ContextErrorPolicy.DONT_CHECK);
// Attach the SurfaceView to the helper, you could do the same with a TextureView
mUiHelper.attachTo(mSurfaceView);
// Set a rendering callback that we will use to invoke Filament
mUiHelper.setRenderCallback(new UiHelper.RendererCallback() {
public void onNativeWindowChanged(Surface surface) {
if (mSwapChain != null) mEngine.destroySwapChain(mSwapChain);
mSwapChain = mEngine.createSwapChain(surface, mUiHelper.getSwapChainFlags());
}
// The native surface went away, we must stop rendering.
public void onDetachedFromSurface() {
if (mSwapChain != null) {
mEngine.destroySwapChain(mSwapChain);
// Required to ensure we don't return before Filament is done executing the
// destroySwapChain command, otherwise Android might destroy the Surface
// too early
mEngine.flushAndWait();
mSwapChain = null;
}
}
// The native surface has changed size. This is always called at least once
// after the surface is created (after onNativeWindowChanged() is invoked).
public void onResized(int width, int height) {
// Wait for all pending frames to be processed before returning. This is to
// avoid a race between the surface being resized before pending frames are
// rendered into it.
Fence fence = mEngine.createFence();
fence.wait(Fence.Mode.FLUSH, Fence.WAIT_FOR_EVER);
mEngine.destroyFence(fence);
// Compute camera projection and set the viewport on the view
}
});
mEngine = Engine.create();
mRenderer = mEngine.createRenderer();
mView = mEngine.createView();
// Create scene, camera, etc.
}
public void onDestroy() {
super.onDestroy();
// Always detach the surface before destroying the engine
mUiHelper.detach();
mEngine.destroy();
}
// This is an example of a render function. You will most likely invoke this from
// a Choreographer callback to trigger rendering at vsync.
public void render() {
if (mUiHelper.isReadyToRender) {
// If beginFrame() returns false you should skip the frame
// This means you are sending frames too quickly to the GPU
if (mRenderer.beginFrame(swapChain)) {
mRenderer.render(mView);
mRenderer.endFrame();
}
}
}
}
| UiHelper | [main] |
| constructor() | |
| Creates a UiHelper which will help manage the native surface provided by a SurfaceView or a TextureView. | |
| constructor(policy: UiHelper.ContextErrorPolicy) | |
| Creates a UiHelper which will help manage the native surface provided by a SurfaceView or a TextureView. |
| Name | Summary |
|---|---|
| ContextErrorPolicy | [main] |
| enum ContextErrorPolicy | |
| Enum used to decide whether UiHelper should perform extra error checking. | |
| RendererCallback | [main] |
| interface RendererCallback | |
| Interface used to know when the native surface is created, destroyed or resized. |
| Name | Summary |
|---|---|
| attachTo | [main] |
| open fun attachTo(holder: SurfaceHolder) | |
| Associate UiHelper with a SurfaceHolder. | |
| [main] | |
| open fun attachTo(view: SurfaceView) | |
| Associate UiHelper with a SurfaceView. | |
| [main] | |
| open fun attachTo(view: TextureView) | |
| Associate UiHelper with a TextureView. | |
| detach | [main] |
| open fun detach() | |
| Free resources associated to the native window specified in attachTo, attachTo, or attachTo. | |
| getDesiredHeight | [main] |
| open fun getDesiredHeight(): Int | |
| Returns the requested height for the native surface. | |
| getDesiredWidth | [main] |
| open fun getDesiredWidth(): Int | |
| Returns the requested width for the native surface. | |
| getRenderCallback | [main] |
| open fun getRenderCallback(): UiHelper.RendererCallback | |
| Returns the current render callback associated with this UiHelper. | |
| getSwapChainFlags | [main] |
| open fun getSwapChainFlags(): Long | |
| Returns the flags to pass to createSwapChain to honor all the options set on this UiHelper. | |
| isMediaOverlay | [main] |
| open fun isMediaOverlay(): Boolean | |
| Returns true if the SurfaceView used as a render target should be positioned above other surfaces but below the activity's surface. | |
| isOpaque | [main] |
| open fun isOpaque(): Boolean | |
| Returns true if the render target is opaque. | |
| isReadyToRender | [main] |
| open fun isReadyToRender(): Boolean | |
| Checks whether we are ready to render into the attached surface. | |
| setDesiredSize | [main] |
| open fun setDesiredSize(width: Int, height: Int) | |
| Set the size of the render target buffers of the native surface. | |
| setMediaOverlay | [main] |
| open fun setMediaOverlay(overlay: Boolean) | |
| Controls whether the surface of the SurfaceView used as a render target should be positioned above other surfaces but below the activity's surface. | |
| setOpaque | [main] |
| open fun setOpaque(opaque: Boolean) | |
| Controls whether the render target (SurfaceView or TextureView) is opaque or not. | |
| setRenderCallback | [main] |
| open fun setRenderCallback(renderCallback: UiHelper.RendererCallback) | |
| Sets the renderer callback that will be notified when the native surface is created, destroyed or resized. |