Overview

The DGA drawable interface is the basic mechanism for sharing screen access between the window server and one or more X11 client processes. This allows a DGA client to access the frame buffer for improved performance while the window server is still in charge of managing screen real estate for all clients in order to maintain the integrity of the screen. This is accomplished via efficient locking primitives and shared memory information which is accessed via a set of routines and macros. Not only does it apply to windows residing on a screen, but to other types of drawables that can be created on a screen, such as pixmaps and DBE buffers.

The goal of DGA is to provide clients with direct access to the graphics hardware while retaining coherence with the window system. DGA allows the window server to pass device-specific information to Solaris visual foundation

library clients such as OpenGL, XIL, and Direct Xlib. The device-specific information is passed to the foundation library device handler so that the handler knows how to drive the hardware.

The coordination between the server and the client is provided by means of the DGA drawable interface. This interface performs two primary functions; first, it allows the server to pass the target drawable's size and clip shape to the client; and second, it allows the client to lock the drawable, so that it does not change while graphics are being rendered. It also enables the client to detect changes to the drawable, such as the addition of backing store, which the client must maintain. A secondary function of the drawable interface is a mechanism that allows the device-dependent portions of the server to share device-dependent information with the client.

Drawable Types

The OpenWindows server provides clients with several different types of resources on which graphics can be drawn. These resources are called drawables. Drawables are always associated with a particular X screen. There are two basic types of drawables: viewable and nonviewable. The pixel contents of viewable drawables can be directly seen by the user. They reside in special device memory from which a video signal can be output to the display screen. The contents of nonviewable drawables cannot be directly seen by the user. For the user to be able to view the drawable contents, the pixels of a nonviewable drawable must be copied to a viewable drawable.

Windows are always viewable drawables. Pixmaps are always nonviewable.

DGA Drawables

A graphics client that intends to do direct rendering into one or more drawables first makes arrangements with the window system to grab the drawable. This enables direct access to the drawable.

Once a drawable is grabbed, the client must lock the drawable prior to rendering to it. The client must provide arguments to the lock routines specifying the drawable it is going to render to. For each drawable locked, the lock routines take a Dga_drawable and a buffer index. The buffer index for windows and pixmaps is always -1. A Dga_drawable is a opaque handle

returned by grabbing a drawable. It is some times also called a DGA client structure for the drawable. For details see "Drawable Locking and Change Detection" on page 147.

The drawable's client structure contains a pointer to the shared memory information about the drawable. This information is shared with the window server. It acts as a communication pathway between the window server and the client. DGA clients cannot access the contents of the Dga_drawable structure or the shared memory information directly; access it through this DGA interface. When this initialization transaction is complete, the client can begin rendering into the drawable.

The window server updates its information in response to changes in the drawable's attributes. These changes are usually initiated by the user, by popping up a menu or resizing a window, for example. Some of these changes can be initiated by a client program through a programmatic interface, such as the double-buffering extension (DBE). The client uses the routines provided in the drawable interface to maintain consistency with these changes.

Back Buffers

Clients should use the ancillary buffer management interface to grab a back buffer. Grabbing a back buffer in some other way will result in DBE being unable to allocate the buffer. For information about ancillary buffers, see "Ancillary Buffer Management Interface" on page 151.

Mutual Exclusion

At a given time, only a single process may access the shared drawable information. Mutual exclusion is enforced by lock and release primitives in the client and window server code streams. Denial of access permission is transparent to the requesting process; it will be blocked when it tries to lock down the shared data structure and will not continue until it has acquired the right to own the shared data structure. Once a process acquires the shared data structure, it retains uninterrupted use of it. When a process decides to give up ownership, another process may acquire ownership. For this reason, the DGA locking primitives should not be held outside of rendering code or for extended periods of time. At present, DGA does not support multi-threaded graphics access to a single drawable from within a single client process.

The drawable interface enforces fairness in that, a process which is denied access is given ownership rights as soon as they become available. Release of ownership is voluntary and the owning process can retain ownership for an indefinite period of time. This exposes a potentially vulnerable area in the mutual exclusion technique, since the owning process may loop, sleep, terminate or perform time-consuming operation while in possession of access rights. This situation is ameliorated by a time-out mechanism that limits a client process's ownership time to a maximum value (currently three seconds). The window server process is not so limited and may retain possession of the lock indefinitely.

Sites

A drawable can reside in different types of memory called drawable site types. System memory and device off-screen memory are examples of drawable site types. Within a site type, a drawable has an address. Together, the site type and address define the drawable's site.

Because a drawable may change site between locks, the client should either:

• Always check for a site change when the drawable is locked and DGA_DRAW_MODIF returns nonzero, or
• Register a site change notification function

There are two ways of detecting site changes:

1. MODIF Testing

   A site change causes DGA_DRAW_MODIF to return nonzero. As part of the state interrogation that follows this, the client can call dga_draw_sitechg to see if the site has changed since the last lock.

2. Notification

   Another way to detect site changes is to register a site change notification function. This function is automatically called by the drawable locking routines when a site change is detected.

The client may use either of these two approaches.

When a drawable is first grabbed, its site is considered changed so the client can synchronize with the initial site.

Backing Store

When a window has backing store, DGA clients must update the backing store as illustrated in Figure 9-1.

Figure 9-1

The backing store always contains the contents of the nonvisible portion of the window. Not only is the DGA client supposed to render to the visible portion of the window, but it is also expected to keep the valid pixel area of the backing store up-to-date. The valid portion of the backing store always has the same shape as the nonvisible portion of the window. This shape is equal to the window's boundary shape minus the visible shape.

The backing store of a window is not a drawable itself. It can be rendered to and can be cached like a pixmap, but it cannot be separately grabbed. It has no XID of its own and no presence in the system independent of its owning window. Backing store can only be accessed by grabbing the window that owns it.

During each lock critical section, the amount of rendering the client must perform depends on the degree to which the window is obscured. dga_draw_visibility can be called to determine which of the following cases holds:

1. If the drawable is entirely unobscured (DGA_VIS_UNOBSCURED), the client can restrict rendering to just the visible shape of the drawable. This shape is returned by dga_draw_clipinfo.

2. If the window is partially obscured (DGA_VIS_PARTIALLY_OBSCURED), the client should render to both the visible and the retained portions.

3. If the drawable is completely obscured (DGA_VIS_FULLY_OBSCURED) then the client should render entirely to the backing store area.

The client must complete rendering updates to both the drawable and backing store within a single lock critical section.

