Example Program

The hello_world.c program is a simple XGL program using the OLIT toolkit. The program opens XGL, creates a Window Raster Device object, renders simple text on the Raster in the default font, and closes XGL. The program's main() function follows these general steps:

• Initialize the OLIT toolkit and the X Toolkit internals, opening the connection to the server.
• Create the toplevel shell and the pane widget that XGL will render into, registering a callback function for expose events on the pane widget.
• Realize the widgets.
• Initialize XGL, creating the System State object.
• Create a Window Raster Device object associated with the pane.

• Create a 2D Context object and associate the Raster object with the Context object.
• Start the Xt main event loop. Once the main event loop has started, Xt handles program execution.

The output of hello_world.c is shown in Figure 3-5, and the complete program listing follows. Turn to page 41 for a more detailed discussion of the program. The code for this program is located in $XGLHOME/demo/examples, with the other XGL sample programs. To compile the program, type make hello_world in the example programs directory.

Figure 3-5 hello_world.c

Code Example 3-1 A First Example Program

/*
 * hello_world.c
 */

#include <X11/Xlib.h>
#include <X11/Xutil.h>
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <X11/Shell.h>
#include <Xol/OpenLook.h>

#include <Xol/DrawArea.h>

#include <xgl/xgl.h>
/* Global variables */

static Xgl_object       ctx = NULL;     /* XGL context object */
static Xgl_object       sys_state;
static Xgl_object       win_ras = NULL; /* XGL window raster */

main (
    int                 argc,
    char                *argv[])
{
    static void         redraw();

    XtAppContext        app;

    Widget              toplevel, pane;

    Display             *display;     /* pointer to X display */
    Window              xwindow;      /* XID of window */
    Xgl_X_window        xgl_x_win;    /* XGL-X data structure */
    Xgl_obj_desc        win_desc;     /* XGL window raster structure */

    OlToolkitInitialize((XtPointer)NULL);
    toplevel = XtVaAppInitialize(&app, "XGL Hello",
        (XrmOptionDescList)NULL, 0,
        &argc, argv, (String *)NULL,
        XtNtitle,       "XGL Hello World Program",
        XtVaTypedArg, XtNvisual, XtRString,
        "PseudoColor", sizeof("PseudoColor"),
        NULL);

    pane = XtVaCreateManagedWidget( "pane",
        drawAreaWidgetClass,    toplevel,
        XtNborderWidth,         1,
        XtNwidth,               500,
        XtNheight,              200,
        NULL);
    XtAddCallback(pane, XtNexposeCallback, redraw, NULL);

    XtRealizeWidget(toplevel);

 /* get X stuff */
    display = (Display *) XtDisplay (pane);
    xwindow = XtWindow (pane);

    /* put X stuff into XGL data structure */
    xgl_x_win.X_display = (void *) display;
    xgl_x_win.X_window  = (Xgl_usgn32) xwindow;
    xgl_x_win.X_screen  = (int) DefaultScreen (display);

/*
 *   Open XGL, create a Raster and a Context.
 *   Attach the raster as the Context's Device.
 *   Initialize the context text attributes to render the text.
 */
    sys_state = xgl_open (NULL);

    win_desc.win_ras.type = XGL_WIN_X;
    win_desc.win_ras.desc = &xgl_x_win;
    win_ras = xgl_object_create (sys_state, XGL_WIN_RAS,
                                       &win_desc, NULL);

    /* create XGL graphics Context object using the
     * Window Raster object */
    ctx = xgl_object_create (sys_state, XGL_2D_CTX, NULL,
                           XGL_CTX_DEVICE, win_ras,
                           XGL_CTX_DEFERRAL_MODE,XGL_DEFER_ASAP,
                           XGL_CTX_STEXT_CHAR_HEIGHT, 20.0,
                           NULL);

     XtAppMainLoop(app);
}

