Back to Filament

UiHelper

docs/android/dokka/filament-android/com.google.android.filament.android/-ui-helper/index.md

1.75.08.3 KB
Original Source

//filament-android/com.google.android.filament.android/UiHelper

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:

kotlin
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();
            }
        }
    }
}

Constructors

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.

Types

NameSummary
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.

Functions

NameSummary
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.