About the LI-2 Layer

The LI-2 layer lies below the transformation and clipping of the LI-1 layer. The LI-2 layer was designed to provide support for hardware that is not able to perform transformations and clipping but can accelerate device coordinate primitives. An LI-2 graphics handler uses the XGL software pipeline for transformations, clipping, and lighting. The software pipeline returns a transformed, clipped, and lit primitive in device coordinates to the LI-2 device pipeline.

The device pipeline LI-2 routines implement scan conversion and pixel rendering, thus providing partial acceleration for primitives. This layer provides a porting layer that is simpler to port to than LI-1 but renders faster than the LI-3 dot/span layer.

Figure 9-1 shows an overview of the pipeline architecture for the LI-2 layer.

Figure 9-1

Table 9-1 lists the set of LI-2 interfaces for the device pipeline. All of the LI-2 interfaces are also implemented by the software pipeline

Table 9-1

Function	2D	3D	Description	Swp Dp
li2GeneralPolygon()	v	v	Scan converts polygons to span lines.	v Optional
li2MultiDot()	v	v	Sends pixels specified by points to the hardware.	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, sends vectors to the hardware. 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	Breaks a triangle into individual triangles and scan converts the triangles.	v Optional
li2TriangleStrip()	-	v	Breaks a triangle list into individual triangles and scan converts the triangles.	v Optional

Deciding Which LI-2 Interfaces to Implement

The XGL architecture provides flexibility in choosing which LI-2 primitives to implement. You can implement all the LI-2 functions, or you can implement some functions at the LI-2 level and some at the LI-3 level. For example, an LI-2 pipeline might implement lines at LI-2 but implement fill primitives like triangles at the LI-3 pixel level.

At rendering time, the flow of control goes to the device pipeline at the LI-2 level if the device pipeline has implemented the LI-2 function. The pipeline determines from the setting of API attributes whether it can or cannot render the primitive at that level. If it can render the primitive, it will generally perform all the operations necessary for rendering from the LI-2 level to the hardware. If it cannot render the primitive, it can call the software pipeline to complete LI-2 operations.

Your decision about which primitives to implement depends primarily on the capabilities of your hardware and the needs of your customers. In addition, if you call the software pipeline to provide some functionality, your decision about which primitives to implement may be influenced by the functions that the software pipeline calls when it returns from LI-1 processing.

LI-1 Software Pipeline and LI-2 Device Pipeline

When the software pipeline completes processing at LI-1, it forwards the processed data through the opsVec array in the XglDpCtx object. For example, when the software pipeline li1MultiPolyline function finishes processing the geometry in a multipolyline call, it calls the LI-2 multipolyline function that is set in the opsVec array. If the device pipeline has implemented polyline functionality at the LI-2 layer, the opsVec array will point to the device pipeline renderer, and the device pipeline will assume control at this point; otherwise, the opsVec setting will forward the rendering call back to the software pipeline.

Figure 9-2 on page 223 illustrates a device pipeline that implements polylines at the LI-2 level. Since the device pipeline hasn't changed the default software pipeline entry at the LI-1 layer, the opsVec entry points to the software pipeline for LI-1 line processing. The device pipeline has set the LI-2 multipolyline opsVec entry to point to its LI-2 line renderer. When the software pipeline returns, the device pipeline's LI-2 multipolyline function is called, and the device pipeline renders the lines. For information on setting entries in the opsVec array, see page 44.

Figure 9-2

A graphics handler can choose not to implement all the LI-2 functions and use the software pipeline for some LI-2 functionality. However, some LI-2 software pipeline routines call other LI-2 functions to continue processing. For example, the software pipeline li2MultiEllipse() function calls the opsVec entry for li2GeneralPolygon() function to scan convert ellipses with rotation angles. If your graphics handler implements the li2GeneralPolygon() routine, rendering of rotated ellipses on your device can be partially accelerated, even though your graphics handler uses the software pipeline for some LI-2 processing.

To determine which functions the software pipeline calls, see Table 9-2 on page 224 or the description for each primitive. Table 9-2 shows which LI-2 and LI-3 functions are called by the LI-2 software pipeline functions. If you decide to implement one of the functions listed in the left column, you may also want to implement the marked functions listed to the right. In this table, "D"

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

Table 9-2

