A render target is a specially created surface into which your rendering can be directed.
It can be created for either your own use, or for consumption by someone other than the owner (e.g., another process). If you're not rendering for your own consumption, you can set the permissions on a render target using the SCREEN_PROPERTY_PERMISSIONS property to grant or deny access to the render target you create. See the Permissions and Privileges chapter for more details.
Render targets can be used for rendering to and displaying content (on-screen), or for only rendering to (off-screen). They can have one or more buffers. The Screen API provides the following types of render targets:
| Render target | Output destination | Buffers |
|---|---|---|
| Window | On-screen | Multiple |
| Stream | Off-screen | Multiple |
| Pixmap | Off-screen | Single |
On-screen render targets have content that's intended to be visible on a display. Windows are the only on-screen render targets. Windows can be created only when Screen is running with at least one display configured (in graphics.conf).
Pixmaps and streams are off-screen render targets. They can be created when Screen is running without any displays configured.
It's possible to make the content of off-screen render targets visible. For example, you can render an image to a pixmap that you're going to use with the eventual intention of making it displayed. Or, you can render it to a stream to provide the image for someone else to consume. If you're using a pixmap, you must copy the buffer, or a region of the buffer, to a window (e.g., by using screen_blit(), OpenGL, memcpy, etc.). If you're using a stream, you can copy the buffer to a window, or share the buffers with a window using screen_share_stream_buffers(). When a window shares buffers with a stream, the window is automatically updated on the display when the stream posts. In this case, there's no need for the window to explicitly call screen_post_window().
You typically render once to a single-buffered render target, and then the rendered content is used multiple times.
Pixmaps are off-screen render targets that are restricted to one buffer. You must create this buffer with screen_create_pixmap_buffer() or attach it with screen_attach_pixmap_buffer().
You can update the contents of the pixmap's buffer using Screen's rendering APIs if you've set the usage flags appropriately before creating or attaching the pixmap buffer.
Once the pixmap's buffer has been allocated, we don't recommend changing the buffer size (SCREEN_PROPERTY_BUFFER_SIZE), usage (SCREEN_PROPERTY_USAGE), or pixel format (SCREEN_PROPERTY_FORMAT). Using screen_set_pixmap_property_iv() to set these properties will result in an error. One exception is if you change the pixel format to one whose depth is identical to the original format that was set. For example, changing between RGBA8888 and RGBX8888 is acceptable.
You typically render multiple times to a multi-buffered render target. The content is used (e.g., for displaying), then the target is rendered to again to generate updated content. Windows and streams are render targets that can have multiple buffers associated with them.
You must create window buffers with screen_create_window_buffers() or attach them with screen_attach_window_buffers(). You must create stream buffers with screen_create_stream_buffers() or attach them with screen_attach_stream_buffers(). Your application specifies the number of buffers to be created or attached through these APIs.
Once your application completes rendering to your target, you can display the content if you're using a window, or mark it ready for consumption if you're using a stream. Use screen_post_window() to display your window content and screen_post_stream() to mark the target ready for consumption.