Sun and OracleChannel SunHow to BuyLog In简体中文

XGL Device Pipeline Porting Guide
只搜寻这本书
搜索帮助
包含在
查找更多文档
专项支持资源
 以 PDF 格式下载本书

Utilities

10

This chapter provides information on XGL utilities. XGL utilities are designed to perform specific operations and are useful for special case processing. Utility classes have Ut in the name, for example XgliUtFooBar. The utilities are part of the core XGL library; they are not in a separately loaded library.

Imported image(30x36)

Most XGL utilities are found in these header files:
  • RefDpCtx.h,RefDpCtx2d.h, and RefDpCtx3d.h
  • CheckBbox.h
  • CopyBuffer.h
  • PgonClass.h
  • Utils3d.h
  • utils.h

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 on its device. However, the pipeline can choose to use the RefDpCtx LI-3 implementation of the LI-3 functions.
The way a device is described to the RefDpCtx object is through a number of PixRect objects. These PixRect objects are abstractions of the buffers managed by the device, for example, the image buffer, Z-buffer, and accumulation buffer. The RefDpCtx object performs all operations for rendering at the LI-3 level, including texture mapping, blending, and transparency. RefDpCtx uses the methods of the PixRect object to read and write pixels.
Before you use RefDpCtx, you should consider the following design issues:
  • Because RefDpCtx accesses the hardware via PixRect objects, the pipeline must bracket calls to RefDpCtx with WIN_LOCK() and WIN_UNLOCK() calls. It is up to the pipeline to manage window locking around a RefDpCtx call.
  • The pipeline must communicate certain attribute changes to RefDpCtx. The device pipeline itself receives information about attribute changes through the device pipeline context object (objectSet()) at the various LI layers, and it handles those changes internally. However, the RefDpCtx is a separate utility object for the pipeline; therefore, the pipeline needs to pass along information about attribute changes to this object as follows:

    · The pipeline can determine itself whether specific attributes have changed or whether the Device's color map object changed. If either of these changed, the pipeline can call RefDpCtx interfaces generalGroupChanged() or cmapChanged() to tell RefDpCtx that changes have occurred.

  • RefDpCtx uses PixRects to represent the buffers of the device. PixRects provide subclasses to handle memory-mapped buffers. If your device's buffers are not memory-mappable, you will have to create your own subclass of PixRect to communicate with your device. See Chapter 4, "Internal Data Storage" for information on PixRect objects.

Using RefDpCtx

To use RefDpCtx for 2D, the pipeline needs a PixRect object to represent the image buffer (or the current image buffer if multibuffering is in effect). For 3D, the pipeline needs PixRect objects to represent the image buffer, the Z-buffer, and the accumulation buffer.
To make the PixRects available to the RefDpCtx object, users of RefDpCtx2d will call:
setImagePixRect()Assigns a PixRect for the image buffer.
setClipMaskPixRect()Assigns a Pixrect for the clip mask.
Users of RefDpCtx3d will call the above functions and the following:
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 might create RefDpCtx object in its XglDpCtx class.

  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());  
  }
Once the PixRects are assigned to the RefDpCtx, the pipeline can use them to render LI-3 functions. There is data associated with the RefDpCtx object, such as plane mask, ROP, and Z-buffer compare method; therefore, the pipeline must check the relevant state and update the RefDpCtx object if necessary.
The example code below shows a 3D pipeline implementing LI-3 using RefDpCtx LI-3 calls. Note that the calls to RefDpCtx rendering functions must be bracketed by calls to lock and unlock the clip list. RefDpCtx calls the PixRect functions getValue() and setValue() to modify the pixel values. You can copy or modify this source code sample as long as the resulting code is used to create a loadable pipeline for XGL.

  const Xgli_span_control_3d&  
  XglDpCtx3dCfb::li3GetSpanControl() const  
  {  
      return refDpCtx.li3GetSpanControl();  
  }  
  
  void  XglDpCtx3dCfb::li3SetSpanControl(const  
  Xgli_span_control_3d&  
                                      sc)  
  {  
      refDpCtx.li3SetSpanControl(sc);  
  }  
  
  void XglDpCtx3dCfb::li3MultiSpan(  
                    const Xgli_span_list_3d* span_list,  
                    const Xgl_color*color,  
                    int*         picked)  
  {  
       // Update RefDpCtx with attribute changes  
  
       WIN_LOCK(drawable);  
  
       // Handle window obscured or moved  
  
       refDpCtx.li3MultiSpan(span_list, color, picked);  
  
       WIN_UNLOCK(drawable);  
  }

RefDpCtx Interfaces

Imported image(30x36)

The RefDpCtx classes include LI-1 and LI-3 functions; documentation on those functions is provided in Chapter 9, "Writing Loadable Interfaces". See the header files RefDpCtx.h, RefDpCtx2d.h, and RefDpCtx3d.h for a complete list of RefDpCtx interfaces.
The following functions are unique to RefDpCtx and its subclasses.
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 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.
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.
void setZbufferPixRect(XglPixRect* z)

  Sets the PixRect that represents the Z-buffer to hold Z values.

void setAccumBufferPixRect(XglPixRect* a)
Used by copy buffer during the accumulation operation.

3D Utilities

XGL utilities for 3D operations are in the header file Utils3d.h.

XgliUtAccumulate 

void XgliUtAccumulate(
   const XglPixRectMem*      src_buf,
   const Xgl_bounds_i2d* rect,
   float                     src_wt,
   float                     dst_wt,
   XglPixRectMem*            dst_buf,
   const Xgl_pt_i2d*         dst_pos)
Accumulates from the source buffer src_buf to the destination buffer dst_buf. rect and src_wt apply to the source buffer. pos and dst_wt apply to the destination buffer.
Input Parameters src_buf
The source buffer used in the accumulation operation. The source buffer should be a 32-bit pixrect.
rectThe rectangle in the source buffer that needs to be accumulated.
src_wtThe source weight in the accumulation operation.
dst_wtThe destination weight in the accumulation operation.
dst_pos.....The position in the destination buffer to be used as starting position.
Output Parameter dst_buf
The destination buffer in the accumulation operation. The destination buffer is either a 32-bit or 48-bit Pixrect.

XgliUtCdAnnCircleApprox 

Xgl_sgn32 XgliUtCdAnnCircleApprox(
   XglContext3d          *ctx,
   XglConicList3d        *circle_list)
Evaluates the number of points to be used to approximate an annotation circle when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is one of the following:
XGL_CURVE_METRIC_WC
XGL_CURVE_METRIC_VDC
XGL_CURVE_METRIC_DC
XGL_CURVE_CHORDAL_DEVIATION_WC
XGL_CURVE_CHORDAL_DEVIATION_VDC
XGL_CURVE_CHORDAL_DEVIATION_DC
Input Parameters ctx
Pointer to a 3D Context.
circle_list....Pointer to an XglConicList3d object containing a list of circles or circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an annotation circle.

XgliUtAnnCircleApprox 

Xgl_sgn32 XgliUtAnnCircleApprox(
   XglContext3d          *ctx,
   Xgl_circle_list       *circle_list)
See XgliUtCdAnnCircleApprox for a description of the functionality.
Input Parameters ctx
Pointer to a 3D Context.
circle_list....Pointer to a list of circles.
Output Parameter None
Return Value Returns the number of points to be used to approximate an annotation circle.

XgliUtAnnArcApprox 

Xgl_sgn32 XgliUtAnnArcApprox(
   XglContext3d          *ctx,
   Xgl_arc_list          *arc_list)
