Introduction to Device Objects

XGL defines a device as any surface on which it can render (create) an image, whether the image is visible or invisible. The Device class is an abstraction of many types of graphics display devices. It has two subclasses: Raster, which represents a two-dimensional rectangular array of discrete image samples (pixels), and Stream, which represents any picture representation, such as Computer Graphics Metafile (CGM) or PostScript^(R), that doesn't rely on discrete pixels to display the image.

The pixels in a raster can reside in a graphics frame buffer (that is, on the display device) or in memory. Thus, there are two types of Raster objects: Memory Rasters, which correspond to contiguous areas of memory that XGL will write into, and Window Rasters, which are areas on the display screen, managed by the window system, that XGL will write into.

A Window Raster requires a window system in which to run; it does not work with a raw screen. The actual display device containing the pixels is generally a window canvas created by the X11 server running as part of the window system. The application must execute the proper Xlib or X toolkit calls to create this canvas before attaching an XGL Window Raster Device. A window should have only one associated Window Raster Device object attached to it.

A Memory Raster is a block of memory allocated from main memory. XGL draws into it the same way it draws into Window Rasters. The pixels composing a Memory Raster Device are in the application's memory space.

XGL provides one Stream device at this time, a CGM device. A CGM device outputs CGM formatted graphics information to the output stream.

The graphics hardware devices running applications may differ considerably. Because XGL Device objects provide the framework for interacting with graphics devices in an abstract, device-independent manner, in most cases the application programmer does not need to know the hardware specifics of each system.

Creating Device Objects

Device objects are created with the xgl_object_create() operator using the input values in Table 5-1:

Table 5-1

Device Type	type Parameter	desc Parameter
Window Raster	XGL_WIN_RAS	A pointer to an Xgl_obj_desc structure containing a window type and a window descriptor.
Memory Raster	XGL_MEM_RAS	NULL
Stream	XGL_STREAM	A pointer to an Xgl_obj_desc structure containing a pointer to the name of the library for the stream device and a pointer to any device-specific information for the stream device.
CGM	XGL_CGM_DEV	A pointer to an Xgl_obj_desc structure containing a pointer to the name of the library for the XGL-provided CGM Stream device.

Window Raster Device Object

To create a Window Raster Device object, XGL needs information on the X11 window that XGL will render to. This information is provided in the desc parameter, which points to a Xgl_obj_desc union containing a window type and a window descriptor structure. The only supported value for the window raster type is XGL_WIN_X. The window descriptor structure is:

typedef struct { void *X_display; int X_screen; Xgl_usgn32 X_window; } Xgl_X_window;

The window system type can be modified to indicate which protocol XGL uses to communicate with the graphics device. XGL supports three protocols for the X window system: Xlib, PEX, and DGA (Direct Graphics Access). The protocol is selected by OR'ing in the name of the protocol with the constant XGL_WIN_X. The constants for the names of the protocol are:

#define XGL_WIN_X_PROTO_DEFAULT         (0x000)
#define XGL_WIN_X_PROTO_XLIB            (0x100)
#define XGL_WIN_X_PROTO_PEX             (0x200)
#define XGL_WIN_X_PROTO_DGA             (0x400)

Only one protocol can be specified. If a protocol is specified, XGL tries to use that protocol to communicate with the graphics device. If it is not available, an error is issued and the Window Raster is not created. If no protocol is specified (or XGL_WIN_X_PROTO_DEFAULT is used), XGL tries to use the best protocol for the particular device. If that is not available, XGL will try a backup protocol. In practical terms, XGL tries to use DGA, but if that is not available, it will attempt to use PEX, and if that fails, then it will use Xlib.

In most cases, an XGL application does not need to be concerned with selecting a protocol. However, this facility is available to aid applications that want to make the best use of the graphics resources, and this usually means part of the application that is device-dependent.

The code fragment below shows how a Window Raster object can be created in XView.

Xgl_win_ras          win_ras = NULL;/* Xgl window raster */
Xgl_X_window         xgl_x_win;        /* XGL-X data structure */
Xgl_obj_desc         win_desc;         /* XGL window raster structure */

pw = (Xv_Window) canvas_paint_window(canvas);
canvas_window = (Window) xv_get(pw, XV_XID);
frame_window = (Window) xv_get(frame, XV_XID);

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

/* create Window Raster Device using XView canvas */
win_desc.win_ras.type = XGL_WIN_X;
win_desc.win_ras.desc = &xgl_x_win;
win_ras = xgl_object_create(sys_st, XGL_WIN_RAS, &win_desc,
                              NULL);

A Device object must be associated with a Context object for rendering to occur. The two objects are associated using the XGL_CTX_DEVICE attribute. This association can be made when the Context object is created, as in the following code fragment.

ctx = xgl_object_create(sys_st, XGL_2D_CTX, NULL, XGL_CTX_DEVICE, win_ras, NULL);

The association between the Device and the Context can also be set with the xgl_object_set() operator:

xgl_object_set(ctx,XGL_CTX_DEVICE, win_ras,NULL);

---

Note - The current implementation of XGL, using DGA, does not support fork() or vfork() if there is an active XGL Window Raster. The application can create only one XGL Raster for each OpenWindows (X) window.

---

Stream Device Object

The XGL Stream device provides protocol-independent stream pipelines for creating formatted output such as PostScript or CGM output. The interface to the Stream device is independent of each specific Stream implementation. Each implemented Stream device provides an include file that contains the mapping of from the pipeline-specific attributes to the generic Stream attributes.

To create a Stream device object, the application needs to supply XGL with the name of the library that provides the Stream device functionality, and, if the Stream pipeline requires other information, a pointer to that information. This information is provided to XGL in the xgl_object_create() desc parameter, which points to an Xgl_obj_desc union containing a stream structure. The actual name of the library is defined in the header file provided with the device pipeline for the Stream device. See the documentation for the particular Stream device for specific information on the name of the library and for required device-specific information. For an example of a Stream device, see the section on the XGL CGM device on page 70.

A Stream device provides support for the following XGL attributes:

• XGL_OBJ_APPLICATION_DATA
• XGL_OBJ_TYPE
• XGL_OBJ_SYS_STATE
• XGL_DEV_COLOR_MAP
• XGL_DEV_REAL_COLOR_TYPE
• XGL_DEV_COLOR_TYPE
• XGL_DEV_CONTEXTS
• XGL_DEV_CONTEXTS_NUM
• XGL_DEV_MAXIMUM_COORDINATES

The Stream device may provide additional attributes that are passed through XGL from the application to the pipeline and from the pipeline to the application. After creating a Stream device, the application can inquire the values of the attributes using the xgl_object_get() operator. See the documentation for the Stream device for information on available attributes.

Raster Object Attributes

Raster attributes define the Window and Memory Raster Device objects created by the Device object operators. Some are shared by both Memory and Window Device objects, and others are specific to one or the other.

General Raster Attributes

Raster attributes that affect all Raster objects are:

XGL_DEV_COLOR_MAP This attribute allows the application to establish its own color map in the Raster Device for specifying the colors rendered onto the Raster. Color maps apply to Rasters of type XGL_COLOR_INDEX. They are not applicable to Rasters of type XGL_COLOR_RGB since user colors are mapped directly to hardware lookup tables. Once a Color Map object has been created, it can be attached to the Raster using xgl_object_set() and this attribute. The default value is a handle to a Color Map object containing a two-element, black and white color table.

After an application sets this attribute and before attempting to draw into the Raster, the application must call xgl_context_new_frame() on the Context to which the Raster is attached. This ensures the correct colors.

XGL_DEV_REAL_COLOR_TYPE
  This is a read-only attribute that indicates the actual color space used to
  store pixels in an XGL Device and the information contained in an actual
  pixel. This information is device-dependent.

XGL_DEV_COLOR_TYPE This attribute defines the color space used for the calculation of color and lighting. It is set at the time of Raster creation and can only be set once. The color space of the device for a window raster object is directly related to the visual class of the X window underlying the window raster object. If the visual class of the X window is PseudoColor, then the color type of the window raster object should be XGL_COLOR_INDEX. If the visual class of the X window is TrueColor or DirectColor, the color type of the window raster object should be XGL_COLOR_RGB. The color spaces currently supported in XGL as defined by the data type Xgl_color_type are:

• XGL_COLOR_RGB, where color is specified as a fractional component of each of the three primary colors: red, green, and blue. Each component is a floating-point number between 0.0 and 1.0, which represents the additive weight the primary contributes to the final color. The visual type of the X window underlying a window raster of this color type should be TrueColor or DirectColor. Note that if the visual type is DirectColor, XGL will behave as if on a TrueColor visual.
• XGL_COLOR_INDEX, where color is specified as an unsigned integer index into a color table. The color table of an XGL Color Map object maps index colors into RGB color values. The default value is device-dependent. The visual type of the X window underlying a window raster of this color type should be PseudoColor.

Thus, for example, if the visual class of the X window underlying the window raster object is PseudoColor, the color type of the Window Raster object is set as shown in this code fragment:

if (vis->class == PseudoColor) ras = xgl_object_create(XGL_WIN_X, &xgl_x_win, XGL_DEV_COLOR_TYPE, XGL_COLOR_INDEX, NULL);

