gf_draw_begin()

Begin rendering

Synopsis:

#include <gf/gf.h>

int gf_draw_begin( gf_context_t context );

Arguments:

context

The graphics context handle to render to.

Library:

gf

Description:

This function begins rendering using the given draw context. It ensures that the calling thread has exclusive access to the hardware, and prepares the hardware to receive draw commands. It also ensures that all the current context settings are applied. Once you no longer require exclusive access to the hardware, you should call gf_draw_end().

---

Although a common address space makes it easy to share contexts across threads of the same process, you should exercise caution when doing so by ensuring that each thread calls gf_draw_begin() before it begins rendering using the shared context. Without following this practice, the two threads may access the hardware simultaneously, which could leave the hardware in an undefined state, causing your application to hang.

---

Because this function locks the hardware for exclusive access by the calling thread, you should follow these practices to ensure fairness to other threads waiting to render, and to avoid potential deadlock:

• Call gf_draw_begin() only when your thread is ready to begin rendering.
• Call gf_draw_end() as soon as your thread is done rendering.
• Avoid calling GF functions that are not directly related to rendering between gf_draw_begin() and gf_draw_end(). This means you should call only functions beginning with gf_draw or gf_context (with the exception of gf_context_set_surface(), which you can't call while you are rendering).

---

In order to render, there must be a surface associated with the given context (using gf_context_set_surface()). If the context has no associated surface, the function fails.

---

You need to call gf_draw_begin() each time you begin drawing using a different context.

Returns:

GF_ERR_OK

Success. Hardware is locked and you may begin rendering.

GF_ERR_MEM

Insufficient memory to lock mutex.

GF_ERR_PARM

Invalid context for rendering; context must be targeting a surface whose format is suitable for 2D rendering.

GF_ERR_INUSE

The calling thread has already successfully called gf_draw_begin(); recursive behaviour is not permitted.

GF_ERR_SURFDESTROYED

The context's surface has been destroyed for some reason, such as a mode switch or power management event.

Classification:

QNX Graphics Framework

See also:

gf_draw_end(), gf_context_set_surface()

“Multi-threaded applications” in the Basic Drawing chapter