Overview of the XGL Class Structure

The XGL class hierarchy can be thought of as providing three sets of classes:

• Classes for implementing API objects
• Internal classes used for device-independent utilities
• Classes subclassed by device pipeline implementors for device pipelines

The root of the XGL class tree is XglDbgObject. All device-independent, device pipeline, and software pipeline classes derive from this class. This class also assigns each instantiated object an object ID for debugging purposes.

XglDbgObject has a number of immediate subclasses. A top-level view of the XGL class structure is shown in Figure 3-1 on page 42. In this diagram, pipeline classes are shown with dark borders, the base class of the API hierarchy is shown as a filled oval, and the internal utility classes have thin borders.

Figure 3-1

The XGL device-independent classes and the device pipeline and software pipeline classes are described in more detail in the sections that follow and in subsequent chapters. See Chapter 6, "Error Handling" for information on XGL error handling.

Device-Independent Classes

The device-independent classes handle operations that are done in a device-independent manner on behalf of the device pipelines and software pipeline in response to requests from the API. Device-independent classes are defined by the XGL device-independent code. There are two general categories of DI classes: the API classes and the internal utility classes.

Classes That Implement the XGL API

The XGL API presents the C programmer with objects that are abstractions of graphics resources. Internally, XGL implements these objects using a hierarchy of C++ classes. Some classes in this hierarchy become API objects used by the application; other classes are not made into objects but are simply subclassed to provide classes that become API objects. The complete API class hierarchy is shown in Figure 3-2.

Figure 3-2

The creation of the System State object is managed by the XglGlobalState object. All other API objects are instantiated through the System State object. The System State object maintains a list of all API objects created in the XGL system and is responsible for destroying API objects during xgl_close(). See Chapter 4, "Object Interactions" for information on object instantiation through the System State object. For information on the API objects, see the XGL Programmer's Guide or the XGL Reference Manual.

The classes in the API hierarchy that do not become API objects are:

XglApiObject

Contains the object type and pointer to the application data. The setting and getting of application data (API attribute XGL_OBJ_APPLICATION_DATA) is handled in this class.

XglObject

The base class of the API classes with the exception of the System State class. XglObject manages the user list for the API objects. The interface for user list message receiving is defined in this class and is overridden by the API object classes that do processing based on received messages. XglObject also handles object destruction.

XglCtxObject

Defines the Context hierarchy and the Pcache object.

XglDevice

Contains device-independent data and operations that are common to all devices. This object constitutes the device-independent part of a device object and contains a pointer to the device-dependent part of the device object. For information on the components of the Device object, see Chapter 4, "Object Interactions".

XglRaster

Contains the raster-specific definition of a device. XglRaster also contains a pointer to the device-dependent part of the Raster object. This class is the parent class of the XglRasterWin and XglRasterMem classes.

XglContext

Contains the device-independent part of the Context object. XglContext contains device-independent data, some cached data that all device pipelines and the software pipeline share, and functions to set and get

Context attributes. XglContext is the parent class for the XglContext2d and XglContext3d classes. For information on the components of the Context object, see Chapter 4, "Object Interactions".

Classes That Provide Internal Utility Functions

The device-independent utility classes provide a variety of functions. For example, several of these classes work together to provide a mechanism that enables the passing of view model information from the application to the device pipeline. Briefly, the DI utility classes provide the following functions:

XglGlobalState

The XglGlobalState class handles device pipeline and software pipeline loading and maintains the handles to the shared objects. XglGlobalState also handles some of the initial interactions between the device-independent classes and the device-pipeline classes. The XglGlobalState class instantiates the XglGlobalState object during xgl_open() just before the System State object is created.

XglViewCache

The XglViewCache class is the base class of the view model derived data facility. It is the abstract class from which XglViewCache2d and XglViewCache3d are derived. XglViewCache defines the data and functions common to the 2D and 3D classes. XglViewCache2d and XglViewCache3d consist of cached view model derived data and functions for evaluating the data when the pipeline requests it. Figure 3-3 shows the class hierarchy for the view cache class. For more information on the view modal derived data facility, see Chapter 5, "Rendering and Handling State Changes.

Figure 3-3

XglViewGrp{2,3}d

XglViewGrp{2,3}d is the base class that defines pointers to evaluation functions in the cache of view model derived data. It is the abstract class from which XglViewGrp{2,3}dConfig and XglViewGrp{2,3}dItf are derived. Figure 3-4 shows the class hierarchy for the view group class in the 2D case.

Figure 3-4

XglViewGrp{2,3}dItf provides the interface to the view model derived data from device and software pipelines. An object of this class consists of functions that describe when derived data have changed and functions for getting evaluated individual derived data items.

XglViewGrp{2,3}dConfig describes the configuration of the view model derived data for geometry entering LI-1 from a particular coordinate system. An object of this class consists of flags in a table for individual derived data items adjusted for a coordinate system that can be other than model coordinates.

XglViewConcern{2,3}d