If the client needs to read pixels from the drawable, it should use the clip state of the drawable to determine whether it should read the pixels from the visible portion of the drawable, the backing store, or both. This is done in a similar fashion to rendering (described above).

By default, the shared information file for backing store is placed by the server in /tmp, but because these files can be rather large, the server also supports placing the files in a path as defined by the -sharedretainedpath server command-line argument.

Zombie Drawables

There is nothing to prevent an X11 drawable resource from being destroyed at any time by an X11 client. Even if the underlying drawable resource is destroyed, a DGA client may still hold a handle to the drawable in the form of a Dga_drawable client structure. A Dga_drawable window or pixmap whose underlying X11 resource has been destroyed is called a zombie.

The first time a client locks a zombie drawable after its underlying X11 resource has been destroyed, a site change is reported. The site will be reported as DGA_SITE_NULL. In addition, dga_draw_clipinfo always returns NULL for a zombie drawable.

Compiling and Linking

To use this interface, the /usr/openwin/include/dga/dga.h file should be included in a library device handler's source file (it contains the definitions of many of the defined symbols and data structures referred to in this document).

The library device handler should be linked with the /usr/openwin/lib/libdga.so library.

---

Note - Routines with all uppercase names, such as DGA_DRAW_LOCK, are C macros--you cannot manipulate them as true C routines.

---

DGA Drawable Functions

Most DGA drawable routines can only be called when the drawable is locked. Otherwise, conflicts could occur with either the server or another client accessing the drawable. An inquiry routine called while the drawable is not locked may return invalid information. An action routine called while the drawable is not locked may not have the desired effect.

In the following routine specifications, if a routine must be called within a lock critical section, it is marked with the tag "(Lock Only)". The results of calling such a routine outside a lock critical section are undefined.

All other routines may be called either inside or outside of a lock critical section.

Initialization and Cleanup

The following routines initialize DGA, initiate and terminate direct access to a drawable, and cleanup DGA.

DGA_INIT

void DGA_INIT()

Purpose....This macro performs the initialization required to use any of the DGA interfaces: this drawable interface, the window compatibility interface, the colormap grabber, and the miscellaneous grabbers.

Called byXDgaGrabDrawable	All client programs before making any other DGA function calls. This macro can be called multiple times by a client program so that, multiple libraries using DGA can be used by the application program without difficulty.
Dga_drawable
Purpose	Initiates direct access to a window or pixmap drawable. drawid is the XID of the window or pixmap. If the grab succeeds, a handle to the DGA client structure for the drawable is returned. If the grab fails or is refused by the server, 0 is returned.

---

Note - If the grabbed drawable is to have ancillary buffers, you must also use the ancillary buffer functions. For details, see "Ancillary Buffer Management Interface" on page 151.

---

Returns	The returned Dga_drawable is used to form the handle to be passed to subsequent DGA inquiry routines on that drawable.
Results	This routine allocates several resources in the calling process's address space for the drawable, including a mapping of the shared memory information. This function opens a file descriptor for the correct graphics device file, using information found in the shared memory area. Only one file descriptor per graphics device will be opened.

---

Note - One file descriptor is consumed when the client grabs a window by calling XDgaGrabDrawable. If dga_draw_rtngrab is also called, an additional file descriptor is consumed. In addition, a single additional file

descriptor is used whenever there are one or more pixmaps grabbed. Finally, for each file descriptor used by the client, a file descriptor is consumed in the server.

---

XDgaUnGrabDrawable

int XDgaUnGrabDrawable (dgadraw) Dga_drawable dgadraw;

Purpose

This function terminates direct access to a drawable. If this was the last direct use of the drawable by the client, DGA resources for the drawable in the client's address space are freed. These were the resources allocated by a previous call to XDgaGrabDrawable. All resources and memory mappings that were created are freed or made inaccessible as a result of this operation. If this was the last direct use of the drawable on the screen, the window server DGA resources for this drawable are also freed.

Results

If the drawable is locked at the time of this call, it is first unlocked.

If resources for backing store have been allocated for the drawable, these resources are freed. The shared memory mappings for the backing store in the calling process's address space are unmapped, the backing store shared info file is closed, and the server is notified to free all its resources associated with the direct access to backing store.

Returns....Nonzero on success 0 on failure

Drawable Locking and Change Detection

The following functions provide the ability to gain exclusive access to a drawable while client operations are being performed. Routines are also provided to detect changes that have occurred to the drawable since the client last locked it.

DGA_DRAW_LOCK

void DGA_DRAW_LOCK(dgadraw, bufIndex) Dga_drawable dgadraw; short bufIndex;

Purpose

This macro locks the drawable info shared memory data structure. The client must lock the drawable info shared memory area before it uses any information in it. This restrains the window server from applying any modifications to the attributes of the drawable a client is rendering into it. It also prevents collisions with other clients. The lock should be held while any rendering is performed or information from the shared memory is being accessed. The lock is lightweight enough to be placed around a small number of primitives without sacrificing performance. Thus calls to the locking primitives should be kept in the graphics library and not exposed in the library API.

Results

The current lock subject is the drawable to which subsequent DGA inquiry routines executed within the lock apply.

Locks nest correctly. If DGA_DRAW_LOCK has been called multiple times without an intervening unlock, DGA_DRAW_UNLOCK must be called the same number of times before the drawable is unlocked.

ArgumentsDGA_DRAW_UNLOCK (Lock Only)	bufIndex should be -1.
void
Purpose	This macro permits external modification of the information in the shared memory data structure. This routine should be used only when a drawable has been first locked with

DGA_DRAW_LOCK. Locks nest correctly. If DGA_DRAW_LOCK has been called multiple times without an intervening unlock, DGA_DRAW_UNLOCK must be called the same number of times before the drawable is unlocked.

DGA_DRAW_LOCK_SRC_AND_DST

void DGA_DRAW_LOCK_SRC_AND_DST(dgasrc, bufIndexSrc, dgadst, bufIndexDst) Dga_drawable dgasrc; short bufIndexSrc; Dga_drawable dgadst; short bufIndexDst;

PurposeDga_drawable.

This macro atomically locks two drawables at the same time. It should be used when the client will be accessing two drawables in a rendering operation. An example of such an operation is a copy from the source drawable to the destination drawable. dgasrc must not be the same as dgadst. Furthermore, it is required that at least one of dgasrc or dgadst be a pixmap drawable. No failure status is returned if either of these conditions fails. For this macro, there are two current lock subjects, one for each

Results

The current lock subject is the drawable to which subsequent DGA inquiry routines executed within the lock apply.