static void
redraw()
{
    static Xgl_pt_f2d   text_pos; /* start pos of text in window */

    text_pos.x = 90.0;
    text_pos.y = 100.0;

    if (ctx) {
        xgl_window_raster_resize(win_ras);
        /* clear the display */
        xgl_context_new_frame (ctx);

        /* draw the stroke text */
        xgl_stroke_text (ctx, "Hello XGL World", &text_pos, NULL);
    }
}

Creating the Window and Registering Callback Procedures

The main() routine of hello_world.c initializes the OLIT toolkit, the Xt toolkit, and XGL, and opens the connection to the server. It creates the OLIT widgets that the application needs, in this case, a DrawArea widget for the pane, registers a callback procedure to handle expose events on the pane, and creates a window for the widget. It also creates the XGL objects that the application needs. Finally, it starts the main event loop to wait for X events.

The program creates a drawing surface 500 units wide and 200 units high. The window frame is labeled "XGL Hello World Program". The visual type of the window is PseudoColor.

Opening XGL

The xgl_open() call initializes the XGL environment.

    sys_state = xgl_open(NULL);

The xgl_open() operator creates and returns the System State object. The System State object handles the creation of other XGL objects in subsequent xgl_object_create() calls.

Creating a Window Raster Device Object

To create a Window Raster Device object, the application must provide XGL with information about the X11 window with which the Raster object is associated. The application must get a pointer to the display, the X handle to the window, and an integer value identifying the screen that XGL will render to. This information is stored in an XGL window descriptor data structure that is passed to xgl_object_create() when the Window Raster object is created. The following code fragments show the Xt calls that retrieve window information, the XGL window data structure, and the xgl_object_create() call.

 /* get X stuff */
    display = (Display *) XtDisplay(pane);
    xwindow = XtWindow (pane);
            .
            .
            .
    /* put X stuff into XGL data structure */

    xgl_x_win.X_display = (void *) display;
    xgl_x_win.X_window = (Xgl_usgn32) xwindow;
    xgl_x_win.X_screen = (int) DefaultScreen(display);
            .
            .
            .
    win_desc.win_ras.type = XGL_WIN_X;
    win_desc.win_ras.desc = &xgl_x_win;
    win_ras = xgl_object_create(sys_state, XGL_WIN_RAS, &win_desc,
                                   NULL);

The xgl_object_create() operator returns a handle to the Window Raster Device object. The System State object stores a pointer to the Device object in its list of API objects.

Creating a Context Object

The Context object keeps track of attribute information for the XGL primitives. In this example, a 2D Context object is created by a call to xgl_object_create() with a type value of XGL_2D_CTX.

ctx = xgl_object_create(sys_state, XGL_2D_CTX, NULL,
                       XGL_CTX_DEVICE, win_ras,
                       XGL_CTX_DEFERRAL_MODE, XGL_DEFER_ASAP,
                       XGL_CTX_STEXT_CHAR_HEIGHT, 20.0,
                       NULL);

The Context's deferral mode is set so that XGL will render a primitive as soon as it is received. The character height for the stroke font is set to 20.0 units. The previously created Device object is associated with the Context object with the XGL_CTX_DEVICE attribute and the Device object's handle. The newly created Context object is registered in the System State object passed to the xgl_object_create() operator.

Rendering Geometry

The redraw() procedure renders the geometry data that the application supplies. In this program, the redraw() procedure clears the display using the XGL operator xgl_context_new_frame() and then draws text into the window with the primitive xgl_stroke_text(). The xgl_stroke_text() primitive renders the string "Hello XGL World" to the text position, using the text attributes in the Context object.

static void
redraw()
{
    static Xgl_pt_f2dtext_pos;/* start pos of text in window */

    text_pos.x = 90.0;
    text_pos.y = 100.0;

    if (ctx) {
        xgl_window_raster_resize(win_ras);
        /* clear the display */
        xgl_context_new_frame (ctx);

        /* draw the stroke text */
        xgl_stroke_text (ctx, "Hello XGL World", &text_pos, NULL);
    }
}