screen_acquire_buffer()

Wait for the next buffer to become available from a producer

Synopsis:

#include <screen/screen.h>
int screen_acquire_buffer(screen_buffer_t *pbuf,
                          screen_stream_t stream,
                          int *pcount,
                          int **pdirty_rects,
                          int *pflags,
                          int flags)

Arguments:

pbuf
A pointer to the buffer that was acquired; or NULL, when no buffer was available and SCREEN_DONT_BLOCK was specified in flags.
stream
The handle of a stream from which a buffer needs to be acquired. The stream must have been created with screen_create_stream(). This stream is typcially realized with screen_consume_stream_buffers().
pcount
A pointer to the number of dirty regions posted by the producer. If pcount points to 0 (i.e., *pcount == 0) when it returns from this function, the consumer should consider the entire pbuf to be dirty.
pdirty_rects
A pointer to an array of pcount regions corresponding to the dirty regions posted by the producer. Each region is expressed by a set of 4 integers that represent the x1, y1, x2, and y2 values of a rectangle. If *pdirty_rects is NULL (i.e., *pdirty_rects == NULL) when it returns from this function, the consumer should consider the entire pbuf to be dirty.
pflags
A pointer to an integer that represents the bitmask that Screen used when the producer posted (e.g., producer called screen_post_window() or screen_post_stream()). The integer is a bitmask that represents a combination of Screen flushing types. As a consumer, use pflags to determine if any action needs to be taken to prevent the producer from remaining blocked. Pass NULL if you don't intend to use this information.
flags
The indication of how you want this function to behave. This integer is a bitmask that represents the combination of Screen flushing types:
  • SCREEN_DONT_BLOCK: When you use SCREEN_DONT_BLOCK, this function returns immediately with the available buffer in pbuf. If there are no buffers available, this function returns immediately with *pbuf = NULL;.
  • 0: When you use 0, this function blocks for as long as there are no buffers that are available for acquiring.

Library:

libscreen

Description:

Function Type: Flushing Execution

This function is typically used by consumers to get the next frame posted by the producer. The consumer uses a stream that shares buffers with an external stream handle by calling screen_consume_stream_buffers(). Producers and consumers that reside in the same process can use the API, or simply pass the buffers between each other.

Acquiring a buffer doesn't release previously acquired buffers. Typically, after calling screen_acquire_buffer(), the consumer releases the previously acquired buffer by calling screen_release_buffer(). Note that if the stream is single-buffered, the consumer calls screen_release_buffer() after finishing with the buffer.

This function returns the next available buffer. However, if the stream is in SCREEN_STREAM_MODE_MAILBOX mode, this function returns all queued front buffers to the render queue, except for the last buffer.

If you provide a non-NULL pointer in pcount and pdirty_rects, this function returns the number of regions in the location pointed to by pcount and pdirty_rects will point to an array of integers that represents the dirty regions. This array is allocated dynamically and must be freed when it's no longer needed.

If you provide NULL in pcount and pdirty_rects, this function doesn't make the dirty regions (if any) available to the consumer.

Returns:

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