🚀 go-pugleaf

----------------------------------------------------------------------------
                                                        The Florida SunFlash

             Improving Performance with Direct Xlib

SunFLASH Vol 44 #32					         August 1992 
----------------------------------------------------------------------------
This article is reprinted from the STB by permission of the author.
-johnj
----------------------------------------------------------------------------

   By - Jamshed Doctor, SMCC Marketing Development Engineering

Direct Xlib is Sun Microsystems Computer Corporation's new, unbundled product
that transparently improves the rendering performance of graphics-intensive
Xlib-based applications. The improved performance depends on the application's
use and mix of graphics primitives. Applications using the standard Xlib
Application Programming Interface (API) should not have to make any changes to
their source code, because Direct Xlib presents the exact same MIT X11R4
interface.

Direct Xlib is a set of supplemental (dynamic and static) Xlib libraries for 
OpenWindows 3.0. It can be easily disabled when standard server rendering is 
desired, and can be used for either the entire window system or on an 
application-by-application basis. A dynamically linked application can use 
Direct Xlib without any recompile or relink. A statically linked application 
must relink with the static Direct Xlib library provided. Performance increase
is provided only when both the window client and the window server are on the 
same machine. Otherwise, standard Xlib is used for rendering.

Direct Xlib Implementation
--------------------------
Direct Xlib increases rendering performance by using Direct Graphics Access 
(DGA) technology to access the graphics hardware directly. It guarantees pixel 
accuracy of graphics output to be identical to that produced by OpenWindows 
by using the same rendering code as the X11/NeWS server. Most new code 
implemented for Direct Xlib is for synchronization between Direct Xlib and the 
server. Performance improvements come from eliminating the overhead 
involved in copying X11 commands and data into the X11 command buffer, 
eliminating the overhead of interprocess communication (IPC) between the 
client and the server in transferring this command buffer, and kernel process 
management overhead.

        Standard X Windows           |              Direct Xlib
                                     |
        -------------------          |          -------------------
        |   Application   |          |          |   Application   |
        -------------------          |          -------------------
        |    Xlib API     |          |          |    Xlib API     |
        -------------------          |          -------------------
                 |                   |           |               |
             X Protocol              |  -------------------      |
                 |                   |  |   Graphics HW   |  X Protocol
        -------------------          |  -------------------      |
        |    X Server     |          |                           |
        -------------------          |                  -------------------
        |   Graphics HW   |          |                  |    X Server     |
        -------------------          |                  -------------------
                                     |                  |   Graphics HW   |
                                     |                  -------------------
                                     |
                                     |
                                     |


	Figure 1	Increased Performance with Direct Xlib



Direct Xlib Performance Numbers
-------------------------------
Direct Xlib roughly doubles raw graphics performance. An application can 
typically achieve a graphics performance improvement of approximately 50%, 
due to inefficiencies in its graphics code. Most window system operations do 
not achieve a noticeable performance increase, because they are limited by 
application software overhead rather than graphics software. Enhancing 
performance of large window scrolling is limited by the hardware blit 
performance in OpenWindows 3.0. The greatest performance increase is achieved
for large numbers of short vectors, filled rectangles, short text strings, 
and small scrolls or blit operations.

Figure 2 shows the performance data from the "x11perf" benchmark, 
conducted by Direct Xlib engineering on a SPARCstation2 GX machine. It 
compares OpenWindows 3.0 X11/NeWS server with the Direct Xlib product.

      ---------------------------------------------------------------

                               DIRECT XLIB   OPEN WINDOWS 3.0   RATIO
      GRAPHICS PRIMITIVES

      Dots                       1,410,000            364,000    3.87

      Lines                        431,000            254,000    1.70

      Rectangles                   321,000            150,000    2.14

      Text                         195,000            104,000    1.88


      WINDOW OPERATIONS

      Scroll                        12,300               3010    4.09

      Copy                          12,600               2910    4.33

      PutImage                        40.9                 6.0   6.82
    
      ---------------------------------------------------------------

	Figure 2	Direct Xlib Performance Data

  o  Lines are 10 pixel randomly oriented.
  o  Rectangles are 10x10 solid.
  o  Text is Times Roman 10, 80 character unclipped polytext line.
  o  Scroll and Copy are for 10x10 pixel areas.
  o  PutImage is for 500x500 pixel areas.

