![]() |
![]() |
![]() |
Pigment 0.3 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <pgm/pgm.h> void pgm_init (int *argc, char **argv[]); gboolean pgm_init_check (int *argc, char **argv[]); void pgm_deinit (void); void pgm_version (guint *major, guint *minor, guint *micro, guint *nano); gchar * pgm_version_string (void); gboolean pgm_events_pending (void); void pgm_main (void); void pgm_main_quit (void); void pgm_main_iteration (void); void pgm_main_iteration_do (gboolean blocking);
Pigment is a media rendering library written in C providing an abstraction layer to easily design GUI (Graphical User Interfaces) like simple games, media center/set-top box applications, etc. It has a pluggable backend system so that the same application can run on various hardware and software platforms using rendering libraries such as OpenGL or DirectFB on operating systems such as Windows, GNU/Linux or Mac OS X.
Pigment has been designed to handle common issues like non square pixels displays, non square pixels images or video sources, positioning abstraction and scalable user interface support. Moreover, Pigment is a fully thread safe library which means that you can call methods on Pigment objects from multiple threads at the same time even if the rendering backend is not thread safe itself like some OpenGL implementations are for example.
The Pigment library has to be initialized
with pgm_init()
before it can be used. You should pass pointers to
the main argc and argv variables so that Pigment can process its own command
line options, as shown in the following example.
Example 1. Initializing the library
int main (int argc, char *argv[]) { pgm_init (&argc, &argv); ... }
The pgm_deinit()
call is used to clean up all internal resources used
by Pigment.
Use pgm_version()
to query the library version at runtime or use the
PGM_VERSION_* macros to find the version at compile time. Optionally
pgm_version_string()
returns a printable string.
Pigment is a GUI toolkit based on an event-driven programming model. When the
user is doing nothing, Pigment sits in the main loop and waits for input.
If the user performs some action, like a mouse button click, then the main
loop "wakes up" and delivers an event to Pigment. When a viewport receives
an event, it emits a signal to notify your program that something happened
by invoking functions you connected to the signal with
g_signal_connect()
. Functions connected to a signal are often termed
callbacks. When your callbacks are invoked, you would typically take some
action, for example when a key of the keyboard is pressed you might update
the properties of your drawables. After a callback finishes, Pigment will
return to the main loop and await more user input.
Last reviewed on 2007-09-25 (0.3.1)
void pgm_init (int *argc, char **argv[]);
Initializes the Pigment library.
This function will terminate your program if it was unable to initialize
Pigment for some reason. If you want your program to fall back,
use pgm_init_check()
instead.
|
the address of the argc parameter of your main function.
|
|
the address of the argv parameter of your main function.
|
gboolean pgm_init_check (int *argc, char **argv[]);
Initializes the Pigment library without terminating the program if it was unable to initialize successfully.
void pgm_deinit (void);
Deinitializes the Pigment library. This is not going to free Pigment
objects, you need to explicitely unref these objects using
gst_object_unref()
.
void pgm_version (guint *major, guint *minor, guint *micro, guint *nano);
Gets the version number of the Pigment library.
gchar * pgm_version_string (void);
Returns a string that is useful for describing this version of Pigment to the outside world: user agent strings, logging, etc.
Returns : |
a newly allocated string describing this version of Pigment. |
gboolean pgm_events_pending (void);
Checks if any events are pending. This can be used to update the GUI, while doing some time intensive computation.
Example 2. Updating the GUI during a long computation.
// computation going on ... while (pgm_events_pending ()) pgm_main_iteration (); ... // computation continued
void pgm_main (void);
Runs the main loop until pgm_main_quit()
is called. It's ok to use the GLib
main loop directly instead, though it involves slightly more typing. See
GMainLoop in the GLib documentation.
void pgm_main_iteration (void);
Runs a single iteration of the main loop. If no events are waiting to be
processed, Pigment will block until the next event is noticed. If you don't
want to block, look at pgm_main_iteration_do()
or check if any events are
pending with pgm_events_pending()
first.