Software Pipeline li2GeneralPolygon li2MultiEllipse li2MultiEllipticalArc li2MultiDot li2MultiPolyline - 2D li2MultiPolyline - 3D li2MultiRect li2MultiSimplePolygon - 2D li2MultiSimplePolygon - 3D li2TriangleList li2TriangleStrip

Device Pipeline

ector

li2MultiSimplepolygon li3Multispan li3MultDot li3V

Window Locking Around Hardware Access

All LI-2 pipelines must lock and unlock the window around any operation that could alter the screen display. This prevents the window clip lists from changing during rendering. For information on window lock and unlock macros, see Chapter 7.

Picking at LI-2

If Z-buffering and picking are enabled, and the device pipeline calls the software pipeline for rendering at LI-1, the software pipeline determines whether the primitive is within the pick aperture. The software pipeline returns the portion of the original primitive that lay within the pick aperture to the device pipeline for LI-2 rendering. At LI-2, the device pipeline tests whether any of the pixels within the pick aperture are visible based on the Z-comparison method, and if so, it records a pick event.

Calling the Software Pipeline for Texture Mapping at LI-2

If your device pipeline has not implemented texture mapping at the LI-2 level, you can call the software pipeline to continue the processing for texturing. At LI-2, face distinguishing has already taken place, so you can optimize your call to the software pipeline by determining 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

The LI-1 software pipeline 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.

LI-2 Attributes

The LI-1 software pipeline sets the Context attributes that must be taken into account by the LI-2 device pipeline routine. For example, when rendering a hollow polygon using the polyline renderer, the software pipeline sets the line color attribute in the Context to reflect the polygon color. For information on specific attributes for each LI-2 function, see the section in this chapter on that function. For a list of attributes that must be accounted for by all LI-2 surface primitives, see Table 9-3 on page 226.

Note that Context.h and Context3d.h provide interfaces for the pipeline to get more than one 3D surface attribute in a single structure. These functions can facilitate device pipeline manipulation of 3D surface attributes. For more information, see "Context Interfaces" on page 101 and "Context 3D Interfaces" on page 103. 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.

Table 9-3

Dimension	LI-2 Surface Attributes
2D and 3D	getSurfAaBlendEq() getSurfAaFilterWidth() getSurfAaFilterShape() getSurfFrontColor() getSurfFrontColorSelector() getSurfFrontFpat() getSurfFrontFpatPosition() getSurfFrontFillStyle() getEdgeAltColor() getEdgeCap() getEdgeColor() getEdgeJoin() getEdgeMiterLimit() getEdgePattern() getEdgeStyle() getEdgeWidthScaleFactor() getSurfEdgeFlag() getSurfInteriorRule() getPlaneMask() getRop() getThreshold()
3D only	getSurfBackColor() getSurfBackColorSelector() getSurfBackFillStyle() getSurfBackFpat() getSurfBackFpatPosition() getHlhsrMode() getSurfDcOffset() getDepthCueMode() getDepthCueInterp()

What You Should Know About the Software Pipeline

This section contains information on the software pipeline that you may need if your device pipeline uses the software pipeline for LI-1 processing.

LI-1 Operations in the Software Pipeline

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.

Lighting and Surface Color in the Software Pipeline

Surface color selection is handled as follows in software pipeline LI-1 functions:

• If lighting is on, color selection and lighting are handled in the LI-1 software pipeline. If lighting is off, color selection is done at LI-2, and the LI-2 device pipeline is responsible for determining color values.
• At LI-1, if depth cueing is on and depth cue interpolation is on, the software pipeline does depth cueing at each vertex and stores the depth cued color 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 the software pipeline does depth cueing at each vertex and stores the output color 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.

If depth cueing is off, color selection is performed at LI-2 and is the responsibility of the device pipeline.

---

Note - Software pipeline LI-1 3D functions perform lighting and depth cueing before calling LI-2 functions. However, if depth cueing is enabled, device pipeline LI-2 functions must handle DC offset and interpolate colors.

---

• If texture mapping is on, no color selection is done at LI-1, and it is the LI-2 device pipeline's responsibility to handle color selection.

Texture Mapping in the Software Pipeline

If texture mapping is enabled (the application must have defined at least one Texture Map object), the software pipeline processing of surface primitives changes. 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.

