Ginga as an NCL Player

Libginga external API is the library public interface. It can used by application programmers to build iTV players that reproduce NCL files. An NCL (Nested Context Language) file is an XML file that specifies an interactive multimedia presentation. For more information about Ginga (the standard) and NCL (the language) see http://ginga.org.br and http://ncl.org.br.

Along with libginga, the Ginga distribution comes with four programs that use libginga external API to play NCL files:

src/ginga.cpp: A GTK+-based command-line player.
src/ginga-qt.cpp: A Qt-based command-line player.
src/ginga-gl.cpp: An experimental command-line player based on SDL and OpenGL.
src-gui/ginga-gtk.cpp: A full-fledged GUI player based on GTK+

External API Overview

Libginga external API consists of a single header file, ginga.h, containing the class Ginga. A Ginga object represents an NCL player (also called formatter). Multiple Ginga instances can coexist within the same program. The external API is fully reentrant. All its methods are non-blocking and should be called in the same thread. (If multiple threads are used, the caller must ensure that only one thread at a time executes in the same Ginga object.)

To play an NCL file, after creating a Ginga object using Ginga::create, the program must call Ginga::start with the path of the file. The Ginga::start call parses the given file and bootstraps the presentation. When the call returns, the presentation is assumed to be at time 0. From this point on, the program that is using libginga should:

Capture the keys pressed by the user and send them to the presentation via Ginga::sendKey.
From time to time, advance the presentation time by sending ticks via Ginga::sendTick.
Whenever necessary, draw the latest frame of the presentation via Ginga::redraw.

The program can use Ginga::stop to stop the presentation or use Ginga::getState to detect its natural end (some NCL presentations eventually terminate). After the Ginga object is stopped, the previous presentation state is lost and the same object can be used to play another file.

Some control options (GingaOptions) can be set on the Ginga object when it is created. Most of these options can also be changed later via Ginga::setOption* calls. The set options are preserved even after the presentation is stopped.