Begin rendering


#include <gf/gf.h>

int gf_draw_begin( gf_context_t context );


The graphics context handle to render to.




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

Caution: 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:

Note: 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.


Success. Hardware is locked and you may begin rendering.
Insufficient memory to lock mutex.
Invalid context for rendering; context must be targeting a surface whose format is suitable for 2D rendering.
The calling thread has already successfully called gf_draw_begin(); recursive behaviour is not permitted.
The context's surface has been destroyed for some reason, such as a mode switch or power management event.


QNX Graphics Framework

Interrupt handler No
Signal handler No
Thread Yes

See also:

gf_draw_end(), gf_context_set_surface()

Multi-threaded applications in the Basic Drawing chapter