About the LI-1 Layer

The LI-1 layer specifies the loadable interfaces that lie just below the XGL API. Functions within the LI-1 layer implement the geometry pipeline for each primitive. 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 rendering operations. LI-1 routines handle all aspects of geometry processing and all rendering.

LI-1 primitives are appropriate for full acceleration on the device. An XGL loadable pipeline developer 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. Figure 10-1 shows an overview of the pipeline architecture.

Figure 10-1

Table 10-1 lists the set of LI-1 interfaces and shows whether the interfaces are implemented by the software pipeline. Functions that require direct pixel access or immediate interaction with the device pipeline are not implemented in software. Functions that are implemented in software are optional for the device pipeline.

Table 10-1

Function	2D	3D	Description	Swp Dp
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
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

Table 10-1 (Continued)

Function	2D	3D	Description	Swp	Dp
li1CopyBuffer()	v	v	Copies a block of pixels from one buffer to another.	-	Required
li1Flush()	v	v	Causes pending processing to complete.	-	Optional
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.	-	Optional
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

Deciding Which LI-1 Interfaces to Implement

The XGL architecture provides you with 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. A typical scenario for a device pipeline is that it will support some combination of attributes and primitives at the LI-1 level, some at the LI-2 level, and some at the LI-3 level.

At rendering time, the flow of control goes to the device pipeline at the LI-1 level if the device pipeline has implemented an LI-1 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-1 level to the hardware. If it cannot render the primitive, it can call the software pipeline to complete LI-1 operations.

The software pipeline includes a set of support routines that 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, such as particular primitives or some combinations of XGL attributes. For information on calling the software pipeline, see "Calling the Software Pipeline" on page 50.

In general, when a device pipeline implements an LI-1 primitive, there is a match between the primitive-attribute combinations and what the accelerator can do. Your decision about which primitives to implement for a particular level 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 LI-1 functionality, your decision about which primitives to implement may be influenced by software pipeline return calls.

Software Pipeline Return Calls

When the software pipeline completes processing at LI-1, it forwards the data it has processed by calling functions through the opsVec array in the XglDpCtx object. For example, if the device pipeline calls the software pipeline multipolyline function at LI-1, when the software pipeline function finishes processing the geometry, 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, it will assume control at this point; otherwise, the opsVec setting will forward the rendering call 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 LI-1 multipolyline function to decompose the string of text into multipolylines. When the software pipeline calls the multipolyline function, the opsVec array pointer for that primitive determines whether the device pipeline or the software pipeline will continue processing the geometry as lines.

Figure 10-2 illustrates a device pipeline that implements polylines but not stroke text. The device pipeline calls the software pipeline to render stroke text; the software pipeline calls back the device pipeline multipolyline function through the opsVec array, and the device pipeline renders the text as polylines.

Figure 10-2

As you prioritize the list of primitives that you want to accelerate, you may start with a few basic primitives, such as lines, markers, triangles, and polygons. Then, for those primitives for which you would like to call the software pipeline, determine what functions the software pipeline calls when it returns from processing. For example, if your customer uses arcs but your hardware does not accelerate arcs, you may decide to use the software pipeline for arc processing at LI-1. Depending on the input data, the software pipeline 3D li1MultiArc() routine will call one of these routines:

li1MultiPolyline(), li1MultiSimplePolygon(),
li2MultiPolyline(), or li2GeneralPolygon(). If your graphics handler

implements these routines, arc rendering on your device can be partially accelerated, even though your graphics handler uses the software pipeline for some arc processing.

To determine which functions the software pipeline calls, see Table 10-2 or refer to the description of each primitive in the interface description sections in this chapter. Table 10-2 shows the mapping of the software pipeline LI-1 functions to the device pipeline LI-1 or LI-2 functions. If you call one of the software pipeline functions listed on the left, you may want to implement some or all of the marked functions listed to the right in your graphics handler. You can think of the functions to the right as being downstream of the software pipeline function that calls them.

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. Note that 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. Note also that surface or fill primitives call LI-1 or LI-2 polylines for fill primitives with edges turned on.

Table 10-2

Software Pipeline li1AnnotationText - 2D/3D li1MultiArc - 2D li1MultiArc - 3D li1MultiCircle - 2D li1MultiCircle - 3D li1MultiEllipticalArc - 3D li1MultiMarker - 2D/3D li1MultiPolyline - 2D/3D li1MultiRectangle - 2D li1MultiRectangle - 3D li1MultiSimplePolygon - 2D li1MultiSimplePolygon - 3D

Device Pipeline

ector

li3MultiSpan li3MultiDot li3V

Table 10-2 (Continued)

Software Pipeline li1NurbsCurve - 2D/3D li1NurbsSurf - 3D li1Polygon - 2D/3D li1QuadrilateralMesh - 3D li1StrokeText - 2D/3D li1TriangleList - 3D li1TriangleStrip - 3D

Device Pipeline

ector

