Introduction to the System State Object

An XGL application must begin with a call to the operator xgl_open(), which creates the XGL System State object. The XGL System State object maintains critical information that XGL requires for managing an XGL session. It keeps track of all other objects created by the application or by XGL itself. Only one XGL System State object within one XGL session is supported.

There are two System State operators, xgl_open() and xgl_close(), and several related System State attributes. These operators and attributes are explained in the following sections.

System State Operators

The operator xgl_open() creates and initializes a System State object.

Xgl_sys_state xgl_open (<attribute-list>);

If the call is successful, a handle to the System State object is returned to the application. As with many XGL operators, xgl_open() takes a NULL-terminated attribute list as one of its input parameters. It may have as few as

zero attribute-value pairs or as many as the total number of XGL system state attributes, but in all cases it must be terminated with a NULL character, where NULL is defined as in stdio.h. Each attribute-value pair consists of an attribute name followed by its value.

The operator xgl_close() ends an XGL session.

void xgl_close (Xgl_sys_state system_state);

This operator is invoked using the handle to the XGL System State object previously created by the xgl_open() call. This operator destroys the XGL System State object and all its associated resources, and then terminates the XGL session.

System State Attributes

The application programmer can create a System State object and set its attributes simultaneously by specifying argument values in the xgl_open() call's list of attributes. Attributes of the System State object primarily affect error detection and error reporting. System State attributes also provide such information as the location of font data and the release number of the XGL library being used.

The attributes associated with the System State are:

XGL_SYS_ST_ERROR_DETECTION This attribute enables or disables additional error detection and reporting. The attribute can either be TRUE or FALSE. TRUE indicates that extra error checking will be done for errors in the USER, ARITHMETIC, and CONFIGURATION error categories (at the expense of performance). FALSE (the default value) limits error checking and reporting to RESOURCE and SYSTEM errors. For information on the XGL error categories, see Table 4-1 on page 51.

XGL_SYS_ST_ERROR_NOTIFICATION_FUNCTION This attribute enables an application to supply its own error-reporting function in place of the XGL default error function. The default value is a pointer to a function that prints an error message to the standard error output (stderr).

XGL_SYS_ST_ERROR_INFO
  This attribute is used to get information about the current error state. It can
  be used within an application's error notification function to change the
  function's behavior based on specific error characteristics.

XGL_SYS_ST_VERSION
  This read-only attribute queries the release number of the current library. In
  this release of the XGL library, this attribute contains the string "XGL 3.0.2".

XGL_SYS_ST_SFONT_DIRECTORY
  This attribute sets the path used by the XGL library to access stroke font
  data files used in the text primitives. When the XGL library is initialized, the
  System State object sets the stroke font path to
  $XGLHOME/lib/xglfonts/stroke if the XGLHOME environment variable
  is set or to
  /opt/SUNWits/Graphics-sw/xgl-3.0/lib/xglfonts/stroke if
  XGLHOME is not set. It then stores the path name in the attribute
  XGL_SYS_ST_SFONT_DIRECTORY.

The application can store the stroke fonts in a directory other than the directory in which they were installed. The XGL_SYS_ST_SFONT_DIRECTORY attribute enables the application to set the stroke font directory path. If the stroke fonts are stored in a location other than the default location, this attribute must be set every time the application is restarted. If XGL does not find the stroke font data when rendering stroke text, an error is reported, and the stroke rendering operation stops.

Error Detection and Reporting

When an XGL application causes an error, the error notification function determines the application-visible response. Because this function is settable by the application, its response can vary depending on its current definition. The default error notification function sends an error message to stderr. For example, the following message is produced by the default function for a malloc error that occurs within an xgl_polygon() call from a 3D Context:

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

Error Notification Function

The XGL library provides the default error notification function. When an error occurs, this function sends an ASCII string to the standard error output (stderr). The string consists of the error code associated with the error, a message describing the error, the XGL operator being executed when the error was detected, the XGL object being used, and other optional information.

XGL allows the application to supply its own error function for filtering errors and reporting them to the application program. An application error notification function can specify the error categories of interest to the application and ignore other error categories. The following code fragment shows an example of an application error notification function that ignores error messages caused by singular transform errors.

#include <xgl/xgl.h>