See XgliUtAnnArcApprox for a description of the functionality.
Input Parameters ctx
Pointer to a 3D Context.
arc_list.....Pointer to a list of arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an annotation arc.

XgliUtCdAnnEllArcApprox 

Xgl_sgn32 XgliUtCdAnnEllArcApprox(
   XglContext3d          *ctx,
   XglConicList3d        *ell_list)
Evaluates the number of points to be used to approximate an annotation ellipse when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is one of the following:
XGL_CURVE_METRIC_WC
XGL_CURVE_METRIC_VDC
XGL_CURVE_METRIC_DC
XGL_CURVE_CHORDAL_DEVIATION_WC
XGL_CURVE_CHORDAL_DEVIATION_VDC
XGL_CURVE_CHORDAL_DEVIATION_DC
Input Parameters ctx
Pointer to a 3D context.
ell_list.....Pointer to an XglConicList3d object containing a list of elliptical arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an annotation ellipse.

XgliUtAnnEllArcApprox 

Xgl_sgn32 XgliUtAnnEllArcApprox(
   XglContext3d          *ctx,
   Xgl_ell_list          *ell_list)
See XgliUtAnnEllArcApprox for a description of the functionality.
Input Parameters ctx
Pointer to a 3D context.
ell_list.....Pointer to a list of ellipses.
Output Parameter None
Return Value Returns the number of points to be used to approximate an annotation ellipse.

XgliUtCalcDcueIndex 

void XgliUtCalcDcueIndex(
   XglContext3d*          ctx3d,
   XglViewGrp3dItf*       view_itf,
   Xgl_color*             color_in,
   float                  z,
   Xgl_color*             color_out)
Used when the color type is XGL_COLOR_INDEX and thus expects colors in the INDEX format. The function depth cues a input color color_in given the Z (in DC) value at which to depth cue the color.
Input Parameters ctx3d
The Context used in rendering the primitive.
view_itfThe view group interface from which the depth cue planes in DC and the DC viewport is used in calculating the depth cue color.
color_inThe color to be depth cued
zThe Z value (in DC) at which to depth cue.
Output Parameter color_out
The depth cued color

XgliUtCalcDcueRgb 

void XgliUtCalcDcueRgb(
   XglContext3d*          ctx3d,
   XglViewGrp3dItf*       view_itf,
   Xgl_color*             color_in,
   float                  z,
   Xgl_color*             color_out)
Used when the color type is XGL_COLOR_RGB and thus expects colors in the RGB format. The function depth cues a input color color_in given the Z (in DC) value at which to depth cue the color.
Input Parameters ctx3d
The Context used in rendering the primitive.
view_itfThe view group interface from which the depth cue planes in DC and the DC viewport is used in calculating the depth cue color.
color_inThe color to be depth cued.
zThe Z value in DC at which to depth cue.
Output Parameter color_out
The depth cued color

XgliUtCalcDoubleCircle 

     void XgliUtCalcDoubleCircle(
        float            *mem,
        Xgl_sgn32        n_steps,
        float            d_angle)
Calculates the points (x, y) on the unit circle which subdivides the unit circle into (n_steps - 1) segments. The calculated points (x,y) are stored twice in the array mem. The first copy of the points (x,y) is stored in:
(mem[0], mem[2*n_steps]), (mem[1], mem[2*n_steps+1]), ... ,
(mem[n_steps-2],mem[3*n_steps-2]),(mem[n_steps-1],mem[3*n_steps -1])
The second copy of the points is stored in:
(mem[n_steps], mem[3*n_steps]), (mem[n_steps+1], mem[3*n_steps+1]),... ,
(mem[2*n_steps-2], mem[4*n_steps-2]), (mem[2*n_steps-1], mem[4*n_steps-1])
Input Parameters n_steps
An integer indicating that the unit circle is subdivided into (n_steps - 1) segments.
d_angle.....The angle in radian formed by two consecutive subdivision points on the unit circle with the center of the unit circle.
Output Parameter mem
An array of floats allocated by the caller. The size of the array is 4*n_steps. This array will hold the points calculated by this utility.

XgliUtCalcLightingCompRgb 

void  XgliUtCalcLightingCompRgb(
    XglContext3d*                 ctx,
    XglViewGrp3dItf*              view_itf,
    Xgl_pt_f3d*                   normal,
    Xgl_pt_f3d*                   point,
    const Xgli_surf_attr_3d* surf,
    Xgl_boolean                   front_flag,
    Xgl_color*                    comp_A,
    Xgl_color*                    comp_B)
This routine takes an input point and normal and calculates the two color components necessary for texture mapping at that point. Consult the texture mapping documentation for more details regarding the color components and their use. This routine can only be used if the XGL color type is
XGL_COLOR_RGB.
Input Parameters ctx
Context containing light sources and lighting parameters.
view_itf.....View group interface used to obtain transformed light positions/directions.
normalInput facet or vertex normal (depending on whether the illumination is per_vertex, or per_facet, respectively).
pointInput 3D point.
surfSurface attributes, either front or back.
front_flagFlag indicating whether the normal is front facing.
Output Parameters comp_A; comp_B
Lighting components to be used during scan conversion by the texture mapping code. comp_A is the color scale factor, while comp_B is the offset.

XgliUtCalcLightingRgb and XgliUtCalcLightingIndex 

void  XgliUtCalcLighting{Rgb,Index}(
    XglContext3d*                 ctx,
    XglViewGrp3dItf*              view_itf,
    Xgl_color*                    color_in,
    Xgl_pt_f3d*                   normal,
    Xgl_pt_f3d*                   point,
    const Xgli_surf_attr_3d* surf,
    Xgl_boolean                   front_flag,
    Xgl_color*                    color_out)
These routines apply the current light sources and lighting parameters to the input color, normal, and 3D point and returns a new, calculated color. XgliUtCalcLightingRgb can only be used if the XGL color type is XGL_COLOR_RGB. The corresponding utility XgliUtCalcLightingIndex is used in the case of XGL_COLOR_INDEX.
Input Parameters ctx
XGL Context containing light sources and lighting parameters.
view_itfView group interface used to obtain transformed light positions/directions.
color_inInput color.
normalInput facet or vertex normal (depending on whether the illumination is per_vertex, or per_facet, respectively).
pointInput 3D point.
surfSurface attributes, either front or back.
front_flagFlag indicating whether the normal is front facing.
Output Parameter color_out
The output color, adjusted for the Context lighting values.

XgliUtCalcSingleCircle 

void XgliUtCalcSingleCircle(
    float                     *mem,
    Xgl_sgn32                 n_steps)
Calculates the points (x,y) on the unit circle which subdivides the unit circle into (n_steps - 1) equal segments. The calculated points (x,y) are stored in the array mem in the following way:
(mem[0], mem[n_steps]), (mem[1], mem[n_steps+1]), ...,
(mem[n_steps-2],mem[2*n_steps-2]),(mem[n_steps-1],mem[2*n_steps-1])
Input Parameters n_steps
An integer indicating that the unit circle is subdivided into (n_steps - 1) segments.
Output Parameter mem
An array of floats allocated by the caller. The size of the array is 2*n_steps. This array will hold the points calculated by this utility.

XgliUtCalcTexturedColor 

void XgliUtCalcTexturedColor(
    XglContext3d*                 ctx,
    const XgliUvSpanInfo3d*       data_info,
    Xgl_color*                    obj_clr,
    Xgl_boolean                   do_lighting,
    Xgl_usgn32                    z,
    Xgl_color*                    color_out)