Point Type Input to LI-2 Device Pipelines

In most cases, the LI-1 software pipeline passes application point data to the LI-2 device pipelines unchanged. However, the LI-1 software pipeline can change the point type to add or remove information. You should be aware that your LI-2 device pipeline may not get point data in the exact form sent in by the application at LI-1, and your device pipeline should handle these cases.

Point type changes occur in the LI-1 software pipeline as follows:

• The point type input to LI-2 3D surface primitives has flag data added if the primitive is clipped. Thus, a point type of Xgl_pt_f3d becomes Xgl_pt_flag_f3d.

---

Note - 2D and 3D polygons (the API primitive xgl_polygon()) always have flag data added; thus, the point type input into li2GeneralPolygon will never be Xgl_pt_f{2,3}d but will be Xgl_pt_flag_f{2,3}d.

---

• If per-vertex lighting is enabled, color data is added to the point type passed to LI-2 if it wasn't already present. If the lighting is per-facet, facet color data is added to the facet type.
• Homogeneous data is added to the point types of surface primitives if the primitive is clipped. Thus, a point type of Xgl_pt_f3d becomes Xgl_pt_f3h.

---

Note - Homogeneous data is always added to the point type of 3D polygons in case texture mapping requires the w value for per-pixel perspective correction.

---

• If an application provides vertex normals with a 3D point type, and then lighting is enabled, the normals are removed from the point type by the LI-1 software pipeline.

Data Input to the LI-2 Layer

At the LI-2 layer, application data has been partially processed by the software pipeline. The software pipeline passes LI-2 renderers 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 software pipeline stores data under the control of a C++ class called XglPrimData. This class contains pointers to the original application data (essentially the arguments to the primitive) and a framework that is used by the software pipeline. However, the XGL point types do not contain all the information that a device pipeline might need to efficiently display the data. To solve this problem, the XGL DDK interface includes a number of internal data types that the pipeline can reference to get application data. These internal data types contain both the application geometry and some useful information about the geometry.

Although XglPrimData is the input to many of the rendering functions at LI-2, it is not used for rendering conics (circles, arcs, ellipses, or elliptical arcs) or rectangles. Conic data is stored in either the XglConicData2d object or the XglConicData3d object. Similarly, rectangle data is stored in the XglRectData2d object or the XglRectData3d object. These objects are similar to XglPrimData.

How Data Is Stored by the Software Pipeline

Within the XglPrimData object, point information relevant to the device pipeline is stored in an object called XglLevel. Level objects are used extensively by the software pipeline and are the device pipeline LI-2 layer interface to the processed geometry.

XglLevel contains point list information that is created when the data moves down through the software pipeline. A level is a memory area for storing primitive data. Each time the data is modified, as it would be after transformations, clipping, lighting, depth cueing, shading, or texture mapping, a new level is started. This design allows the software pipeline to move data around as it processes data and provides the software pipeline with access to previous stages of the pipeline. It also allows a device pipeline to refer back to an earlier version of the data.

Figure 9-3 illustrates the XglLevel objects that would be created for a hypothetical software pipeline that transformed, clipped, and lit the geometry data. Level 0 contains the original API data and is created when the LI-1 software pipeline is first called.

Figure 9-3

The XglPrimData class maintains an array of XglLevel objects. This is effectively a stack, with each object representing the data in various stages of processing. The lowest XglLevel object, level 0, contains the API data, while the top object contains the processed geometry. In an LI-2 renderer the data to be used is read out from this top object. Figure 9-4 illustrates the flow of data from the application to an LI-2 device pipeline.

Figure 9-4

Data Storage in the XglLevel Object

The XglLevel class stores data in a noncontiguous format. This is done by specifying a base-pointer and step-size pair for each field in the point that is being processed. The base pointer points to the field for the first point in the list. The step size indicates how many bytes to increment the pointer to get to the field in the second point (and so on).

Initially, the base pointers all point to the beginning of the API data, and the step sizes are all the same, in other words, equal to the point size. Graphically, this would look something like Figure 9-5, assuming a point type that contained geometry, colors, and normals.

Figure 9-5

Thus, to get to the color field of the second point, the color base pointer would be incremented by the point size.

During normal operation of a software LI-1 routine, one or more of these pointers is replaced by a pointer to a different area of memory, local to XGL. The step sizes are adjusted accordingly. For instance, starting from the sets of pointers and step sizes pictured above, the geometry values may be transformed, and the results stored to a different area of memory. This would change the picture to something like Figure 9-6 on page 233.

Figure 9-6

In Figure 9-6, the geometry base pointer no longer points to the API data but to an array of points local to the pipeline. Since the transformation did not affect the colors or the normals, their pointers still point to the API data. The new geometry step size is equal to the size of [x,y,z] since the array contains no other information. This technique allows the software pipeline to process data efficiently, since only that data that is actually modified is copied. Unmodified data is left in its original form in the user's space.

In order to hold both the separate pointers and step sizes, an internal point list structure, Xgli_point_list, is used. This structure contains the data outlined above, in addition to some flags that control rendering, such as a close flag for polylines that joins the first and last vertices, and an indication of whether a 3D surface is front facing or back facing. See XglPrimData.h for the structures that make up XglLevel.

Pipeline Interfaces to XglPrimData and XglLevel Data

Table 9-4 lists XglPrimData interfaces that the device pipeline can use to get point data and to get information about point data at LI-2.

Table 9-4

Function	Description
getLevelData()	Returns the data for a specified level.
getCurrentLevel() getCurrentLevelData()	Return the data for the current level.
getProcessFlags()	Returns a value indicating which software pipeline processing steps (such as clipping or lighting) need to be done.

Table 9-5 lists useful interfaces from the XglLevel subclass of XglPrimData.

Table 9-5

Function	Description
getPointLists()	Returns the API data point lists.
getFacetList()	Returns the API data facet lists.
getNumPointLists()	Returns the number of point lists.
getRenderFlags()	Returns API rendering flags.
getFaceAttrs()	Returns the front facing and back facing attributes.

Example of Extracting Data from XglLevel

Since the software pipeline makes use of the XglLevel structures in its LI-1 processing, any device pipeline LI-2 function must extract data in XglLevel format from these structures. Level format means that all the point and facet lists have been broken down into base-pointer/step-size format, as shown in Figure 9-5 on page 232 and Figure 9-6 on page 233.

The methods for extracting data in level format use the XglPrimData method getCurrentLevelData(). This method provides offset and step-size information that is available from the structure directly and does not have to be computed.

The following code fragment is an example of how a device pipeline might implement an LI-2 polyline renderer.

XglDpCtx2dExample::li2MultiPolyline(XglPrimData *pd) { // // First get the XglLevel structure.This method gets the // current level, that is the one that contains the most // up-to-date data. // level = pd->getCurrentLevelData(); // // Get the number of point lists, and the point lists // themselves. // num_pl = level->getNumPointLists(); pl = level->getPointLists(); // // See if we have to close the polylines. If this routine is // being called to draw a hollow polygon, for instance, then // the first and last points need to be connected. // close_flag = pd->getProcessFlags() & XGLI_CLOSE_FLAG; // // Loop on the point lists. // for (i = 0; i < num_pl; i++) { pt = (Xgl_pt_i2d*) pl->geom_ptr.base_ptr; // // Loop on the points in each point list. // for (j = 0; j < pl->current_num_points; j++) { send_to_hardware(pt->x); send_to_hardware(pt->y); XGLI_INCR(pt, Xgl_pt_i2d*, pl->geom_ptr.step_size); } // // Optionally close the polyline - send down the 1st pt // again. //

if (close_flag) { pt = (Xgl_pt_i2d*) pl->geom_ptr.base_ptr; send_to_hardware(pt->x); send_to_hardware(pt->y); } } }

---

Note - The lighting_coeffA_ptr, lighting_coeffB_ptr, and use_lighting_coeffs fields in the Xgli_point_list and Xgli_facet_list structures used by XglLevel store the lighting coefficients on a per-vertex and per-facet basis when lighting is on and texturing is on. See Chapter 8 and Chapter 10 for information on texture mapping.

---

Conic and Rectangle Data

The XglConicData{2,3}d and XglRectData{2,3}d data structures are used to hold conic and rectangle data at the LI-2 layer. These data structures are based on XglPrimData in that they organize the data into levels and use a base-pointer/step-size technique. However, the objects used for the level data are specific to the classes.

