screen_share_window_buffers()

Cause a window to share buffers which have been created for or attached to another window.

Synopsis:

#include <screen/screen.h>
 
int screen_share_window_buffers(screen_window_t win,
                                screen_window_t share)

Arguments:

win

The handle of the window that will be sharing the buffer(s) owned by another window.

share

The handle of the window whose buffer(s) is to be shared.

Library:

libscreen

Description:

Function Type: Flushing Execution

This function is used when a window needs to share the same buffers created for, or attached to, another window. For this operation to be successful, the window that is the owner of the buffer(s) to be shared must have at least one buffer that was created with screen_create_window_buffers() or attached with screen_attach_window_buffer(). Buffers cannot be created or attached to any window that is sharing the buffers owned by another window. Updates can only be posted using the window that is the owner of the buffers (i.e. the window whose handle is identified as share). Any window that is sharing buffers with another window is orphaned from the buffers and made invisible when the window who owns the buffer(s) is destroyed. At this time, that status of each orphaned window is such that a new buffer can be created for it, or screen_share_window_buffers() can be called again. You can use the screen_share_window_buffers() function to improve performance by reducing the amount of blending on the screen. For example, a window might be entirely transparent except for a watermark that needs to be blended in a corner. Blending the entire window is costly and can be avoided by setting the transparency of this window to SCREEN_TRANSPARENCY_DISCARD. To keep the watermark visible, another window can be created and made to share buffers with the main window. This way, most of the window is discarded and a much smaller area is actually blended. Any window property, such as SCREEN_PROPERTY_FORMAT, SCREEN_PROPERTY_USAGE, and SCREEN_PROPERTY_BUFFER_SIZE, which was set prior to calling screen_share_window_buffers(), is ignored and reset to the values of the parent window.

Returns:

0 if the windows are sharing buffers, or -1 if an error occurred (errno is set; refer to /usr/include/errno.h for more details). Note that the error may also have been caused by any delayed execution function that's just been flushed.