Before You Begin

Before beginning your device pipeline, check the requirements described below and plan how you will implement support for multiple XGL Context objects. You will also need to determine whether your device will support backing store.

Requirements

When porting a device to XGL and the Sun platform, you must provide support for the operating system kernel and the window system in addition to providing the XGL loadable pipeline for the hardware. Thus, with your device pipeline, you must supply the following:

• A hardware interface from your device to the host platform using the system bus and a boot PROM to identify and initialize the device. For SPARCstation^(TM) and SPARC-compatible systems, the hardware interface is the SBus. For information on writing an SBus interface, see Writing FCode Programs and the OpenBoot Command Reference Manual.
• A kernel device driver for the device. For information on developing a device driver, see Writing Device Drivers.
• A DDX handler for the X11 server for the graphics accelerator. Depending on your hardware, you may also need to port the device-dependent portions of Sun's Direct Graphics Access (DGA) mechanism to your hardware. For information, see the OpenWindows Server Device Developer's Guide.

This documentation and the XGL graphics porting interface is part of the Solaris Driver Developer's Kit (DDK). The Solaris DDK describes the interfaces between the Solaris environment and the hardware platform. The DDK includes information on the Solaris VISUAL environment, Solaris graphics and imaging foundation libraries, the Solaris X11 server, kernel device drivers for graphics and imaging devices, and the physical connections between graphics devices and Solaris platforms. The DDK also includes header files and sample code to help you develop a graphics accelerator and integrate it into the Solaris environment.

OpenWindows and XGL

The OpenWindows^(TM) environment includes Sun's Direct Graphics Access (DGA) technology, which arbitrates access to the display screen between XGL and the window system. DGA defines a protocol between the client application (XGL in this case) and the X11 window server that enables both the application and server to share the underlying graphics hardware. When the application is running on the same machine as the OpenWindows server and the hardware has DGA support, XGL uses DGA to synchronize on-screen drawing with the server. For local rendering, DGA allows XGL to send commands directly to the accelerator or frame buffer, substantially improving performance. When the XGL client program is running remotely, XGL uses Xlib or PEXlib to do all rendering.

As part of your port of the OpenWindows server to your device, you may need to port DGA as well. Your device-specific version of DGA enables XGL to render directly to your device.

Device Support for Multiple XGL Contexts

A hardware device can be used by many different graphics rendering processes at once. At a minimum, the device will be used by the display server and one XGL client, and there may be other libraries or additional XGL clients using the device as well. Each task will maintain a current state or context, such as line color. Since the device is being shared by multiple users, the state must be current for each user before drawing can take place. Thus, your hardware resources must be able to support multiple contexts.

The term context refers to a set of state information that controls an executing entity. The use of this term can become confusing at times because it can refer to any one of the following:

Hardware context	State information that defines rendering characteristics on graphics accelerators, for example line color or raster operation register values.
Process context	State information that controls a UNIX process, such as the program counter, the signal mask, or file descriptors. This state also includes memory mapping information for devices.

XGL Context....State information that defines the rendering of XGL primitives, such as line color or transforms.

Because graphics hardware support for context switching is device dependent, state changes resulting from intraprocess switching of XGL Contexts must be managed within the device pipeline. Thus, early in the device pipeline design phase, you should consider how your device pipeline will support multiple XGL Contexts within a single process.

Also, multiple processes can access your hardware simultaneously. It is important to define how your device will allocate and share its resources among different processes and different windows within a process. Efficient sharing of hardware resources will enable your pipeline to make better use of the XGL architecture.

Device Support for Backing Store

Backing store is a mechanism that saves the obscured portions of a window so that the window can be refreshed quickly when it becomes visible again. A backing store is off-screen memory that reflects the contents of the display buffer. This memory is used by the server to automatically restore previously obscured areas of the display during an expose event. Backing store can be handled by your graphics device or by XGL.

If you can use your graphics device to implement backing store, the device must be able to render into off-screen memory, and in your implementation of the OpenWindows server, you need to enable the backing store feature. A request for backing store support from the server will then allocate backing store memory from your hardware.

If your device does not support backing store, you can request that the server and XGL handle it instead. To use XGL for backing store support, you must implement a small set of device-dependent functions in the pipeline. If your device has a software Z-buffer or accumulation buffer, then the contents of these buffers must be shared with the backing store to keep the buffers and their backing store counterparts synchronized, since the server only repairs damage to the display buffer. See page 65 for more information on using XGL to support backing store, and see the XGL Architecture Guide for information on the architecture of backing store.

