............................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


......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


......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


......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


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


...... 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 of XglDrawable Creation and Use	159
...Drawable Interfaces for the Device Pipeline	161
......Obtaining Information During Pipeline Initialization	162
......Locking the Window	162
......Accessing Dynamic Information	165
......Managing Window System Resources	168
......Managing Software Cursors	170
...Description of Drawable Interfaces	170
......XglDrawable Functions for the Device Pipeline	170
......XglDrawable Functions Used by the XGL Core Only	177
......Window System Dependencies	178
8. LI-3 Loadable Interfaces	181
...About the LI-3 Layer	182
......LI-2 Software Pipeline and LI-3 Device Pipeline	185
......Window Locking Around Hardware Access	186
......Data Input to the LI-3 Layer	186
......Picking at LI-3	186
......Texture Mapping at LI-3	187


...LI-3 Interfaces	188
......li3Begin() and li3End() - 2D/3D	188
......li3CopyFromDpBuffer() - 2D/3D	189
......li3CopyToDpBuffer() - 2D	190
......li3CopyToDpBuffer() - 3D	191
......li3MultiDot() - 2D	193
......li3MultiDot() - 3D	194
......li3Vector() - 2D	196
......li3Vector() - 3D	198
......li3MultiSpan() - 2D	201
......li3MultiSpan() - 3D	203
...RefDpCtx	207
......Using RefDpCtx for Rendering	207
......RefDpCtx LI-3 Rendering Example	210
......Handling Attribute Changes for RefDpCtx	211
......RefDpCtx Interfaces	212
...PixRect Objects	214
......Using PixRects	214
......PixRect Interfaces	216
9. LI-2 Loadable Interfaces	219
...About the LI-2 Layer	220
......Deciding Which LI-2 Interfaces to Implement	221
......Window Locking Around Hardware Access	224
......Picking at LI-2	225


......Calling the Software Pipeline for Texture Mapping at LI-2	225
......LI-2 Attributes	225
...What You Should Know About the Software Pipeline	227
......LI-1 Operations in the Software Pipeline	227
......Lighting and Surface Color in the Software Pipeline	227
......Texture Mapping in the Software Pipeline	228
......Point Type Input to LI-2 Device Pipelines	228
...Data Input to the LI-2 Layer	230
......How Data Is Stored by the Software Pipeline	230
......Data Storage in the XglLevel Object	232
......Pipeline Interfaces to XglPrimData and XglLevel Data	234
......Example of Extracting Data from XglLevel	234
......Conic and Rectangle Data	236
......Pipeline Interfaces to XglConicData and XglRectData	237
......Example of Extracting Data from XglRectData	238
......Example of Extracting Data from XglConicData	239
...LI-2 Interfaces	241
......li2GeneralPolygon() - 2D/3D	241
......li2MultiDot() - 2D/3D	242
......li2MultiEllipse() - 2D	243
......li2MultiEllipticalArc() - 2D	244
......li2MultiPolyline() - 2D	246
......li2MultiPolyline() - 3D	248
......li2MultiRect() - 2D	250


......li2MultiSimplePolygon() - 2D	251
......li2MultiSimplePolygon() - 3D	252
......li2TriangleList() - 3D	253
......li2TriangleStrip() - 3D	254
10. LI-1 Loadable Interfaces	255
...About the LI-1 Layer	256
......Deciding Which LI-1 Interfaces to Implement	258
......Window Locking Around Hardware Access	263
......Handling Invalid Data	263
......Picking	264
......Hidden Surface Data and Maximum Z Value	265
......Hints for Rendering Transparent 3D Surfaces at LI-1	265
......Calling the Software Pipeline for Texture Mapping at LI-1	267
......Antialiasing and Dithering	268
......Data Input to the LI-1 Layer	269
......API Primitive Calls Mapped to LI-1 Functions	273
...LI-1 Interfaces	275
......li1AnnotationText() - 2D/3D	275
......li1DisplayGcache() - 2D/3D	276
......li1MultiArc() - 2D	285
......li1MultiArc() - 3D	286
......li1MultiCircle() - 2D	287
......li1MultiCircle() - 3D	288
......li1MultiEllipticalArc() - 3D	289


......li1MultiMarker() - 2D	290
......li1MultiMarker() - 3D	291
......li1MultiPolyline() - 2D	292
......li1MultiPolyline() - 3D	293
......li1MultiRectangle() - 2D	295
......li1MultiRectangle() - 3D	296
......li1MultiSimplePolygon() - 2D	297
......li1MultiSimplePolygon() - 3D	298
......li1NurbsCurve() - 2D/3D	299
......li1NurbsSurf() - 3D	301
......li1Polygon() - 2D	303
......li1Polygon() - 3D	304
......li1QuadrilateralMesh() - 3D	305
......li1StrokeText() - 2D/3D	306
......li1TriangleList() - 3D	307
......li1TriangleStrip() - 3D	309
......li1Accumulate() - 3D	310
......li1ClearAccumulation() - 3D	312
......li1CopyBuffer() - 2D/3D	313
......li1Flush() - 2D/3D	316
......li1GetPixel() - 2D/3D	317
......li1Image() - 2D/3D	318
......li1NewFrame() - 2D/3D	320
......li1PickBufferFlush() - 2D/3D	321


......li1SetMultiPixel() - 2D/3D	322
......li1SetPixel() - 2D/3D	323
......li1SetPixelRow() - 2D/3D	324
11. Error Handling	325
...Error Reporting for XGL Device Pipelines	326
......Error-Handling Mechanism	326
......Error Message Files	327
......Error Reporting Macros	328
......Example of Error Reporting Using the Error Macros	330
......Creating a Pipeline Error Message File	331
12. Utilities	333
...3D Utilities	334
...Bounding Box Utilities	385
...Copy Buffer Utilities	387
...Polygon Classification Utilities	392
...Polygon Decomposition Utilities	394
A. Performance Tuning	397
...Finding the Performance Critical Paths	398
......At-a-Glance Comparison of Performance Tools	400
......Recommendations for Performance Tools	401
...Selecting Good Benchmarks	401
...Tuning Performance Critical Paths	403
......Locating the Central Body of Code	403
......Changing the Underlying Algorithm	403


......Tuning at the Assembly Language Level	404
...Tips and Techniques for Faster Code	404
B. Changes to the Graphics Porting Interface at GPI 4.1	427
...Additions to the GPI	427
...Changes to the GPI	428
C. Changes to the XGL Graphics Porting Interface at GPI 4.0	429
...Changes in Rendering Architecture	430
...Changes in State Handling	432
...Application Data Passed Directly to Pipelines	433
D. Software Pipeline li1DisplayGcache	435
E. Accelerating NURBS Primitives	451
Index	453