Direct Xlib User’s Guide 2550 Garcia Avenue Mountain View, CA 94043 U.S.A. Part No: 801-6687-10 A Sun Microsystems, Inc. Business Revision A, August 1994 1994 Sun Microsystems, Inc. 2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A. All rights reserved. This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Portions of this product may be derived from the UNIX® and Berkeley 4.3 BSD systems, licensed from UNIX System Laboratories, Inc., a wholly owned subsidiary of Novell, Inc., and the University of California, respectively. Third-party font software in this product is protected by copyright and licensed from Sun’s font suppliers. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19. The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. TRADEMARKS Sun, the Sun logo, Sun Microsystems, Sun Microsystems Computer Corporation, SunSoft, the SunSoft logo, Solaris, SunOS, OpenWindows,Direct Xlib, DeskSet, ONC, ONC+, and NFS are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX and OPEN LOOK are registered trademarks of Novell, Inc. PostScript and Display PostScript are trademarks of Adobe Systems, Inc. All other product names mentioned herein are the trademarks of their respective owners. All SPARC trademarks, including the SCD Compliant Logo, are trademarks or registered trademarks of SPARC International, Inc. SPARCstation, SPARCserver, SPARCengine, SPARCstorage, SPARCware, SPARCcenter, SPARCclassic, SPARCcluster, SPARCdesign, SPARC811, SPARCprinter, UltraSPARC, microSPARC, SPARCworks, and SPARCompiler are licensed exclusively to Sun Microsystems, Inc. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK® and Sun™ Graphical User Interfaces were developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements. X Window System is a product of the Massachusetts Institute of Technology. THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME. Please Recycle Contents Preface . v 1. Introduction . 1 Overview . 1 System Requirements . 2 Supported Graphics Primitives . 3 2. Installing the Direct Xlib 3.1 Software . 5 File Locations . 5 Installation Overview . 6 Determining If Volume Management Is Running . 6 Installing Direct Xlib Using Volume Management . 7 Local Installation. 7 Remote Installation. 9 Installing Direct Xlib without Volume Management. 11 Local Installation. 11 Remote Installation. 13 iii 3. Using the Direct Xlib 3.1 Software. 17 Getting Started . 17 General Setup . 18 Invoking Direct Xlib . 18 Using Direct Xlib on Your Entire Desktop . 20 Usage Notes . 21 Server Connections. 21 Frame Buffers . 22 Determining How Applications Have Been Linked. 22 dxlib Script. 23 Developer Notes . 24 General Application Compiling with Direct Xlib . 24 Direct Xlib Errors . 25 Supporting Your Own X11 Extensions with Direct Xlib . 25 Setting Environment Variables . 26 Direct Xlib Demonstration Programs . 26 pointfish . 27 DXspeed. 27 xspheres . 28 Index . 29 iv Direct Xlib User’s Guide—August 1994 Preface The Direct Xlib User’s Guide describes how to install and use Direct Xlib 3.1. The following describes the contents of each chapter: • Chapter 1 contains an overview of Direct Xlib 3.1. • Chapter 2 describes how to install Direct Xlib 3.1. • Chapter 3 describes how to use Direct Xlib 3.1. Audience This document is primarily for end-users who are responsible for installing and using Direct Xlib on their Sun system. v Typographical Conventions This guide uses a number of typographic conventions: • Palatino font, italic face indicates: • Emphasis • The title of a book, chapter, or section • A variable • A command argument • Courier font indicates: • A listing • A command name • A program name • Text the machine displays • Courier font, bold face indicates: • Input that the user types Cautions and Warnings The following international symbols appear in this book when you must perform procedures requiring proximity to electrical current. Caution – If you do not follow the instructions, damage to the equipment ! may result. Warning – Hazardous voltages are present. If you do not follow the instructions, electrical shock may occur. vi Direct Xlib User’s Guide—August 1994 Introduction 1 Overview Direct Xlib™ is Sun’s accelerated implementation of the Xlib Application Programmers Interface (API). It improves rendering performance for graphics- intensive Xlib applications drawing on the local host’s display. Direct Xlib improves Xlib application performance by eliminating the setup, transport, context switch and parsing overhead involved in communicating graphics commands from the Xlib client to the X11 server. Direct Xlib allows Xlib applications to perform graphics operations directly to the graphics device. Direct Xlib uses the services provided by Direct Graphics Access (DGA), available in OpenWindows™ Version 3.4, to synchronize rendering operations with the server and other direct access applications (like those using XGL or XIL). Since this improved performance comes from the elimination of this communication overhead, performance is dependent upon the ratio of overhead to rendering time. Direct Xlib 3.1 provides the most improvement when rendering small individual primitives or a large list of batched primitives. In the former case, the performance benefits are due to the elimination of the communication on time which is significant when compared to the rendering time for a single small graphics primitive. In the latter case, the performance benefits are due to the elimination of the data copy required to transfer the client’s primitive data between the client’s address space and the server’s. 1 1 Direct Xlib 3.1 supports multiple heterogenous graphics devices within the same system. (Direct Xlib 3.0 supported systems with more than one graphics device only if the devices were the same type.) You can only use Direct Xlib 3.1 with OpenWindows 3.4. The applications most likely to benefit are those in the following industry segments: mechanical design, electronic design, drafting, mapping, and scientific visualization. You can use the Direct Xlib software with any existing or newly developed application that is already linked to Xlib as a shared library. Recompiling or relinking is not necessary. Note – Direct Xlib 3.1 does not support statically linked Xlib applications or applications that load libX11 by calling dlopen. Direct Xlib 3.1 supports the X11R5 API with level 4 Internationalization. The package name for Direct Xlib is SUNWdxlib. System Requirements The Direct Xlib 3.1 software requires the following: • Sun-4™ or SPARC® systems • SunOS™ 5.4 software or later • OpenWindows Version 3.4 software or later 2 Direct Xlib User’s Guide — August 1994 1 Supported Graphics Primitives The following primitives are accelerated by the Direct Xlib 3.1 software: XCopyArea and XCopyPlane XGetImage and XPutImage XSetClipRectangles and XSetClipMask XDrawLine and XDrawLines XDrawSegments XDrawPoint and XDrawPoints XFillRectangle and XFillRectangles XDrawString and XDrawImageString XDrawString16 and XDrawImageString16 XDrawText and XDrawText16 XmbDrawString and XmbDrawImageString XwcDrawString and XwcDrawImageString XmbDrawText and XwcDrawText XFillPolygon XDrawRectangle and XDrawRectangles XClearWindow and XClearArea XDrawArc and XDrawArcs XFillArc and XFillArcs All other Xlib operations are supported by the Direct Xlib 3.1 software through standard Xlib server rendering. Direct Xlib 3.1 supports shared fonts, thereby minimizing wasted memory. Introduction 3 1 4 Direct Xlib User’s Guide — August 1994 Installing the Direct Xlib 3.1 Software 2 This chapter shows you how to install Direct Xlib 3.1 software. The supported system configurations include a SPARC-based standalone or server workstation. The installation procedures include installing Direct Xlib on systems with Volume Management installed, as well as for systems without Volume Management. The Direct Xlib package requires about three megabytes of disk space. Make sure you have enough disk space before you attempt to install Direct Xlib. Install Direct Xlib using pkgadd after you have successfully installed Solaris 2.4 or later software. File