Locks nest correctly. If DGA_DRAW_LOCK_SRC_AND_DST has been called multiple times without an intervening unlock, DGA_DRAW_UNLOCK_SRC_AND_DST must be called the same number of times before the drawables are unlocked.

Arguments..bufIndex should be -1.

When using this macro, make sure you call DGA_DRAW_MODIF for both dgasrc and dgadst, to synchronize with any changes that have occurred to either drawable.

DGA_DRAW_UNLOCK_SRC_AND_DST (Lock Only)

void DGA_DRAW_UNLOCK_SRC_AND_DST(dgasrc, dgadst) Dga_drawable dgasrc; Dga_drawable dgadst;

Purpose	This macro permits external modification of the drawable. This routine should be used only when the drawable was locked with DGA_DRAW_LOCK_SRC_AND_DST. Locks nest correctly. If DGA_DRAW_LOCK_SRC_AND_DST has been called multiple times without an intervening unlock, DGA_DRAW_UNLOCK_SRC_AND_DST must be called the same number of times to unlock the drawable.
ResultsDGA_DRAW_MODIF (Lock Only)	The lock count is decremented, and if zero, the drawable is unlocked.
int
Purpose	This macro checks to see if the current lock subject has been altered since the calling client locked it.
Called by	The client must call this macro after locking, prior to rendering.
Returns	Nonzero is returned if some state information has changed with which the client needs to synchronized.

If no change has occurred, or the client has been notified of all changes through notification call back routines, this routine returns zero.

If this macro returns nonzero and the client has not registered with DGA to receive change notifications, the client should call the following routines to detect changes to the drawable:

dga_draw_curshandle, dga_draw_sitechg, dga_draw_rtnchg and dga_draw_clipchg. These routines should always be called in this order. (If the client has registered with DGA to receive a particular type of change notification by specifying a notification callback, do not call these routines.)

Ancillary Buffer Management Interface

This interface, like the rest of the DGA client interface, is not an application developer interface. To use it, a developer must know the specifics of the hardware interface for each device supported.

The purpose of this interface is to support the full implementation of OpenGL in Solaris. In particular, OpenGL defines several new graphics buffer types which the system needs to support both hardware and system memory implementations.

This interface:

• Allows clients to gain access to (grab) new ancillary buffer types
• Allows clients to gain access to ancillary buffers created by the server and maintained in system shared memory
• Supports new double buffering semantics required by DBE and GLX

Currently, grabbing buffers is only supported for window drawables.

Ancillary Buffer Manager

Since OpenGL mandates the existence of several ancillary buffers which are not supported on many devices, and because the GLX specification requires that multiple GL clients rendering to the same drawable share the ancillary buffers, buffer creation must be managed by the X server. The module in the X server that does this is the ancillary buffer manager.

Since ancillary buffers are really an extension of the X drawable, and DGA is the mechanism for managing shared access to drawables, it is logical to extend the existing DGA interface to include the new ancillary buffer types. DGA clients do not have a direct interface with the ancillary buffer manager.

Ancillary Buffer Types

Ancillary buffers are represented by an object of type Dga_buffer. Several buffer types of Dga_buffer are defined. Several functions are provided to access the buffers associated with a given drawable. These functions may only be called while a DGA lock of the drawable is in progress.

Several buffer types are defined. The list is based on the ancillary buffer types supported by OpenGL.

typedef enum { DGA_DEPTH_BUFFER = 0, DGA_STENCIL_BUFFER, DGA_ACCUM_BUFFER, DGA_ALPHA_BUFFER, DGA_BACK_BUFFER, DGA_AUX_BUFFER0, DGA_AUX_BUFFER1, DGA_AUX_BUFFER2, DGA_AUX_BUFFER3, } Dga_buffer_type;

Buffers of a particular type may not be available for a given drawable, depending on the capabilities of the drawable's X visual. Buffers may be implemented in either system memory or on the device, depending on the capabilities of the hardware, and the choice of the client. The maximum capability for a drawable is determined by the capabilities of the drawable's visual.

Buffer Realization

Buffers are not realized when a drawable is first created, but are realized (and allocated) in response to subsequent client requests. When the drawable is ungrabbed, the previously grabbed buffers are preserved and restored for the next dga_draw_grab_buffer call, with the exception that if the ungrabbed buffer is resized, it is unrealized (freed) and will once again be realized upon later client requests.

dga_draw_grab_buffer

Dga_buffer dga_draw_grab_buffer(dgadraw, type, buffer_site) Dga_drawable dgadraw; Dga_buffer_type type; int buffer_site;

Purpose	This function requests the window system to provide ancillary buffer service for the grabbed drawable named in the dgadraw argument. The call requests the specified type of buffer to be grabbed. If buffer_site is DGA_SITE_SYSTEM, the server allocates the buffer in shared memory. If it is DGA_SITE_DEVICE, the server tries to grab hardware buffers. If the device does not support the given buffer type in hardware, the request fails. This drawable must have been grabbed previously via XDgaGrabDrawable. The call to XDgaGrabDrawable returns a handle dgadraw, which is used in this call. The window server initializes the portion of shared memory that relates to ancillary buffers software support. Currently, grabbing buffers is only supported for window drawables.
Returnsdga_draw_ungrab_buffer	This function returns zero if the window system refuses the registration request. Upon success, this function returns the buffer pointer.
int
Purpose	This function ungrabs the buffer for the specified drawable which has been grabbed previously. Note that ungrabbing a buffer does not necessarily cause it to be freed.

Returnsdga_draw_bufferchg (Lock Only)	If any of these steps fail, zero is returned. True is returned upon success.
int
Returnsdga_draw_get_buffers (Lock Only)	This function returns True if any of the buffers associated with the drawable have undergone a state change since the last lock. When this function returns True, the client should call dga_buffer_sitechg for each of the drawable's buffers.
int
Returnsdga_buffer_type (Lock Only)	This function returns the number of ancillary buffers associated with the specified drawable and an array of buffer pointers. Note that only buffers which have been grabbed by the client are returned. Buffers which are grabbed by other clients or by the server are not returned.
int
Purpose	This function returns the type of the buffer specified.

dga_buffer_site (Lock Only)

int dga_buffer_site(bufferp) Dga_buffer bufferp;

Returns....This function returns the site of the buffer specified.

Possible return values are: DGA_SITE_SYSTEM, DGA_SITE_DEVICE, or DGA_SITE_NULL.