Applies the texture maps in the current ctx. does lighting and depth cueing and returns the textured pixel. The caller passes as input the texture coordinate (u, v) of the pixel and the lighting components at the pixel (these are encapsulated in data_info). Thus, this utility does texture lookup and interpolation based on the (u, v) value, followed by color composition of the texel with the object color obj_clr to obtain the textured color. It also does lighting and depth cueing if applicable.
Input Parameters ctx
Context whose textures are applied.
data_infoContains the texture coordinate (u, v) (before the divide by 1/w) as well as the lighting components at that pixel.
obj_clrPixel color before the texturing operation. This is the intrinsic color of the pixel.
do_lightingIf TRUE, lighting is performed.
zZ value in DC of the pixel, used when performing depth cueing.
Output Parameter color_out
The output color after textures have been applied and lighting and depth cueing have been performed.

XgliUtCalc3dTriOrientation 

int XgliUtCalc3dTriOrientation(
   Xgl_pt_f3d*           v1,
   Xgl_pt_f3d*           v2,
   Xgl_pt_f3d*           v3,
   Xgl_pt_f3d*           fn)
Provides the winding of the points of a triangle given its three vertices and the facet normal.
Input Parameters v1
Coordinates of vertex 1.
v2Coordinates of vertex 2.
v3Coordinates of vertex 3.
fnFacet normal of the face.
Output Parameter None.
Return Value Returns the orientation, which can be either XGLI_PGON_ORIENT_CW or XGLI_PGON_ORIENT_CCW.

XgliUtComputeColorComp 

void XgliUtComputeColorComp(
   Xgli_acolor*              tex_clr,
   Xgl_color*                obj_clr,
   Xgl_texture_desc*         tex_desc,
   Xgl_color*                out_clr)
Takes an incoming color obj_clr and combines it with the texel tex_clr in a manner described in the tex_desc. The result of this color composing is returned in out_clr.
Input Parameters tex_clr
The texel value that should be used in color composition.
obj_clrThe object color that should be combined with the texel.
tex_descThe texture descriptor that contains the color composition method to use.
Output Parameter out_clr
The output color after color composition.

XgliUtComputeColorInterp 

void XgliUtComputeColorInterp(
   Xgli_pt_uv_info*          pdata,
   Xgl_texture_desc*         tex_desc,
   Xgli_acolor*              texel)
Takes as input the texture coordinate (u, v) and the MipMap level (in which this pixel is located) encapsulated in pdata and the texture descriptor tex_desc that should be used to do the texture lookup and interpolation to obtain the texture value.
Input Parameters pdata
Contains the texture coordinate (u, v) and the MipMap level of the pixel.
tex_desc.....The texture descriptor that should be used for lookup and interpolation.
Output Parameter texel
The output color after applying lookup and interpolation. Note that the type is Xgli_acolor, thus the returned value will have an alpha value as well.

XgliUtComputeDiffuseColor 

void XgliUtComputeDiffuseColor(
   Xgli_pixel_data_info* pdata,
   Xgl_color*                in_clr,
   Xgl_color*                out_clr)
Takes the intrinsic color in_clr and applies the texture maps that apply to the diffuse component. This involves texture lookup and interpolation to obtain the texture value, composing the in_clr with the texture color to obtain the out_clr.
Input Parameters pdata
This structure contains the texture maps that are active and the associated texture coordinates (u, v).
in_clr......Pixel color before the texturing operation. This is the intrinsic color of the pixel.
Output Parameter out_clr
The output color (diffuse color) after applying the textures that affect the diffuse component of the rendering pipeline.

XgliUtComputeFinalColor 

void XgliUtComputeFinalColor(
   Xgli_pixel_data_info* pdata,
   Xgl_color*                in_clr,
   Xgl_color*                out_clr)
Takes the depth cued color in_clr and applies the texture maps that apply to the final (after depth cueing) component. This involves texture lookup and interpolation to obtain the texture value, composing the in_clr with the texture color to obtain the out_clr.
Input Parameters pdata
Contains the texture maps that are active and the associated texture coordinates (u, v).
in_clr......Pixel color before the texturing operation. This is the depth cued color of the pixel.
Output Parameter out_clr
The output color after applying the textures that affect the final component of the rendering pipeline.

XgliUtComputeFn 

int XgliUtComputeFn(
   Xgl_operator          op,
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_usgn32            row_dim,
   Xgl_usgn32            col_dim,
   Xgl_usgn32            num_pt_lists,
   Xgl_pt_list*          pl,
   Xgl_pt_f3d*           facet_normal)