li3MultiSpan li3MultiDot li3V

The primitive li1DisplayGcache() is an especially multiplexed primitive. Depending on the geometry in the Gcache, 2D li1DisplayGcache() calls the following LI-1 primitives:

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

For 3D, li1DisplayGcache() may call any of the above and

• li1NurbsSurf()
• li1TriangleStrip()

---

Note - You can use the RefDpCtx utility object to render LI-3 primitives and the following LI-1 raster primitives: li1NewFrame(), li1SetPixel(), li1SetPixelRow(), li1GetPixel(), li1SetMultiPixel(), li1CopyBuffer(). For information on RefDpCtx, see page 207.

---

Window Locking Around Hardware Access

All LI-1 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.

Handling Invalid Data

The device pipeline is responsible for checking for invalid or degenerate data from the application. For example, the device pipeline li1MultiPolyline() function should check the number of vertices for each polyline. When the number of vertices for a polyline is 0 or 1, the pipeline must handle this case appropriately. Typically, a a pipeline will simply return from the primitive. No geometry need be rendered, but the device pipeline must handle the case gracefully without issuing an error message.

The XGL Reference Manual documents the data that the application must pass in for each primitive and also notes restrictions that the application must follow. For example, the center point of each arc in an arc list must have the flag set properly. Refer to the man page for each primitive for this information.

The device pipeline should check for the cases listed in Table 10-3:

Table 10-3

Primitive	Invalid Data
xgl_multipolyline()	pl[i].num_pts less than 2
xgl_multi_simple_polygon()	pl[i].num_pts less than 3
xgl_polygon()	pl[i].num_pts less than 3
xgl_quadrilateral_mesh()	row_dim less than 2 or col_dim less than 2
xgl_triangle_list()	pl->num_pts less than 3
xgl_triangle_strip()	pl->num_pts less than 3

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

If the device pipeline calls the software pipeline for LI-2 rendering, the software pipeline examines the current attributes and scan converts wide lines. It passes the span lines that lie within the pick aperture back to the device pipeline LI-3 routines. LI-1 and LI-2 have already pruned the geometric data to be inside the pick aperture; LI-3 functions test whether 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 that LI-3 functions are only called to do picking if Z-buffering is enabled.

Hidden Surface Data and Maximum Z Value

The operator xgl_context_new_frame() clears the Z buffer if the attribute XGL_CTX_NEW_FRAME_ACTION specifies XGL_CTX_NEW_FRAME_HLHSR_ACTION and the attribute XGL_3D_CTX_HLHSR_MODE is set to XGL_HLHSR_Z_BUFFER. To clear the Z buffer, the device pipeline needs to determine the Z buffer depth. To determine this, use ctx->getHlhsrData() to get the z_value field of the Xgl_hlhsr_data structure.

At initialization, the Xgl_hlhsr_data field z_value is set to infinity. If a pipeline tries to use this value to clear the Z buffer, a floating point exception occurs. Therefore, all device pipelines should check the z_value returned from getHlhsrData(), and if the z_value is larger than the device maximum Z value, the device maximum Z can be used. To determine the device maximum Z value, use dpDev->getMaxZ() or

device->getMaximumCoordinates(). Note that z_value is definable from the API, so device pipelines should use the value defined by the user if it is less than their device's maximum Z value. For more information, see the man page on XGL_3D_CTX_HLHSR_DATA.

Hints for Rendering Transparent 3D Surfaces at LI-1

The device pipeline can optimize the rendering of transparent surfaces at LI-1 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; for information on these utilities, see Chapter 12, "Utilities".

2. Determine what action to take based on the XGL attribute XGL_3D_CTX_BLEND_DRAW_MODE. Optimized surface rendering uses the device's accelerated pipeline to draw the interior of opaque surfaces and/or edges. Add the following 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){ // Do this by setting edges to off and // 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) { // Do this by setting the interior to // empty and later restoring the fill style // set 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 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. Use an algorithm similar to that shown "Calling the Software Pipeline for Texture Mapping at LI-1."

Calling the Software Pipeline for Texture Mapping at LI-1

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.

At the LI-1 level, 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.

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, check for these attributes:

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

Data Input to the LI-1 Layer

A thin layer of device-independent XGL code passes the application's primitive data unchanged to the LI-1 device pipeline. This section provides several examples of ways to handle application data.

Accessing Application Data

The example below shows how a device pipeline might get 2D multipolyline data from the application and draw the multipolyline.

