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 MBX 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 XGL, 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. MBX multibuffers may be either viewable or nonviewable depending on the type of memory where their pixels reside.

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. Only window and pixmap drawables are grabbed. MBX multibuffer drawables are implicitly grabbed by grabbing their associated window.

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. 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. Depending on the values of the Dga_drawable and buffer index, the client can specify any of the following to be locked: a multibuffer of a window, the window itself, or a pixmap. For details see "Drawable Locking and Change Detection" on page 156.

It should be emphasized that multibuffers share the same Dga_drawable as their main window; it is only through the buffer index that windows and multibuffers are differentiated. The buffer index for windows and pixmaps is always -1. The buffer index for a multibuffer is always a small natural number.

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 MBX (multibuffering extension) API or the XGL double buffering API. The client uses the routines provided in the drawable interface to maintain consistency with these changes.

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 a location. This location is defined either by an address or, for some types of multibuffers, a render buffer state. Together, the site type and location within the site define the drawable's site.

In between locks, a drawable's site may change for several reasons:

1. The display buffer may have changed, causing aliasing to another site. (Refer to the section "Multibuffer Flip Modes" on page 136 for more information).

2. The cache state of the drawable may have changed.

Because any type of drawable can potentially 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 10-1.

Figure 10-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 to the entire 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 tend to be rather large the server also supports placing the files in a path as defined by the -sharedretainedpath server command-line argument.

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.
Returns	The returned Dga_drawable is used to form the handle to be passed to subsequent DGA inquiry routines on that drawable.

For a window, use buffer index equal to -1. Likewise for a pixmap.

If the client wants direct access to a multibuffer, it should first query MBX to determine the main window of the multibuffer set. It should then call XDgaGrabDrawable to grab this window. When locking the multibuffer or inquiring state for the multibuffer, the index of the multibuffer (received from MBX) should be passed to DGA along with the Dga_drawable of the main window.

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 - If the drawable is a member of a multibuffer set (a multibuffered window or one of its multibuffers) the grab will succeed only if the number of multibuffers is less than or equal to 16.

---

---

Note - One file descriptor is consumed when the client grabs a window by calling DgaGrabDrawable. 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, or windows grabbed with one or more multibuffers. Since multibuffers that are not viewable can be assigned to windows subsequent to the grab, this file descriptor may not be actually consumed by DgaGrabDrawable itself, but rather, may be allocated during a later lock of the drawable. 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 dgadraw refers to a multibuffered window, all multibuffers associated with this window are also ungrabbed.

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 (window, pixmap, or multibuffer) to which subsequent DGA inquiry routines executed within the lock apply.

If dgadraw is a multibuffered window, not only is the window locked but all the multibuffers in the current multibuffer set are locked as well.

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.

Arguments..If the drawable to be locked is a non-multibuffered window or pixmap, bufIndex should be -1. The current lock subject (used within the lock critical section by other DGA routines) will be the window or the pixmap.

If the drawable to be locked is a multibuffer, dgadraw should be the Dga_drawable of the main window of this multibuffer. bufIndex should be its buffer index. The current lock subject will refer to this multibuffer.

DGA_DRAW_UNLOCK (Lock Only)

void DGA_DRAW_UNLOCK(dgadraw) Dga_drawable dgadraw;

Purpose....This macro permits external modification of the information in the shared memory data structure. Locke nest properly. This routine should be used only when a drawable has been first locked with DGA_DRAW_LOCK. 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;

Purpose

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 Dga_drawable.

Results

The current lock subject is the drawable (window, pixmap, or multibuffer) to which subsequent DGA inquiry routines executed within the lock apply.

If either of the drawables is a multibuffered window, not only is the window locked, but all the multibuffers in the current multibuffer set are locked as well.

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..If the drawable to be locked is a window or pixmap, the buffer index should be -1. The current lock subject of that drawable (used within the lock critical section by other DGA routines) will be the window or the pixmap.

If either of the drawables to be locked is a multibuffer, the Dga_drawable passed in should be that of the main window for the multibuffer. bufIndex should be its buffer index. The current lock subject will refer to this multibuffer.

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 before the drawables are unlocked.
ResultsDGA_DRAW_MODIF (Lock Only)	If either the source or destination drawable is a multibuffer, the lock count for the entire multibuffer set is decremented, and if zero, all members of the multibuffer set are 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.)

General Utility Functions

These routines allow the client to inquire various drawable attributes.

dga_draw_display