Computes the facet normal and returns the normals. For surfaces other than quadmesh, the row_dim and col_dim are ignored. The utility provides the option for normalizing.
Input Parameters op
Type of operator
geom_normalGeometry normal format as defined by the API attribute
XGL_3D_CTX_SURF_GEOM_NORMAL.
normalizeIf TRUE, normalizes the normal.
row_dimNumber of rows when op is XGL_OP_XGL_QUADRILATERAL_MESH. This parameter is ignored for other ops.
col_dimNumber of columns when op is XGL_OP_XGL_QUADRILATERAL_MESH. This parameter is ignored for other ops.
num_pt_listsNumber of point lists in pl. For triangle strip and quadmesh, num_pt_lists is assumed to be 1, so its value is ignored.
plGeometry information describing the primitive.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated by the caller depends on the primitive:
Multisimple polygon = num_pt_lists * 
sizeof(Xgl_pt_f3d)
Triangle strip = (pl[0].num_pts - 2) 
*sizeof(Xgl_pt_f3d)
Quadmesh = (row_dim - 1)*(col_dim-1) * 
sizeof(Xgl_pt_f3d)
Polygon = sizeof(Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeFnReverse 

int  XgliUtComputeFnReverse(
   Xgl_facet_list*       fl,
   Xgl_usgn32            num_facets,
   Xgl_pt_f3d*           fn)
Reverses the facet normals using the normals in fl.
Input Parameters fl
Input from which the facet normals should be reversed.
num_facets Number of facets or number of facet normals.
Output Parameter fn
Caller allocated structure in which to return the facet normals. The memory to be allocated is: num_facets * sizeof (Xgl_pt_f3d)
Return Value Returns a 1 if the function is successful; otherwise, returns a 0.

XgliUtComputeIndepTriFn 

int XgliUtComputeIndepTriFn(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_pt_list*          pl,
   Xgl_pt_f3d*           facet_normal)
Computes the normal for the facets in a set of independent triangles (a subset of the triangle list primitive) from the point list and returns the computed normals.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL 
normalize           If TRUE, normalizes the normal.
pl                  Data from which the normal should be calculated.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: (pl[0].num_pts - 2) * sizeof (Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeIndepTriFnPl 

int XgliUtComputeIndepTriFnPl(
   Xgl_geom_normal     geom_normal,
   Xgl_boolean         normalize,
   Xgl_pt_list*        pl,
   Xgl_tlist_flags     tlist_flags,
   Xgl_pt_f3d*         facet_normal)
Computes the normal for the facets in a set of independent triangles (a subset of the triangle list primitive) from an input point list provided by the user and returns the computed normals.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL.
normalize           If TRUE, normalizes the normal.
pl                  Vertex data.
tlist_flags          Global triangle list flags which were passed into the
                    xgl_triangle_list() primitive.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: (pl[0].num_pts - 2) * sizeof (Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeMspFn 

int XgliUtComputeMspFn(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_usgn32            num_pt_lists,
   Xgl_pt_list*          point_list,
   Xgl_pt_f3d*           facet_normal)
Computes the normals of the simple polygon in a multisimple polygon call from the point_list and returns the computed normal.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL.
normalize           If TRUE, normalizes the normal.
num_pt_lists        Number of point lists in point_list.
point_list          Data from which the normal should be calculated.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: num_pt_lists * sizeof (Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputePolygonFn 

int XgliUtComputePolygonFn(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_usgn32            num_pt_lists,
   Xgl_pt_list*          point_list,
   Xgl_pt_f3d*           facet_normal)
Computes the normal for the polygon from the point list. The first non-degenerate boundary of the polygon is used in the normal computation.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL 
normalize           If TRUE, normalizes the normal.
num_pt_lists        Number of point lists in point_list.
point_list          Data from which the normal is calculated.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is
sizeof (Xgl_pt_f3d).
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeQuadMeshFn 

int XgliUtComputeQuadMeshFn(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_usgn32            row_dim,
   Xgl_usgn32            col_dim,
   Xgl_pt_list*          point_list,
   Xgl_pt_f3d*           facet_normal)
Computes the normal for the facets in the quadrilateral mesh from the point data in point_list and returns the computed normals.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL. 
normalize           If TRUE, normalizes the normal
point_list          Data from which the normal is calculated.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: (row_dim - 1) * (col_dim - 1) * sizeof(Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeReflectedColor 

void XgliUtComputeReflectedColor(
   Xgli_pixel_data_info* pdata,
   Xgl_color*                in_clr,
   Xgl_color*                out_clr)
Takes the diffuse color in_clr and applies the texture maps that apply to the reflected component (after lighting). Applying the texture maps involves texture lookup and interpolation to obtain the texture value, composing the in_clr with the texture color to obtain the out_clr.
Input Parameters pdata
Contains the texture maps that are active and the associated texture coordinates (u, v).
in_clr......Pixel color before the texturing operation. This is the lit color of the pixel.
Output Parameter out_clr
The output color after applying the textures that affect the reflected component of the rendering pipeline.

XgliUtComputeTstripFn 

int XgliUtComputeTstripFn(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_pt_list*          point_list,
   Xgl_pt_f3d*           facet_normal)
Computes the normal for the facets in the triangle strip.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL 
normalize           If TRUE, normalizes the normal.
point_list          Data from which the normal is calculated.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: (pl[0].num_pts - 2) * sizeof (Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeTstripFnPl 

int XgliUtComputeTstripFnPl(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_pt_list*          point_list,
   Xgl_tlist_flags       tlist_flags,
   Xgl_pt_f3d*           facet_normal)
Computes the normal for the facets in a triangle strip from an input point list and returns the computed normals.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL 
normalize           If TRUE, normalizes the normal.
point_list          Vertex data.
tlist_flags          Global triangle list flags that were passed into the
                    xgl_triangle_list() primitive.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: (pl[0].num_pts - 2) * sizeof (Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeTstarFn 

int XgliUtComputeTstarFn(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_pt_list*          point_list,
   Xgl_pt_f3d*           facet_normal)
Computes the normal for the facets in the triangle star from the point_list and returns the computed normals.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL 
normalize           If TRUE, normalizes the normal.
point_list          Data from which the normal is calculated.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: (pl[0].num_pts - 2) * sizeof(Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeTstarFnPl 

int XgliUtComputeTstarFnPl(
   Xgl_geom_normal       geom_normal,
   Xgl_boolean           normalize,
   Xgl_pt_list*          point_list,
   Xgl_pt_list*          saved_pl,
   Xgl_tlist_flags       tlist_flags,
   Xgl_pt_f3d*           facet_normal)
Computes the normal for the facets in a triangle star (a subset of the triangle list primitive) from two input point lists provided by the user and returns the computed normals. Two input point lists are necessary in case the triangle star
vertex data is non-contiguous. The first vertex in the saved_pl point list points to the first vertex in the triangle star. All other vertices in the triangle star are in point_list beginning with the second location in point_list.
Input Parameters geom_normal
Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL.
normalize           If TRUE, normalizes the normal.
point_list          Vertex data for the second point through the last points in
                    the triangle star.
saved_pl            Vertex data for the first point in the triangle star.
tlist_flags          Global triangle list flags that were passed into the
                    xgl_triangle_list() primitive.
Output Parameter facet_normal
Caller allocated structure in which to return the computed normals. The memory to be allocated is: (pl[0].num_pts - 2) * sizeof (Xgl_pt_f3d)
Return Value Returns a 1 if the normal was computed successfully; otherwise, returns a 0.

XgliUtComputeVnReverse 

int XgliUtComputeVnReverse(
   Xgl_usgn32            num_pt_lists,
   Xgl_pt_list*          point_list,
   Xgl_pt_f3d*           vn)
This utility reverses the vertex normals in point_list.
Input Parameters num_pt_lists
Number of point lists in point_list.
point_list....Input from which the vertex normals should be reversed. .
Output Parameter vn
Caller allocated structure in which to return the reversed vertex normals. The memory to be allocated is:
tot_num_pts * sizeof(Xgl_pt_f3d)
where tot_num_pts is initially zero and for each point in the list tot_num_pts += pl[i].num_pts
Return Value Returns a 1 if the function is successful; otherwise, returns a 0.

XgliUtComputeZTolerance 

void XgliUtComputeZTolerance(
   const Xgli_point_list*         pl,
   float*                         z_offset)
Computes the z_offset using the input point list pl. Used either when drawing edges or when the API attribute XGL_3D_CTX_SURF_DC_OFFSET is TRUE. The output value is added to the Z values of the points when drawing edges so that edges appear on top of the rendered surface. This value is also subtracted from the points of a surface primitive if the API attribute
XGL_3D_CTX_SURF_DC_OFFSET is TRUE.
Input Parameters pl
Point list from which to calculate the Z offset.
Output Parameter z_offset
The value of the computed Z offset.

XgliUtCdDcCircleApprox 

Xgl_sgn32 XgliUtCdDcCircleApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   XglConicList3d        *circle_list)
Evaluates the number of points to be used to approximate a circle when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is XGL_CURVE_METRIC_DC or XGL_CURVE_CHORDAL_DEVIATION_DC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
circle_listPointer to an XglConicList3d object containing a list of circles or circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate a circle.

XgliUtDcCircleApprox 

Xgl_sgn32 XgliUtDcCircleApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_circle_list       *circle_list)
Evaluates the number of points to be used to approximate a circle when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_DC or XGL_CURVE_CHORDAL_DEVIATION_DC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
circle_listPointer to a list of circles or circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate a circle.

XgliUtDcArcApprox 

Xgl_sgn32 XgliUtDcArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_arc_list          *arc_list)
Evaluates the number of points to be used to approximate an arc when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_DC or XGL_CURVE_CHORDAL_DEVIATION_DC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
arc_listPointer to a list of circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an arc.

XgliUtCdDcEllArcApprox 

Xgl_sgn32 XgliUtCdDcEllArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   XglConicList3d        *ell_list)
Evaluates the number of points to be used to approximate an ellipse when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_DC or XGL_CURVE_CHORDAL_DEVIATION_DC.
Input Parameters ctx
Pointer to a 3D context.
viewGrpItfPointer to a 3D view group interface.
ell_listPointer to an XglConicList3d object containing a list of elliptical arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an ellipse.

XgliUtDcEllArcApprox 

Xgl_sgn32 XgliUtDcEllArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_ell_list          *ell_list)
Evaluates the number of points to be used to approximate an ellipse when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_DC or XGL_CURVE_CHORDAL_DEVIATION_DC.
Input Parameters ctx
Pointer to a 3D context.
viewGrpItfPointer to a 3D view group interface.
ell_listPointer to a list of elliptical arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an ellipse.

XgliUtFaceDistinguish 

const Xgli_surf_attr_3d*  XgliUtFaceDistinguish(
   XglContext3d*             ctx,
   Xgl_pt_f3d*               normal,
   Xgl_pt_f3d*               pt,
   XglViewGrp3dItf*          view_itf)
Identifies a face to be either front-facing or back-facing.
Input Parameters ctx
Context used in rendering the primitive.
normalThe facet normal of the face that is being distinguished.
ptA point on the face that is being distinguished.
view_itfThe view group from which the eye vector is used in determining front versus back facing.
Output Parameter None
Return Value Returns either the front or back face attributes as a pointer to the Xgli_surf_attr_3d structure.

XgliUtGetZCompFunc 

void XgliUtGetZCompFunc(
   Xgl_z_comp_method         method,
   Xgl_boolean               (**func)(Xgl_usgn32, Xgl_usgn32))

Returns the Z-comparision function func based on the Z-comparision method.
Input Parameter method
Z-comparison method for the function.
Output Parameter func
The Z-comparison function.

XgliUtIsScreenDoor 

Xgl_boolean XgliUtIsScreenDoorTransparent(
   XglContext3d *        ctx,
   Xgl_boolean           front)
Determines whether a surface is screen door transparent; ignores the blending attributes.
Input Parameters ctx
Context from which attributes are obtained.
front......If front is TRUE, the surface front attributes are checked; otherwise, the back attributes are checked.
Output Parameter None
Return Value Returns TRUE if the surface is transparent and FALSE otherwise.

XgliUtIsScreenDoorTransparent 

Xgl_boolean XgliUtIsScreenDoorTransparent(
   XglContext3d *        ctx,
   Xgl_boolean           front)
Determines whether the surface has blended transparency.
Input Parameters ctx
Context from which attributes are obtained.
front......If front is TRUE, the surface front attributes are checked; otherwise, the back attributes are checked.
Output Parameter None
Return Value Returns TRUE if the surface is transparent and FALSE otherwise.

XgliUtIsTransparent 

Xgl_boolean XgliUtIsTransparent(
   XglContext3d *        ctx,
   Xgl_boolean           front)
Determines whether a surface is transparent.
Input Parameters ctx

Context from which the attributes are obtained.

front......If front is TRUE, the surface front attributes are checked; otherwise, the back attributes are checked.
Output Parameter None
Return Value Returns TRUE if the surface is transparent and FALSE otherwise.

XgliUtIsTransparent 

Xgl_boolean XgliUtIsTransparent(
   float                 transparency,
   Xgl_transp_method transp_method,
   Xgl_blend_eq          blend_eq)
This function is similar to the other XgliUtIsTransparent utility except that it gets the API transparency attributes as arguments to the function.
Input Parameters transparency

Value of the attribute XGL_3D_CTX_FRONT_TRANSP or XGL_3D_CTX_BACK_TRANSP. If face distinguishing is FALSE, then transparency is front.

transp_methodValue of XGL_3D_CTX_SURF_TRANSP_METHOD.
blend_eqValue of XGL_3D_CTX_SURF_TRANSP_BLEND_EQ.
Output Parameter None
Return Value Returns TRUE if the surface is transparent and FALSE otherwise.

XgliUtMeanWg 

void XgliUtMeanWg(
   Xgli_acolor*          vector,
   Xgl_usgn32            siz,
   float*                wg,
   Xgl_usgn32            num_channel,
   Xgli_acolor*          out_clr)
Accumulates the result of the product of the individual fields of vector array with the corresponding entries in the wg array for as many entries as given by siz. The number of channels in the vector array (and therefore in the out_clr) is specified by num_channel.
Input Parameters vector
The vector array that is weighted and accumulated.
sizNumber of entries in the vector array.
wgThe weights by which the vector array should be multiplied.
num_channelNumber of channels of useful information (maximum of 4) in the vector array.
Output Parameter out_clr
Output color.

XgliUtMellaToPline 

Xgl_sgn32 XgliUtMellaToPline(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_ell_list          *ell_list,
   Xgl_pt_list           **point_list,
   Xgl_facet_list        **facet_list)
Tessellates the 3D multielliptical arcs stored in ell_list.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
ell_listPoint lists of the tessellated elliptical arcs. Any space that is required for the point lists is allocated by this routine.Pointer to a list of elliptical arcs.
facet_listFacet list of the tessellated elliptical arcs. Any space that is required for the facet list is allocated by this routine. The value of *facet_list on return will always be NULL if XGL_CTX_ARC_FILL_STYLE is XGL_ARC_OPEN.
Return Value Returns 1 if the elliptical arcs are successfully tessellated; otherwise, returns 0.

XgliUtModelClipMarker 

Xgl_sgn32  XgliUtModelClipMarker(
   XglContext3d*          ctx,
   XglViewGrp3dItf*      view_grp,
   Xgl_pt_list*          pl_in,
   Xgl_pt_list**         pl_out)
Takes a single point list stored in pl_in and model clips the points against the current model clipping planes. Note that only the center points of the markers are clipped - the individual marker shapes themselves are not.
Input Parameters ctx
Context from which attributes are obtained.
view_itfView group from which model clip planes are obtained.
pl_inInput point list. This argument is the point list passed to 
                    li1MultiPolyline().
Output Parameter pl_out
List of points containing only those that are within the clipping planes.
Return Value Returns the number of points in the output list. It is the responsibility of the caller to free the memory that this routine allocates to hold the clipped points.

XgliUtModelClipMpline 

Xgl_sgn32  XgliUtModelClipMpline(
   XglContext3d*             ctx,
   XglViewGrp3dItf*          view_itf,
   Xgl_usgn32                num_plines,
   Xgl_pt_list*              pl_in,
   Xgl_pt_list**             pl_out)
Model clips a list of polylines against the current model clipping planes.
Input Parameters ctx
Context from which attributes are obtained.
view_itfView group from which model clip planes are obtained.
num_plinesNumber of point lists in pl_in.
pl_inInput point lists. This argument is the point list passed to 
                    li1MultiPolyline().
Output Parameter pl_out
Clipped output polyline(s). Any space that is required for the polylines is allocated by this routine. It is the responsibility of the caller to free any memory allocated by this routine.
Return Value Returns the number of point lists in the output. A return value of 0 indicates that the entire multipolyline was trivially rejected.

XgliUtModelClipMspg 

Xgl_sgn32 XgliUtModelClipMspg(
   XglContext3d*          ctx,
   XglViewGrp3dItf*       view_grp,
   Xgl_sgn32             num_pl,
   Xgl_pt_list*          pl_in,
   Xgl_pt_list**         pl_out,
   Xgl_facet_list*       fl_in,
   Xgl_facet_list**      fl_clipped)
This function is used to model clip lists of individual polygons, such as might be specified by a call to xgl_multi_simple_polygon(). The function handles multiple facets correctly, removing from the output list those that correspond to polygons that are trivially rejected.
Input Parameters ctx
Context from which attributes are obtained.
view_itfView group from which model clip planes are obtained.
num_plNumber of point lists in pl_in.
pl_inInput point lists. This argument is the point list passed to li1MultiPolyline().
fl_inA list of point lists defining the clipped polygon.Input facet list.
fl_clippedFacet list for the clipped polygon.
Return Value Returns the number of clipped bounds. The number of output bounds is always less than or equal to the number of input bounds - extra point lists are not introduced. The caller must free any memory allocated by this routine.

XgliUtModelClipPgon 

Xgl_sgn32 XgliUtModelClipPgon(
   XglContext3d*          ctx,
   XglViewGrp3dItf*       view_grp,
   Xgl_sgn32             num_pl,
   Xgl_pl_list*          pl_in,
   Xgl_pl_list**         pl_out)
Model-clips an optionally multi-bounded polygon specified as a list of point lists in the pl_in structure, against the current model clipping planes.
Note - This function is only appropriate for individual polygons. If more than one point list is passed in then it is assumed that the polygon is multi-bounded. Calling this routine with multi, separate bounded polygons may result in incorrect data.
Input Parameters ctx
Context from which attributes are obtained.
view_itfView group from which model clip planes are obtained.
num_plNumber of point lists in pl_in.
pl_inInput point lists. This argument is the point list passed to 
                    li1MultiPolyline().
Output Parameter pl_out
A list of point lists defining the clipped polygon.
Return Value Returns the number of clipped bounds. The number of output bounds is always less than or equal to the number of input bounds - extra point lists are not introduced. The caller must free any memory allocated by this routine.

XgliUtModelClipPoint 

Xgl_boolean  XgliUtModelClipPoint(
    XglContext3d*           ctx,
    XglViewGrp3dItf*        view_grp,
    Xgl_pt_f3d*             pt)
Model clips the 3D model-coordinate point pt against the current model clipping planes specified by the Context and the view group interface object.
Input Parameters ctx
Context from which attributes are obtained.
view_grpView group from which model clip planes are obtained.
ptPoint to be model clipped.
Output Parameter None
Return Value If the point is determined to be inside the clipping planes, then the function returns TRUE, otherwise it returns FALSE.

XgliUtModelClipTstrip 

Xgl_sgn32 XgliUtModelClipTstrip(
    XglContext3d*           ctx,
    XglViewGrp3dItf*        view_grp,
    Xgl_pt_list*            pl_in,
    Xgl_facet_list*         fl_in,
    Xgl_pt_list**           pl_out,
    Xgl_facet_list**        fl_out)
Takes as input a single point list, and optionally a facet list, and model clips them against the current model clipping planes. The output is a list of point lists defining triangle strips that may have been created by model clipping the original input list. In practice there is usually only one such list as the clipper makes every attempt to keep everything together in one piece by introducing degenerate triangles where appropriate to link strips together. It is not
impossible, however, for there to be more than one list under some circumstances, so applications that use this utility are advised to assume that there can multiple output strips.
Input Parameters ctx
Context from which attributes are obtained.
view_itfView group from which model clip planes are obtained.
pl_inInput point list. This argument is the point list passed to li1MultiPolyline().
fl_inA list of point lists defining triangle strips that may have been created by model clipping the original input list.Input facet list.
fl_outFacet list for pl_out.
Return Value Returns the number of triangle strips in the clipped output. The caller must free any memory allocated by this routine.

XgliUtPixRect48to32 

void XgliUtPixRect48to32(
   XglPixRectMem*            dst_buf,
   const Xgl_bounds_i2d* rect,
   const XglPixRectMem*      src_buf,
   const Xgl_pt_i2d*         pos)
Copies a region of a 48-bit PixRect src_buf to a 32-bit PixRect dst_buf. The function is designed to do the copy-back of the accumulation buffer to an image buffer. rect applies to the source buffer and pos to the destination buffer.
Input Parameters src_buf
The source buffer used in the copy operation. The source buffer should be a 48-bit pixrect.
rect.......The rectangle in the source buffer that should be copied.
pos.......The position in the destination buffer to be used as starting position.
Output Parameter dst_buf
The destination buffer in the copy operation. The destination buffer is a 32-bit PixRect.

XgliUtVertexFrontFacing 

Xgl_boolean XgliUtVertexFrontFacing(
   Xgl_pt_f3d*            position,
   Xgl_pt_f3d*            normal,
   XglViewGrp3dItf*       viewGrp,
   Xgl_boolean            flipNormal)
Determines if a given vertex is front facing. See the XGL_3D_CTX_SURF_NORMAL_FLIP man page.
Input Parameters position
Vertex position in MC.
normalNormal at vertex
viewGrpView group interface object
flipNormalValue of the Context attribute XGL_3D_CTX_SURF_NORMAL_FLIP.
Output Parameter None
Return Value Returns TRUE if the vertex is front facing and FALSE otherwise.

XgliUtVertexOrientation 

Xgl_boolean XgliUtVertexOrientation(
   Xgl_pt_list*           pl,
   XglViewGrp3dItf*       viewGrp,
   Xgl_boolean*           vrtxFrontFacing,
   Xgl_boolean            flipNormal)
Determines, for each point in a given point list, if it is front or back facing. It also determines whether the point list contains a silhouette edge. See the XGL_3D_CTX_SURF_NORMAL_FLIP man page.
Input Parameters pl
Point list
viewGrpView group interface object
flipNormalContext attribute XGL_3D_CTX_SURF_NORMAL_FLIP
Output Parameter vrtxFrontFacing
For each array index i, TRUE if point i of the point list is front facing and FALSE if it is back facing.
Return Value Returns TRUE if the point list contains a silhouette edge and FALSE otherwise.

XgliUtCdVdcCircleApprox 

Xgl_sgn32 XgliUtCdVdcCircleApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   XglConicList3d        *circle_list)
Evaluates the number of points to be used to approximate a circle when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_VDC or XGL_CURVE_CHORDAL_DEVIATION_VDC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItf...Pointer to a 3D view group interface.
circle_list....Pointer to an XglConicList3d object containing a list of circles or circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate a circle.

XgliUtVdcCircleApprox 

Xgl_sgn32 XgliUtVdcCircleApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_circle_list       *circle_list)
Evaluates the number of points to be used to approximate a circle when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_VDC or XGL_CURVE_CHORDAL_DEVIATION_VDC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
circle_listPointer to a list of circles.
Output Parameter None
Return Value Returns the number of points to be used to approximate a circle.

XgliUtVdcArcApprox 

Xgl_sgn32 XgliUtVdcArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_arc_list          *arc_list)
Evaluates the number of points to be used to approximate an arc when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_VDC or XGL_CURVE_CHORDAL_DEVIATION_VDC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
arc_listPointer to a list of circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an arc.

