New Features and Changes

New Overlay GPI Interface

A new interface, the Overlay GPI (Graphics Programming Interface), was added to this release for overlay window manipulation and rendering transparent pixels into overlay windows.

See the new chapter, Chapter 6, "Overlay Window Interface" for detailed information.

DGA Interface

The DGA interface has been reworked this release. It is now called the DGA drawable interface (instead of the DGA window grabber interface in the previous release). The DGA drawable interface includes:

• New features (see "New DGA Features" on page xxiv)
• Some minor changes (see "Changes to the DGA Interface" on page xxiv)
• Colormap grabber
• Miscellaneous grabbers

See Chapter 10, "Direct Graphics Access Drawable Client Interface" and Chapter 11, "Direct Graphics Access Drawable DDX Interface" for complete descriptions of all routines in the DGA drawable interface. These two chapters are new chapters--they are total rewrites of the two DGA chapters in OpenWindows 3.3.

New DGA Features

The DGA drawable interface provides the following new features:

• Direct access to pixmaps, both cached and uncached.
• Direct access to MBX buffers. Both viewable (on screen) and nonviewable (off screen) buffer types are supported. Nonviewable buffers can reside in system memory or be cached in device memory.
• Window and buffer aliasing, as defined by the MBX extension, to allow clients to directly render to a window's display buffer.

Changes to the DGA Interface

Some changes to the DGA interface simplify client-side programming for:

• Grabbing and ungrabbing a drawable

  Only one routine is necessary, as opposed to two for each operation that were previously required.

• Removing the cursor
• dbinfo, the structure defined in dga.h, has been renamed to devinfo.

  This structure is useful for all device-dependent information, not just double-buffering data.

Backward Compatibility

The DGA drawable interface is compatible with DGA clients written with the window grabber interface in OpenWindows 3.3. 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 201). 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.

OWconfig File Format Enhancements

The following changes were made to the OWconfig file to make per-screen configurations available:

• A new class, XSCREENCONFIG, was added
• New attributes were added to the XDISPLAY class

These changes are backward compatible with the previous release of the OpenWindows server (Version 3.3).

See Appendix A, "The OWconfig File" for detailed information on the OWconfig file.

OWconfig Access Method

The OWconfig Access Method standardizes access to and manipulation of an OpenWindows configuration (OWconfig) database file. If your DDX handler requires configuration information, use this method to access that information specific to your device.

See Appendix A, "The OWconfig File" for more information.

New Debug Server

This release now has a version of the server for debugging purposes. The server is included in the SUNWxwdes (SPARC) and SUNWxwdex (x86) packages. Use the debug server with dbx(1).

The debug server uses several dynamically linked libraries. It is important that these libraries not be substituted for the similar libraries on the distribution CD. The correct debug libraries have _d appended to their filename and exist only in the DDK hierarchy. Set the load library path to the following so that the debug server uses the correct debug libraries:

example% setenv LD_LIBRARY_PATH /usr/openwin/lib:/opt/SUNWddk/ddk_2.4/xserver/bin/sparc

Then you can use the debug server:

example% cd /opt/SUNWddk/ddk_2.4/xserver/bin/sparc example% dbx Xsun-ddkdebug

The source code for some of the dynamic libraries is also in the DDK distribution. Use dbx's file and use commands to step through the dynamic code.

(dbx) stop in miSpritePolyFillRect (dbx) cont stopped in miSpritePolyFillRect at 0xeec15e60 miSpritePolyFillRect+0x2c: ld [%fp + 68], %o0 warning: can't find source /export/ddk/ea2/bin/Xsun/mit/server/ddx/mi/misprite.c (dbx) use /opt/SUNWddk/ddk_2.4/xserver/server/ddx/mi (dbx) file misprite.c

Now you can step through the code examining values as necessary.

---

x86 - This does not work on x86 because the -xs compiler switch is not supported. However, you can still print out the arguments to functions.

---

As a device driver developer, you are most likely interested in the initialization stage of your driver. However, since the server loads your driver dynamically, its symbols are not available to you at startup time. You can stop the server before device initialization in the AddScreen function. This function contains the address of which it is going to switch to initialize the framebuffer device.

(dbx) stop in AddScreen (dbx) run AddScreen(pfnInit = &xxxxxxInit () at 0xef7628a4, argc = 1, argv = 0xeffffaac) at 0x51f50

The pfnInit function pointer should point to your device driver's initialization function. Now that your dynamic library has been loaded, you can set breakpoints and step through your code in dbx.

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

---

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 MIT X Consortium.

You can access MIT X Consortium information if your system is connected to Internet. The UniSoft Test Suite information resides in the /pub/XTEST directory on the ftp.x.org machine. Use the File Transfer Program (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 Internet, see your system administrator.