Initializing Drawable Grabs

The latest version of the DGA applications programmer's interface (API) in the SDK supports direct access to window, pixmap, and multibuffer drawables. In the initialization sequence that supports arbitrary drawable types, not only is this same function vector given to DGA, but two new functions are also given. Providing these new functions is optional. If they are NULL, the DGA drawable interface (dga_draw_xxxx API routines) is only able to grab window drawables.

Call the following initialization routine from the InitOutput routine of your DDX handler.

dgaScreenInit

int dgaScreenInit(pScreen, pDgadevfuncs, major, minor) ScreenPtr pScreen; void *pDgadevfuncs; int major; int minor;

Arguments..pDgadevfuncs is a function vector of device-dependent functions cast to a void*:

typedef struct _DgaDevFuncsDraw { int (*DgaAvail)(); void (*GrabDrawable)(DrawablePtr); void (*UngrabDrawable)(DrawablePtr); int (*CacheDrawInit)(DrawablePtr); int (*CacheDrawCleanup)(DrawablePtr); int (*DbSetup)(WindowPtr, WXINFO*, int, Bool); int (*WidSetup)(WindowPtr, int, WXINFO*); int (*FcsSetup)(WindowPtr, WXINFO*, int); int (*ZbufSetup)(WindowPtr, int, WXINFO*); int (*StereoSetup)(WindowPtr, int, WXINFO*); int (*ChokeFb)(ScreenPtr, Bool); int (*SyncDrawable)(DrawablePtr,GCPtr); int (*UnsyncDrawable)(DrawablePtr,GCPtr); int (*CmapSetup)(CmapPtr, Grabbedcmap*) } DgaDevFuncsDraw;

The pDgadevfuncs argument may be NULL. If so, it means that client DGA is not available on the device.

The device handler is not required fill out all members of devFuncs; some functions may not be applicable to a device and these entries should be NULL in the vector.

The major and minor arguments are the major and minor version numbers for the DDK release as specified in "DDX Versioning" on page 9.

All of the types and structures listed above are defined in the include file dga/dgawinstr.h.

Device-Supplied Routines

Use the following routines during DGA initialization. Values can be NULL; however, functionality might be limited.

DgaAvail

int (*DgaAvail)()

Purpose	This function advertises the flavor of DGA that a device supports. If this function is NULL, the device is considered to not support client DGA. All devices supporting client DGA must supply this routine.
Returns	The definitions of the return codes are found in

dga/dgawinstr.h.

If a device does not support DGA, this routine should return

DGA_AVAIL_NONE.

If the device supports DGA and also has a cursor that is always rendered in hardware, it should return DGA_AVAIL_CURS_HW.

If the cursor is always rendered in software, this routine should return DGA_AVAIL_CURS_SW.

A device that has a limit to the size of cursor that can be drawn in hardware and intends to support larger cursors in software, this routine should return DGA_AVAIL_CURS_HW_SW.

For example, on the GX/GX+, the maximum size for a hardware cursor is 32x32. If a client loads in a cursor that is larger than this, the GX switches to software to render this cursor. So, GX/GX+ would return DGA_AVAIL_CURS_HW_SW from this routine.

GrabDrawable

void (*GrabDrawable)(DrawablePtr pDraw)

Purpose....This function is called when a drawable is first grabbed to allow the device handler to initialize device-dependent information for the drawable. See Server-Supplied Multibuffering Routines for routines to update the device-dependent information area of a drawable. Also, this section describes routines that should be called if the drawable is cached.

---

Note - This function is only called the first time a client grabs the drawable. It is never called for subsequent attempts to grab the same drawable, either by the client to first grab or other clients. Likewise, UngrabDrawable is only called when the last grabbing client ungrabs.

---

---

Note - This function is called on the first grab, even if the drawable is a window that is being grabbed through the older version of the DGA interface, the Window Compatibility Interface. In this case the WindowPtr is cast to a DrawablePtr. .

---

UngrabDrawable

void (*UngrabDrawable)(DrawablePtr pDraw)

Purpose....This function is called when a drawable is ungrabbed. It should undo anything that GrabDrawable has done. For example, the device-specific shared information may need to be updated.

---

Note - This function is called on the first grab, even if the drawable is a window that is being grabbed through the older version of the DGA interface, the Window Compatibility Interface. In this case the WindowPtr is cast to a DrawablePtr. See "Window Grabber Supported Functions" on page xxiv.

---

CachedDrawInit