XGL Architecture from the Pipeline Point of View

The XGL architecture defines two basic components: the device-independent core and the device-dependent loadable device pipelines. The XGL core functions as the interface between the application program and the device pipelines. The pipelines turn geometric primitives and their state attributes into pixel data that is displayed on a graphics hardware device or written into memory. Figure 2-1 illustrates these basic components:

Figure 2-1

A device pipeline can also be thought of as having two components: a set of objects that constitute the abstract XGL Device, and the loadable interfaces that send the application data to the hardware. The set of device objects link the loadable device pipeline with the XGL core and serve as a framework connecting the device-independent code with the device pipeline rendering code.

More on Device Pipelines

Graphics applications perform operations in particular coordinate systems. These operations include clipping, lighting, projection, depth cueing, and mapping to a viewport. A device pipeline consists of a series of transformations from coordinate system to coordinate system.

The conceptual pipeline, which is independent of the implementation across graphics platforms, is the sequence of transformations and operations for a graphics primitive. The actual implementation within a device pipeline for a particular device may reorder the operations to enhance performance while preserving a representation of the final geometric description. However, the device may only be capable of increasing the performance under certain conditions. For other conditions, the device pipeline calls the XGL software pipeline, which can handle any valid combination of conditions.

A device pipeline can be written at three layers, LI-1, LI-2, and LI-3. Chapter 1, "Introduction to XGL Loadable Interfaces" briefly describes these layers. A graphics device with a high degree of functionality may choose to implement a complete primitive at the LI-1 level, in effect bypassing the lower levels. For example, a device may implement the triangle strip primitive at the LI-1 level by executing all of the operations of the rendering pipeline on the device. When a device is unable to handle some situations, for example, dithering with a color cube, it can fall back to the software pipeline for the function specific to the situation.

If you have a simple frame buffer and want to do a minimal amount of work to write a device handler for the device, you would choose to port to the LI-3 level. The pipeline for a simple frame buffer relies on the software pipeline geometric and rendering functions to feed the pixel-level interface at the LI-3 level of the device pipeline.

Services the XGL Core Provides the Device Pipeline

The XGL device-independent core provides the device pipeline with many services. For example, the XGL core can perform generic error checking, backing store, and deferral mode handling. The core also keeps track of XGL Context state and provides interfaces that allow the device pipeline to get information on attribute settings. In addition, the XGL core provides the device pipeline with:

• A quick test to determine whether any view model or coordinate system attributes have changed.
• Utilities that the device pipeline can use in rendering.

A simple view of the XGL core and a device pipeline that has implemented a complete LI-1 loadable interface for the API primitive xgl_multipolyline() looks like Figure 2-2 on page 13.

Figure 2-2

For more information on the XGL architecture and for illustrations on the architecture of the device pipeline, see the XGL Architecture Guide.

Porting Task

During the initial design phase for a device pipeline, you must choose the primary interface level (either LI-1, LI-2, or LI-3) for the port. This section presents some guidelines for choosing an interface level and, as an example, provides a brief overview of the steps involved in porting at the LI-1 level.

Choosing a Loadable Interface Level

An important decision when you begin your port is to determine which loadable interface level to begin implementing first. Depending on your goals and your hardware, you may want to begin with LI-1 functions, LI-2 functions, or LI-3 functions. You can also focus on either 2D rendering or 3D rendering, as these are different paths. In some cases, the hardware will determine the loadable interface level that you port to, as follows:

• Consider an LI-1 port if your hardware provides a high level of graphics rendering capability, such as transforms, clipping, lighting, or accelerated scan conversion. Points are input to an LI-1 pipeline in model coordinates, and it is the device pipeline's responsibility to perform all rendering operations, including transforming the point data to device coordinates.
• Plan on an LI-2 port if your hardware is capable of rendering device coordinate primitives but is not capable of performing higher level operations such as depth cueing, transformations, lighting, or clipping. The LI-2 layer is provided for devices that can draw primitives if the device coordinates and color of the object are given and no further processing is required.
• Port to LI-3 if your device is a frame buffer that provides pixel-based operations and that does not provide graphics acceleration. The input to LI-3 is pixel data, and the frame buffer renders in device coordinates.

If you are writing a pipeline for a high-level graphics device, you may begin by implementing the basic put-pixel and get-pixel interfaces at the LI-3 level or by implementing one or more accelerated pipelines at the LI-1 level. There is no particular layer that you must begin with, but there are some performance trade-offs that you may want to consider.