void XglDpCtx2dSample::li1MultiPolyline( Xgl_bbox* bounding box, Xgl_usgn32 num_pt_lists, Xgl_pt_list *pl); { // NOTE: This example assumes a point type of Xgl_pt_f2d // Xgl_pt_f2d *pt; int num_pts; // Loop through the point lists for ( ; num_pt_lists>0 ; num_pt_lists--, pl++) { // Check for at least 2 vertices per point list if ((num_pts = pl->num_pts) < 2) continue; // Send all vertices to hardware for ( pt=pl->pts.f2d ; num_pts>0 ; num_pts--, pt++ ) { send_xcoord_to_hardware(pt->x); send_ycoord_to_hardware(pt->y); } } }

The next example shows how to access facet data for 3D surfaces. This example assumes that xgl_multi_simple_polygon() has been called with facet colors and that lighting is enabled. This requires that the device pipeline send down a color for each facet, as well as a normal for each vertex.

void XglDpCtx3dSample::li1MultiSimplePolygon( Xgl_facet_flags flags, Xgl_facet_list *facets, Xgl_bbox *bbox, Xg_usgn32 num_pt_lists, Xgl_pt_list pl); { // NOTE: This example assumes a point type of // Xgl_pt_normal_f3d and a facet type of Xgl_color_facet int num_pts; Xgl_color *fc=facets->facet.color_facets; // Loop through all the point lists for ( ; num_pt_lists>0 ; num_pt_lists--, pl++ , fc++ ) { // Check for at least 3 vertices per point list if ((num_pts = pl->num_pts) < 3) continue; // Set the color for the next facet send_rcolor_to_hardware(fc->color.rgb.r); send_gcolor_to_hardware(fc->color.rgb.g); send_bcolor_to_hardware(fc->color.rgb.b); // Send all vertices and normals to hardware for ( pt=pl->pts.normal_f3d ; num_pts>0 ; num_pts--, pt++ ) { send_xnorm_to_hardware(pt->normal.x); send_ynorm_to_hardware(pt->normal.y); send_znorm_to_hardware(pt->normal.z); send_xcoord_to_hardware(pt->x); send_ycoord_to_hardware(pt->y); send_zcoord_to_hardware(pt->z); } } }

Data Access for DMA Devices

The following example shows how a device that uses direct memory access (DMA) might access data. Devices that use DMA to transfer data require only a starting point from which to copy the data and the size of the data block (together, perhaps, with some header block that describes the type of data).

The geometric information pointed to by the Xgl_pt_list structure is guaranteed to always be contiguous. This is true even if a device pipeline is called by the software pipeline. Thus, this interface is appropriate for devices that use DMA to communicate data to their hardware or copy it across from the host as do the two previous examples.

void XglDpCtx2dDmaExample::li1MultiPolyline( Xgl_bbox* bbox, Xgl_usgn32 num_pt_lists, Xgl_pt_list* pl); { // NOTE: This example assumes a point type of Xgl_pt_f2d // Loop through the point lists. for ( ; num_pt_lists>0 ; num_pt_lists--, pl++) { // // Check for at least 2 vertices per point list // if (pl->num_pts < 2) continue; // Send all vertices to hardware // wait_for_outstanding_dma_to_finish(); send_dma_ptlist_to_hardware(pl->pts.f2d, pl->num_pts*sizeof(Xgl_pt_f2d)); } }

Point Lists with Data Mapping Values

Devices that use DMA to transfer data to the hardware may need information on point size. The size of a point is the size of its data type. For example, the API point type Xgl_pt_color_normal_f3d has geometry, color, and normal information and is defined as:

struct Xgl_pt_color_normal_f3d {
   float            x, y, z;
   Xgl_color        color;
   Xgl_pt_f3d       normal;
};

The point might look like this:

The point size is the size of the entire point, except when data-mapping values are present. When data-mapping values are present in the point list, the point size is equal to the sum of the sizes of all of the fields as mentioned above, but only one of the data values is accounted for. For instance, if the point type is Xgl_pt_data_f3d, and there are three data values per point, then the point size is 16 (x,y,z = 12 bytes, plus 4 bytes for the first data value). To calculate the correct point size the following equation must be used:

true_point_size = point_size + (num_data_values - 1)*sizeof(float)

The number of data values is recorded in a field of Xgl_pt_list. The reason this extra calculation is necessary is that some primitives (like multisimple polygon) take an array of point lists as an argument. The number of data values per vertex in each list can be different; thus, the point size can be different for each list.

---

Note - Be sure to calculate the correct point type size for LI-1 markers and polylines if the point type contains data even though the data information is not used.

---

API Primitive Calls Mapped to LI-1 Functions

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

Table 10-4

2D Primitives	LI-1 Functions
xgl_annotation_text()	li1AnnotationText()
xgl_context_display_gcache()	li1DisplayGcache()
xgl_multiarc()	li1MultiArc()
xgl_multicircle()	li1MultiCircle()
xgl_multimarker()	li1MultiMarker()
xgl_multipolyline()	li1MultiPolyline()
xgl_multirectangle()	li1MultiRectangle()
xgl_multi_simple_polygon()	li1MultiSimplePolygon()
xgl_nurbs_curve()	li1NurbsCurve()
xgl_polygon()	li1Polygon()
xgl_stroke_text()	li1StrokeText()

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

Table 10-5

3D Primitives	LI-1 Functions
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()

Table 10-5 (Continued)

3D Primitives	LI-1 Functions
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 10-6 shows the mapping of the API raster and pixel operators to the LI-1 functions.

Table 10-6

XGL Utility Functions	LI-1 Functions
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()

LI-1 Interfaces

li1AnnotationText() - 2D/3D

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. The device pipeline must account for some or all of the attributes listed in the man page.

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

Software Pipeline Return Calls

The software pipeline li1AnnotationText() translates the input string into points in a multipolyline point list and calls the opsVec[] array entry for li1MultiPolyline().

li1DisplayGcache() - 2D/3D

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. When xgl_display_gcache() is called, the device pipeline can use the software pipeline's li1DisplayGcache() function to access the data for the polylines and then call the li1MultiPolyline() function (which the device pipeline may or may not be support). 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:

• 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 developer wants to support will be using Gcaches extensively, it may be worth the effort to implement li1DisplayGcache().
• 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 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. For more information, see the xgl_context_display_gcache() man page.
display	Boolean value that determines whether the Gcache is rendered. See the xgl_context_display_gcache() man page for more information.

What You Need to Know to Implement li1DisplayGcache()

A device pipeline implementation of li1DisplayGcache() must 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_PGON                          Polygons
XGL_GCACHE_PRIM_MSPG                          Multisimple polygons
XGL_GCACHE_PRIM_NURBS_CURVE                   NURBS curves
XGL_GCACHE_PRIM_NURBS_SURF                    NURBS surfaces
XGL_GCACHE_PRIM_MELLA                         Multi elliptical arcs
XGL_GCACHE_PRIM_TEXT                          Stroke text
XGL_GCACHE_PRIM_TLIST                         Triangle lists
XGL_GCACHE_PRIM_TSTRIP                        Triangle strips

The li1DisplayGcache() function does the following: First, it processes the arguments test and display appropriately. Second, it calls the Gcache object getOrigPrimType() function, and, depending on the original primitive type, li1DisplayGcache() 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. A device pipeline implementation of li1DisplayGcache() must handle the attributes for each primitive that may be called to render the geometry in the Gcache.

The following excerpt from the software pipeline 3D li1DisplayGcache() function illustrates the sequence of events in rendering for two of the Gcache primitive types. See Appendix D on page 435 for the complete software pipeline li1DisplayGcache() routine.

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); } ... 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_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; ... }

