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.

Pigment initialization

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.

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.

Pigment version retrieval

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 programming model

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.

pgm_init ()

void                pgm_init                            (int *argc,
                                                         char **argv[]);

Initializes the Pigment library.

pgm_init_check ()

gboolean            pgm_init_check                      (int *argc,
                                                         char **argv[]);

Initializes the Pigment library without terminating the program if it was unable to initialize successfully.

pgm_deinit ()

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

pgm_version ()

void                pgm_version                         (guint *major,
                                                         guint *minor,
                                                         guint *micro,
                                                         guint *nano);

Gets the version number of the Pigment library.

pgm_version_string ()

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.

pgm_events_pending ()

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.

  // computation going on
  ...
  while (pgm_events_pending ())
    pgm_main_iteration ();
  ...
  // computation continued

pgm_main ()

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.

pgm_main_quit ()

void                pgm_main_quit                       (void);

Quits the main loop.

pgm_main_iteration ()

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.

pgm_main_iteration_do ()

void                pgm_main_iteration_do               (gboolean blocking);

Runs a single iteration of the main loop. If no events are available, either returns or blocks dependent on the value of blocking.