If the visual class of the X window is TrueColor or DirectColor, the color type of the window raster object is set to XGL_COLOR_RGB as follows:

if (vis->class == TrueColor || vis->class == DirectColor) ras = xgl_object_create(XGL_WIN_X, &xgl_x_win, XGL_DEV_COLOR_TYPE, XGL_COLOR_RGB, NULL);

XGL_DEV_CONTEXTS_NUM
  This read-only attribute returns the number of Context objects associated
  with a Device. The default value is 0.

XGL_DEV_CONTEXTS This read-only attribute returns a list of the Context object handles associated with a Device. To use this attribute, the application should first get the number of Contexts associated with the Device using the XGL_DEV_CONTEXTS_NUM attribute, allocate sufficient memory to hold the array of object handles, where each object handle is Xgl_ctx in size, and then get the list of object handles. The default value is NULL.

XGL_DEV_MAXIMUM_COORDINATES
  This read-only attribute returns the Device's maximum x and y coordinates
  values. In addition, the maximum Z-buffer value allowed by the Device, is
  returned in the z value of the return Xgl_pt_f3d argument. The default
  values are device-dependent.

XGL_RAS_DEPTH This attribute defines the number of bits used to specify the color of one pixel in an XGL Raster. It is read-only for Window Rasters and read-write for Memory Rasters. Four depths are supported: 1, 4, 8, and 32. The 1-bit depth is used only for creating stipple patterns by the xgl_context_copy_buffer() operator and other polygon-fill attributes. The 4-bit, 8-bit, and 32-bit depths are used for Memory Rasters into which the XGL application can render. The default value is 8 for Memory Rasters. If the depth of the Memory Raster is 8, the recommended device color type is XGL_COLOR_INDEX. If the depth of the Memory Raster is 32, the only device color type that is supported is XGL_COLOR_RGB. The default value is device-dependent for Window Rasters.

XGL_RAS_HEIGHT This attribute defines the height of an XGL Raster. Window Raster height is obtained from the size of the window passed to the object create call. Memory Raster height can be set or reset at any time. The maximum Memory Raster height is 4K. Changing the height of a Memory Raster results in the loss of all pixel data it contains at that time. The default value is 256 for a Memory Raster.

XGL_RAS_WIDTH This attribute defines the width of an XGL Raster. The Window Raster width is obtained from the size of the window passed to the object create call. The Memory Raster width can be set or reset at any time. The maximum Memory Raster width is 4K. Changing the width of a Memory Raster results in the loss of all pixel data it contains. The default value is 256 for a Memory Raster.

XGL_RAS_SOURCE_BUFFER
  This attribute specifies the source buffer for the raster operations
  xgl_context_copy_buffer() and xgl_context_get_pixel(). The
  source buffer can be a raster's draw buffer or its Z-buffer. The default value
  is the draw buffer.

XGL_RAS_RECT_NUM This attribute specifies the number of clip rectangles in the application clip list.

XGL_RAS_RECT_LIST This attribute specifies the list of clip rectangles in the application clip list.

Window Raster Attributes

Raster attributes that affect all Window Raster objects are:

XGL_WIN_RAS_TYPE This attribute supplies the type of Window Raster Device. It is a read-only attribute that describes the window system controlling the Window Raster. The value of this attribute is the value the application passes to XGL with the operator xgl_object_create(). XGL returns the following value:

XGL_WIN_X The Window Raster is an X11 window.

XGL_WIN_RAS_DESCRIPTOR
  This attribute is the descriptor passed to XGL on the creation of the Window
  Raster. Its value is the same as the value passed to XGL by the operator
  xgl_object_create(). It returns a value of type Xgl_X_window, as X11
  windows are the only supported window type. There is no default value.

XGL_WIN_RAS_POSITION This read-only attribute specifies the position of the Window Raster object. It returns the position of the window in device coordinates relative to the upper left corner of the display screen.

XGL_WIN_RAS_PIXEL_MAPPING This attribute specifies the pixel mapping array from the user's index colors to the window system color map index colors. This attribute must be set by the application immediately after setting XGL_CMAP_NAME for the Color Map object associated with the Window Raster. The returned pixel array of the color map created for the Window System is sent to XGL via XGL_WIN_RAS_PIXEL_MAPPING. The default value is identity.

XGL_WIN_RAS_STEREO_MODE This attribute specifies whether the window being rendered into is a stereo window or a monocular (non-stereo) window. If the attribute is set to XGL_STEREO_NONE and the frame buffer is in stereo mode, all graphics will

be rendered into both the left and right eye buffers. If the value is set to XGL_STEREO_LEFT, the image for the left eye buffer is rendered; if the value is set to XGL_STEREO_RIGHT, the image for the right eye buffer is rendered. Note that undefined results may occur if stereo is used when rendering through a 2D Context.

XGL_WIN_RAS_BUF_DISPLAY
  This attribute specifies the current display buffer in the application window.
  When the display and draw buffers are equivalent, the Window Raster is in
  single-buffer mode. The default value is 0, and the default buffering value is
  single buffer.

XGL_WIN_RAS_BUF_DRAW
  This attribute specifies the buffer for reading and writing pixels. All XGL
  drawing primitives take place in this buffer. The default value is 0.

XGL_WIN_RAS_BUF_MIN_DELAY This attribute specifies the minimum number of milliseconds to wait between switches of the display and draw buffers. Minimum delay allows the application to control the speed of the animation loop so it appears synchronized at a rate the application can support. The default value is 0.

XGL_WIN_RAS_BUFFERS_REQUESTED This attribute allocates a specified number of hardware buffers if supported by the hardware. If the hardware does not support multi-buffering, then only 1 buffer will be allocated. If the application sets the number to 1, XGL will do single buffering. If the value is set to 2, XGL will do double buffering, if double buffering is supported by the hardware and the underlying Window Raster. The application should perform a get on the attribute XGL_WIN_RAS_BUFFERS_ALLOCATED immediately after setting XGL_WIN_RAS_BUFFERS_REQUESTED, to determine how many buffers were allocated in the hardware. If the hardware supports only a single buffer, color map double buffering is possible. (For information about Color Map double buffering, see Chapter 6, "Color".)

The value of this attribute determines the valid values for the attributes XGL_WIN_RAS_BUF_DISPLAY and XGL_WIN_RAS_BUF_DRAW. The default value is 1 (single buffered).

XGL_WIN_RAS_BUFFERS_ALLOCATED This read-only attribute reflects the number of buffers allocated in the hardware underlying a Window Raster. The application must first set the XGL_WIN_RAS_BUFFERS_REQUESTED attribute to either 1 (single buffered) or 2 (double buffered). The value of this attribute determines the valid values for the attributes XGL_WIN_RAS_BUF_DISPLAY and XGL_WIN_RAS_BUF_DRAW. The default value is 1 (single buffered).

---

Note - Since the concurrent use of backing store and double buffering is not supported, XGL will enable whichever is requested first. If a request for double buffering is made by setting XGL_WIN_RAS_BUFFERS_REQUESTED to 2 and backing store has already been enabled, XGL will not initiate the double buffering request and will set the value of XGL_WIN_RAS_BUFFERS_ALLOCATED to 1.

---

XGL_WIN_RAS_MULTIBUFFER This attribute requests the multibuffering extension to X (MBX) for a window raster. The application must first create multiple buffers for the window using XmbufCreateBuffers(), which is an MBX API funciton. The application can then set this attribute to TRUE. It is application's responsibility to inform XGL of any subsequent multibuffer destruction and creation on the same window raster using the XGL_WIN_RAS_MULTIBUFFER attribute. The application should set this attribute to FALSE before destroying the MBX multibuffers through the MBX extension. The default value is FALSE. See the OpenWindows Server Programmer's Guide for information on the MBX API.

XGL_WIN_RAS_MBUF_DRAW This attribute specifies the buffer to read and write pixels into for multibuffering for all primitives. The buffer index specified as the attribute value should have one-to-one correspondence to those of the multibuffer array returned from the MBX API XmbufCreateBuffers(). The index can also be -1, which denotes rendering to the window. The application should explicitly set the buffer to draw to using the XGL_WIN_RAS_MBUF_DRAW attribute and use the MBX API XmbufDisplayBuffers() to display a particular buffer. Note that unlike double buffering, xgl_context_new_frame(3) does not switch the buffers for multibuffering. The default value is -1. See the OpenWindows Server Programmer's Guide for information on the MBX API.

XGL_WIN_RAS_BACKING_STORE This attribute enables backing store support for a Window Raster, after backing store support is requested through the Xlib call XChangeWindowAttributes(). Since concurrent use of backing store and double buffering is not supported, XGL will enable whichever is requested first. If a request for backing store is made by setting XGL_WIN_RAS_BACKING_STORE to TRUE and the value of XGL_WIN_RAS_BUFFERS_ALLOCATED is greater than 1, XGL will not initiate the backing store request and will set the value of XGL_WIN_RAS_BACKING_STORE to FALSE.

---