The level data in XglConicData is contained in an array of objects of type XglConicList{2,3}d. Each XglConicList object is a level for a stage of the software pipeline for the conic. The object contains pointers to a list of conic data for each of the items describing a circle, arc, or other conic geometry, as well as information on the number of conics. The API data is referenced at level 0.

Similarly, the level data in XglRectData is contained in an array of objects of type XglRectList{2,3}d. XglRectList has pointers to a list of rectangles specified in Xgl_rect_list as a base and offset. The base points to the first rectangle in the list and the offset specifies the step size to access the next rectangle. The XglRectList object also contains a value for the number of rectangles.

Pipeline Interfaces to XglConicData and XglRectData

The following functions are provided by the XglConicData2d, XglConicData3d, XglRectData2d, and XglRectData3d classes. These interfaces enable the device pipeline to retrieve conic and rectangle level data for the current level or for a different level. Table 9-6 lists interfaces provided by XglConicData.

Table 9-6

Function	Description
getCurrentLevel()	Gets the current level number. The API data is level 0.
getLevelData()	Gets data for a specified level.
getCurrentLevelData()	Gets data for the current level.

Table 9-7 lists interfaces provided by XglConicList2d.

Table 9-7

Function	Description
getNumConics() setNumConics()	Get or set the number of conics in this level.
getConicType()	Gets the conic type, which is one of XGLI_CONIC_CIRCLE or XGLI_CONIC_ARC.
getConicDataType()	Gets the conic data type.
getBbox()	Gets the bounding box enclosing all conics of this level.
getCenterPtr()	Gets the pointer to the list of conic centers.
getFlagPtr()	Gets the pointer to the list of flags.
getRadiusPtr()	Gets the pointer to the list of radii.
getMajorAxisPtr()	Gets the pointer to the list of major axes of ellipses or elliptical arcs.
getMinorAxisPtr()	Gets the pointer to the list of minor axes of ellipses or elliptical arcs.
getRotAnglePtr()	Gets the pointer to the list of rotation angles of ellipses or elliptical arcs.
getStartAnglePtr()	Gets the pointer to the list of start angles of arcs.

Table 9-7 (Continued)

Function	Description
getStopAnglePtr()	Get the pointer to the list of stop angles of arcs.
getStartPointPtr()	Get the pointer to the list of start points of arcs.
getStopPointPtr()	Get the pointer to the list of stop points of arcs.

Table 9-8 lists interfaces provided by the XglRectData classes.

Table 9-8

Function	Description
getNumRects() setNumRects()	Get or set the number of rectangles in this level.

Example of Extracting Data from XglRectData

The following example shows how to extract data from an XglRectData2d object.

void XglDpCtx2dExample::li2MultiRect(XglRectData2d* rd) { XglRectList2d* rlist; Xgl_usgn32 num_rects; // number of rectangles Xgl_rect_i2d* rectangle; // Extract the list of rectangles from the data structure. // rlist = rd->getCurrentLevelData(); num_rects = rlist->getNumRects(); rectangle = (Xgl_rect_i2d *)(rlist ->cornerPoints.base_ptr); // Loop through the list of rectangles. // for (long i = 0; i < num_rects; i++, rectangle++) { send_to_hardware(rectangle->corner_min.x); send_to_hardware(rectangle->corner_min.y); send_to_hardware(rectangle->corner_max.x); send_to_hardware(rectangle->corner_max.y); } }

Example of Extracting Data from XglConicData

This example shows how to access data from an XglConicData2d object.

void XglDpCtx2dExample::li2MultiEllipse(XglConicData2d* cd) { XglConicList2d* conic_list; Xgl_usgn32 num_ells; // number of ellipses Xgl_pt_flag_f2d* center; Xgl_usgn32* major_axis; Xgl_usgn32*minor_axis; float* rot_angle; Xgl_usgn32 center_step, major_axis_step, minor_axis_step, rot_angle_step; Xgli_pointer*ptr; // Get conic data. conic_list = cd->getCurrentLevelData(); num_ells = conic_list->getNumConics(); // Get rotation angle and step increment size. ptr = conic_list->getRotAnglePtr(); rot_angle = (float *)ptr->base_ptr; rot_angle_step = ptr->step_size; // // This device pipeline cannot handle rotated ellipses. // Punt to software pipeline if rotation angle is not 0 or // pi/2. // if ( ! (XGLI_EQUAL_ZERO(*rot_angle, XGLI_ANGULAR_TOLERANCE) || XGLI_EQUAL_ZERO((*rot_angle) - M_PI_2, XGLI_ANGULAR_TOLERANCE)) ) { swp->li2MultiEllipse(cd); return; } // Get center and step increment size. ptr = conic_list->getCenterPtr(); center = (Xgl_pt_flag_f2d *)ptr->base_ptr; center_step = ptr->step_size; // Get major axis and step increment size.

ptr = conic_list->getMajorAxisPtr(); major_axis = (Xgl_usgn32 *)ptr->base_ptr; major_axis_step = ptr->step_size; // Get minor axis and step increment size. ptr = conic_list->getMinorAxisPtr(); minor_axis = (Xgl_usgn32 *)ptr->base_ptr; minor_axis_step = ptr->step_size; // // Loop through the list of ellipses. // for (long i = 0; i < num_ells; i++) { if (XGLI_EQUAL_ZERO(*rot_angle, XGLI_ANGULAR_TOLERANCE)) { send_to_hardware_x(center->x - (*major_axis)); send_to_hardware_y(center->y - (*minor_axis)); send_to_hardware_w(2 * (*major_axis)); send_to_hardware_h(2 * (*minor_axis)); else { send_to_hardware_x(center->x - (*minor_axis)); send_to_hardware_y(center->y - (*major_axis)); send_to_hardware_w(2 * (*minor_axis)); send_to_hardware_h(2 * (*major_axis)); } XGLI_INCR(center, Xgl_pt_flag_f2d*, center_step); XGLI_INCR(major_axis, Xgl_usgn32*, major_axis_step); XGLI_INCR(minor_axis, Xgl_usgn32*, major_axis_step); XGLI_INCR(rot_angle, float*, rot_angle_step); } }

LI-2 Interfaces

li2GeneralPolygon() - 2D/3D

The li2GeneralPolygon() 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 handle edges, interior styles, and fill rules (even-odd only). For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

Syntax

[2D and 3D]
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

See Table 9-3 on page 226 for a list of attributes that this function must handle.

Software Pipeline Return Calls

The software pipeline li2GeneralPolygon() function 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 device pipeline li3MultiSpan()function.

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

li2MultiDot() - 2D/3D

The li2MultiDot() routine enables the device pipeline to accelerate dot markers. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

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

A device pipeline must handle the following attributes.

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

Software Pipeline Return Calls

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

The li2MultiEllipse() function scan converts ellipses to span lines. Although there is no ellipse primitive in the XGL 2D API, the XGL GPI includes the li2MultiEllipse() function to support hardware that can accelerate a regular circle or a circle with uneven scale in DC. This function is expected to handle edges and interior fill styles. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

Syntax

void XglDpCtx2d::li2MultiEllipse(
    XglConicData2d      *ellipses);

Input Parameters

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-3 on page 226 for a list of attributes that this function must handle.

Software Pipeline Return Calls

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

For ellipses with rotation angles, the software pipeline tessellates each ellipse to a list of points, and calls li2GeneralPolygon() to draw the geometry.

li2MultiEllipticalArc() - 2D

The li2MultiEllipticalArc() function scan converts elliptical arcs to span lines. Although there is no ellipse in the XGL 2D API, the XGL GPI provides the li2MultiEllipticalArc() function 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 edges, interior fill styles, and arc fill styles. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

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-3 on page 226.

XglContext::getArcFillStyle()

Software Pipeline Return Calls

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 software pipeline calls the device pipeline LI-3 function li3Vector() 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

The li2MultiPolyline() routine is used to render lines and other stroke primitives, such as hollow surfaces and edges. Since this routine is called by the 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 (most likely the software pipeline) to set the stroke group appropriately for the original primitive; it is the responsibility of the device pipeline LI-2 multipolyline function to get the polyline attributes from the current stroke group. See page 82 for information on the stroke group.

This function is expected to handle wide lines and wide patterned lines as well as thin lines and thin patterned lines. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

Syntax

void XglDpCtx::li2MultiPolyline(
    XglPrimData*        pd);

Input Parameters

pd.......Pointer to an XglPrimData object containing point lists describing multiple, disjoint polylines. The XglPrimData object inludes a flag that specifies whether each polyline is closed.

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()

When the multipolyline 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 87.

In addition, 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. For information on li3Vector(), see page 196 and page 198.

Software Pipeline Return Calls

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 pipeline 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 line overlap. The list of spans is drawn by the li3MultiSpan() function.

li2MultiPolyline() - 3D

The li2MultiPolyline() routine is used to render lines and other stroke primitives, such as hollow surfaces and edges. Since this routine is called by the 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 (most often the software pipeline) to set the stroke group appropriately for the original primitive; it is the responsibility of the device pipeline LI-2 function to get the stroke attributes from the current stroke group. See page 82 for information on the stroke group.

This function is expected to handle wide lines and wide patterned lines as well as thin lines and thin patterned lines. Because the software pipeline calls li2TriangleList() to render wide lines, device pipelines that call the software pipeline to render wide lines may also want to implement li2TriangleList() for triangle stars if the device can accelerate triangles. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

Syntax

void XglDpCtx3d::li2MultiPolyline(
    XglPrimData         *pd);

Input Parameters

pd.......Pointer to an XglPrimData object containing point lists describing multiple, disjoint polylines. The XglPrimData object inludes a flag that specifies whether each polyline is closed

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()

Software Pipeline Return Calls

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

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

li2MultiRect() - 2D

The li2MultiRect() function scan converts rectangles to span lines. It enables hardware to accelerate rectangles and provides an opportunity to reduce the amount of copied data, since for multirectangles only two corner points need to be copied rather than four corner points for polygon routines.

The function is expected to handle edges and interior fill styles.

---

Note - The li2MultiRect() function is not currently called by any LI-1 software pipeline function. The software pipeline li1MultiRectangle() functions call LI-2 polygon routines.

---

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-3 on page 226 for a list of attributes that this function must handle.

Software Pipeline Return Calls

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, the software pipeline calls li2MultiPolyline() with the stroke group set to hollow or edge accordingly.

li2MultiSimplePolygon() - 2D

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

---

Note - This function is not currently called by any LI-1 software pipeline function.

---

Syntax

void XglDpCtx2d::li2MultiSimplePolygon(
    XglPrimData*        pd);

Input Parameters

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

Attributes

See Table 9-3 on page 226 for a list of attributes that this function must handle.

Software Pipeline Return Calls

To render filled surfaces, the software pipeline li2MultiSimplePolygon() 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().

li2MultiSimplePolygon() - 3D

The li2MultiSimplePolygon() function scan converts single-facing polygons to span lines and provides support for single-bounded polygons. This function is expected to handle edges and different fill styles. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

Syntax

void XglDpCtx3d::li2MultiSimplePolygon(
    XglPrimData         *pd);

Input Parameters

pd.......Pointer to an XglPrimData object containing a list of single-facing polygons.

Attributes

See Table 9-3 on page 226 for a list of attributes that this function must handle.

Software Pipeline Return Calls

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

The li2TriangleList() function renders lists of single-facing triangles in device coordinates in the form of triangle strips, triangle stars, or unconnected triangles. The triangles in a triangle list are of the same type; in other words, they are either triangle stars, strips, or independent triangles. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

Syntax

void XglDpCtx3d::li2TriangleList(
    XglPrimData         *pd);

Input Parameters

pd.......Pointer to an XglPrimData object containing point lists of single-facing triangle strips, triangle stars, or unconnected triangles based on the value of the triangle list render flags.

Attributes

A device pipeline must handle the following attributes in addition to the surface attributes listed in Table 9-3 on page 226.

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

Software Pipeline Return Calls

To render triangle strips, the software pipeline checks the level data rendering flags and calls li2TriangleStrip(). To render filled surfaces, the software pipeline 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 205 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 li2MultiPolyline() function.

li2TriangleStrip() - 3D

The li2TriangleStrip() function handles single-facing triangle strips. For a list of the LI-1 software pipeline routines that call this device pipeline routine, see Table 10-2 on page 261.

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-3 on page 226.

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

Software Pipeline Return Calls

The software pipeline li2TriangleStrip() function first processes the input point lists into separate triangles. Then, for filled surfaces, the software pipeline 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 205 for information on texture mapping.)

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