XGL Device Pipeline Porting Guide Loadable Interfaces Version 4.1 2550 Garcia Avenue Mountain View, CA 94043 U.S.A. A Sun Microsystems, Inc. Business Copyright 1996 Sun Microsystems, Inc., 2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document 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® system, licensed from Novell, Inc., and from the Berkeley 4.3 BSD system, licensed from the University of California. UNIX is a registered trademark in the United States and other countries and is exclusively licensed by X/Open Company Ltd. Third-party software, including font technology in this product, is protected by copyright and licensed from Sun’s suppliers. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR 52.227-19. Sun, Sun Microsystems, the Sun logo, Solaris, and XGL are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the United States and other countries. 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 trademark of X Consortium, Inc. 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. Please Recycle Contents Preface. xxi 1. Introduction to XGL Loadable Interfaces . 1 Introduction to the XGL Product . 1 Solaris Dynamic Linking. 2 XGL Loadable Interfaces. 2 Loadable Interface 1 (LI-1) . 3 Loadable Interface 2 (LI-2) . 3 Loadable Interface 3 (LI-3) . 3 2. Getting Started . 7 XGL Architecture From the Pipeline Point of View. 8 About Device Pipelines. 8 Services the XGL Core Provides the Device Pipeline . 9 Issues to Consider Before You Begin Porting . 10 Device Support for Multiple XGL Contexts . 10 Device Support for Backing Store . 11 iii OpenWindows and XGL. 11 Porting Task . 12 Choosing a Loadable Interface Level . 12 A Quick Look at Implementing an XGL Graphics Handler 15 Device Pipeline Makefiles. 21 Directory Structure for the XGL DDK . 22 Accessing External Files at Runtime . 23 3. Pipeline Interface Classes . 25 Overview of the Pipeline Interface Classes . 26 Naming Your Device Pipeline . 27 About Versioning. 28 Setting Up the Required Pipeline Interface Classes. 30 Defining a Function to Create the Device Pipeline Object . 31 Defining the Device Pipeline Library Class . 32 Defining the Device Pipeline Manager Class . 36 Defining the Device Pipeline Device Class. 39 Defining the Device Pipeline-Context Class. 43 What Else You Should Know . 52 How a Device Pipeline Is Loaded . 52 Supporting DGA Transparent Overlay Windows . 53 Device Pipeline Objects for Multiple Processes . 54 Adding Member Data to a Pipeline Class. 56 Backing-Store Support in the Pipeline Classes. 57 Description of Device-Dependent Virtual Functions . 60 iv XGL Device Pipeline Porting Guide—May 1996 Virtual Functions in DpDev.h. 60 Virtual Functions in DpDevRaster.h . 61 Virtual Functions in DpDevWinRas.h. 62 Virtual Functions in DpDevMemRas.h . 65 Quick Reference Chart of Virtual Functions. 66 4. Handling Changes to Object State. 71 State Changes and the Device Pipeline . 72 Getting Attribute Values from the Context Object. 72 When the Device Associated with a Context Is Changed . 74 Getting Attribute Values from Objects Other Than the Context 75 Handling Derived Data Changes. 81 Getting Stroke Attribute Values from the Stroke Group Object 82 Example of Device Pipeline Use of Stroke Groups . 83 Rendering Multipolylines. 85 Flag Mask and Expected Flag Value . 87 DC Offset . 88 Design Issues . 90 Deciding to Reject a Primitive . 90 Handling Context Switches . 90 Partial Rendering of a Primitive . 91 5. Getting Information from XGL Objects . 93 What You Should Know About XGL Attribute Values . 94 Pipeline Connection to Device-Independent Objects . 94 Pipeline Access to Object Attributes . 95 Contents v Naming Conventions for Internal Attributes. 95 Context Attributes and LI Layers . 96 Getting Attribute Values from the Context. 97 Getting Attribute Values from Other Objects . 98 Getting Information from a Transform Object . 99 Getting Attribute Values From the Stroke Group Object . 100 Non-API Interfaces Provided in API Objects . 101 Context Interfaces . 101 Context 2D Interfaces . 102 Context 3D Interfaces . 103 Data Map Texture Interfaces. 104 Device Interfaces . 105 Light Interfaces . 106 Line Pattern Interfaces . 106 Marker Interfaces. 107 MipMap Texture Interfaces. 107 Raster Interfaces. 108 Texture Map Interfaces . 108 Window Raster Interfaces. 109 Memory Raster Interfaces. 109 Stroke Font Interfaces . 110 Transform Interfaces and Flags . 111 Getting Information From the Device Object . 119 Color Map Interfaces. 119 vi XGL Device Pipeline Porting Guide—May 1996 6. View Model Derived Data. 123 Overview of View Model Derived Data . 124 Design Goals of Derived Data . 125 Derived Data Items . 128 Coordinate Systems and Transforms . 128 Other Derived Items. 130 Overview of Derived Data’s Implementation . 131 Accessing Derived Data . 132 Registration of Concerns. 133 Bit Definitions for the View Flag . 135 Determining Whether Derived Items Have Changed. 137 Messages . 137 The Composite . 138 Detecting Changes With the Composite . 138 Setting the Composite . 139 Clearing the Composite . 139 Detecting Changes to Individual Derived Items . 140 Getting Derived Items . 142 Getting Derived Transforms . 143 Getting Boundaries. 144 Getting 3D Viewing Flags . 145 Getting Lights . 146 Getting Eye Positions or Vectors. 147 Getting Model Clip Planes. 148 Contents vii Getting Depth Cue Reference Planes . 149 Example of Detecting Changes and Getting Derived Items . 149 Current Coordinate System . 154 7. Window System Interactions . 157 Overview of the XglDrawable . 158 Services Provided by the XglDrawable Class. 159 Typical Scenario.