Package 

Class UiHelper

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

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      public enum UiHelper.ContextErrorPolicy

      Enum used to decide whether UiHelper should perform extra error checking.
      public interface UiHelper.RendererCallback

      Interface used to know when the native surface is created, destroyed or resized.

    • Constructor Summary

      Constructors 
      Constructor Description
      UiHelper() Creates a UiHelper which will help manage the native surface provided by aSurfaceView or a TextureView.
      UiHelper(UiHelper.ContextErrorPolicy policy) Creates a UiHelper which will help manage the native surface provided by aSurfaceView or a TextureView.

    • Method Summary

      Modifier and Type Method Description
      void setRenderCallback(@Nullable() UiHelper.RendererCallback renderCallback) Sets the renderer callback that will be notified when the native surface iscreated, destroyed or resized.
      UiHelper.RendererCallback getRenderCallback() Returns the current render callback associated with this UiHelper.
      void detach() Free resources associated to the native window specified in attachTo, attachTo, or attachTo.
      boolean isReadyToRender() Checks whether we are ready to render into the attached surface.Using OpenGL ES when this returns true, will result in drawing commands being lost,HOWEVER, GLES state will be preserved.
      void setDesiredSize(int width, int height) Set the size of the render target buffers of the native surface.
      int getDesiredWidth() Returns the requested width for the native surface.
      int getDesiredHeight() Returns the requested height for the native surface.
      boolean isOpaque() Returns true if the render target is opaque.
      void setOpaque(boolean opaque) Controls whether the render target (SurfaceView or TextureView) is opaque or not.The render target is considered opaque by default.
      boolean isMediaOverlay() Returns true if the SurfaceView used as a render target should be positioned aboveother surfaces but below the activity's surface.
      void setMediaOverlay(boolean overlay) Controls whether the surface of the SurfaceView used as a render target should bepositioned above other surfaces but below the activity's surface.
      long getSwapChainFlags() Returns the flags to pass to createSwapChain to honor allthe options set on this UiHelper.
      void attachTo(@NonNull() SurfaceView view) Associate UiHelper with a SurfaceView.As soon as SurfaceView is ready (i.e.
      void attachTo(@NonNull() TextureView view) Associate UiHelper with a TextureView.As soon as TextureView is ready (i.e.
      void attachTo(@NonNull() SurfaceHolder holder) Associate UiHelper with a SurfaceHolder.As soon as a Surface is created, we'll create theEGL resources needed, and call user callbacks if needed.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • UiHelper

        UiHelper()
        Creates a UiHelper which will help manage the native surface provided by aSurfaceView or a TextureView.

      • UiHelper

        UiHelper(UiHelper.ContextErrorPolicy policy)
        Creates a UiHelper which will help manage the native surface provided by aSurfaceView or a TextureView.
        Parameters:
        policy - The error checking policy to use.

    • Method Detail

      • setRenderCallback

         void setRenderCallback(@Nullable() UiHelper.RendererCallback renderCallback)

        Sets the renderer callback that will be notified when the native surface iscreated, destroyed or resized.

        Parameters:
        renderCallback - The callback to register.

      • isReadyToRender

         boolean isReadyToRender()

        Checks whether we are ready to render into the attached surface.Using OpenGL ES when this returns true, will result in drawing commands being lost,HOWEVER, GLES state will be preserved. This is useful to initialize the engine.

      • setDesiredSize

         void setDesiredSize(int width, int height)

        Set the size of the render target buffers of the native surface.

      • getDesiredWidth

         int getDesiredWidth()

        Returns the requested width for the native surface.

      • getDesiredHeight

         int getDesiredHeight()

        Returns the requested height for the native surface.

      • isOpaque

         boolean isOpaque()

        Returns true if the render target is opaque.

      • setOpaque

         void setOpaque(boolean opaque)

        Controls whether the render target (SurfaceView or TextureView) is opaque or not.The render target is considered opaque by default.Must be called before calling attachTo, attachTo,or attachTo.

        Parameters:
        opaque - Indicates whether the render target should be opaque.

      • isMediaOverlay

         boolean isMediaOverlay()

        Returns true if the SurfaceView used as a render target should be positioned aboveother surfaces but below the activity's surface. False by default.

      • setMediaOverlay

         void setMediaOverlay(boolean overlay)

        Controls whether the surface of the SurfaceView used as a render target should bepositioned above other surfaces but below the activity's surface. This propertyonly has an effect when used in combination with setOpaque(false) and does not affect TextureView targets.Must be called before calling attachTo or attachTo.Has no effect when using attachTo.

        Parameters:
        overlay - Indicates whether the render target should be rendered below the activity'ssurface when transparent.

      • attachTo

         void attachTo(@NonNull() SurfaceView view)

        Associate UiHelper with a SurfaceView.As soon as SurfaceView is ready (i.e. has a Surface), we'll create theEGL resources needed, and call user callbacks if needed.

      • attachTo

         void attachTo(@NonNull() TextureView view)

        Associate UiHelper with a TextureView.As soon as TextureView is ready (i.e. has a buffer), we'll create theEGL resources needed, and call user callbacks if needed.

      • attachTo

         void attachTo(@NonNull() SurfaceHolder holder)

        Associate UiHelper with a SurfaceHolder.As soon as a Surface is created, we'll create theEGL resources needed, and call user callbacks if needed.