New Features and Changes

Debug Server Modules

The server includes source files for debugging in the SUNWxwdes (SPARC), SUNWxwdex (x86), and SUNWxwdep (PPC) packages. See Chapter 14, "Debug Server Modules," for more information.

New DGA Overlay Interface

The client DGA interface now supports direct access to windows in overlay planes. The following are new DGA API functions:

• dga_draw_ovlstatechg
• dga_draw_ovlstatesetnotify
• dga_draw_ovlstategetnotify
• dga_draw_ovlstate

See Chapter 10, "Direct Graphics Access Drawable Client Interface," for detailed information.

DGA Backward Compatibility

The DGA drawable interface is compatible with DGA clients written with the window grabber interface in OpenWindows 3.4. Some of the routines described in the drawable interface are new, and some are reworked from last release. The DGA routines from the previous release are still supported. Specifically, the following interfaces are still provided:

• Colormap Grabber
• Miscellaneous Grabber
• Window Grabber

  This includes direct access window functions, cursor grabber functions, and retained window grabber functions.

• Multibuffer Grabber

---

Note - The window grabber and the multibuffer grabber interfaces are being phased out--they will be removed in a future release. Any new DDX handlers and clients should avoid using these interfaces; instead use the DGA drawable interface.

---

Window Grabber Supported Functions

Existing clients that use the older Window Grabber interface (XDgaGrabWindow) will continue to work with some types of windows. It is strongly recommended that you convert your client to use the new DGA drawable interface to directly access the newly supported drawable types and new DGA features.

The following Window Grabber routines are supported in this release:

• XDgaGrabWindow
• XDgaUnGrabWindow
• dga_win_grab
• dga_win_ungrab
• dga_win_fbname
• dga_win_devfd
• DGA_WIN_LOCK
• DGA_WIN_UNLOCK

• DGA_WIN_MODIF
• dga_win_clipchg
• dga_win_bbox
• dga_win_singlerect
• dga_win_empty
• dga_win_obscured
• dga_win_depth
• dga_win_borderwidth
• dga_win_set_client_infop
• dga_win_get_client_infop
• dga_win_clipinfo
• dga_win_cursactive
• dga_win_curschg
• dga_win_cursupdate
• dga_rtn_grab
• dga_rtn_ungrab
• dga_win_rtnchg
• dga_rtn_active
• dga_rtn_cached
• dga_rtn_devinfop
• dga_rtn_devtype
• dga_rtn_dimensions
• dga_rtn_pixels
• dga_db_grab
• dga_db_ungrab
• dga_db_display
• dga_db_interval
• dga_db_interval_check
• dga_db_display_done
• dga_db_write
• dga_db_read
• dga_db_write_inquire
• dga_db_read_inquire
• dga_db_display_inquire
• dga_win_dbinfop

---

Note - Do not use the window grabber interface with the new DGA drawable interface in the same application.

---

---

Note - Use the DGA drawable interface to grab multibuffered windows with the MBX extension. Do not use the window grabber interface to grab these windows; it is not guaranteed to work properly with multibuffer windows whether the window becomes multibuffered through MBX before or after it is grabbed.

---

Multibuffer Grabber Supported Functions

XGL Compatibility Interface

XGL provides a buffer control interface independent of MBX. It allows its clients to create multibuffers on a window and to switch the display of these buffers. The following routines are provided so that XGL can continue to provide this functionality. This interface, however, is deprecated; it will be removed in a future release. XGL is the only client that should use these routines.

Each one of these routines corresponds to an existing DGA buffer interface dga_db_xxx routine with the same suffix. Refer to the DGA client interface documentation on the dga_db_xxx routines for a complete description of the routine arguments and semantics.

Use these routines only with windows (that is, not pixmaps or multibuffered windows) and only when the window is locked.

• dga_draw_db_grab
• dga_draw_db_ungrab
• dga_draw_db_write
• dga_draw_db_read
• dga_draw_db_interval
• dga_draw_db_display
• dga_draw_db_interval_wait
• dga_draw_db_interval_check
• dga_draw_db_display_done
• dga_draw_db_write_inquire
• dga_draw_db_read_inquire
• dga_draw_db_display_inquire
• dga_draw_db_dbinfop

GPI Compatibility

The new DGA drawable interface is compatible with older DDX handlers that only support window grabbing. The old DGA screen initialization function, DgaDevFuncsInit, is still supported.

The new call, dgaScreenInit initializes DGA on the screen the same way as DgaDevFuncsInit (see "Initializing Drawable Grabs" on page 209). In addition to window grabbing, this provides support for pixmap and multibuffer grabbing.