Starting With an LI-3 Level Port

A good way to begin, even for an LI-1 port, might be to start work on the LI-3 level using the LI-3 utility object RefDpCtx (Reference Device Pipeline Context). To implement the LI-3 layer with this object, you simply write functions to store the value of a pixel (set-pixel) and to retrieve the value of a pixel (get-pixel). Then, you can call the LI-3 interfaces using the RefDpCtx utility. XGL will only use your LI-3 device pipeline port at the end of a rendering operation. The XGL software pipeline will handle all other operations required for rendering.

Using RefDpCtx to implement LI-3 is the simplest, quickest route for porting XGL to your hardware. With the LI-3 level implemented in this way, you can begin working on window system interactions with DGA and on verifying your port using the Denizen test suite. (See the XGL Test Suite User's Guide for information on the Denizen test suite.)

Porting to the LI-3 level provides breadth of functionality rather than performance. This is the approach to take if your primary goal is to port XGL quickly to see your device running an XGL application. An LI-3 port is advantageous during the early states of implementing a device pipeline because it produces full XGL functionality with a minimal amount of effort by the porting team. Then, to improve performance, you can concentrate on the primitives that you decide are most important and rewrite their implementation at the LI-1 or LI-2 interface level.

Starting with an LI-1 Level Port

An alternate approach is to focus on accelerated rendering and begin with LI-1 primitives. For example, if your hardware is designed to render triangles at high speed, it will be more advantageous to implement triangle renderers and the LI-1 triangle primitives than to implement a pixel interface at LI-3.

Writing a set of LI-1 level interfaces is not a simple task and can require significant time and resources. If you are new to programming in C++, it will take even longer. Optimizing the code for maximum performance will require even more development time. One way to organize work at the LI-1 level is to focus on a single area of acceleration, for example polylines, and implement the LI-1 level primitive for that area. With this approach, you can identify

design problems early. Once the LI-1 primitive is performing well, you can implement more LI-1 primitives using the design that you have developed for the first primitive.

Starting with an LI-2 Level Port

If you are writing loadable interfaces for a device that renders in device coordinates only, you will implement LI-2 and LI-3 level interfaces and will not need to implement interfaces at the LI-1 level. In this case, you can choose whether to begin with the LI-2 layer or the LI-3 layer. As mentioned above, implementing LI-3 through RefDpCtx provides complete functionality in a relatively short time.

A Quick Look at Implementing an LI-1 Primitive

Implementing an LI-1 level device handler is a large project consisting of several general steps. These steps are summarized in this section. While this section may make the task of writing an LI-1 level port seem simpler than it actually is, it is meant to help you divide the porting task into manageable subtasks or concepts. Each step includes references to later chapters that include the information needed to complete the task.

· Decide which XGL primitives and attributes your hardware can accelerate.

To determine which of the primitives and attributes your hardware can accelerate, consider the capabilities of your hardware and examine the scope of XGL functionality in the XGL Reference Manual and in Chapter 9, "Writing Loadable Interfaces", of this book. Most likely you cannot implement all the XGL functionality on your device. Instead, you may want to focus on implementing only those features that your hardware can accelerate.

For those primitive-attribute combinations that your pipeline cannot handle, you can call the software pipeline for processing. To decide which primitives to implement in your pipeline, consider the kind of applications you are targeting with your device and the features that should be accelerated for those applications. Early identification of what to implement in your device pipeline will facilitate the process of porting XGL to your device.

· Write the xgl_create_PipeLib() routine.

Each pipeline must include a routine that creates an instance of the XGL device pipeline library object corresponding to the pipeline. This routine. xgl_create_PipeLib(), is called through dlsym() after the device pipeline is dynamically loaded. See Chapter 3, "Pipeline Framework", for information on this routine and for information on naming your pipeline so that XGL device initialization functions can load the pipeline at runtime.

· Subclass the set of classes that provide the device pipeline framework.

XGL provides a set of classes that, when initialized, provide a framework linking the device pipeline to the XGL core. You need to subclass from these classes for your device. Briefly, the XGL-provided classes are:

• XglDpLib - Maps to the shared library for your device.
• XglDpMgr - Maintains information about the physical device. You may want to put your device initialization routines in this class.
• XglDpDev - Constitutes the device-dependent part of the XGL Device object.
• XglDpCtx2d and XglDpCtx3d - Constitute the device-dependent part of the XGL Context object. Contain the loadable interfaces that the device implements.

These classes have a number of functions that you are required to implement as well as optional functions, such as the LI-1 and LI-2 loadable interfaces. For a summary of the required and optional functions in the device pipeline classes, see page 68. For detailed information on creating the device pipeline classes and objects, see Chapter 3, "Pipeline Framework". For information and useful illustrations on the architecture of the device pipeline, see the XGL Architecture Guide.

You also need to consider your approach to implementing DGA. When you have implemented DGA and the skeleton for the XGL device pipeline classes, you will be able to create an X window and open an XGL Device on it.

· Choose a simple LI-1 primitive and implement geometry processing.

Once a window is available to render to, you can choose a primitive, such as xgl_multipolyline() to implement. The goal for this step is to render a simple piece of geometry, such as a line, on your hardware. To do this, you need to process the geometry data, converting it to a format appropriate for your hardware. You may also need to work out a way to initialize your hardware for each primitive.

Note that some window information, in particular the window clip list, is critical data. This means that it cannot be modified by another process while XGL is using it. Thus, the device pipeline must lock critical window data structures before rendering and unlock them when rendering is complete. This prevents the server from making changes to these data structures while an XGL rendering operation is taking place. See Chapter 8, "Window System Interactions" for more information on XGL's interface to the window system.

Once you have succeeded in rendering geometry on your device, you have completed the important milestone of getting XGL to communicate with your hardware.

· Determine how to handle attribute processing.

Each XGL primitive has a set of attributes that affect it. The set of attributes for each primitive is noted in Chapter 9, "Writing Loadable Interfaces". Your pipeline can get the attribute settings that it needs from the Context object and process the attribute changes using your pipeline objectSet() function.

Refer to Chapter 5, "Handling Changes to Object State" for information on design issues to consider as you implement attribute handling in your pipeline. When handling attribute changes, be aware that techniques that work for a simple primitive, such as multipolyline, may not work for more complex primitives, such as surface primitives.

At this time, you will also want to consider how to handle view model changes and coordinate system changes. XGL provides the view model derived data facility to assist you in implementing view model operations. Using derived data, you can set up objects that track the derived items important to your pipeline. See Chapter 7, "View Model Derived Data" for information on the processing of viewing and coordinate system changes.

Note that you may have to map the XGL attributes to attributes specific to your hardware so that the appropriate rendering occurs. Once you have determined what attributes you need to handle and how to handle them, you should think about how to structure the pipeline for performance. How you do this will depend on how your hardware saves Context state values. If you determine that your device cannot handle the current attribute setting for a primitive, you can fall back to the software pipeline for rendering.

· Implement a design for falling back to the software pipeline.

At each rendering call, the device pipeline must determine whether it can proceed. If it cannot, it can pass control to the software pipeline. See page 20 for information on falling back to the software pipeline.

Your pipeline must also manage state changes that may result when the application changes the Context it is using to render. Chapter 5, "Handling Changes to Object State" provides a brief discussion on context switching and hardware state updating. This chapter also provides information on handling the updating of state when the pipeline switches between interface layers. There are several pitfalls that you may encounter when switching loadable interface layers. Solving these design problems early in the porting process will simplify your overall task.

When you reach this point, you have worked through most of the porting process for a geometry operator. You should be familiar with problems that you need to resolve. At this point, you can look into implementing other types of functions, including functions that XGL does not provide, such as the xgl_context_new_frame() operator.

· Implement xgl_context_new_frame() and a raster operator.

There is a small subset of device-dependent operators that XGL does not implement in the software pipeline. The xgl_context_new_frame() operator is one of these operators. The new frame operator clears the screen and may be required each time rendering occurs. You may want to implement xgl_context_new_frame() early in your development schedule.

The next step might be to implement a pixel or raster operator, such as xgl_context_copy_buffer(), which is another operator that the device pipeline must provide. Implementing a pixel operator after a geometry primitive will help you understand the range of possible functions that you

must handle. When you have implemented a complete geometry primitive and a pixel operator, you have a good idea of the complete task of writing an LI-1 device pipeline.

Testing Your Implementation

To verify that your device pipeline produces images that conform to XGL's reference images, run the Denizen Test Suite, which is supplied with the XGL DDK. The Denizen Test Suite is a group of shell scripts and C programs designed to use the XGL library to render objects and evaluate results. Denizen contains approximately 580 test programs that test every XGL function and the major internal components of the XGL library.

Your device handler should produce Denizen pass rates similar to those measured for Sun's reference frame buffers (8- and 24-bit nonaccelerated frame buffers). The Denizen Test Suite is not intended to be a debugging tool, but it is intended to provide a verification tool so that you can ensure the accuracy of your implementation. For information on using the Denizen Test Suite, see the XGL Test Suite User's Guide.

Calling the Software Pipeline

When the device pipeline is called, if it can render the geometry, in most cases it will take control and render to the hardware at that point. If the device pipeline cannot perform the LI-1 or LI-2 processing, the device pipeline must call the software pipeline to process the primitive.

The software pipeline may also call the device pipeline. For example, if your device pipeline has not implemented a stroke text primitive, it can call the software pipeline LI-1 stroke text function. The software pipeline will tessellate the text into lines and then call the device pipeline multipolyline function to render the lines.

Device Pipeline Options to Rendering Calls

In response to a rendering call, the device pipeline has several options:

• The device pipeline can fully render the primitive.

• The device pipeline can select its loadable interface function with the opsVec[] function array. The opsVec[] array is a dynamic array of loadable interface function pointers. It is the device pipeline's responsibility to set the entries in the opsVec[] array to point to the appropriate functions. For more information about the opsVec[] array, refer to "Defining the Device Pipeline-Context Class" on page 43 and the XGL Architecture Guide.
• The device pipeline can call the software pipeline for components of primitives that the hardware cannot render. For example, the software pipeline can render a subset of the primitive data, as in the case of a polygon that the device pipeline cannot handle in a xgl_multi_simple_polygon() call.
• The device pipeline can fall back on the software pipeline for the entire primitive as in the case of a clipped polygon that the device pipeline cannot handle in a xgl_polygon() call.

What Else You Should Know

Accessing External Files at Runtime

The XGL system may require a number of external files during the execution of an XGL application. For example, the device pipelines are dynamically loaded shared object files that must exist in a directory tree in a location known to XGL so that XGL can load them. The XGL library also requires external files for the software pipeline, error messages, stroke fonts, and configuration information. These external files exist within the directory tree that is created when the XGL files are installed. The top of this directory tree is pointed to by the XGLHOME environment variable. The value of XGLHOME is used internally by XGL when it searches for any of the external files.

To retrieve the value of XGLHOME from the XGL core, use the static function XglGlobalState::getXglHome() as shown below.

const char*          xgl_home;
xgl_home = XglGlobalState::getXglHome();

Directory Structure for the XGL DDK

Figure 2-3 illustrates the current XGL DDK directory structure. The XGL DDK package includes sample source code for the XGL reference loadable device pipelines.

Figure 2-3

Error Reporting for XGL Device Pipelines

XGL provides an error-reporting mechanism that is used when an error is detected during the execution of an XGL application. In order for an error to be reported to the application, you must explicitly add code to handle error conditions. The easiest way to call the error notification function is with the use of error-reporting macros that are described in the following section.

Error Reporting Macros

The recommended method to call the XGL error-handling function from within the pipeline code is to use one of two error-reporting macros that are defined in the file <xgl_dirs>/src/include/xgli/ErrorMacros.h. The macros are XGLI_ERROR and XGLI_DI_ERROR. Their interfaces are defined as follows:

XGLI_ERROR(sys_state, type, category, error_id, object, op1, op2) XglSysState* sys_state Pointer to current system state; can be NULL; if NULL, then internalfunction will first get system state pointer from global state Xgl_error_type type Error type for the particular error Xgl_error_category category Error category for the error char* error_id Identification string for the error Xgl_obj_type object Object type of currently active object char* op1 Optional operand for this error char* op2 Optional operand for this error

XGLI_DI_ERROR(sys_state, error_id, object, op1, op2) XglSysState* sys_state Pointer to current system state; can be NULL; if NULL, then internal function will first get system state pointer from global state char* error_id Identification string for this error Xgl_obj_type object Object type of currently active object char* op1 Optional operand for this error char* op2 Optional operand for this error

The default error notification function prints internationalized error messages that are retrieved from error message files stored in the directory {path}/{LANG}/LC_MESSAGES/filename.mo, where {path} is $XGLHOME/lib/locale if $XGLHOME is set, or /opt/SUNWits/Graphics-sw/xgl/lib/locale if $XGLHOME is not set. More than one error message file may exist in this directory.

The error message files are binary encoded. The file xgl.mo contains error messages for errors that could occur in either the device-independent XGL code (libxgl.so) or the device-dependent XGL code (the pipelines). The other *.mo files, named xgl<company abbrev><pipeline abbrev>.mo, contain error messages for errors that can only occur within a specific pipeline.

The XGLI_ERROR macro can be used to call the error-reporting function for errors that are defined in either xgl.mo or in the pipeline *.mo files. XGLI_DI_ERROR, however, is used only to report errors defined in xgl.mo.

The specific error message used by the error-handling function is identified by the error_id parameter passed to these macros. The error_id is a character string of one of the following forms, where ## is the error number specified in the error message file:

1. di-## - For error messages from the xgl.mo (device-independent) error file

2. <pipeline abbrev>-##- For error messages from pipeline .mo files associated with the originally supported SunSoft/SMCC frame buffers

3. xgl<company abbrev><pipeline abbrev>-##- For error messages from independent hardware vendor (IHV) pipeline .mo files

In order to determine what error messages exist in the error files, English clear-text (ASCII) versions of the files are located in the following directories:

• For xgl.mo - {path}/include/xgl/xgl_errors_di.po
• For pipeline error message files -{path}/src/<pipeline>/include/xgl_errors_<pipeline>.po

The *.po files are of the form:

msgid"Key String" (same as the error_id string)
msgstr"Translatable error message string"

The UNIX utility msgfmt encodes the *.po ASCII files to create the *.mo binary-encoded versions, which must be placed in the locale directory described above.

Other parameters passed to the error macros are self-explanatory. For more information on error types and categories, see "Error Handling" in the XGL Architecture Guide. The operand values may be used to add useful noninternationalized information (such as numbers or XGL attribute names) to the error report.

---

Note - The macros XGLI_ERROR and XGLI_DI_ERROR use the current operator set by the XGL core wrappers during error reporting. A device pipeline should never set the current operator in the pipeline.

---

Example of Error Reporting Using the Error Macros

Suppose you want to check for a malloc error in your pipeline code. The following steps describe how this is done.

1. Search the ASCII clear-text version of the device-independent and pipeline error files for an error message corresponding to the error condition for which you are checking. In this case, the following error message is defined in xgl_errors_di.po:

    msgid   "di-1"
    msgstr  "malloc or new failed: out of memory"

2. Add the following #include to your source code module:

    #include "xgli/SysState.h"

3. Add a call to one of the two error-reporting macros where you detect the error in your code:

   if (!(pts = (Foo *)malloc(bar * sizeof(Foo)))) {
      XGLI_DI_ERROR (system_state, "di-1", XGL_3D_CTX, NULL, NULL);
      return (-1);
   }

If the handle to the System State object is not known, you can call the macro using a NULL value for the System State parameter as shown below:

XGLI_DI_ERROR ((XglSysState *)NULL, "di-1", XGL_3D_CTX,
                 NULL, NULL);

The error-handling function gets the error file, finds the proper error message string corresponding to the error_id passed by the user, assigns values to internal error attributes, and calls an error notification function (either the default or one set by the XGL application). The default error notification function prints an error message to stderr. For example, in the case of the malloc error above, the following message is printed:

Error number di-1: malloc or new failed: out of memory Operator: xgl_polygon Object: XGL_3D_CTX

Creating a Pipeline Error Message File

As described in the previous section, two types of error message files are delivered with XGL. You can create a new error message file for your pipeline and add error messages to it. Error messages in this file must be specific to the pipeline and should not duplicate error messages that are already available in the device-independent error message file.

Follow these steps to create a new error message file:

1. Use the template named xgl_errors_template.po in $XGLHOME/src/sample_dp/include.

2. Change all occurrences of <company abbrev> and <pipeline abbrev> so that they correspond to your company abbreviation and pipeline (device) abbreviation.

3. Add error messages at the end of the file. Two lines are required for each error message: a msgid line and a msgstr line. See the description in the template file or examine the xgl_errors_di.po file for more information.

4. Add the following lines to your Makefile in the directory where the clear-text version (the .po file) of the error message file is located:

xgl<company abbrev><pipeline abbrev>.mo: xgl_errors_<pipeline abbrev>.po
msgfmt xgl_errors_<pipeline abbrev>.po

You may add new error messages to the end of the error file once it has been created. Then, use the XGLI_ERROR macro described above to call the error handler with the error messages you define in your .po file.