XgliUtCdVdcEllArcApprox 

Xgl_sgn32 XgliUtCdVdcEllArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   XglConicList3d        *ell_list)
Evaluates the number of points to be used to approximate an ellipse when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_VDC or XGL_CURVE_CHORDAL_DEVIATION_VDC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
ell_listPointer to an XglConicList3d object containing a list of elliptical arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an ellipse.

XgliUtVdcEllArcApprox 

Xgl_sgn32 XgliUtVdcEllArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_ell_list          *ell_list)
Evaluates the number of points to be used to approximate an ellipse when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_VDC or XGL_CURVE_CHORDAL_DEVIATION_VDC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
ell_listPointer to a list of elliptical arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an ellipse.

XgliUtCdWcCircleApprox 

Xgl_sgn32 XgliUtCdWcCircleApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   XglConicList3d        *circle_list)
Evaluates the number of points to be used to approximate a circle when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is XGL_CURVE_METRIC_WC or XGL_CURVE_CHORDAL_DEVIATION_WC.
Input Parameters ctx
Pointer to a 3D context.
viewGrpItfPointer to a 3D view group interface.
circle_listPointer to an XglConicList3d object containing a list of circles or circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate a circle.

XgliUtWcCircleApprox 

Xgl_sgn32 XgliUtWcCircleApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_circle_list       *circle_list)
Evaluates the number of points to be used to approximate a circle when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_WC or XGL_CURVE_CHORDAL_DEVIATION_WC.
Input Parameters ctx
Pointer to a 3D context.
viewGrpItfPointer to a 3D view group interface.
circle_listPointer to a list of circles.
Output Parameter None
Return Value Returns the number of points to be used to approximate a circle.

