Getting Started

This section describes the basic instructions for using Direct Xlib on an application-by-application basis. These instructions assume that your application is explicitly dynamically linked to libX11. If your application is statically linked to libX11, loads libX11 by invoking dlopen, or if you are not sure, see "Determining How Applications Have Been Linked" on page 22.

General Setup

By default, Direct Xlib places shared memory files in /tmp. Therefore, you may need more swap space than normally required when using Direct Xlib. This is especially true if you use a large number of 16-bit fonts.

You can set a different path for Direct Xlib to use for shared memory with the following command when starting OpenWindows. To do this, replace /home/mymachine with any path with plenty of disk space where you have write permission:

It is only necessary to use the -sharedretainedpath option with Direct Xlib if you have limited space in /tmp.

If you are upgrading from Direct Xlib 2.0 and used the -sharedretainedpath path option, you should remove all files in the specified directory. The shared font mechanism has changed between Direct Xlib 2.0 and 3.x. Old shared font files created through use of Direct Xlib 2.0 will not work correctly with Direct Xlib 3.2

Invoking Direct Xlib 3.2

In this section, /mydir refers to the directory where you installed Direct Xlib. With the standard installation, this directory is /opt. Substitute the directory path on your machine that points to the location of Direct Xlib.

1. Make sure you are running OpenWindows Version 3.5 or later software.

2. In a Shell Tool or Command Tool, enter the following to start a single application using Direct Xlib.

where myapp is the name of the application you want to start. Follow the application name with the command-line arguments, if any, you would normally use when starting that application.

Remember that when you activate Direct Xlib in this manner, it is only active for the single application started with the dxlib script. You must execute the dxlib script with each application you want to use with Direct Xlib. If you want your entire desktop to use Direct Xlib, see "Using Direct Xlib on Your Entire Desktop" on page 20.

---

Note - The LD_LIBRARY_PATH environment variable should already be set to $OPENWINHOME/lib before executing the above command where $OPENWINHOME is set to /usr/openwin under SunOS5.x.

---

You may want to display general information about how to use the Direct Xlib software and its current status. To do this, enter dxlib with no application name, as shown in the following example:

---

Note - The release number in the following example corresponds to the major MIT release from which this version of the Direct Xlib software was derived. The version number is the version of the Direct Xlib software.

---

If your environment is not correctly set up to use Direct Xlib when you use the dxlib script, the software returns an error message. Refer to "Usage Notes" on page 21.

Using Direct Xlib on Your Entire Desktop

This section describes how to use Direct Xlib on your entire desktop.

1. Add the following lines in your .xinitrc file just before you start your window manager (olwm in the default case):

---

Note - The LD_LIBRARY_PATH environment variable should already be set to $OPENWINHOME/lib before executing the following command where $OPENWINHOME is set to /usr/openwin under SunOS5.x.

---

LD_LIBRARY_PATH=/mydir/SUNWdxlib/lib/dxlib/SunOS5.x:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH

where /mydir is /opt in the default case. If no .xinitrc file exists in your home directory

a. Copy $OPENWINHOME/lib/Xinitrc to .xinitrc in your home directory.

b. Edit the file, and add the above lines just before the following line:

  if [ "$OW_WINDOW_MANAGER" ]; then  #Alternate Window Manager

If $OPENWINHOME is not equal to /usr/openwin, then modify the LD_LIBRARY_PATH to include $OPENWINHOME/server/lib as shown below:

2. Start the OpenWindows server as you would normally.

Now, after starting the OpenWindows server, if you enter

env

the following appears in front of your old LD_LIBRARY_PATH:

/mydir/SUNWdxlib/lib/dxlib/SunOS5.x

or

/mydir/SUNWdxlib/lib/dxlib/SunOS5.x:$OPENWINHOME/server/lib

Leave your LD_LIBRARY_PATH set to this as long as you want Direct Xlib to be automatically used for dynamically linked applications when you start them from shells within the OpenWindows software or from the desktop menu. You can disable Direct Xlib for particular applications by setting the DIRECTX_DISABLE environment variable to any non-zero value before starting the application as discussed in "Setting Environment Variables" on page 27.

---

Note - DO NOT SET LD_LIBRARY_PATH environment variable in your .cshrc to include /mydir/SUNWdxlib/lib/dxlib/SunOS5.x. If you do, you will not be able to run OpenWindows.

---

If you update your LD_LIBRARY_PATH in your .cshrc, then Direct Xlib will not be enabled when you run Xlib applications from within a shell. You will have to explicitly run /opt/SUNWdxlib/bin/dxlib myapp (your Xlib application), or update your .cshrc file and remove references to LD_LIBRARY_PATH.

Usage Notes

This section contains detailed information on using Direct Xlib. Unless you encounter problems when using Direct Xlib, or plan to develop applications using it, you may wish to skip this section and the more detailed sections that follow.

Server Connections

The following message may appear while running Direct Xlib:

If this message appears, you need to shutdown some of your Direct Xlib applications before you can again connect to the server. Direct Xlib consumes server connection resources more quickly than standard Xlib.

Frame Buffers

Direct Xlib usage on devices that do not have hardware cursor support is not recommended. The Cursor image data may corrupt underlying window data. These devices include CG3, CG8, and the onboard frame buffer for the SPARCStation 4.

On GX, GXplus, TurboGX, Turbo GXplus, SX, ZX and TurboZX frame buffers, Direct Xlib forces the cursor to fit in the hardware cursor, which is only 32 by 32 pixels. Therefore, when running Direct Xlib on this type of frame buffer, you may notice that drag and drop cursors may not display completely.

Font Performance

Direct Xlib cannot detect fixed width fonts that can normally be accelerated within the X server. Due to this limitation, applications that are dominated by fixed width fonts may have their performance reduced rather than improved through Direct Xlib usage. Applications that mix fixed width fonts with non- fixed width fonts or other operations should not be greatly impacted by this problem.

Determining How Applications Have Been Linked

Applications already dynamically linked to libX11 automatically start using the Direct Xlib software when it is enabled. An application that is statically linked to libX11 needs relinking to take advantage of Direct Xlib.

---

Note - Direct Xlib does not support statically linked Xlib applications.

---

You can determine whether an application is statically or dynamically linked to libX11. To do this, enter ldd myapp at your prompt, and press Return. The following appears:

If after using ldd, you see that libX11 is one of the libraries listed, then this application is dynamically linked to Xlib. If libX11 is not listed, then either the application does not use Xlib, calls dlopen to load Xlib, or it is statically linked to Xlib.

dxlib Script

If the dxlib script is run with no application name and it displays the message "Direct Xlib is not active," the Direct Xlib software has probably not been correctly installed on your system. See Chapter 2, "Installing the Direct Xlib Software," for more details. When Direct Xlib is run on dumb frame buffers, this message states that Direct Xlib is active but will not do direct rendering. It does not perform any direct rendering on these frame buffers, but continues to send X11 requests to the OpenWindows server as standard Xlib does.

For more specific information about the state of Direct Xlib, including the state of the environment variables that you can use to control it (explained in "Setting Environment Variables" on page 27), enter the following:

mydir refers to the directory where you installed Direct Xlib.

If the dxlib script cannot find Direct Xlib, a message to that effect appears. It suggests that you set the DXLIBHOME environment variable to the correct location. This usually only happens if the dxlib script has been moved after installation.

You can still use the script from this location if you set the DXLIBHOME environment variable to the directory path containing Direct Xlib.

To do so on an application-by-application basis, set the DXLIBHOME environment variable to where Direct Xlib is located before using the dxlib script. For example, if you have installed Direct Xlib in /home/mydxlib, enter the following:

To get status information on Direct Xlib, enter the following:

Developer Notes

This section covers topics specific to developers using Direct Xlib. Direct Xlib gives your application process direct access to system hardware that you did not previously have when using the X11 API. Because of this, errors in applications that accidentally corrupt system memory can have more severe effects on the system than before. In particular, accidentally writing to graphics accelerator hardware registers can cause system crashes. This is, however, a highly unlikely event for well-behaved applications.

General Application Compiling with Direct Xlib

When compiling X11 applications, continue to use the standard include/X11 header files. You only need to use the header files supplied with Direct Xlib under the following conditions:

• If you are developing your own X extension libraries
• If your application code directly manipulates the Xlib X11 request buffer pointed to by the Display pointer
• If it modifies pixels in X11 drawables in a manner unknown to Xlib

