Overview of the XglDrawable

The XglDrawable object represents 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 7-1 lists these subclasses.

Table 7-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

Services Provided by the 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
• Terminating the connection with the window system and destroying the XglDrawable object

Services provided by the XglDrawable for the device pipelines include:

• Locking clip lists, thereby preventing the window system from changing them during rendering
• Unlocking clip lists
• Providing access to the clip list
• Indicating whether clip lists have changed
• Providing information about window geometry

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

Typical Scenario of XglDrawable 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 creates an XGL API Device object.

2. During Device creation, the XGL core calls

   XglDrawable::grabDrawable() with the descriptor provided by the application. The grabDrawable() function 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 the pipeline XglDpLib->getDpMgr() to retrieve or create (if it doesn't exist) a DpMgr object to manage the physical device, and then calls XglDpMgr->createDpDev() to create a DpDev object to manage the window. getDpMgr() and createDpDev() may call various XglDrawable functions to get information needed to handle the device.

4. The pipeline should call XglDrawable::setCursorRopFunc() to register a function that removes a software cursor from the window. 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 no need 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 determine 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 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. 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 forcefully breaks the lock, which may result in incorrect rendering on the screen.

Drawable Interfaces for the Device Pipeline

The XglDrawable object provides a number of interfaces that allow the device pipeline to:

• Obtain information about the frame buffer or the window
• Lock and unlock the window during rendering
• 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 170.

---

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.

---

Obtaining Information During Pipeline Initialization

Several XglDrawable functions allow the pipeline to get information that it may need about the frame buffer. Table 7-2 lists these functions.

Table 7-2

Function	Description
getDevFd()	Returns the device file descriptor.
getDeviceName()	Returns a pointer to the frame buffer device name.
getWindowDepth()	Returns the depth of the window.

For example, as part of the getDpMgr() function, you will probably first want to determine whether an XglDpMgr object for this frame buffer has already been created. "Defining the Device Pipeline Library Class" on page 32 shows an example of a pipeline getting this information using an XglDrawable interface.

Locking the Window

The primary service provided by the Drawable is to provide a mechanism to lock the window clip list during rendering. The window system updates the clip list and other window attributes in response to changes in the window, and 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 - Set by the window system.
• User clip list - Set by the XGL application.
• Merged clip list - 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.

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 at any time the pipeline needs a valid clip list. (The clip list may not be considered valid outside 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 WIN_LOCK() and WIN_UNLOCK() around the actual rendering code, as shown here:

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

Operations that 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 maintains stable clip list until // rendering is complete.

Guidelines for Using the Window Lock Macros or Function Calls

As mentioned above, the XglDrawable object provides the pipeline with a pair of window lock macros and a pair of function calls. These are listed in Table 7-3.

Table 7-3

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

If performance is an issue, use the WIN_LOCK(drawable) inline macro to lock the window and the WIN_UNLOCK(drawable) macro to unlock the window. The macros are designed so that 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 need locking, so they are not quite as lightweight as the macros but result in less generated code.

Accessing Dynamic Information

All rendering occurs between lock and unlock calls. Between these calls, the device pipeline may need information about the window, such as its current dimensions. Once the window is locked, the pipeline can get window information from the XglDrawable object. 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);

The next code example shows the use of the modifChanged() routine to check for any change in the shared memory data structure and the use of the devInfoChanged() routine to check for any change in the device-specific information in the shared memory data structure. The devInfoChanged() routine can be used by multiplane group hardware ports when a change in the window visibility needs to be handled (as opposed to the clip list, which is not updated when an overlay window visually obscures a window in the image planes).

WIN_LOCK(drawable); if (drawable->modifChanged()) { if (drawable->clipChanged()) { // Handle clip change } if (drawable->devInfoChanged()) { dev_info = drawable->winDbInfop(); // Check for anything that might have changed } } // render WIN_UNLOCK(drawable)

Table 7-4 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 7-4

Function	Description
clipChanged()	Returns TRUE if the clip list has changed since the last time this function was called.
modifChanged()	Returns TRUE if the shared memory data structure has changed since the last time this function was called.
devInfoChanged()	Returns TRUE if the device-specific information in the shared memory data structure 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 the window is completely exposed. DGA_VIS_PARTIALLY_OBSCURED means the window is partially clipped. DGA_VIS_FULLY_OBSCURED means the window is completely hidden.
getMergeClipList()	Returns the clip list.
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.

Table 7-4 (Continued)

Function	Description
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 7-5 lists functions that the pipeline can use to manage resources.

Table 7-5

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.

Table 7-5

Function	Description
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.
getDrawType()	Determines whether the server supports DGA overlays for the drawable.

As an example, if your hardware supports multiple buffers, you may want to request a Z-buffer and specify hardware double buffering during device initialization. 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 uses 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 170 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 inline code and is therefore lightweight.
[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 interfaces that are subject to change.

---

XglDrawable Functions for the Device Pipeline

void winLock()

Locks the raster's clip list and other information in the shared memory data structure. 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 because this can cause a time-out. [L2]

void winUnLock()

  Unlocks the shared-memory data structure. [L2]

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

WIN_UNLOCK(d)

Unlocks 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" on page 178. [M]

Xgl_boolean devInfoChanged()

The routine returns a cached devinfoFlag flag and clears the flag. The devinfoFlag is set to TRUE if the device-specific information area in the shared memory data structure has changed since the last time this routine was called. Only valid inside a lock.

This routine may be used by Multi Plane group hardware ports where a change in the window visibility (as opposed to the clip list which is not updated when an overlay window visually obscures a window in the image planes) need to be processed.

Xgli_ClipStat getClipStat()
  Returns DRW_EXPOSED, DRW_CLIPPED, or 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]

int getDrawType()
  Returns the Drawable type, which is defined in dga_externaldefs.h as
  either DGA_DRAW_WINDOW, DGA_DRAW_PIXMAP, or DGA_DRAW_OVERLAY. [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()

Gets 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 X 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" on page 178. [E]

Xgl_boolean grabStereo(int st_mode)

Grabs or releases 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" on page 178. [E]

Xgl_boolean modifChanged()

The routine returns a cached modIf flag and clears the flag. The modIf is set to TRUE if the shared memory data structure has changed since the time this routine was called. Only valid inside a lock.

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 Device, 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 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; otherwise, 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)
  Set 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]

void* getDevinfo()

This routine returns a pointer to the device-specific information area in the shared memory data structure. This information is not used by XGL, but the device pipeline should know how to interpret it. Only valid inside a lock.