---

Note - DgaDevFuncsInit and dgaScreenInit are mutually exclusive; a DDX handler should call only one of these.

---

Combining Client Interfaces

Client-Side Issues

An application can allow its window(s) to be directly accessed through the new DGA drawable client interface, as well as through the DGA window grabber interface. Only the drawable client interface can be used to grab pixmaps or multibuffered (MBX) windows.

The purpose of mixing new and old features is to enable applications to combine the use of graphics libraries with different revision levels, some using the old interface and some using the new interface. Individual libraries, like XGL, must only use one of these interfaces; it cannot mix functions from the old interface with functions from the new interface. It is strongly recommended that new applications or clients use the new drawable interface.

Server-Side Issues

The device-dependent DGA screen function used is determined by which screen initialization routine your DDX handler calls. Your DDX handler can call either the new screen initialization routine (dgaScreenInit) or the old routine (DgaDevFuncsInit).

---

Note - New DDX handlers should use dgaScreenInit.

---

If your DDX handler uses the old routine, DgaDevFuncsInit, only windows can still be directly accessed through the drawable interface, as well as the window grabber interface--pixmap and multibuffered windows cannot be grabbed.

DDX handlers that use dgaScreenInit, can access windows, pixmaps and multibuffered windows with the new DGA drawable interface.

Direct Pixel Access Interface

Direct pixel access (DPA) interface enables the window server to directly manipulate pixels in drawables that you control in your DDX handler. The Display PostScript (DPS) extension uses DPA to improve compositing performance.

Performance Enhancements

If you NFS mount the window server, mount it setuid allowable. This enables the server to take advantage of performance features in the Solaris operating system.

x86 In-line Assembly Language Note

The SunPro^(TM) C Compilation system includes in-line assembly language provides direct access to x86 I/O instructions, as well as optimized in-line expansion templates. See the manual pages for cc(1) and inline(1), and SunPro's ProCompiler C 2.0.1 Programmer's Guide for more information.

If you want to include in-line assembly language in your code, place the in-line assembly definition file (with the .il extension) first in the cc command line:

cc -O inline.il bitblt.c

Common in-line examples are included in the file below.

/////////////////////////////////////////////////////////////// / File: inline.il / ///////////////////////////////////////////////////////////////

/ in and out / int ioaddr = 0x3c4; / / Called as: / char data; / data = inb(ioaddr); / .inline inb,4 movl (%esp), %edx xorl %eax, %eax inb (%dx) .end / Called as: / short data; / data = inw(ioaddr); / .inline inw,4 movl (%esp), %edx xorl %eax, %eax inw (%dx) .end / Called as: / int data; / data = inl(ioaddr); / .inline inl,4 movl (%esp), %edx xorl %eax, %eax inl (%dx) .end / Called as: / char data; / outb(ioaddr,data); / .inline outb,8 movl (%esp), %edx movl 4(%esp), %eax outb (%dx) .end / Called as: / short data;

/ outw(ioaddr,data); / .inline outw,8 movl (%esp), %edx movl 4(%esp), %eax outw (%dx) .end / Called as: / int data; / outl(ioaddr,data); / .inline outl,8 movl (%esp), %edx movl 4(%esp), %eax outl (%dx) .end /////////////////////////////////////////////////////////////// / Set and clear direction flags / / Called as: cld(); / .inline cld,0 cld .end / Called as: std(); / .inline std,0 std .end

DPS Extension Graphics Rendering

Due to a bug in this release of the DPS code, pixmaps used by DPS must have their pPixmap->devKind field equal to the width of the pixmap in bytes. This means that frame buffers that cache pixmaps in off-screen video memory need to use regular memory under certain conditions.

A flag has been added to inform DDX handlers when they should force pixmaps into regular memory. Make the following declaration in your DDX handler's pScreen->CreatePixmap routine:

extern int sunCreateDFBPixmap

Check this variable before creating a pixmap in off-screen memory. If the variable is TRUE, your DDX handler should force the pixmap into regular processor memory.

---

Note - This DPS bug workaround is unchanged from OpenWindows 3.4.

---

Test/Verify Recommendation

To test and verify a DDX handler, it is recommended that you run the UniSoft Test Suite. This test suite is available from the X Consortium.

You can access X Consortium information if your system is connected to the Internet. The UniSoft Test Suite information resides in the /pub/XTEST directory on the ftp.x.org machine. Use the File Transfer Protocol (ftp) to download files from this system. If you need help using ftp, refer to the ftp(1) man page. To determine if your system is connected to the Internet, see your system administrator.