XglGcache Functions Relevant to the Pipeline

The XglGcache.h functions relevant to the pipeline are listed in Table 10-7.

Table 10-7

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.

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 can; 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 device-dependent part of a Gcache. The validation of a Gcache is still done by 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 cause the DD translation to be removed from the DI Gcache:

• The device is destroyed (where device is a DpCtx, DpDev, DpMgr, or DpLib).
• The device decides the translation is no longer valid (that is, out of resource, attributes changed, etc).
• The DI Gcache is destroyed.
• 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 that is unique within the XGL system; using the address of a DpCtx, DpDev, DpMgr, or DpLib object is suggested. 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 The functions listed in Table 10-8 allow a device to manage a DD translation.

Table 10-8

Function	Description
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. 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, you should write code to anticipate the case in which a DD translation is not accepted. Currently, a Gcache can store only one DD translation. If more than one DD translation is added, the second translation is not 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 pipeline should not build a new translation or call addDdTranslation().

Table 10-8

Function	Description
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 derive this class for their own use and then add specific data for the DD Gcache.

Thus, to create a DD translation object, the pipeline derives 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.

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 XglDpMgr 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 DD 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 // do device-dependent operations to release resources // and clean up data structures delete this; }

li1MultiArc() - 2D

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 a description of the functionality that the device pipeline needs to handle. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx2d::li1MultiArc(
    Xgl_arc_list *arc_list);

Input Parameters

arc_list.....A pointer to the list of arcs to draw.

Software Pipeline Return Calls

The software pipeline 2D li1MultiArc() function transforms a list of circular arcs in model coordinates into a list of elliptical arcs described in device coordinates. For each elliptical arc that needs to be clipped, or if picking is enabled, the elliptical arc is broken up into a list of:

• Polylines (for open arcs). The polylines are passed to the opsVec entry for li1MultiPolyline().
• Polygons (for filled arcs). The polygons are passed to the opsVec entry for

  li1Polygon().

Elliptical arcs that do not need clipping or do not have picking enabled are passed to li2MultiEllipticalArc().

li1MultiArc() - 3D

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. The device pipeline must handle some or all of the attributes listed in the xgl_multiarc() man page.

Syntax

void XglDpCtx3d::li1MultiArc(
    Xgl_arc_list *arc_list);

Input Parameters

arc_list.....Pointer to the list of arcs to draw.

Software Pipeline Return Calls

The software pipeline 3D li1MultiArc() function processes regular 3D arcs and 3D annotation arcs. If the data type of the input parameter arc_list is XGL_MULTIARC_F3D or XGL_MULTIARC_D3D (the arcs are regular), the function tessellates the arcs and calls the the opsVec entries for these routines:

• For open regular arcs, the function calls li1MultiPolyline().
• For closed regular arcs, the function calls li1MultiSimplePolygon().

If the data type of the input parameter arc_list is XGL_MULTIARC_AF3D or XGL_MULTIARC_AD3D (the arcs are annotated), the function tessellates the arcs in DC, view transforms and clips the arcs, depth cues the arcs, and calls the opsVec entries for these routines:

• For open annotated arcs, the function calls li2MultiPolyline().
• For closed annotated arcs, the function calls li2GeneralPolygon().

li1MultiCircle() - 2D

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. The device pipeline must handle some or all of the attributes listed in the xgl_multicircle() man page.

Syntax

void XglDpCtx2d::li1MultiCircle(
    Xgl_circle_list     *circle_list);

Input Parameters

circle_list....Pointer to the list of circles to render.

Software Pipeline Return Calls

The software pipeline 2D li1MultiCircle() function transforms a list of circles in model coordinates into a list of ellipses in device coordinates. For each circle that needs to be clipped, the circle is decomposed into a polygon and passed to the opsVec entry for li1Polygon().

Circles that do not need clipping are passed to the opsVec entry for li2MultiEllipse().

li1MultiCircle() - 3D

This function draws a list of circles in a plane described by the 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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx3d::li1MultiCircle(
    Xgl_circle_list     *circle_list);

Input Parameters

circle_list....Pointer to a list of circles to render.

Software Pipeline Return Calls

The li1MultiCircle() function processes regular 3D circles and 3D annotation circles. If the data type of the input parameter circle_list is XGL_MULTICIRCLE_F3D or XGL_MULTICIRCLE_D3D (the circles are regular), the function tessellates the circles by projecting the circle onto the plane in MC described by the two direction vectors provided with the circle. It then calls the opsVec entry for the li1MultiSimplePolygon() routine.

If the data type of the input parameter circle_list is XGL_MULTICIRCLE_AF3D or XGL_MULTICIRCLE_AD3D (the circles are annotated), the function tessellates the circles in DC, view transforms and clips the circles, depth cues the circles, and calls the opsVec entry for the li2GeneralPolygon() routine.

li1MultiEllipticalArc() - 3D

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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx3d::li1MultiEllipticalArc(
    Xgl_ell_list *ell_list);

Input Parameters

ell_list.....Pointer to a list of elliptical arcs.

Software Pipeline Return Calls

The li1MultiEllipticalArc() function processes regular 3D elliptical arcs and 3D annotation elliptical 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 tessellates each of the arcs specified in ell_list and calls the opsVec entry for these routines:

• For open non-annotated arcs, the function calls li1MultiPolyline().
• For closed non-annotated arcs, it calls li1MultiSimplePolygon().

If the data type of the input parameter ell_list is XGL_MULTIELLARC_AF3D or XGL_MULTIELLARC_AD3D (the arcs are annotated), the function tessellates the arc in DC, view transforms and clips the arcs, and depth cues the arcs. Then it calls the the opsVec entry for these routines:

• For annotated open arcs, the function calls li2MultiPolyline()
• For annotated closed arcs, the function calls li2GeneralPolygon().

li1MultiMarker() - 2D

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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx2d::li1MultiMarker(
    Xgl_pt_list     *point_list);

Input Parameters

point_list....Pointer to a list of points, optionally with colors associated.

Software Pipeline Return Calls

The software pipeline routine transforms a list of points to DC. 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, the software pipeline calls these routines:

• If the current marker type is xgl_marker_dot, the list of clipped points is passed to the opsVec entry for li2MultiDot().
• 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 point lists are passed to the opsVec entry for li1MultiPolyline().

li1MultiMarker() - 3D

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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx3d::li1MultiMarker(
    Xgl_point_list      *point_list);

Input Parameters

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

Software Pipeline Return Calls

The software pipeline transforms the list of points to DC. 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, points that are inside the pick volume are passed to the opsVec entry for the li2MultiDot() routine for Z comparisons to confirm a pick hit.

If picking is not enabled, the marker points are optionally depth cued, and the software pipeline calls the opsVec entry for these routines:

• If the current marker type is xgl_marker_dot, then the list of clipped points is passed to li2MultiDot().
• 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 point lists are passed to li1MultiPolyline().

li1MultiPolyline() - 2D

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. The device pipeline must handle some or all the attributes listed in the man page.

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. There may be colors and/or flags associated with the points, and the line width may be greater than 1.

---

Note - The device pipeline is responsible for checking the number of vertices for each polyline. When the number of vertices for a polyline is 0 or 1, the pipeline must handle this case appropriately.

---

Software Pipeline Return Calls

The software pipeline li1MultiPolyline() function transforms the array of point lists to DC. If picking is enabled, 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, the software pipeline calls the opsVec entry for li2MultiPolyline().

