Method Detail

• setDisplayInfo

   void setDisplayInfo(@NonNull() Renderer.DisplayInfo info)

  Information about the display this Renderer is associated to. This information is neededto accurately compute dynamic-resolution scaling and for frame-pacing.

• getDisplayInfo

  @NonNull() Renderer.DisplayInfo getDisplayInfo()

  Returns the DisplayInfo object set in setDisplayInfo or a new instance otherwise.

• setFrameRateOptions

   void setFrameRateOptions(@NonNull() Renderer.FrameRateOptions options)

  Set options controlling the desired frame-rate.

• getFrameRateOptions

  @NonNull() Renderer.FrameRateOptions getFrameRateOptions()

  Returns the FrameRateOptions object set in setFrameRateOptions or a new instanceotherwise.

• setClearOptions

   void setClearOptions(@NonNull() Renderer.ClearOptions options)

  Set ClearOptions which are used at the beginning of a frame to clear or retain theSwapChain content.

• getClearOptions

  @NonNull() Renderer.ClearOptions getClearOptions()

  Returns the ClearOptions object set in setClearOptions or a new instanceotherwise.

• getEngine

  @NonNull() Engine getEngine()

  Gets the Engine that created this Renderer.

• setPresentationTime

   void setPresentationTime(long monotonicClockNanos)

  Set the time at which the frame must be presented to the display.

  This must be called between beginFrame and endFrame.

  Parameters:

  monotonicClockNanos - The time in nanoseconds corresponding to the system monotonicup-time clock.

• beginFrame

   boolean beginFrame(@NonNull() SwapChain swapChain, long frameTimeNanos)

  Sets up a frame for this Renderer.

  beginFrame manages frame pacing, and returns whether or not a frame should bedrawn. The goal of this is to skip frames when the GPU falls behind in order to keep the framelatency low.

  If a given frame takes too much time in the GPU, the CPU will get ahead of the GPU. Thedisplay will draw the same frame twice producing a stutter. At this point, the CPU isahead of the GPU and depending on how many frames are buffered, latency increases.beginFrame() attempts to detect this situation and returns false in that case,indicating to the caller to skip the current frame.

  All calls to render() must happen after beginFrame().

  Parameters:

  swapChain - the SwapChain instance to use

  frameTimeNanos - The time in nanoseconds when the frame started being rendered,in the nanoTime timebase.

• endFrame

   void endFrame()

  Finishes the current frame and schedules it for display.

  endFrame() schedules the current frame to be displayed on theRenderer's window.

  All calls to render() must happen before endFrame().

• render

   void render(@NonNull() View view)

  Renders a View into this Renderer's window.

  This is filament's main rendering method, most of the CPU-side heavy lifting is performedhere. The purpose of the render() function is to generate render commands whichare asynchronously executed by the Engine's render thread.

  render() generates commands for each of the following stages:

  • Shadow map passes, if needed
  • Depth pre-pass
  • SSAO pass, if enabled
  • Color pass
  • Post-processing pass

  A typical render loop looks like this:

  void renderLoop(Renderer renderer, SwapChain swapChain) {
      do {
          // typically we wait for VSYNC and user input events
          if (renderer.beginFrame(swapChain)) {
              renderer.render(mView);
              renderer.endFrame();
          }
      } while (!quit());
  }
  

  • render() must be called afterbeginFrame and beforeendFrame.
  • render() must be called from the Engine's main thread(or external synchronization must be provided). In particular, calls to render()on different Renderer instances must be synchronized.
  • render() performs potentially heavy computations and cannot be multi-threaded.However, internally, it is highly multi-threaded to both improve performance and mitigatethe call's latency.
  • render() is typically called once per frame (but not necessarily).

  Parameters:

  view - the View to render

• renderStandaloneView

   void renderStandaloneView(@NonNull() View view)

  Renders a standalone View into its associated RenderTarget.

  This call is mostly equivalent to calling render inside a beginFrame / endFrame block, but incurs less overhead. It can be usedas a poor man's compute API.

  • renderStandaloneView() must be called outside of beginFrame / endFrame.
  • renderStandaloneView() must be called from the Engine's main thread(or external synchronization must be provided). In particular, calls torenderStandaloneView() on different Renderer instances mustbe synchronized.
  • renderStandaloneView() performs potentially heavy computations and cannot bemulti-threaded. However, internally, it is highly multi-threaded to both improve performanceand mitigate the call's latency.

  Parameters:

  view - the View to render.

• copyFrame

   void copyFrame(@NonNull() SwapChain dstSwapChain, @NonNull() Viewport dstViewport, @NonNull() Viewport srcViewport, int flags)

  Copies the currently rendered View to the indicated SwapChain, using theindicated source and destination rectangle.

  copyFrame() should be called after a frame is rendered using render but before endFrame is called.

  Parameters:

  dstSwapChain - the SwapChain into which the frame should be copied

  dstViewport - the destination rectangle in which to draw the view

  srcViewport - the source rectangle to be copied

  flags - one or more CopyFrameFlag behavior configuration flags

• mirrorFrame

  @Deprecated() void mirrorFrame(@NonNull() SwapChain dstSwapChain, @NonNull() Viewport dstViewport, @NonNull() Viewport srcViewport, int flags)