DGA_SITE_SYSTEM indicates the current lock subject resides in system memory (i.e. memory that is mapped into the client address space). In this case, the routines dga_buffer_address, dga_buffer_linebytes dga_buffer_bitsperpixel return, respectively, the address of the origin pixel of the drawable, the inter-scanline stride (i.e. the number of bytes per scanline), and the number of bits per pixel.

DGA_SITE_DEVICE indicates the drawable resides in device memory. In this case, the return values of the routines dga_buffer_address, dga_buffer_linebytes, and dga_buffer_bitsperpixel are invalid. Information about the exact location of the drawable within the site can be queried with dga_draw_devinfo. The data returned by this routine is device dependent and is not interpreted by DGA.

DGA_SITE_NULL means that the underlying X11 resource for the drawable has been destroyed since the last time the drawable was locked.

The site of a viewable drawable is DGA_SITE_SYSTEM, unless it has been destroyed, in which case the site is DGA_SITE_NULL. The site of a nonviewable depends on whether or not it is cached.

dga_buffer_sitechg (Lock Only)

int dga_buffer_sitechg(bufferp, reason) Dga_buffer bufferp; int *reason;

Purpose	This function checks whether a site change has occurred for the buffer.
Returnsdga_buffer_address (Lock Only)	This function returns True if the buffer has the sitechg flag set. Note that this function always returns False for device buffers. Only memory buffers can have a site change. dga_buffer_sitechg also returns the reason for site change. Currently, the only possible values for reason are DGA_SITECHG_INITIAL, which is reported the first time a drawable is locked after a buffer has been created; and DGA_SITECHG_CACHE, which indicates that the buffer has been resized since the drawable was last locked.
void *
Returns	This function returns that data pointer from the shared buffer page of the buffer specified. An address is returned only for buffers which are located in system memory. If dga_buffer_address is called on a buffer located with DGA_SITE_DEVICE, NULL will be returned. The value returned remains valid across locks until a site change is reported as described above in the description of dga_buffer_sitechg.

dga_buffer_linebytes (Lock Only)

int dga_buffer_linebytes(bufferp) Dga_buffer bufferp;

Returnsdga_buffer_bitsperpixel (Lock Only)	This function returns the number of bytes per scanline of the buffer specified. Only buffers that are located in system memory are addressable. If dga_buffer_linebytes is called for a buffer located on the device, 0 is returned.
int
Returnsdga_draw_buffer_swap	This function returns the bits per pixel of the buffer specified if the buffer is located in system memory. If the buffer is located on the device, zero is returned. Note that the value might be different than the number of significant bits. For example, an unpacked 4-bit stencil buffer would return 8 bits per pixel, and a 24-bit Z buffer would return 32 bits per pixel.
void
Purpose	This function swaps front and back buffers if they have been grabbed. A swap causes DGA_DRAW_MODIF to return nonzero. The shared page is modified. visfunc is a device-dependent function that performs the buffer swap.

dga_draw_swap_check

int dga_draw_swap_check(dgadraw) Dga_drawable dgadraw;

Purpose....This function checks to see whether a buffer swap has occurred.

General Utility Functions

These routines allow the client to query various drawable attributes.

dga_draw_display

Display * dga_draw_display(dgadraw) Dga_drawable dgadraw;

Returnsdga_draw_id	The display of a drawable that has been grabbed with XDgaGrabDrawable.
Drawable
Returns	The XID of a drawable that has been grabbed with XDgaGrabDrawable.

dga_draw_type

int dga_draw_type(dgadraw) Dga_drawable dgadraw;

Returnsdga_draw_devname	The type of the drawable client structure. The returned value is one of: DGA_DRAW_WINDOW, DGA_DRAW_PIXMAP, or DGA_DRAW_OVERLAY.
char *
Returnsdga_draw_devfd	A pointer to a null-terminated string representing the device name of the screen with which the grabbed drawable is associated.
int
Returns	The client's file descriptor for the screen with which the grabbed drawable is associated.

dga_draw_depth

int dga_draw_depth(dgadraw) Dga_drawable dgadraw;

Returnsdga_draw_set_client_infop	This routine returns the depth of the grabbed drawable.
void
Purposedga_draw_get_client_infop	This routine allows the client to set a pointer to client-specific data associated with dgadraw. This pointer could point to information that is local to the client alone.
void *
Returns	The client-specific data pointer associated with dgadraw. If this pointer was not set by the client, then this routine returns NULL.

dga_draw_devinfo (Lock Only)

void * dga_draw_devinfo(dgadraw) Dga_drawable dgadraw;

Returns....This function returns a pointer to the device-specific information area for the current lock subject. The structure should be accessed by the client to query device-dependent information to be shared between server and client. DGA routines do not interpret the device-dependent data, but the client graphics library device-dependent code may need to do so. The size of this area is 132 bytes. The returned pointer is 4-byte aligned.

If the lock subject is cached, the device-dependent information can specify its location in the cache.

The format of this data area is completely device-dependent. The return pointer is NULL if the lock subject is not cached. An example of this structure could be:

struct { short basex, basey; /* drawable's position in dev. memory */ u_char mode; /* a device specific mode */ u_char pad[2]; } Cache_Dev_Info;

---

Note - This routine returns a pointer to the device_info data member of the dga_draw_dbinfo structure. A pointer to this structure is returned by the buffer interface routine dga_win_dbinfop. This routine is still supported for compatibility with existing clients.

---

Drawable Sites

The routines in this section allow a client to detect site changes. Write the client to detect site changes for all types of drawables--all types of drawables may undergo site changes.

dga_draw_sitechg (Lock Only)

int dga_draw_sitechg(dgadraw, reason) Dga_drawable dgadraw; int *reason;

Returns....Nonzero if the current lock subject has undergone a change in site since the last time it was locked by this client. dga_draw_site can be called to inquire the site in which the drawable currently resides. The site can change for two reasons: either the site itself changed or the location within the site changed.

This routine should be called if DGA_DRAW_MODIF returns nonzero and the client has not registered a site change notification function.

Zero is returned if the last site and location within the site noted by the client still applies.

This routine returns valid results only the first time it is called after locking the drawable.

If nonzero is returned, reason indicates why the site change occurred. These are the possible values for this return argument:

DGA_SITECHG_INITIAL -- A site change is always reported the first time a drawable is locked.

