Overview of the XglDrawable

The XglDrawable object conceptualizes the sharing of a device with another entity, most often the window system, but possibly also a Memory Raster device or a Stream device. In the case of the window system, it also makes transparent to the pipeline whether it is running in an X client (using the DGA mechanism, PEXlib, or Xlib) or in a PEX server.

Because there are so many different ways to access target devices, the XglDrawable object was designed to encapsulate the various access mechanisms. Ideally, device pipelines do not need to be aware of the underlying mechanism. For example, a device pipeline can be used to render to an X window as a DGA client, within the server, or in a backing store.

XglDrawable objects are created by the XGL core in response to an xgl_object_create() call with a Device type, such as XGL_WIN_RAS. XGL creates the appropriate XglDrawable object, establishes a connection to the window system, creates the Device object, and links the XglDrawable object to the Device object. There is a one-to-one correspondence between the Device object and the XglDrawable object for that Device.

There are several subclasses to the XglDrawable object, each of which manages a different kind of target device. Table 8-1 lists these subclasses.

Table 8-1

Subclass	Target Device
XglDrawableDgaCView	X11 window. This class encapsulates the DGA library.
XglDrawableMem	Memory Raster
XglDrawableDgaRtn	Backing-store device
XglDrawableXpex	PEXlib and Xlib device
XglDrawableDgaBase	Multibuffer in system memory
XglDrawableDgaCached	Multibuffer cached in hardware memory
XglDrawableStream	Stream device

---

Note - The device pipelines should interact with the XglDrawable object through the interfaces in Drawable.h, which contains the public interface for the XglDrawable hierarchy. Do not use the interfaces in the XglDrawable subclasses.

---

Services Provided by XglDrawable Class

The XglDrawable class was designed to provide information and services to both the XGL core and the device pipeline. In particular, it provides the device pipeline with a way to get current clip lists and to lock out clip list changes while rendering is in progress.

Services provided by XglDrawable for the XGL core include:

• Establishing the connection with the window system and creating the XglDrawable object - grabDrawable()
• Terminating the connection with the window system and destroying the XglDrawable object - unGrabDrawable()

Services provided by the XglDrawable for the device pipelines include:

• Locking clip lists, thereby preventing the window system from changing them during rendering - winLock()
• Unlocking clip lists - winUnLock()
• Indicating whether clip lists have changed - clipChanged()
• Providing information about window geometry - getWindowWidth(),

getWindowHeight(), getWindowX(), getWindowY(),
getWindowDepth()

• Providing access to the clip list - getMergeClipList()

A more extensive discussion of the services provided for the pipelines by the XglDrawable begins on page 189.

A Typical Scenario of Drawable Creation and Use

The creation of the XglDrawable object is handled automatically by the XGL core. The typical sequence of operations when a window raster is created is this:

1. A client (application) program maps a window and then creates an XGL API Device object.

2. The XGL core calls XglDrawable::grabDrawable() with the descriptor provided by the application. grabDrawable() uses the window descriptor information included in the request to determine the kind of Drawable required. This depends on the raster type (memory or window), the window type specified by the application, and whether the window system accepts the connection. grabDrawable() returns an XglDrawable object.

3. The XGL core calls drawable->getPipeName() to get the name of the appropriate rendering pipeline. If not already loaded, that pipeline is then loaded. The XGL core calls dp_lib->getDpMgr() to retrieve or create (if it doesn't exist) a DpMgr object to manage the physical device, and then calls dp_mgr->createDpDev() to create a DpDev object to manage the window. getDpMgr() and createDpDev() may call various XglDrawable functions to get information required for handling the device.

4. The pipeline should call XglDrawable::setCursorRopFunc() to register a function that will remove a software cursor from the window if necessary. Even pipelines for frame buffers with hardware cursors should call this function, as the window system may be displaying a cursor that is too big for the device's hardware cursor registers.

When the device pipeline is called on to render, it typically performs the following operations:

1. The pipeline calls drawable->winLock() to lock the clip lists.

2. The pipeline calls drawable->windowIsObscured() to determine whether the window is obscured. If drawable->windowIsObscured() returns TRUE, there is nothing to render, so the pipeline calls drawable->winUnLock() and returns.

3. The pipeline calls drawable->clipChanged() to determine whether the clip list changed since the last rendering operation. If

   drawable->clipChanged() returns TRUE, there is a new clip list. The pipeline proceeds as follows:

   a. It calls drawable->getWindowWidth(),

  drawable->getWindowHeight(), drawable->getWindowX(), and
  drawable->getWindowY() to get the new window geometry.

b. It then calls drawable->getMergeClipListCount() to determine how many rectangles are in the clip list. Note that MergeClipList is a combination of the window system clip list and the XGL settable user clip list.

c. It calls drawable->getMergeClipList() to get the clip list. It loads this clip list into device hardware if applicable.

4. The pipeline renders to the frame buffer.

5. The pipeline calls drawable->winUnLock() to unlock the clip lists.

Note that after winLock() is called, OpenWindows and other applications must wait until winUnLock() is called before rendering to that window. For this reason, keeping a window locked for more than about 0.1 second is discouraged. Therefore, the winLock() and winUnLock() functions have been made as lightweight as possible. Holding on to a lock for more than a fraction of a second may result in poor window-system interaction; after three seconds, the window system will forcefully break the lock, which may result in incorrect rendering on the screen.

What You Should Know About Locking the Window

The interface to DGA provides macros that serve to prevent the window clip list from changing during rendering. Locking the window also prevents other processes from rendering to the same window at the same time. All rendering pipelines should use the macros WIN_LOCK() and WIN_UNLOCK() (or the equivalent function calls winLock() and winUnLock()) around any operation that could alter the screen, or any time the pipeline needs a valid clip list. (The clip list may not be considered valid outside of a lock.) The pipeline uses these calls to explicitly lock and unlock the window unless the device supports concurrent access by multiple UNIX processes.

In the case of immediate-rendering hardware, a pipeline would use winLock() and winUnLock() around the actual rendering code:

WIN_LOCK(drawable) ;// cliplist is now valid if( drawable->clipChanged() ) // cliplist has changed since last lock { // retrieve new cliplist from drawable } // render WIN_UNLOCK(drawable) ;// done, cliplist no longer valid

Note that operations which do not depend on the clip list or change the contents of the screen do not need to be performed inside a lock. This can include things like changing rendering attributes and transformation matrices (except that the final viewport-to-screen coordinates transform depends on the size of the destination window, and thus must be done within a lock).

In the case of an asynchronous device (for example, a display-list device), the pipeline does not need to maintain the lock until rendering is complete. In this case, the pipeline needs only to hold the lock until the host has completed its access to the device. It is the responsibility of the window system and the hardware device to set up whatever synchronization protocol allows coherent rendering between them. This synchronization protocol, which is independent of XGL, most often relies on the window system requesting the accelerator to flush all its pending operations.

On a display-list device, the rendering code would look something like this:

WIN_LOCK(drawable) ;// cliplist is now valid and stable if( drawable->clipChanged() ) // clip list has changed since last lock { // retrieve new cliplist from drawable // and download to device. } // download display list to device. // initiate rendering. WIN_UNLOCK(drawable) ;// done // Window system will maintain stable clip list until // rendering is complete.

See "Accessing Dynamic Information Through the Drawable" on page 191 for more information on locking and unlocking the window at rendering time.

Drawable Interfaces for the Pipeline

The XglDrawable object provides a number of interfaces that allow you to:

• Obtain information about the frame buffer or the window
• Access dynamic information, such as window dimensions
• Manage window system resources

These general categories of functions are discussed in the sections that follow. For detailed descriptions of the XglDrawable pipeline interfaces, see page 197.

Obtaining Information During Pipeline Initialization

Several XglDrawable functions allow you to get information that you may need about the frame buffer during device creation. Table 8-2 lists these functions.

Table 8-2

Function	Description
getDevFd()	Returns the device file descriptor.
getDeviceName()	Returns a pointer to the frame buffer device name, such as /dev/fb.
getWindowDepth()	Returns the depth of the window.

For example, as part of your getDpMgr() function, you will probably first want to determine whether an XglDpMgr object for this frame buffer has already been created. One way of doing this is provided in the utility functions of the XglListOfDpMgr class. This class provides two functions: one to retrieve an existing DpMgr matching a file descriptor, and another to create a new DpMgr for the device.

XglDpMgr* XglListOfDpMgr::getDpMgr(int fildes)
void XglListOfDpMgr::addDpMgr(int fildes, XglDpMgr* mgr)

The code fragment below shows an example of how the pipeline can use these utility functions.

XglDpMgr* XglDpLibSampDp::getDpMgr(Xgl_obj_type, XglDrawable* drawable) { XglDpMgr* dpMgr; dpMgr = dpMgrList.getDpMgr(drawable->getDevFd()); if (dpMgr == NULL) { dpMgr = new XglDpMgrSampDp(drawable->getDevFd()); dpMgrList.addDpMgr(drawable->getDevFd(), dpMgr); } return dpMgr; }

Accessing Dynamic Information Through the Drawable

The primary service provided by the Drawable is to provide a mechanism to lock the window clip list during rendering. Since the window system updates the clip list and other window attributes in response to changes in the window, the XglDrawable object synchronizes access to the window information via a lock and release mechanism. Once the coordination between the client (XGL) and the server has been established, the client can draw directly to the window using the lock and release routines. Since the server can continue to update the window in response to changes in the window's characteristics, the client must lock the window clip list before drawing and unlock it when drawing is complete.

The lock function does the following:

• Locks the clip list so that the server cannot change it during a rendering operation
• Examines the clip list to see if it has changed since the last lock, and, if it has changed, the function updates the global copy of the clip list
• Merges the system clip list and the user clip list

The unlock function releases the lock on the clip list. At that point, the server can change the window at any time, and the clip lists are invalid until the next lock.

There are three kinds of clip lists that the XglDrawable object manages:

• Window system clip list. This is the clip list that is set by the window system.
• User clip list. This is the clip list that is set by the XGL application.
• Merged clip list. This clip list is obtained when the lock function merges the window system clip list and the user clip list.

Most device pipelines should use the merged clip list at all times. However, devices on which the window system sets up hardware window clipping in advance should use the user clip list.

Guidelines for Using the Window Lock Macros or Function Calls

To lock and unlock the window, the XglDrawable object provides the pipeline with a pair of macros and a pair of function calls.

	Lock	Unlock
Inline macros	WIN_LOCK(drawable)	WIN_UNLOCK(drawable)
Function calls	drawable->winLock()	drawable->winUnLock()

If performance is an issue, you should use the WIN_LOCK(drawable) inline macro to lock the window, and after rendering, use the WIN_UNLOCK(drawable) macro to unlock the window. Both WIN_LOCK() and WIN_UNLOCK() are designed to be as lightweight as possible; in other words, no function calls are made unless the window has changed.

If performance is not critical, the drawable->winLock() and drawable->winUnLock() inline functions can be used instead. These result in function calls for XglDrawable objects that actually need locking, so they are not quite as lightweight as the macros but result in less generated code.

Between Lock and Unlock Calls

All rendering occurs between lock and unlock calls. In addition to rendering during locks, the device pipeline may need other information, such as the current dimensions of the window. Once the window is locked, you can ask the XglDrawable object for the information that you need. In general, any hardware access that depends on the state of the window should be bracketed by lock and unlock calls.

The following code example shows a pipeline checking the state of the window and the status of the clip list. The clip list changes when the window moves, changes size, or is partially covered.

*drawable = device->getDrawable() ; WIN_LOCK(drawable) ; if( drawable->windowIsObscured() ) { //window is covered or closed WIN_UNLOCK(drawable) ; return 1 ; // window is obscured; don't render } if( drawable->clipChanged() ) { // load new clip list into hardware // recompute view transformation matrices } // render WIN_UNLOCK(drawable);

Table 8-3 lists functions that are only meaningful inside lock and unlock calls because, in general, the information that they return is valid only when the window information is locked.

Table 8-3

Function	Description
clipChanged()	Returns TRUE if the clip list has changed since the last time this function was called.
getClipMask()	Returns the clip mask.
getClipStat()	Returns one of DGA_VIS_UNOBSCURED, DGA_VIS_PARTIALLY_OBSCURED, or DGA_VIS_FULLY_OBSCURED. DGA_VIS_UNOBSCURED means that the window is completely exposed. DGA_VIS_PARTIALLY_OBSCURED means the window is partially clipped. DGA_VIS_FULLY_OBSCURED means that the window is completely hidden.
getMergeClipList()	Returns the clip list.

Table 8-3 (Continued)

Function	Description
getMergeClipListCount()	Returns the number of Xgl_irect structures in the clip list.
getWindowDepth()	Returns the depth of the window.
getWindowWidth() getWindowHeight()	Return the height or width of the window.
getWindowX() getWindowY()	Return coordinates of the window.
getWsClipList()	Returns the window clip list.
getWsClipListCount()	Returns the number of Xgl_irect structures in the window clip list.
windowIsClipped()	Returns TRUE if the window is partially clipped.
windowIsFullyExposed()	Returns TRUE if the window is completely exposed.
windowIsObscured()	Returns TRUE if the window is completely obscured.

Xpex and Memory Raster Pipelines

Note that for some drawable types, such as XglDrawableDgaRtn and XglDrawableMem, the concept of window locking has no meaning. However, in most cases the pipeline should call these functions as described anyway. Clip list inquiry functions will simply return the user's clip list.

Managing Window System Resources

Some frame buffers have special characteristics, such as hardware double buffering, Z-buffers, or stereo imaging. These attributes are a limited resource and are assigned by the window system. Table 8-4 lists functions that you can use to manage resources.

Table 8-4

Function	Description
grabWids()	Returns a block of window IDs from the server. Use with getWid() to return the IDs just allocated.
grabZbuf()	Communicates to the server a client request for a Z-buffer.
grabFCS()	Requests to allocate fast clear plane set.
grabStereo()	Requests stereo planes.
dbGrab()	Requests double buffering on the drawable.
dbUnGrab()	Terminates double buffering on the drawable.
getWid()	Returns the window IDs for the window, if applicable.
setWriteBuffer()	Sets the buffer to be written.
setReadBuffer()	Sets the buffer to be read.
setDisplayBuffer()	Sets the buffer to be displayed.
dbDisplayComplete()	Called after setDisplayBuffer(); returns 1 if the new buffer is now visible.
dbDisplayWait()	Waits for the double-buffering interval (one frame) to expire.
dbGetWid()	Returns the window ID for the double-buffering window.

As an example, during your device initialization, you may want to request a Z-buffer and specify hardware double buffering, since your hardware supports multiple buffers. A minimal implementation of these calls might be:

XglDrawable* drawable = device->getDrawable(); if (!drawable->grabZbuf(1)) { //request the Z buffer return error; } if (drawable->dbGrab(2, (void(*)())vrtfunc, cpage) { //request double buffering //set up hardware } else { //server didn't comply with request return 1; }

When the device pipeline is using double buffering, it is the pipeline's responsibility to inform the server/DGA of the buffer switch. To do this, use the relevant XglDrawable functions. See page 197 for a more complete description of the XglDrawable interfaces.

Managing Software Cursors

For frame buffers with software cursors, the XglDrawable object must be able to erase the cursor before drawing. The setCursorRopFunc() passes the Drawable a pointer to a device pipeline function that erases the cursor whenever necessary. Although XGL does not include a user-defined cursor, the pipeline should define the setCursorRopFunc() so that DGA can call it to copy the image under the software cursor (as passed in by a parameter to the cursor rop function) when the cursor is on top of the display window.

Description of Drawable Interfaces

The following is an alphabetized list of the XglDrawable operators. This list provides the syntax and description for each function. It also provides you with hints about how you can best optimize XglDrawable accesses within a pipeline. The hints are in the form of the following codes:

[E]	The function is time consuming to call; in other words, the subroutine call has many tasks to perform.
[M]	The function is moderately time-consuming; the subroutine call does very little.
[L]	The function is lightweight because it is inline code.
[L2]	The function is basically a lightweight function that is only time consuming if there has been a clip list change.

---

Note - The XglDrawable interface and any DGA interfaces mentioned in this chapter are uncommitted and subject to change.

---

XglDrawable Functions for the Device Pipeline

void winLock()

This function locks the raster's clip list and other information in the shared memory data structure, making it possible to render. All rendering must be between winLock() and winUnLock() calls.

This is an inline function for efficiency. In the noncontested case, it is very fast. winLock() and winUnLock() calls should be run fairly frequently so that the cursor and other updates on the screen are fast. Under no circumstances should XGL hold onto a lock for more than three seconds, since this can cause a timeout. [L2]

void winUnLock()

  Unlock the shared-memory data structure. [L2]

WIN_LOCK(d)

Lock the window. This macro is more efficient than using winLock(), but it expands to more code. [L2]

WIN_UNLOCK(d)
  Unlock the window. [L2]

Xgl_boolean clipChanged()
  Returns TRUE if the clip list has changed since the last time this function
  was called. Only valid inside a lock. [L]

int dbDisplayComplete(int waitflag)
  Returns 1 if the new displayed buffer is now visible. If the new buffer is not
  yet displayed, and waitflag is zero, returns 0. If waitflag is set,
  dbDisplayComplete() waits for the display to be visible if necessary and
  always returns 1. [E]

void dbDisplayWait()

Waits for the double-buffering interval (one frame) to expire. [E]

u_int dbGetWid()
  Returns the window ID for the double-buffering window. Meaningful only
  for frame buffers that use window IDs for double buffering. See also
  "Window System Dependencies".  [M]

Xgli_ClipStat getClipStat()
  Returns one of DRW_EXPOSED, DRW_CLIPPED, DRW_OBSCURED. Only valid
  inside a lock. [L]

int getDevFd()
  Returns the device file descriptor for the frame buffer on which the grabbed
  window is displayed. [M]

XglDevice* getDevice()

Returns the back pointer to the corresponding Device object, which may be XglRasterWin, XglRasterMem, and so on.

const char * getDeviceName()

Returns a pointer to the device name of the frame buffer on which the grabbed window is displayed, for example /dev/cgsix0. Note that the device has already been opened. [M]

const Xgl_irect_list& getMergeClipList()
  Returns the clip list. Only valid inside a lock. [L2]

Xgl_sgn32 getMergeClipListCount()
  Returns the number of Xgl_irect structures in the clip list. Only valid inside
  a lock. [L2]

XglPixRectMem* getMergeClipMask()

Returns a bitmap representing the visible portion of the window.

Xgl_color_type getRealColorType()
  Returns the actual color type of the underlying hardware, which can be one
  of XGL_COLOR_INDEX or XGL_COLOR_RGB.

void getWid(int &nwid, int &start_wid, int &cur_wid)
  Returns the window IDs for the window, if applicable. nwid is the number
  of window IDs, start_wid is the first window ID, and cur_wid is the
  current window ID. [M]

Xgl_sgn32 getWindowDepth()

Get window depth. [E]

Xgl_sgn32 getWindowWidth()
Xgl_sgn32 getWindowHeight()
  Return overall window geometry, including parts that may be clipped. Only
  valid inside a lock. [L]

Xgl_sgn32 getWindowX()
Xgl_sgn32 getWindowY()
  Return overall window geometry, including parts that may be clipped. Only
  valid inside a lock. [L]

Xgl_sgn32 getWsClipListCount()

Returns the number of Xgl_irect structures in the window clip list. Only valid inside a lock. [L]

const Xgl_irect_list& getWsClipList()
  Returns the window clip list. Only valid inside a lock. [L]

Xgl_sgn32 getUserClipListCount()

Returns the number of Xgl_irect structures in the user clip list. [L]

const Xgl_irect_list& getUserClipList()

Returns the user clip list. [L]

Xgl_boolean dbGrab(int nbuffers,
     void(*vrtfunc)(Dga_window), u_int* vrtcounterp)

Requests double buffering on this Drawable with nbuffers. Both vrtfunc and vrtcounterp are supplied by the device pipeline. For more information on the implementation of this function, see dga_db_grab() in the OpenWindows Server Device Developer's Guide. Returns TRUE for success and FALSE for failure. [E]

Xgl_boolean grabFCS(int nfcs)

Grabs nfcs fast clear sets. Releases fast clear sets by setting nfcs to zero. Returns FALSE for failure and TRUE for success. Currently only succeeds for OpenWindows windows and only when supported by the hardware. Fast clear set information is stored in an device-dependent manner. See "Window System Dependencies". [E]

Xgl_boolean grabWids(int nwids)

  Grabs nwids window IDs. Returns FALSE on failure. [E]

Xgl_boolean grabZbuf(int nzbuftype)

Grabs or releases the Z-buffer where 1 means grab and 0 means release. Returns FALSE for failure, TRUE for success. Currently only succeeds for OpenWindows windows and only when supported by hardware. Z-buffer information is stored in a device-dependent manner. See "Window System Dependencies". [E]

Xgl_boolean grabStereo(int st_mode)

Grab or release the stereo planes; 1 means grab, 0 means release. Returns FALSE for failure, TRUE for success. Currently only succeeds for OpenWindows windows and only when supported by hardware. Stereo plane information is stored in an undocumented device-dependent manner. See "Window System Dependencies". [E]

void setCursorRopFunc(void * my_rop_func,caddr_t client)

Sets the function that is used to remove the cursor from the screen. my_rop_func is a function provided by the pipeline. This function is called by DGA to copy the image under the software cursor as passed in through the caddr_t memptr parameter to the cursor rop function when the cursor is on top of the display window. The function should look like this :

void
my_rop_func(XglDevice *dev, int x, int y, int width, int height,
             int depth, int linebytes, caddr_t memptr,
             caddr_t client)

This function is called from within WIN_LOCK() whenever the cursor needs to be taken down. Its purpose is to copy a block of pixels onto the frame buffer, thus undrawing the cursor. The dev pointer is the XGL Device of the window for which the cursor is being undrawn; to retrieve the DpDev, get the XglDpDev object with device->getDpDev(). The arguments x,y,w,h,depth describe the region of the screen to be replaced. linebytes and memptr describe the source for the pixels. client is the arbitrary client data provided to setCursorRopFunc(). memptr points to the (0,0) pixel address of the image. The format is a row-column order with each row starting linebytes after the previous row. Note that no XGL attribute (that is the ROP and the plane mask) is relevant within this function.

All pipelines should provide this function if it is at all possible for a software cursor to intersect this drawable. [M]

void setDisplayBuffer(int buffer, int (*displayfunc)(),
                                caddr_t data)
  Sets the buffer to be displayed. displayfunc is a function that you provide
  in the form:

    int displayfunc(caddr_t data, Dga_window clientp, int buffer)

where data is the data provided, clientp is the client info pointer described in the OpenWindows DDK documentation, and buffer is the buffer to be written. Your displayfunc function is device dependent and is responsible for setting the hardware to display to the specified buffer. [M]

void setReadBuffer(int buffer, int (*readfunc)(),
                                caddr_t data)

Sets the buffer to be read. readfunc is a function that you provide in the form:

    int readfunc(caddr_t data, Dga_window clientp, int buffer)

where data is the data provided, clientp is the client info pointer described in the OpenWindows DDK documentation, and buffer is the buffer to be written. Your readfunc function is device-dependent and is responsible for setting the hardware to read from the specified buffer. [M]

void setWriteBuffer(int buffer, int (*writefunc)(),
                                caddr_t data)
  Sets the buffer to be written. writefunc is a function that you provide in
  the form:

    int writefunc(caddr_t data, Dga_window clientp, int buffer)

  where data is the data provided, clientp is the client info pointer
  described in the OpenWindows DDK documentation, and buffer is the
  buffer to be written. Your writefunc function is device-dependent and is
  responsible for setting the hardware to write to the specified buffer. [M]

Xgl_boolean windowIsClipped()

Returns TRUE if window is partially exposed. Only valid inside a lock. [L]

Xgl_boolean windowIsFullyExposed()

Returns TRUE if window is completely exposed. Only valid inside a lock. [L]

Xgl_boolean windowIsObscured()

Returns TRUE if window is completely obscured. Only valid inside a lock. Data does not need to be sent to the hardware if windowIsObscured() is TRUE. If backing store is enabled and handled by the device pipeline, the

pipeline should check the X window system's backing store attribute to determine whether it is WhenMapped or Always to decide whether to render to the backing store if windowIsObscured() is TRUE. [L]

Xgl_boolean dbUnGrab()

Terminates double buffering on this drawable. Returns TRUE on success, FALSE on failure. [E]

XglDrawable Functions Used by the XGL Core Only

Xgli_DrawClass getClass()
  Returns one of DRW_WIN_RAS, DRW_MEM_RAS, or DRW_CGM. These identify
  the kind of raster that this Drawable was created for.  [L]

void getDescriptor(void *)
  Returns the original descriptor passed to xgl_object_create(). [M]

DrawableLockType getLockType()
  This function is not normally relevant to device pipelines. It describes what
  action will be taken by winLock(), which can be one of DR_LK_NONE,
  DR_LK_FUNC, or DR_LK_MACRO.

cont char* getPipeName()

Used by the XGL core to determine the proper rendering pipeline for this window.

Xgl_window_type getType()
  Returns the Xgl_window_type from xgl.h for DRW_WIN_RAS. [L]

Xgl_boolean grabRetainedWindow()

Grabs a window for backing store. Returns an XglDrawable object on success and connects the new object to the existing XglDrawable object. Returns NULL on failure. Note that the retained window is actually a file in /tmp.

static XglDrawable *grabDrawable(Xgl_obj_desc *,
                                         Xgl_device *)
  Grabs the window. Returns an XglDrawable object on success, NULL on
  failure. Initializes most of the fields in the XglDrawableClient object. [E]

Xgl_boolean matchDesc(Xgl_obj_desc *)

Returns TRUE if the given descriptor matches this XglDrawable object. [E]

Xgl_boolean possible(Xgl_X_window *)
  Determines whether DGA is possible on this window. If DGA is possible,
  the function returns TRUE. If DGA is not possible, returns FALSE. In the
  latter case, PEXlib or Xlib must be used for rendering. [E]

void resize()
  Used to inform the XglDrawable object that the window has been resized.
  Note that this function is used only by the XglDrawableXpex subclass, since
  it has no other way of determining whether the window has been resized.

void setRectList(Xgl_irect rect_list[])
void setRectNum(Xgl_usgn32)
  Sets the user clip list. [E]

Xgl_boolean unGrabRetainedWindow()

Terminates access to the backing-store window. The XglDrawable object and its resources are freed.

void ungrabDrawable()

Used by the XGL core to terminate access to a window. The XglDrawable and all of its resources are freed.

Window System Dependencies

Unfortunately, some DGA information, such as fast clear sets, is not formally defined in OpenWindows DGA. Currently, the information is simply stored in the OpenWindows DGA shared page in a device-dependent manner.

Pipelines that need access to the double-buffering information or the bounding-box information in shared memory should use the following functions:

caddr_t winBboxinfop()
  Returns a pointer to the bounding-box information structure within shared
  memory. This structure is:

  struct {
        int     xleft, xtop;
        int     width, height;
   }

Returns NULL if not running under OpenWindows. [L]

Dga_dbinfo *winDbInfop()

Returns a pointer to the double-buffering information area within shared memory, as defined in <dga/dga.h>. Returns NULL if not running under OpenWindows. [L]