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)

Since:

BlackBerry 10.0.0

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.

count

The number of rectangles provided in the dirty_rects argument.

dirty_rects

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.

flags

A bitmask that can be used to alter the default posting behaviour. Valid flags are of type Screen_Flushing_Types.

Library:

libscreen (For the qcc command, use the -l screen option to link against this library)

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.

In addition to the area(s) defined by dirty_rects, Screen may update all the pixels in the buffer. 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 is autonomous and so the entire buffer will be continuously read from by the display hardware until another buffer is posted to replace it). Your application must ensure that the entire content 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 the 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. Note that a window will not be made visible until screen_post_window() has been called at least once.

The function may cause the SCREEN_PROPERTY_RENDER_BUFFERS of the window to change. If your application uses multiple threads, don't have this property read by other threads in the application while one thread is running screen_post_window() on the same window. If this happens, the property 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.

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.

Returns:

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).

Last modified: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus