What You Need to Know about the Loadable Interfaces

The XGL architecture provides considerable flexibility in implementing a device pipeline. You can implement pipelines at the LI-1 level for every XGL primitive, or you can choose to implement some primitives at the LI-1 level and some at the LI-2 level and use the software pipeline for the remaining primitives. You can also use the software pipeline for LI-1 processing, and implement some of the LI-2 interfaces and the LI-3 interfaces. Your decision will depend on the capabilities of your hardware.

The software pipeline includes a set of support routines that can fill in functionality that a pipeline cannot handle. It is likely that even pipeline ports that fully accelerate most XGL functionality will fall back to the software pipeline for some features. In general, the software pipeline will be used for devices that:

• Accelerate most XGL functionality, including transformations, clipping, lighting, and scan conversion, but may not implement particular primitives or support some combinations of XGL attributes. Device pipelines for these devices can fall back to the software pipeline for unimplemented primitives or unaccelerated features.
• Partially accelerate functionality at a particular level, such as Xlib devices or simple color frame buffer devices. For example, an Xlib device may render vectors and polygons using Xlib routines. This pipeline will use the XGL software pipeline for LI-1 operations such as transformations, clipping. lighting, and depth cueing, and will perform scan conversion at the LI-2 level in the server after the device pipeline issues an Xlib call. A simple color frame buffer may use the software pipeline LI-1 and LI-2 functions and implement only LI-3 functions to write pixel values into the hardware.

The software pipeline provides a generic implementation of what is expected of the device pipeline at each loadable interface level. By examining the software pipeline implementation, you can get a global view of what the device pipeline needs to do.

Overview List of Loadable Pipeline Interfaces

Table 9-1 lists the set of interfaces for the device pipeline. Some of these interfaces must be implemented by every device pipeline; others are optional. The table describes the interfaces at each layer and shows whether the interfaces are implemented by the software pipeline. Note that functions that require direct pixel access or immediate interaction with the device pipeline are not simulated in software.

Table 9-1

LI	Function	2D	3D	Description	Swp Dp
LI-1	li1AnnotationText()	v	v	Renders text in a plane parallel to the display surface.	v Optional
	li1DisplayGcache()	v	v	Displays the contents of the Gcache object.	v Optional
	li1MultiArc()	v	v	Renders a set of arcs.	v Optional
	li1MultiCircle()	v	v	Renders a set of circles.	v Optional
	li1MultiEllipticalArc()		v	Renders a set of 3D elliptical arcs.	v Optional
	li1MultiMarker()	v	v	Renders a set of markers.	v Optional
	li1MultiPolyline()	v	v	Renders a set of polylines.	v Optional
	li1MultiRectangle()	v	v	Renders a set of rectangles.	v Optional
	li1MultiSimplePolygon()	v	v	Renders a set of single-bounded polygons.	v Optional
	li1NurbsCurve()	v	v	Renders a NURBS curve.	v Optional
	li1NurbsSurf()		v	Renders a NURBS surface.	v Optional
	li1Polygon()	v	v	Renders a single planar polygon.	v Optional
	li1QuadrilateralMesh()		v	Renders a set of connected quadrilateral polygons.	v Optional
	li1StrokeText()	v	v	Renders stroke text.	v Optional
	li1TriangleList()		v	Renders a set of triangles arranged as a triangle strip, a triangle star, or unconnected triangles.	v Optional
	li1TriangleStrip()		v	Renders a set of connected triangular polygons.	v Optional

Table 9-1

LI	Function	2D	3D	Description	Swp	Dp
	li1Accumulate()		v	Accumulates images from the draw buffer of the raster to a specified accumulation buffer.	v	Optional
	li1ClearAccumulation()		v	Clears the accumulation buffer.	v	Optional
	li1CopyBuffer()	v	v	Copies a block of pixels from one buffer to another.		Required
	li1Flush()	v	v	Causes pending processing to complete.		Required
	li1GetPixel()	v	v	Gets the color value of a pixel.		Required
	li1Image()	v	v	Displays a block of pixels.	v	Optional
	li1NewFrame()	v	v	Clears the DC viewport to the background color.		Required
	li1PickBufferFlush()	v	v	Synchronizes the device's pick buffer and the XGL core pick buffer.		Required
	li1SetMultiPixel()	v	v	Sets the color values for a list of pixels.	v	Optional
	li1SetPixel()	v	v	Sets the color value of a specified pixel.		Required
	li1SetPixelRow()	v	v	Sets the color value for a row of pixels.	v	Optional
LI-2	li2GeneralPolygon()	v	v	Scan converts polygons to span lines.	v	Optional
	li2MultiDot()	v	v	Calls li3MultiDot().	v	Optional
	li2MultiEllipse()	v		Scan converts ellipses to span lines.	v	Optional
	li2MultiEllipticalArc()	v		Scan converts elliptical arcs to span lines.	v	Optional
	li2MultiPolyline()	v	v	For thin lines, calls li3Vector(); scan converts wide lines to span lines.	v	Optional
	li2MultiRect()	v		Scan converts rectangles to span lines.	v	Optional
	li2MultiSimplePolygon()	v	v	Scan converts polygons to span lines.	v	Optional
	li2TriangleList()		v	Takes a triangle list, breaks it into individual triangles and scan converts the triangles.	v	Optional
	li2TriangleStrip()		v	Takes a triangle list, breaks it into individual triangles and scan converts the triangles.	v	Optional

Table 9-1

LI	Function	2D	3D	Description	Swp	Dp
LI-3	li3Begin()	v	v	Specifies the beginning of a sequence of LI- 3 primitives.		Required
	li3End()	v	v	Specifies the end of a sequence of LI-3 primitives.		Required
	li3CopyFromDpBuffer()	v	v	Copies pixel data from a hardware buffer into memory.		Required
	li3CopyToDpBuffer()	v	v	Copies pixel data from memory into the specified hardware buffer.		Required
	li3MultiDot()	v	v	Draws a list of dots at a specified x,y location.		Required
	li3MultiSpan()	v	v	Draws a list of spans.		Required
	li3Vector()	v	v	Draws a vector.		Required
	li3GetDotControl() li3GetVectorControl() li3GetSpanControl()	v v	v v v	Get control functions for LI-3 dots, vectors, and spans.		Required
	li3SetDotControl() li3SetVectorControl() li3SetSpanControl()	v v	v v v	Set control functions for LI-3 dots, vectors, and spans.		Required

Deciding Which Interfaces to Implement

Table 9-2 shows the LI-1, LI-2, and LI-3 functions that are called by the software pipeline LI-1 functions. If you decide to implement one of the interfaces listed in the left column, you may also want to implement some or all of the checked functions listed to the right. You can think of the functions to the right as being downstream from the LI-1 function that calls them. In this

table, "D" indicates a function that the pipeline calls directly; "I" indicates to a function that is called indirectly by a function downstream from the LI-1 function.

Table 9-2

	riangleList riangleStrip..........riangleList riangleStrip li1MultiPolyline li1Polygon li1MultiSimplePolygon li1MultiMarker li1T li1T li1QuadrilateralMesh li2MultiPolyline li2MultiDot li2MultiSimplePolygon li2GeneralPolygon li2MultiEllipticalArc li2MultiEllipse li2T li2T
li1AnnotationText - 2D/3D	D.............I		I
li1MultiArc - 2D	D D...........I.....I D.......I		I
li1MultiArc - 3D	D I D........D....D.........I		I
li1MultiCircle - 2D	D..................I..D.....I
li1MultiCircle - 3D	I D...............D.........I
li1MultiEllipticalArc - 3D	D I D........D....D.........I		I
li1MultiMarker - 2D/3D	D.............I D.............I	I	I
li1MultiPolyline - 2D/3D	D...............I		I
li1MultiRectangle - 2D	I D...............I.........I
li1MultiRectangle - 3D	I D...............D.........I
li1MultiSimplePolygon - 2D	D..................I.........I
li1MultiSimplePolygon - 3D	D...............D I.........I
li1NurbsCurve - 2D/3D	D....D.......I I.............I		I
li1NurbsSurf - 3D	D....D D..D I I I.......I..I		I
li1Polygon - 2D/3D	D.........I		I
li1QuadrilateralMesh - 3D	D...............I..I
li1StrokeText - 2D/3D	D.............I...............I		I
li1TriangleList - 3D	D....D D I
li1TriangleStrip - 3D	D......D I

ector

li3MultiSpan li3MultiDot li3V

Note that, depending on the geometry in the Gcache, 2D li1DisplayGcache() calls the following LI-1 primitives:

• li1Marker()
• li1MultiPolyline()
• li1MultiSimplePolygon()
• li1Polygon()
• li1NurbsCurve()

For 3D, li1DisplayGcache() calls all of the above and

• li1NurbsSurf()
• li1TriangleStrip().

Table 9-3 shows which LI-2 and LI-3 functions are called by each of the LI-2 functions. If you decide to replace one of the functions listed in the left column, you may also want to replace the functions listed to the right.

Table 9-3

	riangleList li2Multipolyline li2GeneralPolygon li2T
li2GeneralPolygon	D.......D		I
li2MultiEllipse	D....D
li2MultiEllipticalArc	D D....D		D
li2MultiDot		D
li2MultiPolyline - 2D	D		D
li2MultiPolyline - 3D	D...I		D
li2MultiRect	D.......D		I
li2MultiSimplePolygon - 2D	D.......D		I
li2MultiSimplePolygon - 3D	I D.....I		I
li2TriangleList	D.......D		I
li2TriangleStrip	D.......D		I

ector

li2MultiSimplepolygon li3Multispan li3MultDot li3V

Input Data for LI-2 and LI-3

All input data to LI-2 or LI-3 functions are in device coordinates unless otherwise noted.

Picking

It is the responsibility of the LI-1 primitive functions to handle picking, if picking is enabled. If a particular device pipeline can do picking with its hardware, then the pipeline can either cache pick hits as they occur, or it can immediately write them into the XGL core pick buffer. In the former case, if the XGL core pick buffer requires synchronization (because a software function is about to be used to pick a particular primitive, or the API has called xgl_pick_get_identifiers), then the LI-1 li1PickBufferFlush() function is called to transfer the cached hardware pick information (if any). For example, if the device pipeline picks an object, and then the software pipeline is called to pick another object with the same pick ID, the li1PickBufferFlush() function is called, and only one pick is placed in the pick buffer. The XGL core merges device pipeline LI-1 pick events and LI-3 pick events.

If Z-buffering is enabled, the geometry is passed to LI-2, which will examine the current attributes and scan convert wide lines. The geometry is then passed down to LI-3 functions. LI-1 and LI-2 will have already pruned the geometric data to be inside the pick aperture; LI-3 functions must test if the geometry is visible based upon the Z comparison method. The 3D LI-3 primitive functions return a Boolean parameter picked. This parameter returns TRUE if the primitive was picked via Z-buffer-based picking (if Z-buffering is on and picking is on).

---

Note - LI-3 functions are only called to do picking if Z-buffering is enabled.

---

Hints for Rendering Transparent 3D Surfaces

The device pipeline can optimize the rendering of transparent surfaces or let the software pipeline handle the rendering of transparent surfaces. To handle transparency, the pipeline must first determine whether the surface is transparent, and then it can decide whether to optimize the rendering of the surface. Transparency is available for 3D surfaces only. Follow these steps:

1. After face distinguishing has been done, determine whether the surface is transparent or opaque. You can use the XgliUtIsTransparent utilities to determine this; see Chapter 10, "Utilities" for information on these utilities.

2. Determine what action to take based on the XGL attribute XGL_3D_CTX_BLEND_DRAW_MODE. Optimized surface rendering will use the device's accelerated pipeline to draw the interior of opaque surfaces and/or edges. Add the following lines of code to your LI-1 implementation of each 3D surface primitive. Add the code after front and back distinguishing and after determining whether the surface is opaque or transparent.

if (surface is not transparent /* returned by the util */){ if (blend draw mode == XGL_BLEND_DRAW_NOT_BLENDED){ // draw opaque surface but not the edges if (XGL_CTX_SURF_EDGE_FLAG is TRUE){ // you may do this by setting edges to off and // then restoring the edge flag later // set things up so that only INTERIOR is drawn, // edges are NOT drawn // continue drawing the interior } else if (blend draw mode == XGL_BLEND_DRAW_BLENDED) { // draw nothing or draw edges only if edges are on // if (XGL_CTX_SURF_EDGE_FLAG is TRUE) { // you may do this by setting the interior to // empty and later restoring the fill style // set things up so that only EDGES are drawn, } else { return 1; // nothing needs to be drawn } } } else // surface is transparent { if (blend draw mode == XGL_BLEND_DRAW_NOT_BLENDED) return 1; // nothing needs to be drawn call the software pipeline }

To let the software pipeline handle all rendering of the surfaces, add the following lines of code to your implementation of each 3D surface primitive. Add the code after front and back face distinguishing and after determining whether the surface is opaque or transparent.

if (surface is not transparent) { if (blend draw mode != XGL_BLEND_DRAW_ALL) { call the software pipeline } } else // surface is transparent { if (blend draw mode == XGL_BLEND_DRAW_NOT_BLENDED) return 1; // nothing needs to be drawn call the software pipeline }

If a device does face distinguishing and face culling in hardware, it can optimize code that calls the software pipeline for transparency. You can use an algorithm similar to that shown in the next section on texture mapping.

Calling the Software Pipeline for Texture Mapping

The application can enable texture mapping for front or back surfaces. Two conditions must be met for texture mapping to be enabled: the application must provide texture mapping objects using the RGB window raster, and the input point type must be a data point type if the texture coordinate source is DATA. If a device has not implemented texture mapping, it can call the software pipeline to do texturing.

The device pipeline can optimize its call to the software pipeline for texture mapping by determining whether the application has requested texture mapping for only front surfaces or only back surfaces. In either of those cases, the device pipeline can determine whether the surface is textured and call the software pipeline only if texture mapping is required. The following code sample provides an example.

if (!ctx->getSurfFaceDistinguish()){ if (ctx->getFrontTexturing()) // call the software pipeline } else { if (ctx->getSurfFaceCull() == XGL_CULL_BACK) { if (&& ctx->getFrontTexturing())

// call the software pipeline } else if (ctx->getSurfFaceCull() == XGL_CULL_FRONT) { if (&& ctx->getBackTexturing()) // call the software pipeline } else { // No culling if (&& (ctx->getFrontTexturing() || ctx->getBackTexturing())) // call the software pipeline } }

In this code sample, the device pipeline first determines whether face distinguishing is enabled. If it is not, it checks whether texture mapping objects are present for texturing front faces. If so, the device pipeline calls the software pipeline. If face distinguishing is enabled, the code determines whether back faces are culled and front texture mapping is on. If so, the front surfaces can be sent to the software pipeline for texture mapping. Similarly, if front faces are culled and texture mapping is on for back surfaces, then the back surfaces can be sent to the software pipeline. Finally, if face culling is not enabled and either front or back texture mapping is enabled, the device pipeline can send all the surfaces to the software pipeline for texture mapping.

At the LI-2 level, face distinguishing has already taken place, so it is sufficient to determine whether texture mapping is enabled for front or back surfaces (based on the front flag in the PrimData level 0 field):

if (ctx->get{Front,Back}Texturing()) // fall back to the software pipeline

LI-1 stores the w component for 3D surface primitives. The w values are passed to LI-2 as part of the point list for 3D surface primitives.

Antialiasing and Dithering

If your device does not perform antialiasing or dithering in hardware, your pipeline can use the software pipeline. For software pipeline dithering, check for the following attribute values and then call the software pipeline.

if ((device->getColorType() == XGL_COLOR_RGB) && (device->getRealColorType() != XGL_COLOR_INDEX) // if hw doesn't perform dithering, fall back to the software pipe swp->Li1{primitive}();

For software pipeline antialiasing, check for the value of these attributes.

For 3D markers:

if (ctx->getMarkerAaBlendEq() != XGL_BLEND_NONE || ctx->getMarkerAaFilterWidth() > 1) // fall back to swp if hw doesn't handle antialiasing of dots swp->li1MultiMarker(pl);

For 3D strokes:

if (curr_stroke->getAaBlendEq()) != XGL_BLEND_NONE || curr_stroke->curr_stroke->getAaFilterWidth() > 1) // fall back to swp if hw doesn't handle antialiasing of strokes swp->li1MultiPolyline(bbox, num_lists, pl);

Mapping of API Primitive Calls to LI-1 Functions

Table 9-4 shows the mapping of the 2D API primitives to the 2D LI-1 functions.

Table 9-4

API Function	LI-1 Functions
xgl_annotation_text()	li1AnnotationText()
xgl_context_display_gcache()	li1DisplayGcache()
xgl_multiarc()	li1MultiArc()
xgl_multicircle()	li1MultiCircle()
xgl_multimarker()	li1MultiMarker()

Table 9-4

API Function	LI-1 Functions
xgl_multipolyline()	li1MultiPolyline()
xgl_multirectangle()	li1MultiRectangle()
xgl_multi_simple_polygon()	li1MultiSimplePolygon()
xgl_nurbs_curve()	li1NurbsCurve()
xgl_polygon()	li1Polygon()
xgl_stroke_text()	li1StrokeText()

Table 9-5 shows the mapping of the 3D API primitives to the 3D LI-1 functions.

Table 9-5

API Function	LI-1 Function
xgl_annotation_text()	li1AnnotationText()
xgl_context_display_gcache()	li1DisplayGcache()
xgl_multiarc()	li1MultiArc()
xgl_multicircle()	li1MultiCircle()
xgl_multi_elliptical_arc()	li1MultiEllipticalArc()
xgl_multimarker()	li1MultiMarker()
xgl_multipolyline()	li1MultiPolyline()
xgl_multirectangle()	li1MultiRectangle()
xgl_multi_simple_polygon()	li1MultiSimplePolygon()
xgl_nurbs_curve()	li1NurbsCurve()
xgl_nurbs_surface()	li1NurbsSurf()
xgl_polygon()	li1Polygon()
xgl_quadrilateral_mesh()	li1QuadrilateralMesh()
xgl_stroke_text()	li1StrokeText()
xgl_triangle_list()	li1TriangleList()
xgl_triangle_strip()	li1TriangleStrip()

Table 9-6 shows the mapping of the API raster and pixel operators to the LI-1 functions.

Table 9-6

API Function	LI-1 Function
xgl_context_accumulate()	li1Accumulate()
xgl_context_clear_accumulation()	li1ClearAccumulation()
xgl_context_new_frame()	li1NewFrame()
xgl_context_copy_buffer()	li1CopyBuffer()
xgl_context_flush()	li1Flush()
xgl_context_get_pick_identifiers()	li1PickBufferFlush()
xgl_context_get_pixel()	li1GetPixel()
xgl_image()	li1Image()
xgl_context_set_multi_pixel()	li1SetMultiPixel()
xgl_context_set_pixel()	li1SetPixel()
xgl_context_set_pixel_row()	li1SetPixelRow()

What You Should Know about the Software Pipeline

Software Pipeline Multiplexing

The software pipeline at a particular level can call other functions for processing at the same level or at a lower level. It does this through the opsVec array. For example, the software pipeline LI-1 multipolyline function calls the LI-2 layer multipolyline function with the following call:

    (dp->*((void(XglDpCtx3d::*)(XglPrimData*))
           (dp->opsVec[XGLI_LI2_MULTIPOLYLINE])
          ))(pd);

If the device pipeline has implemented multipolyline functionality at the LI-2 layer, it will assume control at this point; otherwise, the ops_vector setting will forward the rendering call directly back to the software pipeline.

Some software pipeline functions call other LI-1 functions to perform operations. For example, the software pipeline stroke text li1StrokeText() function calls the device pipeline LI-1 multipolyline function through the opsVec to display a string of text as multipolylines. As another example, the software pipeline li1DisplayGcache() function calls the LI-1 primitive that corresponds to the type of geometry in the Gcache. The software pipeline calls back the device pipeline through the opsVec array; the array pointer for that primitive determines whether the device pipeline or the software pipeline will render the primitive.

Software Pipeline Backing Store

The software pipeline functions include a flag for backing store control. This flag, do_retained, is set by XGL core and passed to the software pipeline. However, this flag does not exist in device pipeline functions, and the device pipeline does not need to include it in calls to the software pipeline functions.

Surface Color in the Software Pipeline

Surface color selection is handled as follows for software pipeline LI-1 and LI-2 functions:

• At LI-1, if lighting is on, color selection is applied before lighting. If there is no lighting, color selection is done at LI-2.
• At LI-1, if depth cueing is on and depth cue interpolation is on, then depth cueing is done at each vertex, and the depth cued color is stored at the vertices of the output point list.

  If depth cue interpolation is off, and if incoming point list has vertex color (as a part of the point type or due to vertex lighting), then depth cueing is done at each vertex, and the output color is stored at the vertices of the output point list. However, if the incoming point list has facet color or if the color is obtained from the Context object, then depth cueing is done only once per facet, and the depth-cued color is stored in the first vertex of each point list.

• Color selection is performed at LI-2, if there is no lighting or depth cueing,
• If texture mapping is on, no color selection is done at LI-1, and all color selection is done at LI-2.

Texture Mapping in the Software Pipeline

If texture mapping is enabled (the application must have defined at least one Data Map Texture object or Texture Map object), the software pipeline processing of surface primitives changes.

Texture Mapping at LI-1

At LI-1, if texturing is enabled, the surface primitive is not lit, since the diffuse color for lighting is not known until LI-3 when texturing takes place. Therefore, lighting coefficients are computed at LI-1 and stored in the XglPrimData object. In addition, depth cueing is deferred until LI-3.

Texture Mapping at LI-2

At LI-2, the following steps occur:

1. The (u,v) values for the span are computed using hyperbolic interpolation and are passed to LI-3 using the class XgliUvSpanInfo3d.

2. The lighting coefficients, if present are also computed at the spans and passed to LI-3 using XgliUvSpanInfo3d.

3. The MipMap level in which the start of the span is located and the delta is computed and passed to LI-3 using XgliUvSpanInfo3d.

See the section beginning on page 343 for information on XgliUvSpanInfo3d.

Texture Mapping at LI-3

At LI-3, the (u,v) value and the lighting coefficient at a pixel are determined. The (u,v) value is used to look up the texture map to obtain the texture value (texel). Depending on the control parameters present in the Texture Map object, the texel is combined with the pixel color to obtain the final textured pixel (lighting and depth cueing are done as applicable). Note that there may be more than one texture active, and the final textured pixel is the result after applying all active textures. See page 343 for more information.

Note that the device pipeline must implement texture mapping at LI-3 or use RefDpCtx. RefDpCtx performs all operations for rendering at the LI-3 level.

LI-1 Functions

About the LI-1 Layer

The LI-1 layer specifies the loadable interface that lies just below the XGL API. An XGL loadable pipeline writer for a high-end graphics platform that supports a broad range of functionality would probably choose the LI-1 interface as the basis for an XGL port. Functions within the LI-1 layer implement the geometry pipeline for each primitive; that is, for graphics primitive operations, the functions take as an argument the points defining the primitive, and transform, light (for the 3D case), clip, and depth cue (for the 3D case) in preparation for the rendering operations performed in LI-2 and LI-3.

LI-1 Operations in the Software Pipeline

Processing within the LI-1 layer transforms and clips points to device coordinates that can be used for rendering. The following operations are performed within the software pipeline LI-1 layer:

1. Model clip.

2. Transform vertices from model coordinates to world coordinates.

3. Process face culling and face distinguishing.

4. Light vertices (if necessary).

5. Transform vertices from world coordinates to device coordinates.

6. View clip. If necessary, perform rational w-clip (object is clipped to two planes w = +- epsilon) and divide by w.

7. Pick the primitive.

8. Divide by w.

9. Depth cue.

Thus, an LI-1 device pipeline implementation of a primitive will incorporate these operations, although the order of the operations may differ.

Mapping of LI-1 to LI-2 Functions in the Software Pipeline

While the LI-1 interface has a nearly one-to-one mapping of functions defined at the XGL API, at LI-2 there is a more limited set of functions. Complex LI-1 primitives, such as stroke text, do not have a corresponding interface at LI-2; instead, these primitives must be converted to a mix of simpler, component primitives before rendering.

Table 9-7 shows the mapping of the 2D LI-1 primitives to the LI-1 or LI-2 functions that they call. A hardware port of a given primitive at the LI-1 layer is free to ignore the layers below it and call whatever functions it wishes.

Table 9-7

LI-1 Function	LI-1 or LI-2 Function
li1AnnotationText	li1MultiPolyline
li1MultiArc	li2MultiEllipticalArc li1MultiPolyline li1Polygon
li1MultiCircle	li2MultiEllipse li1Polygon
li1MultiMarker	li1MultiPolyline li2MultiDot
li1MultiPolyline	li2MultiPolyline
li1MultiRectangle	li1MultiSimplePolygon
li1MultiSimplePolygon	li1Polygon
li1NurbsCurve	li1MultiMarker li1MultiPolyline
li1Polygon	li2GeneralPolygon
li1StrokeText	li1MultiPolyline

Table 9-8 shows the mapping of the 3D LI-1 primitives to LI-1 or LI-2 functions.

Table 9-8

LI-1 Function	LI Function
li1AnnotationText	li1MultiPolyline
li1MultiArc - regular arcs	(open)li1MultiPolyline
li1MultiArc - annotation arcs	(closed)li1MultiSimplePolygon (open)li2MultiPolyline (closed)li2GeneralPolygon
li1MultiCircle - regular circles	li1MultiSimplePolygon
li1MultiCircle - annotation circles	li2GeneralPolygon
li1MultiEllipticalArc - regular arcs	(open)li1MultiPolyline (closed)li1MultiSimplePolygon
li1MultiEllipticalArc - annotation elliptical arcs	(open)li2MultiPolyline (closed)li2GeneralPolygon
li1MultiMarker	li1MultiPolyline li2MultiDot
li1MultiPolyline	li2MultiPolyline
li1MultiRectangle - regular rectangles	li1MultiSimplePolygon
li1MultiRectangle - annotation rectangles	li2GeneralPolygon
li1MultiSimplePolygon	li1Polygon li2MultiSimplePolygon
li1NurbsCurve	li1MultiMarker li1MultiPolyline
li1NurbsSurf	li1MultiMarker li1TriangleList li1QuadrilateralMesh li1MultiPolyline
li1Polygon	li2GeneralPolygon
li1QuadrilateralMesh	li2TriangleStrip

Table 9-8

LI-1 Function	LI Function
li1StrokeText	li1MultiPolyline
li1TriangleList	li2TriangleStrip li2TriangleList li2GeneralPolygon
li1TriangleStrip	li2GeneralPolygon li2TriangleStrip

LI-1 Attributes

The following sections provide information on the attributes that each LI-1 primitive must handle. For more information on the attributes that a particular primitive must handle, see the man page for the primitive.

li1AnnotationText() - 2D/3D

Overview

li1AnnotationText() renders text on a plane parallel to the display surface. See the xgl_annotation_text man page for information on functionality that the device pipeline needs to handle.

Syntax

[2D]void XglDpCtx2d::li1AnnotationText(
    void*           string,
    Xgl_pt_f2d*     ref_pos,
    Xgl_pt_f2d*     ann_pos);

[3D]void XglDpCtx3d::li1AnnotationText(
    void*           string,
    Xgl_pt_f3d*     ref_pos,
    Xgl_pt_f3d*     ann_pos);

Input Parameters string

A NULL-terminated C-style list of characters if the character encoding is single-string encoding, or a pointer to a Xgl_mono_text_list structure if the character encoding is multi-string encoding.

ref_pos	The reference point for the text string.
ann_pos	ann_pos is added to the transformed reference position to obtain the annotation point.

Attributes That the Device Pipeline Needs to Handle The device pipeline must account for some or all of the attributes listed in the xgl_annotation_text man page.

Description of the Software Pipeline li1AnnotationText Function The software pipeline li1AnnotationText() function takes as input a single point, which is the reference position for the starting point of the string. The reference point is clipped against the window boundaries, and if it is outside the window boundaries, no text is drawn, even if part of the string would be visible.

If the reference point is inside the window boundaries, the function sets up the viewing matrices and translates the string input into points in a multipolyline point list. The multiplyline is set up to draw the text at ann_pos at the appropriate scale. The function provides API arguments for input to the multipolyline interface and calls li1MultiPolyline().

If the device pipeline falls back to the software pipeline to render li1AnnotationText(), the device pipeline li1MultiPolyline() function is called.

li1DisplayGcache() - 2D/3D

Overview The li1DisplayGcache() function renders the geometry stored in the XGL device-indepedent Gcache object. The li1DisplayGcache() operator is different from other LI-1 functions because the Gcache object is an object that can contain any of a number of different primitives. See the Solaris XGL Reference Manual for information on Gcache functions and attributes.

The main parameter to li1DisplayGcache() is a pointer to an XGL Gcache object. This object is the implementation of the API Gcache functions, so it has member functions for getting and setting attributes and functions for caching incoming primitives. The pipeline does not need to use these functions.

The pipeline's task is to determine what type of primitive the Gcache contains, and then access the data for that primitive and display it. However, there is relatively little advantage for a pipeline to supply its own li1DisplayGcache() function because the software pipeline handles all the work of determining the primitive, casting the data structures to the correct primitive, and calling the LI-1 function for that primitive. For example, if a text string is stored in a Gcache, the text is converted into polylines; then, when xgl_display_gcache() is called, the XGL core ensures that the cached polyline is rendered with the correct stroke attributes, and the software pipeline li1DisplayGcache() function accesses the data for the polylines and calls the li1MultiPolyline() function (which may or may not be supported by the device pipeline). Note that the software pipeline calls LI-1 functions for each of the Gcache primitives.

A device pipeline would want to implement li1DisplayGcache() for one of two reasons:

1. If for some reason the performance gain is such that the device pipeline can access the stored data faster than the XGL core can, and if the applications that the device pipeline implementor wants to capture will be using Gcaches extensively, it may be worth the effort to implement li1DisplayGcache().

2. The XGL architecture provides a mechanism for the device pipeline to store device-dependent data within the Gcache. The device pipeline may be able to access the device-dependent data more efficiently than if device-

independent Gcache data is used. Alternately, the device pipeline may choose to store the data on the device and then keep a pointer to the data in the Gcache; this approach would cut down on data transport to the device.

Information on implementing li1DisplayGcache() and the mechanism for storing device-dependent data in the Gcache is provided below.

Syntax

Xgl_cache_display XglDpCtx{2,3d}::li1DisplayGcache(
    XglGcache*      gcache
    Xgl_boolean     test,
    Xgl_boolean     display);

Input Parameters gcache

Pointer to an XGL Gcache object.

test	Boolean value that determines whether the saved state of the Gcache (attribute settings) is compared with the current state in the Context. See the xgl_context_display_gcache man page for more information.
display	Boolean value that determines whether the Gcache is rendered. See the xgl_context_display_gcache man page for more information.

Attributes That the Device Pipeline Needs to Handle A device pipeline implementation of li1DisplayGcache() must handle the attributes for each primitive that may be called to render the geometry in the Gcache.

What You Need to Know to Implement li1DisplayGcache() If the device pipeline supplies an implementation of the li1DisplayGcache() function, it will have to use the Gcache object in XglGcache.h as well as any one of a number of other objects that are defined as XglGcachePrim objects in XglGcachePrim*.h. The Gcache primitive objects are:

XGL_GCACHE_PRIM_MARKER                        Markers
XGL_GCACHE_PRIM_MPLINE                        Multipolylines
XGL_GCACHE_PRIM_TEXT                          Stroke text
XGL_GCACHE_PRIM_PGON                          Polygons
XGL_GCACHE_PRIM_MSPG                          Multisimple polygons
XGL_GCACHE_PRIM_TSTRIP                        Triangle strips
XGL_GCACHE_PRIM_NURBS_CURVE                   NURBS curves
XGL_GCACHE_PRIM_NURBS_SURF                    NURBS surfaces
XGL_GCACHE_PRIM_MELLA                         Multi elliptical arcs

The li1DisplayGcache() function does the following: First, it processes the arguments test and display appropriately. Secondly, it calls the Gcache object getOrigPrimType() function, and then, depending on the original primitive type, the li1DisplayGcache() function uses the Gcache object getGcachePrim() function to get a pointer to the object representing the cached geometry. The pointer must be cast to the object for that primitive type.

The following code from the software pipeline li1DisplayGcache() function illustrates the sequence of events in rendering for each of the Gcache primitive types. You can copy or modify this source code sample as long as the resulting code is used to create a loadable pipeline for XGL.

XglSwpCtx3dDef::li1DisplayGcache(Xgl_gcache gcache_obj, Xgl_boolean test, Xgl_boolean display, Xgl_boolean do_retained) { XglGcache* gcache; XglGcachePrim* prim; Xgl_cache_display ret_val; Xgl_boolean do_display; Xgl_usgn32 num_model_clip_planes; gcache = (XglGcache*) gcache_obj; prim = gcache->getGcachePrim(); if (prim == NULL) { return (XGL_CACHE_NOT_CHECKED); } if ((prim->getDisplayPrimType() != XGL_PRIM_NONE) && !prim->getSavedCtxIs3d() ) { return(XGL_CACHE_NOT_CHECKED); /* ctx dims don't match; best fit */

} if (test) { if ((prim->getDisplayPrimType() != XGL_PRIM_NONE) && (prim->validate(ctx))) { do_display = display; ret_val = XGL_CACHE_DISPLAY_OK; } else { do_display = FALSE; ret_val = XGL_CACHE_ATTR_STATE_DIFFERENT; } } else { do_display = display; ret_val = XGL_CACHE_NOT_CHECKED; } if ((prim->getDisplayPrimType() == XGL_PRIM_NONE) || !do_display) return ret_val; if (prim->wasModelClipped() && ((ret_val == XGL_CACHE_DISPLAY_OK) || gcache->getBypassModelClip())) { num_model_clip_planes = ctx->getModelClipPlaneNum(); xgl_object_set(ctx, XGL_3D_CTX_MODEL_CLIP_PLANE_NUM,0,0); } else num_model_clip_planes = 0; switch (gcache->getOrigPrimType()) { case XGL_PRIM_STROKE_TEXT: { XglGcachePrimText*gp_text = (XglGcachePrimText *) gcache->getGcachePrim(); Xgl_geom_status status; if (gp_text->getDisplayPtListList()->num_pt_lists < 1) return ret_val; xgl_context_check_bbox(ctx,XGL_PRIM_MULTIPOLYLINE, gp_text->getPlm()->get_pll_bbox(),&status); if ((status & XGL_GEOM_STATUS_VIEW_REJECT) || (status & XGL_GEOM_STATUS_MODEL_REJECT)) return ret_val;

XGLI_3D_DP(void, XGLI_LI1_MULTIPOLYLINE, (Xgl_bbox*,Xgl_usgn32,Xgl_pt_list*, Xgl_boolean), (NULL, gp_text->getDisplayPtListList() ->num_pt_lists, gp_text->getDisplayPtListList()->pt_lists, FALSE)) } break; case XGL_PRIM_NURBS_SURFACE: { XglGcachePrimNSurf*gp_nsurf = (XglGcachePrimNSurf*) gcache->getGcachePrim(); void* cache_data = gp_nsurf->getCacheData(); if(cache_data == NULL){ XglNurbsSurfData* apiData = gp_nsurf->getApiData(); if(apiData->surface->order_u == 1 || apiData->surface->order_v == 1) { Xgl_pt_list plist; plist.pt_type = apiData->surface->ctrl_pts.pt_type; plist.num_pts = apiData->surface->ctrl_pts.num_pts; plist.bbox = NULL; plist.pts.f3d = apiData->surface->ctrl_pts.pts.f3d; ctx->assignCurStrokeAsMarker(); XGLI_3D_DP(void, XGLI_LI1_MULTIMARKER, (Xgl_pt_list*, Xgl_boolean), (&plist, FALSE)) ctx->assignCurStrokeAsLine(); break; } else { XglSwpNurbs nurbs(ctx, viewGrpItf, TRUE); cache_data = nurbs.setUsrData(gp_nsurf->getApiData(), gp_nsurf->getGcacheMode(), TRUE); gp_nsurf->setCacheData(cache_data); } }

XGLI_3D_DP(void, XGLI_LI1_NURBS_SURFACE, (Xgl_nurbs_surf*, Xgl_trim_loop_list*, Xgl_nurbs_surf_simple_geom*, Xgl_surf_color_spline*, Xgl_surf_data_spline_list*, void*, Xgl_boolean), (NULL, NULL, NULL, NULL, NULL, cache_data, FALSE)) } break; case XGL_PRIM_NURBS_CURVE: { XglGcachePrimNCurve*gp_ncurve = (XglGcachePrimNCurve *)gcache->getGcachePrim(); void* cache_data = gp_ncurve->getCacheData(); if(cache_data == NULL){ XglNurbsCurveData* apiData = gp_ncurve ->getApiData(); if(apiData->curve->order == 1) { Xgl_pt_list plist; plist.pt_type = apiData->curve->ctrl_pts.pt_type; plist.num_pts = apiData->curve->ctrl_pts.num_pts; plist.bbox = NULL; plist.pts.f3d = apiData->curve->ctrl_pts.pts.f3d; ctx->assignCurStrokeAsMarker(); XGLI_3D_DP(void, XGLI_LI1_MULTIMARKER, (Xgl_pt_list*, Xgl_boolean), (&plist, FALSE)) ctx->assignCurStrokeAsLine(); break; } else { XglSwpNurbs nurbs(ctx, viewGrpItf, TRUE); cache_data = nurbs.setUsrData (gp_ncurve->getApiData(), gp_ncurve->getGcacheMode(), TRUE); gp_ncurve->setCacheData(cache_data); }

} ctx->assignCurStrokeAsLine(); XGLI_3D_DP(void, XGLI_LI1_NURBS_CURVE, (Xgl_nurbs_curve*, Xgl_bounds_f1d*, Xgl_curve_color_spline*, void*, Xgl_boolean), (NULL, NULL, NULL, cache_data, FALSE)) } break; case XGL_PRIM_TRIANGLE_STRIP: { XglGcachePrimTstrip*gp_tstrip = (XglGcachePrimTstrip*)gcache->getGcachePrim(); register int i; register Xgl_pt_list_list*display_pll = gp_tstrip->getDisplayPtListList(); register Xgl_facet_list_list*display_fll = gp_tstrip->getDisplayFacetListList(); for (i = 0; i < display_pll->num_pt_lists; i++) { XGLI_3D_DP(void, XGLI_LI1_TRIANGLE_LIST, (Xgl_facet_list*, Xgl_pt_list*, Xgl_tlist_flags, Xgl_boolean), (NULL, &(display_pll->pt_lists[i]), XGL_TLIST_FLAG_USE_VTX_FLAGS, FALSE)) } else for (i = 0; i < display_fll->num_facet_lists; i++) { XGLI_3D_DP(void, XGLI_LI1_TRIANGLE_STRIP, (Xgl_facet_list*, Xgl_pt_list*, Xgl_boolean), (&(display_fll->facet_lists[i]), &(display_pll->pt_lists[i]), FALSE)) } } break; case XGL_PRIM_POLYGON: { Xgl_boolean do_orig_pgon;

Xgl_boolean edges; XglGcachePrimPgon*gp_pgon = (XglGcachePrimPgon*) gcache->getGcachePrim(); do_orig_pgon = FALSE; if ((gcache->getDisplayPrimType() == XGL_PRIM_MULTI_SIMPLE_POLYGON) && (gcache->getDoPolygonDecomp())) { /* The pgon has been decomposed */ /* into a list of triangle stars */ Xgl_surf_fill_stylefill_style; Xgl_pt_list_list*decomp_pll; Xgl_pt_list_list*display_pll; Xgl_facet_list*decomp_fl; Xgl_boolean front_facing = TRUE; Xgl_pt_f3d* normal; Xgl_booleando_silhouette = FALSE; Xgl_boolean use_front_attributes, use_back_attributes; Xgl_surf_fill_style front_style; Xgl_surf_fill_style back_style; Xgl_boolean distinguish; Xgl_surf_cull_mode cull_mode; decomp_pll = gp_pgon->getDecompPtListList(); display_pll = gp_pgon->getDisplayPtListList(); decomp_fl = gp_pgon->getDecompFacetList(); front_style = ctx->getSurfFrontFillStyle(); back_style = ctx->getSurfBackFillStyle(); cull_mode = ctx->getSurfFaceCull(); distinguish = ctx->getSurfFaceDistinguish(); /* find out what attributes will be used */ if (distinguish) { switch (cull_mode) { case XGL_CULL_OFF: use_front_attributes = TRUE; use_back_attributes = TRUE; break; case XGL_CULL_BACK:

use_front_attributes = TRUE; use_back_attributes = FALSE; break; case XGL_CULL_FRONT: use_front_attributes = FALSE; use_back_attributes = TRUE; break; } } else { use_front_attributes = TRUE; use_back_attributes = FALSE; } if (use_front_attributes) fill_style = front_style; else fill_style = back_style; /* see if orig pgon data must be used to avoid seeing */ /* the tessalation */ if (distinguish) { if (cull_mode == XGL_CULL_FRONT && back_style == XGL_SURF_FILL_HOLLOW) do_orig_pgon = TRUE; else if (cull_mode == XGL_CULL_BACK && front_style == XGL_SURF_FILL_HOLLOW) do_orig_pgon = TRUE; } else if (front_style == XGL_SURF_FILL_HOLLOW) do_orig_pgon = TRUE; /* now the biggie - see if we need to determine the pgon */ /* facing */ if (!do_orig_pgon && use_front_attributes && use_back_attributes && front_style != back_style && (front_style == XGL_SURF_FILL_HOLLOW || back_style == XGL_SURF_FILL_HOLLOW)) { /* determine if pgon is front or back facing */ switch (decomp_fl->facet_type) { case XGL_FACET_NORMAL: normal = &(decomp_fl->facets.normal_facets->normal);

break; case XGL_FACET_COLOR_NORMAL: normal = &(decomp_fl->facets.color_normal_facets ->normal); break; } /* if culled were done */ front_facing = (XgliUtFaceDistinguish(ctx, normal, display_pll->pt_lists->pts.f3d, viewGrpItf) == ctx->getSurfFrontAttr3d()); if (front_facing && (cull_mode == XGL_CULL_FRONT)) return ret_val; if (!front_facing && (cull_mode == XGL_CULL_BACK)) return ret_val ; if (front_facing) fill_style = front_style; else fill_style = back_style; } do_silhouette = ctx->getSurfSilhouetteEdgeFlag(); if (!gcache->getShowDecompEdges() && !(do_silhouette && fill_style == XGL_SURF_FILL_EMPTY && ctx->getSurfEdgeFlag() == FALSE) && fill_style == XGL_SURF_FILL_HOLLOW) do_orig_pgon = TRUE; if (!do_orig_pgon) { if (gp_pgon->getPgonConvex()) { XGLI_3D_DP(void, XGLI_LI1_MULTI_SIMPLE_POLYGON, (Xgl_facet_flags, Xgl_facet_list*, Xgl_bbox*, Xgl_usgn32, Xgl_pt_list*, Xgl_boolean), (gp_pgon->getMspgFlags(), decomp_fl, display_pll->bbox, 1, display_pll->pt_lists, FALSE)) } else { edges = ctx->getSurfEdgeFlag(); if (edges && !gcache->getShowDecompEdges())

ctx->setSurfEdgeFlag(FALSE); /* pgon was decomposed into an msp list */ decomp_pll = gp_pgon->getDecompPtListList(); if(decomp_pll->num_pt_lists){ XGLI_3D_DP(void, XGLI_LI1_MULTI_SIMPLE_POLYGON, (Xgl_facet_flags, Xgl_facet_list*, Xgl_bbox*, Xgl_usgn32, Xgl_pt_list*, Xgl_boolean),(gp_pgon->getMspgFlags(), gp_pgon->getDisplayFacetListList() ->facet_lists,decomp_pll->bbox, decomp_pll->num_pt_lists, decomp_pll->pt_lists, FALSE)) } } /* turn edges on and render orig polygon as empty */ if (edges && !gcache->getShowDecompEdges() && !gp_pgon ->getPgonConvex()) { ctx->setSurfEdgeFlag(TRUE); if (front_facing) ctx->setSurfFrontFillStyle(XGL_SURF_FILL_EMPTY); else ctx->setSurfBackFillStyle(XGL_SURF_FILL_EMPTY); Xgl_pt_list_list*pgon_pll = gp_pgon ->getPgonPtListList(); if (pgon_pll->num_pt_lists == 0) { return ret_val; } if(pgon_pll->num_pt_lists){ XGLI_3D_DP(void, XGLI_LI1_POLYGON, (Xgl_facet_type, Xgl_facet*, Xgl_bbox*, Xgl_usgn32, Xgl_pt_list*, Xgl_boolean), (gp_pgon->getPgonFacetType(), gp_pgon->getPgonFacetPtr(), pgon_pll->bbox, pgon_pll->num_pt_lists, pgon_pll->pt_lists, FALSE)) }

/* restore fill style */ if (front_facing) ctx->setSurfFrontFillStyle(fill_style); else ctx->setSurfBackFillStyle(fill_style); } } } if (gcache->getDisplayPrimType() == XGL_PRIM_POLYGON || do_orig_pgon) { if (gcache->getUseApplGeom()) { Xgl_pt_list_list*appl_pll = gp_pgon ->getApplPtListList(); if(appl_pll->num_pt_lists == 0) return ret_val; XGLI_3D_DP(void, XGLI_LI1_POLYGON, (Xgl_facet_type, Xgl_facet*, Xgl_bbox*, Xgl_usgn32, Xgl_pt_list*, Xgl_boolean), (gp_pgon->getPgonFacetType(), gp_pgon->getPgonFacetPtr(), appl_pll->bbox, appl_pll->num_pt_lists, appl_pll->pt_lists, FALSE)) } else { Xgl_pt_list_list*pgon_pll = gp_pgon ->getPgonPtListList(); if (pgon_pll->num_pt_lists == 0) { return ret_val; } XGLI_3D_DP(void, XGLI_LI1_POLYGON, (Xgl_facet_type, Xgl_facet*, Xgl_bbox*, Xgl_usgn32, Xgl_pt_list*, Xgl_boolean), (gp_pgon->getPgonFacetType(), gp_pgon->getPgonFacetPtr(), pgon_pll->bbox, pgon_pll->num_pt_lists, pgon_pll->pt_lists, FALSE)) } }

} break; case XGL_PRIM_ELLIPTICAL_ARC: { XglGcachePrimMella*gp_mella = (XglGcachePrimMella *)gcache->getGcachePrim(); if(gp_mella->getDisplayPtListList()->num_pt_lists < 1) return ret_val; if (gcache->getDisplayPrimType() == XGL_PRIM_MULTIPOLYLINE) { XGLI_3D_DP(void, XGLI_LI1_MULTIPOLYLINE, (Xgl_bbox*,Xgl_usgn32,Xgl_pt_list*, Xgl_boolean), (NULL, gp_mella->getDisplayPtListList() ->num_pt_lists, gp_mella->getDisplayPtListList() ->pt_lists, FALSE)) } else if (gcache->getDisplayPrimType() == XGL_PRIM_MULTI_SIMPLE_POLYGON) { XGLI_3D_DP(void, XGLI_LI1_MULTI_SIMPLE_POLYGON, (Xgl_facet_flags, Xgl_facet_list*, Xgl_bbox*, Xgl_usgn32, Xgl_pt_list*, Xgl_boolean), (XGL_FACET_FLAG_SHAPE_CONVEX, gp_mella->getDisplayFacetListList() ->facet_lists, NULL, gp_mella->getDisplayPtListList() ->num_pt_lists, gp_mella->getDisplayPtListList() ->pt_lists, FALSE)) } } break; case XGL_PRIM_MULTI_SIMPLE_POLYGON: { Xgl_boolean do_orig_pgon; Xgl_boolean edges;

XglGcachePrimMspg*gp_mspg = (XglGcachePrimMspg *) gcache->getGcachePrim(); Xgl_pt_list_list* pll; Xgl_facet_list_list* fll; Xgl_usgn32 mspg_flags; Xgl_usgn32npl; do_orig_pgon = FALSE; edges = ctx->getSurfEdgeFlag(); Xgl_surf_fill_style front_style; Xgl_surf_fill_style back_style; Xgl_boolean distinguish; Xgl_surf_cull_mode cull_mode; front_style = ctx->getSurfFrontFillStyle(); back_style = ctx->getSurfBackFillStyle(); cull_mode = ctx->getSurfFaceCull(); distinguish = ctx->getSurfFaceDistinguish(); if (!distinguish && front_style == XGL_SURF_FILL_HOLLOW) do_orig_pgon = TRUE; else if (cull_mode == XGL_CULL_OFF && (front_style == XGL_SURF_FILL_HOLLOW || (back_style == XGL_SURF_FILL_HOLLOW && distinguish))) do_orig_pgon = TRUE; else if (cull_mode == XGL_CULL_FRONT && (distinguish && back_style == XGL_SURF_FILL_HOLLOW)) do_orig_pgon = TRUE; else if (cull_mode == XGL_CULL_BACK && front_style == XGL_SURF_FILL_HOLLOW) do_orig_pgon = TRUE; if (do_orig_pgon || edges) { if (gcache->getUseApplGeom()) { if(npl = gp_mspg->getApplPtListList()->num_pt_lists) { mspg_flags = gp_mspg->getApplMspgFlags(); pll = gp_mspg->getApplPtListList(); fll = gp_mspg->getApplFacetListList(); } } else { if(npl = gp_mspg->getDisplayPtListList()->num_pt_lists) { mspg_flags = gp_mspg->getApplMspgFlags();

pll = gp_mspg->getDisplayPtListList(); fll = gp_mspg->getDisplayFacetListList(); } } } else { if(npl = gp_mspg->getDisplayPtListList()->num_pt_lists) { mspg_flags = gp_mspg->getMspgFlags(); pll = gp_mspg->getDisplayPtListList(); fll = gp_mspg->getDisplayFacetListList(); } } if(npl) { XGLI_3D_DP(void, XGLI_LI1_MULTI_SIMPLE_POLYGON, (Xgl_facet_flags, Xgl_facet_list*, Xgl_bbox*, Xgl_usgn32, Xgl_pt_list*, Xgl_boolean), (mspg_flags, fll->facet_lists, NULL, npl, pll->pt_lists, FALSE)) } } break; case XGL_PRIM_MULTIMARKER: { XglGcachePrimMarker*gp_marker = (XglGcachePrimMarker *)gcache->getGcachePrim(); Xgl_pt_list_list* pll = gp_marker ->getDisplayPtListList(); if (pll->num_pt_lists < 1) return ret_val; XGLI_3D_DP(void, XGLI_LI1_MULTIMARKER, (Xgl_pt_list*, Xgl_boolean), (pll->pt_lists, FALSE)) } break; case XGL_PRIM_MULTIPOLYLINE: { XglGcachePrimMpline*gp_mpline = (XglGcachePrimMpline *)gcache->getGcachePrim();

Xgl_pt_list_list* pll = gp_mpline ->getDisplayPtListList(); if (pll->num_pt_lists < 1) return ret_val; XGLI_3D_DP(void, XGLI_LI1_MULTIPOLYLINE, (Xgl_bbox*,Xgl_usgn32,Xgl_pt_list*, Xgl_boolean), (NULL, pll->num_pt_lists, pll->pt_lists, FALSE)) } default: break; } /* end switch */ if (num_model_clip_planes > 0) ctx->setModelClipPlaneNum(num_model_clip_planes); return ret_val; }

XglGcache Functions Relevant to the Pipeline The device pipeline does not need to use many of the functions in XglGcache.h. The functions relevant to the pipeline are listed in Table 9-9.

Table 9-9

Function	Description
getOrigPrimType()	Returns the type of theoriginal primitive.
getGcachePrim()	Returns the type of the cached primitive.
getPlm()	Returns a point list manager object. See PlManager.h.
getFlm()	Returns a facet list manager object. See FlManager.h.

Implementing a Device-Dependent Gcache The device-dependent (DD) Gcache facility allows the device pipeline to store device-dependent information with the Gcache. This device-dependent information may allow the device pipeline to render the Gcache more efficiently than the XGL core; however, the device-independent part of the Gcache remains, and it is available for the device to use. This allows the device to fall back to the software pipeline for the display of the Gcache.

The API interface to the Gcache object does not change. The application will not know about the DD part of a Gcache. The validation of a Gcache is still be done by the the XGL core; only the display of the Gcache is device dependent.

The approach for device-dependent Gcache information is that the device pipeline translates the DI Gcache primitive information into its own format. The device pipeline then associates this translation with the DI Gcache. There is a protocol between the DI Gcache and the device pipeline to manage the life cycle of the translation.

Semantics of Device-Dependent Gcache There is no explicit function to create a DD Gcache. When the device pipeline's li1DisplayGcache() function is called, it can implicitly create a DD translation. It is then up to the device pipeline to associate this translation with the DI Gcache. Once the association is made, the DI Gcache and the device must tell each other to remove the DD translation for the DI Gcache. The following actions will cause the DD translation to be removed from the DI Gcache:

1. The device is destroyed (where device is one of DpCtx, DpDev, DpMgr, or DpLib).

2. The device decides the translation is no longer valid (e.g. out of resource, attributes changed, etc).

3. The DI Gcache is destroyed.

4. The DI Gcache gets a new primitive.

The DI Gcache and the device use a translation identifier to refer to the DD translation. This ID must be an address so it is unique within the XGL system; we suggest that it be the address of a DpCtx, DpDev, DpMgr, or DpLib object. This allows the device to choose the scope of the DD translation; that is, the

translation could be valid for just a DpCtx or for all DpCtx's associated with a DpMgr. Thus, the ID is the address of an object already under the control of the device pipeline.

The same ID is used for all Gcaches. Thus, for example, for every Gcache, the pipeline can use the address of the DpCtx object as the identifier to show that this DD translation belongs to this DpCtx object. The ID of a DD translation is the same for all the translations under the control of the device pipeline. (Remember that for each unique Context and Device pair, there is a unique DpCtx object, so if there are two Contexts associated with a Device, there is a unique DpCtx object for each Context.)

XglGcache Functions for Managing a DD Translation In the XglGcache.h class, the following functions allow a device to manage a DD translation.

Xgl_boolean
addDdTranslation(XgliDdGcacheTranslation* dd_trans)

The device pipeline tells the DI Gcache to add a new translation. The new object is added to the DI Gcache's store of translations. TRUE is returned if the operation was successful, and FALSE is returned otherwise. It is up to the device pipeline to delete dd_trans if the addition fails.

Note that it is not guaranteed that a DI Gcache will accept a DD translation. The device must ask the Gcache object whether it will accept the translation. Therefore, code should be written to anticipate the case in which a DD translation is not accepted. In the current implementation, a Gcache can store only one DD translation. If more than one DD translation is added, the second translation is not be allowed. In the future, more than one DD translation per device/context pair may be allowed.

XgliDdGcacheTranslation*
lookUpTranslation(void* dd_trans_id,
                                Xgl_boolean* room_for_more)

The device pipeline uses this function to look up a dd_trans_id to see if this Gcache has a dd_trans for this pipeline. If the look up fails, NULL is returned. In this case, the room_for_more boolean indicates if the DI Gcache will accept new translations. If it is FALSE, the the pipeline should not bother building a new translation and calling addDdTranslation().

void
removeDdTranslation(void* dd_trans_id)

This function is invoked by the pipeline to tell the DI Gcache to remove the DD translation with the given ID. The XGL core does not delete the translation. This function enables the device to clean up its database of DD translations before deleting the DD translation object. This is easier to do with an explicit destroy function (which is only called by the DI Gcache) than by having the XGL core delete the translation. The DI Gcache will call the destroy function, and then the DD code should clean up the translation and delete the object.

DD Translation Object The class XgliDdGcacheTranslation in the file DdGcacheTranslation.h acts as a wrapper for the DD translation. This class provides a standard way of handling DD translations. Devices should subclass this class for their own use. When the pipeline subclasses this class, it can then add its own data for the DD Gcache.

Thus, to create a DD translation object, the pipeline subclasses the XgliDdGcacheTranslation class, creates an object of the subclass, and returns a pointer to the object and casts the pointer as an XgliDdGcacheTranslation pointer.

Example for Device-Dependent Gcache The following pseudo-code is an example device pipeline li1DisplayGcache() function. The example shows how the Gcache object functions are used to manage the DD translations. You can copy or modify this source code sample as long as the resulting code is used to create a loadable pipeline for XGL.

In this example, the call to lookUpDdTranslation() returns a pointer to the DD translation object, thus getting the ID for the DD translation. In addition, a pointer to a Boolean value that indicates whether there is room for a translation is returned. If dd_trans is NULL and room_for_more is TRUE, then a

DD Gcache object does not already exist, so the pipeline can build its own. When the DD Gcache is built, the function addDdTranslation() stores it in the Gcache, and it can then be displayed.

// DpCtx Li1DisplayGcache // This is where dd translations are build. // DpCtx::Li1DisplayGcache(.., di_gcache, ..) { Xgl_boolean room_for_more; XgliDdGcacheTranslation* dd_tran; dd_tran = di_gcache->lookUpDdTranslation(tran_id, &room_for_more); if ((dd_tran == NULL) && room_for_more) { // build dd_tran dd_tran = build_my_dd_gcache(); if (di_gcache->addDdTranslation(dd_tran) == FALSE) { delete dd_tran; dd_tran = NULL; } } if (dd_tran != NULL) { my_display_dd_gcache(dd_tran); } }

It is up to the device pipeline to determine whether dd_trans is valid for one context, one device, one particular DpMgr object (which would include all windows on a frame buffer), etc. This is a device-dependent decision. Most applications use one context and one device.

Whenever the device pipeline object that is managing the DD Gcache is destroyed, as part of the clean up sequence, the device pipeline must destroy the DD translations.

// // Dp Object (DpCtx, DpDev, DpMgr, DpLib) which has Gcache // translation is destroyed: Dp::destroy_translations()

{ // DI Gcache removes translations given translation ID // assuming that the pipeline has a list of device- // dependent translations // if one translation is destroyed, manage the list foreach dd_trans in list of translations { dd_trans->getDiGcache()->removeDdTranslation(trans_id); // clean up next/prev pointers delete dd_trans; } } // // Sample XgliDdGcacheTranlation destroy function void XgliDdGcacheTranlation::destroy() { // unlink this dd translation from lists // does device-dependent operations to release resources // and clean up data structures delete this; }

li1MultiArc() - 2D

Overview This function draws a list of arcs in the plane of the view surface. See the xgl_multiarc() man page for a description of the input data structure and for a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiArc(
    Xgl_arc_list *arc_list);

Input Parameters arc_list

A pointer to the list of arcs to draw.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multiarc() man page.

Description of the Software Pipeline 2D li1MultiArc Function The software pipeline 2D li1MultiArc() function first constructs an XglConicData2d object called arc_data using the argument arc_list and then transforms the geometry to device coordinates. The behavior of a circle under transformation determines the shape of an arc in DC. A general 2D matrix can transform a circle into an ellipse with an arbitrary orientation of the major and minor axes. For a single call to this function, the MC-to-DC matrix is invariant. This matrix is the only entity that determines the eccentricity and orientation of all MC circles when they are transformed into DC. This function calculates these quantities once for a unit radius circle in MC. Circular arcs in MC become elliptical arcs in DC. For each arc, the center in MC maps to the center in DC via the MC-to-DC matrix; this is also true for the start and stop points. The radius determines the size of the elliptical arc in DC. The start and stop angles in DC (with the x-axis to the right and the y-axis down) increase in the counter-clockwise sense, and both angles are in the range [0, 2*pi]. The arc includes the locus on the ellipse from the start point to the stop point when moving counter-clockwise.

For clip checking, this function calculates the bounding box of the ellipse in DC corresponding to a unit radius circle in MC. Then, for each arc in MC, the function translates and scales the unit circle's bounding box in DC to give the bounds of the current ellipse in DC. The bounding box is reduced further by examining the start and stop points, as well as the center point if the arc fill style is sector. There are two trivial clip checking cases. If the specific DC bounding box is completely outside the view clip bounds in DC, then the function skips to the next arc. If the DC bounding box is completely inside the view clip bounds, the arc's center, major axis, minor axis, start angle, stop angle, start point, stop point, rotation angle, and edge flag are stored in a list, which is level 1 of arc_data. ¹

If the DC bounding box is partly inside the view clip bounds, the function flushes the current list of elliptical arcs by calling the device pipeline li2MultiEllipticalArc() function with the current level of arc_data set to level 1, which contains the list of arcs in DC. Then it decomposes the current arc into a point list with a utility, sets the current coordinate system in the view group interface to DC, and calls li1Polygon() or li1MultiPolyline() so that the polygon or polyline clipper handles the clipping depending on the whether the arc is filled or open, respectively. (An elliptical arc clipper would be desirable so that clipped elliptical arcs are converted into simpler elliptical arcs instead of polygons, but this is not implemented in the software pipelines of XGL 3.0.1.) After all arcs have been processed, the remaining buffered arcs (if any) are flushed by calling the device pipeline li2MultiEllipticalArc() function.

If picking is enabled, the function falls back on the polygon or polyline picker.

---

1. The calculated rotation angle is in the range [-pi/2, pi/2]. It's sense is right-handed. Since DC is oriented with the x-axis to the right and the y-axis down, angles increase in the clockwise sense..

li1MultiArc() - 3D

Overview This function draws a list of arcs in the plane described by two direction vectors provided with the arc. See the xgl_multiarc() man page for a description of the input data structure and for a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1MultiArc(
    Xgl_arc_list *arc_list);

Input Parameters arc_list

Pointer to the list of arcs to draw.

Attributes That the Device Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multiarc() man page.

Description of the Software Pipeline 3D li1MultiArc Function The li1MultiArc() function processes regular 3D arcs and 3D annotation arcs. Processing is slightly different for annotated arcs.

If the data type of the input parameter arc_list is XGL_MULTIARC_F3D or XGL_MULTIARC_D3D (the arcs are not annotated), this function evaluates the number of points necessary to tessellate each of the arcs in arc_list and computes the unit circle. It then tessellates each of the arcs by projecting the arc onto the plane in MC described by the two direction vectors provided with the arc. If the multiarcs are open arcs, then the function calls li1MultiPolyline() to draw the tessellated arcs; otherwise, it calls li1MultiSimplePolygon() to draw the tessellated arcs.

If the data type of the input parameter arc_list is XGL_MULTIARC_AF3D or XGL_MULTIARC_AD3D (the arcs are annotated), the function determines whether there is a bounding box provided for the entire multiarc data. If so, the function determines whether the bounding box is completely clipped by the model clipping or by the view clipping. If it is completely clipped, the function stops processing and returns control to the caller. Otherwise, the

function evaluates the number of points to be used to tessellate each of the arcs specified in arc_list and computes the unit circle. Subsequently, the function model clips the reference points (center points) of the multiarcs and transforms the center points of the multiarcs from MC to DC. From each of the center points of the multiarcs and the corresponding radius, start angle, and stop angle, the function will tessellate the arc in DC, and view transform and clip the arc.

Finally, if picking is enabled, the function performs the picking operation for the arc. Otherwise, if the multiarcs are open arcs, the function will depth cue the open arcs and call li2MultiPolyline() to draw the open arcs. If the multiarcs are closed arcs, the function will depth cue the closed arcs and call li2GeneralPolygon() to draw the closed arcs.

li1MultiCircle() - 2D

Overview This function draws a list of circles in the plane of the view surface. See the xgl_multicircle() man page for a description of the input data structure and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiCircle(
    Xgl_circle_list     *circle_list);

Input Parameters circle_list

Pointer to the list of circles to render.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multicircle() man page.

Description of the Software Pipeline li1MultiCircle Function The software pipeline li1MultiCircle() function first constructs an XglConicData2d object called circle_data using the argument circle_list and then transforms the geometry to DC. A general 2D matrix can transform a circle into an ellipse with an arbitrary orientation of the major and minor axes. For a single call to this function, the MC-to-DC matrix is invariant. This matrix is the only entity that determines the eccentricity and orientation of all MC circles when they are transformed into DC. This function calculates these quantities once for a unit radius circle in MC. For each circle, the center in MC maps to the center in DC via the MC-to-DC matrix. The radius determines the size of the ellipse in DC.

For clip checking, this function calculates the bounding box of the ellipse in DC corresponding to a unit radius circle in MC. Then for each circle in MC, it translates and scales the unit circle's bounding box in DC to give the bounds of the current ellipse in DC. There are two trivial clip checking cases. If the specific DC bounding box is completely outside the view clip bounds in DC,

then the function skips to the next circle. If the DC bounding box is completely inside the view clip bounds, the ellipse's center, major axis, minor axis, rotation angle, and edge flags are stored in a list, which is level 1 of circle_data. ¹

If the DC bounding box is partly inside the view clip bounds, the function flushes the current list of ellipses by calling li2MultiEllipse() with the current level of circle_data set to level 1, which contains the list of ellipses in DC. Then it decomposes the current ellipse into a polygon with a utility, sets the current coordinate system in the view group interface to DC, and calls li1Polygon() so that the polygon clipper handles the clipping of the ellipse. (An ellipse clipper would be desirable so that ellipses are converted into elliptical arcs instead of polygons, but this is not implemented in the software pipelines of XGL 3.0.1.) After all ellipses have been processed, the remaining buffered ellipses (if any) are flushed by calling li2MultiEllipse().

If picking is enabled, the function performs picking in MC because geometry is always a circle whereas the conic could be a rotated ellipse in DC, making picking more difficult to do quickly. The pick aperture is clipped to the view clip bounds in DC. If the aperture is at least partly inside, the corners of the clipped aperture are transformed to MC. The circle picking implementation is fast, but approximate. Some picks may be missed if the circle is smaller than the aperture and the aperture covers less than half of the circle.

---

1. The calculated rotation angle is in the range [-pi/2, pi/2]. It's sense is right-handed. Since DC is oriented with the x-axis to the right and the y-axis down, angles increase in the clockwise sense..

li1MultiCircle() - 3D

Overview This function draws a list of circles in the plane described by two direction vectors provided with each circle. See the xgl_multicircle() man page for a description of the input data structure and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1MultiCircle(
    Xgl_circle_list     *circle_list);

Input Parameters circle_list

Pointer to a list of circles to render.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multicircle() man page.

Description of the Software Pipeline li1MultiCircle Function The li1MultiCircle() function processes regular 3D circles and 3D annotation circles. Processing is slightly different for annotated circles.

If the data type of the input parameter circle_list is XGL_MULTICIRCLE_F3D or XGL_MULTICIRCLE_D3D (the circles are not annotated), this function evaluates the number of points to be used to tessellate each of the circles specified in circle_list and computes the unit circle with the correct precision. The function then tessellates each of the circles specified in circle_list by projecting the circle onto the plane in MC described by the two direction vectors provided with the circle, using the correct radius. Finally, it calls li1MultiSimplePolygon() to draw the tessellated circles.

If the data type of the input parameter circle_list is XGL_MULTICIRCLE_AF3D or XGL_MULTICIRCLE_AD3D (the circles are annotated), the function determines whether there is a bounding box provided for the entire multicircle data. Is so, the function determines whether the bounding box is completely clipped by the model clipping or by the view clipping. If it is completely clipped, the function will stop processing and return control to the caller.

Otherwise, the function evaluates the number of points to be used to tessellate each of the circles specified in circle_list and computes the unit circle with the correct precision. It then model clips the reference points (center points) of the multicircles and transforms the center points of the multicircles from MC to DC. From each of the center points of the multicircles and the corresponding radius, the function will tessellate the circle in DC, and view transform and clip the circle. If picking is enabled, the function will perform the picking operation for the circle. Otherwise, it will depth cue the circle and call li2GeneralPolygon() to draw the circle.

li1MultiEllipticalArc() - 3D

Overview This function draws a list of 3D elliptical arcs in the plane described by two direction vectors provided with each arc. See the xgl_multi_elliptical_arc() man page for a description of the input data structure and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1MultiEllipticalArc(
    Xgl_ell_list *ell_list);

Input Parameters ell_list

Pointer to a list of elliptical arcs.

Attributes That the Device Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multi_elliptical_arc() man page.

Description of the Software Pipeline li1MultiEllipticalArc Function The li1MultiEllipticalArc() function processes regular 3D elliptical arcs and 3D annotation elliptical arcs. Processing is slightly different for annotated arcs.

If the data type of the input parameter ell_list is XGL_MULTIELLARC_F3D or XGL_MULTIELLARC_D3D (the elliptical arcs are not annotated), this function evaluates the number of points to be used to tessellate each of the arcs specified in ell_list and computes the unit circle with the correct precision. It then tessellates each of the arcs specified in ell_list by projecting the arc onto the plane in MC described by the two direction vectors provided with the arc. If the multielliptical arcs are open arcs, the function calls li1MultiPolyline() to draw the tessellated arcs; otherwise, it calls li1MultiSimplePolygon() to draw the tessellated arcs.

If the data type of the input parameter ell_list is XGL_MULTIELLARC_AF3D or XGL_MULTIELLARC_AD3D (the arcs are annotated), this function determines whether there is a bounding box provided for the entire multielliptical arc

data. If so, the function determines whether the bounding box is completely clipped by the model clipping or by the view clipping. If it is completely clipped, the function stops processing and return control to the caller. Otherwise, the function evaluates the number of points to be used to tessellate each of the arcs specified in ell_list and computes the unit circle with the correct precision. The function model clips the reference points (center points) of the multielliptical arcs and transforms the center points of the multielliptical arcs from MC to DC. From each of the center points of the multielliptical arcs and the corresponding axes, start angle, and stop angle, and rotation angle, the function tessellates the arc in DC and view transforms and clips the arc.

If picking is enabled, the function performs the picking operation for the arc. Otherwise, if the multielliptical arcs are open arcs, it will depth cue the open arcs and call li2MultiPolyline() to draw the open arcs. If the multielliptical arcs are closed arcs, the function will depth cue the closed arcs and call li2GeneralPolygon() to draw the closed arcs.

li1MultiMarker() - 2D

Overview This function draws a marker at each point in a list of points. See the xgl_multimarker() man page for a description of the input data structure and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiMarker(
    Xgl_pt_list     *point_list);

Input Parameters point_list

Pointer to a list of points.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multimarker() man page.

Description of the Software Pipeline 2D li1MultiMarker Function The software pipeline routine takes a list of points, optionally with colors associated, transforms the points to DC, and clips them against the viewing planes.

If picking is enabled, the points are checked against the pick aperture. If a pick hit is detected, the function records the information and immediately returns; otherwise, the function returns after all the points have been checked. If picking is not enabled, markers are rendered according to the following rules:

• If the current marker type is xgl_marker_dot, then the list of clipped points is passed to li2MultiDot() for rendering.
• For all other marker types (predefined or user-defined), a point list is constructed that describes the marker as a series of strokes centered on each of the clipped points. The marker routine overwrites the current line attributes with the marker attributes and sets the MC-to-DC transform to the identity. (Note that the polyline routine need not be aware that it is being overwritten.) The point lists are passed to li1MultiPolyline() for rendering. After the marker function has completed processing the list, the polyline attributes and transforms are reset.

li1MultiMarker() - 3D

Overview This function draws a marker at each point in a list of points. See the xgl_multimarker() man page for a description of the input data structure and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglSwpCtx3dDef::li1MultiMarker(
    Xgl_point_list      *point_list);

Input Parameters point_list

Pointer to a list of 3D points, optionally with colors (normals are ignored).

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multimarker() man page.

Description of the Software Pipeline 3D li1MultiMarker Function The software pipeline first clips the input list of points against the current set of model clipping planes (if no clipping planes are defined, this step is ignored). The points are then transformed to clip coordinates (CC) where they are clip-checked against the CC viewing volume. Those points that are found to be "inside" are transformed from CC to DC and are saved for the next step in the pipeline.

If picking is enabled and Z-buffering is not enabled, the points are checked against the pick volume, and the routine returns after determining whether the pick was successful.

If both picking and Z-buffering are enabled, then simply comparing the points to the pick volume is not sufficient. Points that are inside the pick volume are passed to i2MultiDot() to do Z comparisons to confirm a pick hit.

If picking is not enabled, then the marker points are optionally depth cued, and rendered according to the following rules.

• If the current marker type is xgl_marker_dot, then the list of clipped points is passed to li2MultiDot() for rendering.
• For all other marker types (predefined or user-defined), a point list is constructed that describes the marker as a series of strokes centered on each of the clipped points. The marker routine overwrites the current line attributes with the marker attributes and sets the MC-to-DC transform to the identity. (The polyline routine need not be aware that it is being overwritten.) These point lists are then passed to li1MultiPolyline() for rendering. After the marker function has completed processing the list, the attributes and transforms are reset.

li1MultiPolyline() - 2D

Overview This function draws a list of unconnected polylines. See the man page xgl_multipolyline() for a description of the input data structures and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiPolyline(
    Xgl_bbox            *bounding_box,
    Xgl_usgn32          num_pt_lists,
    Xgl_point_list      *point_list);

Input Parameters bounding_box

Pointer to a bounding box structure that defines a bounding box for all the points in each polyline.

num_pt_lists	The number of point lists passed to the primitive.
point_list	Pointer to an array of point lists.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multipolyline() man page.

Description of the Software Pipeline 2D li1MultiPolyline Function The software pipeline li1MultiPolyline() function transforms the input array of point lists to DC and clips them against the view planes if necessary. There may be colors and/or flags associated with the points, and the line width may be greater than 1, although these factors do not effect the geometric processing that is performed by this function. Note that line patterning is done after view clipping, so a view-clipped line may be drawn with a different pattern offset than a non-view clipped line.

If picking is enabled, then each vector is checked to see if it passes through the pick aperture. The multipolyline function either returns as soon as a pick hit is found, or returns after checking the list of vectors. If picking is not enabled, li2MultiPolyline() is called to render the polylines.

li1MultiPolyline() - 3D

Overview This function draws a list of unconnected polylines from an input array of point lists. See the xgl_multipolyline() man page for a description of the input data structures and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiPolyline(
    Xgl_bbox            *bounding_box,
    Xgl_usgn32          num_pt_lists,
    Xgl_point_list      *point_list);

Input Parameters bounding_box

Pointer to a bounding box structure that defines a bounding box for all the points in each polyline.

num_pt_lists	The number of point lists passed to the primitive.
point_list	Pointer to an array of point lists.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multipolyline() man page.

Description of the Software Pipeline li1MultiPolyline Function The software pipeline 3D li1MultiPolyline() function optionally model clips the polylines, if necessary (see li1MultiMarker() above), then transforms them to clip coordinates (CC) and clip-checks them against the viewing volume. The points are then transformed to DC for further processing.

If picking is enabled and Z-buffering is enabled, then the polylines are passed down to li2MultiPolyline(), from which Z-buffer comparisons can be made to confirm any pick hits.

If picking is enabled and Z-buffering is not enabled, the polylines are picked by determining whether they pass through the 3D pick volume. If any single piece of any of the polylines meets this criteria, then the entire list is deemed to have been picked, and the routine returns.

If picking is not enabled, the polylines are depth cued (if depth cueing is turned on), and li2MultiPolyline() is called to render them. These operations are applied regardless of the width of the line or the data that is present at the vertices (flags, colors, etc.).

Note that line patterning is done after view clipping, so a view-clipped line may be drawn with a different pattern offset than a non-view clipped line.

li1MultiRectangle() - 2D

Overview This function draws a list of rectangles. See the xgl_multirectangle() man page for a description of the input data structure and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiRectangle(
    Xgl_rect_list       *rect_list);

Input Parameters rect_list

Pointer to a list of rectangles.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multirectangle() man page.

Description of the Software Pipeline li1MultiRectangle Function The point information in the Xgl_rect_list structure is copied into a Xgl_pt_list structure as a list of 4-sided polygons. The function then calls li1MultiSimplePolygon() with the facet flags set to 4-sided and convex.

li1MultiRectangle() - 3D

Overview This function draws a list of rectangles. See the xgl_multirectangle() man page for a description of the input data structure and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1MultiRectangle(
    Xgl_rect_list       *rect_list);

Input Parameters rect_list

Pointer to a list of rectangles.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multirectangle() man page.

Description of the Software Pipeline li1MultiRectangle Function The li1MultiRectangle() function processes regular 3D rectangles and 3D annotation rectangles. Processing is slightly different for annotated rectangles.

If the data type of the input parameter rect_list is XGL_MULTIRECT_F3D or XGL_MULTIRECT_D3D (the rectangles are not annotated), this function projects each of the rectangles specified in rect_list onto the plane in MC described by the two direction vectors provided with the rectangle and calls li1MultiSimplePolygon() to draw the rectangles.

If the data type of the input parameter rect_list is XGL_MULTIRECT_AF3D or XGL_MULTIRECT_AD3D (the rectangles are annotated), this function first determines whether there is a bounding box provided for the entire multirectangle data. If so, the function determines whether the bounding box is completely clipped by the model clipping or by the view clipping. If it is completely clipped, the function will stop processing and return control to the caller. Otherwise, the function model clips the reference points of the multirectangles and transforms the reference points of the multirectangles from

MC to DC. From each of the reference points of the multirectangles and the corresponding corner max point, the function will build a rectangle in DC and view transform and clip the rectangle.

Finally, if picking is enabled, the function performs picking operation for the rectangle. Otherwise, it depth cues the rectangle and calls li2GeneralPolygon() to draw the rectangle.

li1MultiSimplePolygon() - 2D

Overview This function draws a list of separate, single-bounded polygons. The polygons can be self-intersecting. See the xgl_multi_simple_polygon() man page for a description of the input data structures and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiSimplePolygon(
    Xgl_facet_flags     flags,
    Xgl_facet_list      *facets,
    Xgl_bbox            *bounding_box,
    Xgl_usgn32          num_pt_lists,
    Xgl_pt_list         *point_list);

Input Parameters flags

Structure specifying the kind of polygons being rendered.

facets	Pointer to a structure defining facet data for the polygons.
bounding_box	Pointer to a bounding box structure that defines a bounding box for all the points in the point list.
num_pt_lists	The number of point lists.
point_list	Pointer to an array of point lists for the polygons.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multi_simple_polygon() man page.

Description of the Software Pipeline 2d li1MultiSimplePolygon Function The software pipeline 2D li1MultiSimplePolygon() function calls the more general li1Polygon() routine to process each polygon in the list of polygons. This is expected to change in future releases by optimizing the code in this routine to process the polygons.

li1MultiSimplePolygon() - 3D

Overview This function draws a list of separate, single-bounded polygons. See the xgl_multi_simple_polygon() man page for a description of the input data structures and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1MultiSimplePolygon(
    Xgl_facet_flags     flags,
    Xgl_facet_list      *facets,
    Xgl_bbox            *bounding_box,
    Xgl_usgn32          num_pt_lists,
    Xgl_pt_list         *point_list);

Input Parameters flags

Structure specifying the kind of polygons being rendered.

facets	Pointer to a structure defining facet data for the polygons.
bounding_box	Pointer to a bounding box structure that defines a bounding box for all the points in the point list.
num_pt_lists	The number of point lists.
point_list	Pointer to an array of point lists for the polygons.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_multi_simple_polygon() man page.

Description of the Software Pipeline li1MultiSimplePolygon Function The software pipeline li1MultiSimplePolygon() function takes the input lists of points and transforms them to DC, clipping the polygons if necessary. Since clipping may introduce internal edges, a list of flags is introduced to indicate edges that should not be drawn later. The first step in processing the polygon is to determine whether it can be culled (this is an optional step that is only done if culling is enabled). If so, then the function immediately returns.

If the polygon passes the culling test, then it is model clipped if model clipping planes have been supplied by the user. After model clipping, the polygon is transformed and clip-checked in a manner analogous to markers and polylines. If lighting is set to per_vertex then the vertices are lit before clipping. This is only done for boundaries that are found to be inside the view-volume, or for boundaries that require clipping. Bounds that are outside the volume are not lit.

The final stage in polygon processing is to optionally depth cue the vertices. Once this is done, and if picking is not enabled, the polygon is passed down to li2MultiSimplePolygon() for rendering.

li1MultiSimplePolygon() does not render edges; this is the responsibility of li2MultiSimplePolygon(). In addition, li1MultiSimplePolygon() does not treat hollow or empty interior styles any differently than solid fills.

Notes Performance is optimized if the facet flags are set before calling li1MultiSimplePolygon() to be either 3 sided or 4 sided and convex, and there is no picking, no model clipping, and no silhoutte edges, and the view clip is only done for plus w values. If one or more of these conditions are not satisfied (for example, picking is enabled), then li1Polygon() is called in a loop for each polygon.

li1NurbsCurve() - 2D

Overview This function draws a NURBS curve of a specified order based on the list of knots in parameter space, the list of control points, and the parameteric range. See the xgl_nurbs_curve() man page for a description of the input data structures and a description of the functionality that the device pipeline must handle.

---

Note - For information on how the software pipeline implements NURBS, see the list of references in Appendix C, "Accelerating NURBS Primitives".

---

Syntax

void XglDpCtx2d::li1NurbsCurve(
    Xgl_nurbs_curve             *curve,
    Xgl_bounds_f1d              *range,
    Xgl_curve_color_spline *color_spline,
    void                        *gcache_rep);

Input Parameters curve

Pointer to a structure defining the geometry of the curve.

range	Pointer to a structure defining the parametric limits of the curve.
color_spline	Pointer to a structure defining the color distribution of the curve's geometry. This argument is ignored in 2D.
gcache_rep	An optional pointer to the device-dependent Gcache representation.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_nurbs_curve() man page.

Description of the Software Pipeline li1NurbsCurve Function The software pipeline li1NurbsCurve() function is a common entry point for both the regular NURBS curve primitive and the Gcache'd NURBS curve. For the regular NURBS primitive, the void* is set to NULL. If the Gcache contains a NURBS curve, then li1DisplayGcache() calls li1NurbsCurve() (if the order of the API geometry is greater then 1) with the void pointer set to the device-dependent Gcache storage, and the other three arguments are ignored. See page 229 for a description of device-dependent Gcache. A device pipeline can choose to support both the regular and the Gcache primitives in the same li1NurbsCurve() function, or support the regular primitive only and let the li1DisplayGcache() handle Gcache cases, or call the software pipeline in both cases.

If the order of the geometry data is 1, the Context current stroke is set to markers, and li1MultiMarker() is called with the list of control points. Otherwise, the routine takes the geometry data and tessellates it to a list of points in DC. Then, li1MultiPolyline() is called with the current coordinate system set to DC.

If the input is from a Gcache, a list of points is generated in MC. In the case of COMBINED and STATIC Gcaches, li1MultiPolyline() is called. In the case of a DYNAMIC Gcache, the points are generated in DC, and the push/pop coordinate system will be done like a regular 2D NURBS curve primitive.

li1NurbsCurve() - 3D

Overview This function draws a NURBS curve of a specified order based on the list of knots in parameter space, the list of control points, and the parameteric range. See the xgl_nurbs_curve() man page for a description of the input data structures and a description of the functionality that the device pipeline needs to handle.

---

Note - For more information on how the software pipeline implements NURBS, see the list of references in Appendix C, "Accelerating NURBS Primitives".

---

Syntax

void XglDpCtx2d::li1NurbsCurve(
    Xgl_nurbs_curve             *curve,
    Xgl_bounds_f1d              *range,
    Xgl_curve_color_spline *color_spline,
    void                        *gcache_rep);

Input Parameters curve

Pointer to a structure defining the geometry of the curve.

range	Pointer to a structure defining the parametric limits of the curve.
color_spline	Pointer to a structure defining the color distribution of the curve's geometry. This argument is only supported in 3D.
gcache_rep	An optional pointer to the device-dependent Gcache representation.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_nurbs_curve() man page.

Description of the Software Pipeline li1NurbsCurve Function The software pipeline li1NurbsCurve() function is a common entry point for both the regular NURBS curve primitive and the Gcache'd NURBS curve. For the regular NURBS primitive, the void* is set to NULL. If the Gcache contains a NURBS curve, then li1DisplayGcache() calls li1NurbsCurve() (if the order of the API geometry is greater then 1) with the void pointer set to the device-dependent Gcache storage, and the other three arguments are ignored. See page 229 for a description of device-dependent Gcache. A device pipeline can choose to support both the regular and the Gcache primitives in the same li1NurbsCurve() function, or support the regular primitive only and let the li1DisplayGcache() handle Gcache cases, or call the software pipeline in both cases.

If the order of the geometry data is 1, the current stroke is set to marker, and li1MultiMarker() is called with the list of control points. Otherwise, the routine takes the geometry data and tessellates to a list of points in LC (Lighting Coordinates). Then li1MultiPolyline() is called with current coordinate system set to LC, and reset back when it returns. Vertex colors will be attached if a color spline is present.

If the input is from a Gcache, then in the case of COMBINED and STATIC Gcache, a list of points will be generated in MC. Then li1MultiPolyline() is called. In the case of a DYNAMIC Gcache, the points will be generated in LC, the push/pop of the coordinates will be done like a regular NURBS curve primitive.

li1NurbsSurf() - 3D

Overview This function draws a NURBS surface of a specified order based on the list of knots in parameter space, the list of control points, and the trimming information. See the xgl_nurbs_surface() man page for a description of the input data structures and a description of the functionality that the device pipeline needs to handle.

---

Note - For more information on how the software pipeline implements NURBS, see the list of references in Appendix C, "Accelerating NURBS Primitives".

---

Syntax

void XglDpCtx3d::li1NurbsSurf(
    Xgl_nurbs_surf                  *surface,
    Xgl_trim_loop_list              *trim_list,
    Xgl_nurbs_surf_simple_geom *hints,
    Xgl_surf_color_spline           *color_spline,
    Xgl_surf_data_spline_list       *data_splines,
    void                            *gcache_rep);

Input Parameters nurbs_surf

Pointer to a structure defining the geometry of the surface.

trim_list	Pointer to a structure defining the trimmed portion of the surface.
hints	Pointer to a structure containing hints about the shape of the surface.
color_spline	Pointer to a structure describing the color distribution over the surface.
data_splines	Not currently implemented.
gcache_rep	An optional pointer to the device-specific Gcache representation.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_nurbs_surface() man page.

Description of the Software Pipeline li1NurbsSurf Function The software pipeline li1NurbsSurf() function is a common entry point for both the regular NURBS curve primitive and the Gcache'd NURBS curve. For the regular NURBS primitive, the void* is set to NULL. If the Gcache contains a NURBS surface, then li1DisplayGcache() calls li1NurbsSurf() (if the order of the API geometry is greater then 1) with the void pointer set to the device-dependent Gcache storage, and the other three arguments are ignored. See page 229 for a description of device-dependent Gcache. A device pipeline can choose to support both the regular and the Gcache primitives in the same li1NurbsSurf() function, or support the regular primitive only and let the li1DisplayGcache() handle Gcache cases, or call the software pipeline in both cases.

If the order of the geometry data is 1, the current stroke is set to marker, and li1MultiMarker() is called with the list of control points. Otherwise, the routine takes the geometry data and tessellates it to triangle lists, quadmeshes, or polylines (if an isoparameteric curve is present). For the regular NURBS surface, vertices will be generated in LC (Lighting Coordinates). Then li1TriangleList(), li1QuadrilateralMesh(), or li1MultiPolyline() is called with current coordinate system set to LC. Vertex colors will be attached for triangle lists and quad meshes if a color spline is present.)

If the input is from a Gcache, in the case of COMBINED and STATIC Gcache, a list of points will be generated in MC, then li1TriangleList(), li1QuadrilateralMesh(), or li1MultiPolyline() is called. If it is a DYNAMIC Gcache, the points will be generated in LC, the push/pop of the coordinate systems will be done like a regular NURBS surface primitive.

li1Polygon() - 2D

Overview This function draws a single polygon polygon that may, optionally, have several bounds. See the xgl_polygon() man page for a description of the input data structures and a description of the functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx2d::li1Polygon(
    Xgl_facet_type      facet_type,
    Xgl_facet           *facet,
    Xgl_bbox            *bounding_box,
    Xgl_usgn32          num_pt_lists,
    Xgl_pt_list         *point_list);

Input Parameters facet_type

Data type of the facets in the list.

facet	Pointer to a structure defining the facet data.
bounding_box	Pointer to a structure defining the bounding box around all the points in the array of point lists.
num_pt_lists	Number of point lists in the array of point lists.
point_list	Pointer to an array of point lists.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_polygon() man page.

Description of the Software Pipeline li1Polygon Function The software pipeline li1Polygon() function takes as input an array of point lists, each describing a boundary of a possibly multi-bounded polygon (in other words, "holes" are permitted). The lists of points are first transformed to DC and clipped if necessary. Since clipping may introduce internal edges, a list of flags is introduced to indicate edges that should not be drawn later.

If picking is enabled, then the resulting polygon is checked against the pick aperture, and the routine exits. If picking is not enabled, li2GeneralPolygon() is called to render the polygon. li1Polygon() does not render edges (edge rendering is the responsibility of li2GeneralPolygon()). In addition, it does not treat hollow or empty interior styles any differently than solid fills.

li1Polygon() - 3D

Overview This function draws a single polygon polygon that may, optionally, have several bounds. See the xgl_polygon() man page for a description of the functionality that the device pipeline needs to handle

Syntax

void XglDpCtx2d::li1Polygon(
    Xgl_facet_type      facet_type,
    Xgl_facet           *facet,
    Xgl_bbox            *bounding_box,
    Xgl_usgn32          num_pt_lists,
    Xgl_pt_list         *point_list);

Input Parameters facet_type

Data type of the facets in the list.

facet	Pointer to a structure defining the facet data.
bounding_box	Pointer to a structure defining the bounding box around all the points in the array of point lists.
num_pt_lists	Number of point lists in the array of point lists.
point_list	Pointer to an array of point lists.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_polygon() man page.

Description of the Software Pipeline li1Polygon Function The software pipeline 3D li1Polygon() routine is the general case 3D polygon renderer. The input is an array of point lists, each defining a boundary of the polygon. The first step in processing the polygon is to determine whether it can be culled (this is an optional step that is only done if culling is enabled). If so, then the function immediately returns.

If the polygon passes the culling test, then it is model clipped if model clipping planes have been supplied by the user. After model clipping, the polygon is transformed and clip-checked in a manner analogous to markers and polylines. If lighting is set to "per_vertex" then the vertices are lit before clipping. This is only done for boundaries that are found to be inside the view-volume, or for boundaries that require clipping. Bounds that are outside the volume are not lit.

If picking is enabled (which means that rendering is disabled), it is done in a manner similar to markers and polylines. If Z-buffering is enabled, li2GeneralPolygon() is called to perform the Z comparisons necessary to verify a pick hit; otherwise, the boundaries are checked to determine whether any of them pass through the pick volume.

The final stage in polygon processing is to optionally depth cue the vertices. Once this is done, the polygon is passed down to li2GeneralPolygon() for rendering.

li1QuadrilateralMesh() - 3D

Overview This function draws a quadrilateral mesh. See the man page xgl_quadrilateral_mesh() for a description on the input data structures and for information on functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1QuadrilateralMesh(
    Xgl_usgn32          row_dim,
    Xgl_usgn32          col_dim,
    Xgl_facet_list      *facet_list,
    Xgl_point_list      *point_list);

Input Parameters row_dim

The number of rows of points defining the mesh.

col_dim	The number of columns of points defining the mesh.
facet_list	Pointer to a structure defining the facets.
point_list	Pointer to geometry data for the quad mesh.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_quadrilateral_mesh() man page.

Description of the Software Pipeline li1QuadrilateralMesh Function The software LI-1 quadrilateral mesh function breaks up the input quad mesh into triangle strips, one for each row of the original mesh. The li1TriangleStrip() routine is called for each triangle strip.

The points that are passed to li1TriangleStrip() are identical to those input to the quad mesh function with the exception that flags are introduced to mark edges that fall along the diagonals of each quad (see page 130). If the interior style is "hollow", or if edges are enabled, then these diagonals should not be drawn. Quad mesh edges are drawn by the li2TriangleStrip() function. The edge pattern is restarted for every new row of the mesh.

li1StrokeText() - 2D/3D

Overview

li1StrokeText() renders characters defined as a collection of lines. See the xgl_stroke_text() man page for information on functionality that the device pipeline needs to handle.

Syntax

[2D]void XglDpCtx2d::li1StrokeText(
    void            *string,
    Xgl_pt_f2d      *pos,
    Xgl_pt_f3d      *dir);

[3D]void XglDpCtx3d::li1StrokeText(
    void            *string,
    Xgl_pt_f3d      *pos,
    Xgl_pt_f3d      *dir);

Input Parameters string

A NULL-terminated C-style list of characters if the character encoding is single-string encoding, or a pointer to a Xgl_mono_text_list structure if the character encoding is multi-string encoding.

pos	The reference point for the position of the string and the origin of the text plane.
dir	An array containing the two direction vectors used for the orientation of the 2D plane on which the text sits. Used for 3D Contexts only.

Attributes That the Pipeline Needs to Handle The device pipeline must account for some or all of the attributes listed in the xgl_stroke_text() man page.

Description of the Software Pipeline li1StrokeText Function The software pipeline li1StrokeText() function takes as input a single point, which is the starting position for the string. This point is clipped against the window boundaries, and if it is outside the window boundaries, no text is drawn, even if part of the string would be visible.

If the point is inside the window boundaries, this function takes the string and converts it to multipolylines. It then sets the current stroke to text, sets up the viewing matrices, and calls li1MultiPolyline().

li1TriangleList() - 3D

Overview This function draws a triangle list, which is a set of points that form a triangle strip, a triangle star, or a group of unconnected triangles. See the xgl_triangle_list() man page for a description of the input data structures and for information on functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1TriangleList(
    Xgl_facet_list      *facet_list,
    Xgl_pt_list         *point_list,
    Xgl_tlist_flags     flags);

Input Parameters facet_list

Pointer to a structure defining the facet information for the triangle list.

point_list	Pointer to the point list defining the vertices of the triangles in the triangle list.
flags	A word containing information on the overall characteristics of the triangle list.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_triangle_list() man page.

Description of the Software Pipeline li1TriangleList Function The software pipeline function provides general purpose triangle rendering. It is more flexible than the li1TriangleStrip() primitive because it allows for the rendering of triangle stars and independent triangles in addition to triangle strips. However, the operations performed by this LI-1 call are similar to the li1TriangleStrip() function.

The first step is to branch to one of four different internal routines based on the value of the global triangle list flags parameter (part of the API call). This parameter specifies whether the input point list describes a triangle strip, a triangle list, a set of independent triangles, or a set of triangles that is composed of a combination of strips, stars and independent triangles. The points in the point list are interpreted differently based on whether the triangle list defines a triangle star, strip, or set of independent triangles. The triangle list function always tries to keep together runs of points in a point list that define one particular type of triangle; thus, a set of points defining a set of independent triangles, for instance, will be handled as one point list.

Within each of these four routines, the processing steps are similar. The first step is to model clip the triangles if model clipping is requested. Model clipping is done before culling because it may cause the triangle list to be separated into smaller sub-strips which can be processed more easily as separate entities.

Next, face culling is performed on the triangle list (if enabled by the user). This involves traversing the triangle list and skipping over those facets that are culled. This effectively breaks the triangle list down into smaller sub-lists of non-culled faces. Each of these sub-lists is then processed separately as is done for model-clipping. (The difference is that the normal-direction information calculated by this stage can be reused later on in the pipeline.) There are separate routines for culling the different kinds of triangle lists.

When the original triangle list has been broken down into sublists that are visible in MC, the vertices are transformed to clip coordinates (CC) and clip-checked in the same manner as the other 3D primitives described earlier. If lighting is enabled, the vertices that are found to be inside the clip volume, or those that require clipping, are lit in MC, and the new color is stored with the transformed points. Finally, the transformed points are depth cued, if depth cueing is enabled.

Once processing is complete on a sublist, it is ready to either be picked, or rendered. If picking is enabled and Z-buffering is enabled, li2TriangleStrip() or li2TriangleList() is called for Z-buffered picking. For non-Z-buffered picking, a simple geometry test is performed on the points to see if they lie within the pick aperture. If picking is not enabled, the points are passed down to either li2TriangleStrip() or li2TriangleList() for rendering.

Edges are drawn on triangle lists by calling the li2MultiPolyline() function for each triangle separately. This means that the edge pattern is restarted for each new triangle.

---

Note - If a triangle within the list requires clipping, then li2GeneralPolygon() is called to render it. This is because li2TriangleStrip() and li2TriangleList() require points that are in strip or list format. A clipped triangle may not necessarily still be in this format.

---

li1TriangleStrip() - 3D

Overview This function draws a triangle strip. See the xgl_triangle_strip() man page for a description of the input data structures and for information on functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1TriangleStrip(
    Xgl_facet_list      *facet_list,
    Xgl_pt_list         *point_list);

Input Parameters facet_list

Pointer to a structure containing facet information for the triangle strip.

point_list....Pointer to a structure defining the point list.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_triangle_strip() man page.

Description of the Software Pipeline li1TriangleStrip Function This function operates like li1Polygon(), except for the added complexity of multiple facets being derived from a one point list. The input to this routine is a single point list defining the vertices of the triangles in the strip. A facet list that defines facet normals and/or colors for the triangles can also be passed to this function.

The first step in processing the triangle strip is to optionally model clip it. This is done first, rather than face culling, because the model clipping utility may separate the strip into smaller sub-strips, and it is easier to process each of the sub-strips separately than as a group.

Next, face culling is performed on the strip (if enabled by the user). This involves traversing the strip and skipping over those facets that are determined to be culled. This effectively breaks the strip down into smaller sub-strips of non-culled faces. Each of these sub-strips is then processed

separately. (The difference between this and the separate processing of model clipping is that the normal-direction information calculated by this stage can be reused later in the pipeline.)

When the original strip has been broken down into sub-strips that are visible in MC, the vertices are transformed to clip coordinates (CC) and clip-checked in the same manner as other 3D primitives. As with li1Polygon(), if lighting is enabled, the vertices that are found to be inside the clip volume, or those that require clipping, are lit in MC, and the new color is stored with the transformed points. Finally, the transformed points are depth cued, if depth cueing is enabled.

Once processing is complete on a sub-strip, it is ready to either be picked, or rendered. If picking is enabled, then either li2TriangleStrip() is called for Z buffered picking, or a simple geometry test is performed on the points to see if they lie within the aperture. If picking is not enabled, the points are passed to li2TriangleStrip() for rendering.

Edges are drawn on triangle strip by calling the li2MultiPolyline() function for each triangle separately. This means that the pattern is restarted for each new triangle.

---

Note - If a triangle within the strip requires clipping, then li2GeneralPolygon() is called to render it. This is because li2TriangleStrip() requires points that are in "strip format". A clipped triangle may not necessarily still be in this format.

---

li1Accumulate() - 3D

Overview This function accumulates from one buffer to another. See the xgl_context_accumulate() man page for information on functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1Accumulate(
    Xgl_bounds_i2d*     rectangle,
    Xgl_pt_i2d*         position,
    float               src_wt,
    float               accum_wt,
    Xgl_buffer_set      copy_buf);

Input Parameters rectangle

Source area of the draw buffer of the raster. If rectangle is NULL, the maximum area of the source buffer is assigned to the value by the XGL core

position	The position in the destination buffer to be used as the starting position. If position is NULL, the top left corner of the destination buffer is assigned to the value by the XGL core.
src_wt	The weight to be used as the source weight in the accumulation calculation.
accum_wt	The weight to be used as the accumulation weight in the accumulation calculation.
copy_buf	The buffer to copy the accumulated image to.

---

Note - Note that although the application can specify NULL values for rectangle and postion, the XGL core assigns valid values to these parameters before passing them to the device pipeline; thus, the pipeline does not have to test for this but can assume the values for these parameters are valid.

---

Attributes That the Pipeline Needs to Handle The device pipeline must handle the attributes listed in the xgl_context_accumulate() man page.

What You Need to Know to Implement li1Accumulate Accumulation buffers must be either 32- or 48-bits. Indexed colors are not supported. The accumulation buffer must be BBGGRR or XBGR.

Description of the Software Pipeline li1Accumulate Function The software pipeline li1Accumulate() function accumulates the rectangle (rect) from the draw buffer to the accumulation buffer starting at pos. If copy_buf is not XGL_BUFFER_SEL_NONE, the accumulated area is also copied to rect in copy_buf. If rect is NULL, it is assumed to be the entire raster. If pos is NULL, it is assumed to be (0,0). If either rect or pos are out of bounds, they are both clipped accordingly.

If the weight for a buffer is zero, that buffer is not read. If the source weight is 0.0 and the destination (accumulation) weight is 1.0, the accumulation and copy-back steps are omitted (the copy to copy_buf is still performed, however). There is no substantial optimization at this time if the source weight is 1.0 and the destination weight is 0.0.

li1ClearAccumulation() - 3D

Overview This function clears the accumulation buffer. See the xgl_context_clear_accumulation() man page for information on functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx3d::li1ClearAccumulation(
    Xgl_color*      color);

Input Parameters color

Color value.

Attributes that the Pipeline Needs to Handle The device pipeline must handle the attribute listed in the xgl_context_clear_accumulation() man page.

What You Need to Know to Implement li1ClearAccumulation Accumulation buffers must be either 32- or 48-bits. Indexed colors are not supported. Format XBGR pixels are accessed as words. BBGGRR pixels are normally accessed as arrays of three Xgl_usgn16 structures, but because the SPARC architecture is big-endian, the BBGGRR pixels are stored a word at a time as well. This software implementation is for the SPARC architecture only. The implementation will be changed to run on both the x86 architecture and the SPARC architecture for the 10/93 release.

Description of the Software Pipeline li1ClearAccumulation Function The software pipeline li1ClearAccumulation() function sets the entire buffer specified by XGL_3D_CTX_ACCUM_OP_DEST to the specified color. The accumulation buffer is either BBGGRR or XBGR.

li1CopyBuffer() - 2D/3D

Overview This function copies a block of pixels from one buffer to another. See the xgl_context_copy_buffer() man page for information on functionality that the device pipeline needs to handle.

Syntax

[2D and 3D]
void XglDpCtx{2,3}d::li1CopyBuffer(
    Xgl_bounds_i2d*     rectangle,
    Xgl_pt_i2d*         position,
    XglRaster*          source_ras);

Input Parameters rectangle

Area that is copied in the source buffer. If rectangle is NULL, the maximum area of the source buffer is assigned to the value by the XGL core. The source rectangle cannot have negative components; that is, xmin, xmax, ymin, and ymax cannot be less than zero, and xmin and ymin cannot be greater than xmax and ymax respectively.

position	Position in the destination buffer where the copy begins. If position is NULL, the top left corner is assigned to the value by the XGL core.
source_ras	The buffer to be used as the source for the copy.

---

Note - Note that although the application can specify NULL values for rectangle and postion, the XGL core assigns valid values to these parameters before passing them to the device pipeline; thus, the pipeline does not have to test for this but can assume the values for these parameters are valid.

---

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_context_copy_buffer() man page.

What You Need to Know to Implement li1CopyBuffer Copy buffer copies a block of pixels from a buffer in system memory to the frame buffer or from the frame buffer to system memory. The direction of the copy (i.e. memory to frame buffer or vice versa) is reflected in the XGL core as follows:

• If the copy is from a memory raster to the frame buffer, li1CopyBuffer() is used for the copy operation. In this case, a memory raster is the source buffer, and the device associated with the Context in the xgl_context_copy_buffer() call is a window raster device.
• If the copy is from the frame buffer to a memory raster, the source buffer is a window raster device, and the device associated with the Context in the xgl_context_copy_buffer() call is a memory raster. In this case, the XglDpDev::copyBuffer() function is called to do the copy operation. Note that when copying from device to memory, the device object must perform the copy between winLock() and winUnLock() calls.

The XGL core determines what type of device the application is requesting for the source raster and the destination raster, and then calls the appropriate copy buffer routine.

For the case of copying from memory to a window raster, if the pipeline chooses to implement li1CopyBuffer(), it must take into account different color models and different underlying representations of memory. The memory raster can be indexed or RGB color type. However, XGL makes a distinction between the real color type, which is the actual memory organization for the data in the device, and the color type of the XGL Device that the application works with. For copying from memory to a window raster, the li1CopyBuffer() function must take into account all the cases of the various combinations of Device color type and real color type, although the pipeline may want to optimize some cases, such as the straight-forward copy from an indexed memory raster to an indexed device.

Since the XglDpDev copy buffer function is device-dependent and since the software pipeline does not currently implement li1CopyBuffer(), both copy buffer functions must be implemented by the device pipeline. However in CopyBuffer.h, XGL provides utility functions that perform copy operations with all the color conversion and fill styles.

CopyBuffer.h defines the data structures and interfaces for the copy buffer utility functions. It provides two utility functions: XgliUtCopyBuffer() and XgliUtFbToMemCopyBuffer(). XgliUtCopyBuffer() is a general routine that copies from one buffer to another; it can be used for either the memory to frame buffer copy or the frame buffer to memory copy. XgliUtFbToMemCopyBuffer() is a wrapper on XgliUtCopyBuffer() that is easier to use for the frame buffer to memory copy. These copy buffer utilities use the PixRect object to represent the raster memory for the copy. See Chapter 4, "Internal Data Storage" for information on PixRects.

XgliUtCopyBuffer() has pointers to the following structures, which can be NULL if the pipeline doesn't need them:

• Destination foreground color dest_fg_color and background color dest_bg_color can be NULL if the fill style is such that they are not needed.
• Destination clip mask dest_clip_mask and source clip mask src_clip_mask can be NULL if there is no per-pixel clip mask or if the whole area of window or memory is visible so that the pipeline does not need to do a per-pixel clip.
• The copy buffer color information structure color_info needs to be filled out. This structure specifies the color space of the data. Color Map objects are needed to do the copy and color conversion.
• The rop_info structure can be NULL if mask and rop mode do not apply or the device does not want plane mask or raster operations to be done in software.
• If the raster fill style is XGL_RAS_FILL_COPY (see the reference page for XGL_CTX_RASTER_FILL_STYLE), the fill_info structure must be filled in with the fill style; otherwise, the fill_info structure can be NULL. If there is a raster fill pattern or a stipple raster, then the PixRect needs to be supplied, and the stipple position and color must be supplied.
• Note that the z_buffer_info structure is not required for copy buffer, but if this utility is used for xgl_image(), this structure would need to be filled in.

The RefDpCtx utility also provides an li1CopyBufferMemToFB() function that the pipeline can use to implement the memory to frame buffer case of copy buffer. Note that none of the XGL-provided utilites for copying buffers are optimized, so it may advisable for the pipeline to implement at least the more straight-forward copy operations.

In summary, here's what you need to do to implement copy buffer:

1. Implement li1CopyBuffer(). You can use the RefDpCtx utility li1CopyBufferMemToFB to do this.

2. Implement XglDpDev::CopyBuffer() using XgliUtFbToMemCopyBuffer().

---

Note - You must also implement the LI-3 versions of copying to and from buffers, but you can use the RefDpCtx utilities li3CopyToDpBuffer() and li3CopyFromDpBuffer(). See page 329 through page 331 for more information on LI-3 copy buffer functions.

---

Description of the Software Pipeline li1CopyBuffer Function The software pipeline does not implement this function.

li1Flush() - 2D/3D

Overview This function causes pending or asynchronous processing to complete. See the xgl_context_flush() man page for information on functionality that the device pipeline needs to handle.

Syntax

void XglDpCtx{2,3}d::li1Flush(
    Xgl_usgn32      flush_action);

Input Parameters flush_action

The type of flushing that the function performs. See the man page for the options.

Attributes that the Pipeline Needs to Handle The device pipeline must handle the attributes listed in the xgl_context_flush() man page.

Description of the Software Pipeline li1Flush Function The software pipeline does not implement this function.

li1GetPixel() - 2D/3D

Overview This function gets the color value of a specified pixel. See the xgl_context_get_pixel() man page for information on functionality that the device pipeline needs to handle.

Syntax

[2D and 3D]
void XglDpCtx{2,3}d::li1GetPixel(
    Xgl_pt_i2d*     position,
    Xgl_color*      value,
    Xgl_boolean* obscured);

Input Parameters position

Location of the pixel.

value	Location where the retrieved color value is stored.
obscured	TRUE if the window is covered at that pixel position.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_context_get_pixel() man page.

Description of the Software Pipeline li1GetPixel Function This function is not implemented by the software pipeline.

li1Image() - 2D/3D

Overview This function displays a block of pixels from a raster. See the xgl_image() man page for information on functionality that the device pipeline needs to handle.

Syntax

[2D] void XglDpCtx::li1Image(
    Xgl_pt_f2d*         position,
    Xgl_bounds_i2d*     image,
    XglRaster*          src_ras);

[3D] void XglDpCtx::li1Image(
    Xgl_pt_f3d*         position,
    Xgl_bounds_i2d*     image,
    XglRaster*          src_ras);

Input Parameters position

The position in the destination Context where the copy starts. The position must be a valid point in the Context's model space.

image	The rectangular area in the source raster to be copied. If image is NULL, the maximum area of the source Raster is assigned to the value by the XGL core
src_ras	The source memory raster.

---

Note - Note that although the application can specify a NULL value for image, the XGL core assigns a valid value to this parameter before passing it to the device pipeline; thus, the pipeline does not have to test for this but can assume the value is valid.

---

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_image() man page.

Description of the Software Pipeline li1Image Function The software pipeline li1Image() function first verifies that rectangle is within the source raster's boundaries. For 3D images, the function then does model clipping if necessary. Then, for both 2D and 3D image copying, the function transforms the position point from model coordinates to device coordinates and verifies that the position in DC is not clipped; if the position point is clipped, the image is not copied. The function then clips the rectangle against the src_ras boundaries and the DC bounds, verifies that the render buffer is the draw buffer, sets up the copy information, and calls li3CopyToDpBuffer() to do the copying.

li1NewFrame() - 2D/3D

Overview This function clears the device coordinate viewport and possibly the Z-buffer. See the xgl_context_new_frame() man page for information on functionality that the device pipeline needs to handle.

Syntax

[2D and 3D]
void XglDpCtx{2,3}d::li1NewFrame();

Input Parameters None

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_context_new_frame() man page.

What the You Need to Know to Implement li1NewFrame In the case of indexed color, the plane mask during a new frame operation is different from the plane mask used for rendering. The new frame plane mask prepares the surface based on a pixel mapping offset. To simplify the processing of the new frame plane mask, the XGL core provides the inline function getNewFramePlaneMask(). This function can be called regardless of the color type of the device. The following example shows the use of getNewFramePlaneMask().

if (action & XGL_CTX_NEW_FRAME_CLEAR) { Xgl_booleanchange_flag = FALSE; Xgl_usgn32new_frame_plane_mask; new_frame_plane_mask = baseCtx->getNewFramePlaneMask(); if (cached_plane_mask != new_frame_plane_mask) { change_flag = TRUE; //set the new frame plane mask } // Perform the clear operation if (change_flag) {

// Restore the original plane mask } }

Description of the Software Pipeline li1NewFrame Function The software pipeline does not implement this function.

li1PickBufferFlush() - 2D/3D

Overview This function requires a device pipeline to empty its device pick buffer, if any, into the XGL core pick buffer. This is useful for asynchronous devices that buffer pick events. The function is called when the API function xgl_get_pick_identifiers is called. It also is called to synchronize the device's pick buffer and the XGL core pick buffer before each call to the software picking code. See the xgl_get_pick_identifiers() man page for information on functionality.

Syntax
void XglDpCtx{2,3}d::li1PickBufferFlush();

Input Parameters None

Attributes that the Pipeline Needs to Handle None

What You Need to Know to Implement li1PickBufferFlush The purpose of this function is to allow synchronization between a device's pick buffer and the pick buffer maintained by XGL's device-independent code. The device-independent picking routines call this function whenever the software pipeline detects a pick (if a pipeline has fallen back to the software pipeline to pick a particular primitive, for instance) and when the application explicitly requests to see the contents of the pick buffer (via xgl_pick_get_identifiers()).

To implement this function, device pipelines check the hardware pick buffer (if applicable) and then add the identifiers of the pick events to the XGL core pick buffer using the DI function ctx->addPickToBuffer(Xgl_usgn32 pick_id1, Xgl_usgn32 pick_id2). If a device does not support picking, then this function need not be implemented.

The Context class includes another function that compares the last recorded pick IDs with the current pick IDs and returns TRUE if they are identical. This function is checkLastPick(). This function is an optimization to allows the

device pipeline to return to the application immediately if nothing new has been picked. Note that for devices caching pick events checkLastPick() does not call li1PickBuffer Flush(). This means that the last recorded pick event might not be the last actual pick event if the pipeline's cached pick events have not been flushed in the XGL core pick buffer.

li1PickBufferFlush() takes no arguments and is only called by the software pipeline and the XGL core. A device pipeline need not call this function itself.

Description of the Software Pipeline li1PickBufferFlush Function The software pipeline does not implement this function.

li1SetMultiPixel()

Overview This function sets the color values for a list of pixel locations. See the xgl_context_set_multi_pixel() man page for information on the functionality that the device pipeline needs to handle.

Syntax

[2D and 3D]
void XglDpCtx{2,3}d::li1SetMultiPixel(
    Xgl_usgn32      count,
    Xgl_pt_i2d      *pt,
    Xgl_color       *color);

Input Parameters count

Number of pixels to write.

pt	Array of screen locations to write to.
color	Array of pixel colors to write (in one-to-one correspondence with the location array).

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_context_set_multi_pixel() man page.

Description of the Software Pipeline li1SetMultiPixel Function The software pipeline li1SetMultiPixel() function writes a set of count pixels into the locations specified by the pt array argument. The first pixel is written to (pt[0].x, pt[0].y), the next pixel is written to (pt[1].x, pt[1].y), etc. There should be at least count valid entries in the pt argument. Since this routine operates on individual pixels, rather than geometry, all coordinates are device coordinates, and the 2D and 3D versions of this routine are identical.

Each pixel color is determined by taking sucessive values from the color argument, which should contain an array of colors, one color for each pixel. The color[0] entry specifies the color for the pixel located at (pt[0].x,pt[0].y), color[1] for (pt[1].x, pt[1].y), etc. The count argument specifies the number of pixels to write. The color argument array should have at least count entries.

li1SetPixel() - 2D/3D

Overview This function sets the color value for a specified pixel. See the xgl_context_set_pixel() man page for information on functionality that the device pipeline needs to handle.

Syntax

[2D and 3D]
void XglDpCtx{2,3}d::li1SetPixel(
    Xgl_pt_i2d      *position,
    Xgl_color       *color);

Input Parameters position

Location of the pixel value to be set.

color......The color value of the pixel that is set.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_context_set_pixel() man page.

Description of the Software Pipeline li1SetPixel Function The software pipeline does not implement this function.

li1SetPixelRow() - 2D/3D

Overview This function sets the color value for a row of pixels. See the xgl_context_set_pixel_row() man page for information on functionality.

Syntax

[2D and 3D]
void XglDpCtx{2,3}d::li1SetPixelRow(
    Xgl_usgn32      start_col,
    Xgl_usgn32      row,
    Xgl_usgn32      count,
    Xgl_color       *color);

Input start_col

First x-coordinate of pixel row.

row	y-coordinate of all pixels in pixel row.
count	Number of pixels to write.
color	Array of pixel colors to write.

Attributes That the Pipeline Needs to Handle The device pipeline must handle some or all of the attributes listed in the xgl_context_set_pixel_row() man page.

Description of the Software Pipeline li1SetPixelRow Function The software pipeline li1SetPixelRow() function writes a series of count contiguous, horizontal pixels along the y-position supplied by row, starting at the x-position start_col and continuing in the direction of increasing x values. Since this routine operates on individual pixels, rather than geometry, all coordinates are device coordinates, and the 2D and 3D versions of the routine are identical. The pixel colors along the row are determined by taking sucessive values from the color argument, which should contain an array of colors, one color corresponding to to each pixel in the row. The color[0] entry specifies the color for the left-most pixel located at (start_col,row), color[1] for (start_col + 1, row), etc. The count argument specifies the number of pixels to write. The color argument array should have at least count entries.

LI2 Functions

About the LI-2 Layer

Conceptually, the LI-2 layer lies below the transformation and clipping of the LI-1 layer. While the LI-1 functions implement and make decisions regarding the geometry pipeline for each primitive, the LI-2 functions are more concerned with rendering. The LI-2 layer was designed to provide support for hardware that might not be able to perform transformations and clipping but that can still accelerate DC primitives. The LI-2 layer provides a porting layer that is simpler to port to than LI-1 but that renders faster than the dot/span layer LI-3.

In general, the LI-2 renderers are passed an internal data structure containing a list of points or a list of point lists in device coordinates. These points have already been view clipped, and, in the case where the canvas is completely exposed (window rasters only), the points have been window clipped as well. The calling function is responsible for setting the attributes in the Context to be used by the LI-2 routine: for example, when rendering a hollow polygon using the polyline renderer, the line color attribute should be set to reflect the polygon color.

For 3D Contexts, the LI-2 renderers are similar to the 2D case. The calling LI-1 function should perform any applicable lighting and depth cueing; however, if depth cueing is enabled, 3D LI-2 functions must handle DC offset and interpolate colors.

LI-2 Surface Attributes

Table 9-10 lists the attributes that must be accounted for by the LI-2 surface primitives. Note that Context.h and Context3d.h provide interfaces for the pipeline to get a number of 3D surface attributes within a single structure. These functions can facilitate device pipeline manipulation of 3D surface attributes. At LI-2, face determination has already taken place. Using these interfaces, a pipeline can set up the surface attribute pointer based on the

facing in the renderer and do all the attribute processing without referring to the actual facing. See page 127 and page 129 for information on these interfaces.

Table 9-10

	Attributes
2D and 3D	getSurfFrontColor() getSurfFrontColorSelector() getSurfFrontFpat() getSurfFrontFpatPosition() getSurfFrontFillStyle() getEdgeAltColor() getEdgeCap() getEdgeColor() getEdgeJoin() getEdgeMiterLimit() getEdgePattern() getEdgeStyle() getEdgeWidthScaleFactor() getSurfEdgeFlag() getSurfInteriorRule() getRop()
3D only	getSurfBackColor() getSurfBackColorSelector() getSurfBackFillStyle() getSurfBackFpat() getSurfBackFpatPosition() getHlhsrMode() getSurfDcOffset() getDepthCueMode() getDepthCueInterp()

Mapping of LI-2 Functions to LI-3 Functions in the Software Pipeline

Table 9-11 shows the mapping of the 2D LI-2 functions to LI-3 functions or other LI-2 functions.

Table 9-11

LI-2 Function	LI-2 Function
li2GeneralPolygon()	li3MultiSpan() li2MultiPolyline()(hollow polygons or edges on)
li2MultiDot()	li3MultiDot()
li2MultiEllipse()	li3MultiSpan() li2GeneralPolygon()(rotation angles)
li2MultiEllipticalArc()	li3Vector()(straight lines of sectors or chords) li3MultiSpan() li2MultiPolyline()(rotation angles - open) li2GeneralPolygon()(rotation angles - closed)
li2MultiPolyline()	li3Vector()(thin lines) li3MultiSpan()(wide lines)
li2MultiRect()	li3MultiSpan() li2MultiPolyline()(hollow rects or edges on)
li2MultiSimplePolygon()	li3MultiSpan() li2MultiPolyline()(hollow polygons or edges on)

Table 9-12 shows the mapping of the 2D LI-2 functions to LI-3 functions and other LI-2 functions.

Table 9-12

LI-2 Function	Li-2 Function
li2GeneralPolygon()	li3MultiSpan() li2MultiPolyline()(hollow polygons or edges on)
li2MultiDot()	li3MultiDot()
li2MultiPolyline()	li3Vector()(thin lines) li2TriangleList()(wide lines)

Table 9-12

LI-2 Function	Li-2 Function
li2MultiSimplePolygon()	li2GeneralPolygon()
li2TriangleList()	li3MultiSpan()(filled surfaces) li2MultiPolyline()(hollow triangles or edges on)
li2TriangleStrip()	li3MultiSpan()(filled surfaces) li2MultiPolyline()(hollow triangles or edges on)

li2GeneralPolygon() - 2D/3D

Overview This function scan converts a polygon to span lines. A general polygon routine supports geometry that cannot be easily tesselated (such as multi-bounded polygons) and provides an opportunity for hardware to handle such cases. The li2GeneralPolygon() function is expected to support different interior styles and fill rules (even-odd only), and to handle edges.

Syntax

void XglDpCtx{2,3}d::li2GeneralPolygon(
    XglPrimData* pd);

Input Parameters pd

Pointer to an XglPrimData object containing a list of point lists specifying a single (possibly multi-bounded) polygon.

Attributes That the Device Pipeline Needs to Handle See Table 9-10 on page 309 for a list of attributes that this function must handle.

Description of the Software Pipeline li2GeneralPolygon To render filled surfaces, li2GeneralPolygon() scan converts the polygon to a list of span lines and calls the device pipeline li3MultiSpan() function to draw the list of spans. For 3D polygons, the function handles texture mapping, adds the surface DC offsets to the Z value, and calls the pipeline li3MultiSpan()function.

To render hollow surfaces or edges, the function converts the point list into point lists for multipolylines, sets the current stroke to hollow or edge, and calls the device pipeline li2MultiPolyline() function.

li2MultiDot() - 2D/3D

Overview A multi-dot routine at the LI-2 level provides the opportunity for hardware to accelerate dot markers.

Syntax

[2D and 3D}
void XglDpCtx{2,3}d::li2MultiDot(
    XglPrimData* pd);

Input Parameters pd

Pointer to an XglPrimData object containing a list of marker positions in device coordinates.

Attributes That the Device Pipeline Needs to Handle A device pipeline must handle the following attributes.

XglContext::getMarkerColorSelector()
XglContext::getMarkerColor()

Description of the Software Pipeline li2MultiDot Function The software pipeline li2MultiDot() function determines the marker color based on the marker color selector, the input point type, or in the 3D case, the depth cueing mode. It then calls the device pipeline li3MultiDot()function to draw the markers.

li2MultiEllipse() - 2D

Overview This function scan converts ellipses to span lines. Although there is no ellipse in the 2D API, XGL provides li2MultiEllipse() to support hardware that can accelerate a regular circle or a circle with uneven scale in DC. This function is expected to handle different interior fill styles and edges.

Syntax

void XglDpCtx2d::li2MultiEllipse(
    XglConicData2d*ellipses);

Input Parameter ellipses

Pointer to an XglConicData2d object containing a list of ellipses, with each ellipse specified with a center point, and a major and minor axis in DC.

Attributes See Table 9-10 on page 309 for a list of attributes that this function must handle.

Description of the Software Pipeline li2MultiEllipse Function For ellipses without rotation angles, the software pipeline converts each ellipse to a list of span lines and calls li3MultiSpan() to draw the spans.

For ellipses with rotation angles, the ellipse is tessellated to a list of points, and the pipeline li2GeneralPolygon() is called to draw the geometry.

li2MultiEllipticalArc() - 2D

Overview This function scan converts elliptical arcs to span lines. Although there is no ellipse in the 2D API, XGL provides li2MultiEllipticalArc() to support hardware that can accelerate a circular arc with uneven scale in DC. You may want to implement li2MultiEllipticalArc() if your hardware can accelerate arcs or elliptical arcs. The function is expected to handle different interior fill styles and edges, and different arc fill styles.

Syntax

void XglDpCtx2d::li2MultiEllipticalArc(
    XglConicData2d*arcs);

Input Parameters arcs

Pointer to an XglConicData2d object containing a list of partial ellipses, with each ellipse specified with a center point, major and minor axes, and a start and stop angle in DC.

Attributes A device pipeline must handle the following attribute in addition to the surface attributes listed in Table 9-10 on page 309.

XglContext::getArcFillStyle()

Description of the Software Pipeline li2MultiEllipticalArc Function For elliptical arcs without rotation angles, the software pipeline scan converts the interior and arc borders to a list of span lines and calls i3MultiSpan() to draw the spans. If the arcs have a fill style (XGL_CTX_ARC_FILL_STYLE) of XGL_ARC_SECTOR or XGL_ARC_CHORD and have thin lines for the line segments, the device pipeline LI-3 function li3Vector() is called to draw the lines. The line segments of arcs with a fill style of XGL_ARC_SECTOR or XGL_ARC_CHORD and with thick lines for the line segments are drawn with li3MultiSpan(). For ellipses with rotation angles, if the arc fill style is open, the arc is tessellated to a list of points, and li2MultiPolyline() is called. If the arc is closed, li2GeneralPolygon() is called.

li2MultiPolyline() - 2D

Overview This function is expected to handle wide lines and wide patterned lines as well as thin lines and thin patterned lines.

The li2MultiPolyline routine is the most multiplexed of the LI-2 functions. Since this routine is called by the other stroke primitives, the polyline attributes (color, style, width, etc.) are read from the current stroke group in the Context object. It is the responsibility of the calling routine to set the stroke group appropriately for the original primitive; it is the responsibility of the LI-2 multipolyline function to get the polyline attributes from the current stroke group. See page 106 for information on the stroke group.

Syntax

void XglDpCtx::li2MultiPolyline(
    XglPrimData* pd);

Input Parameters pd

Pointer to an XglPrimData object containing point lists describing multiple, disjoint polylines. A flag that specifies whether each polyline is closed is also included.

Attributes A device pipeline must handle the following attributes.

XglContext::getRop()
XglContext::getCurrentStroke()
XglStrokeGroup::getAaBlendEq()
XglStrokeGroup::getAaFilterWidth()
XglStrokeGroup::getAaFilterShape()
XglStrokeGroup::getAltColor()
XglStrokeGroup::getCap()
XglStrokeGroup::getColor()
XglStrokeGroup::getColorSelector()
XglStrokeGroup::getJoin()
XglStrokeGroup::getMiterLimit()
XglStrokeGroup::getPattern()
XglStrokeGroup::getStyle()

XglStrokeGroup::getWidthScaleFactor()
XglStrokeGroup::getExpectedFlagValue()
XglStrokeGroup::getFlagMask()

What You Should Know to Implement li2MultiPolyline There is a flag in li3Vector() that determines whether the last pixel of a line segment is drawn. To prevent drawing the shared pixel twice for consecutive lines, set the draw_last_pixel flag for li3Vector() to FALSE. Then, set it to TRUE for the last segment in the polyline.

In addition, when the point type has flag information, the device pipeline must check the stroke group flag mask and expected flag value to determine whether individual segments of the line should be drawn. For more information, see "Flag Mask and Expected Flag Value" on page 111.

Description of the Software Pipeline 2D li2MultiPolyline Function For thin lines and thin patterned lines, the software pipeline 2D li2MultiPolyline() function calls li3SetVectorControl to set the attributes for the LI-3 line renderers and calls li3Vector() function to draw the lines.

To render wide lines as well as caps and joins, the software implementation creates a list of span lines. The span lines are sorted, and clipped if necessary, for certain ROP modes so that correct rendering will occur with span lines overlap. The list of spans is drawn with the li3MultiSpan() function.

li2MultiPolyline() - 3D

Overview This function is expected to handle wide lines and wide patterned lines as well as thin lines and thin patterned lines. Device pipelines that call li2MultiPolyline() for wide lines may also want to implement li2TriangleList() for triangle stars if the device can accelerate triangles.

The li2MultiPolyline routine is the most multiplexed of the LI-2 functions. Since this routine is called by the other stroke primitives, the polyline attributes (color, style, width, etc.) are read from the current stroke group in the Context object. It is the responsibility of the calling routine to set the stroke group appropriately for the original primitive; it is the responsibility of the LI-2 function to get the stroke attributes from the current stroke group. See page 106 for information on the stroke group.

Syntax

void XglDpCtx3d::li2MultiPolyline(
    XglPrimData *pd);

Input Parameters pd

Pointer to an XglPrimData object containing point lists of vertex coordinates of the lines in device coordinates.

Attributes A device pipeline must handle the following attributes.

XglContext::getRop()
XglContext3d::getHlhsrMode()
XglContext::getCurrentStroke()
XglStrokeGroup::getAaBlendEq()
XglStrokeGroup::getAaFilterWidth()
XglStrokeGroup::getAaFilterShape()
XglStrokeGroup::getAltColor()
XglStrokeGroup::getCap()
XglStrokeGroup::getColor()
XglStrokeGroup::getColorSelector()
XglStrokeGroup::getJoin()
XglStrokeGroup::getMiterLimit()

  XglStrokeGroup::getPattern()
  XglStrokeGroup::getStyle()
  XglStrokeGroup::getWidthScaleFactor()
  XglStrokeGroup::getExpectedFlagValue()
  XglStrokeGroup::getFlagMask()
  XglStrokeGroup3d::getDcOffset()
  XglStrokeGroup3d::getColorInterp()

Description of the Software Pipeline li2MultiPolyline Function The software pipeline 3D li2MultiPolyline() function breaks lines into line segments and sends the segments individually to either li3Vector() or li2TriangeList().

If the value of the width scale factor attribute for the line is less than 2.0, the function creates individual line segments, puts each line segment into an Xgli_vector_3d structure, and then calls li3Vector() for rendering.

Wide lines and relevant caps and joins are converted to triangle stars. Specifically, if the line width scale factor is equal to or greater than 2.0, the function creates rectangular line segments, converts each segment into triangle stars, and calls li2TriangleList() for rendering. Patterned wide lines are broken down at each pattern boundary, so only solid triangle stars are sent to li2TriangleList().

li2MultiRect() - 2D

Overview This function scan converts rectangles to span lines and is expected to handle different interior fill styles and edges. It is provided for hardware that can accelerate rectangles and provides an opportunity to reduce the amount of data copied (2 corners versus 4 points if a polygon routine is used.)

Syntax

void XglDpCtx2d::li2MultiRect(
    XglRectData2d* rects);

Input Parameters rects

Pointer to an XglRectData2d object containing a list of rectangles specified by their corners.

Attributes See Table 9-10 on page 309 for a list of attributes that this function must handle.

Description of the Software Pipeline li2MultiRect Function If the interior style of the surface is solid, stippled, opaque-stippled, or patterned, the software pipeline li2MultiRect() function scan converts the polygon to a list of span lines and calls li3MultiSpan() to draw the spans. If the interior style of the surface is hollow or if the edge flag is on, li2MultiPolyline() is called with the stroke group set to hollow or edge accordingly.

This function is not currently used by any LI-1 functions in the software pipeline. In the future, li2MultiRect() may be called from the li1MultiRectangle() function if the MC-to-DC transform does not contain any rotations.

li2MultiSimplePolygon() - 2D

Overview This function scan converts polygons to span lines. It is expected to handle different fill styles and edges. This function is provided for hardware that can accelerate single-bounded polygons.

Syntax

void XglDpCtx2d::li2MultiSimplePolygon(
    XglPrimData* pd);

Input Parameters pd

Pointer to an XglPrimData object containing a list of point lists in device coordinates, each describing a single, bounded polygon.

Attributes See Table 9-10 on page 309 for a list of attributes that this function must handle.

Description of the Software Pipeline li2MultiSimplePolygon Function To render filled surfaces, the software pipeline scan converts the polygon to a list of span lines and calls li3MultiSpan() to draw the spans.

To render hollow surfaces or edges, the software pipeline sets the stroke group to hollow or edge and calls li2MultiPolyline().

This function is not currently used by any LI-1 functions in the software pipeline. In the future, li2MultiSimplePolygon() may be called from li1MultiSimplePolygon().

li2MultiSimplePolygon() - 3D

Overview This function scan converts polygons to span lines and provides support for single-bounded polygons. This function is expected to handle different fill styles and edges.

Syntax

void XglDpCtx3d::li2MultiSimplePolygon(
    XglPrimData*pd);

Input Parameters pd

Pointer to an XglPrimData object containing a list of polygons.

Attributes See Table 9-10 on page 309 for a list of attributes that this function must handle.

Description of the Software Pipeline li2MultiSimplePolygon Function The software pipeline li2MultiSimplePolygon() function calls li2GeneralPolygon() in a loop for each simple polygon. In future releases, the software pipeline may provide optimized code to process the polygons.

li2TriangleList() - 3D

Overview This function renders single-facing, non-mixed triangle lists in the form of triangle strips, triangle stars, or unconnected triangles in device coordinates.

Syntax

void XglDpCtx3d::li2TriangleList(
    XglPrimData*pd);

Input Parameters pd

Pointer to an XglPrimData object containing point lists of either single-facing triangle strips, triangle stars, or unconnected triangles based on the value of the triangle list render flags. The triangle point list cannot be mixed. All surfaces must be single facing.

Attributes A device pipeline must handle the following attribute in addition to the surface attributes listed in Table 9-10 on page 309.

XglLevel::getRenderFlags()
XglContext3d::getDepthCueInterp()
XglContext3d::getDepthCueMode()
XglContext3d::getHlhsrMode()

Description of the Software Pipeline li2TriangleList Function To render triangle strips, the software pipeline function checks the level data rendering flags and calls li2TriangleStrip(). To render filled surfaces, the function scan converts triangle stars and independent triangles into lists of spans. It handles color selection and texture mapping, adds the corresponding surface DC offsets to the Z value, and calls li3MultiSpan(). See page 216 for information on texture mapping. To render hollow triangles or edges, the function converts the triangle point list into point lists for multipolylines, assigns the current stroke, and calls the device pipeline li2MultiPolyline() function.

li2TriangleStrip() - 3D

Overview This function handles single-facing triangle strips.

Syntax

void XglDpCtx3d::li2TriangleStrip(
    XglPrimData*pd);

Input Parameters pd

An XglPrimData object containing point lists of single-facing triangle strips in device coordinates.

Attributes A device pipeline must handle the following attributes in addition to the surface attributes listed in Table 9-10 on page 309.

XglLevel::getRenderFlags()
XglContext3d::getDepthCueInterp()
XglContext3d::getDepthCueMode()
XglContext3d::getHlhsrMode()

Description of the Software Pipeline li2TriangleStrip Function The software pipeline li2TriangleStrip() function first processes the input point lists into separate triangles. Then, for filled surfaces, the function scan converts the triangle strips into lists of spans. It handles color selection and texture mapping, adds the corresponding DC offsets to the Z value, and calls li3MultiSpan(). See page 216 for information on texture mapping.

To render hollow surfaces or edges, the function converts the triangle point list into lists of points for multipolyline, handles color selection, assigns the current stroke, and calls li2MultiPolyline().

LI-3 Functions

About the LI-3 Layer

The LI-3 layer is the lowest level of the XGL interface hierarchy. The LI-3 layer consists of control functions, primitive functions, and begin/end batching functions. It also includes functions that copy pixel data to and from buffers managed by the device pipeline. The primitive functions are listed in Table 9-13.

Table 9-13

Function	Description
li3MultiDot()	Draws a list of dots.
li3MultiSpan()	Draws a list of horizontal spans.
li3Vector()	Draws a single vector.

The control functions set the attributes for LI-3 primitives. The begin/end batching functions are used to indicate that a series of the same LI-3 primitives will be sent and that the state will not change between successive calls. This allows the device pipeline some opportunities for optimization when implementing LI-3.

There is no software pipeline implementation of the LI-3 functions; therefore, each device pipeline must implement all of the LI-3 operators for 2D and 3D primitives. However, to help you with this task, there is a set of utilities called RefDpCtx (Reference Device Pipeline Context), which implements the LI-3 layer. RefDpCtx is built on a simple get-pixel and put-pixel interface; it is not meant to provide fast performance but to enable the device pipeline to get XGL running relatively quickly. See "RefDpCtx" on page 348 for more details on using RefDpCtx to implement the LI-3 layer.

Note that although the 2D versions of the primitive functions are straightforward, the 3D versions are more complicated because they must support antialiasing, shading, and texture mapping. The 3D version of LI-3 is perhaps more complex than it should be; however, you can use RefDpCtx to implement the difficult cases.

Notes on Implementing LI-3 Functions

The main caller of LI-3 functions is the software pipeline LI-2 layer (the device pipeline could call its own LI-3 functions, but that is not very likely). The calling sequence from the software pipeline LI-2 layer to the device pipeline LI-3 layer is:

set Context attributes (if needed)
li3Set<Prim>Control (if needed)
li3Begin(<Prim>)
    li3<Prim> (called as many times as needed)
li3End(<Prim>)

where <Prim> is one of the LI-3 primitive functions. All device pipeline LI-3 primitives called by the software pipeline are surrounded by li3Begin()and li3End() calls. Within the li3Begin()/li3End() pair, only the primitive type specified in the li3Begin() function can be called, and no other Context or primitive functions can be called. Within a begin/end, neither the Context nor the LI-3 state will change, and the device pipeline can continue to render. li3Begin() returns a Boolean value: TRUE means that the LI-3 primitive will be visible when rendered; FALSE means that the LI-3 primitive function will not draw anything because the window is obscured, so the device pipeline may not want to call the primitive function.

The LI-3 implementation must take into account the color type of the Device and the color type specified by the XGL API. To do this, the LI-3 implementation may want to get the following information from the Device.

XglRaster::getDoPixelMapping()
XglDevice::getColorType()
XglDevice::getRealColorType()
XglDevice::getCmap()
XglDevice::getDrawable()

The LI-3 implemenation also must be aware of the rendering buffer as specificed by:

XglContext::getRenderBuffer()

All LI-3 2D functions receive geometry data in 2D integer Device Coordinates. The geometry will be within the bounds of the Device, but it is up to the LI-3 implementation to clip the primitives to the window clip list. All 3D LI-3 geometric coordinates are specified in floating 3D Device coordinates and, as such, may have fractional components for the coordinate values.

Attributes relevant to the LI-3 functions are listed on the page for each function description.

---

Note - As in the other LI layers, LI-3 requires that window locking be done around each LI-3 rendering call.

---

Picking at LI-3

The 3D LI-3 primitive functions return a Boolean parameter picked. This parameter returns TRUE if the primitive was picked via Z-buffer-based picking (if Z-buffering is on and picking is on). LI-1 and LI-2 will have already pruned the geometric data to be inside the pick aperture; LI-3 functions must test if the geometry is visible based upon the Z comparison method.

The picked return value is an optimization for LI-2. If the return value is TRUE, then LI-2 can stop sending primitives. The software pipeline LI-2 function which calls LI-3 will update the pick buffer. It is allowable, however, for LI-3 to always return FALSE, but in this case, the LI-3 function must update the pick buffer by using the XglContext function ctx->addPickToBuffer (Xgl_usgn32 pick_id1, Xgl_usgn32 pick_id2). The device pipeline code need only fill in the picked parameter if picking is enbled. If picking is disabled, it can be ignored.

---

Note - LI-3 functions are only called to do picking if Z-buffering is enabled.

---

Where to Look for More Information

For more information on LI-3 data structures and functions, refer to the header files Li3Structs.h, Li3Structs2d.h, and Li3Structs3d.h. If you are planning on using RefDpCtx, refer to RefDpCtx.h, RefDpCtx2d.h, and RefDpCtx3d.h.

li3Begin() and li3End() - 2D/3D

Syntax

[2D]
Xgl_boolean XglDpCtx2d::li3Begin(
    Xgli_layer_prim_2d      prim_type);

void XglDpCtx2d::li3End(
    Xgli_layer_prim_2d      prim_type);

[3D]
Xgl_boolean XglDpCtx3d::li3Begin(
    Xgli_layer_prim_3d      prim_type);

void XglDpCtx::li3End(
    Xgli_layer_prim_3d      prim_type);

Input Parameters prim_type

The type of primitive that is called between the LI-3 Begin/End calls.

Attributes That the Device Pipeline Needs to Handle There are no specific attributes used by these functions.

What You Need to Know to Implement li3Begin and li3End

li3Begin() specifies the beginning of a sequence of LI-3 primitives of type prim_type; li3End() indicates the end of the sequence. In between the Begin/End pair, only the specified LI-3 primitive function will be called, there will not be any calls to other LI-3 functions or calls to the Context. It is permissible for the implementation of li3Begin() to call WIN_LOCK and to hold the lock until li3End() is called. However, the implementation must be sure that the lock does not time out; that is, the implementation may have to release and then reaquire the lock before li3End() is called.

li3Begin() returns TRUE if the primitive will be visible when rendered and FALSE if it will not be. For example, the primitive would not be visible if the window were completely covered.

li3CopyFromDpBuffer() - 2D/3D

Syntax

[2D and 3D]
void XglDpCtx2d::li3CopyFromDpBuffer(
    const Xgl_bounds_i2d*       src_rect,
    const Xgl_pt_i2d*           dest_pos,
    Xgl_buffer_sel              sel,
    XglPixRectMem*              buf);

Input Parameters src_rect

A rectangle in the device pipeline's coordinates (relative to the origin of the window).

dest_pos	The position to copy to (relative to the origin of buf).
sel	Selects an image buffer in the pipeline, when the pipeline is multi-buffering, to copy out of.
buf	The PixRect buffer where the data is copied into.

Attributes That the Device Pipeline Needs to Handle There are no specific attributes used by this function.

What You Need to Know to Implement li3CopyFromDpBuffer This function copies pixel data from the device pipeline's frame buffer into memory. The memory is represent by a PixRectMem object (see PixRect.h and PixRectMem.h). The PixRect is the same depth as the framebuffer.

---

Note - Currently, 2D li3CopyFromDpBuffer() is not called by the software pipeline.

---

li3CopyToDpBuffer() - 2D

Syntax

void XglDpCtx2d::li3CopyToDpBuffer(
    const Xgl_bounds_i2d*       src_rect,
    const Xgl_pt_i2d*           dest_pos,
    Xgl_buffer_sel              sel,
    const XglPixRectMem*        buf,
    Xgli_copy_to_dp_info*       copy_info);

Input Parameters src_rect

A rectangle in buf's coordinates.

dest_pos	The position to copy to (relative to origin of the window).
sel	An image buffer in the device pipeline, when the device pipeline is multi-buffering, to copy into.
buf	The PixRect buffer where the data is copied from.
copy_info	Contains information about the incoming data such as the color map and color type of the data.

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getRealPlaneMask()
XglContext::getRop()

What You Need to Know to Implement li3CopyToDpBuffer This function copies pixel data to the device pipeline's framebuffer out of memory. The memory is represent by a PixRectMem object (see PixRect.h and PixRectMem.h). The PixRect is the same depth as the frame buffer.

This function may be used to implement xgl_copy_buffer() in the future; review the comments in the definition of Xgli_copy_to_dp_info in the file Li3Structs.h.

li3CopyToDpBuffer() - 3D

Syntax

void XglDpCtx3d::li3CopyToDpBuffer(
    const Xgl_bounds_i2d*       src_rect,
    const Xgl_pt_i2d*           dest_pos,
    Xgl_buffer_sel              sel,
    const XglPixRectMem*        buf,
    Xgli_copy_to_dp_info*       copy_info);

Input Parameters src_rect

A rectangle in buf's coordinates.

dest_pos	The position to copy to (relative to origin of the window).
sel	An image buffer in the device pipeline, when the device pipeline is multi-buffering, to copy into.
buf	The PixRect buffer where the data is copied from.
copy_info	Contains information about the incoming data such as the color map and color type of the data. See Li2Structs.h.

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getBackgroundColor()
XglContext::getRealPlaneMask()
XglContext::getRop()
XglContext::getSurfFrontColor()

What You Need to Know to Implement 3D li3CopyToDpBuffer This function copies pixel data to the device pipeline's frame buffer out of memory. The memory is represent by a PixRectMem object (see PixRect.h and PixRectMem.h). The PixRect is the same depth as the frame buffer. If the copy_info pointer is NULL, the implementation of li3CopyToDpBuffer() operates as if a structure was given with copy_info->do_zbuffer set to FALSE and copy_info->do_fill_style set to FALSE.

The Xgli_copy_to_dp_info structure is used to provide information for li3CopyToDpBuffer(). The structure contains color map information for the source PixRect or raster; the pipeline needs to process this information. The structure also contains a flag to control whether the copy uses the Z-buffer. This flag will be FALSE for 2D Contexts but may be TRUE for 3D Contexts. In addition, the structure includes a flag for implementing fill style, but currently this flag will always be FALSE. See Li3Structs.h for comments in the definition of Xgli_copy_to_dp_info.

This function may be used to implement xgl_copy_buffer() in the future. Currently, for 3D, li3CopyToDpBuffer() is used by the accumulation operation and by xgl_image().

li3MultiDot() - 2D

Syntax

void XglDpCtx2d::li3MultiDot(
    const XglPrimData*      pd,
    const Xgl_color*        color);

Input Parameters pd

An XglPrimData object containing a list of point locations for the marker positions.

color......The color value for the marker, if applicable.

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getRealPlaneMask()
XglContext::getRop()

What You Need to Know to Implement li3MultiDot This function draws a list of dots (i.e pixels) at the X,Y locations given in pd. If color is not NULL, then all of the dots are draw in that color. If it is NULL, then each dot is drawn in the color given by the per vertex color in pd.

li3MultiDot() - 3D

Syntax

void XglDpCtx3d::li3MultiDot(
    const XglPrimData*          pd,
    const Xgl_color*            color,
    Xgl_boolean*                picked);

Input Parameters pd

Locations of the rendered dots.

color......Color of the dots.

Output Parameter picked

TRUE if the primitive has been picked by Z-buffer-based picking.

Related Data Structures

const Xgli_dot_control_3d& li3GetDotControl() const;

void li3SetDotControl(const Xgli_dot_control_3d&);

typedef struct {
    Xgl_boolean         do_aa;

    // This is ignored if do_aa is FALSE.
    Xgli_aa_info        aa_info;

    Xgl_usgn32          unused[4];
} Xgli_dot_control_3d;

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getPickEnable()
XglContext::addPickToBuffer
XglContext::getPickId1()
XglContext::getPickId2()
XglContext::getBackgroundColor()
XglContext::getRealPlaneMask()

XglContext::getRenderBuffer()
XglContext::getRop()
XglContext3d::getBlendFreezeZBuffer()
XglContext3d::getHlhsrData()
XglContext3d::getHlhsrMode()
XglContext3d::getZBufferCompMethod()
XglContext3d::getZBufferWriteMask()

What You Need to Know to Implement 3D li3MultiDot This function draws a list of dots at the X,Y locations given in pd. If color is not NULL, then all of the dots are draw in that color. If color is NULL, the each dot is drawn in the color given by the per vertex color in pd.

The control structure specifies if dots are antialiased. If they are, then a dot will touch more than one pixel.

li3Vector() - 2D

Syntax

Xgl_usgn32 XglDpCtx2d::li3Vector(
    const Xgli_vector_2d*           vector,
    const Xgl_color*                color);

Input Parameters vector

Pointer to a structure defining the vector. Refer to the structure Xgli_vector_2d below.

color......Color of the vector.

Related Data Structures

const Xgli_vector_control_2d& li3GetVectorControl() const;

void li3SetVectorControl(
    const Xgli_vector_control_2d&);

typedef struct {
    Xgl_line_style              line_style;// style for vector
    const XglLinePattern*       pattern;// pattern to use
                                    // for PATTERNED
                                    // or ALT_PATTERNED
    const Xgl_color*            alt_color;// ALT_PATTERNED color
} Xgli_line_style_info;

typedef struct {
    Xgli_line_style_info        line_style_info;
    Xgl_usgn32                  unused[4];
} Xgli_vector_control_2d;

typedef struct {
    Xgl_pt_i2d*         p1;              // end point 1
    Xgl_pt_i2d*         p2;              // end point 2
    Xgl_boolean         draw_last_pixel; // controls whether last
                                         // pixel is drawn.
    // the following is used for PATTERNED or ALT_PATTERNED vectors;
    Xgl_usgn32          pat_offset;      // pattern offset
} Xgli_vector_2d;

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getRealPlaneMask()
XglContext::getRop()

What You Need to Know to Implement li3Begin and li3End The li3Vector() function draws a vector from vector->p1 to vector->p2. The function returns the number of pixels that will be drawn for the vector if it is not window clipped. This information is used by the software pipeline LI-2 to manage the pattern information for a polyline. If the flag vector->draw_last_pixel is TRUE, the whole vector is drawn, if it is FALSE, then the last pixel in the vector is not drawn.

The parameter color gives the color for the line and for the foreground pixels in an alt-patterned vector. The line_style_info argument controls whether the vector is solid, patterned or alt patterned. The line_style_info->pattern argument gives the pattern information.

li3Vector() - 3D

Syntax

Xgl_usgn32 XglDpCtx3d::li3Vector(
    const Xgli_vector_3d*           vector,
    const Xgl_color*                color,
    Xgl_boolean*                    picked);

Input Parameters vector

Pointer to a structure defining the vector. Refer to the structure Xgli_vector_3d below.

color......Color of the vector.

Output Parameter picked

TRUE if the primitive has been picked by Z-buffer-based picking.

Related Data Structures

const Xgli_vector_control_3d& li3GetVectorControl() const;

void li3SetVectorControl(const Xgli_vector_control_3d&);

typedef struct {
    Xgli_line_style_info        line_style_info;
    Xgli_blend_type             blend_type;
    union {
        Xgli_transp_info        transp_info; // if a vector is
                            // used to draw hollow;
                            // it could be transparent.
        Xgli_aa_info            aa_info;
    } blend_info;
    Xgl_usgn32                  unused[4];
} Xgli_vector_control_3d;

typedef struct {
    Xgl_pt_f3d*         p1;              // end point 1
    Xgl_pt_f3d*         p2;              // end point2
    Xgl_color*          p1_color;
    Xgl_color*          p2_color;
    Xgl_color*          p1_alt_color;    // alt color for
                                         // alt patterning
    Xgl_color*          p2_alt_color;
    Xgl_boolean         draw_last_pixel; // controls if last pixel
                                         // is drawn.
    // the following is used for patterned vectors
    Xgl_usgn32          pat_offset;      // pattern offset
    Xgl_usgn32          unused[8];
} Xgli_vector_3d;

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getPickEnable()
XglContext::addPickToBuffer
XglContext::getPickId1()
XglContext::getPickId2()
XglContext::getBackgroundColor()
XglContext::getRealPlaneMask()
XglContext::getRenderBuffer()
XglContext::getRop()
XglContext3d::getBlendFreezeZBuffer()
XglContext3d::getHlhsrData()
XglContext3d::getHlhsrMode()
XglContext3d::getZBufferCompMethod()
XglContext3d::getZBufferWriteMask()

What You Need to Know to Implement 3D Li3Vector This function draws a vector from vector->p1 to vector->p2. The function returns the number of pixels would be drawn for the vector if it is not window clipped. This information is used by the software pipeline LI-2 to manage the pattern information for a polyline. If the flag vector->draw_last_pixel is TRUE, the whole vector is drawn; if it is FALSE, then the last pixel in the vector is not drawn.

The parameter color gives the color for the line and for the foreground pixels in an alternate patterned vector. If color is NULL, then vector->p1_color and vector->p2_color values are interpolated.

The line_style_info controls if the vector is solid, patterned or alt patterned. line_style_info->pattern gives the pattern information.

If the line style is alt-patterned and vector->pt1_alt_color and vector->pt2_alt_color are not NULL, then these colors are interpolated, and the interpolated color is used as the alternate pattern color. It is possible to interpolate the primary colors for the vector and use a constant alt color. In this case, vector->pt1_alt_color and vector->pt2_alt_color will be NULL, and the line_style_info.alt_color will be used.

The control structure allows for using vectors to implement transparent, hollow polygon edges, but we do not support this in XGL 3.0.1.

Vectors may be antialiased. The rule for determining if a vector is antialiased is:

// For now blending is only done when apiColorType is RGB
control.do_blend = ((vecCtrl.blend_info.aa_info.blend_eq !=
                       XGL_BLEND_NONE)
        && (vecCtrl.blend_info.aa_info.filter_width > 1)
        && (vecCtrl.blend_type == XGLI_BLEND_TYPE_AA)
        && (apiColorType == XGL_COLOR_RGB));

li3MultiSpan() - 2D

Syntax

void XglDpCtx2d::li3MultiSpan(
    const Xgli_span_list_2d*        span_list,
    const Xgl_color*                color);

Input Parameters span_list

Pointer to a structure defining the list of spans to be rendered. Refer to the structure Xgli_span_list_2d below.

color......Controls the color of the spans in the list.

Related Data Structures

const Xgli_span_control_2d&li3GetSpanControl() const;
void  li3SetSpanControl(const Xgli_span_control_2d&);

typedef struct {
    Xgl_surf_fill_style         fill_style;
    const XglRasterMem*         fill_raster;
    Xgl_pt_i2d                  offset;  // DC coord offset for
                                         // realizing Fpat
                                         // position attribute.
} Xgli_fill_style_info;

typedef struct {
    Xgli_fill_style_info        fill_style_info;
    Xgl_usgn32                  unused[4];
} Xgli_span_control_2d;

typedef struct {
    Xgl_usgn32  num_x;
    Xgl_usgn32  y_start;
    Xgl_usgn32  x_start;
    Xgl_sgn32   x_delta;       // either +1 or -1
    Xgl_color*  color;
} Xgli_span_2d;

typedef struct {
    Xgl_usgn32                 num_spans;
    Xgli_span_2d               *spans;
} Xgli_span_list_2d;

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getRealPlaneMask()
XglContext::getRop()
XglContext::getBackgroundColor() (for opaque stipple filled
patterns)

What You Need to Know to Implement li3MultiDot This function draws a list of spans. A span is a horizontal run of pixels given by a starting X and Y location and the number of pixels to draw in the X direction. The X direction may be either to the left or to the right of the starting location.

The color parameter controls if all of the spans are drawn in the same color (then this parameter is not NULL) or if the color field in the span structure specifies the color for each span (then this parameter is NULL).

Spans can be filled with a pattern. The fill_style_info control fields specify the fill style for the spans and give the raster pattern to use for patterned spans.

li3MultiSpan() - 3D

Syntax

void XglDpCtx3d::li3MultiSpan(
    const Xgli_span_list_3d*        span_list,
    const Xgl_color*                color,
    Xgl_boolean*                    picked);

Input Parameters span_list

Pointer to a structure defining the list of spans to be rendered. Refer to the structure Xgli_span_list_3d below.

color......Controls the color of the spans in the list.

Output Parameter picked

TRUE if the primitive has been picked by Z-buffer-based picking.

Related Data Structures

const Xgli_span_control_3d&li3GetSpanControl() const;

void li3SetSpanControl(const Xgli_span_control_3d&);

typedef struct {
    Xgli_fill_style_info        fill_style_info;

    Xgli_blend_type             blend_type;   // only NONE,
                                              // SCREEN_DOOR,
                                              // or TRANSP
    Xgli_transp_info            transp_info;

    Xgl_boolean                 do_texturing;
    Xgl_boolean                 do_lighting;
    Xgl_usgn32                  unused[4];
} Xgli_span_control_3d;

typedef struct {
    Xgl_usgn32          num_x;

    Xgl_usgn32          y_start;        // Y start value
    Xgl_usgn32          x_start;        // X start value

    Xgl_sgn32           x_delta;        // either +1 or -1
    Xgli_fixed_z        z_start;        // Z start
    Xgli_fixed_z        z_delta;        // Z increment
    double              w_start;
    double              w_delta;

    /* These colors use Xgli_fixed_xy representation for indexed
       colors. The colors are interpolated in fixed point and LI3
       then truncates to an integer.
     */
    Xgl_color           color_start;
    Xgl_color           color_delta;

    XgliUvSpanInfo3d    uv_info;
    Xgl_usgn32          unused[8];
} Xgli_span_3d;

typedef struct {
    Xgl_usgn32          num_spans;
    Xgli_span_3d        *spans;

    Xgl_usgn32          unused[4];
} Xgli_span_list_3d;

Attributes That the Device Pipeline Needs to Handle The Context attributes used by this function are:

XglContext::getPickEnable()
XglContext::addPickToBuffer
XglContext::getPickId1()
XglContext::getPickId2()
XglContext::getBackgroundColor()
XglContext::getRealPlaneMask()
XglContext::getRenderBuffer()
XglContext::getRop()
XglContext3d::getBlendFreezeZBuffer()
XglContext3d::getHlhsrData()
XglContext3d::getHlhsrMode()
XglContext3d::getZBufferCompMethod()
XglContext3d::getZBufferWriteMask()
XglContext3d::getDepthCueMode() (for texture mapping)

What You Need to Know to Implement 3D li3MultiSpan This function draws a list of spans. A span is a horizontal run of pixels given by a starting X and Y location and the number of pixels to draw in the X direction. The X direction may be either to the left or to the right of the starting location.

The color parameters controls if all of the spans are drawn in the same color (then this parameter is not NULL) or if the color field in the span structure specifies the color for each span (then this parameter is NULL). If the color is given per span, then the color is interpolated using the color_start and color_delta fields.

When the color type is indexed and interpolation is being done, the colors in Xgli_span_3d are treated as fixed point numbers (Xgli_fixed_xy in FixedPoint.h). As an example, in Xgli_span_3d, color_start.index should be cast to a Xgli_fixed_xy.

Spans can also be filled with a pattern. The fill_style_info control fields specifies the fill style for the spans and gives the raster pattern to use for patterned spans.

Spans can be rendered with transparency value and a transparency mode (either screen door or blended transparency); the field blend_type in the the control structure manages blending.

In addition, spans can be filled with a texture-mapped pattern. If the do_texturing field in Xgli_span_control_3d is TRUE, spans are rendered with a texture-mapped pattern. The information needed to texture a span is passed from LI-2 in the uv_info field of the Xgli_Span_3d structure. Texture mapping is implemented in RefDpCtx. If you choose not to use RefDpCtx but want to implement texture mapping, you can call the utility XgliUtCalcTexturedColor. See Chapter 10, "Utilities".

XGL uses hyperbolic interpolation to arrive at an intermediate (u,v) in a span. The class XgliUvSpanInfo3d encapsulates the Data Map Texture object (u,v) numerator, denominator, (u,v) deltas, the start MipMap level, and the delta for the span. In addition, it has the lighting coefficients that are used if lighting is applicable.

XgliUtUvSpanInfo3d provides functions to retrieve this information and increment the information as the span is traversed. The interfaces provided by this class are:

void    setNumInfo(Xgl_usgn32 n)

  This function sets the number of of texture coordinates (u,v) and related
  information that needs to be stored in the class. (This corresponds to the
  number of data maps that are active). This function allocates the neccesary
  space for the storage.

Xgl_usgn32getNumInfo() const

This function returns the number of sets of texture coordinate ({u,v}) values.

Xgli_light_and_uv_info* getLightAndUvInfo()

This function returns a structure that contains the {u,v} related fields such as numerator and delta (for hyperbolic interpolation), the start mipmap level and delta for the span as well as lighting coefficients and delta for the span. The function is called when various fields need to be filled in.

void getPixelDataInfo(Xgli_pixel_data_info*) const

This function takes the current value of texture coordinates ({u,v}) and light coefficients at a pixel location, does a perspective divide, and returns the values. The value returned is the texture coordinate ({u,v}) that is used to look up in the texture map, and the lighting coefficients used to light the pixel. Note that since there can be multiple data maps( and several textures within a data map) that are active. The structure has an array of {u,v} corresponding to the number of data map objects that are active.

void incrementLightAndUvInfo()

This function increments the pixel information as it proceeds along the span. Typically, for each pixel the caller uses getPixelDataInfo() to get the {u,v} and lighting values for that pixel and then increments the pixel information to reflect the correct values for the next pixel in the span.