DGA_SITECHG_ZOMBIE -- The site change occurred because the current lock subject is a zombie drawable (i.e. it's underlying X11 resource has been destroyed).

DGA_SITECHG_ALIAS -- The site change is due to a change in the display buffer of the current lock subject from the previous lock subject. (This is only applicable to drawables that are members of an active multibuffer set).

DGA_SITECHG_CACHE -- The site change is due to a change to the cache state of the current lock subject from the previous lock subject.

DGA_SITECHG_MB -- The site change happened because the multibuffer set was changed (activated, deactivated, or replaced).

dga_draw_sitesetnotify

int dga_draw_sitesetnotify(dgadraw, site_notify_func, client_data) Dga_drawable dgadraw; DgaSiteNotifyFunc site_notify_func; void *client_data;

Purpose	Registers a function to be called by one of the drawable locking routines whenever a site change has occurred since the last lock of the drawable.
Arguments	client_data is a client-specific data pointer that is given to the notification function as an argument.

DgaSiteNotifyFunc is defined as:

typedef void (*DgaSiteNotifyFunc) (Dga_drawable, short, void *, int);

Description..The calling sequence for a typical notification function is:

void site_notify_func(dgadraw, bufIndex, client_data, reason) Dga_drawable dgadraw; short bufIndex; void *client_data; int reason;

The notification function should call dga_draw_site to determine the current site of the drawable.

site_notify_func will be called whenever a site change occurs to the window. bufIndex is a historical parameter that is no longer used and should always have a value of -1.

When a site notification function is registered for a drawable, the client will receive notification of drawable site changes only through this function. dga_draw_sitechg will never return nonzero.

The site notification function is always called within the lock critical section. Therefore, care should be taken to avoid performing lengthy and time-consuming operations within it, such as system calls. Otherwise, the DGA lock time-out might expire, causing the lock to be prematurely broken.

dga_draw_sitegetnotify

void dga_draw_sitegetnotify(dgadraw, site_notify_func, client_data) Dga_drawable dgadraw; DgaSiteNotifyFunc *site_notify_func; void **client_data;

Returnsdga_draw_site (Lock Only)	The site notification function and client data for the drawable which was given to dga_draw_sitesetnotify. NULL is returned for both if this routine has not been called.
int
Returns	The site in which the current lock subject resides. Possible return values are: DGA_SITE_SYSTEM, DGA_SITE_DEVICE, or DGA_SITE_NULL.

DGA_SITE_SYSTEM indicates the current lock subject resides in system memory (i.e. memory that is mapped into the client address space). In this case, the routines dga_draw_address, dga_draw_linebytes dga_draw_bitsperpixel return, respectively, the address of the origin pixel of the drawable, the inter-scanline stride (i.e. the number of bytes per scanline), and the number of bits per pixel.

DGA_SITE_DEVICE indicates the drawable resides in device memory. In this case, the return values of the routines dga_draw_address, dga_draw_linebytes, and dga_draw_bitsperpixel are invalid. Information about the exact location of the drawable within the site can be queried with dga_draw_devinfo. The data returned by this routine is device dependent and is not interpreted by DGA.

DGA_SITE_NULL means that the underlying X11 resource for the drawable has been destroyed since the last time the drawable was locked.

The site of a viewable drawable is DGA_SITE_SYSTEM, unless it has been destroyed, in which case the site is DGA_SITE_NULL. The site of a nonviewable depends on whether or not it is cached.

dga_draw_address (Lock Only)

void * dga_draw_address (dgadraw) Dga_drawable dgadraw;

Returns....A pointer to the origin pixel of the current lock subject (x = 0, y = 0). A valid result is only returned when the site of the drawable is DGA_SITE_SYSTEM.

dga_draw_linebytes (Lock Only)

int dga_draw_linebytes(dgadraw) Dga_drawable dgadraw;

Returnsdga_draw_bitsperpixel (Lock Only)	The value of the inter-scanline stride of the current lock subject. A valid result is only returned when the site of the drawable is DGA_SITE_SYSTEM.
int
Returns	The bits per pixel of the current lock subject. A valid result is only returned when the site of the drawable is DGA_SITE_SYSTEM.

Clipping State

The following functions enable clients to detect whether the clipping information of a drawable has changed and to synchronize with the new information.

dga_draw_clipchg (Lock Only)

int dga_draw_clipchg(dgadraw) Dga_drawable dgadraw;

Purpose....If DGA_DRAW_MODIF returns nonzero, this routine should be called to determine if the clipping state for the current lock subject changed. Zero is returned if there were no such changes, otherwise nonzero is returned.

If a clipping change has occurred, the dga_draw_bbox, dga_draw_visibility, dga_draw_empty and dga_draw_clipinfo routines can be called to inquire the new clipping information.

Returnsdga_draw_bbox (Lock Only)	Valid information only the first time it is called after the drawable is locked.
void
Returns	The screen coordinates of the upper left origin of the current lock subject and the width and height in the locations pointed to by the xp, yp, widthp, and heightp arguments. These values represent the shape of the bounding box of the drawable. If dga_draw_visibility returns

DGA_VIS_UNOBSCURED and dga_draw_singlerect
returns nonzero, the bounding box can be used to clip
rendering rather than using the clip shape returned by
dga_draw_clipinfo.

If the current lock subject is a window, the returned rectangle shape does not include any clipping of the window by other overlapping windows. For viewable drawables, the bounding box corresponds to the minimum and maximum x and y coordinates of the drawable. If the drawable is nonviewable, the x and y coordinates of the origin are (0, 0).

dga_draw_visibility (Lock Only)

int dga_draw_visibility(dgadraw) Dga_drawable dgadraw;

Returns....Whether the drawable is fully obscured, partially obscured, or fully unobscured. Possible return values are:)

DGA_VIS_UNOBSCURED DGA_VIS_PARTIALLY_OBSCURED DGA_VIS_FULLY_OBSCURED

DGA_VIS_UNOBSCURED means the drawable is not obscured by any other drawable (i.e. children, siblings, or ancestors). DGA_VIS_PARTIALLY_OBSCURED means a proper subset of the drawable pixels are obscured by some other drawable. DGA_VIS_FULLY_OBSCURED means the entire drawable is obscured.

This routine is useful for deciding how much of the backing store of a window should be rendered. See section "Backing Store" on page 143 for more details.

dga_draw_empty (Lock Only)

int dga_draw_empty(dgadraw) Dga_drawable dgadraw;

Returns....Nonzero if the current clipping shape of the current lock subject is empty, zero otherwise.

dga_draw_clipinfo (Lock Only)

short * dga_draw_clipinfo(dgadraw) Dga_drawable dgadraw;