Display * dga_draw_display(dgadraw) Dga_drawable dgadraw;

Returns....The display of a drawable that has been grabbed with XGrabDrawable.

dga_draw_id

Drawable dga_draw_id(dgadraw) Dga_drawable dgadraw;

Returns....The XID of a drawable that has been grabbed with XGrabDrawable.

---

Note - This routine only returns the XID of a window or a pixmap. To determine the XID of a multibuffer, use this routine to inquire the XID of the main window and then use the MBX API routine, XmbufGetWindowAttributes, to inquire the multibuffer set information.

---

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 or DGA_DRAW_PIXMAP.
char *
Returns	A pointer to a null-terminated string representing the device name of the screen with which the grabbed drawable is associated.

dga_draw_devfd

int dga_draw_devfd(dgadraw) Dga_drawable dgadraw;

Returnsdga_draw_depth	The client's file descriptor for the screen with which the grabbed drawable is associated.
int
Returnsdga_draw_set_client_infop	This routine returns the depth of the grabbed drawable.
void
Purpose	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.

dga_draw_get_client_infop

void * dga_draw_get_client_infop(dgadraw) Dga_drawable dgadraw;

Returnsdga_draw_devinfo (Lock Only)	The client-specific data pointer associated with dgadraw. If this pointer was not set by the client, then this routine returns NULL.
void *
Returns	This function returns a pointer to the device-specific information area the DGA shared information area for the current lock subject. The structure should be accessed by the client to inquire device-dependent information which is 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. 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_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 can potentially undergo site changes.

• Pixmaps and nonviewable multibuffers can undergo site changes because they can become cached in device memory and alternately uncached.
• A site change can occur to a viewable multibuffer if the multibuffers in the multibuffer set for the main window are destroyed and then recreated. The multibuffer of the same buffer index in the multibuffer set may have a different address or viewability.
• Windows can also undergo site changes. But since a window may become multibuffered anytime after it is grabbed, and window aliasing of a multibuffer window can produce a site change, any window may potentially undergo a site change.

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 either the window or, if multibuffered, to any of its associated multibuffers. When the change has occurred to a window, bufIndex will be -1, otherwise it will be the index of the changed multibuffer.

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 not perform 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 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 the underlying X11 resource for the drawable has been destroyed since the last time the drawable was locked. Refer to the section "Zombie Drawables" on page 198 for more details.

The site of a viewable drawable is always 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 or multibuffer, the returned rectangle shape does not include any clipping of the window by other overlapping windows or multibuffers. 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 151 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:

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.

---

Note - It is recommended that dga_draw_visibility be used rather than the following two routines. However, these two routines are still provided for the convenience of programmers used to the older DGA window grabbing interface. These two routines are deprecated and will be removed in a future version of this interface.

---

dga_draw_singlerect (Lock Only)

int dga_draw_singlerect(dgadraw) Dga_drawable dgadraw;

Returnsdga_draw_obscured (Lock Only)	Nonzero if the current clipping shape of the current lock subject is a single rectangle, zero otherwise. Note that a clipping shape consisting of a single rectangle is not necessarily the same as the bounding box of the drawable.
int
Returns	Nonzero if the current clipping shape of the drawable is the same as the full shape of the window without regard to overlapping windows, zero otherwise. At present, this routine returns valid information only for rectangular windows.

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 and multibuffer 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 not perform 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 or multibuffer 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 178 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.

Another reason this type of change can happen is if the current lock subject of the window is actually a multibuffer. Since multibuffers don't have backing store in the current release, it might result in a reported retained change if the window itself has backing store. Another reason might be that a window with backing store was previously aliased but is no longer.

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 181).

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 { short basex, basey; /* backing store's position on frame buffer */ u_char mode; /* a device specific mode */ u_char pad[2]; } Shared_Retained_Dev_Info;

dga_draw_rtndevtype (Lock Only)