int (*CachedDrawInit)(DrawablePtr pDraw)

Purpose....This function allows the device handler to do any device-specific setup needed for the drawable when it is cached. Examples include: location within the cache and the format of the data within the cache.

This routine is called for drawables that may be cached in special device memory. Drawable types that can cached include: pixmaps, nonviewable multibuffers, and the backing store of a window.

---

Note - Drawable refers to backing store in this context, even though a backing store is technically not a drawable because it doesn't have an XID.

---

The type of drawable may be determined by inspecting pDraw->type. If this is DRAWABLE_WINDOW, the type of drawable that is being referred to is the drawable's backing

store. The server-internal structure for this backing store (which, incidentally, happens to be of type PixmapPtr) can be derived using the expression:

((miBSWindowPtr)((WindowPtr)pDraw)->backStorage)->pBackingPixmap

If the type is DRAWABLE_PIXMAP, then the routine DgaMbIsMultibuffer should be called to determine if the drawable is a pixmap or a multibuffer.

Results....If the drawable is cached, this routine should do the following:

1. Call DgaCacheDescribeDev on the pScreen of the drawable with devCode and devname.

2. Call DgaCacheStateChange with a value of TRUE.

3. Call DgaDevInfoGet and DgaDevInfoChange to update any device-dependent information which is necessary for the cached drawable.

After this routine has been called, whenever the device handler changes the cache state of the drawable, it should call these routines.

Returns....If this routine returns 0, DGA assumes that the drawable is of type DGA_DRAW_SYSTEM and it copies the contents of the pixmap to the shared page.

This routine should return 1 if the drawable is not of type DGA_DRAW_SYSTEM, or the device handler has already copied the pixmap to the shared page.

CachedDrawCleanup

int (*CachedDrawCleanup)(DrawablePtr pDraw)

Purpose....This function is called when a nonviewable drawable or backing store is ungrabbed. It should undo anything done by CachedDrawInit. For example, it would call DgaCacheStateChange to mark the drawable as uncached. DgaDevInfoGet and DgaDevInfoChange might need to be called to clean up information in the device-dependent shared area.

The type of drawable might be determined by inspecting pDraw->type. If this is DRAWABLE_WINDOW, the type of drawable being referred to is the drawable's backing store. The server-internal structure for this backing store can be derived using the expression:

((miBSWindowPtr)((WindowPtr)pDraw)->backStorage)->pBackingPixmap

If the type is DRAWABLE_PIXMAP, then the routine DgaMbIsMultibuffer should be called to determine if the drawable is a pixmap or a multibuffer.

Returns....1 on success; 0 on failure. If 0 is returned, DGA assumes the drawable (or backing store) is uncached and directs its data pointer at the shared page. At this time, the contents of the drawable (or backing store) are copied to the shared page.

DbSetup

int (*DbSetup)(WindowPtr pWin, WXINFO *infop, int num_buf, Bool flag)

Purpose	This function is called when an application requests direct access to do multibuffering. Typically, this function would update some device-specific structures/hardware states, as well as information on the shared info page.
Arguments	The WXINFO structure has a field, wx_dbuf, which is a structure containing information relevant to multibuffering. The definitions of these structures are found in dga/dgawinstr.h.

This function must update the following structures:

infop->wx_dbuf.num_buffers should be set equal to the total number of buffers that the device supports in hardware. If the number of buffers available from the device is less than the requested number, num_buf, this function should return failure (0).

MPG Devices with hardware window ids can allocate a new window id for the multibuffered window. If so, this function is responsible for repreparing the window with the new (hardware) window id. If a new and unique WID is allocated for this window, the infop->wx_dbuf.WID field should be updated with this new value and the infop->wx_dbuf.UNIQUE flag should be set to 1 to indicate that this is a unique window id. See Chapter 5, "Multiple Plane Group Interface" for more information.

The wx_dbuf structure contains a device-specific field, wx_dbuf->device, that can be used by the device to communicate information between the server and the client. In the wx_dbuf structure, this is declared as:

union { char pad[128];} device

Each device can cast this to its own structure and communicate information to the client.

infop->w_refresh_period should be set equal to the refresh period of the monitor in milliseconds. This information is required by client-side DGA code. If this value is not supplied (set to zero), the client-side code defaults to a 66Hz monitor.

ReturnsWidSetup	1 on success; 0 on failure.
int
Purpose	This function is called when an application requests a block of window ids to be grabbed. The allocation of window ids is device specific and should be handled by this routine.
Results	On MPG devices, the window might need to be reprepared after new window ids are allocated. This routine should take care of the repreparation as well.
Arguments	This routine should update information in the DGA shared page pertaining to window ids:

infop->w_number_wids should be set equal to the number of contiguous wids, num_wids that have been allocated. If the device was not able to allocate the requested number of contiguous wids, this function should return 0 for failure.

infop->w_start_wid should be set equal to the value of the first WID in the newly allocated block. The base WID should be aligned on a power-of-two boundary.

infop->w_wid should be set equal to the current WID of the window. This is often equal to infop->w_start_wid.

If the window has been allocated a new window id, this function is responsible for repreparing the window with this WID value. See Chapter 5, "Multiple Plane Group Interface" for details on how to do this.

ReturnsFcsSetup	1 on success; 0 on failure.
int
Purpose	This function is called when an application requests a number of fast clear planes, num_fcs, to be grabbed for a window, pWin. The allocation of fcs planes is device-specific and should be handled by this routine.

On MPG devices, allocation of FCS planes may require repreparation of the window. This function is responsible for repreparation. See Chapter 5, "Multiple Plane Group Interface" for more details about accessing the MPG information.

Arguments	This routine should update the information in the DGA shared page pertaining to fast clear planes. Information about a window's fast clear planes is stored in the device-specific portion of the wx_dbuf structure found in the WXINFO structure infop->wx_dbuf.device. This structure can be cast to a device-defined structure and the fcs information could be stored here.
Returns	1 on success; 0 on failure.

ZbufSetup

int (*ZbufSetup)(WindowPtr pWin, int zbuf_type, WXINFO *infop)

Purpose	This function is called when an application requests direct access to the Zbuffer for a window, pWin. This is a device-specific operation and should be handled by this routine.
Arguments	This routine should update the device-specific information in the DGA shared page pertaining to Zbuffer. A device may support various types of Z buffers and the second argument, zbuf_type, indicates which type of Zbuffer is being requested. Each device may support different types of Z buffers.

Information about a window's Zbuffer is stored in the device-specific portion of the wx_dbuf structure found in the WXINFO structure infop->wx_dbuf.device.

This array can be cast to a device-defined structure and the Zbuffer information could be stored here. On MPG devices, allocation of Zbuffer may require repreparation of the window. This function is responsible for repreparation. Please see Chapter 5, "Multiple Plane Group Interface" for more details about accessing the MPG information.

ReturnsStereoSetup	1 on success; 0 on failure.
int
Purpose	This function is called when an application requests that a stereo mode be associated or disassociated with this window, pWin.

Arguments..If the second argument, st_mode is a nonzero value, a stereo mode is associated with the window and if it is equal to zero, stereo mode is turned off. This is device-specific and should be handled by this routine.

This routine should update the device-dependent information in the DGA shared page pertaining to stereo.

Information about a window's stereo state is stored in the device-specific portion of the wx_dbuf structure found in the WXINFO structure infop->wx_dbuf.device.

This array can be cast to a device-defined structure and the stereo information could be stored here.

ReturnsChokeFb	1 on success; 0 on failure.
int
Purpose	When all windows on a screen are locked down, frame buffers having asynchronous accelerators need to choke the accelerator. This prevents the accelerator from rendering into a locked window. Since this is a device-specific operation, this function has to implement the choking and unchoking.
Arguments	If the second argument, flag, is 1, this function should choke the accelerator; if flag is 0, it should unchoke the accelerator. Typically, this is done via an ioctl. For example, the GT uses the FBIOGRABHW ioctl to choke its accelerator.
Returns	1 on success; 0 on failure.

SyncDrawable

int (*SyncDrawable)(DrawablePtr pDraw, GCPtr pGC)

Purpose....When DGA is used to switch buffers, all X rendering functions need to be directed at the currently displayed buffer. This function is called before calling the X rendering function but only if the window is multibuffered.

This routine can also be used to update device-private structures with the current buffer state.

ResultsUnsyncDrawable	This function might need to call dgaMbGetBufferInfo to get the current buffer configuration.
int
Purpose	This function should undo anything that was done in

                  SyncDrawable.

This routine can also be used to update device private structures with the current buffer state.

Results....This function may need to call dgaMbGetBufferInfo to get the current buffer configuration.

CmapSetup

int (*CmapSetup)(CmapPtr pCmap, Grabbedcmap cginfop)