XglViewConcern{2,3}d registers the collection of concerns for each coordinate system from which geometry can enter LI-1. Upon entering LI-1, a primitive for a pipeline cares about only a limited selection of derived data items. Objects of this class store this selection for each coordinate system.

XglDrawable

The XglDrawable class provides a public interface for window system interaction. This class maintains information about the window size and clip list, as well as information about the device. XglDrawable subclasses to drawables for Window Raster objects, Memory Raster objects, Xlib/PEXlib connections, and backing store objects.

The base XglDrawable class serves as a repository for shared internal data, such as window dimensions and clip list information, as well as providing default or common operations for the derived classes. It also provides the public interface for the hierarchy. Actual window system interactions are implemented in the derived classes and are transparent to the device pipelines.

Creation of the appropriate Drawable class object is done by the XGL core through the XglDrawable class during XGL device creation, based on the descriptor that is passed in through the API or attributes that are set internally (for backing store mode).

XglCmapDrawable

The XglCmapDrawable class encapsulates color sharing between XGL and the X window server.

XglStrokeGroup

The XglStrokeGroup class maintains the attributes used for multiplexing line drawing to handle different primitives. The Context object maintains one XglStrokeGroup object for lines, markers, text, edges, and hollow polygons. For more information on stroke groups, see Chapter 5, "Rendering and Handling State Changes".

Device Pipeline Classes

The pipeline hierarchies provide predefined interfaces between the device-independent code and the device pipelines. These interfaces allow the XGL device-independent code to interact with the device pipeline code in expected ways. For each specific device pipeline implementation, the device pipeline writer must subclass a device-dependent class from each of the four pipeline class hierarchies. The objects instantiated from the device-specific subclasses will then provide the functionality that the XGL device-independent code expects.

All member functions for device-dependent internal object management are defined in the base classes provided by the XGL device-independent code. When subclassing a device pipeline class, the device pipeline writer can add member data and functions as needed.

The four device-dependent pipeline class hierarchies are listed in Table 3-1.

Table 3-1

Name	Definition	Description
XglPipeLib	Hierarchy for the pipeline library objects	This hierarchy represents the loaded shared library of a device or software pipeline. It handles the creation and destruction of the XglDpMgr subclass of objects.
XglDpMgr	Hierarchy for the device pipeline manager	This hierarchy represents a category of devices, such as frame buffers. In the case of multiple frame buffers, a XglPipeLib object can choose to maintain multiple XglDpMgr objects, each of which maps to a physical frame buffer. This hierarchy handles the creation of the XglDpDev subclass of objects.

Table 3-1

Name	Definition	Description
XglDpDev	Hierarchy for the device-dependent part of the Device object	This hierarchy holds the device-dependent elements of an XglDevice object. It also manages the creation and manipulation of the device pipeline-context objects.This hierarchy is device-specific and is not subclassed by the software pipeline.
XglPipeCtx	Hierarchy for the pipeline-context objects	This hierarchy represents the interfaces for the loadable interface layers of the device pipelines and the software pipeline.

The following sections provide information on the pipeline hierarchies.

Pipeline Library Class Hierarchy

A pipeline library object maps to to a unique .so shared library. Thus, for each shared library (for example, libxglcfb.so) that is loaded into the XGL environment, there is an XglPipeLib subclassed object that represents it.

The base class of the pipeline library hierarchy is XglPipeLib. XglPipeLib subclasses to the device pipeline library (XglDpLib) class and the software pipeline library (XglSwpLib) class. XglPipeLib simply serves as a general category for these two specific shared library classes and has no member functions of its own. Individual pipeline implementations derive to device pipeline-specific objects, such as XglDpLibGx. Figure 3-5 on page 50 shows the pipeline library hierarchy.

Figure 3-5

The primary characteristics of the device pipeline library and software pipeline library base classes are as follows:

XglSwpLib

The XglSwpLib object represents the unique software pipeline shared library and is the base class for the software pipeline class.

When the software pipeline shared library is loaded, the XglSwpLib object is created by a call to xgli_create_PipeLib(). The handle to the XglSwpLib object is maintained by the XglGlobalState object. There is one XglSwpLib object for the software pipeline in the XGL system, and it is assumed that there is only one software pipeline. The software pipeline is the default pipeline and is provided with the XGL product.

The XglSwpLib class is responsible for creating the software pipeline-context objects during Context creation. The XglSwpLib class can be used to store state information that can be shared by all software-context objects.

XglDpLib

The XglDpLib object is the base class for the XglDpLib classes in the device pipelines. This class maps to a loaded device pipeline, and there is one loaded device pipeline per device type. XglDpLib is also responsible for the creation of the device pipeline manager object. In the case of frame buffers, XglDpLib allows more than one XglDpMgr (each of which represents a physical frame buffer) to share hardware or software resources. When the device pipeline shared library is loaded through the XglGlobalState object, an instance of the derived XglDpLib object is created by a call to xgli_create_PipeLib().

Note that since the XGL core does not control the actual number of XglDpMgr objects created, it is the device pipeline's responsibility to destroy any existing XglDpMgr objects during the destruction of the XglDpLib object when this is invoked by the XGL core.

