screen_post_window()

Make window content updates visible on the display

Synopsis:

#include <screen/screen.h>

int screen_post_window(screen_window_t win,
                       screen_buffer_t buf,
                       int count,
                       const int *dirty_rects,
                       int flags)

Arguments:

win

The handle for the window whose content has changed.

buf

The rendering buffer of the window that contains the changes needed to be made visible. Most applications use two buffers for rendering. Therefore, the simplest way is to use the buffer in the first element of the SCREEN_PROPERTY_RENDER_BUFFERS property of the window. Screen rotates the buffer handles accordingly so that the first buffer handle of SCREEN_PROPERTY_RENDER_BUFFERS is one that is available.

count

The number of rectangles provided in the dirty_rects argument, or 0 to indicate that the entire buffer is dirty.

dirty_rects

An array of integers containing the x and y coordinates, width, and height of a rectangle that bounds the area of the rendering buffer that has changed since the last posting of the window. The dirty_rects argument must provide at least count * 4 integers. You can also pass NULL if you are passing 0 for the count argument.

flags

The indication of how you want this function to behave. Valid values for this parameter are:

SCREEN_WAIT_IDLE: When you use SCREEN_WAIT_IDLE, this function returns only when the display is updated with the buffer from the screen_post_window() call and at least one render buffer is available.
0: When you use 0, this function returns immediately if there is at least one render buffer available.

Library:

libscreen

Description:

Function Type: Apply Execution

This function makes some pixels in a rendering buffer visible. The pixels to be posted are defined by the dirty rectangles contained in the dirty_rects argument. Note that a window will not be made visible until screen_post_window() has been called at least once.

In addition to the area(s) defined by dirty_rects, Screen may update the other pixels in the buffer (i.e., Screen posts entire buffers, using dirty_rects as a guide). Therefore, your application must ensure that the entire contents of a window buffer is suitable for display at all times.

The use of multiple threads or application buffer management schemes to render at the full display frame rate aren't necessary because unlike equivalent calls in other graphics systems, screen_post_window() doesn't always block.

This function may cause the SCREEN_PROPERTY_RENDER_BUFFERS property of the posting window to change. At any time, only one thread must operate on, or render, to this window. If your application uses multiple threads, you must ensure that access to this window's handle by these threads is guarded. If not, SCREEN_PROPERTY_RENDER_BUFFERS may reflect out-of-date information that can lead to animation artifacts. The presentation of new content may result in a copy or a buffer flip, depending on how the composited windowing system chooses to perform the operation. Use the window property SCREEN_PROPERTY_RENDER_BUFFER_COUNT to determine the number of buffers you have that are available for rendering.

Returns:

0 if successful, or -1 if an error occurred (errno is set; refer to errno.h for more details).