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.

rect	The rectangle in the source buffer that needs to be accumulated.
src_wt	The source weight in the accumulation operation.
dst_wt	The 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 value (in DC) at which to depth cue the color.

Input Parameters ctx3d

The Context used in rendering the primitive.

view_itf	The view group interface from which the depth cue planes in DC and the DC viewport is used in calculating the depth cue color.
color_in	The color to be depth cued
z	The 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 value (in DC) at which to depth cue the color.

Input Parameters ctx3d

The Context used in rendering the primitive.

view_itf	The view group interface from which the depth cue planes in DC and the DC viewport is used in calculating the depth cue color.
color_in	The color to be depth cued.
z	The 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 that subdivide 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.

normal	Input facet or vertex normal (depending on whether the illumination is per_vertex, or per_facet, respectively).
point	Input 3D point.
surf	Surface attributes, either front or back.
front_flag	Flag 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; comp_B is the offset.

XgliUtCalcLighting Utilities

The XGL DDK provides a set of 34 utilities that apply light sources and lighting parameters to a 3D point or a list of 3D points and return a lit color or list of colors. The XgliUtCalcLightingRgb and XgliUtCalcLightingIndex return a single lit color and are described below. The remaining lighting utilities are listed and described on page 342.

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

Input Parameters ctx

XGL Context containing light sources and lighting parameters.

view_itf	View group interface used to obtain transformed light positions/directions.
color_in	Input color.
normal	Input facet or vertex normal (depending on whether the illumination is per_vertex, or per_facet, respectively).
point	Input 3D point.
surf	Surface attributes, either front or back.
front_flag	Flag indicating whether the normal is front facing.

Output Parameter color_out

The output color, adjusted for the Context lighting values.

XgliUtCalcLighting{Rgb,Index}{...}

void  XgliUtCalcLighting{Rgb,Index}{Front,Back}{Persp,Parallel}
{--,Cc}{--,Noniso}(
    XglContext3d*                 ctx,
    XglViewGrp3dItf*              view_itf,
    Xgl_color*                    color_in,
    Xgl_usgn32                    inclr_step,
    Xgl_pt_f3d*                   normal,
    Xgl_usgn32                    nrm_step,
    Xgl_pt_f3d*                   geom_ptr,
    Xgl_usgn32                    geom_step,
    Xgl_usgn32                    num_points,
    const Xgli_surf_attr_3d* surf,
    const float                   table,
    Xgl_color*                    color_out,
    Xgl_usgn32                    outclr_step)

These utilities apply the current light sources and lighting parameters to a list of points and return a list of lit colors. There are a set of 32 routines for the five different possible combinations of characteristics. The key word for each of the characteristics is defined in Table 12-1 on page 343.

Table 12-1

Key Word	Values	Description
Color type	Rbg / Index	Specifies whether the color type is RGB or Index.
Flip normal	Back - normals flipped Front - normals not flipped	Specifies whether the normal is be flipped before lighting.
Perspective	Persp / Parallel	Specifies whether the view is perspective or parallel.
Constant color	Cc / --	Specifies whether the color changes for each point, or the same color is used for every point in the lighting calculations.
Non-isotropic	Noniso / --	Specifies whether the McToWc matrix is not isotropic. For a definition of an isotropic or angle preserving matrix, refer to the section on XGL_TRANS_MEMBER_ANGLE_PRESERV in the xgl_transform_write_specific() man page.

The utilities are listed here, and their input and output parameters are described below.

XgliUtCalcLightingRgbFrontPersp	XgliUtCalcLightingIndexFrontPersp
XgliUtCalcLightingRgbFrontPerspCc	XgliUtCalcLightingIndexFrontPerspCc
XgliUtCalcLightingRgbFrontParallel	XgliUtCalcLightingIndexFrontParallel
XgliUtCalcLightingRgbFrontParallelCc	XgliUtCalcLightingIndexFrontParallelCc
XgliUtCalcLightingRgbFrontPerspNoniso	XgliUtCalcLightingIndexFrontPerspNoniso
XgliUtCalcLightingRgbFrontPerspCcNoniso	XgliUtCalcLightingIndexFrontPerspCcNoniso
XgliUtCalcLightingRgbFrontParallelNoniso	XgliUtCalcLightingIndexFrontParallelNoniso
XgliUtCalcLightingRgbFrontParallelCcNoniso	XgliUtCalcLightingIndexFrontParallelCcNoniso
XgliUtCalcLightingRgbBackPersp	XgliUtCalcLightingIndexBackPersp
XgliUtCalcLightingRgbBackPerspCc	XgliUtCalcLightingIndexBackPerspCc
XgliUtCalcLightingRgbBackParallel	XgliUtCalcLightingIndexBackParallel
XgliUtCalcLightingRgbBackParallelCc	XgliUtCalcLightingIndexBackParallelCc
XgliUtCalcLightingRgbBackPerspNoniso	XgliUtCalcLightingIndexBackPerspNoniso

