About the LI-3 Layer

The LI-3 layer is the lowest level of the XGL interface hierarchy. The LI-3 layer contains dot, vector, and span primitive functions, control functions, and begin/end batching functions. It also includes functions that copy pixel data to and from buffers managed by the device pipeline. An LI-3 device pipeline uses the XGL software pipeline to perform all operations needed to reduce a primitive to the pixel level, and the device pipeline then renders the pixels. Figure 8-1 shows an overview of the pipeline architecture for the LI-3 layer.

Figure 8-1

A graphics handler must provide a set of LI-3 functions, as there is no software pipeline implementation of LI-3 functions. There are two ways to implement LI-3 functions. You can:

• Rewrite the functions for your device to achieve accelerated performance.
• Implement the functions using the RefDpCtx (Reference Device Pipeline Context) set of utilities. RefDpCtx is built on a simple get-pixel and put-pixel interface. It is not meant to provide fast performance, but it enables the device pipeline to get XGL running relatively quickly. RefDpCtx also protects a graphics handler from changes in the XGL API, since RefDpCtx

provides full functionality. RefDpCtx is called from within an LI-3 primitive call. See page 207 for more information on using RefDpCtx to implement the LI-3 layer.

LI-3 Primitives

The LI-3 primitive functions are listed in Table 8-1.

Table 8-1

Function	2D	3D	Description	Swp	Dp
li3MultiDot()	v	v	Draws a list of dots.	-	Required
li3MultiSpan()	v	v	Draws a list of horizontal spans.	-	Required
li3Vector()	v	v	Draws a single vector.	-	Required

The code example below shows the implementation of li3MultiSpan() using the RefDpCtx utility.

void XglDpCtx3dCfb::li3MultiSpan( const Xgli_span_list_3d* span_list, const Xgl_color* color, int* picked) { WIN_LOCK(drawable); refDpCtx.li3MultiSpan(span_list, color, picked); WIN_UNLOCK(drawable); }

Although the 2D versions of the LI-3 primitive functions are straightforward, the 3D LI-3 functions are more complicated because they must support antialiasing, shading, and texture mapping. However, you can use RefDpCtx to implement the difficult primitives. Note that if you decide to accelerate one aspect of an LI-3 primitive, such as transparency, you must implement the entire primitive rather than using RefDpCtx.

LI-3 Batching and Control Functions

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

Table 8-2

Function	2D	3D	Description	Swp	Dp
li3Begin()	v	v	Specify the beginning of a sequence of LI-3 primitives.	-	Required
li3End()	v	v	Specify the end of a sequence of LI-3 primitives.	-	Required

The control functions are called by the software pipeline to set state information in structures used by RefDpCtx. These functions can optionally be called by LI-3 device pipelines. If you fully implement LI-2 and all of the LI-3 functions, your pipeline does not need to implement the control functions; otherwise, the LI-3 control functions must be implemented, as they are called by the LI-2 software pipeline. As with other LI-3 functions, you can implement the control functions using RefDpCtx, as in the following example.

void XglDpCtx3dCfb::li3SetSpanControl(const Xgli_span_control_3d& sc) { refDpCtx.li3SetSpanControl(sc); }

The LI-3 control functions are listed in Table 8-3.

Table 8-3

Function	2D	3D	Description	Swp	Dp
li3GetDotControl()	-	v	Get attributes for li3MultiDot().	-	Required
li3GetVectorControl()	v	v	Get attributes for li3Vector().	-	Required
li3GetSpanControl()	v	v	Get attributes for li3MultiSpan().	-	Required

Table 8-3 (Continued)

Function	2D	3D	Description	Swp	Dp
li3SetDotControl()	-	v	Set attributes for li3MultiDot().	-	Required
li3SetVectorControl()	v	v	Set attributes for li3Vector().	-	Required
li3SetSpanControl()	v	v	Set attributes for li3MultiSpan().	-	Required

LI-2 Software Pipeline and LI-3 Device Pipeline

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

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

where <Prim> is one of the LI-3 primitive functions. All device pipeline LI-3 primitives called by the software pipeline are surrounded by li3Begin()and li3End() calls. Within the li3Begin()/li3End() pair, only the primitive type specified in the li3Begin() function can be called, and no other Context or primitive functions can be called. Within a begin/end, neither the Context nor the LI-3 state will change, and the device pipeline can continue to render.