li1MultiPolyline() - 3D

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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

---

Note - The device pipeline is responsible for checking the number of vertices for each polyline. When the number of vertices for a polyline is 0 or 1, the pipeline must handle this case appropriately.

---

Software Pipeline Return Calls

The software pipeline 3D li1MultiPolyline() function transforms the points in the polyline to DC. If picking is enabled and Z-buffering is enabled, the polylines are passed to the opsVec entry for the li2MultiPolyline() routine to do Z-buffer comparisons 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 software pipeline optinally depth cues the polylines and calls the opsVec entry for li2MultiPolyline().

li1MultiRectangle() - 2D

The li1MultiRectangle() 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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx2d::li1MultiRectangle(
    Xgl_rect_list       *rect_list);

Input Parameters

rect_list.....Pointer to a list of rectangles.

Software Pipeline Return Calls

The point information in the Xgl_rect_list structure is copied into an Xgl_pt_list structure as a list of 4-sided polygons. The function sets the facet flags to 4-sided and convex and calls the opsVec entry for li1MultiSimplePolygon().

li1MultiRectangle() - 3D

The li1MultiRectangle() 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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx3d::li1MultiRectangle(
    Xgl_rect_list       *rect_list);

Input Parameters

rect_list.....Pointer to a list of rectangles.

Software Pipeline Return Calls

The li1MultiRectangle() function processes regular 3D rectangles and 3D annotation 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 a plane in MC and calls the opsVec entry for the li1MultiSimplePolygon() routine.

If the data type of the input parameter rect_list is XGL_MULTIRECT_AF3D or XGL_MULTIRECT_AD3D (the rectangles are annotated), this function transforms the reference points of the multirectangles from MC to DC, view transforms and clips the rectangles, depth cues the rectangles, and calls the opsVec entry for the li2GeneralPolygon() routine.

li1MultiSimplePolygon() - 2D

The li1MultiSimplePolygon() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline 2D li1MultiSimplePolygon() function calls the opsVec entry for li1Polygon() to process each polygon in the list of polygons.

li1MultiSimplePolygon() - 3D

The li1MultiSimplePolygon() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The performance of the software pipeline li1MultiSimplePolygon() routine is optimized if facet flags are set to convex, 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 any one of these conditions is not satisfied (for example, picking is enabled), the software pipeline calls its own li1Polygon() for each polygon. For polygons that meet the conditions, the software pipeline calls the opsVec entry for li2MultiSimplePolygon() for each polygon.

li1NurbsCurve() - 2D/3D

The li1NurbsCurve() function draws a NURBS curve of a specified order based on a list of knots in parameter space, a 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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

void XglDpCtx2/3d::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.

Software Pipeline Return Calls

The software pipeline li1NurbsCurve() function is a common entry point for both the regular NURBS curve primitive (xgl_nurbs_curve()) the Gcache'd NURBS curve (xgl_gcache_nurbs_curve()).

Nurbs Primitive For the regular NURBS primitive, the void* is set to NULL. If the order of the geometry data is 1, the software pipeline sends the list of control points to the the opsVec entry for the li1MultiMarker() routine.

Otherwise, the software pipeline tessellates the geometry data to a list of points in DC for 2D or LC (Lighting Coordinates) for 3D. For 3D, vertex colors are present in the point list if a color spline is non-NULL. The software pipeline calls the li1MultiPolyline() routine with the current coordinate system set to DC or LC as appropriate.

Gcache Nurbs Primitive If the input is from a Gcache containing a NURBS curve, 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. For COMBINED and STATIC Gcaches, a list of points is generated in MC, and the software pipeline calls the opsVec entry for li1MultiPolyline(). For DYNAMIC Gcaches, the points are generated in DC for 2D or LC for 3D, and the software pipeline calls the opsVec entry for li1MultiPolyline().

See page 276 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.

---

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

---

li1NurbsSurf() - 3D

The li1NurbsSurf() function draws a NURBS surface of a specified order based on a list of knots in parameter space, a list of control points, and 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline li1NurbsSurf() function is a common entry point for both the regular NURBS surface primitive (xgl_nurbs_surface()) and the Gcache'd NURBS surface (xgl_gcache_nurbs_surface()).

Nurbs Surface Primitive For the regular NURBS surface primitive, the void* is set to NULL. If the order of the geometry data is 1, the software pipeline sends the list of control points to the opsVec entry for li1MultiMarker().

Otherwise, the routine tessellates the data to triangle lists, quadmeshes, or polylines (if an isoparametric curve is present). Vertices are generated in lighting coordinates. Vertex colors are present in the point lists for triangle lists and quad meshes if a color spline is non-NULL. The software pipeline calls the appropriate routine with current coordinate system set to LC:

• li1TriangleList()
• li1QuadrilateralMesh()
• li1MultiPolyline()