XgliUtCalcLightingRgbBackPerspCcNoniso	XgliUtCalcLightingIndexBackPerspCcNoniso
XgliUtCalcLightingRgbBackParallelNoniso	XgliUtCalcLightingIndexBackParallelNoniso
XgliUtCalcLightingRgbBackParallelCcNoniso	XgliUtCalcLightingIndexBackParallelCcNoniso

Input Parameters ctx

XGL Context containing light sources and lighting parameters.

view_itf	View group interface used to obtain transformed light positions/directions.
color_in	Input color.
inclr_step	Step size by which color_in should be incremented to access the color of the next point. This field is unused for constant color routines.
normal	Pointer to a list of input normals.
nrm_step	Step size by which normal should be incremented to access the normal of the next point.
geom_ptr	Pointer to a list of 3D points.
geom_step	Step size by which the geometry should be incremented to access the normal of the next point.
num_pts	Number of points in geom_ptr list. The lighting values are computed for this many points.
surf	Surface attributes, either front or back.
table	Pointer to a table for computing the power function to use for computing specular exponents. This table is an array of 257 values corresponding to the current specular exponent (front or back depending on surf). The array index to use is computed by multiplying the dot value in the lighting equation with 256 and trucating it to a integer.
outclr_step	Step size by which color_out should be incremented to access the color of the next point.

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)

void XgliUtCalcTexturedColor(
    XglContext3d*                 ctx,
    const XgliUvSpanInfo3d*       data_info,
    Xgl_color*                    obj_clr,
    Xgl_boolean                   do_lighting,
    Xgl_usgn32                    z,
    float                         alpha_in,
    Xgl_color*                    color_out,
    float*                        alpha_out)

These routines apply the texture maps in the current ctx. do lighting and depth cueing, and return 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. These routines are the same except that the second routine also handles alpha values.

Input Parameters ctx

Context whose textures are applied.

data_info	Contains the texture coordinate (u, v) (before the divide by 1/w) as well as the lighting components at that pixel.
obj_clr	Pixel color before the texturing operation. This is the intrinsic color of the pixel.
do_lighting	If TRUE, lighting is performed.
z	Z value in DC of the pixel, used for depth cueing.
alpha_inThe output color after textures have been applied and lighting and depth cueing have been performed.	Input alpha value.
alpha_out	Output alpha value.

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.

v2	Coordinates of vertex 2.
v3	Coordinates of vertex 3.
fn	Facet 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_clr	The object color that should be combined with the texel.
tex_desc	The 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)

void XgliUtComputeFinalColor(
   Xgli_pixel_data_info* pdata,
   Xgl_color*                in_clr,
   float                     in_alpha,
   Xgl_color*                out_clr,
   float*                    out_alpha)

Both of these routines take the depth cued color in_clr and in_alpha 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. These routines are the same except that the second routine handles alpha values.

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.
in_alphaThe output color after applying the textures that affect the final component of the rendering pipeline.	Alpha value.
out_alpha	Output alpha value.

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 quadrilateral mesh, the row_dim and col_dim are ignored. The utility provides the option for normalizing.

Input Parameters op

Type of operator.

geom_normal	Geometry normal format as defined by the API attribute
XGL_3D_CTX_SURF_GEOM_NORMAL.
normalize	If TRUE, normalizes the normal.
row_dim	Number of rows when op is XGL_OP_XGL_QUADRILATERAL_MESH. This parameter is ignored for other ops.
col_dim	Number of columns when op is XGL_OP_XGL_QUADRILATERAL_MESH. This parameter is ignored for other ops.
num_pt_lists	Number of point lists in pl. For triangle strip and quadmesh, num_pt_lists is assumed to be 1, so its value is ignored.
pl	Geometry 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 point 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.

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.

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.

viewGrpItf	Pointer to a 3D view group interface.
circle_list	Pointer 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.

viewGrpItf	Pointer to a 3D view group interface.
arc_list	Pointer 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.

viewGrpItf	Pointer to a 3D view group interface.
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 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.

viewGrpItf	Pointer to a 3D view group interface.
ell_list	Pointer 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.

normal	The facet normal of the face that is being distinguished.
pt	A point on the face that is being distinguished.
view_itf	The 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.

XgliUtGetExponentTable

const float* XgliUtGetExponentTable(
   float*                     exp)

Finds the table of values corresponding to the closest exponent to the specified exponent exp.

Input Parameter exp

The exponent for which the table of values is desired.

Output Parameter None

Return Value A constant pointer to a table of 257 values.

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; otherwise, returns FALSE.

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; otherwise, returns FALSE.

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_method	Value of XGL_3D_CTX_SURF_TRANSP_METHOD.
blend_eq	Value 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.

siz	Number of entries in the vector array.
wg	The weights by which the vector array should be multiplied.
num_channel	Number 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.

viewGrpItf	Pointer 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_list	Facet 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 clipped.

Input Parameters ctx

Context from which attributes are obtained.

view_itf	View group from which model clip planes are obtained.
pl_in	Input 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_itf	View group from which model clip planes are obtained.
num_plines	Number of point lists in pl_in.
pl_in	Input 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_itf	View group from which model clip planes are obtained.
num_pl	Number of point lists in pl_in.
pl_in	Input 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_clipped	Facet 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_itf	View group from which model clip planes are obtained.
num_pl	Number of point lists in pl_in.
pl_in	Input 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_grp	View group from which model clip planes are obtained.
pt	Point 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_itf	View group from which model clip planes are obtained.
pl_in	Input 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_out	Facet 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 the starting position.

Output Parameter dst_buf

The destination buffer in the copy operation. The destination buffer is a 32-bit PixRect.

XgliUtPower

float XgliUtPower (
   float                 x,
   Xgl_usgn32            n)

Raises x to a positive integer power n. This routine is faster than the routine pow in the standard math library, but it only accepts integer exponents. Refer to The Art of Computer Programming by Donald E. Knuth, Volume 2, 2nd. edition, Addison-Wesley, 1981.

Input Parameters x

Input value.

n........Integer exponent value.

Output Parameter None

Return Value Returns a floating point value.

XgliUtProcessTxCoords

void XgliUtProcessTxCoords(
   XglViewGrp3dItf*               view_itf,
   Xgl_usgn32                     np,
   Xgli_point_list*               ipl,
   Xgli_facet_list*               ifl,
   Xgl_usgn32                     num_tm,
   XglTmap**                      tmap,
   Xgl_boolean*                   tswitch)

This routine allocates memory for texture coordinates, processes of texture coordinates based on texture map attributes (XGL_TMAP_PARAM_TYPE, XGL_TMAP_COORD_SOURCE, and XGL_TMAP_T0/1_INDEX), and and stores one set of {u,v} coordinate for each texture map. Thus, this routine allocates 2 * num_tm amount of floats for storing texture coordinates. The num_data_vals, data_ptr and pt_type fields of the point list ipl are accordingly modified. If a particular tswitch is FALSE (that is the texture map is not active), then the data values corresponding to these two entries in the array is uninitialized. The caller is responsible for freeing the allocated space once the values are no longer used.

Input Parameters view_itf

Pointer to a 3D view group interface.

np	Number of points for which texture coordinates needs to be processed.
ipl	Input point list from which the old data values are gotten. The input point list data pointer is overwritten with the processed data values.
ifl	Input facet list. The facet list is used if facet normals are used in generating u,v coordinates.

num_tm	Number of texture map objects as specified at the API level.
tmap	A pointer to the list of texture map objects.
tswitch	The list of texture map switches.

Output Parameters The ipl->num_data_vals, ipl->data_ptr.base_ptr, ipl->data_ptr.step_size, and ipl->pt_type are modified to reflect the newly generated texture coordinates.

XgliUtTxBoundary

int XgliUtTxBoundary(
   Xgl_texture_general_desc* desc,
   float&                         u,
   float&                         v,
   Xgli_acolor                    *texel)

Applies the boundary condition, and if necessary, the hierarchy of boundary condition as defined in the man page XGL_TMAP_DESCRIPTOR.

Input Parameters desc

The texture descriptor from which the boundary condition values are used.

u	The u texture coordinate.
v	The v texture coordinate.

Output Parameter texel

The texel value if it is computed.

Return Value Returns 0 if transparent, 1 if the texel is computed from boundary conditions, and 2 otherwise (u or v may be modified).

XgliUtTxGetUv

void XgliUtTxGetUv(
   XglTmap               *tmap,
   Xgl_pt_f3d            *pt,
   Xgl_pt_f3d            *norm,
   XglViewGrp3dItf       *view_itf,
   float&                u,
   float&                v)

This routine generates the {u,v} texture coordinates for environment texture mapping based on the texture map tmap attributes XGL_TMAP_PARAM_TYPE, XGL_TMAP_COORD_SOURCE, and XGL_TMAP_PARAM_INFO.

Input Parameters tmap

Texture map based on whose attributes the texture values are generated.

pt	The point for which the texture values are generated.
norm	The normal at the point at which the texture values are desired
view_itf	Pointer to a 3D view group interface.

Output Parameters u,v

The output texture coordinates.

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.

