Make window content updates visible on the display.
#include <screen/screen.h>
int screen_post_window(screen_window_t win,
screen_buffer_t buf,
int count,
const int *dirty_rects,
int flags)
The handle for the window whose content has changed.
The rendering buffer of the window that contains the changes needed to be made visible. Most applications use only 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.
The number of rectangles provided in the dirty_rects argument.
An array of integers containing the x1, y1, x2, and y2 coordinates 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.
A bitmask that can be used to alter the default posting behaviour. Valid flags are of type Screen_Flushing_Types.
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). Screen may also retrieve data from the buffer at times other than when screen_post_window() is called (e.g., when the contents or properties of overlapping windows are updated, or when the window's entire buffer is continuously read by the display hardware until another buffer is posted to replace it). Therefore, your application must ensure that the entire contents of a window buffer is suitable for display at all times until a new buffer is posted to the window and the content of the display has been updated from the new buffer.
screen_post_window() returns immediately if render buffers are available and if SCREEN_WAIT_IDLE is not set. The use of multiple threads or application buffer management schemes to render at the full display frame rate are not necessary because unlike equivalent calls in other graphics systems, screen_post_window() does not always block.
If SCREEN_WAIT_IDLE is set in the flags, the function will return only when the contents of the display have been updated.
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, into 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.
If the window is currently locked, posting updates has the effect of flushing all pending property changes and blocks until all other locked windows have released the lock or posted updates of their own. In this case, the window remains locked when screen_post_window() returns, and any subsequent property change is delayed until the window lock is released or another frame is posted.
If count is 0, the buffer is discarded and a new set of rendering buffers is returned. The current front buffer remains unchanged and the contents of the screen will not be updated.
0 if the area of the rendering buffer that is marked dirty has updated on the screen and a new set of rendering buffers was returned (this new set of buffers can be used for the next updates), or -1 if an error occurred (errno is set; refer to /usr/include/errno.h for more details). Note that the error may also have been caused by any delayed execution function that's just been flushed.