Gcache Nurbs Surface Primitive If the input is from a Gcache and the Gcache contains a NURBS surface, 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. In the case of COMBINED and STATIC Gcaches, a list of points is generated in MC, and the opsVec entry for one of these routines is called:

• li1TriangleList()
• li1QuadrilateralMesh()
• li1MultiPolyline()

For a DYNAMIC Gcache, the points are generated in LC, the push/pop of the coordinate systems is done like a regular NURBS surface primitive, and one of the routines listed above is called. See page 276 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.

---

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

---

li1Polygon() - 2D

The li1Polygon() function draws a single 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline li1Polygon() function transforms the list of point lists to DC. Each list can describe a boundary of a possibly multi-bounded polygon (in other words, "holes" are permitted).

If picking is enabled, the polygon is checked against the pick aperture, and the routine exits. If picking is not enabled, the software pipeline calls the opsVec entry for the li2GeneralPolygon() routine.

li1Polygon() - 3D

The li1Polygon() function draws a single 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline 3D li1Polygon() routine takes an array of point lists, each of which defines a boundary of the polygon. If picking is enabled, 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 polygon boundaries are checked to determine whether any of them pass through the pick volume, and the software pipeline sends the polygon is to the opsVec entry for li2GeneralPolygon().

li1QuadrilateralMesh() - 3D

The li1QuadrilateralMesh() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline LI-1 quadrilateral mesh function breaks up the input quad mesh into triangle strips, one for each row of the original mesh. The routine then calls the opsVec entry for the li1TriangleStrip() function 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. If the interior style is hollow, or if edges are enabled, then these diagonals are not drawn. Quad mesh edges are drawn by the li1TriangleStrip() routine, and the edge pattern is restarted for every new row of the mesh.

li1StrokeText() - 2D/3D

The li1StrokeText() function 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. The device pipeline must account for some or all of the attributes listed in the man page.

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

Software Pipeline Return Calls

The software pipeline li1StrokeText() function takes as input a single point, which is the starting position for the string. If the point is inside the window boundaries, this function converts the string to multipolylines. It calls the opsVec entry for li1MultiPolyline() to render the lines.

li1TriangleList() - 3D

The li1TriangleList() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline li1TriangleList() function provides general purpose triangle rendering. This routine is more flexible than the li1TriangleStrip() primitive because it enables rendering of triangle stars and independent triangles in addition to triangle strips. However, the operations performed by this call are similar to those of 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 in 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 what the triangle list defines.

Within each of these four routines, the processing steps are similar. Once processing is complete on a point list, the list is ready to either be picked or rendered. If picking is enabled and Z-buffering is enabled, the appropriate routine is called:

• li2TriangleStrip()
• li2TriangleList()

For non-Z-buffered picking, a simple geometry test is performed on the points to determine whether they lie within the pick aperture. If picking is not enabled, the points are passed down to:

• li2TriangleStrip()
• li2TriangleList()

From within li2TriangleList() or li2TriangleStrip(), the software pipeline draws edges on triangle lists by calling the li2MultiPolyline() routine for each triangle separately. The edge pattern is restarted for each new triangle.

---

Note - If a triangle within the list is clipped, 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 be in this format.

---

li1TriangleStrip() - 3D

The li1TriangleStrip() 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. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

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

Input Parameters

facet_list	Pointer to a structure containing facet normals and/or colors for the triangles in the strip.
point_list	Pointer to a structure defining the point list.

Software Pipeline Return Calls

The input to this routine is a single point list defining the vertices of the triangles in the strip. The original strip is broken down into sub-strips that are visible in MC. Once processing is complete on a sub-strip, if picking is enabled, then either li2TriangleStrip() is called for Z buffered picking, or a simple geometry test is performed on the points to determine whether they lie within the aperture. If picking is not enabled, the points are passed to li2TriangleStrip() for rendering.

From within li2TriangleStrip(), edges are drawn on triangle strip by calling the li2MultiPolyline() function for each triangle separately. The edge pattern is restarted for each new triangle.

---

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

---

li1Accumulate() - 3D

The li1Accumulate() function accumulates images from one buffer to another. See the xgl_context_accumulate() man page for information on functionality that the device pipeline needs to handle. The device pipeline must handle the attributes listed in the man page.

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

---

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.

Software Pipeline Return Calls

The software pipeline li1Accumulate() function allocates two buffers draw_buf and accum_buf of type XglPixRectMemAllocated. The software pipeline calls li3CopyFromDpBuffer to copy the raster's draw buffer to the allocated buffer's draw_buf. It makes another call to li3CopyFromDpBuffer to copy the contents of the buffer specified by XGL_3D_CTX_ACCUM_OP_DEST to the allocated buffer accum_buf. The accumulation takes place, and the result is written to accum_buf. The software pipeline then calls li3CopyToDpBuffer to write the values to the buffer specified by XGL_3D_CTX_ACCUM_OP_DEST. In addition, there may also be another call to li3CopyToDpBuffer to copy the contents of the accum_buf to copy_buf in the xgl_context_accumulate() call.