Note - The X server does not handle the copying of a Z-buffer or accumulation buffer for backing store. When a Z-buffer and/or an accumulation buffer is enabled and the display device uses a software Z-buffer and/or accumulation buffer, the backing store will share the software buffers with the display window, so the contents of the buffers will be the same without copying. If the display device uses a hardware Z-buffer and/or accumulation buffer, the buffers cannot be shared with the backing store. In this case, the device pipeline for the backing store will use a separate Z-buffer for rendering and/or a separate accumulation buffer to accumulate. The resulting image after damage repair is likely to be inaccurate, especially if the clip list has changed. Thus, backing store should not be used when accumulation is needed or when XGL_3D_CTX_HLHSR_MODE is set to XGL_HLHSR_Z_BUFFER for a 3D Context.

---

Memory Raster Attributes

XGL_MEM_RAS_IMAGE_BUFFER_ADDR This attribute reflects the address of the array of pixels for an XGL Memory Raster, allowing the application programmer to read and write pixel data. The application programmer must know the depth, width, and height of a Raster to access its pixel values correctly. The memory address varies depending on the Raster depth:

• 1-bit Rasters: The memory address points to the word containing the upper left pixel. The pixels are stored along the row as bits, the left-most pixel being the most significant bit (MSB) in the word. To allow each row to begin at a 16-bit boundary, padding can be added to the least significant bits of the word at the end of each row.

• 4-bit Rasters: The memory address points to the word containing the upper left pixel. Each byte contains two pixels stored along the row. Each row begins at a 16-bit boundary, and padding may be added to the row.
• 8-bit Rasters: The memory address points to the word containing the upper left pixel. Each byte contains one pixel, stored as an unsigned char, along the row. Each row begins at a 16-bit boundary.
• 32-bit Rasters: The memory address points to the word containing the upper-left pixel. Each pixel occupies 32 bits, and the pixels are aligned to the 32-bit boundary.

---

Note - When creating a Memory Raster, the application program must set the XGL_RAS_DEPTH, XGL_RAS_WIDTH, and XGL_RAS_HEIGHT attributes in the xgl_object_create() call before setting the XGL_MEM_RAS_IMAGE_BUFFER_ADDR attribute.

---

XGL_MEM_RAS_Z_BUFFER_ADDR This attribute reflects the starting address of the block of memory for the Z-buffer of a Memory Raster, allowing the application programmer to read and write Z-buffer values.

The Z-buffer is a collection of z values. Each z value occupies 32 bits. XGL accesses the least significant three bytes of the 32-bit word during Z-buffer operations. Thus, each row begins at a 32-bit word boundary. The Z-buffer of a Memory Raster has 24 bit planes and thus a depth of (2²⁴ - 1). The height of the Z-buffer is based on the raster height (XGL_RAS_HEIGHT), and the width is based on the raster width (XGL_RAS_WIDTH).

CGM Device Object

XGL can open and write to a Computer Graphics Metafile (CGM), Version 1. The XGL CGM file conforms to the ISO 8632:1985 standard. Metafiles are UNIX file streams that contain graphical information in a special format, and are used to store or interchange graphical information. A CGM is not a Raster Device. It is a data file consisting of a stream of graphical information. The CGM object uses higher-level primitives; the resulting output is compact and often easier to manipulate than a raster file. For example, modifying orientation is easier on CGM polygon data than on a polygon-shaped pixel area of a raster file.

The XGL CGM Device supports both 2D and 3D Contexts. However, the CGM standard deals strictly with 2D coordinates. The XGL implementation is further restricted to outputting only 2D integer coordinates. Although the CGM Device outputs only x and y coordinates, all stages of the XGL viewing pipeline are still supported. In the current implementation, stroke text, 3D circles, circular arcs, ellipses, elliptical arcs, and NURBs are output as polylines or polygons. Lines are interpolated, and surfaces are constant shaded. Picking is not supported. Although point colors and normals are ignored by the CGM device, the XGL pipeline processes them; therefore, face culling and face distinguishing are possible on a CGM device. Pixel operations are not supported in the current implementation. User-defined line and fill patterns are not supported.

The XGL implementation supports Binary, Character, and Clear Text CGM encoding formats. Both Long and Short integer coordinate representations are available in the current implementation. Floating point coordinates are not currently supported.

Creating a CGM Device

To create a CGM device, the application must supply the name of the XGL CGM library, XGL_CGM_LIB_NAME, in the Stream object descriptor. The name of the library is defined in the header file provided with the CGM device. At device creation time, the application can also pass in Stream device attributes. The code fragment below shows the creation of an XGL CGM device.

#include <stdlib.h>
#include <X11/Xlib.h>
#include <xgl/xgl.h>
#include <xgl/xgl_cgm-2.0.h>

static Xgl_3d_ctx        ctx = NULL;/* XGL context object */
static Xgl_sys_state sys_st;           /* XGL system state object */

main (argc, argv)
   int     argc;
   char    *argv[];
{
    Display              *display;   /* pointer to X display */
    Xgl_obj_desc         obj_desc;   /* XGL object descriptor */
    char*                     fname = "CGM_file";
    float                     scale_factor = 1000.0;
    Xgl_cgm                   cgm;
    Xgl_cgm_description      cgm_desc;

    if (argc == 2)
        fname = argv[1];

    sys_st = xgl_open(NULL);

    /* Use the XGL CGM pipeline provided with Solaris */
    obj_desc.stream.name = XGL_CGM_LIB_NAME;
    obj_desc.stream.desc = NULL;

    cgm_desc.cgm_fp = fopen(fname, "w");
    cgm_desc.cgm_signature = NULL;
    cgm_desc.cgm_description = NULL;
    cgm = xgl_object_create(sys_st,
                XGL_CGM_DEV, &obj_desc,
                XGL_DEV_COLOR_TYPE, XGL_COLOR_INDEX,
                XGL_CGM_DESCRIPTION, &cgm_desc,
                XGL_CGM_ENCODING, XGL_CGM_CLEAR_TEXT,
                XGL_CGM_VDC_EXTENT, XGL_CGM_VDC_EXT_SHORT,
                XGL_CGM_SCALE_MODE, XGL_CGM_METRIC,
                XGL_CGM_SCALE_FACTOR, &scale_factor,
                NULL);

  /* create XGL Context object using the CGM device */
  ctx = xgl_object_create (sys_st,
                XGL_3D_CTX, NULL,
                XGL_CTX_DEVICE, cgm,
                XGL_CTX_DEFERRAL_MODE, XGL_DEFER_ASAP,
                XGL_CTX_NEW_FRAME_ACTION, XGL_CTX_NEW_FRAME_CLEAR,
                 NULL);
}

Creating a Picture

The xgl_object_create() operator results in the following lines being inserted into a metafile on a CGM Device outputting clear text:

(open file)
BEGIN METAFILE <string1> /*signature from description*/
METAFILE VERSION 1
METAFILE DESCRIPTION <string2>
VDC TYPE INTEGER /*all metafiles are this type*/
METAFILE ELEMENT LIST
DRAWING BEGMFDEFAULTS ENDMFDEFAULTS COLRINDEXPREC MAXCOLRINDEX
INTEGERPREC REALPREC INDEXPREC COLORPREC COLRVALUEEXT
SCALEMODE COLRMODE LINEWIDTHMODE MARKERSIZEMODE

The xgl_object_destroy() operator destroys the CGM Device. When xgl_object_destroy() is invoked, the CGM device closes the current picture, if it isn't already closed. The CGM Device then ensures that an "end metafile" delimiter has been written, and flushes the output stream. The user must close the stream. As with any XGL device, a call to xgl_object_destroy() will not have an effect until all XGL objects using the device are destroyed. Overlooking this can result in incomplete metafiles, since the file will not be flushed or closed.

Invoking the xgl_context_new_frame() operator (used to delimit CGM pictures) starts a new picture element in the Metafile. The current color map, which should be loaded by this time, is output to the Metafile. The xgl_context_new_frame() operator results in the output of the "begin picture" delimiter to the Metafile. Any picture already open is closed, and a new picture is started.

The following Context attributes apply to the CGM Device:

XGL_CTX_DEFERRAL_MODE
XGL_CTX_DEVICE
XGL_CTX_VDC_ORIENTATION
XGL_CTX_BACKGROUND_COLOR

CGM Metafile Device Attributes

Since a CGM Device is not a Raster Device, none of the Raster Device-specific attributes apply. Attributes that affect CGM Device objects are:

XGL_CGM_TYPE
  This read-only attribute defines the type of CGM Metafile object associated
  with an XGL object; it cannot be modified later. It can be used to query the
  CGM Metafile object type when only a generic Xgl_cgm handle is known.
  The only type of CGM Metafile object that the XGL library currently
  supports is XGL_METAFILE_CGM_V1.

XGL_CGM_ENCODING This attribute defines the data representation used to store graphical objects in an XGL Metafile. The attribute can only be set before any part of the Metafile is written to the output stream, after which the attribute becomes read-only.

XGL supports three standard CGM encoding formats.

