screen_acquire

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 you specified SCREEN_ACQUIRE_DONT_BLOCK 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 typically 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 acquire buffer flags:

SCREEN_ACQUIRE_DONT_BLOCK: When you use SCREEN_ACQUIRE_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;.
SCREEN_ACQUIRE_AND_RELEASE_OTHERS: When you use this option, this function first releases all buffers that you've previously acquired, before acquring a new one. This flag must be specified with SCREEN_ACQUIRE_DONT_BLOCK.
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: Immediate 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 unless you specify SCREEN_ACQUIRE_AND_RELEASE_OTHERS in the flags parameter. In this case, all other buffers are released whenever a new buffer is returned. 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 no buffer is available, this function blocks unless you specify SCREEN_ACQUIRE_DONT_BLOCK in the flags parameter.

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