Purpose....This routine is used to get the address of the clipping shape of the current lock subject. The clip shape is represented by a sequence of signed shorts which describes a sequence of rectangles. The data consists of a sequence of one or more (ymin, ymax) pairs, each of which is followed by a sequence of one or more (xmin, xmax) pairs. (xmin, xmax) sequences are terminated by a single value of DGA_X_EOL. (ymin, ymax) sequences are terminated by a single value of DGA_Y_EOL. DGA_X_EOL and DGA_Y_EOL are defined constants. This is best described with the following sample code:

short int x0, y0, x1, y1, *ptr; ptr = dga_draw_clipinfo(dgadraw); while((y0=*ptr++)!= DGA_Y_EOL) { y1 = *ptr++; while((x0=*ptr++)!= DGA_X_EOL) { x1 = *ptr++; printf("rectangle from (%d,%d)to (%d,%d)\n",x0,y0,x1,y1); } }

Note that for each (min, max) pair, the min coordinate pixels are included in the clipping shape, but the max coordinate pixels are not (they are one pixel unit outside the clipping shape). The client should not modify the contents of the data area pointed to by the return value.

If the drawable is a window, this clip shape does not include the clipping shape of the children of the window.

If the drawable is a pixmap, the clip shape is always a single rectangle.

A NULL pointer is returned if the X resource referred to if the current lock subject no longer exists. In this case, all rendering to this drawable will be entirely clipped.

Dealing with Cursor Conflicts

The cursor image may conflict with rendering when the DGA client is about to perform. In these cases, the client must detect the conflict and take down the cursor image. Only then should the client render. The window system restores the cursor image after the client unlocks the drawable.

Some devices always render the cursor image in a plane group dedicated for that purpose. These devices never display viewable drawables in this plane group. On these types of devices, there will never be any cursor conflicts. These devices are called dedicated cursor devices.

Some devices always render the cursor image in a plane group in which viewable drawables also reside. In this case, each time a viewable drawable is locked, the DGA client must detect a cursor conflict and then deal with the conflict. These devices are called software cursor devices.

Always truncate the cursor on a hardware cursor device. This forces the cursor into hardware any time a window is grabbed.

Whether a DGA client must handle potential cursor conflicts depends, therefore, on the type of device. No cursor conflict handling is needed for dedicated cursor devices or hardware cursor register devices that always truncate large cursor images. On the other hand, conflict handling is required for software cursor devices or hardware cursor register devices that don't truncate.

Except on devices for which there will never be conflicts, DGA clients are required to call dga_draw_curshandle if, after a drawable is locked, DGA_DRAW_MODIF returns nonzero. This is the case for window drawables only. This is not required for pixmap drawables. If the cursor image currently intersects the pixels of the drawable, the cursor will be taken down.

dga_draw_curshandle (Lock Only)

void dga_draw_curshandle(dgadraw, take_down_func, client_data) Dga_drawable dgadraw; DgaCursTakeDownFunc take_down_func; void *client_data;

Purpose	If the device is can have cursor conflicts, this routine should be called if, after locking a drawable, DGA_DRAW_MODIF returns nonzero. If there is a cursor conflict, this routine will take down the cursor.
Arguments	take_down_func is a pointer to a client-supplied function which can take down the cursor by restoring the pixels that the cursor was rendered over. client_data is a pointer to arbitrary client data which will be passed to the client-supplied function. The calling sequence for a typical take-down function is defined by the following type:

typedef void (*DgaCursTakeDownFunc)( void *, /* client_data */ Dga_drawable, /* dgadraw */ int, int, /* x, y */ Dga_curs_memimage */* memimgp */ );

where the Dga_cur_memimage structure is defined as follows:

typedef struct dga_curs_memimage { u_int width; u_int height; u_int depth; u_int linebytes; void *memptr; } Dga_curs_memimage;

take_down_func should restore (width*height) pixels of depth depth stored at the locations pointed to by memptr to the screen starting at (x, y) relative to the window origin. Successive scanlines of the stored pixels are separated by linebytes bytes. The current possible depths are 1, 8, 32. Depth 1 pixels are packed 8 pixels per byte. Depth 8 pixels are packed 1 pixel per byte. Depth 32 pixels are packed 1 pixel per 4 bytes.

The cursor take-down function is always called within the lock critical section. Therefore, care should be taken to avoid performing lengthy and time-consuming operations within it, such as system calls. Otherwise, the DGA lock time-out might expire, causing the lock to be prematurely broken.

---

Note - take_down_func will only be called if the cursor needs to be taken down because it is currently up and intersects the pixels of the drawable. The overlap test is currently based on the bounding box of the drawable, not on the actual exposed shape.

---

---

Note - It is very important that dga_draw_curshandle be called after every window lock for which DGA_DRAW_MODIF returns nonzero. If the drawable is locked without checking DGA_DRAW_MODIF and calling dga_draw_curshandle, future locks of the drawable may not notice the cursor conflict.

---

Backing Store Routines

The following routines are provided for direct access to the backing store of a drawable. Currently, only windows have backing store.

dga_draw_rtngrab

int dga_draw_rtngrab(dgadraw) Dga_drawable dgadraw;

Purpose	This routine provides direct access to the backing store of a window. A window may have backing store either due to some client setting the XWindowAttributes.backing_store attribute of the window to WhenMapped or Always, or due to the window being occluded by a save-under window.
Returns	Nonzero if direct access to the backing store of a window is permitted. In this case, the necessary client/server information sharing channel is established.

Zero is returned if the server denies access to backing store for the drawable or the routine otherwise fails.

The window does not need to actually have backing store at the time of the call. The backing store may be provided by the server at a later time. It is the responsibility of the client to always check for the presence of backing store. See section "dga_draw_rtnchg (Lock Only)" on page 174 for more on this.

---

Note - If a DGA client does not call this routine, or if it does call it, but the routine fails, the server assumes that the client is not updating the contents of the backing store when it renders. If this is the case, the server considers the backing store inconsistent when the drawable is unlocked. This may cause an exposure event to be sent for the drawable.

---

---

Note - Grabbing the backing store of a drawable consumes one file descriptor in the client and one file descriptor in the server.

---

dga_draw_rtnungrab

int dga_draw_rtnungrab(dgadraw) Dga_drawable dgadraw;

Purposedga_draw_rtnchg (Lock Only)	This routine terminates direct access to backing store for the given window and frees any associated resources.
int
Purpose	This routine should be called if, after the window drawable is locked, DGA_DRAW_MODIF returns nonzero.
Returns	Nonzero if the state of the drawable backing store has changed since the last time the drawable was locked. If nonzero is returned, dga_draw_rtnactive should be called to determine whether backing store is currently present. This is because the window server may attach or detach backing store at any time. If backing store is present, the client is required to update the contents of the backing store appropriately.