• XGL_CGM_CLEAR_TEXT uses the 94 printing characters from the ISO 646 7-bit code table to represent data. Designed to be "human-readable" and self-delimiting, clear text encoding is comparatively slow and complex to parse and generate. This is the default value.
• XGL_CGM_CHARACTER uses ASCII bytes, including control characters, to represent element codes and parameters. It is self-delimiting, although more compact than clear text encoding. Designed for transmission over communication lines, it is comparatively slow to parse and generate.
• XGL_CGM_BINARY uses internally formatted binary numbers to represent data. It is the fastest to read and write, and provides the most compact representation.

XGL_CGM_DESCRIPTION This attribute defines the Metafile header information and the file pointer to the Metafile output file. It can only be set before any part of the Metafile has been written to the output stream, after which the attribute becomes read-only. The Metafile description information is specified by the data type Xgl_cgm_description, which has three components:

• cgm_fp is the stream pointer where the Metafile should be written. If the file already exists, XGL appends the Metafile to it. If XGL is given a structure with the file pointer equal to NULL, the default value is stdout.

• cgm_signature is a string containing the Metafile label, which could include a description of the Metafile's contents. If XGL is given a structure with the string pointer equal to NULL, the default value is XGL 3.0 CGM 1.0 current date and time.

cgm_description is a string containing descriptive information about the Metafile, such as the author, the place of origin, and date and time of generation. If XGL is given a structure with the string pointer equal to NULL, the default value is: Sun Microsystems CGM TOP/FULL conformance.

XGL_CGM_SCALE_MODE This attribute defines the data representation used to store graphical objects in an XGL Metafile. It can only be set before any part of the Metafile has been written to the output stream, after which time the attribute becomes read-only. Two encoding formats are currently supported in XGL as defined by the data type Xgl_cgm_scale_mode:

• XGL_CGM_ABSTRACT means there is no correspondence between the range of coordinate values in the Metafile and the image it produces. In this case, the SCALEMODE will always be ABSTRACT, and the scale factor will always be 1.0. XGL_CGM_ABSTRACT is the default value.
• XGL_CGM_METRIC means there is a correspondence between the range of coordinate values in the Metafile and the image it produces. In this case, the SCALEMODE will be METRIC, and the scale factor (set with the attribute XGL_CGM_SCALE_FACT), will indicate the mapping between one unit in Metafile coordinate values and one millimeter in the displayed image. This mode allows images of predetermined size to be exchanged using CGM.

XGL_CGM_SCALE_FACTOR This attribute defines the scale factor used when the SCALEMODE delimiter is set to METRIC. It can only be set before any part of the Metafile has been written to the output stream, after which the attribute becomes read-only. The value is the address of a floating point number. The default scale value is 1.0.

XGL_CGM_PICTURE_DESCRIPTION This attribute defines the descriptive label for a picture within an XGL Metafile. It can only be set before any part of the Metafile has been written, after which the attribute becomes read-only. The picture name attribute is described as a string, Xgl_sgn8 *. This string value is output to the Metafile with the BEGIN PICTURE delimiter in the Metafile. This delimiter is written

(and a new picture started) when the user calls xgl_context_new_frame(). Any changes to the picture name attribute after this call does not affect the current picture.

XGL_DEV_COLOR_MAP This attribute permits the application to set its own Color Map into the Metafile, which will be used to specify the colors rendered into the Metafile. The attribute specifies the handle of the Color Map object to be associated with the Metafile Device. Once the Color Map is created, it is attached to the Metafile using the xgl_object_set() operator and this attribute. Color Map objects can only be attached to Rasters and Metafiles, not Contexts. The default value is a handle to a Color Map object containing a two-element, monochrome (black and white) color table if XGL_DEV_COLOR_TYPE is set to XGL_COLOR_INDEX and a 6-9-4 color cube is XGL_DEV_COLOR_TYPE is set to XGL_COLOR_RGB.

XGL_CGM_VDC_EXTENT This attribute controls the type and range of the coordinate values. XGL currently supports only integer extent. The values are:

• XGL_CGM_VDC_EXT_SHORT, a 16-bit VDC extent.
• XGL_CGM_VDC_EXT_LONG, a 32-bit VDC extent. This extent is implemented but not officially supported. This is due to overflow problems with transformations of 32-bit integers and floating point numbers in the XGL pipeline.

XGL CGM Line Patterns

CGM Metafiles only support a fixed set of line patterns. The default pattern is solid fill. User-defined line patterns or line pattern types not on the list below will default to solid lines. The line patterns supported are as follows:

xgl_lpat_cgm_dotted
xgl_lpat_cgm_dashed
xgl_lpat_dash_dot
xgl_lpat_dash_dot_dotted
xgl_lpat_long_dashed

An application must use the XGL attribute XGL_CTX_LINE_PATTERN or XGL_CTX_EDGE_PATTERN to achieve line or edge patterns in the CGM Metafile.

XGL CGM Markers

CGM Metafiles only support a fixed set of marker types. The default marker type is a dot marker. If there is no application data

(XGL_OBJ_APPLICATION_DATA) attached to the marker object currently in use, user-defined markers and marker types not on the list below default to dot markers. The marker types supported are as follows:

xgl_marker_dot
xgl_marker_plus
xgl_marker_asterisk
xgl_marker_circle
xgl_marker_cross

An application must use the XGL attribute XGL_CTX_MARKER to set the current marker type in the CGM Metafile.

An application can place user-defined markers in the CGM Metafile by setting the XGL_OBJ_APPLICATION_DATA attribute of the marker object to point to the marker data, as in the example below:

Xgl_marker               my_marker;
Xgl_sys_state            sys_state;
Xgl_pt_list_list         pll;
float                    scale_factor;

sys_state - xgl_open(<attribute-list>);
<Initialize pll for user-defined marker>;
<Set scale factor >;
my_marker = xgl_object_create(sys_state,
                         XGL_MARKER,NULL,
                         XGL_MARKER_DESCRIPTION, &pll,
                         XGL_OBJ_APPLICATION_DATA, &scale_factor,
                         0);

When application data is added to a Marker object, XGL will stroke out the marker into lines and scale these lines by a factor equal to the scale factor pointed to by the application data multiplied by XGL_CTX_MARKER_SCALE_FACTOR. Whereas normal markers have a fixed size, stroked out markers will scale as the size of the image producted from the CGM Metafile is changed.

Important Notes on Integrating XGL with a Windowing System

XGL is an output-only library. The application uses the window system's input and event mechanisms to provide interaction with the user. X toolkit and Xlib function calls interact with the OpenWindows environment to create and manipulate windows on the display device, and XGL draws into the X11 windows created by the application. If the canvas has been created using an X toolkit, the application must explicitly get the X window ID from the canvas to associate the canvas with a Window Raster. The Xlib XCreateWindow call returns the handle that XGL requires.

Mixing XGL and Xlib Drawing Routines

The DGA facility allows XGL to communicate directly with the graphics hardware, without going through the Xlib communications path to the server. Because of this, application programmers must be careful when mixing XGL and Xlib calls, as latencies involved with XGL communication with graphics hardware and Xlib communication with the server can result in geometry being drawn in an unexpected order. For example, a line drawn by an Xlib function may appear on the screen after a polygon drawn by XGL even though the Xlib function was called first. If the order in which the primitives are drawn is important to an application, the following precautions should be taken when mixing XGL and Xlib functions:

• An application that has finished drawing with XGL primitives should call xgl_context_flush(ctx,XGL_FLUSH_SYNCHRONIZE) to ensure that XGL primitives are displayed before calling Xlib functions. This operator should be called even if the XGL_CTX_DEFERRAL_MODE is XGL_ASAP.
• Xlib calls should be flushed with XSync before further XGL commands are issued.

Note also that when rendering and clearing the window with Xlib calls, the application must clear the window with xgl_context_new_frame() before rendering with XGL primitives, even if the window has previously been cleared with Xlib calls.

Window Resize Events

In OpenWindows, window resize events are not trapped internally by XGL. The application must explicitly handle these events with the XGL operator xgl_window_raster_resize(). This operator causes XGL to resize its Device Coordinate boundaries and, for 3D applications, update the size of the software Z-buffer and accumulation buffer, if applicable.

If the application will run as a DGA application, it should call XSync() before calling xgl_window_raster_resize() in order to synchronize XGL and the server. XView, and possibly other toolkits, may call the application resize procedure before sending the resize request to the server. This causes DGA to return a window size that is behind by one resize event. Calling XSync() before calling xgl_window_raster_resize() will prevent this problem.

---

Note - Be sure to check that the XGL Window Raster has been created before calling the xgl_window_raster_resize() operator. An error may occur if a the resize operator is called before the Window Raster is created.

---

Device Example Programs

The following programs illustrate creating Device objects using Xlib, the XView toolkit, and the OLIT toolkit. In an XGL program, the Xlib or X toolkit calls are interleaved with the XGL calls, and the results of the X and XGL calls share the same drawable area on the screen. The output of all three example programs is the same and is shown in Figure 5-1. The source code for the examples follows.

Figure 5-1 ow_olit.c

XGL and Xlib

The example program ow_xlib.c uses Xlib calls to create the window used by XGL. To compile this program, type make ow_xlib in the example program directory.

Code Example 5-1 Using XGL with Xlib