normal	Normal at vertex
viewGrp	Pointer to a view group interface object
flipNormal	Value 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

viewGrp	View group interface object
flipNormal	Context 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.

viewGrpItf	Pointer to a 3D view group interface.
circle_list	Pointer 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.

viewGrpItf	Pointer to a 3D view group interface.
arc_list	Pointer 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.

viewGrpItf	Pointer to a 3D view group interface.
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 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.

viewGrpItf	Pointer to a 3D view group interface.
ell_list	Pointer 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.

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.

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.

viewGrpItf	Pointer to a 3D view group interface.
circle_list	Pointer 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.

viewGrpItf	Pointer to a 3D view group interface.
arc_list	Pointer 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.

viewGrpItf	Pointer to a 3D view group interface.
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 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.

viewGrpItf	Pointer to a 3D view group interface.
ell_list	Pointer 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 xgl_context_check_bbox() man page.

Input Parameters ctx

Pointer to a 2D Context.

prim_type	The bounding box primitive type.
bbox	Pointer to a bounding box which can be an Xgl_bbox_i2d, Xgl_bbox_f2d, or Xgl_bbox_d2d structure.
view_grp_itf	Pointer 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 xgl_context_check_bbox() man page.

Input Parameters ctx

Pointer to a 3D Context.

prim_type	The bounding box primitive type.
bbox	Pointer to a bounding box which can be an Xgl_bbox_f3d or Xgl_bbox_d3d structure.
view_grp_itf	Pointer 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_rect	Source rectangle in src_dev's coordinate space.
adj_src_rect	Adjusted source rectangle; the new, valid rectangle.
dest_dev	Destination device.
dest_pos	Destination position in dest_dev's coordinate space.
adj_dest_pos	Adjusted 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 using PixRects. 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 when necessary).

Input Parameters dest_pr

PixRect representing the destination raster.

dest_pos	Destination position.
dest_fg_color	Foreground color from destination Context. Can be NULL if the fill style does not require color.
dest_bg_color	Background color from destination Context. Can be NULL if the fill style does not require color.
dest_clip_mask	Per-pixel clip mask represented as a PixRect for the destination. Can be NULL if there is no per-pixel clip mask, or if the whole area of the window or memory is visible so that the pipeline does not need to do a per-pixel clip.
src_pr	PixRect representing the source raster.
src_rect	Rectangle of pixels which get copied to destination.
src_clip_mask	Per-pixel clip mask represented as a PixRect for the source. Can be NULL if there is no per-pixel clip mask, or if the whole area of the window or memory is visible so that the pipeline does not need to do a per-pixel clip.

color_info	Color info for source and destination raster. This structure specifies the color space of the data. Color Map objects are needed to do the copy and color conversion. This may be NULL if copy does not involve color.
rop_info	Plane mask and rop function. If the raster fill style is XGL_RAS_FILL_COPY (see the man page for XGL_CTX_RASTER_FILL_STYLE), the fill_info structure must be filled in with the fill style; otherwise, the fill_info structure can be NULL. If there is a raster fill pattern or a stipple raster, the PixRect object must be supplied, and the stipple position and color must be supplied. May be NULL if the device does not want plane mask or raster operations to be done in software.
fill_info	Information from destination Context for filling with patterns or stipples; may be NULL if not using patterned fill.
z_buffer_info	Information for copying from one Z-buffer to another; should be NULL if not copying Z-buffer data. If this utility is used for xgl_image(), this structure must be filled in.

Output Parameter None

Return Value Returns 1 if the function succeeds or 0 otherwise.

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

rect	Rectangle from API
pos	Position from API
src_dev	Source device
src_image_pr	PixRect for source device's image buffer.
src_zbuffer_pr	PixRect for source device's Z buffer
src_clip_mask	PixRect 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_list	Pointer to the data to be classified.
points	Pointer 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.

pl	Pointer to the data to be classified.
facet_normal	Pointer 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

facet	Facet information
num_in_pt_lists	Number of point lists (i.e. bounds) in input polygon.
in_pl	Array of point lists for input polygon.
color_type	Color type (index or RGB).
d_c_normal	Normalized facet normal of input polygon.

geom_normal_type Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL.

normal_flip	Specifies 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_pl	Pointer 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.

facet	Facet information.
num_in_pt_lists	Number of point lists (i.e. bounds) in input polygon.

in_pl	Array of point lists for input polygon.
color_type	Color type (index or RGB).
d_c_normal	Normalized facet normal of input polygon.

geom_normal_type Geometry normal format as defined by the API attribute XGL_3D_CTX_SURF_GEOM_NORMAL.

normal_flip	Specifies 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_pl	Pointer to output point lists of triangle stars.

Return Value Returns 1 if the polygon is successfully decomposed and 0 if memory allocation fails.