li1ClearAccumulation() - 3D

The li1ClearAccumulation() function clears the accumulation buffer. See the xgl_context_clear_accumulation() man page for information on functionality that the device pipeline needs to handle. The device pipeline must handle the attribute listed in the man page.

Syntax

void XglDpCtx3d::li1ClearAccumulation(
    Xgl_color*      color);

Input Parameters

color......Color value.

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 one word at a time as well. This software implementation is for the SPARC architecture only.

Software Pipeline Return Calls

The software pipeline li1ClearAccumulation() function allocates a buffer of type XglPixRectMemAllocated the size, width, and height of the raster, and sets the entire buffer to the specified color. It then calls the LI-3 routine li3CopyToDpBuffer to copy the buffer to the buffer specified by the attribute XGL_3D_CTX_ACCUM_OP_DEST.

li1CopyBuffer() - 2D/3D

The li1CopyBuffer() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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

---

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 (that is, 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 which type of device the application is requesting for the source raster and the destination raster, and then calls the appropriate copy buffer routine.

If your pipeline implements li1CopyBuffer() for the case of copying from memory to a window raster, it must take into account different color models and different underlying representations of memory. The memory raster can be indexed or RGB color type. Note that 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 handle all the cases of the various combinations of Device color type and real color type. However, 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(), the device pipeline must implement both the li1CopyBuffer() function and the XglDpDev::copyBuffer() function. However, XGL provides utility functions that perform copy operations with all the color conversion and fill styles.

Using XGL Utilities for Copy Buffer Operations

CopyBuffer.h defines the data structures and interfaces for two copy buffer 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. For information on these utilities, see Chapter 12. For information on PixRects, see page 214.

The RefDpCtx utility 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 be 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 at LI-1:

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

2. Implement XglDpDev::CopyBuffer(). You can use the utility XgliUtFbToMemCopyBuffer() to do this.

---

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 189 for more information on LI-3 copy buffer functions.

---

Software Pipeline Return Calls

The software pipeline does not implement this function.

li1Flush() - 2D/3D

The li1Flush() 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. The device pipeline must handle the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline does not implement this function.

li1GetPixel() - 2D/3D

The li1GetPixel() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Calling the Software Pipeline

The software pipeline does not implement this function.

li1Image() - 2D/3D

The li1Image() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

---

Software Pipeline Return Calls

The software pipeline li1Image() function transforms the position point from model coordinates to device coordinates, 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 the opsVec entry for the li3CopyToDpBuffer() routine to do the copying.

li1NewFrame() - 2D/3D

This function clears the device coordinate viewport and, for 3D Contexts, the Z-buffer. See the xgl_context_new_frame() man page for information on functionality that the device pipeline needs to handle. The device pipeline must handle some or all of the attributes listed in the man page. See also page 265 for information on clearing the Z buffer.

Syntax

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

What 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 } }

Software Pipeline Return Calls

The software pipeline does not implement this function.

li1PickBufferFlush() - 2D/3D

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. There are no required attributes for this function.

Syntax

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

What You Need to Know to Implement li1PickBufferFlush

This function provides 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) or 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 the function checkLastPick(), which compares the last recorded pick IDs with the current pick IDs and returns TRUE if they are identical. This function is an optimization that 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 li1PickBufferFlush(). 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. This function is not implemented by the software pipeline.

li1SetMultiPixel() - 2D/3D

The li1SetMultiPixel() function sets the color values for a list of pixel locations. 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. See the xgl_context_set_multi_pixel() man page for information on the functionality that the device pipeline needs to handle. The device pipeline must handle some or all of the attributes listed in the man page.

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. The array should contain at least count valid entries.
color	Array of pixel colors to write (in one-to-one correspondence with the location array).

Software Pipeline Return Calls

The software pipeline li1SetMultiPixel() function writes a set of pixels into the locations specified by the pt array argument. Each pixel color is determined by taking successive values from the color argument. For each pixel, the function calls the opsVec entry for li1SetPixel().

li1SetPixel() - 2D/3D

The li1SetPixel() 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. The device pipeline must handle some or all of the attributes listed in the man page.

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.

Software Pipeline Return Calls

The software pipeline does not implement this function.

li1SetPixelRow() - 2D/3D

The li1SetPixelRow() function sets the color value for a row of pixels. 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. See the xgl_context_set_pixel_row() man page for information on functionality. The device pipeline must handle some or all of the attributes listed in the man page.

Syntax

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

Input Parameters

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. The array should contain at least count entries.

Software Pipeline Return Calls

The software pipeline li1SetPixelRow() function writes a series contiguous, horizontal pixels along the y-position supplied by row, starting at the x-position in start_col, and continuing in the direction of increasing x values. The pixel colors along the row are determined by taking successive values from the color argument. For each pixel, the function calls the opsVec entry for li1SetPixel().