/* ow_xlib.c - attach XGL Window Raster to OpenWindows Xlib window */
/*
 * This program demonstrates how to create an XGL Window Raster given
 * an Xlib window.
 */

#include <stdio.h>
#include <X11/Xlib.h>

#include <X11/Xutil.h>
#include <xgl/xgl.h>

/* need this global so that quit_proc can get it */
static Xgl_objectsys_st;/* XGL System State object */

/* need this global so that repaint procedure can get it */
static Xgl_objectctx = NULL;/* XGL graphics Context object */

main (
    intargc,
    char*argv[])
{
    Xgl_object       win_ras = NULL;/* XGL Window Raster object */
    Xgl_X_window     xgl_x_win;        /* XGL-X data structure */
    Xgl_obj_desc     win_desc;         /* XGL win ras structure */

    Xgl_pt_list      pl;
                                       /* polygon point structure */
    Xgl_pt_i2d       pts_i2d[3];       /* integer 2d points */

    Display          *display;
                                       /* X display data structure */
    int              screen;           /* X screen */
    Visual           *vis;             /* X color visual */
    Window           win;              /* X window */
    XSetWindowAttributes attrs; /* X create window attributes */
    XEvent           event;            /* X event */

    intdone = 0;/* quit flag */

    /* open X display */
    if ((display = XOpenDisplay (NULL)) == NULL) {
        (void) fprintf (stderr, "cannot open display\n");
        exit (1);
    }

    /* get screen number for this display */
    screen = DefaultScreen (display);

    /* express interest in these events */
    attrs.event_mask = ButtonPressMask | ButtonReleaseMask |
                         ExposureMask;

    /* create window of type visual */
    if (!(win = XCreateWindow (display,
               RootWindow (display, screen),
               10, 10, 500, 500, 1,

               XDisplayPlanes (display, 0),
               CopyFromParent, CopyFromParent,
               CWEventMask, &attrs))) {
        printf ("can't create visual window\n");
        exit (1);
    }
    XSetStandardProperties (display, win,
                              "Press any mouse button to quit",
                              "X-Xgl", None, argv, argc, NULL);

    /* map and wait for exposure */
    XMapWindow (display, win);
    do {
        XNextEvent (display, &event);
    } while (event.type != Expose);

    /* create XGL System State object */
    sys_st = xgl_open (NULL);

    /* copy X information into XGL data structure */
    xgl_x_win.X_display = (void *) display;
    xgl_x_win.X_window = (Xgl_usgn32) win;
    xgl_x_win.X_screen = (int) screen;

    /* create Window Raster Device using XView canvas */
    win_desc.win_ras.type = XGL_WIN_X | XGL_WIN_X_PROTO_DEFAULT;
    win_desc.win_ras.desc = &xgl_x_win;

    win_ras = xgl_object_create (sys_st, XGL_WIN_RAS, &win_desc,
                                 XGL_DEV_COLOR_TYPE, XGL_COLOR_INDEX,
                                    NULL);

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

    /* clear canvas area to default background color of black */
    xgl_context_new_frame (ctx);
    /* setup data points for a triangle */
    /* XGL will close the triangle */
    pts_i2d[0].x = 25;
    pts_i2d[0].y = 50;
    pts_i2d[1].x = 50;

    pts_i2d[1].y = 400;
    pts_i2d[2].x = 250;
    pts_i2d[2].y = 375;

    /* fill XGL polygon data structure */
    pl.pt_type = XGL_PT_I2D;
    pl.num_pts = 3;
    pl.bbox = 0;
    pl.pts.i2d = &pts_i2d[0];

    /* draw a polygon in the default color of white */
    xgl_polygon (ctx, XGL_FACET_NONE, 0, 0, 1, &pl);

    /* wait for user input and quit on key press event */
    done = 0;
    while (!done) {
        XNextEvent (display, &event);
        if (event.type == Expose) {
            if (!event.xexpose.count) {
                xgl_window_raster_resize(win_ras);
                /* clear rendering area */
                xgl_context_new_frame (ctx);
                /* draw a polygon in default color of white */
                xgl_polygon (ctx, XGL_FACET_NONE, 0, 0, 1, &pl);
            }
        }
        else if (event.type == ButtonPress) {
            done = 1;
        }
    }

    xgl_context_post(ctx, TRUE);

    /* close XGL and free all memory used by XGL */
    xgl_close (sys_st);

    /* destroy X11 resources used */
    XDestroyWindow (display, win);
    XCloseDisplay (display);

    exit (0);
}

XGL and the XView Toolkit

The example program ow_xview.c uses the XView toolkit to create the window used by XGL. To compile this program, type make ow_xview in the example program directory.

Code Example 5-2 Using XGL with XView

/* ow_xview.c - attach XGL Window Raster to OpenWindows XView canvas
*/

/*
 * This program demonstrates how to create an XGL Window Raster given
 * an XView canvas.
 */

#include <stdio.h>
#include <X11/Xlib.h>
#include <X11/Xutil.h>
#include <xview/xview.h>
#include <xview/canvas.h>
#include <xview/xv_xrect.h>

#include <xgl/xgl.h>

/*
 * need this global so that quit_proc can get it
 */
static Xgl_object    sys_st;    /* XGL System State object */

/*
 * need this global so that repaint procedure can get to it
 */
static Xgl_object    ctx = NULL; /* Graphics Context object */
static Xgl_object    win_ras = NULL; /* Xgl window raster */

void    event_proc (Xv_Window, Event*, Notify_arg);
void    repaint_proc (Canvas, Xv_Window, Display*, Window,
                         Xv_xrectlist*);
Notify_value    quit_proc (Frame, Destroy_status);

main (
    int              argc,
    char             *argv[])