Direct Xlib speeds up graphics rendering, but not general computation. 
Programs that are not graphics-intensive may see little overall performance 
gain. Direct Xlib will provide better performance for programs that are limited 
by X graphics performance. If other factors are limiting the performance of the 
program, Direct Xlib offers only minimal improvements. Non-graphics 
portions of Xlib code are not accelerated by Direct Xlib.


Direct Xlib Supported Primitives
--------------------------------
Direct Xlib accelerates the graphics primitives that are heavily used by 
graphics-intensive applications and can produce significant performance 
improvements when rendered directly by the client-side code. The rest of the 
primitives are sent to the server for graphics rendering. Even those primitives 
that are Direct Xlib-accelerated are sent to the server for rendering under 
certain conditions. Generally, these graphics primitives are accelerated 
(rendered locally) when Direct Xlib can be assured that there is no possibility 
that it will render them incorrectly or incompletely.

Direct Xlib accelerates the following primitives:

  o  XCopyArea - when Direct Xlib is sure that no graphics exposure events 
     other than a NoExpose event need to be generated

  o  XPutImage - when bit ordering, byte ordering, scanline padding, etc., 
     match the native attributes used internally within the server

  o  XSetClipRectangles - to support local clip control

  o  XSetClipMask - supported locally only when the client has local DGA 
     access to the pixmap used as a clip mask (available with future versions
     of Direct Xlib on Solaris 2.0)

  o  XDrawPoint / XDrawPoints

  o  XDrawline / XDrawLines / XDrawSegments

  o  XFillRectangle / XFillRectangles

  o  XDrawRectangle / XDrawRectangles - For line width less than or equal 
     to one and number of rectangles less than or equal to two, these commands 
     are concerted to batched XDrawLine commands. For all other line widths or 
     when more than two rectangles are requested, Direct Xlib uses the same 
     significantly slower rendering techniques as the OpenWindows server.

  o  XDrawArc / XDrawArcs / XFillArc / XFillArcs - These primitives are 
     rendered locally, when possible. XDrawArcs are not batched due to the way 
     join styles are applied to arcs.This is also the case for standard Xlib.

  o  XDrawPoint / XDrawPoints - are batched locally in the client with 
     delayed rendering to provide maximum performance, as in standard Xlib

  o  XDrawLine, XDrawPoint, XFillRectangle, XDrawRectangle, and 
     XFillArc primitives - batched locally in the client with delayed rendering 
     to provide maximum performance, as they are in standard Xlib.

  o  XFillPolygon - Polygons are batched locally in the client with delayed 
     rendering to provide maximum performance. A total of 256 vertices among 
     one or several polygons is batched locally.

  o  XDrawString / XDrawImageString - Direct Xlib currently supports a maximum
     of thirty-two (32) 8-bit fonts stored locally on the client side. The 
     amount of local memory used to store font bitmaps can be controlled by the 
     DIRECTX_FONT_MEMORY_LIMIT environment variable. The default value is 
     65536 bytes per client. Most 8-bit fonts average between 4K and 8K in
     total memory needed for bitmaps.

  o  XClearWindow / XClearArea - Only the simplest case of these primitives 
     is supported locally: when the background is rendered using a single 
     background pixel color and is not ParentRelative.

Direct Xlib also supports local DGA access to backing store.


Programming Tips: Improve Your Application Performance
------------------------------------------------------
How much an application's performance improves depends on the application's
graphics utilization and mix of graphics primitives. Almost everything that
applies to making standard Xlib graphics fast, applies to Direct Xlib; on
Direct Xlib this performance gain is magnified. Optimizing an application's
graphics code would include the following:

  o  batching vectors into chains
  o  avoiding color changes when possible
  o  avoiding copies of data within the application

