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 Output of 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);
    }
}

Objects Provided at XGL Initialization

A set of XGL objects is created during the initialization of the XGL library. Although the application must create the Context object and the Device object, other objects are automatically created, as follows:

• The System State object is automatically created during the xgl_open() call. The System State object in turn creates the following objects:

  · Line Pattern objects that supply the application with a set of predefined line patterns. These predefined Line Pattern objects cannot be modified by the application. To create additional Line Patterns, the application must create additional Line Pattern objects.

  · Marker objects that provide predefined symbols. Like the predefined Line Pattern objects, these Marker objects cannot be modified by the application. To create additional markers, the application must create additional Marker objects.

• When the application creates the Device object, the XGL system creates a default two-color (black and white) Color Map object. This Color Map cannot be modified. To render in color, the application must create its own Color Map object and associate it with the Device object.

• When the application creates a Context object, the following objects are also created:

  · Transform objects for transformation matrices used by the viewing pipeline. These Transform objects are the Local Model Transform, the Global Model Transform, the Model Transform, the View Transform, the VDC Transform, and for 3D Contexts, the Normal Transform. These Transforms are set to identity at initialization, but the application can retrieve several of the matrices and manipulate the values using the Transform operators. Applications can also create new Transform objects as necessary.

  · A Stroke Font object that defines the Roman_M font in the XGL font directory as the default font. To use different font, the application must create a new Stroke Font object, set it to the appropriate font name, and associate it with the Context object.

Note that no Light objects are created at initialization, but Context environment attributes can create an array of lights whose values can be retrieved and set.

Programming Tips

This section provides tips on writing XGL programs. The first group of tips contains general information and considerations about writing XGL programs; the second group of tips contains information about using XView and XGL.

General Tips

• The default value of the Context attribute XGL_CTX_DEFERRAL_MODE is XGL_DEFER_ASTI ("At Some TIme"). In this mode, the application must call xgl_context_post() to ensure that all the data is flushed from the XGL internal buffer and displayed.
• Assuming that an application has obtained X information on the X11 display, the frame window containing the drawing window, and the canvas window that XGL will draw to, the application can use the following lines of code to enable the window manager to install an application color map for the canvas window.

Atom      catom;
catom = XInternAtom(display, "WM_COLORMAP_WINDOWS", False);
XChangeProperty(display, frame_window, catom, XA_WINDOW, 32,
                 PropModeAppend, &canvas_window, 1);

• xgl_close() should be called to ensure that all resources are released.

XView Tips

• The XView attribute CANVAS_AUTO_CLEAR should be set to FALSE, since the XGL xgl_context_new_frame() operator can clear the canvas (using DGA) faster than Xlib can. xgl_context_new_frame() also performs other actions, such as clearing the Z-buffer.
• The application should supply an event procedure to handle resize and repaint events for the canvas paint window of the XView canvas. When a WIN_RESIZE event occurs, the XGL xgl_window_raster_resize() operator should be called. If there is more than one XGL window raster in an application, the application must determine which Xgl_win_ras object corresponds to the Xv_window object passed to the event procedure.

  In addition, before calling xgl_window_raster_resize(), the application should call XSync() if it will be running as a DGA application. The XGL call xgl_window_raster_resize() uses DGA to grab window size information. Because of the way XView handles geometry management, the window size returned is the previous window size. Calling XSync() before xgl_window_raster_resize() will synchronize the server and XGL.

• The XView attribute CANVAS_FIXED_IMAGE should be set to FALSE so that the server will inform the application, via the CANVAS_RESIZE_PROC, that the canvas has been resized. When this attribute is TRUE, the CANVAS_RESIZE_PROC is not called when the canvas is made smaller.
• If the application defines a color map for a canvas, the application must set the WM_COLORMAP_WINDOWS property on the its top-level window to tell the window manager which canvas will use the color map. The following lines of code shows how to accomplish this under XView.

Atom      catom;
/* These four lines get X info from XView objects */
display = (Display *)xv_get(frame, XV_DISPLAY);
frame_window = (Window)xv_get(frame, XV_XID);

canvas_window = (Window)xv_get
                 (canvas_paint_window(canvas),XV_XID);
catom = XInternAtom(display, "WM_COLORMAP_WINDOWS", False);
XChangeProperty(display, frame_window, catom, XA_WINDOW, 32,
             PropModeAppend, &canvas_window, 1);

Note that an application does not need to set the WM_COLORMAP_WINDOWS property if it is only using one color map.

• Instead of calling xgl_close() after xv_main_loop returns, the application should call xgl_close() in a routine interposed on the quit event.

OLIT Tips

• The application should call xgl_close() from the "Quit" selection in the window menu. This is done by adding a callback to the toplevel shell:

 OlAddCallback(toplevel, XtNwmProtocol, WMCallback, NULL);

The following lines of code show an example of a procedure that could be called when the shell receives a WM_PROTOCOL message.

void
WMCallback(widget, clientdata, calldata)
    Widget           widget;
    XtPointer        clientdata;
    XtPointer        calldata;
{
    OlWMProtocolVerify *wmvrfy = (OlWMProtocolVerify *)calldata;

    if ((wmvrfy->msgtype == OL_WM_DELETE_WINDOW) &&
                                   (application wants to stay up))
        return;
    else {
        xgl_close(sys_state);
        OlWMProtocolAvction(widget, wmvrfy, OL_DEFAULTACTION);
    }
}