li3Begin() returns a Boolean value: TRUE means that the LI-3 primitive will be visible when rendered; FALSE means that the LI-3 primitive function will not draw anything because the window is obscured, so the device pipeline may not want to call the primitive function.

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

XglRaster::getDoPixelMapping()
XglDevice::getColorType()

XglDevice::getRealColorType()
XglDevice::getCmap()
XglDevice::getDrawable()

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

XglContext::getRenderBuffer()

Window Locking Around Hardware Access

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

Data Input to the LI-3 Layer

All LI-3 2D functions receive geometry data in 2D integer device coordinates. The geometry will be within the bounds of the window, but it is up to the LI-3 implementation to clip the primitives to the window clip list if the window changes.

All 3D LI-3 geometric coordinates are specified in floating 3D device coordinates and, as such, may have fractional components for the coordinate values. For information on LI-3 data structures, refer to the description of individual primitives or to the header files Li3Structs.h, Li3Structs2d.h, and Li3Structs3d.h.

Picking at LI-3

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

The picked return value is an optimization for LI-2. If the return value is TRUE, then LI-2 can stop sending primitives. The software pipeline LI-2 function that calls LI-3 will update the pick buffer. It is allowable, however, for LI-3 to always return FALSE, but in this case, the LI-3 function must update the pick

buffer by using the XglContext function ctx->addPickToBuffer (Xgl_usgn32 pick_id1, Xgl_usgn32 pick_id2). The device pipeline code need only fill in the picked parameter if picking is enabled. If picking is disabled, it can be ignored. Note that LI-3 functions are only called to do picking if Z-buffering is enabled.

Texture Mapping at LI-3

At LI-2, the software pipeline continues the processing of texturing by doing the following:

1. The software pipeline computes (u,v) values for the span using hyperbolic interpolation and passes the values to the LI-3 device pipeline using the class XgliUvSpanInfo3d.

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

3. The software pipeline computes the MipMap level in which the start of the span is located and the delta and passes this information to LI-3 using XgliUvSpanInfo3d.

For information on XgliUvSpanInfo3d, "Texture Mapping and li3MultiSpan()" on page 205.

At LI-3, the device pipeline must implement texture mapping or call RefDpCtx for texturing. To implement texture mapping, the RefDpCtx object determines the (u,v) value and the lighting coefficient at a pixel. It then uses the (u,v) value to look up the texture map to obtain the texture value (texel). Depending on the control parameters present in the Texture Map object, RefDpCtx combines the texel with the pixel color to obtain the final textured pixel (lighting and depth cueing are done as applicable). Your device pipeline should follow a similar process. Note that there may be more than one texture active, and the final textured pixel is the result after applying all active textures. For more information on implementing texture mapping at LI-3, see page 205.

LI-3 Interfaces

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

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

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

Syntax

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

void XglDpCtx2d::li3End(
    Xgli_layer_prim_2d      prim_type);

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

void XglDpCtx::li3End(
    Xgli_layer_prim_3d      prim_type);

Input Parameters

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

Attributes

There are no specific attributes used by these functions.

li3CopyFromDpBuffer() - 2D/3D

The li3CopyFromDpBuffer() function copies pixel data from the device pipeline's frame buffer into memory. The memory is represented by a PixRectMem object. The PixRect object is the same depth as the frame buffer. For information on PixRects, see page 214, or see the header files PixRect.h and PixRectMem.h.

Syntax

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

Input Parameters

src_rect	A rectangle in the device pipeline's coordinates relative to the origin of the window.
dest_pos	The position to copy to relative to the origin of buf.
sel	Selects an image buffer in the pipeline, when the pipeline is multi-buffering, to copy from.
buf	The PixRect buffer into which the data is copied.

Attributes

There are no specific attributes used by this function.

---

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

---

li3CopyToDpBuffer() - 2D

The li3CopyToDpBuffer() function copies pixel data to the device pipeline's framebuffer out of memory. The memory is represented by a PixRectMem object. The PixRect is the same depth as the frame buffer. For information on PixRects, see page 214, or see the header files PixRect.h and PixRectMem.h.

Syntax

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

Input Parameters

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

Attributes

The Context attributes used by this function are:

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

li3CopyToDpBuffer() - 3D

The li3CopyToDpBuffer() function copies pixel data to the device pipeline's frame buffer out of memory. The memory is represent by a PixRectMem object. The PixRect is the same depth as the frame buffer. For information on PixRects, see page 214, or see the header files PixRect.h and PixRectMem.h.

Syntax

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

Input Parameters

src_rect	A rectangle in buf's coordinates.
dest_pos	The position to copy to relative to origin of the window.
sel	An image buffer in the device pipeline, when the device pipeline is multi-buffering, to copy into.
buf	The PixRect buffer from which the data is copied.
copy_info	Contains information about the incoming data such as the color map and color type of the data. For information on LI-3 data structures, see Li2Structs.h.

Attributes

The Context attributes used by this function are:

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

What You Need to Know to Implement 3D li3CopyToDpBuffer

If the copy_info pointer is NULL, the implementation of li3CopyToDpBuffer() operates as if a structure was given with copy_info->do_zbuffer set to FALSE and copy_info->do_fill_style set to FALSE.

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

Currently, for 3D, li3CopyToDpBuffer() is called by the accumulation operations, li1Accumulate() and li1ClearAccumulation(), and by li1Image().

li3MultiDot() - 2D

The li3MultiDot() function draws a list of dots (pixels) at the x,y locations given in the input point strucutre. If color is not NULL, then all of the dots are drawn in that color. If it is NULL, each dot is drawn in the color given by the per vertex color in pd.

Syntax

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

Input Parameters

pd	An XglPrimData object containing a list of point locations for the marker positions.
color	The color value for the marker, if applicable.

Attributes

The Context attributes used by this function are:

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

li3MultiDot() - 3D

The li3MultiDot() function draws a list of dots at the x,y locations given in pd. If color is not NULL, then all of the dots are draw in that color. If color is NULL, each dot is drawn in the color given by the per vertex color in pd.

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

Syntax

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

Input Parameters

pd	An XglPrimData object containing a list of point locations for the marker positions.
colorOutput Parameter	The color value for the marker, if applicable.
picked	TRUE if the primitive has been picked by Z-buffer-based picking.

Related Data Structures

const Xgli_dot_control_3d& li3GetDotControl() const;

void li3SetDotControl(const Xgli_dot_control_3d&);

typedef struct {
    Xgl_boolean         do_aa;

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

    Xgl_usgn32          unused[4];
} Xgli_dot_control_3d;

Attributes

The Context attributes used by this function are:

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

li3Vector() - 2D

The li3Vector() function draws a vector between two points. The function returns the number of pixels that are drawn for the vector if it is not window clipped. This information is used by the software pipeline LI-2 to manage the pattern information for a polyline. If the flag vector->draw_last_pixel is TRUE, the whole vector is drawn, if it is FALSE, then the last pixel in the vector is not drawn.

The vector control structures specify whether the vector is solid, patterned or alt patterned, and give the pattern information. The vector control structures also specify the alternate color for patterned lines.

Syntax

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

Input Parameters

vector	Pointer to a structure defining the vector. Refer to the structure Xgli_vector_2d below.
color	Color of the vector and, for an an alt-patterned vector, the color of the foreground pixels.

Related Data Structures

const Xgli_vector_control_2d& li3GetVectorControl() const;

void li3SetVectorControl(
    const Xgli_vector_control_2d&);

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

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

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

Attributes

The Context attributes used by this function are:

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

li3Vector() - 3D

The li3Vector() function draws a vector between two points. The function returns the number of pixels drawn for the vector if it is not window clipped. This information is used by the software pipeline LI-2 to manage the pattern information for a polyline. If the flag vector->draw_last_pixel is TRUE, the whole vector is drawn; if it is FALSE, then the last pixel in the vector is not drawn.

The vector control structures specify whether the vector is solid, patterned or alt patterned, and give the pattern information. The control structures also specify the blend type.

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

Syntax

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

Input Parameters

vector	Pointer to a structure defining the vector. Refer to the structure Xgli_vector_3d below.
colorOutput Parameter	Color of the vector and for the foreground pixels in an alternate patterned vector. If color is NULL, then vector->p1_color and vector->p2_color values are interpolated.
picked	TRUE if the primitive has been picked by Z-buffer-based picking.

Related Data Structures

const Xgli_vector_control_3d& li3GetVectorControl() const;

void li3SetVectorControl(const Xgli_vector_control_3d&);

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

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

Attributes

The Context attributes used by this function are:

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

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

Notes

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

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

The control structure allows for using vectors to implement transparent, hollow polygon edges, but this is not currently supported.

