gf_surface_attach_by_sid()

Attach to a previously allocated surface

Synopsis:

#include <gf/gf.h>

int gf_surface_attach_by_sid( gf_surface_t * psurface,
                              gf_dev_t gdev,
                              gf_sid_t sid);

Arguments:

psurface: The address where the function can store a handle to the surface.
gdev: A handle for the graphical device (acquired by gf_dev_attach() that will manage the surface.
sid: The surface ID of the desired surface.

Description:

This function attaches to a previously allocated surface.

No control over surface parameters is provided via this function since the surface already exists and these parameters are already defined.

Threads should not call this function between calls to gf_draw_begin() and gf_draw_end(), or a deadlock will occur.

Any surface that is managed by io-display (that is, a surface that's been created using gf_surface_create() or gf_surface_create_layer() with default settings) can be shared across process boundaries by its surface ID (SID), a unique numerical ID assigned by io-display to each managed surface. Multiple processes can render to the same surface by sharing surfaces in this manner.

Coordination of rendering (ensuring one process doesn't render over another) is up to the application.

You can get the SID for a surface by using gf_surface_get_info().

Because multiple processes may be using a surface attached via gf_surface_attach_by_sid(), calling gf_surface_free() will free the associated gf_surface_t, but not necessarily the frame data buffer. The monitor process (io-display) maintains a reference counter for each surface it manages; it increments the counter each time a surface is attached to, and decrements the counter for each call to gf_surface_free() for the surface. It only frees the buffer memory when the reference counter reaches 0.

Returns:

GF_ERR_OK: Success.
GF_ERR_MEM: Memory allocation failure.
GF_ERR_IODISPLAY: Error communicating with io-display. Check to ensure io-display is still running. The sloginfo utility may provide more information.
GF_ERR_PARM: Invalid surface ID.

Classification:

QNX Graphics Framework

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes