IImageReadback
Functions
Detailed Description
-
class IImageReadback : public RED::IREDObject
This interface gives access to the image readback’s properties.
@related Readback Images, class RED::IImage
A readback image is intended to retrieve the contents of a buffer directly from the video memory. It’s created using the RED::IResourceManager::CreateImageReadback method. A readback image is also implementing the RED::IImage2D interface.
A readback image must be used carefully. On a RED::IImageReadback::GetPixels call, it’ll stall the rendering pipeline and extract the contents of the targeted buffer using an internal glReadPixels call. Main window buffers are double buffers with front and back buffers. If a buffer swap has occurred at the end of the drawing operation, then the contents of the back buffer (always targeted by the GetPixels call) may be undefined, depending on the operating system and on the buffer swapping method implemented by the graphic driver of the graphic card (buffer copy or buffer exchange). Note that REDsdk can’t provide any guarantee on the internal behavior of the buffer swapping method chosen by the hardware manufacturer.
For non critical performance operations, it’s better to create a 2D image and to set it as a RED::IImage2D::SetRenderImage on the targeted VRL, or to directly access a VRL’s render image using RED::IViewpointRenderList::GetRenderImage. Then a simple call to GetPixels will retrieve the contents of the buffer, without having to handle hardware issues mentioned above.
For an in-depth coverage of the images in REDsdk, please read: \ref bk_images (see \ref bk_im_readback_images for specific documentation about readback images).
Public Functions
-
virtual RED_RC GetPixels(RED::Object *iVRL, RED::Object *iViewpoint, int iStateNumber = -1) = 0
Retrieves pixels from a VRL’s buffer.
This is a synchronous GPU call that stalls the rendering pipeline to proceed with the retrieval of the VRL’s buffer contents. Read pixels are stored in the local pixel storage of the image (a readback image also implements the RED::IImage2D interface).
As this method directly accesses to the internal video memory of the graphic card, the layout of the RED::FMT_RGBA may be BGRA with a swap of the blue and red bytes. Most video adapters have an internal BGRA memory layout.
- Parameters
iVRL – The VRL source of the image (the buffer).
iViewpoint – The read viewport region. This parameter can be NULL. In this case, the full VRL region is read back.
iStateNumber – Queried state.
- Returns
RED_OK when the modification succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal memory allocation did fail,
RED_FAIL if a graphic driver error occurred.
-
virtual RED_RC GetPixels(RED::Object *iVRL, RED::Object *iViewpoint, int iStateNumber = -1) = 0