li3MultiSpan() - 2D

The li3MultiSpan() function draws a list of spans. A span is a horizontal run of pixels given by a starting X and Y location and the number of pixels to draw in the X direction. The X direction may be either to the left or to the right of the starting location.

The span control structures specify the fill style for the spans and give the raster pattern to use for patterned spans.

Syntax

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

Input Parameters

span_list	Pointer to a structure defining the list of spans to be rendered. Refer to the structure Xgli_span_list_2d below.
color	Controls the color of the spans in the list. If the color parameter is not NULL, all the spans are drawn in the same color. If color is NULL, the color field in the span structure specifies the color for each span.

Related Data Structures

const Xgli_span_control_2d&   li3GetSpanControl() const;

void  li3SetSpanControl(const Xgli_span_control_2d&);

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

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

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

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

Attributes

The Context attributes used by this function are:

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

li3MultiSpan() - 3D

The li3MultiSpan() function draws a list of spans. A span is a horizontal run of pixels given by a starting X and Y location and the number of pixels to draw in the X direction. The X direction may be either to the left or to the right of the starting location.

The span control structures specify the fill style for the spans and give the raster pattern to use for patterned spans. The control structures also specify transparency value and transparency mode (either screen door or blended transparency), type of blending, and whether texture mapping or lighting is enabled.

Syntax

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

Input Parameters

span_list	Pointer to a structure defining the list of spans to be rendered. Refer to the structure Xgli_span_list_3d below.
colorOutput Parameter	Controls the color of the spans in the list. If color is not NULL, all the spans are drawn in the same color. If color is NULL, the color field in the span structure specifies the color for each span. If the color is given per span, then the color is interpolated using the color_start and color_delta fields in the Xgli_span_3d structure.
picked	TRUE if the primitive has been picked by Z-buffer-based picking.

Related Data Structures

const Xgli_span_control_3d&li3GetSpanControl() const;

void li3SetSpanControl(const Xgli_span_control_3d&);

typedef struct {
    Xgli_fill_style_info        fill_style_info;
    Xgli_blend_type             blend_type;   // only NONE,
                                              // SCREEN_DOOR,
                                              // or TRANSP
    Xgli_transp_info            transp_info;
    Xgl_boolean                 do_texturing;
    Xgl_boolean                 do_lighting;
    Xgl_usgn32                  unused[4];
} Xgli_span_control_3d;

