XGL Programmer’s Guide 2550 Garcia Avenue Mountain View, CA 94043 U.S.A. A Sun Microsystems, Inc. Business 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, DeskSet, ONC, ONC+, NFS, and XGL are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark of Novell, Inc., in the United States and other countries; X/Open Company, Ltd., is the exclusive licensor of such trademark. OPEN LOOK® is a registered trademark 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. xxix New Features . xxxiii 1. Introduction to XGL . 1 Overview of XGL Functionality. 1 Direct Graphics Access . 4 Introduction to XGL Objects and Graphical Organization. 6 System State Object and Generic Operators. 7 Device Object . 8 2D and 3D Context Objects. 9 Color Map Object. 10 Transform Object . 10 Line Pattern Object . 11 Light Object . 12 Stroke Font Object . 13 Marker Object. 13 iii Pcache Object . 13 Gcache Object. 14 Texture Map Object and MipMap Texture Object . 14 2. Installation Issues. 15 About the XGL Directory Structure. 15 Font Files. 17 XGL AnswerBook Directory Structure . 18 Setting XGL Environment Variables . 18 Verifying the Installation of XGL. 19 Installation and System Administrator Notes . 19 Debuggable XGL Runtime Library . 19 XGL Library and Reference Pipelines . 20 XGL and the PEXLib Library . 20 Solaris Security Feature and DGA. 20 Using the Solaris XGL AnswerBook . 21 Accessing the XGL Man Pages. 21 3. Getting Started with XGL Programming . 23 Compiling and Running XGL Programs. 23 Run-time Considerations . 25 Using make(1) To Build XGL Example Programs . 26 Basic XGL Concepts. 27 XGL and the X Window System Environment. 27 How an XGL Application Works. 30 XGL Drawing Primitives . 31 iv XGL Programmer’s Guide—August 1994 Handling 2D and 3D Data . 32 More on XGL Object-Based Programming . 34 Example Program . 37 Creating the Window and Registering Callback Procedures 41 Opening XGL . 41 Creating a Window Raster Device Object. 41 Creating a Context Object. 42 Rendering Geometry. 42 Objects Provided at XGL Initialization . 43 Programming Tips . 44 General Tips . 44 XView Tips . 45 OLIT Tips . 46 4. System State Information and Generic Operators . 47 Introduction to the System State Object . 47 System State Operators . 47 System State Attributes. 48 Error Detection and Reporting. 49 Error Notification Function . 50 Error Types and Categories . 51 Generic XGL Operators. 53 5. Devices . 57 Introduction to Device Objects . 57 Creating Device Objects . 58 Contents v Window Raster Device Object . 59 Stream Device Object . 61 Raster Object Attributes . 62 General Raster Attributes . 62 Window Raster Attributes . 65 Memory Raster Attributes . 68 CGM Device Object . 70 Creating a CGM Device . 70 Creating a Picture . 72 CGM Metafile Device Attributes . 73 XGL CGM Line Patterns . 75 XGL CGM Markers . 76 Important Notes on Integrating XGL with a Windowing System 77 Mixing XGL and Xlib Drawing Routines . 77 Window Resize Events . 78 Device Example Programs . 78 XGL and Xlib . 79 XGL and the XView Toolkit . 83 XGL and the OLIT Toolkit . 87 Transparent Overlay Windows . 90 Creating an Overlay Window . 90 Rendering to an Overlay Window. 94 Determining Device Acceleration . 97 Inquire Example Program. 99 vi XGL Programmer’s Guide—August 1994 6. Color . 105 Introduction to XGL Color . 105 Indexed Color Space . 106 RGB Color Space . 106 XGL Color Pipeline . 106 Introduction to the Color Map Object . 108 Creating a Color Map Object . 108 Color Tables . 109 Color Table Attributes. ..