Internal Data Types

The XGL API offers a wide variety of point types that applications can use to pass data to XGL. Although varied, these point types do not contain all the information that a device pipeline might need to efficiently display the data. To solve this problem, XGL designed a number of internal data types that the pipeline can reference to get application data. These internal data types contain both the application geometry and some useful information about the geometry.

At the LI-1 layer, the API parameters are passed directly to the device pipeline. For more information on the LI-1 API arguments, refer to the XGL Reference Manual.

Most geometry in XGL that is passed to and between loadable interface layer 2 is stored under the control of a C++ class called XglPrimData. This class contains pointers to the original API data (essentially the arguments to the API primitive), together with a framework that is used internally by the software pipeline. XglPrimData is used to handle both 2D and 3D point and facet types; the same structures are used in both cases.

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

At the LI-3 layer, a different set of data structures is used for point data. These data structures, along with the LI-3 functions that use them, are described in Chapter 9, "Writing Loadable Interfaces". To help you implement the LI-3 layer, XGL provides a set of utilities that render to a device via the PixRect object. A PixRect is an abstraction of a rectangular array of pixels that represents the underlying frame buffer. Information on the PixRect object and its interfaces is provided in this chapter on page 89.

Accessing Data at the LI-1 Layer

To access data at the LI-1 layer, the device pipeline receives the API data directly from the application. Figure 4-1 illustrates the flow of data through the LI-1 primitive.

Figure 4-1

This section presents several code samples for accessing application data. You can copy or modify these source code samples and the other source code samples in this chapter as long as the resulting code is used to create a loadable pipeline for XGL.

Accessing Application Data

The example below shows how a fictitious device might access data from the application to draw a simple 2D multipolyline.

void XglDpCtx2dExample::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); } } }

Accessing Facet Data

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

void XglDpCtx3dExample::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); } } }

Point Lists with Data Mapping Values

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.

Data Access for DMA Devices

The next 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 being called back by the software pipeline. This means that 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)); } }

How Data Is Stored by the Software Pipeline

The XglPrimData class includes a subclass called XglLevel. This class is used by the software pipeline to store the results of processing the original API data. A level is a memory area for storing primitive data. Each time the data is modified, as it would be after transformations, clipping, lighting, depth cueing, shading, or texture mapping, a new level is started. This allows the software pipeline to move data around as it processes data and provides it with access to previous stages of the pipeline. It also allows a device pipeline to refer back to an earlier version of the data. Figure 4-2 illustrates the XglLevel objects that would be created for a hypothetical software pipeline that transformed, clipped, and lit the geometry data; level 0 contains the original API data.

Figure 4-2

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

Figure 4-3

Data Storage in the XglLevel Object

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

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

Figure 4-4

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

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

Figure 4-5

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

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

LI-2 Point Data

LI-2 point data is stored internally under the control of the XglPrimData object. The information relevant to the device pipeline is stored in an object called XglLevel within the XglPrimData object. XglLevel contains point list information that is created when the data moves down through the software pipeline. For example, the first level, level 0, is created when the LI-1 software pipeline is called. If points are transformed, the transformed points are stored at a different level than the original points. Level objects are used extensively by the software pipeline and are the device pipeline LI-2 layer interface to the processed geometry.

Accessing Data at the LI-2 Layer

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

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

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