typedef struct {
    Xgl_usgn32          num_x;
    Xgl_usgn32          y_start;        // Y start value
    Xgl_usgn32          x_start;        // X start value
    Xgl_sgn32           x_delta;        // either +1 or -1
    Xgli_fixed_z        z_start;        // Z start
    Xgli_fixed_z        z_delta;        // Z increment
    double              w_start;
    double              w_delta;

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

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

typedef struct {
    Xgl_usgn32          num_spans;
    Xgli_span_3d        *spans;

    Xgl_usgn32          unused[4];
} Xgli_span_list_3d;

---

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

---

Attributes

The Context attributes used by this function are:

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

Texture Mapping and li3MultiSpan()

Spans can be filled with a texture-mapped pattern. If the do_texturing field in Xgli_span_control_3d is TRUE, spans are rendered with a texture-mapped pattern. The information needed to texture a span is passed from LI-2 in the uv_info field of the Xgli_span_3d structure.

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

XgliUtUvSpanInfo3d provides functions to retrieve this information and increment the information as the span is traversed. The interfaces provided by this class are listed in Table 8-4.

Table 8-4

Function	Description
void setNumInfo(Xgl_usgn32 n)	Sets the number of texture coordinates (u,v) and related information that needs to be stored in the class. This corresponds to the number of data maps that are active. This function allocates the neccesary space for the storage.
Xgl_usgn32 getNumInfo() const	Returns the number of sets of texture coordinate ({u,v}) values.
Xgli_light_and_uv_info* getLightAndUvInfo()	Returns a structure that contains the {u,v} related fields such as numerator and delta (for hyperbolic interpolation), the start MipMap level and delta for the span, and the lighting coefficients and delta for the span. The function is called when various fields need to be filled in.
void getPixelDataInfo (Xgli_pixel_data_info*) const	Takes the current value of texture coordinates ({u,v}) and light coefficients at a pixel location, does a perspective divide, and returns the values. The value returned is the texture coordinate ({u,v}) that is used to look up in the texture map, and the lighting coefficients used to light the pixel. Note that there can be multiple data maps and several textures within a data map that are active. The structure has an array of {u,v} values corresponding to the number of data map objects that are active.
void incrementLightAndUvInfo()	Increments the pixel information as it proceeds along the span. Typically, the caller uses getPixelDataInfo() to get the {u,v} and lighting values for each pixel and then increments the pixel information to reflect the correct values for the next pixel in the span.

Note that texture mapping is implemented in RefDpCtx. If you choose not to use RefDpCtx but want to implement texture mapping, you can call the utility XgliUtCalcTexturedColor. For information on this utility, see Chapter 12, "Utilities".

RefDpCtx

RefDpCtx (Reference Device Pipeline Context) is a utility object that provides a non-optimized implementation of LI-3 functions and several LI-1 pixel functions for the device pipeline. Each device pipeline must implement the LI-3 functions for its device. However, the pipeline can choose to use the RefDpCtx LI-3 implementation of the LI-3 functions. The RefDpCtx object performs all operations for rendering at the LI-3 level, including texture mapping, blending, and transparency.

The way a device is described to the RefDpCtx object is through a number of PixRect objects. PixRect objects are abstractions of the buffers managed by the device, for example the image buffer, Z-buffer, and accumulation buffer. RefDpCtx uses the methods of the PixRect object to read and write pixels to the device.

Using RefDpCtx for Rendering

To use RefDpCtx for rendering, the pipeline must create PixRect objects to represent its buffers. For 2D rendering, the pipeline needs a PixRect object to represent the image buffer (or the current image buffer if multibuffering is in effect). For 3D rendering, the pipeline needs PixRect objects to represent the image buffer, the Z-buffer, and the accumulation buffer. Setting up the PixRect objects for RefDpCtx involves allocating members in several of the device pipeline interface files and implementing methods to support RefDpCtx rendering. This is described in the next section.

Setting Up PixRect Objects for Rendering Through RefDpCtx

The initial work in setting up PixRect objects to use RefDpCtx depends on whether your device has memory-mappable buffers or non-memory mappable buffers. The PixRect class hierarchy provides subclasses to handle memory-mapped buffers. For devices with non-memory-mapped buffers or for devices in which only one buffer can be accessed at a time (the image buffer and Z buffer share the same address space), you have to create your own subclass of PixRect to communicate with your device. For 3D pipelines, you also need to determine whether the Z buffer and accumulation buffer are handled in hardware or software. If they are handled in hardware, how the PixRects are allocated again depends on the type of hardware device.

Once you have determined the type of device you have, the procedure for setting up PixRects to use RefDpCtx for rendering is the same for both types of devices.

Follow these steps to implement rendering using the RefDpCtx utility class.

1. Begin setting up the PixRect objects by doing one of the following:

• For a memory-mapped frame buffer - In the XglDpMgr class, declare an XglPixRectMem member, such as fbPixRect, for the frame buffer. In your XglDpMgr source file, specify the base address of the framebuffer, get the frame buffer height and width, and get the depth of the window. Initialize the frame buffer PixRect with these values.
• For a non-memory mapped frame buffer - Subclass from PixRect.h to create a PixRect class specific to your frame buffer. Override PixRect.h functions with functions that do whatever is needed to access the hardware. See page 214 for information on the methods of the classes in the PixRect hierarchy.

2. At the raster level, in the XglDpDev object, continue to set up the PixRects for use by RefDpCtx as follows:

   a. In DpDev.h, declare PixRects for the window image buffer for 2D, and for the image buffer, Z buffer, and accumulation buffer for 3D. The types of PixRects that you can use are listed in Table 8-5. See "PixRect Objects" on page 214 for more information about the PixRect classes.

Table 8-5

PixRect Type	Buffer
XglPixRect<YourFb>	PixRect for hardware non-memory mapped frame buffer or for devices in which only one buffer can be accessed at a time. Subclass this PixRect from PixRect.h.
XglPixRectMemAssigned	PixRect for hardware memory mapped frame buffer, including Z buffer in hardware. Provided in the PixRect class hierarchy.
XglPixRectAllocated	PixRect for Z buffer or accumulation buffer in software. Provided in the PixRect class hierarchy.

b. In the DpDev header and source files, provide methods that RefDpCtx can use to access the PixRects, including methods for allocating software PixRects, if necessary.

c. Initialize the PixRects to point to hardware addresses or memory. Memory mapped frame buffers can use fbPixRect as a resource to set up the image buffer PixRect.

3. In the XglDpCtx object, make the PixRect objects available to RefDpCtx using the RefDpCtx methods listed in Table 8-6.

Table 8-6

	Method	Description
2D	setImagePixRect()	Assigns a PixRect for the image buffer.
	setClipMaskPixRect()	Assigns a Pixrect for the clip mask.
3D	setImagePixRect()	Assigns a PixRect for the image buffer.
	setClipMaskPixRect()	Assigns a PixRect for the clip mask.
	setZbufferPixRect()	Assigns a PixRect for the Z-buffer.
	setAccumBufferPixRect()	Assigns a PixRect for the accumulation buffer.

The example code below shows how a 3D pipeline XglDpCtx class constructor uses RefDpCtx functions to call XglDpDev methods that return pointers to the PixRects the device is using.

XglDpCtx3dCfb::XglDpCtx3dCfb(XglDpDevCfb* dD, XglContext3d* ctx) : XglDpCtx3d(ctx), refDpCtx((XglRaster*)dD->getDevice(), ctx) { dpDev = dD; drawable = dpDev->getDevice()->getDrawable(); // the following XglDpDev functions are device-dependent // functions that return pointers to PixRects refDpCtx.setImagePixRect(dpDev->getWinPixRect()); refDpCtx.setZbufferPixRect(dpDev->getZbufferPixRect()); refDpCtx.setAccumBufferPixRect (dpDev->getAccumBufferPixRect()); }

RefDpCtx LI-3 Rendering Example

Once PixRects are assigned to the RefDpCtx, the pipeline can use them to render LI-3 functions. The example code below shows a 3D pipeline implementing li3MultiSpan() using RefDpCtx. The RefDpCtx object calls the PixRect functions getValue() and setValue() to modify the pixel values of the input data.

---

Note - Because RefDpCtx accesses the hardware via PixRect objects, the pipeline must bracket calls to RefDpCtx with WIN_LOCK() and WIN_UNLOCK() calls to lock and unlock the clip list. It is up to the pipeline to manage window locking around a RefDpCtx call.

---

void XglDpCtx3dCfb::li3MultiSpan( const Xgli_span_list_3d* span_list, const Xgl_color* color, int* picked) { WIN_LOCK(drawable); // Handle window obscured or moved refDpCtx.li3MultiSpan(span_list, color, picked); WIN_UNLOCK(drawable); }

---

Note - RefDpCtx only renders into the current image buffer. The user of RefDpCtx must ensure that its current image buffer is synchronized with the buffer identified by XglContext::getRealRenderBuffers(). When the device is in double buffer mode, the device pipeline must use the setImagePixRect() function to switch the buffer used by RefDpCtx. In addition, it is possible for getRealRenderBuffers() to indicate that geometry is rendered into both the draw and display buffers. In this case, the device using RefDpCtx must render each primitive twice: once with the image PixRect pointing to the draw buffer and once with it pointing to the display buffer.

---

Handling Attribute Changes for RefDpCtx

The RefDpCtx object has data associated with it, including information on the color map, plane mask, ROP, or the Z-buffer compare method. The pipeline must update the RefDpCtx object when attribute changes occur. To do this, the pipeline determines whether relevant attributes have changed and calls the RefDpCtx methods generalGroupChanged() and cmapChanged() to inform RefDpCtx of changes. Table 8-7 briefly describes these RefDpCtx methods.

Table 8-7

Function	Description
generalGroupChanged()	Informs RefDpCtx that changes have occurred in plane mask, ROP, or Z-buffer compare method. Check for the attributes XGL_CTX_PLANE_MASK, XGL_3D_CTX_Z_BUFFER_COMP_METHOD, or XGL_CTX_ROP.
cmapChanged()	Informs RefDpCtx that the device color map changed.

One place to update the RefDpCtx object is in the XglDpCtx objectSet() routine. The following code fragment shows the GX objectSet() routine using RefDpCtx methods to update the RefDpCtx object.

void XglDpCtx2dCfb::objectSet(const Xgl_attribute *att_type) { for (;*att_type; att_type++) { switch(*att_type) { case XGL_CTX_DEVICE: refDpCtx.cmapChanged(); // no break case XGL_CTX_PLANE_MASK: case XGL_CTX_ROP: update(ctx); refDpCtx.generalGroupChanged(); return; break; } } }

RefDpCtx Interfaces

The RefDpCtx classes provide some LI-1 functions and the complete set of LI-3 functions. These RefDpCtx methods are listed in Table 8-8.

Table 8-8

LI-3 Methods in RefDpCtx	LI-1 Methods in RefDpCtx
li3SetVectorControl()	li1NewFrame()
li3GetVectorControl()	li1SetPixel()
li3SetSpanControl()	li1SetPixelRow()
li3GetSpanControl()	li1GetPixel()
li3Begin()	li1SetMultiPixel()
li3End()	li1CopyBuffer()
li3Multidot() li3Vector() li3MultiSpan() li3CopyFromDpBuffer() li3CopyToDpBuffer() li3GetDotControl() (3D only)	li1CopyBufferMemToFB()

The functions listed in Table 8-9 are unique to RefDpCtx and its subclasses. See the header files RefDpCtx.h, RefDpCtx2d.h, and RefDpCtx3d.h for a complete list of RefDpCtx methods.

Table 8-9

Function	Description
void setImagePixRect(XglPixRect*)	Sets the PixRect that represents the image buffer to draw into. If single buffering is being used, this PixRect will be set once; if multi-buffering is used, this PixRect will be changed.
void setZbufferPixRect (XglPixRect* z)	Sets the PixRect that represents the Z-buffer.
void setAccumBufferPixRect (XglPixRect* a)	Used by copy buffer during the accumulation operation.

Table 8-9 (Continued)

Function	Description
void setClipMaskPixRect (XglPixRectMem* i, Xgl_boolean no_need_to_clip)	Call when the clip list changes. The PixRect for the clip area is a 1-bit deep PixRect that represents the mask for the clip area. This PixRect comes from the XglDrawable function getMergeClipMask().
void syncClipMask()	Gets the current clip mask from the Drawable. In the current implementation, synclipMask() is called internally to ensure that the current clip mask is always up to date.
void setDoMaskAndRop(Xgl_boolean)	Controls whether RefDpCtx does the plane mask and ROP. If it returns TRUE, the current plane mask and rop are used in calculating the pixel value. If it returns FALSE, then the plane mask and rop are not applied.
void cmapChanged()	When XGL_CTX_DEVICE is passed through objectSet(), the device pipeline should call this function to inform RefDpCtx that the Device's Color Map object has changed.
clearZBuffer(const Xgl_bounds_d3d* dcViewport)	Call to request RefDpCtx to clear the Z buffer.
void generalGroupChanged()	When XGL_CTX_PLANE_MASK (2D and 3D), XGL_CTX_ROP (2D and 3D), and XGL_3D_CTX_Z_BUFFER_COMP_METHOD (3D only) are passed through objectSet(), the device pipeline should call this function to inform RefDpCtx that changes have occurred in plane mask, ROP, or Z-buffer compare method.

PixRect Objects

PixRects are objects that provide a uniform way of accessing and managing a 2D array of pixels. PixRects are used by the XGL core for Memory Rasters, Context fill patterns, and accumulation buffers. Device pipelines use PixRects in two ways:

• If the device pipeline uses RefDpCtx for LI-3 rendering, the pipeline will use PixRects to represent the image buffer for 2D and to represent the image buffer, Z-buffer, and accumulation buffer for 3D. See "RefDpCtx" on page 207 for information on using RefDpCtx to implement LI-3 functions.
• PixRects are used as the raster image for copy buffer operations. See the description of li1CopyBuffer() on page 313 and "Defining the Device Pipeline Device Class" on page 39 for information on copy buffer functions.

Pixel values in PixRects are unsigned and can be 1, 4, 8, 16, 32, or 48 bits in depth. A pixel value can be specified by an (x,y) location, and you can get or set a value at that location.

Using PixRects

XglPixRect is the base class of the hierarchy that provides methods for using PixRects. If your device's buffers are memory mappable, the XglPixRect class has several subclasses that memory-mapped frame buffers can use to declare PixRect objects. If your device is not memory mappable or if your memory-mapped device does not correspond to Sun's memory format (see the XGL Reference Manual page for the format of Sun Memory Rasters), you need to derive a class from XglPixRect for your frame buffer. The XglPixRect class hierarchy is illustrated in Figure 8-2.

Figure 8-2

Memory-Based PixRects

The XglPixRectMem class is a specialized version of XglPixRect in which the underlying pixels can be addressed as memory. In this class, memory-mapped frame buffers and memory allocated via malloc are treated the same way. If your device is a memory-mapped frame buffer and it corresponds to the Sun memory layout, you can declare a PixRect object using one of the subclasses of XglPixRectMem.

The XglPixRectMemAssigned class sets up PixRect data structures to point to an existing piece of memory. An object of type XglPixRectMemAssigned is based on a memory-mapped frame buffer, memory allocated via malloc, or on an existing XglPixRectMemAllocated object. To create a PixRectMemAssigned object, declare the PixRect, allocate the memory, and assign the memory to the PixRect.

An object of type XglPixRectMemAllocated dynamically allocates memory to create a PixRect of a given width, height, and depth. To create an object of this type, declare the object and then call its reallocate() function to allocate the memory.

PixRects for Non-Memory-Based Frame Buffers

If neither the image part of the buffers nor the Z-buffer is directly memory mappable or if only one of the buffers can be accessed at a time, the device pipeline must derive its own PixRect implementation from PixRect.h. An example of this when the pixel values you want to read are not memory based but are in a register or a set of registers.

In your device PixRect class, you can do whatever you need to do to access the frame buffer. The RefDpCtx implementation requires separate PixRect objects for the image buffer and the Z-buffer, so you might need two objects, one for the image buffer and one for the Z-buffer, that are connected to manage the registers between them.

PixRect Interfaces

Table 8-10 lists interfaces that are provided by XglPixRect and its subclasses. These functions describe the basic interface to a PixRect. Note that the color values are stored in xBGR format. In this format, the physical amount of memory for a 24-bit RGB pixel is actually 32 bits, in which the high-order byte is unused, the next byte is blue, followed by one byte each of green and red intensity values.

Table 8-10

Function	Description
getValue() setValue()	Return the value of a pixel or set the value of a pixel at the given coordinates. The PixRect must have a depth less than 32 bits, where the depth refers to the physical size rather than the layout of the pixel (in other words, a 32-bit PixRect may hold only 24 bits of information for RGB). Undefined if the coordinate values are out of bounds or the pixel is obscured. These functions must be supplied by the subclasses.
getWidth() getHeight() getDepth()	Return the size of the PixRect.
isMemory()	Returns TRUE if the PixRect can be accessed as pure memory, as when the PixRect is in memory or is a memory-mapped frame buffer, and the pixel layout corresponds to the Sun standard pixel format. See the man pages for XGL Memory Rasters for information on the Sun standard pixel format.
getWrapOriginX() getWrapOriginY() setWrapOriginX() setWrapOriginY()	Set and get the wrap values that are used for stipple filling where the pattern repeats itself. The origin specifies a position in the PixRect, and the get wrap value takes an (x,y) value and does a modulus operation on the value with the width and height, and returns the value at that modulus position. This is used for filling where the fill pattern is represented as a PixRect.
getWrappedValue()	Subtracts wrapOrigin from the point, wraps at the edge of the PixRect, and returns the value.

Table 8-10

Function	Description
fillRectangle()	Sets a rectanglar region with a given value.
getValueByPointer() setValueByPointer()	Handle very large PixRects. Specifically, these functions handle 48-bit deep PixRects, which are used by the accumulation operation.

Table 8-11 lists the interfaces provided by the XglPixRectMem class.

Table 8-11

Function	Description
getLineBytes()	Returns the number of bytes per scan line, including any possible padding at the end of the PixRect.
getMemoryAddress()	Given an (x,y) location, this function returns a pointer to the address of the pixel at that location.
getMemoryAddress1() getMemoryAddress4() getMemoryAddress8() getMemoryAddress16() getMemoryAddress32() getMemoryAddress48()	Inline versions of getMemoryAddress().
getValue1() getValue4() getValue8() getValue16() getValue32() setValue1() setValue4() setValue8() setValue16() setValue32()	Inline versions of getValue() and setValue().

Table 8-12 lists the interfaces provided by the XglPixRectMemAllocated class.

Table 8-12

Function	Description
reallocate()	Returns the address of the newly allocated memory raster. NULL if allocation fails.
deallocate()	Frees memory used for the PixRect.

Table 8-13 lists the interfaces provided by XglPixRectMemAssigned.

Table 8-13

Function	Description
reassign()	Creates a PixRect on existing memory.