Pixels for all drawables accelerated (rendered locally) by Direct Xlib are
shared with OpenWindows. Access to these pixels is synchronized between the two 
processes. Synchronization is accomplished by a combination of the locking 
mechanism, and by flushing graphics primitives and forcing a round trip to the 
server through the X11 command buffer whenever necessary. To minimize round
trips, synchronization with the server is implemented only when switching
between client local and server-based graphics rendering. If a series of
primitives can be rendered locally, no round trip-style synchronization is 
necessary. Conversely, if a series of primitives can only be rendered by the 
server, no extra round trip synchronization is necessary. Round trip-style 
synchronization is only required when alternating between local and server 
based graphics rendering.

Not all operations are faster with Direct Xlib. Applications that use many fill 
styles or clip masks may actually show performance reductions when running 
with Direct Xlib on OpenWindows 3.0. This is because DGA-shared pixmaps are
not supported in OpenWindows 3.0; the amount of synchronization necessary with
the server can increase significantly. This limitation is removed in the future
version of Direct Xlib on Solaris 2.0. In addition, window creation and
destruction times are significantly slower with Direct Xlib because of extra 
overhead involved in gaining direct access to the windows. Because the DGA 
interface forces all changes to the window hierarchy to complete immediately 
without the benefits of batching requests and delayed processing, the 
performance of operations like window circulation suffers when many windows
exist in the hierarchy.


Direct Xlib and the X Window System
-----------------------------------
To get accelerated performance from the application, Direct Xlib must be used 
with OpenWindows 3.0 X11/NeWS server. If any other MIT X11 server is used, 
you will not see any acceleration because DGA will not be available on other X 
servers.

Using other X servers should not cause any noticeable degradation in 
performance in comparison to the standard Xlib libraries.


Positioning Direct Xlib, XGL, and Other Graphic APIs on SPARCstation
--------------------------------------------------------------------
XGL offers maximum performance and functionality on a SPARCstation, and is 
the recommended API for all graphics intensive applications. Under Sun's 
Open Graphics Initiative, several XGL-based APIs are available-SunPHIGS, 
SunGKS, Nth Graphics' NPGL, Ithaca Software's HOOPS-all of which offer 
high performance and enhanced functionality in comparison to Direct Xlib.

For applications that must use the Xlib API due to portability considerations, 
or those that don't need XGL's advanced functionality, the use of Direct Xlib 
can provide a significant graphics performance gain.


Benefits from Direct Xlib for XGL API and Applications
------------------------------------------------------
There is currently no support for raster text in XGL 2.0 API. An XGL-based 
application that must use raster text may make an Xlib call to display raster 
text. Raster text is accelerated by Direct Xlib, and the application may see 
improved performance.

XGL also uses Xlib to render wide lines. If Direct Xlib is enabled, it will get 
called. Wide lines are supported by Direct Xlib, but are unlikely to be any 
faster than through standard Xlib.

In the case where XGL renders through Xlib (dumb frame buffers) because DGA is
not available, Direct Xlib will not help, because it needs DGA as well. In this
case, standard server rendering will be used.


Systems and Software Requirements for Using Direct Xlib
-------------------------------------------------------
Direct Xlib is currently supported on the following platforms:

  o  Systems: Sun-4, Sun-4c, and Sun-4m.

  o  Operating System: SunOS 4.1.1 GFX Rev. 2, SunOS 4.1.2, and later versions.

  o  Window System: OpenWindows 3.0 and later versions.

  o  Graphics Accelerators: GX, GXplus, GS, and GT. Acts like standard Xlib for 
     bwtwo0, cgthree0, and other dumb frame buffers supported by OpenWindows
     3.0.