XgliUtWcArcApprox 

Xgl_sgn32 XgliUtWcArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_arc_list          *arc_list)
Evaluates the number of points to be used to approximate an arc when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_WC or XGL_CURVE_CHORDAL_DEVIATION_WC.
Input Parameters ctx
Pointer to a 3D context.
viewGrpItfPointer to a 3D view group interface.
arc_listPointer to a list of circular arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an arc.

XgliUtCdWcEllArcApprox 

Xgl_sgn32 XgliUtCdWcEllArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   XglConicList3d        *ell_list)
Evaluates the number of points to be used to approximate an ellipse when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_WC or XGL_CURVE_CHORDAL_DEVIATION_WC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
ell_listPointer to an XglConicList3d object containing a list of elliptical arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an ellipse.

XgliUtWcEllArcApprox 

Xgl_sgn32 XgliUtWcEllArcApprox(
   XglContext3d          *ctx,
   XglViewGrp3dItf       *viewGrpItf,
   Xgl_ell_list          *ell_list)
Evaluates the number of points to be used to approximate an ellipse when the value of the attribute XGL_CTX_NURBS_CURVE_APPROX is
XGL_CURVE_METRIC_WC or XGL_CURVE_CHORDAL_DEVIATION_WC.
Input Parameters ctx
Pointer to a 3D Context.
viewGrpItfPointer to a 3D view group interface.
ell_listPointer to a list of elliptical arcs.
Output Parameter None
Return Value Returns the number of points to be used to approximate an ellipse.