/*   error_notify
 *      Error handling code to prevent singular transforms from
 *      issuing error messages. All other XGL errors are displayed
 *      as if this procedure did not exist.
 */

static Xgl_sgn32 error_notify(Xgl_sys_state sys_state)
{
    Xgl_error_info info;       /* Information structure */

    xgl_object_get(sys_state, XGL_SYS_ST_ERROR_INFO, &info);

    if (strcmp("di-128", info.id) == 0) {
        /* Singular transform, we did it on purpose, ignore */
        return(0);
    }

    /* Just print out the standard error messages */
    if (info.msg != NULL)
        printf("msg = %s\n", info.msg);
    if ((info.cur_op != NULL) && (info.cur_obj != NULL))
        printf("cur_op = %s\t%s\n", info.cur_op,info.cur_obj);
    if ((info.operand1 != NULL) && (info.operand2 != NULL))
        printf("cur_obj = %s\t%s\n", info.operand1, info.operand2);

    return(1);
}

This function uses the information in the Xgl_error_info structure returned by XGL_SYS_ST_ERROR_INFO to handle errors. Any of the eight fields in the structure can be used to filter errors. The System State attribute XGL_SYS_ST_ERROR_NOTIFICATION_FUNCTION sets the application-specific error function, as in this example:

/* Prepare to catch error 128, singular transform */
   xgl_object_set(sys_st,
        XGL_SYS_ST_ERROR_NOTIFICATION_FUNCTION, error_notify,
        NULL);

The interface for the error notification function is:

error_notify (Xgl_sys_state sys_state);

Error Types and Categories

XGL errors are grouped into five categories, as listed in Table 4-1. These error categories enable an application programmer creating a new error notification function to detect a particular error group and respond accordingly.

Table 4-1

Category	Description
SYSTEM	Internal errors, unsupported features, and errors that generally cannot be fixed by changing the application.
CONFIGURATION	Errors caused by improper installation or configuration of XGL (such as a .so file not found).
RESOURCE	Unavailable resource errors including both hardware and software resources (such as memory, shared memory, window ID, frame buffer).
ARITHMETIC	Arithmetic exceptions (such as an error resulting from dividing by 0 or taking the square root of -1).
USER	Errors caused by invalid function parameters, nonexistent user files, or situations that may be caused by application program logic errors.

Errors in these categories can be further classified into RECOVERABLE and NONRECOVERABLE error types, as described in Table 4-2. Recoverable errors are reported with error codes of 100 or greater. With recoverable errors, XGL makes an assumption about what the application intended, corrects the error, and continues. If an error is nonrecoverable, XGL stops processing and returns control to the caller. Nonrecoverable errors may cause a core dump with further execution of the application because the application will be left in an invalid state. The application should stop further processing if XGL returns with a nonrecoverable error. Nonrecoverable errors are reported with error codes between 0 and 99.

Table 4-2

Type	Description
NONRECOVERABLE	XGL immediately aborts processing and returns control to the caller. Includes all SYSTEM and CONFIGURATION errors, most RESOURCE errors, and some ARITHMETIC errors.
RECOVERABLE	XGL makes assumptions about what the application intended to do, corrects the error if it can, and continues processing. Includes some RESOURCE errors, most ARITHMETIC errors, all USER errors.

System errors generally cannot be fixed by altering the application program. Other kinds of errors are caused by improper use of the XGL library and can be fixed by modifying the application. The following example error notification function checks the error ID; this function could be extended to stop processing in the case of a nonrecoverable error.

#include <xgl/xgl.h>

static Xgl_sgn32 error_notify2(Xgl_sys_state sys_state)
{
   Xgl_error_info        info;
   int                   n;

   xgl_object_get (sys_state, XGL_SYS_ST_ERROR_INFO, &info);

   printf ("id      = %s\n", info.id);
   printf ("msg     = %s\n", info.msg);
   printf ("cur_op  = %s\n", info.cur_op);

   printf ("cur_obj = %s\n", info.cur_obj);

   n = atoi(info.id);
   if (n < 100) {
        printf ("Non-Recoverable Error!\n");
   } else {
        printf ("Recoverable Error!\n");
   }

   return(1);
}

Note that the XGL default error notification function does not use the error types and categories. These are provided for developers who want to trap specific error types and categories in their own error notification function.

---