Installing Direct Xlib
----------------------
Direct Xlib is a set of supplemental Xlib libraries for OpenWindows 3.0. Some 
key points to be aware of during installation:

  o  OpenWindows 3.0 should be installed before installing Direct Xlib.

  o  Installation must be performed as root.

  o  Direct Xlib must be installed on a local disk.

  o  At least 4 Megabytes of disk space should be made available for
     installation.

  o  Installation directory may be in the $OPENWINHOME directory, where 
OpenWindows 3.0 is installed. Direct Xlib can be installed in another 
location, if desired.

The supported system configuration during installation includes:

  o  Sun-4 Local Standalone Workstation
  o  Local Homogeneous Server Workstation
  o  Local Heterogeneous Server Workstation

The following figure illustrates the file system structure on the CD as it is 
shipped. The Direct Xlib installation directory is shown in Figure 3:

                           /cdrom
                             |   
            +-------+--------+-------+
           bin/   cdm*    dx-1.0/   cdmanager*
                             |
                             |
           +--------+--------+--------+
         _info   _install  _text     usr/
                                      |  
                                      |
                                    openwin/
                                      |
                                      |
                          +-----------+-----------+
                         bin/      include/      lib/
                          |           |           |
                          |           |           |
                       PROGRAMS      X11/       dxlib/
                                      |           |
                                      |           |
                                   HEADERS    LIBRARIES

	Figure 3	Direct Xlib Installation Directory Structure

Please refer to Chapter 2, "Installing Direct Xlib", in the Direct Xlib User's
Guide (part number 800-7466-10) for detailed information.


Using Direct Xlib
-----------------
Direct Xlib may be used in the following ways:

  o  With an individual application (i.e., using Direct Xlib on an application-
     by-application basis)

  o  With the entire desktop

To allow Direct Xlib to work properly under the widest range of conditions, it 
is beneficial to use the following procedures before starting the OpenWindows 
server:

1.  Set the file descriptor limit in the shell from which you plan to start the 
    server to the maximum value of 256 with the following command:

	% limit descriptors 256

    Direct Xlib currently requires one file descriptor for each direct X11
    window. Increasing the limit before starting the OpenWindows server reduces
    the chance that applications will run out of file descriptors. If one logs
    out and logs back in, this step must be redone.

2.  Find 10 Megabytes of disk space where the OpenWindows server has permission
    to read and write.

3.  Start OpenWindows by giving it a path to this disk space.

	% openwin -sharedretainedpath <directory_path_to_space> &

where <directory_path_to_space> is the directory path you have chosen. The path 
pointed to must not be a "tmpfs" mount.

To determine the system's current number of file descriptors, type:

	% /etc/pstat -fT
	183/582 files (files used/files supported)
	273/312 inodes
	51/138 processes
	10776/40000 swap
	%

Make sure that the quantity of files supported is not less than 400. If it is
less than 400, you should reconfigure the kernel to support a larger number of
file descriptors.

To run Direct Xlib on an application-by-application basis (assuming Direct Xlib 
is in the default installation location, and the application is dynamically
linked to libx11), type:

	% $OPENWINHOME/bin/dxlib <myprog>

where <myprog> is the name of the application. The program name may be 
followed with the usual command line arguments, if any. Direct Xlib activated 
in this manner is only active for the single application started with the dxlib 
script. The dxlib script must be executed with each application you want to 
use with Direct Xlib.

Running the following script with no application argument:

	% $OPENWINHOME/bin/dxlib

will give you information about how to use Direct Xlib, its current status.

When using Direct Xlib with the entire desktop, one should be aware of the 
following limitations:

1.  Do not use a GENERIC_SMALL kernel, because there are not enough file 
    descriptors available for a large number of normal applications plus a
    large number of DGA applications.

2.  NeWS-based applications may hang in a DGA environment (PageView is fine).
    This problem is limited to OpenWindows 3.0 and will be corrected in later
    versions.

3.  Direct Xlib increases the total working set size by about 1.5 megabytes. On 
    systems with limited memory, this may cause more paging than when Direct 
    Xlib is not used.