{
    Xgl_X_window     xgl_x_win;  /* XGL-X data structure */
    Xgl_obj_desc     win_desc;   /* Window raster structure */

    Frame            frame;   /* XView frame around window */
    Canvas           canvas;  /* XView canvas in frame */

    Xv_Window        pw;             /* XView paint window */
    Window           frame_window;   /* XID of frame */
    Window           canvas_window;  /* XID of canvas */

    Display          *display;       /* pointer to X display */
    int              screen;         /* X screen number */

    xv_init (XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

    /*
     * create a XView simple window frame - WIN_DYNAMIC_TRUE must be
     * specified for OW 1.0 where the default is static color maps
     */
    frame = xv_create (NULL, FRAME,
                       FRAME_LABEL,     "View Window",
                       WIN_DYNAMIC_VISUAL,    TRUE,
                       OPENWIN_AUTO_CLEAR,    FALSE,
                       CANVAS_RETAINED,       FALSE,
                       CANVAS_FIXED_IMAGE,    FALSE,
                       WIN_DEPTH,             8,
                       XV_VISUAL_CLASS,       PseudoColor,
                       NULL);

    /*
     * create XView canvas - WIN_DYNAMIC_TRUE must be specified OW
     * where the default is static color maps
     */
    /* set event and repaint procedures */
    canvas = xv_create (frame, CANVAS,
                        WIN_DYNAMIC_VISUAL,     TRUE,
                        OPENWIN_AUTO_CLEAR,     FALSE,
                        CANVAS_RETAINED,        FALSE,
                        WIN_EVENT_PROC,         event_proc,
                        CANVAS_REPAINT_PROC,    repaint_proc,
                        WIN_DEPTH,              8,
                        XV_VISUAL_CLASS,        PseudoColor,
                        NULL);

    /* get X stuff */

    display = (Display *) xv_get (frame, XV_DISPLAY);

    pw = (Xv_Window) canvas_paint_window (canvas);
    canvas_window = (Window) xv_get (pw, XV_XID);
    frame_window  = (Window) xv_get (frame, XV_XID);

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

    /* wait for the window */
    sleep (2);

    /* create XGL System State object */
    sys_st = xgl_open (NULL);

    /* create Window Raster Device using XView canvas */
    win_desc.win_ras.type = XGL_WIN_X;
    win_desc.win_ras.desc = &xgl_x_win;
    win_ras = xgl_object_create (sys_st, XGL_WIN_RAS, &win_desc,
                                    NULL);

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

    /* set quit procedure where xgl_close is called */
    notify_interpose_destroy_func (frame, quit_proc);

    /* go into XView loop */

    exit (0);
}

static
void
event_proc (
    Xv_Window            window,
    Event               *event,
    Notify_arg           arg)
{
    switch (event_action (event)) {

        /*
         * not anything to do here, but mouse and keyboard
         * events should be tracked in this procedure
         */
    default:
        break;
    }
}

/*
 * Xview repaint procedure.  Draw the polygon in this function.
 */
static
void
repaint_proc (
    Canvas              local_canvas,
    Xv_Window           local_pw,
    Display             *dpy,
    Window              xwin,
    Xv_xrectlist        *xrects)
{
    Xgl_pt_list         pl;  /* polygon point structure */
    Xgl_pt_i2d          pts_i2d[3]; /* integer 2d points */

    xgl_window_raster_resize(win_ras);

    /* clear canvas area to default background color of black */
    xgl_context_new_frame (ctx);

    /* setup data points for a triangle - XGL will close triangle */
    pts_i2d[0].x = 25;
    pts_i2d[0].y = 50;
    pts_i2d[1].x = 50;
    pts_i2d[1].y = 400;
    pts_i2d[2].x = 250;
    pts_i2d[2].y = 375;

    /* fill XGL polygon data structure */
    pl.pt_type = XGL_PT_I2D;
    pl.num_pts = 3;
    pl.bbox = 0;
    pl.pts.i2d = &pts_i2d[0];

    /* draw a polygon in the default color of white */
    xgl_polygon (ctx, XGL_FACET_NONE, 0, 0, 1, &pl);

}
static
Notify_value
quit_proc (
    Frame               fr,
    Destroy_status      status)
{
    if (status == DESTROY_CHECKING) {
        xgl_close (sys_st);
    }
    return (notify_next_destroy_func (fr, status));
}

XGL and the OLIT Toolkit

The example program ow_olit.c uses the OLIT toolkit calls to create the window used by XGL. To compile this program, type make ow_olit in the example program directory.

Code Example 5-3 Using XGL with OLIT

/* ow_olit.c - attach XGL Window Raster to OLIT stub widget */

/*
 * This program demonstrates how to create an XGL Window
 * Raster given an OLIT stub widget.
 */

#include <stdio.h>
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/DrawArea.h>

#include <xgl/xgl.h>

/*
 * need these global so that expose procedure can get to them
 */
static Xgl_object        ctx = NULL;/* XGL Context object */
static Xgl_object        sys_st;       /* XGL System State object */
static Xgl_object        win_ras = NULL; /* XGL Window Raster */

main (
    int                  argc;
    char                 *argv[])
{
    Xgl_X_window         xgl_x_win; /* XGL-X data structure */
    Xgl_obj_desc         win_desc;     /* Window raster struct */

    Widget               toplevel;
                                       /* Widget top-level */
    Widget               drawable;     /* Drawable widget */
    XtAppContext         app;

    Window               window;
                                       /* X window for canvas */
    Display              *display;     /* pointer to X display */

    void                 repaint(); /* OLIT repaint procedure */
    /*
     * Initialize toolkits
     */
    OlToolkitInitialize((XtPointer)NULL);
    toplevel = XtVaAppInitialize (&app, "ow_olit",
                (XrmOptionDescList)NULL, 0,
                &argc, argv, (String *)NULL,
                XtNtitle, "Simple OLIT Drawable",
                XtVaTypedArg, XtNvisual, XtRString,
                "PseudoColor", sizeof("PseudoColor"),
                NULL);

    /*
     * Create a draw area widget for rendering graphics
     * and add expose callback to draw area widget
     */
    drawable = XtVaCreateManagedWidget("drawable",
                drawAreaWidgetClass, toplevel,
                XtNlayout, OL_IGNORE,
                XtNheight, 512,
                XtNwidth,  512,
                NULL);
    XtAddCallback(drawable, XtNexposeCallback, repaint,
                     (XtPointer) NULL);

    XtRealizeWidget(toplevel);

    /* get X stuff */
    display = (Display *) XtDisplay (drawable);
    window = (Window) XtWindow (drawable);

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

    /* wait for the window */
    sleep (2);

    /* create XGL System State object */
    sys_st = xgl_open (NULL);

    /* create Window Raster Device using OLIT widget */
    win_desc.win_ras.type = XGL_WIN_X;
    win_desc.win_ras.desc = &xgl_x_win;
    win_ras = xgl_object_create (sys_st, XGL_WIN_RAS, &win_desc,
                                   NULL);

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

    /* go into Xt main loop and wait for expose events */
    XtAppMainLoop(app);

    exit (0);
}

/*
 * Xgl repaint procedure called on expose events
 */
static
void
repaint ()
{
    Xgl_pt_list          pl;           /* polygon point structure */
    Xgl_pt_i2d           pts_i2d[3];/* integer 2d points */

    /* clear draw area to default background color of black */
    xgl_context_new_frame (ctx);

    /* set up data points for a triangle - XGL will close triangle */
    pts_i2d[0].x = 25;
    pts_i2d[0].y = 50;
    pts_i2d[1].x = 50;

    pts_i2d[1].y = 400;
    pts_i2d[2].x = 250;
    pts_i2d[2].y = 375;

    /* fill XGL polygon data structure */
    pl.pt_type = XGL_PT_I2D;
    pl.num_pts = 3;
    pl.bbox = 0;
    pl.pts.i2d = &pts_i2d[0];

    /* draw a polygon in the default color of white */
    xgl_polygon (ctx, XGL_FACET_NONE, 0, 0, 1, &pl);
}

Transparent Overlay Windows

The XGL library supports the use of transparent overlay windows. Overlay windows allow applications to render simple temporary items such as menus on complex rendering in the underlying window. When geometry in the overlay is cleared, the complex rendering does not need to be regenerated.

The transparent overlay functionality in XGL requires the Solaris overlay extension in the Solaris Visual environment. For details on how to verify that the server includes the overlay extension, see the OpenWindows Server Programmer's Guide.

Creating an Overlay Window

An overlay window is always associated with another window, called an underlay window. An overlay window remains associated with the same underlay window throughout its lifetime, and the underlay window is the parent of the overlay window.

An XGL overlay window is created as an XGL window raster, and like other XGL window rasters, an overlay window must have information on the Xll window that XGL will render to. The application will open an X window for the underlay window and another for the overlay window. The application will then copy the X information for these windows into XGL window descriptor structures and create XGL window rasters.

The code fragment below shows an initialization routine for the XGL window rasters for a pair of underlay and overlay windows. For information on creating the X overlay and underlay windows using the Solaris overlay extension function calls, see the OpenWindows Server Programmer's Guide.

#include <stdio.h>
#include <sys/file.h>
#include <X11/Xos.h>
#include <X11/Xlib.h>
#include <X11/Xatom.h>
#include <X11/Xutil.h>
#include <X11/keysym.h>
#include <X11/extensions/transovl.h>
#include <xgl/xgl.h>

#define BORDER_WIDTH 0

Display    *dsp = NULL;/* important that this be initialized */
Window          underlay, overlay;
GC              ovgc, gc;
XSizeHints      size_hints;
int             screen, height, width;
XColor          ovblack, ovwhite;

Xgl_sys_state        sys_st;
Xgl_cmap             xgl_cmap, ov_cmap;
Xgl_win_ras          win_ras, ov_win_ras;
Xgl_2d_ctx           ctx, ov_ctx;
Xgl_color            ovl_white, ovl_black;

#define     OV_WHITE_IDX0
#define     OV_BLACK_IDX1

void
init(argc, argv)
    int         argc;
    char       *argv[];
{
    XSetWindowAttributes               xswa;
    Visual                             *vis;
    XSolarisOvlVisualCriteria          visCriteria;
    XSolarisOvlSelectStatus            status;
    unsigned long                      ovFailures;
    XVisualInfo                        ovInfo, winInfo;

    Visual                             *ovvisual;
    Colormap                           cmap, ovcmap;
    int                                major_opcode, event_base,
                                       error_base;
    Window                             root;

    Xgl_X_window         xgl_x_win;/* XGL-X data structure */
    Xgl_obj_desc         win_desc;/* XGL window raster structure */

    /* Open X display */
    if ((dsp = XOpenDisplay (NULL) ) == NULL) {
        (void) fprintf (stderr, "cannot open display\n");
        exit (1);
    }

   /* Create the X windows for the Solaris overlay and */
   /* underlay windows. */

    /* Set up XGL for rendering to underlay window. */
    sys_st = xgl_open(NULL);

    cmap = xgl_object_create (sys_st, XGL_CMAP, NULL,
            XGL_CMAP_NAME, cmap,
            XGL_CMAP_COLOR_TABLE_SIZE, 2,
            NULL);

    xgl_x_win.X_display = (void *) dsp;
    xgl_x_win.X_window = (Xgl_usgn32) underlay;
    xgl_x_win.X_screen = (int) screen;

    win_desc.win_ras.type = XGL_WIN_X | XGL_WIN_X_PROTO_DEFAULT;
    win_desc.win_ras.desc = &xgl_x_win;

    win_ras = xgl_object_create (sys_st, XGL_WIN_RAS, &win_desc,
            XGL_DEV_COLOR_MAP, cmap,
            NULL);

    ctx = xgl_object_create (sys_st, XGL_2D_CTX, NULL,
            XGL_CTX_DEVICE, win_ras,
            XGL_CTX_DEFERRAL_MODE, XGL_DEFER_ASTI,
            XGL_CTX_STEXT_CHAR_HEIGHT, 20.0,
            NULL);

    /* Set up XGL for rendering to overlay window. */

    /* These pixel values need to be contiguous and */
    /* in increasing order */
    pixels[OV_WHITE_IDX] = ovwhite.pixel;
    pixels[OV_BLACK_IDX] = ovblack.pixel;
    ovl_white.index = OV_WHITE_IDX;
    ovl_black.index = OV_BLACK_IDX;

    ov_cmap = xgl_object_create (sys_st, XGL_CMAP, NULL,
            XGL_CMAP_NAME, ovcmap,
            XGL_CMAP_COLOR_TABLE_SIZE, 2,
            NULL);

    xgl_x_win.X_display = (void *) dsp;
    xgl_x_win.X_window = (Xgl_usgn32) overlay;
    xgl_x_win.X_screen = (int) screen;

    win_desc.win_ras.type = XGL_WIN_X | XGL_WIN_X_PROTO_DEFAULT;
    win_desc.win_ras.desc = &xgl_x_win;

    ov_win_ras = xgl_object_create (sys_st, XGL_WIN_RAS, &win_desc,
            XGL_DEV_COLOR_MAP, ov_cmap,
            XGL_DEV_COLOR_TYPE, XGL_COLOR_INDEX,
            XGL_WIN_RAS_PIXEL_MAPPING, pixels,
            NULL);

    ov_ctx = xgl_object_create (sys_st, XGL_2D_CTX, NULL,
            XGL_CTX_DEVICE, ov_win_ras,
            XGL_CTX_DEFERRAL_MODE, XGL_DEFER_ASTI,
            XGL_CTX_STEXT_CHAR_HEIGHT, 20.0,
            NULL);

   /* Note that the application may want to get transforms */
   /* and other sharable object handles from the underlay */
   /* ctx and set them on ov_ctx to share them between contexts. */

   xgl_object_get(ctx, XGL_CTX_LOCAL_MODEL_TRANS, &lmod_trans);
   xgl_object_get(ctx, XGL_CTX_GLOBAL_MODEL_TRANS, &gmod_trans);
   xgl_object_get(ctx, XGL_CTX_VIEW_TRANS, &view_trans);

   xgl_object_set(ov_ctx, XGL_CTX_LOCAL_MODEL_TRANS, lmod_trans,
                              XGL_CTX_GLOBAL_MODEL_TRANS, gmod_trans,
                              XGL_CTX_VIEW_TRANS, &view_trans,
                              NULL);
}

Rendering to an Overlay Window

In the transparent overlay model, the pixels, or paint, has a characteristic called the paint type. The paint type can be either opaque or transparent. Pixels rendered with an opaque paint type obscure pixels in underlying windows. Pixels rendered transparently have no intrinsic color and derive their color from the pixels that lie beneath them. This allows the application to selectively erase the contents of the overlay window in such a way that the graphics in the underlay window show through.

In an XGL application, the paint type is set on the Context object using the XGL_CTX_PAINT_TYPE attribute. This attribute can be set to XGL_PAINT_OPAQUE, which is the default value, or XGL_PAINT_TRANSPARENT. The attribute XGL_CTX_PAINT_TYPE has an effect only when the Device associated with a Context is an overlay window; otherwise, XGL_CTX_PAINT_TYPE is ignored, and the paint type is opaque.

Most XGL primitives will render pixels into overlay windows. Note, however, the following exceptions:

• xgl_context_accumulate() - Only the color information of the draw buffer is accumulated into an overlay window that is the destination buffer of the accumulation. The paint type is not changed.
• xgl_context_copy_buffer() - If the Device associated with the Context is an overlay window, the color information of the source raster is copied to the destination raster as follows:

  · If the source raster is an overlay window and the destination raster is also an overlay window, the color and paint type are copied to the destination.

  · If the source raster is an overlay window but the destination raster is not an overlay window, the color is copied to the destination. If the source paint type is transparent, the color is undefined.

  In addition, if the source raster is not an overlay window but the destination raster is an overlay window, the pixel color is copied, and the paint type of the destination is not changed.

To clear the overlay window, the application can use the attribute XGL_CTX_NEW_FRAME_PAINT_TYPE set to XGL_PAINT_TRANSPARENT, which is the default value. The XGL_CTX_NEW_FRAME_PAINT_TYPE attribute is applied when an application calls xgl_context_new_frame() and

XGL_CTX_NEW_FRAME_ACTION includes XGL_CTX_NEW_FRAME_CLEAR. In this case, the color information is set to the background color, and the paint type is set to the value of XGL_CTX_NEW_FRAME_PAINT_TYPE.

The code fragment below shows the use of the XGL_CTX_PAINT_TYPE attribute.

void
draw(window, x, y, w, h)
    Window window;
    int         x,
                y,
                w,
                h;
{
    int                  i, j;
    Xgl_rect_list        rl;
    Xgl_rect_i2d         rect_i2d[3];
    Xgl_pt_list          pl[5];
    Xgl_pt_i2d           pt_i2d[500];

    if (window == overlay) {

        xgl_object_set (ov_ctx,
            XGL_CTX_LINE_COLOR, &ovl_black,
            XGL_CTX_MARKER_COLOR, &ovl_black,
            XGL_CTX_STEXT_COLOR, &ovl_black,
            XGL_CTX_SURF_FRONT_COLOR, &ovl_black,
            XGL_CTX_BACKGROUND_COLOR, &ovl_white,
            NULL);

       /* Fill Rectangle */

    xgl_object_set (ov_ctx,
            XGL_CTX_PAINT_TYPE, XGL_PAINT_OPAQUE,
            XGL_CTX_SURF_FRONT_FILL_STYLE, XGL_SURF_FILL_SOLID,
            NULL);

    rect_i2d[0].corner_min.x = 0;
    rect_i2d[0].corner_min.y = 0;
    rect_i2d[0].corner_min.flag = FALSE;
    rect_i2d[0].corner_max.x = 900;
    rect_i2d[0].corner_max.y = 250;
    rl.num_rects = 1;
    rl.rect_type = XGL_MULTIRECT_I2D;

    rl.bbox = NULL;
    rl.rects.i2d = rect_i2d;
    xgl_multirectangle (ov_ctx, &rl);

   /* Polylinse */
   pt_i2d[0].x = 275; pt_i2d[0].y = 50;
   pt_i2d[1].x = 275; pt_i2d[1].y = 200;
   pt_i2d[2].x = 285; pt_i2d[2].y = 50;
   pt_i2d[3].x = 285; pt_i2d[3].y = 200;
   pt_i2d[4].x = 295; pt_i2d[4].y = 50;
   pt_i2d[5].x = 295; pt_i2d[5].y = 200;
   pt_i2d[6].x = 305; pt_i2d[6].y = 50;
   pt_i2d[7].x = 305; pt_i2d[7].y = 200;
   pt_i2d[8].x = 315; pt_i2d[8].y = 50;
   pt_i2d[9].x = 315; pt_i2d[9].y = 200;
   pl[0].pt_type = XGL_PT_I2D;
   pl[0].bbox = NULL;
   pl[0].num_pts = 10;
   pl[0].pts.i2d = pt_i2d;

   xgl_object_set (ov_ctx,
            XGL_CTX_PAINT_TYPE, XGL_PAINT_TRANSPARENT,
            NULL);

   xgl_multipolyline (ov_ctx, NULL, 1, pl);

   for (i=0; i<10; i++)
        pt_i2d[i].y += 250;

   xgl_object_set (ov_ctx,
            XGL_CTX_PAINT_TYPE, XGL_PAINT_OPAQUE,
            NULL);

   xgl_multipolyline (ov_ctx, NULL, 1, pl);
   }
}

Determining Device Acceleration

XGL accelerates a primitive if some portion of the geometry is processed directly by accelerating hardware. Acceleration can speed up geometric transformations and clipping, as well as actual rendering. To determine what acceleration features underlie a window, an application can use the xgl_inquire() operator. xgl_inquire() is defined as:

Xgl_inquire* xgl_inquire( Xgl_sys_state sys_state Xgl_obj_desc *desc);

The parameter desc contains window information. The operator returns a pointer to a structure of type Xgl_inquire. This structure contains the following fields of information about the frame buffer underlying the window:

Table 5-2 xgl_inquire()

Field	Information
Name	The XGL name of the frame buffer underlying the window.
DGA flag	Specifies whether XGL does direct graphics access to render pixels into the frame buffer underlying the window. If DGA is not available, XGL uses Xlib or PEXlib to render pixels.
Color type	Indicates whether the frame buffer is color index or RGB.
Depth	Specifies the depth of the frame buffer underlying the window.
Width	Specifies the width of the frame buffer in pixel coordinates.
Height	Specifies the height of the frame buffer in pixel coordinates.
Maximum buffer	Specifies the maximum number of buffers available from the frame buffer underlying the window. A value of two means the application might be able to perform double buffering.
Double buffer is copy	Specifies whether the underlying hardware device performs double buffering by copying pixels from the draw (hidden) buffer to the display buffer.
Point type	Specifies the point types supported by the frame buffer.
HLHSR mode	Indicates whether the frame buffer underlying the window directly supports a Z-buffer and Z-buffer rendering.

Table 5-2 xgl_inquire()

Field	Information
Picking Double buffer Indexed color True color Depth cueing Lighting Shading Antialiasing HLHSR	These fields reflect the capabilities of the underlying hardware accelerator, if any. If the accelerator does not support this functionality, these fields are set to XGL_INQ_NOT_SUPPORTED. If support for the functionality is provided through software emulation, these fields are set to XGL_INQ_SOFTWARE. If hardware acceleration is provided, these fields are set to XGL_INQ_HARDWARE.
Stereo	Specifies whether the device underlying the window raster has hardware support for stereo.
Extensions	Bitmask indicating the extensions supported by the frame buffer underlying the window. Currently, only queries for the multibuffer extension to X (MBX). To determine whether MBX is supported, AND the value of this field with the bitmask XGL_INQ_MULTI_BUFFERING. If the result is not zero, the frame buffer supports MBX.

---

Note - The application must open XGL with a call to xgl_open() before calling xgl_inquire(). Device characteristics cannot be queried before XGL is open.

---

Inquire Example Program

The program inq.c shows the use of xgl_inquire(). To compile this program, type make inq in the example program directory. An example of program output for a particular hardware device is shown in Figure 5-2. The source code for the example follows.

# inq Inquire Information: Sun:GX Direct Graphics Access Color Model: INDEXED Depth : 8 Width : 1152 Height: 900 Single Buffering Using bitblt transfer Point Types: 2D 3D INT FLOAT Software Zbuffer in host Picking emulated in software Double buffering emulated in software Index colors accelerated through hardware True colors emulated in software Depth cueing emulated in software Lighting emulated in software Shading emulated in software Hidden line removal emulated in software Antialiasing emulated in software No stereo support No Multi Buffering support #

Figure 5-2 Output of inq.c

Code Example 5-4 Inquire Example

/*
 * inq.c
 */

#include <stdio.h>
#include <math.h>
#include <xgl/xgl.h>
#include <X11/Xlib.h>

/* Xgl inquiry function */

/*
 * main routine
 *      description:
 *          This example program opens an Xlib display and window
 *          and uses the Xgl inquiry function to determine the
 *          hardware features underlying that window.
 *      arguments:
 *              -display [X display number]
 */

static  char    *colon_zero = ":0";

main(
    int              argc,
    char             *argv[])
{
    Xgl_object       sys_st;
    Xgl_obj_desc     obj_desc; /* XGL window system information */
    Xgl_inquire      *inq_info;     /* Xgl inquiry structure */
    Xgl_X_window     xgl_x_win;     /* Xgl to X structure */
    char             *display_name; /* name of X display */
    Display          *display;      /* Xlib display structure */
    int              screen;        /* screen for X display */
    Window           window;        /* X window we create */

    if (argc < 2)
        display_name = colon_zero;
    else
        display_name = argv[2];

    display = XOpenDisplay(display_name);

    if (display == (Display *)NULL) {
        printf("could not open display %s\n", display_name);
        exit(1);
    }
    screen = DefaultScreen(display);

 window = XCreateSimpleWindow(
        display,                      /* Xlib display structure */
        RootWindow(display, screen),  /* use X root window */
        0, 0,                         /* x, y position */
        1, 1,                         /* width, height */
        1,                            /* border width in pixels */
        BlackPixel(display, screen),  /* border color */
        BlackPixel(display, screen)); /* background color */

    if (window == 0) {
        printf("could not open window %s\n", display_name);
        exit(1);
    }

    sys_st = xgl_open (XGL_SYS_ST_ERROR_DETECTION, TRUE,
                       NULL);

    xgl_x_win.X_display = (void *)display;
    xgl_x_win.X_screen = screen;
    xgl_x_win.X_window = window;

    obj_desc.win_ras.type = XGL_WIN_X;
    obj_desc.win_ras.desc = &xgl_x_win;
    if (!(inq_info = xgl_inquire(sys_st, &obj_desc))) {
      printf("error getting inquiry\n");
      exit(1);
    }

    printf("Inquire Information:\n");

    printf("  %s\n", inq_info->name);
    if (inq_info->dga_flag)
        printf("  Direct Graphics Access\n");
    else
        printf("  Xlib port\n");

    printf("    Accelerated Color Type(s): ");
    if (!inq_info->color_type.index &&
        !inq_info->color_type.rgb)

        printf("None\n");
    else {
        if (inq_info->color_type.index)
            printf("INDEXED ");
        if (inq_info->color_type.rgb)
          printf("RGB ");
        printf("\n");
    }
    printf("    Depth : %d\n", inq_info->depth);
    printf("    Width : %d\n", inq_info->width);
    printf("    Height: %d\n", inq_info->height);
    if (inq_info->maximum_buffer == 1)
        printf("    Single Buffering\n");
    if (inq_info->maximum_buffer == 2)
        printf("    Double Buffering\n");
    if (inq_info->maximum_buffer > 2)
        printf("    Multiple Buffering (%d)\n",
                         inq_info->maximum_buffer);
    if (inq_info->db_buffer_is_copy)
        printf("      Using bitblt transfer\n");
    else
        printf("      Using hardware swap\n");
    printf("    Point Types:\n");
    if (!inq_info->pt_type.pt_dim_2d &&
        !inq_info->pt_type.pt_dim_3d &&
        !inq_info->pt_type.pt_type_int &&
        !inq_info->pt_type.pt_type_float) {
      printf("        None (?)\n");
    }
    else {
      if (inq_info->pt_type.pt_dim_2d)
          printf("        2D\n");
      if (inq_info->pt_type.pt_dim_3d)
          printf("        3D\n");
      if (inq_info->pt_type.pt_type_int)
          printf("        INT\n");
      if (inq_info->pt_type.pt_type_float)
          printf("        FLOAT\n");
    }
    if (inq_info->hlhsr_mode == XGL_HLHSR_NONE)
        printf("    Software Zbuffer in host\n");
    if (inq_info->hlhsr_mode == XGL_HLHSR_ZBUFFER)
        printf("    Hardware Zbuffer\n");

    if (inq_info->picking == XGL_INQ_NOT_SUPPORTED)
        printf("    Picking not supported\n");

    else if (inq_info->picking == XGL_INQ_SOFTWARE)
        printf("    Picking emulated in software\n");
    else if (inq_info->picking == XGL_INQ_HARDWARE)
        printf("    Picking accelerated through hardware\n");

    if (inq_info->double_buffer == XGL_INQ_NOT_SUPPORTED)
        printf("    Double buffering not supported\n");
    else if (inq_info->double_buffer == XGL_INQ_SOFTWARE)
        printf("    Double buffering emulated in software\n");
    else if (inq_info->double_buffer == XGL_INQ_HARDWARE)
        printf("    Double buffering accelerated through hardware\n");

    if (inq_info->indexed_color == XGL_INQ_NOT_SUPPORTED)
        printf("    Index colors not supported\n");
    else if (inq_info->indexed_color == XGL_INQ_SOFTWARE)
        printf("    Index colors emulated in software\n");
    else if (inq_info->indexed_color == XGL_INQ_HARDWARE)
        printf("    Index colors accelerated through hardware\n");

    if (inq_info->true_color == XGL_INQ_NOT_SUPPORTED)
        printf("    True colors not supported\n");
    else if (inq_info->true_color == XGL_INQ_SOFTWARE)
        printf("    True colors emulated in software\n");
    else if (inq_info->true_color == XGL_INQ_HARDWARE)
        printf("    True colors accelerated through hardware\n");

    if (inq_info->depth_cueing == XGL_INQ_NOT_SUPPORTED)
        printf("    Depth cueing not supported\n");
    else if (inq_info->depth_cueing == XGL_INQ_SOFTWARE)
        printf("    Depth cueing emulated in software\n");
    else if (inq_info->depth_cueing == XGL_INQ_HARDWARE)
        printf("    Depth cueing accelerated through hardware\n");

    if (inq_info->lighting == XGL_INQ_NOT_SUPPORTED)
        printf("    Lighting not supported\n");
    else if (inq_info->lighting == XGL_INQ_SOFTWARE)
        printf("    Lighting emulated in software\n");
    else if (inq_info->lighting == XGL_INQ_HARDWARE)
        printf("    Lighting accelerated through hardware\n");

 if (inq_info->shading == XGL_INQ_NOT_SUPPORTED)
        printf("    Shading not supported\n");
    else if (inq_info->shading == XGL_INQ_SOFTWARE)
        printf("    Shading emulated in software\n");
    else if (inq_info->shading == XGL_INQ_HARDWARE)
        printf("    Shading accelerated through hardware\n");

    if (inq_info->hlhsr == XGL_INQ_NOT_SUPPORTED)
        printf("    Hidden line removal not supported\n");
    else if (inq_info->hlhsr == XGL_INQ_SOFTWARE)
        printf("    Hidden line removal emulated in software\n");
    else if (inq_info->hlhsr == XGL_INQ_HARDWARE)
        printf(" Hidden line removal accelerated through hardware\n");

    if (inq_info->antialiasing == XGL_INQ_NOT_SUPPORTED)
        printf("    Antialiasing not supported\n");
    else if (inq_info->antialiasing == XGL_INQ_SOFTWARE)
        printf("    Antialiasing emulated in software\n");
    else if (inq_info->antialiasing == XGL_INQ_HARDWARE)
        printf("    Antialiasing accelerated through hardware\n");

    if (inq_info->stereo)
        printf("    Hardware stereo support\n");
    else
        printf("    No stereo support\n");

   if (inq_info->extns & XGL_INQ_MULTI_BUFFERING)
        printf("     Multi Buffering supported\n");
   else
        printf("     No Multi Buffering support\n");

    free (inq_info);
}