Bounding Box Utilities

XGL utilities for checking for bounding boxes are in the file CheckBbox.h.

XgliUt2dCheckBbox 

Xgl_geom_status XgliUt2dCheckBbox(
   XglContext2d*         ctx,
   Xgl_primitive_type prim_type,
   Xgl_bbox*             bbox,
   XglViewGrp2dItf*      view_grp_itf)
Performs a bounding box check against the 2D clip volume and returns the geometry status of the bounding box. For more information, see the man page for xgl_context_check_bbox().
Input Parameters ctx
Pointer to a 2D Context.
prim_typeThe bounding box primitive type.
bboxPointer to a bounding box which can be an Xgl_bbox_i2d, Xgl_bbox_f2d, or Xgl_bbox_d2d structure.
view_grp_itfPointer to a 2D view group interface.
Output Parameter None
Return Value This utility returns a geometry status which is either XGL_GEOM_STATUS_VIEW_REJECT (outside the clipping volume) or 0 (clipped).

XgliUt3dCheckBbox 

Xgl_geom_status XgliUt3dCheckBbox(
   XglContext3d*             ctx,
   Xgl_primitive_type        prim_type,
   Xgl_bbox*                 bbox,
   XglViewGrp3dItf*          view_grp_itf)
Performs a bounding box check against the 3D clip volume and returns the geometry status of the bounding box. For more information, see the man page for xgl_context_check_bbox().
Input Parameters ctx
Pointer to a 3D Context.
prim_typeThe bounding box primitive type.
bboxPointer to a bounding box which can be an Xgl_bbox_f3d or Xgl_bbox_d3d structure.
view_grp_itfPointer to a 3D view group interface.
Output Parameter None
Return Value Returns a geometry status which is a combination of the following flags:
XGL_GEOM_STATUS_VIEW_ACCEPT
XGL_GEOM_STATUS_VIEW_REJECT
XGL_GEOM_STATUS_VIEW_SMALL
XGL_GEOM_STATUS_MODEL_ACCEPT
XGL_GEOM_STATUS_MODEL_REJECT

Copy Buffer Utilities

XGL utilities for copy buffer operations are in the file CopyBuffer.h.

XgliUtAdjustRectPos 

extern int XgliUtAdjustRectPos(
   XglRaster*            src_dev,
   Xgl_bounds_i2d*        src_rect,
   Xgl_bounds_i2d*        adj_src_rect,
   XglRaster*             dest_dev,
   Xgl_pt_i2d*            dest_pos,
   Xgl_pt_i2d*            adj_dest_pos);
Computes a new rectangle and position whose coordinates are valid as input to the XgliUtCopyBuffer utility. The new or adjusted rectangle and position are based upon the original rectangle and position and the size of the source and destination device.
Input Parameters src_dev
Source device.
src_rectSource rectangle in src_dev's coordinate space.
adj_src_rectAdjusted source rectangle; the new, valid rectangle.
dest_devDestination device.
dest_posDestination position in dest_dev's coordinate space.
adj_dest_posAdjusted destination position.
Output Parameter None
Return Value Returns 1 if successful or 0 if the input data is inconsistent.

XgliUtCopyBuffer 

extern int XgliUtCopyBuffer(
   XglPixRect*                    dest_pr,
   const Xgl_pt_i2d*              dest_pos,
   const Xgl_color*               dest_fg_color,
   const Xgl_color*               dest_bg_color,
   XglPixRectMem*                 dest_clip_mask,
   XglPixRect*                    src_pr,
   const Xgl_bounds_i2d*          src_rect,
   XglPixRectMem*                 src_clip_mask,
   Xgli_cb_color_info*            color_info,
   Xgli_cb_mask_and_rop_info*rop_info,
   Xgli_cb_fill_info*             fill_info,
   Xgli_cb_z_buffer_info*         z_buffer_info)
Implements the xgl_copy_buffer() function. It copies a rectangular block of pixels from a source raster to a destination raster and, in addition, may convert from one color type to another, clip, fill with a pattern, or perform the copy based upon Z-buffer values. The caller must ensure that the device is locked (in other words, call WIN_LOCK if necessary).
Input Parameters dest_pr
PixRect representing the destination raster.
dest_posDestination position.
dest_fg_colorForeground color from destination Context.
dest_bg_colorBackground color from destination Context.
dest_clip_maskPer-pixel clip mask represented as a PixRect for the destination.
src_prPixRect representing the source raster.
src_rectRectangle of pixels which get copied to destination.
src_clip_maskPer-pixel clip mask represented as a PixRect for the source.
color_infoColor info for source and destination raster; may be NULL if copy does not involve color.
rop_infoPlane mask and rop function; may be NULL if not doing ROP or masking.
fill_infoInformation from destination Context for filling with patterns or stipples; may be NULL if not using patterned fill.
z_buffer_infoInformation for copying from one Z-buffer to another; should be NULL if not copying Z-buffer data.
Output Parameter None
Return Value Returns 1 if the function succeeds or 0 for nonsuccess.

XgliUtFbToMemCopyBuffer 

