screen_post_stream()

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

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.

buf

The rendering buffer of the stream that needs 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 {x,y,w,h} containing the x and y coordinates, width, and height of a rectangle respectively, 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 buf (the buffer being posted) has been released or has become a render buffer again.
SCREEN_DONT_BLOCK: When you use SCREEN_DONT_BLOCK, this function returns immediately regardless of whether a render buffer is currently available. Do not use SCREEN_PROPERTY_RENDER_BUFFERS after posting with this flag. Instead, use screen_dequeue_stream_render_buffer() to wait for the next available render buffer.
SCREEN_EXPLICIT_ENQUEUE: When you use SCREEN_EXPLICIT_ENQUEUE, this function leaves the render buffer dequeued. The buffer remains unavailable to the content producer until said producer calls screen_enqueue_render_buffer() and all content consumers release the buffer. This allows the content producer to continue referencing and reading from the buffer after the post. Under no circumstances should the content producer continue writing to the buffer once post has been called.
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.

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.

Returns:

0 if the area of the rendering buffer that is marked dirty has been updated and a new set of rendering buffers was returned, or -1 if an error occurred (errno is set; refer to errno.h for more details).

Page updated: March 05, 2025