Device Pipeline Manager Class Hierarchy

The XglDpMgr class is responsible for the creation and management of the device-dependent part (XglDpDev) of a Device object. XglDpMgr allows multiple XglDpDev objects to share the physical resources of a device. XglDpMgr is the base class for the XglDpMgr subclasses defined in a pipeline implementation.

In the case of a window raster device, each instance of an XglDpMgr subclass represents a physical device (frame buffer), and there is one XglDpMgr object per physical device. The frame buffers can be the same type (for example, both GX) or different types. If there are multiple devices of the same type on a system, there will usually be multiple instantiations of the same XglDpMgr subclass, all of which map to the same device pipeline. However, since the creation and destruction of all XglDpMgr objects is handled internally by the device-dependent XglDpLib object, a device can choose to have only one XglDpMgr object for more than one frame buffer of its type.

If the devices are of different types, the XglDpMgr object corresponding to each device type will be created by the XglDpLib unique to the shared library. Figure 3-6 on page 52 shows the device pipeline manager class hierarchy.

Figure 3-6

Device-Dependent Device Class Hierarchy

XglDpDev is the base class for the device-dependent part of the Device object. A pointer to the XglDpDev object is stored by the device-independent Device object. XglDpDev has the following functions:

• It creates the device pipeline-context objects.
• It performs device-dependent device operations, such as propagating changes of the device-independent Device object to the device pipeline.

XglDpDev is created as part of the Device object creation process and remains attached to the Device object for the lifetime of the Device instance. XglDpDev was designed to isolate the device-dependent operations from the device-independent operations. Each pipeline implementation must define the actual device-specific operations for the device.

If an application has multiple windows using the same underlying frame buffer, the XglDpMgr object representing that frame buffer will create multiple XglDpDev objects. If an application runs on a system with more than one frame buffer and creates multiple windows on each frame buffer, the XglDpMgr object representing each frame buffer will create the XglDpDev objects for the application windows. For an illustration of the device pipeline objects created for a multi-headed system, see Chapter 2, "Overview of the XGL Architecture".

In Figure 3-7, XglDpDevWinRas and XglDpDevMemRas contain the abstract class interfaces provided by the XGL core. The pipeline implementation derives to XglDpDevCfb, XglDpDevGx, etc., to define the actual device-dependent operations.

Figure 3-7

Pipeline-Context Class Hierarchy

The base class of the pipeline-context hierarchy is XglPipeCtx. The derived classes in this hierarchy, XglPipeCtx2d and XglPipeCtx3d, represent the pipeline interfaces for Context operations. The software and device pipelines subclass from these two classes to implement the actual 2D and 3D primitive operations.

Each Context object links with two XglPipeCtx subclassed objects: one for the software pipeline (for example, XglSwpCtx3d) and one for the device pipeline (for example, XglDpCtx3dCfb). Figure 3-8 on page 54 illustrates the pipeline-context hierarchy.

Figure 3-8

Pipeline-Context Objects

The software pipeline-context object is created by XglSwpLib during XglContext creation time and remains attached to the Context object for the lifetime of the Context object.

The device pipeline-context object is created and maintained by a subclass of XglDpDev during the first association of a Context and a Device. The device pipeline-context object remains associated with the Context object until the Context switches devices. When a Context object is destroyed, the System State object destroys the associated pipeline-context objects for all existing devices.

The interfaces for the XglPipeCtx hierarchy are defined in an array of function pointers to device pipeline or software pipeline renderers. The function pointers represent the primitives for Context operations at the LI-1, LI-2, and LI-3 layers.

Classes for Internal Data Storage

The internal data types are represented by the following C++ classes:

XglPrimData

The XglPrimData class formats API geometric data to the XGL internal point type in the software pipeline. It includes an array of several levels of point list data (contained in the XglLevel subclass) that can be created when data is moved down through the graphics pipeline (in other words, transformed points are stored at a different level than the original points). Briefly, this class includes member functions that:

• Allocate and free memory used for containing geometric data, and copy and convert geometric data into the form appropriate for a particular stage of the geometric pipeline.
• Set and test the per-facet or per-primitive flags for hollow flags, global edge flags, vertex edge flags, pick information, and silhouette edge flags.

XglConicData2d / XglConicData3d

The XglConicData classes format conic data (in circles, arcs, ellipses, or elliptical arcs) to the appropriate internal point type. Like the XglPrimData class, these classes include an array of levels of point list data (contained in the XglConicList2d and XglConicList3d subclasses) that can be created when data is moved down through the graphics pipeline.

XglRectData2d / XglRectData3d

The XglRectData classes format rectangle data to the appropriate internal point type. Like the XglPrimData class, this class includes an array of levels of point list data (contained in the XglRectList2d and XglRectList3d subclasses) that can be created when data is moved down through the graphics pipeline.

XglPixRect

The XglPixRect class manages pixel data. A PixRect is an abstraction of a 2D rectangular array of pixels. The XglPixRect class subclasses to classes that represent memory-based PixRect objects.

For more information on the internal point type classes, see the XGL Device Pipeline Porting Guide.