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.

Library:

gf

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

See also:

gf_surface_attach(), gf_surface_create(), gf_surface_get_info()