If any of these conditions exist, you should contact the Sun Microsystems Computer Corporation (SMCC) US Answer Center at (800) 872-4786 for further assistance on developing your code using Direct Xlib.

If you are currently dynamically linked to libX11, continue to link to the standard libX11 libraries. Linking dynamically to Direct Xlib causes your executable to reference libraries that may not be available through standard libX11. This makes it more difficult to move between standard libX11 and the Direct Xlib software.

If you are statically linked to libX11 and want to use Direct Xlib, you will have to dynamically link to libX11. Direct Xlib no longer supplies static versions of its libraries.

If your application library both uses and is statically linked to libXext, you must dynamically link to libXext.

Direct Xlib Errors

Direct Xlib may not report as many X11 error conditions as standard X11. This is especially apparent when applications attempt to send numeric information out of the acceptable range. For this reason, do primary application development with standard libX11, and use Direct Xlib after application code is considered to be relatively bug free.

Supporting Your Own X11 Extensions with Direct Xlib

Normal X11 applications do not need to perform any of the operations discussed in this section; only developers of applications or X11 extensions that reach below the X11 API or attempt to extend it need to pay attention to this section. If your application directly manipulates the Xlib X11 request buffer or if you are developing your own X extension libraries, you need to adhere to the following rules when using your application or extension with Direct Xlib.

Your application and/or extension must be compiled with the Xlibint.h header file from OpenWindows 3.5.

In addition, you need to synchronize your Xlib request buffer manipulation and any pixel modifications performed by your extension but unknown to Xlib with Direct Xlib by using additional macros. For more information on how to develop applications or extensions that reach below the Xlib API, contact Sun Microsystems Computer Corporation (SMCC).

Setting Environment Variables

The following environment variables control memory usage and allow portions of Direct Xlib to be disabled.

DIRECTX_MIN_WIN_WIDTH                 Limits the number of file descriptors

DIRECTX_MIN_WIN_HEIGHT...by specifying a minimum window size below which the Direct Xlib software will not attempt direct access for that window. They default to 96 and 64 respectively.

DIRECTX_FONT_MEMORY_LIMIT             Turns shared fonts on or off.

DIRECTX_DISABLE                       Disables Direct Xlib functionality.

Use the following to determine the current values of the above environment variables:

/opt/SUNWdxlib/bin/dxlib /opt/SUNWdxlib/bin/dxlib_status -v

Direct Xlib Demonstration Programs

Direct Xlib provides three demonstration programs. pointfish, DXspeed, and xspheres illustrate the performance of Direct Xlib.

These programs are installed in the following subdirectory:

/mydir/SUNWdxlib/demo/bin

DXspeed and pointfish depend upon images that are part of the OpenWindows packages. The particular packages, SUNWoldim and SUNWxwdim, are not installed by default. They are only installed if the entire Solaris 2.5 software distribution is installed. You will have to install this package to use DXspeed and pointfish to their fullest capabilities.

In the following examples, /mydir refers to the directory where you installed Direct Xlib. With the standard installation, this directory is /opt.

1. Make sure the OpenWindows Version 3.5 software is running as described previously.

2. In a Shell Tool or Command Tool, enter the following commands to start the demonstration programs.

pointfish

The pointfish program uses XDrawPoints to draw an aquarium background with many fish. The background and the fish are sorted by color. To run this program, enter the following:

The -t option to pointfish gives a points-per-second measure. To compare the performance, run the pointfish demonstration program without the Direct Xlib software.

DXspeed

The DXspeed program demonstrates the performance of the Direct Xlib software using XPutImage, XCopyArea, XDrawLines, XDrawSegments, XFillPolygon, and XDrawPoints. DXspeed uses four fish and the mandrill baboon for the image and area tests. For vectors, polygons, and points, DXspeed allows you to pick from four different math functions. These math functions generate a 125x125 matrix with a depth associated at each vertex. To run this program, enter the following:

To compare the performance, try running the DXspeed demonstration without the Direct Xlib software.

xspheres

The xspheres program demonstrates the performance of the Direct Xlib software using XPutImage and XCopyArea.To run this program, enter the following:

An xspheres manpage is available in the /demo/bin directory which explains its use. Source code is also available as a compressed tar file. Read the xspheres.man man page for usage instructions. xspheres runs fastest on frame buffers with offscreen pixmap memory.