XglDpCtx2dExample::li2MultiPolyline(XglPrimData *pd) { // // First get the XglLevel structure.This method gets the // current level, that is the one that contains the most // up-to-date data. // level = pd->getCurrentLevelData(); // // Get the number of point lists, and the point lists // themselves. // num_pl = level->getNumPointLists();

pl = level->getPointLists(); // // See if we have to close the polylines. If this routine is // being called to draw a hollow polygon, for instance, then // the first and last points need to be connected. // close_flag = pd->getProcessFlags() & XGLI_CLOSE_FLAG; // // Loop on the point lists. // for (i = 0; i < num_pl; i++) { pt = (Xgl_pt_i2d*) pl->geom_ptr.base_ptr; // // Loop on the points in each point list. // for (j = 0; j < pl->current_num_points; j++) { send_to_hardware(pt->x); send_to_hardware(pt->y); XGLI_INCR(pt, Xgl_pt_i2d*, pl->geom_ptr.step_size); } // // Optionally close the polyline - send down the 1st pt // again. // if (close_flag) { pt = (Xgl_pt_i2d*) pl->geom_ptr.base_ptr; send_to_hardware(pt->x); send_to_hardware(pt->y); } } }

---

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

---

Pipeline Interfaces to XglPrimData and XglLevel Data

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

Table 4-1

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

Table 4-2 lists useful interfaces from the XglLevel subclass of XglPrimData.

Table 4-2

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

Conic and Rectangle Data

The conic and rectangle data at the LI-1 layer is defined at the API level. This section discusses the conic and rectangle data at the LI-2 layer.

The XglConicData{2,3}d and XglRectData{2,3}d data structures are used to hold information for rendering conics and rectangles. These data structures are based on XglPrimData in that they organize the data into levels and use a base-pointer/step-size technique. They differ from XglPrimData in that the level structures are used at LI-2.

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

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

The following examples illustrate how the pipeline can retrieve information from these objects.

Accessing Rectangle Data from XglRectData

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

void XglDpCtx2dExample::li2MultiRect(XglRectData2d* rd) { XglRectList2d* rlist; Xgl_usgn32 num_rects; // number of rectangles Xgl_rect_i2d* rectangle; // // Extract the list of rectangles from the data structure. // rlist = rd->getCurrentLevelData(); num_rects = rlist->getNumRects();

rectangle = (Xgl_rect_i2d *)(rlist ->cornerPoints.base_ptr); // // Loop through the list of rectangles. // for (long i = 0; i < num_rects; i++, rectangle++) { send_to_hardware(rectangle->corner_min.x); send_to_hardware(rectangle->corner_min.y); send_to_hardware(rectangle->corner_max.x); send_to_hardware(rectangle->corner_max.y); } }

Accessing Conic Data from XglConicData

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

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

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

Pipeline Interfaces to XglConicData and XglRectData

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

Table 4-3

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

Table 4-4 lists interfaces provided by XglConicList2d.

Table 4-4

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

Table 4-4

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

Table 4-5 lists interfaces provided by the XglRectData classes.

Table 4-5

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

Pixel Data

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 348 for information on using RefDpCtx to implement LI-3 functions.
• PixRects are used as the raster image for copy buffer operations. See page 293 in Chapter 9, "Writing Loadable Interfaces" and the section beginning on page 38 in Chapter 3, "Pipeline Framework" 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 subclass from XglPixRect for your frame buffer. The XglPixRect class hierarchy looks like Figure 4-6.

Figure 4-6

Memory-Based PixRects

The XglPixRectMem class is a specialized version of PixRect 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 itself 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.

Subclassing a PixRect for a Non-Memory-Based Frame Buffer

If neither the image part of the buffers nor the Z-buffer is direct memory mappable or if only one of the buffers can be accessed at a time, the device pipeline must subclass its own PixRect implementation from PixRect.h. An example of this is the case where 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 4-6 lists interfaces provided by XglPixRect and common to its subclasses. These functions describe the basic interface to a PixRect. Note that the color values are stored in xBGR format, where for a 24-bit RGB pixel, the physical amount of memory 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 4-6

Function	Description
getValue() setValue()	Return the value of a pixel or sets 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 wrap values 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.
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 4-7 lists the interfaces provided by the XglPixRectMem class.

Table 4-7

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 4-8 lists the interfaces provided by the XglPixRectMemAllocated class.

Table 4-8

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

Table 4-9 lists the interfaces provided by XglPixRectMemAssigned.

Table 4-9

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