Package com.google.android.filament.android

Class UiHelper

  • public class UiHelper
extends java.lang.Object
    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) {
                 // 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
      static class  UiHelper.ContextErrorPolicy
      Enum used to decide whether UiHelper should perform extra error checking.
      static 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 a SurfaceView or a TextureView.
      UiHelper​(UiHelper.ContextErrorPolicy policy)
      Creates a UiHelper which will help manage the native surface provided by a SurfaceView or a TextureView.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void attachTo​(android.view.SurfaceHolder holder)
      Associate UiHelper with a SurfaceHolder.
      void attachTo​(android.view.SurfaceView view)
      Associate UiHelper with a SurfaceView.
      void attachTo​(android.view.TextureView view)
      Associate UiHelper with a TextureView.
      void detach()
      Free resources associated to the native window specified in attachTo(SurfaceView), attachTo(TextureView), or attachTo(SurfaceHolder).
      int getDesiredHeight()
      Returns the requested height for the native surface.
      int getDesiredWidth()
      Returns the requested width for the native surface.
      UiHelper.RendererCallback getRenderCallback()
      Returns the current render callback associated with this UiHelper.
      long getSwapChainFlags()
      Returns the flags to pass to Engine.createSwapChain(Object, long) to honor all the options set on this UiHelper.
      boolean isMediaOverlay()
      Returns true if the SurfaceView used as a render target should be positioned above other surfaces but below the activity's surface.
      boolean isOpaque()
      Returns true if the render target is opaque.
      boolean isReadyToRender()
      Checks whether we are ready to render into the attached surface.
      void setDesiredSize​(int width, int height)
      Set the size of the render target buffers of the native surface.
      void setMediaOverlay​(boolean overlay)
      Controls whether the surface of the SurfaceView used as a render target should be positioned above other surfaces but below the activity's surface.
      void setOpaque​(boolean opaque)
      Controls whether the render target (SurfaceView or TextureView) is opaque or not.
      void setRenderCallback​(UiHelper.RendererCallback renderCallback)
      Sets the renderer callback that will be notified when the native surface is created, destroyed or resized.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • UiHelper

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

      • UiHelper

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

    • Method Detail

      • setRenderCallback

        public void setRenderCallback​(@Nullable
                              UiHelper.RendererCallback renderCallback)
        Sets the renderer callback that will be notified when the native surface is created, destroyed or resized.
        Parameters:
        renderCallback - The callback to register.

      • getRenderCallback

        @Nullable
public UiHelper.RendererCallback getRenderCallback()
        Returns the current render callback associated with this UiHelper.

      • isReadyToRender

        public 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.
        Returns:
        true: rendering is possible, false: rendering is not possible.

      • setDesiredSize

        public void setDesiredSize​(int width,
                           int height)
        Set the size of the render target buffers of the native surface.

      • getDesiredWidth

        public int getDesiredWidth()
        Returns the requested width for the native surface.

      • getDesiredHeight

        public int getDesiredHeight()
        Returns the requested height for the native surface.

      • isOpaque

        public boolean isOpaque()
        Returns true if the render target is opaque.

      • setOpaque

        public 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(SurfaceView), attachTo(TextureView), or attachTo(SurfaceHolder).
        Parameters:
        opaque - Indicates whether the render target should be opaque. True by default.

      • isMediaOverlay

        public boolean isMediaOverlay()
        Returns true if the SurfaceView used as a render target should be positioned above other surfaces but below the activity's surface. False by default.

      • setMediaOverlay

        public void setMediaOverlay​(boolean overlay)
        Controls whether the surface of the SurfaceView used as a render target should be positioned above other surfaces but below the activity's surface. This property only has an effect when used in combination with setOpaque(false) and does not affect TextureView targets. Must be called before calling attachTo(SurfaceView) or attachTo(TextureView). Has no effect when using attachTo(SurfaceHolder).
        Parameters:
        overlay - Indicates whether the render target should be rendered below the activity's surface when transparent.

      • attachTo

        public void attachTo​(@NonNull
                     android.view.SurfaceView view)
        Associate UiHelper with a SurfaceView. As soon as SurfaceView is ready (i.e. has a Surface), we'll create the EGL resources needed, and call user callbacks if needed.

      • attachTo

        public void attachTo​(@NonNull
                     android.view.TextureView view)
        Associate UiHelper with a TextureView. As soon as TextureView is ready (i.e. has a buffer), we'll create the EGL resources needed, and call user callbacks if needed.

      • attachTo

        public void attachTo​(@NonNull
                     android.view.SurfaceHolder holder)
        Associate UiHelper with a SurfaceHolder. As soon as a Surface is created, we'll create the EGL resources needed, and call user callbacks if needed.