To run Direct Xlib on the entire desktop, add the following to the .xinitrc 
file just before starting the window manager (olwm in the default case):

	LD_LIBRARY_PATH=$OPENWINHOME/lib/dxlib/SunOS4.x:$LD_LIBRARY_PATH
	export LD_LIBRARY_PATH

These lines should be added just before the line with the comment:

	# OpenLook Window Manager

If you use a window manager other than olwm, place the line before the 
specific window manager is started.

Now if you type the following:

	% printenv LD_LIBRARY_PATH

you will see the path $OPENWINHOME/lib/dxlib/SunOS4.x appended to the first
part of the old LD_LIBRARY_PATH. Leave this in your value of LD_LIBRARY_PATH
as long as you want Direct Xlib to be automatically used when you start
programs from shells within OpenWindows or from the Desktop menu.

Even though Direct Xlib may be running on the entire desktop, it can be turned 
off on particular applications. To do so, set the DIRECTX_DISABLE environment
variable to any non-zero value before starting the application:

	% setenv DIRECTX_DISABLE 1

If Direct Xlib is installed somewhere else other than $OPENWINHOME, starting 
Direct Xlib gets to be a little different, but it can be easily done. Direct
Xlib can also be used to support proprietary X11 extensions.

Please refer to Chapter 3, "Using Direct Xlib", in the Direct Xlib User's Guide
for in-depth information and additional functionalities.


Includes, Compiles, and Links with Direct Xlib
----------------------------------------------
When compiling Xlib X11 applications, you should continue to use the standard
include/X11 header files. The header files supplied with Direct Xlib are only
needed by programmers who are developing proprietary X extension libraries or
whose application code directly manipulates the X11 command buffer.

For dynamic links to libX11, you should continue to link to the standard 
libraries. Linking dynamically with Direct Xlib makes it difficult to move the 
application back and forth between standard Xlib and Direct Xlib environment. 
It causes the executable to reference libraries which may not be available 
through standard libX11. Any application which is dynamically linked with 
standard libX11 can run with Direct Xlib. Links should include the C math 
libraries (-lm). When compiling and linking, remember to turn off Direct Xlib 
in your shell:

	% setenv DIRECTX_DISABLE 1

For static links to libX11, you must link to the static version of Direct Xlib. 
Links should include the C math libraries (-lm).

If the application uses libXext and/or libxinput and is statically linked to 
either of them, the application must also link to the static Direct Xlib
versions of libX11, and libXext and/or libXinput supplied with Direct Xlib.

Please refer to Chapter 3, "Using Direct Xlib", in the Direct Xlib User's Guide
for more information.


Documentation
-------------
To use Direct Xlib features most effectively on your system, please refer to 
Direct Xlib User's Guide (part number 800-7466-10). It covers the following 
topics in depth:

  o  Introduction (Chapter 1)

	Overview / System Requirements / Supported Primitives

  o  Installing Direct Xlib (Chapter 2)

	Installing Direct Xlib in different system configurations and 
	environments, which include Standalone Workstations, Homogeneous 
	Server Workstations, and Heterogeneous Server Workstations.

  o  Troubleshooting (Chapter 4)

	Error detection techniques for programmers and system administrators. 
	Addresses problems that may arise during the installation of Direct
	Xlib or OpenWindows and in turning on DGA.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
For information send mail to info-sunflash@sunvice.East.Sun.COM.
Subscription requests should be sent to sunflash-request@sunvice.East.Sun.COM.
Archives are on solar.nova.edu, paris.cs.miami.edu, uunet.uu.net,
src.doc.ic.ac.uk and ftp.adelaide.edu.au

All prices, availability, and other statements relating to Sun or third
party products are valid in the U.S. only. Please contact your local
Sales Representative for details of pricing and product availability in
your region. Descriptions of, or references to products or publications
within SunFlash does not imply an endorsement of that product or
publication by Sun Microsystems.

John McLaughlin, SunFlash editor, flash@sunvice.East.Sun.COM. (305) 776-7770.

TRACE: To: sunflash@housun.Central Errors-to: owner-sunflash@housun.Central.sun.com