//filament-android/com.google.android.filament/Renderer/readPixels

readPixels

[main]
open fun readPixels(xoffset: Int, yoffset: Int, width: Int, height: Int, buffer: Texture.PixelBufferDescriptor)

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

kotlin


 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 issuing this method, the callback associated with buffer will be invoked on the main thread, indicating that the read-back has completed. Typically, this will happen after multiple calls to beginFrame, render, endFrame.

It is also possible to use a Fence to wait for the read-back.

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

Parameters

main


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 written
The following format are always supported:
RGBA RGBA_INTEGER
The following types are always supported:
UBYTE UINT INT FLOAT
Other combination of format/type may be supported. If a combination is not supported, this operation may fail silently. Use a DEBUG build to get some logs about the failure.

Throws


BufferOverflowException	if the specified parameters would result in reading outside of `buffer`.

[main]
open fun readPixels(renderTarget: RenderTarget, xoffset: Int, yoffset: Int, width: Int, height: Int, buffer: Texture.PixelBufferDescriptor)

Reads back the content of a specified RenderTarget.