This routine returns valid information only the first time it is called after locking the drawable. To use this routine, dga_draw_rtngrab must have first been called on the drawable and the grab must have succeeded.

For initialization purposes, this routine will always return nonzero the first time it is called.

dga_draw_rtnactive (Lock Only)

int dga_draw_rtnactive(dgadraw) Dga_drawable dgadraw;

Purpose	This routine should be called each time dga_draw_rtnchg indicates a change occurred to the state of a window drawable's backing store; the server may have granted or taken away backing store from the windows.
Returns	Nonzero if backing store is currently available to the drawable; otherwise zero.

A return value of zero indicates that backing store is not (or no longer) available for the drawable. In this case, the client does not need to update the backing store contents. Otherwise, the client should call the routines described below in order to update the backing store.

dga_draw_rtncached (Lock Only)

int dga_draw_rtncached(dgadraw) Dga_drawable dgadraw;

Returns....A nonzero value if the backing store is cached in hardware as opposed to being in system memory. If the return value is set to DGA_RTN_NEW_DEV, then it means that the server has re-cached the backing store from system memory to the hardware device associated with the drawable. If this is the case, then the name and type of the device may be obtained by calling dga_draw_rtndevtype (see page 176).

If the return value is set to DGA_RTN_SAME_DEV, then the backing store remains cached in the same device as previously recorded. If the backing store is not cached,

DGA_RTN_NOT_CACHED is returned. DGA_RTN_NEW_DEV, DGA_RTN_SAME_DEV and DGA_RTN_NOT_CACHED are predefined constants.

dga_draw_rtndevinfop (Lock Only)

void * dga_draw_rtndevinfop(dgadraw) Dga_drawable dgadraw;