Purpose	This function is called when a colormap is being grabbed. The include file that provides definition of the Grabbedcmap structure is dga/dgacmapstr.h. This function is typically used by devices supporting multiple hardware colormaps or other specialized colormap hardware.
Arguments	In this routine, the DDX handlers can set up cginfo->devinfop to point to a private data area. The maximum size of this private area is DGA_CM_DEV_INFO_SZ, defined in dga/dgacmapstr.h. This field is declared as an u_char array.

Each DDX handler can cast this to a device-private structure. Typically, this device-dependent structure contains information about the hardware colormap associated with the grabbed X colormap.

On the client side, the client program can gain access to this data by using the appropriate libdga function call, dga_cm_get_devinfo. See Chapter 9, "Multibuffering Extension to X Interface" for more information.

Devices that do not have specialized colormap hardware, like multiple hardware color look up tables, do not need to fill out this element in the function vector, DgaDevFuncsDraw.

Returns....The return value is ignored.

Server-Supplied Multibuffering Routines

If your DDX handler defines a non-NULL MBX TryMpg function, you are required to use the following routines to inform DGA of multibuffer set attributes of a multibuffered window. If your DDX handler does not define TryMpg, you do not need to make these calls.

To use these routines, include the dgambufstr.h header file.

dgaMbCrtSetInfo

int dgaMbCrtSetInfo (pWin, flipMode, accessMode, siteTypeConst bufViewabilityMask) WindowPtr pWin; int flipMode; int accessMode; Bool siteTypeConst; unsigned long bufViewabilityMask

Purpose	This function informs DGA of the attributes of the multibuffer set of a multibuffered window. Nonzero is returned if the information was successfully associated with the window, zero otherwise.
Called by	The MBX TryMpg routine. If the device driver does not call this routine, the following defaults will apply:
flipMode	DGA_MBFLIP_COPY
accessMode	DGA_MBACCESS_MULTIADDR
siteTypeConst	FALSE
bufViewableMask	0 (all nonviewable)
Arguments	flipMode specifies the method used to display multibuffers. It may be one of:

DGA_MBFLIP_VIDEO -- use this if multibuffers are displayed by copying their contents into a viewable drawable

DGA_MBFLIP_COPY -- use this if they are displayed by directly outputting a video single from the multibuffer

accessMode specifies how a foundation library client can access the multibuffers. It may be one of:

DGA_MBACCESS_SINGLEADDR -- specifies single address access mode. In this mode, clients use a single address and a render buffer state in the device to specify the rendering destination

DGA_MBACCESS_MULTIADDR -- specifies multiple address mode. In this mode, clients use a unique address for each buffer to specify the rendering destination

siteTypeConst is TRUE if the sites of the multibuffers in the multibuffer set will never change during the lifetime of the set, and FALSE otherwise.

bufViewableMask is a bit mask in which the bits specify the viewability of all multibuffers in the multibuffer set. The viewability of multibuffer i is specified by (1L<<i) in the mask. 1 means the multibuffer is viewable (video can be sent directly out of it). 0 means the multibuffer is nonviewable (the multibuffer must be copied to a viewable drawable to be seen).

dgaMbSetBufViewability

int dgaMbSetBufViewability (pWin, bufIndex, viewable) WindowPtr pWin; short bufIndex; Bool viewable;

Purpose	This function is used to specify the viewability of an individual buffer.
Called by	The MBX ResizeMultibuffer routine if resizing causes a change in the viewability of a multibuffer.
Arguments	bufIndex is the index of the multibuffer in the multibuffer set (counted from 0).

If viewable is TRUE, the multibuffer is viewable, otherwise it is nonviewable.

Returns....Nonzero if the information was successfully associated with the window; zero otherwise.

dgaMbSetDisplayBuf

void dgaMbSetDisplayBuf (pWin, bufIndex) WindowPtr pWin; short bufIndex;

Purpose	This function specifies the current display buffer of a multibuffered window. This routine must be called only after a creation sequence has been successfully completed on the window. The initial display buffer is 0.
Called bydgaMbIsMultibuffer	DisplayMultibuffer, if the DDX handler defines a non-NULL DisplayMultibuffer.
Bool
Returns	TRUE if the given pixmap is actually a pixmap that was created through the MBX extension. In other words, returns TRUE if it is a multibuffer. Otherwise returns FALSE. Regardless of the drawable type, the drawable must have been previously grabbed. Otherwise returns FALSE.