void dga_draw_rtndevtype(dgadraw, type, name) Dga_drawable dgadraw; u_char *type; char **name;

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_rtn_dimensions(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.
Arguments	linebytes is valid only for non-cached backing store.

dga_draw_rtnpixels (Lock Only)

void * dga_draw_rtnpixels(dgadraw) Dga_drawable dgadraw;

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.

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.

Multibuffering Grabber Interface

The following functions do not manipulate graphics device registers or device state. The developers of the graphics library device-dependent code that use these routines are responsible for all manipulations of a particular graphics device, and for providing callback routines that are called from within these functions. The callback routines can get to device-dependent information stored in shared memory.

Some of the following functions let the client communicate with the server with shared memory, which buffer it is using for pixel reads and writes, and for display. The server uses this information to select the buffer for Xlib rendering, so that applications that mix server rendering with DGA rendering in the same window behave properly.

dga_db_grab

int dga_db_grab(dgawin, nbuffers, vrtfunc, vrtcounterp) Dga_window dgawin; int nbuffers; void (*vrtfunc)(); u_int *vrtcounterp;

Purpose	This function requests the window system to provide multibuffering services for the grabbed window named in the dgawin argument. The call requests nbuffers to be allocated to the client. This window must have been grabbed previously via XDgaGrabWindow. The call to XDgaGrabWindow yields a handle, dgawin, which is used in this call. The window server initializes the portion of the shared memory window information area that relates to multibuffering.
Returns	Zero if the window system refuses the registration request; a nonzero value upon success. Each graphics device supports a small number of buffers. If more buffers are specified than the device can support, this call fails.
Arguments	vrtfunc is a client-supplied function that blocks the client process until (at least) the beginning of the next vertical retrace period. This function is called when operations dependent on the vertical retrace period are performed on dgawin. If this pointer is NULL, the functions dga_db_display (page 191), dga_db_interval_wait

(page 192) and dga_db_interval_check (page 192) will not perform accurate timing of the minimal interval between buffer swaps. The calling sequence of this function is:

void *vrtfunc(dgawin);

Often, vrtfunc is implemented as an ioctl to the associated device driver which, in turn, blocks until (at least) the beginning of the next vertical retrace period. The vrtfunc function might require the file descriptor of the device or information stored in the client-private data area and can obtain the information with dga_win_devfd and dga_win_get_client_infop.

vrtcounterp is a pointer to a client-supplied free-running vertical retrace counter. Often, this counter is implemented as a read-only device register that can be mapped into the client's address space or a memory location mapped into the client's space which is incremented by the associated device driver at vertical retrace interrupt. The DGA functions only read this counter. If this pointer is NULL, the functions dga_db_display, dga_db_interval_wait and dga_db_interval_check will not perform accurate timing of the minimal interval between buffer swaps.

dga_db_ungrab

int dga_db_ungrab(dgawin) Dga_window dgawin;

Returns....A previously multibuffered window to single-buffer mode. It also frees server and client multibuffering resources associated with dgawin.

If any of these steps fail, zero is returned. A nonzero value is returned upon success.

dga_db_write

void dga_db_write(dgawin, buffer, writefunc, data) Dga_window dgawin; int buffer; int (* writefunc)(); void *data;

Purpose	This function selects which buffer is written to when the client program draws to a multibuffered window.
Arguments	The device-dependent callback routine for setting the write buffer, writefunc, is supplied by the client program.

Permissible values for the buffer argument are small integers (from 0 to nbuffers-1). No function will be called if writefunc is NULL. The calling sequence of the callback routine is:

int writefunc(data, dgawin, buffer);

The purpose of calling the device-dependent routine indirectly through dga_db_write is to ensure proper coordination with the server. The application program uses data to pass private information to (and from) writefunc (but the data argument is now redundant, since dga_win_get_client_infop has been added to the interface).

dga_db_read

void dga_db_read(dgawin, buffer, readfunc, data) Dga_window dgawin; int buffer; int (*readfunc)(); void *data;

Purpose	This function selects which buffer is read from when the client program reads pixel values from a multibuffered window.
Arguments	The device-dependent callback routine for setting the read buffer, readfunc, is supplied by the client program.

Permissible values for the buffer argument are small integers. No function will be called if readfunc is NULL. The calling sequence of the callback routine is:

void readfunc(data, dgawin, buffer);

The purpose of calling the device-dependent routine indirectly through dga_db_read is to ensure proper coordination with the server. Use data to pass private information to (and from) readfunc (but the data argument is redundant, because dga_win_get_client_infop has been added to the interface).

dga_db_interval

void dga_db_interval(dgawin, interval) Dga_window dgawin; int interval;

Purpose....This function establishes a timed delay between buffer swaps.

Arguments dga_db_display	interval specifies in milliseconds the minimum delay between successive buffer swaps. The default interval is one refresh period. Assigning a negative value to interval results in the interval being set to the default interval. The exact duration of the default interval depends on the frequency characteristics of the monitor.
void dga_db_display(dgawin, buffer, visfunc, data)
Purpose	This function causes buffer to become visible. A device-dependent callback routine for making this buffer visible is supplied by the caller in the form of the visfunc routine. This routine gets the values of data, dgawin and buffer as arguments.
Arguments	No function is called if visfunc is NULL. Use data to pass private information to (and from) visfunc (but the data argument is now redundant, since dga_win_get_client_infop has been added to the interface).

This routine performs the following steps:

call dga_db_interval_check(); if (interval isn't exhausted) call dga_db_interval_wait(); call (*visfunc(data, dgawin, buffer));

This function first waits for the minimum display interval to elapse for the previous frame (if it has not already done so). Then, visfunc makes the named buffer visible. After calling visfunc, this function returns. visfunc need not block until the buffer is actually visible. It is up to the device-

rendering routines to ensure that buffer flip has been completed before commencing rendering. Typically, the actual visibility of the new buffer will be delayed until the next vertical retrace. This means that rendering a subsequent frame to the old buffer might need to be delayed until the next retrace. A client can check to see if the operation is completed by calling the dga_db_display_done routine (see page 193).

The purpose of calling visfunc indirectly through this routine is proper coordination with the server and maintenance of the buffer swap timing and vertical retrace synchronization.

dga_db_interval_wait

void dga_db_interval_wait(dgawin) Dga_window dgawin;

Resultsdga_db_interval_check	This function blocks the calling process until the minimum display interval time is exhausted.
int
Purpose	This Boolean function indicates whether the minimum display time has elapsed since a buffer flip was requested.
Returns	A nonzero value if the time has elapsed, zero if there is still time left.

dga_db_display_done

int dga_db_display_done(dgawin, flag, display_done_func) Dga_window dgawin; int flag; int (*display_done_func)();

Purpose	This function checks to see if the new buffer is visible after a previous call to dga_db_display. If the flag is set to zero, it performs a polling function. In this case, the function returns a nonzero value if the buffer has been switched, zero otherwise. If the flag is set to a nonzero value, the function blocks until the buffer has switched. In this case, a nonzero value is returned once the switch has occurred, -1 on error.
Arguments	display_done_func is a non-blocking routine that returns 1 when the new buffer is visible, 0 when the new buffer is not yet visible and -1 on error. The calling sequence of this function is:
(*display_done_func)(dgawin);dga_db_write_inquire
int
Purpose	This function is used to determine the state of multibuffering on a window, and indicates which buffer is selected for writing.
Returns	The buffer number.

dga_db_read_inquire

int dga_db_read_inquire(dgawin) Dga_window dgawin;

Purpose	This function is used to determine the state of multibuffering on a window, and indicates which buffer is selected for reading.
Returnsdga_db_display_inquire	The buffer number.
int
Returnsdga_win_dbinfop	The buffer number of the visible buffer.
Dga_dbinfop
Returns	A pointer to the multibuffering area in the DGA shared memory. The structure can be accessed for device-dependent information that must be shared between server and client. DGA routines do not interpret device-dependent data, but your graphics library device-dependent code might. This

structure also contains information regarding the hardware window ids associated with multibuffered windows. The definition of this structure is in the file dga.h.

typedef struct dga_dbinfo { short number_buffers; short read_buffer; short write_buffer; short display_buffer; u_int reserved_1; /* for the future */ u_int reserved_2; /* for the future */ u_int reserved_3; /* for the future */ u_int reserved_4; /* for the future */ u_int reserved_5; /* for the future */ u_int wid; /* db window id */ u_int reserved_6; /* for the future */ u_char device_info[132]; } Dga_dbinfo;

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 197) 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.

To release the allocated WIDs, call XDgaDrawGrabWids with an nwids argument of zero.

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_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.

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. A multibuffer can also be a zombie if the buffer index specified by the client is outside the range of multibuffers in the current multibuffer set. This can be the case if the main window is no longer multibuffered or the buffer index is greater or equal to the current number of multibuffers.

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.

---

Note - When an MBX application changes the number of multibuffers in a multibuffer set, it must first destroy all of the existing multibuffers and then create new ones. Because multibuffers in the DGA drawable interface are identified with a buffer index, it is possible for the index that identified a certain multibuffer in the old set, to now refer to a new one. To avoid this type of aliasing, client libraries should avoid rendering into multibuffers that have been destroyed. Presently, client libraries themselves need to make this determination with help from the application.

---