screen_post_stream()

Make a stream frame available to its consumers

Synopsis:

#include <screen/screen.h>

int screen_post_stream(screen_stream_t stream,
                       screen_buffer_t buf,
                       int count,
                       const int *dirty_rects,
                       int flags)

Arguments:

stream

The handle for the stream whose content has changed.

buf

The rendering buffer of the stream that contains the changes that need to be made available to consumers.

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 all consumers have released the previous buffer 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

In addition to the area(s) defined by dirty_rects, consumers may use all the pixels in the buffer. Consumers may also retrieve data from the buffer at times other than when screen_post_stream() is called.

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

The function may cause the SCREEN_PROPERTY_RENDER_BUFFERS of the stream to change. Avoid having other threads in the application read this property while one thread is running screen_post_stream() on the same stream. If this happens, the property may reflect out-of-date information that can lead to artifacts.

If count is 0, the buffer is discarded and a new set of rendering buffers is returned. The current front buffer remains unchanged.

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, or -1 if an error occurred (errno is set).