If TRUE is returned, a pointer to the main window of the multibuffer is also returned.

---

Note - The DGA cache notification routines (see "Caching Routines" on page 226) use this routine to distinguish multibuffers from pixmaps.

---

---

Note - This should be implemented by adding a field to the DgaPixmapRec. This field has three states: pixmap, multibuffer, or don't know. If pixmap or multibuffer, return FALSE or TRUE respectively. If don't know, do a

LookupIdByType on pPix->drawable.id with type MultibufferResType. If this succeeds, it's a multibuffer. If not, it's a pixmap. Record the result in the DgaPixmapRec and return it.

---

dgaMbGetBufferInfo

void dgaMbGetBufferInfo (pDraw, num_buffers, read_buffer, write_buffer, display_buffer) DrawablePtr pDraw; short *num_buffers; short *read_buffer; short *write_buffer; short *display_buffer;

Returns	Information about the current buffer set.
Called by	The DGA routines, SyncDrawable and UnsyncDrawable.

Caching Routines

The following routines allow a DDX handler to keep DGA informed of caching changes on a device.

dgaCacheDescribeDev

void DgaCacheDescribeDev (pScreen, devCode, devName) ScreenPtr pScreen; int devCode; char *devName;

Results....The contents of devName are copied into an internal structure.

dgaCacheStateChange

void DgaCacheStateChange (pDraw, state) DrawablePtr pDraw; Bool state;

Purpose	Informs DGA that a change has occurred to the cache state of a drawable. DgaCacheDescribeDev must have been called prior to calling this routine.
ArgumentsdgaSharedDataInfo	If state is TRUE, the drawable is currently cached. If it is FALSE, the drawable is not cached.
void
Purpose	When a nonviewable drawable or backing store is not cached, the data pointer of the drawable should be directed toward the pixel store that exists in the shared page and the contents of the drawable should be copied into the shared page. This is automatically performed by DGA if the DGA routines CacheDrawInit or CacheDrawCleanup return 0. However, the DDX handler itself may want to copy the drawable contents into the shared page (for performance). To do this, the DDX handler must know where to put the data. It must also know the scanline stride (linebytes). This routine supplies the necessary information necessary. This routine should only be called when the drawable has been grabbed.

Device Information Routines

In each shared information page of a drawable, DGA provides an area in which a DDX handler can place device-specific information. When anything in this area changes, the DDX handler must inform DGA so that it can signal the change to the client.

dgaDevInfoGet

pointer DgaDevInfoGet (pDraw) DrawablePtr pDraw;

Purpose	The device-dependent area can be used by DDX handlers to transmit device-dependent information to the DDX handlers of the client foundation libraries. The format of this area is completely opaque to DGA; no interpretation is given.
Called by	This routine might need to be called from a DDX handler's DGA GrabDrawable routine to initialize device-dependent information for a drawable. It might also need to be called for a cached nonviewable drawable if the DDX handler changes the location of the cache.
Results	If the device alters any information in this area, it should call DgaDevInfoChange to inform DGA.
Returns	A pointer to the device-dependent area in the shared information of the given drawable. Returns NULL if the drawable has not yet been grabbed.

dgaDevInfoChange

void DgaDevInfoChange (pDraw) DrawablePtr pDraw;

Purpose....This routine informs DGA that a change has occurred to the device-dependent area of the drawable. A pointer to this area is returned by calling DgaCacheDevInfo. This routine must be called after any DDX handler changes to this area.

DGA and Colormaps

The colormap grabber is discussed in "Colormap Grabber Interface" on page 188. It allows DGA foundation libraries to directly load color lookup tables, bypassing the X protocol. This functionality is not required for Solaris to operate properly. The implementation of DGA libraries handles the case where colormap grabs fail and fall back to Xlib to load the lookup tables. The performance loss is minimal.

The implementation of the colormap grabber uses interfaces which are private to the CMAP pacakage and DGA. By default, the colormap grabber is disabled for each screen. It is enabled when the handler for a given screen calls cmapScreenInit() to initialize the CMAP package for that screen.

If the DDX handler implementor chooses to disable the colormap grabber on a device that is using the CMAP package, the handler should call the function dgaDisableCmapGrabs(ScreenPtr) after the call to cmapScreenInit().

---

Note - Ideally, the DGA implementation should check the return value from the screen's CmapSetup function to disable and enable grabs, but unfortunately, it does not. This cannot be changed without breaking binary compatibility.

---