• readPixels

   void readPixels(@IntRange(from = 0) int xoffset, @IntRange(from = 0) int yoffset, @IntRange(from = 0) int width, @IntRange(from = 0) int height, @NonNull() Texture.PixelBufferDescriptor buffer)

  Reads back the content of the SwapChain associated with this Renderer.

  
   Framebuffer as seen on         User buffer (PixelBufferDescriptor)
   screen
   +--------------------+
   |                    |                .stride         .alignment
   |                    |         ----------------------->-->
   |                    |         O----------------------+--+   low addresses
   |                    |         |          |           |  |
   |             w      |         |          | .top      |  |
   |       <--------->  |         |          V           |  |
   |       +---------+  |         |     +---------+      |  |
   |       |     ^   |  | ======> |     |         |      |  |
   |   x   |    h|   |  |         |.left|         |      |  |
   +------>|     v   |  |         +---->|         |      |  |
   |       +.........+  |         |     +.........+      |  |
   |            ^       |         |                      |  |
   |          y |       |         +----------------------+--+  high addresses
   O------------+-------+
  
  

  readPixels must be called within a frame, meaning after beginFrame and before endFrame. Typically, readPixels will be called after render.

  After calling this method, the callback associated with bufferwill be invoked on the main thread, indicating that the read-back has completed.Typically, this will happen after multiple calls to beginFrame, render, endFrame.

  readPixels is intended for debugging and testing.It will impact performance significantly.

  Parameters:

  xoffset - left offset of the sub-region to read back

  yoffset - bottom offset of the sub-region to read back

  width - width of the sub-region to read back

  height - height of the sub-region to read back

  buffer - client-side buffer where the read-back will be writtenThe following format are always supported:RGBARGBA_INTEGERThe following types are always supported:UBYTEUINTINTFLOATOther combination of format/type may be supported.

• readPixels

   void readPixels(@NonNull() RenderTarget renderTarget, @IntRange(from = 0) int xoffset, @IntRange(from = 0) int yoffset, @IntRange(from = 0) int width, @IntRange(from = 0) int height, @NonNull() Texture.PixelBufferDescriptor buffer)

  Reads back the content of a specified RenderTarget.

  
   Framebuffer as seen on         User buffer (PixelBufferDescriptor)
   screen
   +--------------------+
   |                    |                .stride         .alignment
   |                    |         ----------------------->-->
   |                    |         O----------------------+--+   low addresses
   |                    |         |          |           |  |
   |             w      |         |          | .top      |  |
   |       <--------->  |         |          V           |  |
   |       +---------+  |         |     +---------+      |  |
   |       |     ^   |  | ======> |     |         |      |  |
   |   x   |    h|   |  |         |.left|         |      |  |
   +------>|     v   |  |         +---->|         |      |  |
   |       +.........+  |         |     +.........+      |  |
   |            ^       |         |                      |  |
   |          y |       |         +----------------------+--+  high addresses
   O------------+-------+
  
  

  Typically readPixels will be called after render and before endFrame.

  After calling this method, the callback associated with bufferwill be invoked on the main thread, indicating that the read-back has completed.Typically, this will happen after multiple calls to beginFrame, render, endFrame.

  OpenGL only: if issuing a readPixels on a RenderTarget backed by a Texture that had data uploaded to it via setImage, the data returnedfrom readPixels will be y-flipped with respect to the setImage call.

  readPixels is intended for debugging and testing.It will impact performance significantly.

  Parameters:

  renderTarget - RenderTarget to read back from

  xoffset - left offset of the sub-region to read back

  yoffset - bottom offset of the sub-region to read back

  width - width of the sub-region to read back

  height - height of the sub-region to read back

  buffer - client-side buffer where the read-back will be writtenThe following format are always supported:RGBARGBA_INTEGERThe following types are always supported:UBYTEUINTINTFLOATOther combination of format/type may be supported.

• getUserTime

   double getUserTime()

  Returns a timestamp (in seconds) for the last call to beginFrame. This value isconstant for all views rendered during a frame. The epoch is set with resetUserTime.

  In materials, this value can be queried using vec4 getUserTime(). The valuereturned is a highp vec4 encoded as follows:

       time.x = (float)Renderer.getUserTime();
       time.y = Renderer.getUserTime() - time.x;
  

  It follows that the following invariants are true:

       (double)time.x + (double)time.y == Renderer.getUserTime()
       time.x == (float)Renderer.getUserTime()
  

  This encoding allows the shader code to perform high precision (i.e. double) timecalculations when needed despite the lack of double precision in the shader, e.g.:To compute (double)time * vertex in the material, use the following construct:

               vec3 result = time.x * vertex + time.y * vertex;
  

  Most of the time, high precision computations are not required, but be aware that theprecision of time.x rapidly diminishes as time passes:

  In other words, it is only possible to get microsecond accuracy for about 16s or millisecondaccuracy for just under 5h. This problem can be mitigated by calling resetUserTime,or using high precision time as described above.

• resetUserTime

   void resetUserTime()

  Sets the user time epoch to now, i.e. resets the user time to zero.

  Use this method used to keep the precision of time high in materials, in practice it shouldbe called at least when the application is paused, e.g.Activity.onPause in Android.

• getNativeObject

   long getNativeObject()