Returns	A pointer to the device-specific shared backing store information when the backing store is cached. The pointer is invalid if the backing store is not cached. This structure contains device-specific information. This device-specific information is required because devices that support cached backing store may implement it differently. The pointer points to a memory area which is 8 bytes long and 4-byte aligned. An example of this structure could be:
struct {dga_draw_rtndevtype (Lock Only)
void
Purpose	This routine is used to obtain the shared backing store's hardware cache device type and name.
Arguments	type is device dependent.

name should point to an array of characters. The returned name will be a maximum of 32 characters long, including a NULL terminator.

dga_draw_rtndimensions (Lock Only)

void dga_draw_rtndimensions(dgadraw, width, height, linebytes) Dga_drawable dgadraw; short *width; short *height; u_int *linebytes;

Purpose	This routine is used to obtain the dimensions of the shared backing store.
Argumentsdga_draw_rtnpixels (Lock Only)	linebytes is valid only for non-cached backing store.
void *
Returns	A pointer to the backing store's pixel memory. This pointer is valid only for non-cached backing store. The format of the shared memory backing store is the same as the pixmap format of the corresponding depth for the window's screen.

DGA Overlays

The DGA overlay interface allows direct access to windows in overlay planes. To render in overlay windows, the client must be able to manipulate the device's visibility planes. When overlay windows are in the same plane group as other windows, they are in conflict. Direct rendering to overlay windows in conflict is not allowed. A client may inquire the overlay state by calling dga_draw_ovlstate to determine whether the overlay windows supported on that device are in conflict with other windows.

---

Note - This section applies only to Sun transparent overlays. It does not apply to server overlays. For information about transparent overlays and server overlays, see the Solaris X Window System Developer's Guide.

---

---

Note - Currently, direct rendering to backing store associated with overlay windows is not supported.

---

Direct access to overlay windows follows the same locking rules as other windows. dga_draw_type (on page 159) returns DGA_DRAW_OVERLAY for a grabbed overlay window.

---

Note - The following new functions are specific to overlay windows and should only be called when the drawable holds the lock.

---

dga_draw_ovlstate

int dga_draw_ovlstate(dgadraw) Dga_drawable dgadraw;

Purpose....Use this function to determine whether to render directly to an overlay window. It returns the overlay state for dgadraw.

To render to an overlay, clients need to get additional device-specific information. Get this information from the device's devinfo pointer with dga_draw_devinfo (see page 161).

Returns           DGA_OVLSTATE_SAFE

If the return state is DGA_OVLSTATE_SAFE, render both opaque and transparent paint on the window using the device-specific information.

DGA_OVLSTATE_MULTIWID

If the return state is DGA_OVLSTATE_MULTIWID, render with opaque paint using the device-specific information. Most devices are unable to provide enough information for the

client to successfully render transparent paint on its own. In this case, use X11 protocol requests to render transparent paint to the overlay.

DGA_OVLSTATE_CONFLICT

If the return state is DGA_OVLSTATE_CONFLICT, the client cannot render either opaque or transparent paint to the overlay.

dga_draw_ovlstatechg

int dga_draw_ovlstatechg (dgadraw) Dga_drawable dgadraw;

Purpose	Indicates whether the overlay state has changed since the last time the drawable was locked. If the DGA_DRAW_MODIF macro indicates that an overlay has been altered, use this function to see if the overlay's state has changed.
Returnsdga_draw_ovlstatesetnotify	1 if the overlay state has changed; 0 otherwise.
void
Purpose	Allows the client to set a pointer to a user-specified overlay state change notification function associated with dgadraw. It is automatically called during lock and MODIF flag processing if the overlay window's conflict state has changed.

dga_draw_ovlstategetnotify

void dga_draw_ovlstategetnotify(dgadraw, pOvlstate_notify_func, pClient_data) Dga_drawable dgadraw; DgaOvlStateNotifyFunc *ovlstate_notify_func; void **client_data;

Purpose	Returns the previously set overlay state change notification function.
Returns	NULL if no function has been set.

Colormap Grabber Interface

The following routines are the client's interface to the colormap grabber functions.

XDgaGrabColormap

Dga_token XDgaGrabColormap(dpy, cmap) Display *dpy; Colormap cmap;

Results	This function grabs an existing X11 (virtual) colormap and creates server-side resources for sharing updates to it with the client. The window server is sent a protocol request to create a shared colormap information file.
Returns	A token, which is used by the client to access the shared information.

An error code if the window system refuses the registration request. The request also fails if the DGA client and the server are not running on the same machine.

dga_cm_grab

Dga_cmap dga_cm_grab(devfd, token) int devfd; Dga_token token;

Purpose	This function is similar to dga_win_grab, in that it maps a shared memory data structure and returns a pointer to a client-side structure.
Arguments	devfd is the file descriptor of the graphics device on which the grabbed window is resident.

If the device is not known or not yet opened, the caller can pass in -1, and dga_cm_grab opens the correct device file, using information found in the shared memory area.

token must be obtained by a previous call to XDgaGrabColormap.

Returns....A Dga_cmap handle if successful; NULL for failure.

The Dga_cmap structure contains client-specific information and a pointer to the shared memory. Thus, several clients can grab the same colormap.

dga_cm_ungrab

void dga_cm_ungrab(dgacmap,cflag) Dga_cmap dgacmap; int cflag;

Purpose....This function releases resources allocated by a previous call to dga_cm_grab. All resources and memory mappings created by dga_cm_grab are freed or made inaccessible as a result of this operation. Call XDgaUnGrabColormap after invoking this function to free window server resources. If the cflag argument is a nonzero value, the graphic device file is also closed.

XDgaUnGrabColormap

int XDgaUnGrabColormap(dpy, cmap) Display *dpy; Colormap cmap;

Purposedga_cm_devfd	This function releases server resources associated with a shared colormap by sending the window server a protocol-extension request.
int dga_cm_devfd(dgacmap)
Returnsdga_cm_devinfop	The client's file descriptor for the frame buffer with which the grabbed colormap is associated.
void *dga_cm_devinfop(dgacmap)
Returns	A pointer to a shared-memory area containing device-dependent colormap information. The pointer is guaranteed to be 4-byte aligned and points to an area of 132 bytes. On devices with multiple hardware colormaps, information regarding the identity of the hardware colormap associated with the grabbed X colormap could be stored here. This device-specific information is required because each device that supports multiple hardware colormaps implements it differently. Any device information that needs to be sent between the server device code and the client device code is stored here. Device-dependent server code stores information here that the client can read.

dga_cm_set_client_infop

void dga_cm_set_client_infop(dgacmap, client_info_ptr) Dga_cmap dgacmap; void *client_info_ptr;

Purposedga_cm_get_client_infop	This routine allows the client to set a pointer to client-specific data associated with dgacmap. This pointer could point to information that is local to the client alone.
void *dga_cm_get_client_infop(dgacmap)
Returnsdga_cm_write	The client-specific data pointer associated with dgacmap. If this pointer was not set by the client, then this routine returns NULL.
void dga_cm_write(dgacmap, index, count, red, green, blue,
Purpose	This function requests that the colormap information in the red, green, and blue arrays in user data space be placed in the grabbed colormap referenced by the dgacmap argument, starting at index, for count entries.
Arguments	putfunc is a client-supplied and device-dependent callback function that updates the hardware colormap when necessary.

The calling sequence for the callback routine is:

void putfunc(dgacmap, index, count, red, green, blue);

The purpose of calling the device-dependent routine indirectly through dga_cm_write is to ensure proper coordination with the server.

If the colormap is currently installed, then the new values are loaded into the appropriate hardware colormap via the client-supplied callback routine. If the X11 colormap is not currently installed, no hardware update is performed. The putfunc function is called only if the colormap is installed in hardware.

dga_cm_read

void dga_cm_read(dgacmap, index, count, red, green, blue) Dga_cmap dgacmap; int index, count; u_char *red, *green, *blue;

Purpose....This function reads colormap information into the red, green, and blue arrays in user data space. The dgacmap argument describes which colormap to read from. The data is read, starting at index, for count entries. The information is read from the shared-memory representation of the X11 virtual colormap.

Miscellaneous Grabbers

The following routines define the client interface to the window ID grabber, fast clear plane grabber, stereo grabber and Z buffer grabber. These grabbers may require specialized hardware.

---

Note - Currently, miscellaneous grabbers only work for windows; they will fail for pixmaps.

---

XDgaDrawGrabWids

int XDgaDrawGrabWids(dpy, drawid, nwids) Display dpy; Drawable drawid; int nwids;

Purpose

Some graphics devices control video display characteristics and/or hardware clipping via a control plane group called a window ID (WID) plane group. Normally WIDs are allocated and managed by the server. In some cases, DGA clients can make use of multiple WIDs for a single window to optimize some operation. XDgaDrawGrabWids is called to allocate nwids consecutive WID's. The window must have previously been grabbed via XDgaGrabDrawable.

Returns

Zero for failure; nonzero for success.

If successful, the WID values can be obtained from the shared memory via the dga_draw_widinfop (see page 186) routine. WIDs are 16-bit unsigned integer values. The base WID will be aligned on a power-of-two boundary which is determined by rounding up nwids to the next power of two.

dga_draw_widinfop

Dga_widinfo * dga_draw_widinfop(dgadraw) Dga_drawable dgadraw;

Returns....A pointer to the dga_widinfo structure in the shared memory area for dgadraw. The structure is defined as follows and can also be found in the file dga.h:

typedef struct dga_widinfo { short w_number_wids; /* number contiguous block wids allocated */ short w_start_wid; /* starting wid of the wid block */ short w_wid; /* current drawing wid */ short reserved_1; /* for the future */ } Dga_widinfo;

In this structure, w_number_wids is the total number of WIDs that have been allocated as a contiguous block. w_start_wid is the starting window ID value of this block. w_wid is the value of the window ID currently being used for the window associated with the handle dagdraw.

XDgaDrawGrabFCS

int XDgaDrawGrabFCS(dpy, drawid, nfcs) Display *dpy; Drawable drawid int nfcs;

Purpose....Some graphics devices have a feature called fast clear sets which can effectively speed up the clearing of the back buffer in a multibuffering application. Fast clear sets are scarce resources dedicated to a particular window. XDgaDrawGrabFCS is used to request one or more fast clear sets. The window must have previously been grabbed via XDgaGrabDrawable. The function returns zero for failure,

nonzero for success. If successful, the FCS values can be obtained from the shared memory via the dga_draw_db_dbinfop routine, described in a previous section. The FCS information will be stored in the device-dependent section (device_info) of the dga_draw_dbinfo structure. To release the allocated FCSs call XDgaDrawGrabFCS with an nfcs argument of zero.

XDgaDrawGrabStereo

int XDgaDrawGrabStereo(dpy, drawid, st_mode) Display *dpy; Drawable drawid int st_mode;

Purpose	Some graphics devices are capable of stereo display of images. This function is used to inform the server that a particular window will be using stereo display. The window must have previously been grabbed via XDgaGraDrawable.
Returns	Zero for failure, nonzero for success.
Arguments	st_mode is 1 to enable stereo, 0 to disable it.