int XgliUtFbToMemCopyBuffer(
   XglContext*           dest_ctx,
   Xgl_bounds_i2d*       rect,
   Xgl_pt_i2d*           pos,
   XglRaster*            src_dev,
   XglPixRect*           src_image_pr,
   XglPixRect*           src_zbuffer_pr,
   XglPixRectMem*        src_clip_mask);
A high-level utility that implements xgl_copy_buffer() when copying from a Device's frame buffer to a Memory Raster. This function calls XgliUtCopyBuffer(). The caller must ensure that the device is locked (in other words, WIN_LOCK is called if needed).
Input Parameters dest_ctx
Destination Context object
rectRectangle from API
posPosition from API
src_devSource device
src_image_prPixRect for source device's image buffer.
src_zbuffer_prPixRect for source device's Z buffer
src_clip_maskPixRect for source device's clip mask
Output Parameter None
Return Value Returns 1 if the function succeeds or 0 for nonsuccess.

XgliUtGetMaskAndRopFunc 

extern  void XgliUtGetMaskAndRopFunc(
   Xgl_rop_mode        rop,
   Xgl_usgn32 (**func)(Xgl_usgn32 s, Xgl_usgn32 d, Xgl_usgn32 p))

Returns a pointer to a function that implements the given ROP value.
Input Parameter rop
ROP mode that is implemented by the returned function.
Output Parameter func
Pointer to a function which returns the ROP'ed and masked pixel; it takes the following parameters: the source pixel s, the destination pixel, d, and the plane mask p.

Polygon Classification Utilities

XGL utilities for polygon classification are in the file PgonClass.h.

XgliUtClassifyMsp 

int XgliUtClassifyMsp(
   Xgl_usgn32                num_pt_lists
   Xgl_pt_list*              point_list
   Xgl_pt_f3d*               points
   Xgli_polygon_class*       pgon_class
Classifies polygons sent to the primitive xgl_multi_simple_polygon(). The classification consists of checking the number of points in each polygon and testing for convexity. The information obtained can be used to decrease rendering time. For example, if a classified polygon has the XGL_PGON_TRISTAR bit set then a triangle star renderer can be used rather than a generic polygon scan converter.
Input Parameters num_pt_lists
Number of point lists in point_list.
point_listPointer to the data to be classified.
pointsPointer to the polygon's facet normal list. This list must be of type XGL_FACET_NORMAL or XGL_FACET_COLOR_NORMAL. If calling with a 2D point list, this parameter is ignored.
Output Parameter pgon_class
A pointer to a bit vector. The bit vector must be allocated in the calling routine to num_pt_lists in size. The bit vector array is returned with at least one of the bits set. See the return value for XgliUtClassifyPgon for the possible values.
Return Value Returns 0 if the classification finished successfully and 1 if the classification was aborted. An attempt is made to classify a 3D multisimple polygon list without the facet normal list.

XgliUtClassifyPgon 

Xgli_polygon_class XgliUtClassifyPgon(
   Xgl_usgn32                num_pt_lists
   Xgl_pt_list*              pl
   Xgl_pt_f3d*               facet_normal)
Classifies polygons sent to the primitive xgl_polygon(). The classification consists of checking the number of points in the polygon, checking the number of bounds, and testing for convexity. The information obtained can be used to decrease rendering time. For example, if a classified polygon has the XGL_PGON_TRISTAR bit set, a triangle star renderer can be used rather than a generic polygon scan converter.
Input Parameters num_pt_lists

Number of point lists in pl.

plPointer to the data to be classified.
facet_normalPointer to the polygon's facet normal. This must point to a facet of type Xgl_normal_facet or Xgl_color_normal_facet. If calling with a 2D point list, this parameter is ignored.
Output Parameter None
Return Value Returns a bit vector with at least one of the following set:
  • XGL_PGON_DEGENERATE - The polygon has less than three points in its point list.
  • XGL_PGON_SIDES_ARE_3 - The polygon has three points in its point list. No testing is done for degenerate data.
  • XGL_PGON_SIDES_ARE_4 - The polygon has four points in its point list. No testing is done for degenerate or self-intersecting data.
  • XGL_PGON_SIDES_UNSPECIFIED - The polygon has more than four points in its point list. No testing is done for degenerate data nor for a self intersecting point list.
  • XGL_PGON_TRISTAR - The polygon can be rendered using a triangle star starting from the first vertex in the point list.
  • XGL_PGON_CONV_ONEBOUND - The polygon is convex (can be rendered as a triangle star from any vertex) and is single bounded (there are no holes in the polygon).
  • XGL_PGON_COMPLEX - No information was found about the polygon.

Polygon Decomposition Utilities

XGL provides utilities to decompose polygons into triangles in the file utils.h.

XgliUtDecomposePgon 

int XgliUtDecomposePgon(
   Xgl_facet_type         facet_type,
   Xgl_facet*             facet,
   Xgl_usgn32             num_in_pt_lists,
   Xgl_pt_list*           in_pl,
   Xgl_usgn32*            num_out_pt_lists,
   Xgl_pt_list**          out_pl,
   Xgl_color_type         color_type,
   Xgl_pt_f3d*            d_c_normal,
   Xgl_geom_normal        geom_normal_type,
   Xgl_boolean            normal_flip);
Decomposes one complex polygon facet into strips of triangle stars, which are returned via the output parameter out_pl. The utility allocates the memory for the output point lists of triangle stars, so it's the caller's responsibility to free the memory when the output point lists are no longer needed.
Input Parameters facet_type
Facet type of input polygon
facetFacet information
num_in_pt_listsNumber of point lists (i.e. bounds) in input polygon.
in_plArray of point lists for input polygon.
color_typeColor type (index or RGB).
d_c_normalNormalized facet normal of input polygon.
geom_normal_type Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL.
normal_flipSpecifies whether vertex and facet normals are flipped, as defined by the attribute
XGL_3D_CTX_SURF_NORMAL_FLIP.Number of output point lists of triangle stars.
out_plPointer to output point lists of triangle stars.
Return Value Returns 1 if the polygon is successfully decomposed and 0 if memory allocation fails.

XgliUtDecomposeNsiPgon 

int XgliUtDecomposeNsiPgon(
   Xgl_facet_type         facet_type,
   Xgl_facet*             facet,
   Xgl_usgn32             num_in_pt_lists,
   Xgl_pt_list*           in_pl,
   Xgl_usgn32*            num_out_pt_lists,
   Xgl_pt_list**          out_pl,
   Xgl_color_type         color_type,
   Xgl_pt_f3d*            d_c_normal,
   Xgl_geom_normal        geom_normal_type,
   Xgl_boolean            normal_flip);
Decomposes one non-self-intersecting polygon facet into strips of triangle stars, which are returned via the output parameter out_pl. The utility allocates the memory for the output point lists of triangle stars, so it's the caller's responsibility to free the memory when the output point lists are no longer needed.
Input Parameters facet_type
Facet type of input polygon.
facetFacet information.
num_in_pt_listsNumber of point lists (i.e. bounds) in input polygon.
in_plArray of point lists for input polygon.
color_typeColor type (index or RGB).
d_c_normalNormalized facet normal of input polygon.
geom_normal_type Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL.
normal_flipSpecifies whether vertex and facet normals are flipped, as defined by the API attribute
XGL_3D_CTX_SURF_NORMAL_FLIP.Number of output point lists of triangle stars.
out_plPointer to output point lists of triangle stars.
Return Value Returns 1 if the polygon is successfully decomposed and 0 if memory allocation fails.