Note - When error checking is turned on (XGL_SYS_ST_ERROR_DETECTION is set to TRUE), XGL checks as many errors as possible. This may affect performance. Therefore, you should set XGL_SYS_ST_ERROR_DETECTION to TRUE while you are developing your application and set it to FALSE when you compile your application for distribution.

---

Generic XGL Operators

The XGL library provides four operators that are used to manipulate all XGL objects. These operators provide a consistent method of working with XGL objects. XGL objects no longer needed by an application should be destroyed so the system can reclaim resources (mainly memory) for use by new objects. Destroying unused objects minimizes the amount of internal data structures, thereby improving performance when referencing objects.

---

Note - The create and destroy operators described below cannot be used on the System State object. The xgl_open() and xgl_close() operators create and destroy the System State object.

---

The generic XGL operators are:

• xgl_object_create() This operator creates the XGL object specified by type and initializes it with the settings provided in the attributes list. After creating the object, the application can determine the values of the object's attributes using the xgl_object_get() operator.

Xgl_object xgl_object_create ( Xgl_sys_state sys_state, Xgl_obj_type type, Xgl_desc *desc, <attribute-list> attributes)

The parameter type can take the values listed in Table 4-3.

Table 4-3 xgl_object_create type

Value	Creates:
XGL_2D_CTX	2D Context object
XGL_3D_CTX	3D Context object.
XGL_CGM_DEV	XGL CGM Device object
XGL_CMAP	Color Map object
XGL_DMAP_TEXTURE	Data Map Texture object
XGL_GCACHE	Gcache object
XGL_LIGHT	Light object
XGL_LPAT	Line Pattern object
XGL_MARKER	User-defined Marker object
XGL_MEM_RAS	Memory Raster object
XGL_MIPMAP_TEXTURE	MipMap Texture object
XGL_PCACHE	Pcache object
XGL_SFONT	Stroke Font object
XGL_STREAM	Stream Device object
XGL_SYS_STATE	System State object

Table 4-3 xgl_object_create type(Continued)

Value	Creates:
XGL_TMAP	Texture Map object
XGL_TRANS	Transform object
XGL_WIN_RAS	Window Raster object

The parameter desc is used to define additional information needed for the Stroke Font object, the Window Raster Device object, and the Stream Device object. In the case of the Stroke Font object, the sfont_name field of the desc parameter contains a pointer to the name of the font. For the Window Raster Device object, the desc parameter contains a window type and a window descriptor whose contents depend on the window type. For a Stream Device object, the stream structure of the desc parameter consists of a field pointing to the name of the specific stream pipeline and a field containing a pointer to device-specific information for the particular stream device.

• xgl_object_destroy() This operator destroys the specified XGL object (represented by the handle returned by the corresponding xgl_object_create() call) by freeing all the resources associated with it. The actual destruction of an object may be delayed if the object is referenced by other objects.

void xgl_object_destroy (Xgl_object handle)

• xgl_object_get() This operator is used to determine the value of attributes associated with an object. It returns the value of a specified attribute, attr, of the object, obj. The parameter val points to a memory location into which the operator writes the attribute's value.

void xgl_object_get ( Xgl_object obj, Xgl_attribute attr, void *val)

For example, the following call to xgl_object_get() retrieves the value of the current View Transform and stores it in view_trans:

xgl_object_get(ctx, XGL_CTX_VIEW_TRANS, &view_trans);

---

Note - The application program is responsible for ensuring that the val field in the xgl_object_get() operator points to an area in memory large enough to store the information returned.

---

• xgl_object_set() This operator is used to change the value of attributes associated with an object. It assigns a given value to an attribute in the object obj. One or more attributes can be updated with a single call to xgl_object_set(). The parameter type <attribute-list> is used to specify a NULL-terminated list of attribute-value pairs. For each pair, the attribute name is followed by the value.

void xgl_object_set ( Xgl_object obj, <attribute-list> attributes)

For example, the following call to xgl_object_set() sets four Context edge pattern attributes:

xgl_object_set (ctx, XGL_CTX_EDGE_PATTERN, xgl_lpat_dashed_dotted, XGL_CTX_EDGE_COLOR, &ln_fg_color, XGL_CTX_EDGE_ALT_COLOR, &ln_bg_color, XGL_CTX_SURF_FRONT_COLOR, &pgon_front_color, NULL);