Table of Contents

9. Annotation - Axis,Billboard,Dimension,Font,Glyph,Tess,Triad

The annotation modules Axis, Font and Glyph are designed to complement the other modules in VisTools by providing a convenient means of generating stroked text, various 3D glyphs (arrows, markers, etc.) and labelled and titled axes for building graphs. The Billboard module is meant to provide a screen oriented rectangular area for displaying 2D text and graphics. Billboards are useful for displaying quantitative information about individual entities such as finite elements or nodes. The Dimension module is designed to draw a number of standard dimensioning annotations such as linear and radial dimensioning, leader lines, etc. The Triad module may be used to draw representations of Cartesian, cylindrical, spherical and toroidal coordinate systems in various styles.

Table of Contents

9.1 Annotated Axes - Axis

Use Axis to generate labelled and titled axes. The primary use of axes is to build a quantitative frame for 2D and 3D graphs. However axes are also useful for drawing "rulers" in 3D space for measuring distances between objects etc. The functions associated with a Axis object are the following.

Instance an Axis object using vis_AxisBegin. Once an Axis object is instanced, set the attribute objects using vis_AxisSetObject and set display parameters using vis_AxisSetParami. The axis orientation is specified using vis_AxisSetPlane.

Each axis visualization entity is composed of up to three separately drawn parts - the path, plane and projection, drawn using vis_AxisPath, vis_AxisPlane and vis_AxisProjection respectively. The terms path, plane and projection simply refer to the 3 orthogonal directions of the axis orientation direction cosine matrix. This orientation matrix is defined in a manner similar to that used for defining orientations in the Font module. The path is the primary axis direction. When the path component of the axis is drawn, the axis itself as well as titles, labels and intermediate tic marks are generated. The extension of the grid lines, which pass through the labelled points of the axis, into orthogonal planes is done by drawing the plane and projection components. For example, for a conventional XY graph, two axes and their associated plane components are required to generate the X and Y axes and the intersecting grid lines in the XY plane. A three dimensional XYZ graph would require three axes and the grid lines corresponding to the plane and projection components for each axis. Axis visualization entities are not subject to isosurface clipping.

By default all axis titles and numeric labels are drawn using a stroked font. The use of a stroked font as opposed to a raster font for drawing titles and labels may be toggled on or off using vis_AxisSetParami with the parameter AXIS_STROKEFONT.

Table of Contents

9.2 Attribute Objects

An Axis object uses DrawFun, Levels, VisContext, ColorMap and TransMap objects to define attributes required to generate an axis visualization entity. A Levels object is used to define the values along the axis at which labelled grid lines are to be placed. A discrete labelled grid line is generated at each level in the Levels attribute object. An Axis object requires a VisContext object for the axis and the fonts used for labelling and titling. If a TransMap attribute object is not set any specified constant transparency is ignored. An Axis object uses the following VisContext components.

AColor
Label color
Color
Plane fill color
DataIndex
Draw Levels object map index flag. If enabled, then the level number map index is drawn as a DataIndex before any primitives associated with the level are drawn.
Fill
Plane fill flag
Flags
VIS_BACKPLANEFLIP flips the labels and titles if the normal to the character plane is pointing away from the viewer. This option requires the current modelview matrix.
Format
Format of axis labels. If VIS_XFORMAT is used, the mantissa of the label value is displayed. The exponent which has been factored from each label value on the axis is displayed beneath the final label on the axis.
Frequency
Number of intermediate tic marks between labelled grid points
LineWidth
Line width of axis
LineStyle
Line style of axis
MinorColor
Title and subtitle color
MinorLineWidth
Line width of grid lines
MinorLineStyle
Line style of grid lines
MinorSize
Size of axis title. The subtitle and axis labels are scaled from the title size.
Size
Unit line width of cylindrical line style
TextBox
Text box size for positioning raster font titles and labels
Transparency
Fill plane transparency
XfmMatrix
Modelview matrix, used with back plane flip
XColor
Axis color
YColor
Color of grid lines in plane
ZColor
Color of grid lines along projection
Figure 9-1 illustrates an axis system. The axis path extends from left to right. The path component of the axis is drawn as a line with a title and subtitle lying below the axis in the axis plane. Seven equally spaced points are labelled along the axis. Intermediate tic marks are placed between the labels. The plane component of the axis consists of seven vertical lines drawn through the labelled points in the positive direction in the axis plane. The projection component of the axis consists of seven lines drawn "out of the paper", orthogonal to the axis plane.


Figure 9-1, Axis Path, Plane and Projection
Table of Contents

9.3 Function Descriptions

The currently available Axis functions are described in detail in this section.


Table of Contents , Axis

NAME

*vis_AxisBegin - create an instance of a Axis object

C SPECIFICATION

vis_Axis *vis_AxisBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Axis object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Axis object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The path, plane and projection directions are along the x, y and z global coordinate axes respectively. The axis sense is right handed.

Destroy an instance of a Axis object using

     void vis_AxisEnd (vis_Axis *axis)

Return the current value of a Axis object error flag using

     Vint vis_AxisError (vis_Axis *axis)


Table of Contents , Axis

NAME

vis_AxisSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_AxisSetObject (vis_Axis *axis,
                        Vint objecttype,
                        Vobject *object)

INPUT ARGUMENTS

axis         Pointer to Axis object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_VISCONTEXT         VisContext object
             =VIS_LEVELS             Levels object
             =VIS_COLORMAP           ColorMap object
             =VIS_TRANSMAP           TransMap object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. All the attribute objects are mandatory for all drawing methods.


Table of Contents , Axis

NAME

vis_AxisSetParami - set axis display parameters

C SPECIFICATION

void vis_AxisSetParami (vis_Axis *axis,
                        Vint ptype,
                        Vint iparam)

INPUT ARGUMENTS

axis         Pointer to Axis object.
ptype        Type of display parameter to set
             =AXIS_FIRSTLABEL         Draw first axis label
             =AXIS_FIRSTGRID          Draw first grid line on the axis
                                      plane and projection
             =AXIS_LABELUSELEVELS     Toggle Levels labels.
             =AXIS_LASTGRID           Draw last grid line on the axis
                                      plane and projection
             =AXIS_PLANEEND           Draw axis at end of axis plane
             =AXIS_ROTATELABEL        Rotate label + or - 90 degrees
             =AXIS_SENSE              Set left handedness of axis
             =AXIS_SHORTGRID          Specify short grid lines on the axis
                                      plane and projection
             =AXIS_STROKEFONT         Toggle use of stroked font labels.
iparam       Specifies the integer value that ptype will be set to.
             =VIS_OFF                Turn parameter off
             =VIS_ON                 Turn parameter on
             =AXIS_ROTATELABEL_NONE  Do not rotate label
             =AXIS_ROTATELABEL_PLUS90   Rotate label +90 degrees
             =AXIS_ROTATELABEL_MINUS90  Rotate label -90 degrees

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify the drawing of the first label on the axis path. This may disabled to prevent spatial collisions of grid labels on 3D graphs. By default AXIS_FIRSTLABEL is set to on.

The labels may be drawn using the text labels contained in the Levels attribute object by enabling the AXIS_LABELUSELEVELS parameter. By default AXIS_LABELUSELEVELS is set to off.

Specify the drawing of the first grid line on axis plane and projections. This grid line normally coincides in space with the axes of orthogonal axes. By default AXIS_FIRSTGRID is set to off.

Specify the drawing of the last grid line on axis plane and projections. By default AXIS_LASTGRID is set to on.

Specify the drawing of an axis at the end of the axis plane. If this parameter is enabled it is a good idea to disable AXIS_LASTGRID when drawing the plane and projection or orthogonal axes. By default AXIS_PLANEEND is set to off.

Set rotation of axis labels using AXIS_ROTATELABEL. The label may be rotated by +90. degrees using AXIS_ROTATELABEL_PLUS90. and by -90. degrees using AXIS_ROTATELABEL_MINUS90. By default AXIS_ROTATELABEL is set to XIS_ROTATELABEL_NONE.

Set axis sense. By default AXIS_SENSE is set to off.

Set short grid line flag. If this flag is enabled short grid lines are drawn on the axis plane and projection. Plane fill, if specified, is always drawn to fill the entire plane. By default AXIS_SHORTGRID is set to off.

Toggle the use of a stroked font as opposed to a raster font for drawing titles and labels. By default AXIS_STROKEFONT is set to VIS_ON.


Table of Contents , Axis

NAME

vis_AxisSetPlane - set axis orientation

C SPECIFICATION

void vis_AxisSetPlane (vis_Axis *axis,
                       Vfloat path[3], 
                       Vfloat plane[3])

INPUT ARGUMENTS

axis         Pointer to Axis object.
path         Vector in direction of axis path.
plane        Vector in direction of axis plane.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_COMPUTE is generated if path and plane do not define a unique orientation plane.

DESCRIPTION

Set axis orientation. The path and plane vectors need not be normalized or orthogonal. The axis plane is formed perpendicular to the axis path in the plane defined by the path and plane vectors. The path and plane vectors can not be parallel.

Get path and plane as output arguments using

     void vis_AxisGetPlane (vis_Axis *axis,
                            Vfloat path[3], 
                            Vfloat plane[3])


Table of Contents , Axis

NAME

vis_AxisPath - draw axis path

C SPECIFICATION

void vis_AxisPath (vis_Axis *axis,
                   Vfloat x[3],
                   Vfloat length,
                   Vchar title[], 
                   Vchar subtitle[])

INPUT ARGUMENTS

axis         Pointer to Axis object.
x            Origin of axis
length       Length of axis along path
title        Axis title
subtitle     Axis subtitle

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw an axis with its origin at x projecting a distance length along the axis path. The axis is labelled at the locations specified by the Levels attribute object. Tic marks are drawn between labelled points. A title and subtitle are drawn immediately below the axis.


Table of Contents , Axis

NAME

vis_AxisPlane - draw grid lines and plane fill in plane

C SPECIFICATION

void vis_AxisPlane (vis_Axis *axis,
                    Vfloat x[3],
                    Vfloat length, 
                    Vfloat lengthy,
                    Vchar title[], 
                    Vchar subtitle[])

INPUT ARGUMENTS

axis         Pointer to Axis object.
x            Origin of axis
length       Length of axis along path
lengthy      Length of grid lines along plane
title        Axis title
subtitle     Axis subtitle

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw grid lines in axis plane with its origin at x projecting a distance length along the axis path and a distance lengthy along the axis plane. The extent of the axis plane is defined by the distances length and lengthy. The axis plane is filled at this time if requested. A title and subtitle are drawn immediately above the end of the grid lines in the axis plane.


Table of Contents , Axis

NAME

vis_AxisProjection - draw grid lines along projection

C SPECIFICATION

void vis_AxisProjection (vis_Axis *axis,
                         Vfloat x[3],
                         Vfloat length, 
                         Vfloat lengthz,
                         Vchar title[], 
                         Vchar subtitle[])

INPUT ARGUMENTS

axis         Pointer to Axis object.
x            Origin of axis
length       Length of axis along path
lengthz      Length of grid lines along projection
title        Axis title
subtitle     Axis subtitle

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw grid lines along axis projection with its origin at x projecting a distance length along the axis path and a distance lengthz along the axis projection. A title and subtitle are drawn immediately below the end of the grid lines along the axis projection.


Table of Contents

9.4 Billboard Displays - Billboard

Use Billboard for displaying 2D text and graphics in a screen oriented rectangular area. A billboard can be used to display information particular to a specific entity such as finite element properties, or any information which must remain readable such as a graph legend or customized color bar.

A Billboard object allows you to insert items (text, lines, points, polygons, etc.) and spacing information in a manner similar to a typewriter, in which one adds a series of text, from the top down, separated by spaces and newlines. A Billboard object will automatically adjust its width and height so that it encloses the items contained in it.

The Billboard object employs a 2D coordinate system based on a the size of a text box. The dimensions of the text box are defined in the visualization context TextBox. A single character (e.g., 'a') will have the width and height of one text box. The dimensions of geometric items (e.g., lines, polygons, rectangles, etc.) are specified in terms of a text box. Therefore, the string "abcd" and a line of length 4.0 will have the same length. Positive x and y is to the right and up, respectively.

The placement of items within the billboard is performed using a current (x, y) position stored in the Billboard object. Initially, the current position is at the top left of the billboard. When an item is added, it is placed at the current position within the billboard. The current position is then automatically incremented in x, depending on the item. For example, adding the text string "stress" will increment the current x position by six units; adding a line of width 2.5 will increment the current x position by 2.5 units. Adding spaces and incrementing the current y position must be done explicitly.

Billboard visualization entities are not subject to isosurface clipping.

The functions associated with a Billboard object are the following.

Since the Billboard module uses "DC" style drawing functions to perform all drawing, it is suggested to disable lighting before drawing a billboard with vis_BillboardDraw. This will ensure that the billboard is drawn in base colors without any lighting effects.

Table of Contents

9.5 Attribute Objects

A Billboard object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes required to generate a billboard visualization entity.

A Billboard object requires a VisContext object for the billboard background and border colors and transparency. It is also used to define the size of a text box used for positioning items.

If a TransMap attribute object is not set then transparency is ignored.

A Billboard object uses the following VisContext components.

AColor
Border color
BColor
Border shadow color (for bevels)
CColor
Border highlight color (for bevels)
Color
Background rectangle fill color
DeviceOffset
Offset of attachment point position from specified anchor point in device coordinates
LineWidth
Line width of border
MinorColor
Offset vector color
Position
Attachment point position on billboard
TextBox
Text box size for positioning items
Transparency
Background rectangle transparency
A Billboard object references the following DrawFun functions.
vgl_DrawFunLineStyle
vgl_DrawFunLineWidth
vgl_DrawFunPointSize
vgl_DrawFunPolygonDC
vgl_DrawFunPolyLineDC
vgl_DrawFunPolyPointDC
vgl_DrawFunTextDC

Figure 9-2 illustrates a simple billboard that could be used to display summary information about a specific finite element. The billboard is always drawn screen oriented (perpendicular to the viewer) and anchored at a 3D world coordinate. This allows it to be anchored in 3D to the entity which it describes.


Figure 9-2, Simple Billboard for Element Information
Table of Contents

9.6 Function Descriptions

The currently available Billboard functions are described in detail in this section.


Table of Contents , Billboard

NAME

*vis_BillboardBegin - create an instance of a Billboard object

C SPECIFICATION

vis_Billboard *vis_BillboardBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Billboard object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Billboard object. Memory is allocated for the object's private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a Billboard object using

     void vis_BillboardEnd (vis_Billboard *billboard)

Return the current value of a Billboard object error flag using

     Vint vis_BillboardError (vis_Billboard *billboard)


Table of Contents , Billboard

NAME

vis_BillboardSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_BillboardSetObject (vis_Billboard *billboard,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

billboard    Pointer to Billboard object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_VISCONTEXT         VisContext object
             =VIS_COLORMAP           ColorMap object
             =VIS_TRANSMAP           TransMap object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. The DrawFun, VisContext and ColorMap attribute objects are mandatory. The TransMap attribute object is optional.


Table of Contents , Billboard

NAME

vis_BillboardSetParami - set display parameters

C SPECIFICATION

void vis_BillboardSetParami (vis_Billboard *billboard,
                             Vint ptype,
                             Vint iparam)

INPUT ARGUMENTS

billboard    Pointer to Billboard object.
ptype        Type of display parameter to set
             =BILLBOARD_BEVEL         Draw billboard with bevels
             =BILLBOARD_OFFSET_VECTOR Draw billboard with location vector
iparam       Specifies the integer value that ptype will be set to.
             =VIS_OFF                 Turn parameter off
             =VIS_ON                  Turn parameter on

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify the addition of bevels for drawing the billboard border. By default BILLBOARD_BEVEL is set to on.

Specify the drawing of an arrow from the billboard position to its anchor point. The vector is drawn only if the billboard has a nonzero offset from the anchor point specified by the DeviceOffset visualization context. By default BILLBOARD_OFFSET_VECTOR is set to off.


Table of Contents , Billboard

NAME

vis_BillboardSetItemParami - set item integer parameters

C SPECIFICATION

void vis_BillboardSetItemParami (vis_Billboard *billboard,
                                 Vint ptype,
                                 Vint iparam)

INPUT ARGUMENTS

billboard    Pointer to Billboard object.
ptype        Type of current item display parameter to set
             =BILLBOARD_COLOR         Set the item color
             =BILLBOARD_POINT_SIZE    Set the point size for point items
             =BILLBOARD_LINE_WIDTH    Set the line width for 
                                      line, rule, and polyline items
             =BILLBOARD_LINE_STYLE    Set the line style for 
                                      line, rule, and polyline items
             =BILLBOARD_RULE_BEVEL    Draw rule with bevels
             =BILLBOARD_SHADOW_COLOR  Set the shadow color for
                                      beveled rules.
             =BILLBOARD_TRANSPARENCY  Set the item transparency
iparam       Specifies the integer value that ptype will be set to.
             =VIS_OFF                 Turn parameter off
             =VIS_ON                  Turn parameter on
             =VIS_SOLID               Solid line style 
             =VIS_DASHDASH            Dashed line style 
             =VIS_DOTDOT              Dotted line style 
             =VIS_DOTDASH             Dotted/dashed line style 

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify the color used to draw items. The color value is an index for a color map object. By default BILLBOARD_COLOR is set to one.

Specify the point size used to draw a point item. By default BILLBOARD_POINT_SIZE is set to one.

Specify the line width used to draw line, rule, and polyline items. By default BILLBOARD_LINE_WIDTH is set to one.

Specify the line style used to draw line, rule, and polyline items. By default BILLBOARD_LINE_STYLE is set to VIS_SOLID.

Specify the rule style used to draw a rule item. By default BILLBOARD_RULE_STYLE is set to BILLBOARD_RULE_STYLE_NONE.

Specify the transparency used to draw items. The transparency value is an index for a transparency map object. By default BILLBOARD_TRANSPARENCY is set to one.


Table of Contents , Billboard

NAME

vis_BillboardSetItemParamfv - set item float vector parameters

C SPECIFICATION

void vis_BillboardSetItemParamfv (vis_Billboard *billboard,
                                  Vint ptype,
                                  Vfloat fparam[])

INPUT ARGUMENTS

billboard    Pointer to Billboard object
ptype        Type of parameter to set
             =BILLBOARD_OFFSET        Offset of an item  
fparam       Specifies the float values that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify the current positional offset of an item. The offset is added to the position of an item when it is drawn. The offset is specified in multiples of a text box. By default BILLBOARD_OFFSET is set to (0.0, 0.0).


Table of Contents , Billboard

NAME

vis_BillboardErase - erase all items

C SPECIFICATION

void vis_BillboardErase (vis_Billboard *billboard)

INPUT ARGUMENTS

billboard    Pointer to Billboard object

OUTPUT ARGUMENTS

None

DESCRIPTION

Erase all items. The current x position is set to 0.0 (left) and the current y position is set to the top of the billboard.


Table of Contents , Billboard

NAME

vis_BillboardLineItem - add a line item

C SPECIFICATION

void vis_BillboardLineItem (vis_Billboard *billboard,
                            Vfloat length)  

INPUT ARGUMENTS

billboard    Pointer to Billboard object
length       Length of the line

OUTPUT ARGUMENTS

None

DESCRIPTION

Add a line item of length length to a Billboard object. The line is drawn from the current (x,y) position to the right. The current x position is incremented by the length of the line.


Table of Contents , Billboard

NAME

vis_BillboardPointItem - add a point item

C SPECIFICATION

void vis_BillboardPointItem (vis_Billboard *billboard)

INPUT ARGUMENTS

billboard    Pointer to Billboard object

OUTPUT ARGUMENTS

None

DESCRIPTION

Add a point item to a Billboard object. The point is drawn at the current (x,y) position. The current x position is incremented by 1.


Table of Contents , Billboard

NAME

vis_BillboardPolygonItem - add a polygon item

C SPECIFICATION

void vis_BillboardPolygonItem (vis_Billboard *billboard,
                               Vint npts, 
                               Vfloat pts[][2],
                               Vint fill)

INPUT ARGUMENTS

billboard    Pointer to Billboard object
npts         Number of points defining the polygon
pts          Points defining the polygon
fill         Flag specifying a filled polygon

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if npts = 0.

DESCRIPTION

Add a polygon item to a billboard. The polygon points are offsets relative to the current (x,y) position. Positive offsets are to the right and up; negative to the left and down. The current x position is incremented by the maximum x coordinate value in the pts array.


Table of Contents , Billboard

NAME

vis_BillboardRectangleItem - add a rectangle item

C SPECIFICATION

void vis_BillboardRectangleItem (vis_Billboard *billboard,
                                 Vfloat width, 
                                 Vfloat height,
                                 Vint solid)

INPUT ARGUMENTS

billboard    Pointer to Billboard object
width        Width of the rectangle
height       Height of the rectangle 
solid        Flag specifying a solid rectangle 

OUTPUT ARGUMENTS

None

DESCRIPTION

Add a rectangle item to a billboard of width width and height height. The rectangle is drawn up and to the right with its bottom left corner at the current (x,y) position. The current x position is incremented by the width of the rectangle.


Table of Contents , Billboard

NAME

vis_BillboardRuleItem - add a rule item

C SPECIFICATION

void vis_BillboardRuleItem (vis_Billboard *billboard)

INPUT ARGUMENTS

billboard    Pointer to Billboard object

OUTPUT ARGUMENTS

None

DESCRIPTION

Add a rule item to a billboard. The width of the rule will equal the width of the billboard and will be centered in the text box at the current y position. A new line is automatically generated and the current x position is set to 0.0 (left).


Table of Contents , Billboard

NAME

vis_BillboardTextItem - add a text item

C SPECIFICATION

void vis_BillboardTextItem (vis_Billboard *billboard,
                            Vchar *text)  
void vis_BillboardTextItemtv (vis_Billboard *billboard,
                              Vtchar *text)  

INPUT ARGUMENTS

billboard    Pointer to Billboard object
text         Text string

OUTPUT ARGUMENTS

None

DESCRIPTION

Add a text item to a billboard. The text is drawn with its bottom left corner at the current (x,y) position. The current x position is incremented by the number of characters in text. If the string ends in a newline character (i.e., '\n') then a new line is automatically generated and the current x position is set to 0.0.


Table of Contents , Billboard

NAME

vis_BillboardTitleItem - add a title item

C SPECIFICATION

void vis_BillboardTitleItem (vis_Billboard *billboard,
                             Vchar *title)  
void vis_BillboardTitleItemtv (vis_Billboard *billboard,
                               Vtchar *title)  

INPUT ARGUMENTS

billboard    Pointer to Billboard object
title        Title string

OUTPUT ARGUMENTS

None

DESCRIPTION

Add a title item to a billboard. The title is centered in x in the billboard at the current y position. A new line is automatically generated and the current x position is set to 0.0 (left).


Table of Contents , Billboard

NAME

vis_BillboardNewLine - increment the current y position

C SPECIFICATION

void vis_BillboardNewLine (vis_Billboard *billboard,
                           Vfloat nlines)

INPUT ARGUMENTS

billboard    Pointer to Billboard object
nlines       Number of lines to increment

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if nlines < 0.

DESCRIPTION

Increment the current y position by nlines * (text box height). The current x position is set to 0.0.


Table of Contents , Billboard

NAME

vis_BillboardSpace - increment the current x position

C SPECIFICATION

void vis_BillboardSpace (vis_Billboard *billboard,
                         Vfloat nspaces)  

INPUT ARGUMENTS

billboard    Pointer to Billboard object
nspaces      Number of spaces to increment

OUTPUT ARGUMENTS

None

DESCRIPTION

Increment the current x position by nspaces * (text box width).


Table of Contents , Billboard

NAME

vis_BillboardDraw - display the contents of a billboard

C SPECIFICATION

void vis_BillboardDraw (vis_Billboard *billboard,
                        Vfloat x[3])

INPUT ARGUMENTS

billboard    Pointer to Billboard object
x            World coordinate anchor point

OUTPUT ARGUMENTS

None

DESCRIPTION

Display the contents of a Billboard object at the specified location in world coordinates.


Table of Contents

9.7 Dimensioning - Dimension

Use Dimension to display dimensioning and annotation information for 2D or 3D objects. Dimensioning can be used to display the numeric dimensions such as length, width, height, distance, radius, etc. of geometric features

The Dimension object employs a local coordinate system embedded in 3D space called the dimension plane to define the placement of the dimensioning lines and text. The orientation of the dimension plane is defined by a pair of 3D vectors. The x',y',z' axes of local coordinate system define the "horizontal", "vertical" and "indepth" directions of the dimensioning annotation.

There are two basic types of dimensioning annotation, linear dimensions and leader lines. A linear dimension is used to label the straight line distance between two points. It consists of two extension lines, a dimension line, a label and in some cases a leader line. The extension lines are lines drawn from the two points which define a straight line feature to the position of the dimension line and label. The dimension line is drawn perpendicular to the extension lines and defines the straight line distance between the two points. A linear dimension can be oriented to be horizontal, vertical, in depth or aligned with the angle of a feature.

A leader line is used to dimension specific features (e.g., holes) and consists of a line pointing to the feature and a label. A special type of leader termed a radius leader line can be used to dimension the radius of a circular feature.

The following functions are associated with a Dimension object.

Instance a Dimension object using vis_DimensionBegin. Once a Dimension object is instanced, set the attribute objects using vis_DimensionSetObject and set display parameters using vis_DimensionSetParami and vis_DimensionSetParamf. Dimension lines, leader lines and labels are drawn with respect to a local coordinate system specified by vis_DimensionSetPlane. The local x',y',z' axes define the horizontal, vertical and depth directions. Linear dimensions are drawn using vis_DimensionLinear and leader lines are drawn using vis_DimensionLeader and vis_DimensionRadius. An angular dimension may be drawn using vis_DimensionAngular.

All linear dimension annotation drawn using vis_DimensionLinear uses two points to define the feature to be dimensioned and a single point for positioning the dimensioning label. The dimension line is drawn through the label point parallel to an axis of the local coordinate system (horizontal, vertical or depth axis) or parallel to the line between the feature points. Extension lines are drawn from the feature points to the dimension line. The extension lines are constructed to be perpendicular to the dimension line. The label may be drawn horizontally or aligned to the dimension line. The dimension label is positioned along the dimension line in different ways depending upon user options and whether it is located inside or outside of the extension lines. The user may specify that the label be automatically placed by calling vis_DimensionSetParami with the DIMENSION_LABEL_AUTO parameter enabled. In this case the label is centered exactly between the extension lines if its original input location is between the extension lines and it is positioned at a user specified offset from an extension line if its original input location is outside the extension lines. If the automatic placement option is not enabled the label is placed exactly at the original input location. The use of a stroked font as opposed to a raster font for drawing labels may be toggled on or off using the parameter DIMENSION_STROKEFONT. Figure 9-3a illustrates a linear dimension annotation aligned (drawn parallel) to the line between the feature points and centered between the extension lines.


Figure 9-3a, Linear Dimension Annotation
The functions vis_DimensionLeader and vis_DimensionRadius are used to draw leader lines. The first point input to leader line drawing is the attachment point. This point specifies the location of the tip of the arrow of the leader annotation. The leader line angles from the attachment point to the vertical position of the label, the leader line is then continued horizontally to the label. Figure 9-3b illustrates a simple leader with a label.


Figure 9-3b, Leader with Label
In the case of the radius style leader drawn using vis_DimensionRadius, the leader line from the attachment point passes through a specified center point to the vertical position of the label. Figure 9-3c illustrates a radius leader with a label and center mark.


Figure 9-3c, Radius Leader with Label and Center Mark
All angular dimension annotation drawn using vis_DimensionAngular uses three points to define the feature to be dimensioned and a single point for positioning the dimensioning label. The dimension line is an arc drawn through the label point at a constant radius from a given center point. Extension lines are drawn from the center point through the feature points The length of the extension lines is the maximum distance of a feature point from the center point. The label may be drawn horizontally or aligned to the dimension line arc. In a manner similar to the placement of label in a linear dimension. Figure 9-3d illustrates an angular dimension annotation orthogonal to the arc between the feature points and centered between the extension lines.


Figure 9-3d, Angular Dimension Annotation
Table of Contents

9.8 Attribute Objects

A Dimension object uses ColorMap, DrawFun and VisContext objects to define attributes required to generate a dimension visualization entity. A Dimension object requires a VisContext object for line color, width and style, font size and color for labels, and arrow head attributes. A Dimension object uses the following VisContext components.

Angle
Half angle in degrees of an arrow head
Color
Leader, dimension and extension lines color
Fill
Arrow head fill flag
Flags
VIS_BACKPLANEFLIP flips a label if the normal to the dimension plane is pointing away from the viewer. This option requires the current modelview matrix. VIS_VECTORNOCAP draws arrow heads without a cap. VIS_VECTORNOHEAD draws all arrows without heads.
LineWidth
Line width for all extension, leader and dimension lines.
LineStyle
Line style for all leader and dimension lines.
MinorColor
Label color
MinorLineWidth
Label line width
MinorLineStyle
Line style for all extension lines.
MinorSize
Size of arrow head
Ratio
Arrow head slant ratio
Refinement
Arrow head refinement
Shade
Arrow head shading
Size
Text size for labels
VectorType
Arrow head type
XfmMatrix
Modelview matrix, used with back plane flip
A Dimension object references the following DrawFun functions.
vgl_DrawFunColor
vgl_DrawFunColorIndex
vgl_DrawFunLineStyle
vgl_DrawFunLineWidth
vgl_DrawFunPolyLine
vgl_DrawFunTrans
vgl_DrawFunTransIndex

Table of Contents

9.9 Function Descriptions

The currently available Dimension functions are described in detail in this section.


Table of Contents , Dimension

NAME

*vis_DimensionBegin - create an instance of a Dimension object

C SPECIFICATION

vis_Dimension *vis_DimensionBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Dimension object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Dimension object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The dimension plane is oriented with the x and y global coordinate axes.

Destroy an instance of a Dimension object using

     void vis_DimensionEnd (vis_Dimension *dimension)

Return the current value of a Dimension object error flag using

     Vint vis_DimensionError (vis_Dimension *dimension)


Table of Contents , Dimension

NAME

vis_DimensionSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_DimensionSetObject (vis_Dimension *dimension,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

dimension    Pointer to Dimension object.
objecttype   The name of the object type to be set.
             =VIS_COLORMAP           ColorMap object
             =VGL_DRAWFUN            DrawFun object
             =VIS_VISCONTEXT         VisContext object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object.


Table of Contents , Dimension

NAME

vis_DimensionSetParamf - set dimension display parameters

C SPECIFICATION

void vis_DimensionSetParamf (vis_Dimension *dimension,
                             Vint ptype,
                             Vfloat fparam)

INPUT ARGUMENTS

dimension    Pointer to Dimension object.
ptype        Type of display parameter to set
             =DIMENSION_ANGLE          Angle of leader lines
             =DIMENSION_GAP            Extension line gap
             =DIMENSION_LABEL_ANGLE    Angle of label
             =DIMENSION_OFFSET         Length of horizontal leader
fparam       Specifies the float value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

The parameter DIMENSION_ANGLE specifies the angle in degrees that the leader line is constrained to make from its attachment point to the vertical position of its label. This angle is used only if DIMENSION_ANGLE_LOCK is enabled using vis_DimensionSetParami. By default DIMENSION_ANGLE is set to 45.0 degrees.

The parameter DIMENSION_GAP specifies gap of extension lines from feature locations in world coordinates. By default DIMENSION_GAP is set to 0.0.

The parameter DIMENSION_LABEL_ANGLE specifies an additional angle of rotation to be applied to labels. By default DIMENSION_LABEL_ANGLE is set to 0.0.

The parameter DIMENSION_OFFSET specifies the length of certain segments of leader lines and dimension lines. If DIMENSION_LABEL_AUTO is enabled using vis_DimensionSetParami then the length of the horizontal segment of a leader line drawn using vis_DimensionLeader or vis_DimensionRadius is constrained to be DIMENSION_OFFSET. Any leader lines outside extension lines drawn using vis_DimensionLinear or vis_DimensionAngular are constrained to be of length DIMENSION_OFFSET. By default DIMENSION_OFFSET is set to 1.0.


Table of Contents , Dimension

NAME

vis_DimensionSetParami - set dimension display parameters

C SPECIFICATION

void vis_DimensionSetParami (vis_Dimension *dimension,
                             Vint ptype,
                             Vint iparam)

INPUT ARGUMENTS

dimension    Pointer to Dimension object.
ptype        Type of display parameter to set
             =DIMENSION_ANGLE_LOCK     Constrain angle of leader lines
             =DIMENSION_CENTER_MARK    Mark center point of radius leader
             =DIMENSION_EXTENSIONLINES Toggle drawing of extension lines
             =DIMENSION_LABEL_ALIGN    Label alignment
             =DIMENSION_LABEL_AUTO     Place label at specified offset
             =DIMENSION_LABEL_POSITION Anchor label at specified position
             =DIMENSION_INSIDE         Place dimension lines on inside of
                                       extension lines
             =DIMENSION_LINEAR_ALIGN   Linear dimension alignment
             =DIMENSION_NOHEAD_FIRST   No head on first arrow
             =DIMENSION_NOHEAD_SECOND  No head on second arrow
             =DIMENSION_STROKEFONT     Toggle use of stroked font labels. 
fparam       Specifies the float value that ptype will be set to.
iparam       Specifies the integer value that ptype will be set to.
             =VIS_OFF                Turn parameter off
             =VIS_ON                 Turn parameter on
             =DIMENSION_HORIZONTAL   Orient horizontally
             =DIMENSION_VERTICAL     Orient vertically
             =DIMENSION_INDEPTH      Orient in depth
             =DIMENSION_ALIGNED      Align in line
             =DIMENSION_ORTHOGONAL   Align orthogonally
             =VIS_CENTER             Anchor label at label center
             =VIS_RIGHT              Anchor label at label right
             =VIS_LEFT               Anchor label at label left

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

The parameter DIMENSION_ANGLE_LOCK specifies that a leader line is constrained to make a specified angle from its attachment point to the vertical position of its label. The angle is specified using vis_DimensionSetParamf with the parameter DIMENSION_ANGLE. By default DIMENSION_ANGLE_LOCK is set to VIS_OFF.

The parameter DIMENSION_CENTER_MARK indicates whether the center mark of radius leader lines are to be drawn with a cross. By default DIMENSION_CENTER_MARK is set to VIS_ON.

The parameter DIMENSION_EXTENSIONLINES toggles the drawing of linear dimension extension lines. By default DIMENSION_EXTENSIONLINES is set to VIS_ON.

The parameter DIMENSION_LABEL_ALIGN specifies the alignment of the label. DIMENSION_HORIZONTAL will orient the label parallel to the local x' axis, DIMENSION_ALIGNED will orient the label parallel with the dimension line, and DIMENSION_ORTHOGONAL will orient the label at a right angle with the dimension line. By default DIMENSION_LABEL_ALIGN is set to DIMENSION_HORIZONTAL.

The parameter DIMENSION_LABEL_AUTO specifies the automatic placement of labels. Normally, labels are placed at the location specified when defining a dimension. If DIMENSION_LABEL_AUTO is enabled then labels are placed at an offset from the dimensioning lines. The offset is specified using vis_DimensionSetParamf with the parameter DIMENSION_OFFSET. If the label is between the extension lines it is centered. All labels placed drawing leaders with vis_DimensionLeader and vis_DimensionRadius are constrained to be a horizontal distance DIMENSION_OFFSET from the angled leader line. By default DIMENSION_LABEL_AUTO is set to VIS_ON.

The parameter DIMENSION_LABEL_POSITION specifies the position on the label that linear dimension labels will be anchored. A position of VIS_LEFT will anchor the label at its left extent. A position of VIS_RIGHT will anchor the label at its right extent. By default DIMENSION_LABEL_POSITION is set to VIS_CENTER.

The parameter DIMENSION_LINEAR_ALIGN specifies the orientation of linear dimensions with respect to the local coordinate system. DIMENSION_VERTICAL will orient the dimension line parallel to the local y' axis; DIMENSION_HORIZONTAL will orient it parallel to the local x' axis; DIMENSION_INDEPTH will orient it parallel to the local z' axis; DIMENSION_ALIGNED will orient it parallel with the line between the two feature delineation points. By default DIMENSION_LINEAR_ALIGN is set to DIMENSION_HORIZONTAL.

The parameter DIMENSION_INSIDE specifies that linear dimension lines will be drawn on the inside of the extension lines. By default DIMENSION_INSIDE is set to VIS_ON.

The parameters DIMENSION_NOHEAD_FIRST and DIMENSION_NOHEAD_SECOND are designed to control the drawing of arrow heads on linear dimension lines. By default DIMENSION_NOHEAD_FIRST and DIMENSION_NOHEAD_SECOND are set to VIS_OFF. Note that all arrow heads are disabled if the visualization context VIS_VECTORNOHEAD flag is enabled.

Toggle the use of a stroked font as opposed to a raster font for drawing labels. By default DIMENSION_STROKEFONT is set to VIS_ON.


Table of Contents , Dimension

NAME

vis_DimensionSetPlane - set dimension plane

C SPECIFICATION

void vis_DimensionSetPlane (vis_Dimension *dimension,
                            Vfloat right[3], 
                            Vfloat up[3])

INPUT ARGUMENTS

dimension    Pointer to Dimension object
right        Vector in direction of dimension local x' axis.
up           Vector in direction of dimension local y' axis.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_COMPUTE is generated if right and up do not define a unique dimension plane.

DESCRIPTION

Set dimension plane. The dimension plane is specified as the plane formed by the right and up vectors. The right vector defines the x' direction. The y' direction lies in the dimension plane perpendicular to x'. The normal to the dimension plane defines the z' axis. The right and up vectors need not be normalized or orthogonal but they cannot be parallel. By default the right vector is (1.,0.,0.) and the up vector is (0.,1.,0.).

Get right and up as output arguments using

     void vis_DimensionGetPlane (vis_Dimension *dimension,
                                 Vfloat right[3], 
                                 Vfloat up[3])


Table of Contents , Dimension

NAME

vis_DimensionAngular - draw angular dimension

C SPECIFICATION

void vis_DimensionAngular (vis_Dimension *dimension,
                           Vfloat x1[3],
                           Vfloat x2[3],
                           Vfloat xcenter[3], 
                           Vfloat xlabel[3],
                           Vchar *label)

INPUT ARGUMENTS

dimension    Pointer to Dimension object.
x1           First feature location
x2           Second feature location
xcenter      Center of circle    
xlabel       Dimension line location
label        Label

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw an angular dimension with two extension lines originating from xcenter passing through x1 and x2. The length of the extension lines is computed as the maximum distance of either x1 or x2 from xcenter.

The position of xlabel relative to the extension lines determines where the label is drawn: to the left, right or in the center of the extension lines. If xlabel is to the left or right of the extension lines and DIMENSION_LABEL_AUTO is on then label will be drawn a fixed distance to the left or right from the extension lines, otherwise the label will be drawn at xlabel. If xlabel is inside the extension lines then label will be drawn centered.

                                                                           


Table of Contents , Dimension

NAME

vis_DimensionLeader - draw a leader dimension

C SPECIFICATION

void vis_DimensionLeader (vis_Dimension *dimension,
                          Vfloat x[3], 
                          Vfloat xlabel[3], 
                          Vchar *label)

INPUT ARGUMENTS

dimension    Pointer to Dimension object.
x            Feature location    
xlabel       Label location 
label        Label 

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a leader line pointing to x. A line will be drawn angled from x to a vertical position defined by xlabel. A horizontal line is drawn from the angled leader line to the position of the label. The angle made by the leader line with respect to the horizontal direction may be constrained to be a specified angle by setting the angle using vis_DimensionSetParamf with parameter DIMENSION_ANGLE and then enabling the angle constrain using vis_DimensionSetParami with parameter DIMENSION_ANGLE_LOCK. The position of x relative to xlabel determines how the horizontal segment of the leader line is drawn, left or right. If DIMENSION_LABEL_AUTO is enabled then label will be drawn a fixed offset, DIMENSION_OFFSET, specified using vis_DimensionSetParamf from the angled leader line otherwise the label will be drawn at xlabel.


Table of Contents , Dimension

NAME

vis_DimensionLinear - draw a linear dimension

C SPECIFICATION

void vis_DimensionLinear (vis_Dimension *dimension,
                          Vfloat x1[3], 
                          Vfloat x2[3], 
                          Vfloat xlabel[3], 
                          Vchar *label)

INPUT ARGUMENTS

dimension    Pointer to Dimension object.
x1           First feature location    
x2           Second feature location    
xlabel       Dimension line location 
label        Label 

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a linear dimension with extension lines originating from x1 and x2 and extending to the position defined by xlabel. The position of xlabel relative to the extension lines determines where the label is drawn: to the left, right or in the center of the extension lines.

If xlabel is to the left or right of the extension lines and DIMENSION_LABEL_AUTO is on then label will be drawn a fixed distance to the left or right from the extension lines, otherwise the label will be drawn at xlabel. If xlabel is inside the extension lines then label will be drawn centered.

If DIMENSION_LINEAR_ALIGN is set to DIMENSION_HORIZONTAL then the dimension line will be drawn passing through the point xlabel parallel to the dimension plane x' axis; if it is set to DIMENSION_VERTICAL it will be drawn parallel to the y' axis; if it is set to DIMENSION_INDEPTH it will be drawn parallel to the z' axis; if it is set to DIMENSION_ALIGNED then it will be drawn parallel to the two feature delineation points x1 and x2.


Table of Contents , Dimension

NAME

vis_DimensionRadius - draw a circle radius leader line dimension

C SPECIFICATION

void vis_DimensionRadius (vis_Dimension *dimension,
                          Vfloat x[3], 
                          Vfloat xcenter[3], 
                          Vfloat xlabel[3], 
                          Vchar *label)

INPUT ARGUMENTS

dimension    Pointer to Dimension object.
x            Feature location    
xcenter      Center of circle    
xlabel       Label location 
label        Label 

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_COMPUTE is generated if the center of the circle, xcenter is coincident with the feature location, x.

DESCRIPTION

Draw a circle radius leader line pointing to x and marking the center of a circle of radius |x - xcenter|. A line will be drawn from x though xcenter to a vertical position defined by xlabel. A cross will be drawn at xcenter. If DIMENSION_LABEL_AUTO is enabled then label will be drawn a fixed offset, DIMENSION_OFFSET, specified using vis_DimensionSetParamf from the angled leader line otherwise the label will be drawn at xlabel.


Table of Contents

9.10 Stroked Text - Font

Use Font to generate stroked text positioned and oriented in 3D space. A full set of text transformations are available including 3D extrusion. Extrusion allows light source shaded 3D text to be generated. A Font object, when first created, contains a built-in constant space font. A selection of other fonts may be established in a Font object by reading one of the font description files provided with VisTools. Font visualization entities are not subject to isosurface clipping. The functions associated with a Font object are the following.

Instance a Font object using vis_FontBegin. Once a Font object is instanced, set the attribute objects using vis_FontSetObject and set display parameters using vis_FontSetParami and vis_FontSetParamf. Text is drawn in a plane parallel to the plane specified by vis_FontSetPlane. A text string is drawn at a given point in the font represented by the Font object using vis_FontText. The length of a text string may be returned using vis_FontLength.

Table of Contents

9.11 Attribute Objects

A Font object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes to generate a font visualization entity. A DrawFun object is required but VisContext, ColorMap and TransMap objects are optional. A Font object uses the following VisContext components.

Color
Text color
DeviceSize
Size of character in device coordinates
Flags
VIS_BACKPLANEFLIP flips the text string if the normal to the character plane is pointing away from the viewer. This option requires the current modelview matrix.
LineWidth
Line width of text
LineStyle
Line style of text
Position
Text string alignment. The alignment specifies the anchor point of the text string relative to the text string extent.
ProjMatrix
Projection matrix, used with device sizing
Shade
Flag to apply light source shading
Size
Size of character in world coordinates
SizeType
Specify either world coordinate or device coordinate sizing
Transparency
Text extrusion transparency
Viewport
Viewport limits, used with device sizing
XfmMatrix
Modelview matrix, used with device sizing and back plane flip
If the VisContext attribute object pointer is NULL, then stroked text is generated without referencing the VisContext, ColorMap and TransMap objects. No attribute drawing functions are invoked, all text is drawn with line and vertex shaded polygon graphics primitives assuming the current color, line width, line style and transparency.

Figure 9-4 illustrates a number of font styles.


Figure 9-4, Font Styles
Table of Contents

9.12 Function Descriptions

The currently available Font functions are described in detail in this section.


Table of Contents , Font

NAME

*vis_FontBegin - create an instance of a Font object

C SPECIFICATION

vis_Font *vis_FontBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Font object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Font object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. Font path and plane are oriented along the global coordinate x and y axes. Font direction is VIS_RIGHT and font alignment is VIS_LEFT and VIS_BOTTOM.

Destroy an instance of a Font object using

     void vis_FontEnd (vis_Font *font)

Return the current value of a Font object error flag using

     Vint vis_FontError (vis_Font *font)


Table of Contents , Font

NAME

vis_FontSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_FontSetObject (vis_Font *font,
                        Vint objecttype,
                        Vobject *object)

INPUT ARGUMENTS

font         Pointer to Font object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_VISCONTEXT         VisContext object
             =VIS_COLORMAP           ColorMap object
             =VIS_TRANSMAP           TransMap object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object.


Table of Contents , Font

NAME

vis_FontSetParam - set font display parameters

C SPECIFICATION

void vis_FontSetParamf (vis_Font *font,
                        Vint ptype,
                        Vfloat fparam)

void vis_FontSetParami (vis_Font *font,
                        Vint ptype,
                        Vint iparam)

INPUT ARGUMENTS

font         Pointer to Font object.
ptype        Type of display parameter to set
             =FONT_ANGLE              Set text string rotation angle
             =FONT_DIRECTION          Set text string direction
             =FONT_EXPANSION          Set text string expansion factor
             =FONT_EXTRUSION          Set text string extrusion distance
             =FONT_SLANT              Set font character slant
             =FONT_SPACING            Set font character spacing
fparam       Specifies the float value that ptype will be set to.
iparam       Specifies the integer value that ptype will be set to.
             =VIS_LEFT                Direction to left
             =VIS_RIGHT               Direction to right
             =VIS_TOP                 Direction to top
             =VIS_BOTTOM              Direction to bottom

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified. VIS_ERROR_ENUM is generated if an improper FONT_DIRECTION parameter is specified.

DESCRIPTION

Set font rotation angle. The rotation angle is in the character plane and provides a convenient means of rotating the character direction without changing the overall orientation. The text is rotated about the anchor point input using vis_FontText. By default FONT_ANGLE is set to 0.

Set text string direction relative to font path. By default FONT_DIRECTION is set to VIS_RIGHT.

Set font expansion factor. The expansion factor scales the width of each character such that the character height to width aspect ratio is changed. An expansion factor less then unity contracts the width of a character, a factor greater than unity increases the width. The expansion factor also applies to the amount of space between characters. By default FONT_EXPANSION is set to 1.

Set the distance that stroked text characters are to be extruded. The extrusion distance is normal to the font plane. Font extrusion results in a shaded 3D text string. By default FONT_EXTRUSION is set to 0.

Set the slant of stroked text characters. A slant of unity results in characters italicized at a 45 degree angle. A slant of zero results in no slant. By default FONT_SLANT is set to 0.

Set the spacing of stroked text characters. The character spacing inserts additional space between characters within a text string without changing the character size. By default FONT_SPACING is set to 0.


Table of Contents , Font

NAME

vis_FontSetPlane - set font orientation

C SPECIFICATION

void vis_FontSetPlane (vis_Font *font,
                       Vfloat path[3], 
                       Vfloat plane[3])

INPUT ARGUMENTS

font         Pointer to Font object.
path         Vector in direction of font path.
plane        Vector in direction of font plane.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_COMPUTE is generated if path and plane do not define a unique orientation plane.

DESCRIPTION

Set font orientation plane. The path and plane vectors need not be normalized or orthogonal but they can not be parallel. The font orientation plane is formed as the plane defined by the path and plane vectors. Text is drawn at a specified anchor point using vis_FontText. The text is drawn in a plane passing through the anchor point parallel to the orientation plane. By default the path vector is (1.,0.,0.) and the plane vector is (0.,1.,0.).

Get path and plane as output arguments using

     void vis_FontGetPlane (vis_Font *font,
                            Vfloat path[3], 
                            Vfloat plane[3])


Table of Contents , Font

NAME

vis_FontLoad - read a font description file

C SPECIFICATION

void vis_FontLoad (vis_Font *font,
                   Vint ifont)

INPUT ARGUMENTS

font         Pointer to Font object.
ifont        Stroked font type to load
             =FONT_STANDARD          Default fixed width font
             =FONT_GREEK             Greek letters
             =FONT_ITALICS           Italics
             =FONT_ROMAN1            Roman
             =FONT_ROMAN2            Roman
             =FONT_BOLDSCRIPT        Bold script
             =FONT_FILLROMAN1        Outlined roman
             =FONT_FILLROMAN2        Outlined roman
             =FONT_GOTHIC            Gothic
             =FONT_SCRIPT            Script
             =FONT_UNCIAL            Interesting

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ifont is specified.

DESCRIPTION

Load a built-in stroked font description. Since all the available fonts are memory resident, font loading is not a time consuming operation.


Table of Contents , Font

NAME

vis_FontText - draw font text string

C SPECIFICATION

void vis_FontText (vis_Font *font,
                   Vfloat x[3],
                   const Vchar text[])

INPUT ARGUMENTS

font         Pointer to Font object.
x            Anchor point of text string
text         Text string

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a text string anchored at x.


Table of Contents , Font

NAME

vis_FontLength - compute length of text string

C SPECIFICATION

void vis_FontLength (vis_Font *font,
                     const Vchar text[],
                     Vfloat *length)

INPUT ARGUMENTS

font         Pointer to Font object.
text         Text string

OUTPUT ARGUMENTS

length       Length of text string

DESCRIPTION

Compute the length of a text string.


Table of Contents

9.13 Markers and Glyphs - Glyph

Use Glyph to generate a variety of 2D and 3D icons from simple filled rectangles to 3D ellipsoids. Glyph objects are used extensively by other modules in VisTools to draw markers, cylindrical line styles, etc. Glyph visualization entities are not subject to isosurface clipping. The functions associated with a Glyph object are the following.

Instance a Glyph object using vis_GlyphBegin. Once a Glyph object is instanced, set the attribute objects using vis_GlyphSetObject. All glyphs are oriented to a direction cosine matrix in 3D space. By default the direction cosine matrix is aligned with the global coordinate system. Use vis_GlyphSetOrientTriad, vis_GlyphSetOrientZ or vis_GlyphSetOrientXY to set the current orientation.

The following convention for the direction cosine matrices of a local coordinate system is used. Given that x',y' and z' are three orthonormal vectors indicating the direction of the local coordinate axes in the global coordinate system (x,y,z), then the direction cosine matrix, tm for this local coordinate system is defined as:

tm[0][0] = x'x  tm[0][1] = x'y  tm[0][2] = x'z
tm[1][0] = y'x  tm[1][1] = y'y  tm[1][2] = y'z
tm[2][0] = z'x  tm[2][1] = z'y  tm[2][2] = z'z
where y'x, for example, is the global x coordinate of the y' unit vector.

Table of Contents

9.14 Attribute Objects

A Glyph object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes to generate a glyph visualization entity. A DrawFun object is required but VisContext, ColorMap and TransMap objects are optional. A Glyph object uses the following VisContext components.

Color
Glyph color
LineWidth
Line width of glyph line primitives
LineStyle
Line style of glyph line primitives
Refinement
Level of refinement for drawing curved lines and surfaces. As a general rule a value of 0 draws curves with 8 subdivisions. A value of 1 or greater uses 16 subdivisions. A value less than zero uses 4 subdivisions.
Shade
Flag to apply light source shading
Transparency
Transparency of glyph polygon primitives
If the VisContext attribute object pointer is NULL, then stroked glyphs are generated without referencing the VisContext, ColorMap and TransMap objects. No attribute drawing functions are invoked, all glyphs are drawn with line and flat shaded polygon graphics primitives assuming the current color, line width, line style and transparency. Zero level refinement is assumed.

Table of Contents

9.15 Function Descriptions

The currently available Glyph functions are described in detail in this section.


Table of Contents , Glyph

NAME

*vis_GlyphBegin - create an instance of a Glyph object

C SPECIFICATION

vis_Glyph *vis_GlyphBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Glyph object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Glyph object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. Glyph orientation is along the global coordinate axes. Refinement is zero level.

Destroy an instance of a Glyph object using

     void vis_GlyphEnd (vis_Glyph *glyph)

Return the current value of a Glyph object error flag using

     Vint vis_GlyphError (vis_Glyph *glyph)


Table of Contents , Glyph

NAME

vis_GlyphSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_GlyphSetObject (vis_Glyph *glyph,
                         Vint objecttype,
                         Vobject *object)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_VISCONTEXT         VisContext object
             =VIS_COLORMAP           ColorMap object
             =VIS_TRANSMAP           TransMap object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object.


Table of Contents , Glyph

NAME

vis_GlyphSetOrientTriad - set glyph orientation to global axes

C SPECIFICATION

void vis_GlyphSetOrientTriad (vis_Glyph *glyph,
                              Vfloat tm[3][3])

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
tm           Direction cosine matrix of glyph orientation.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set glyph orientation to global axis.

Get tm as an output argument using

     void vis_GlyphGetOrientTriad (vis_Glyph *glyph,
                                   Vfloat tm[3][3])


Table of Contents , Glyph

NAME

vis_GlyphSetOrientZ - set glyph orientation in z direction

C SPECIFICATION

void vis_GlyphSetOrientZ (vis_Glyph *glyph,
                          Vfloat vz[3])

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
vz           Vector of local z axis.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set glyph orientation z axis. The input vector, vz, need not be a unit vector. The local x and y axes are computed internally to be orthonormal to the z axis. This function is useful for orienting glyphs such as vectors which have symmetry about the z axis.


Table of Contents , Glyph

NAME

vis_GlyphSetOrientXY - set glyph orientation in x,y directions

C SPECIFICATION

void vis_GlyphSetOrientXY (vis_Glyph *glyph,
                          Vfloat vx[3],
                          Vfloat vy[3])

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
vx           Vector of local x axis.
vy           Vector defining the half plane of the local y axis.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set glyph orientation x and y axes. The input vectors, vx and vy, need not be unit vectors or perpendicular. The local x axis lies along vx, the local y axis is perpendicular to x lying in the plane defined by vx and vy, the local z axis is constructed to be perpendicular to the x and y axes.


Table of Contents , Glyph

NAME

vis_GlyphArrow2D vis_GlyphArrow2D3D vis_GlyphArrow3D - draw arrows

C SPECIFICATION

void vis_GlyphArrow2D (vis_Glyph *glyph,
                       Vfloat x[3], 
                       Vfloat l, Vfloat r, Vfloat h, 
                       Vfloat off,
                       Vint head, 
                       Vint tail, Vint fill, Vint push, Vint cap)
void vis_GlyphArrow2D3D (vis_Glyph *glyph,
                         Vfloat x[3], 
                         Vfloat l, Vfloat r, Vfloat h, 
                         Vfloat off,
                         Vint head, 
                         Vint tail, Vint fill, Vint push, Vint cap)
void vis_GlyphArrow3D (vis_Glyph *glyph,
                       Vfloat x[3], 
                       Vfloat l, Vfloat r, Vfloat h, 
                       Vfloat off,
                       Vint head, 
                       Vint tail, Vint fill, Vint push, Vint cap)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of tip of arrow.
l            Length of arrow
r            Radius of head of arrow
h            Height of head of arrow
off          Offset of arrow tip from x along z axis
head         Number of arrow heads.
tail         Arrow tail flag
             =VIS_OFF      Do not display tail
             =VIS_ON       Display tail
fill         Arrow head fill flag
             =VIS_OFF      Do not fill arrow head
             =VIS_ON       Fill arrow head
push         Arrow head push flag
             =VIS_OFF      Do not draw arrow head in push style
             =VIS_ON       Draw arrow head in push style
cap          Arrow head cap flag
             =VIS_OFF      Do not cap arrow head
             =VIS_ON       Cap arrow head

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw arrows. The tip of the head of the arrow is anchored at x. Arrows are oriented along the z axis of the orientation triad. 2D arrows are drawn with a planar head and a simple line tail. The head is drawn in the x,z plane defined by the orientation triad. 2D, 3D mixed arrows are drawn with a 3D conical head and a simple line tail. If the refinement for a mixed 2D, 3D arrow is -1 then the head is drawn as a tetrahedron. 3D arrows are drawn with cylindrical shafts and conical heads.

If an offset, off, is specified then the anchor point is moved a distance off along the shaft of the arrow from the arrow tip. Double headed arrows may be generated by setting head = 2. Arrows are oriented along the z axis of the orientation triad. If the push flag is set, the arrow head is drawn to appear to "push" the vector tail.


Table of Contents , Glyph

NAME

vis_GlyphBox - draw a box

C SPECIFICATION

void vis_GlyphBox(vis_Glyph *glyph,
                  Vfloat x[3], 
                  Vfloat sx, 
                  Vfloat sy, 
                  Vfloat sz,
                  Vint fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of centroid of box
sx           Length in x direction
sy           Length in y direction
sz           Length in z direction
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill box

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a box in space centered at x. The box may be optionally filled.


Table of Contents , Glyph

NAME

vis_GlyphCircle - draw a circle in a plane

C SPECIFICATION

void vis_GlyphCircle (vis_Glyph *glyph,
                      Vfloat x[3], 
                      Vfloat r, 
                      Vfloat off,
                      Vint   fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of centroid of circle
r            Radius of circle
off          Offset of circle center along z axis.
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a circle in the x,y plane centered at x. The circle may be optionally filled.


Table of Contents , Glyph

NAME

vis_GlyphCone - draw a cone

C SPECIFICATION

void vis_GlyphCone (vis_Glyph *glyph,
                    Vfloat x[3],
                    Vfloat r,
                    Vfloat h,
                    Vfloat off,
                    Vint fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of base of cone
r            Radius of base of cone
h            Height of cone
off          Offset of cone base along z axis.
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a cone with the center of the base anchored at x and aligned so that the height direction is along the z axis of the orientation triad.


Table of Contents , Glyph

NAME

vis_GlyphConicalFrustum - draw a conical frustum

C SPECIFICATION

void vis_GlyphConicalFrustum (vis_Glyph *glyph,
                              Vfloat x[3],
                              Vfloat r1,
                              Vfloat r2,
                              Vfloat h,
                              Vfloat off,
                              Vint fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of base of conical frustum
r1           Radius of base of conical frustum
r2           Radius of top of conical frustum
h            Height of conical frustum
off          Offset of base of conical frustum along z axis.
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a conical frustum with the base anchored at x and aligned so that the height direction is along the z axis of the orientation triad.


Table of Contents , Glyph

NAME

vis_GlyphCylinder - draw a cylinder

C SPECIFICATION

void vis_GlyphCylinder (vis_Glyph *glyph,
                        Vfloat x[3], 
                        Vfloat r, 
                        Vfloat h, 
                        Vfloat off,
                        Vint fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of base of cylinder
r            Radius of cylinder
h            Height of cylinder
off          Offset of cylinder base along z axis.
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a cylinder with the center of one end, the base, anchored at x and aligned so that the height direction is along the z axis of the orientation triad.


Table of Contents , Glyph

NAME

vis_GlyphDisk - draw disk

C SPECIFICATION

void vis_GlyphDisk (vis_Glyph *glyph,
                    Vfloat x[3],
                    Vfloat r,
                    Vfloat h,
                    Vfloat off,
                    Vint fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of base of disk
r            Radius of disk
h            Height of disk
off          Offset of disk base along z axis.
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a disk with the center of the base of the disk anchored at x and aligned so that the height direction is along the z axis of the orientation triad. This primitive is much like vis_GlyphCylinder except that the ends are capped.


Table of Contents , Glyph

NAME

vis_GlyphEllipsoid - draw an ellipsoid

C SPECIFICATION

void vis_GlyphEllipsoid (vis_Glyph *glyph,
                         Vfloat x[3], 
                         Vfloat sx, Vfloat sy, Vfloat sz)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of centroid of ellipse
sx           Length in x direction
sy           Length in y direction
sz           Length in z direction

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw an ellipse centered at x. The ellipse is drawn with filled polygons.


Table of Contents , Glyph

NAME

vis_GlyphRectangle - draw a rectangle

C SPECIFICATION

void vis_GlyphRectangle (vis_Glyph *glyph,
                         Vfloat x[3], 
                         Vfloat w, 
                         Vfloat h, 
                         Vfloat off,
                         Vint fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of center of rectangle
w            Width of rectangle
h            Height of rectangle
off          Offset of rectangle along z axis.
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a rectangle centered at x. The rectangle is oriented in the x,y plane, the width is in the x direction and the height is in the y direction. The rectangle may be drawn either as an outlined or a filled rectangle.


Table of Contents , Glyph

NAME

vis_GlyphSphere - draw a sphere

C SPECIFICATION

void vis_GlyphSphere (vis_Glyph *glyph,
                      Vfloat x[3], 
                      Vfloat r,
                      Vint fill)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of center of sphere
r            Radius of sphere
fill         Fill flag
             =VIS_OFF      Do not fill
             =VIS_ON       Fill

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a sphere centered at x with radius r.


Table of Contents , Glyph

NAME

vis_GlyphTriaxis - draw triaxis

C SPECIFICATION

void vis_GlyphTriaxis(vis_Glyph *glyph,
                      Vfloat x[3],
                      Vfloat sx,
                      Vfloat sy,
                      Vfloat sz,
                      Vfloat off)

INPUT ARGUMENTS

glyph        Pointer to Glyph object.
x            Coordinate location of center of triaxis
sx           Axis length in x direction
sy           Axis length in y direction
sz           Axis length in z direction
off          Offset of triaxis along z axis.

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a triaxis centered at x. A triaxis consists of 3 axes, represented as lines, drawn along the x, y and z directions. The lengths of the axes in each direction are given by sx, sy and sz respectively. If an axis length is input as zero it is not drawn.


Table of Contents

9.16 Tesselation Tools - Tess

Use Tess to draw a tesselation of a two-dimensional region delineated by possibly overlapping arcs and segments. Arcs are first tesselated into segments whose size is controlled by VisContextSetSizeType prior to generating a tesselation of the area. The functions associated with a Tess object are the following.

Instance a Tess object using vis_TessBegin. Once a Tess object is instanced, set the attribute objects using vis_TessSetObject, and the drawing parameters with either vis_TessSetParami and vis_TessSetParamd. Use vis_TessDef to indicate the creating of a new region. Points are added with vis_TessSetPoint, straight lines with vis_TessSetLine, and arcs with vis_TessSetArc. All lines and arcs are oriented such that if one defines a local x direction as going from the first to the second point on the curve, and with the z direction going towards the observer, then the region of interest is in the local y direction.

Arcs are tesselated into segments whose size can be defined either in world or in device coordinates. The size type is set in the VisContext object using VisContextSetSizeType.

All input points, lines and arcs are tested for intersection. The intersection tolerance is specified using vis_TessSetParamd with parameter TESS_INTERTOL. Lines and arcs are divided and points are inserted where intersections occur. Coincident points are merged. Unconnected points are tested for intersection with lines and arcs. All points are included in the final tessellation.

All point locations are 3D world coordinates. All intersection and tesselation calculations are performed in a plane specified by a normal vector input using vis_TessSetNormal. By default the normal is a vector pointing in the positive z-coordinate direction.

The function vis_TessDraw performs the actual tesselation of the input geometry. This operation is subject to failure if the input geometry is not closed or there are very small features. Use vis_TessGetInteger to query for tesselation information to see if a subsequent vis_TessDraw operation was successful. The function vis_TessWrite is provided to write a complete description of the defined input geometry to a file. The primary use of this file is to encapsulate cases in which the Tess module fails in some respect. This output file can then be made available to Visual Kinematics for failure diagnosis of Tess tesselation algorithms.

Table of Contents

9.17 Attribute Objects

A Tess object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes to generate a tesselation visualization entity. DrawFun and VisContext objects are required but ColorMap and TransMap objects are optional. A Tess object uses the following VisContext components.

Color
Polygon color
DeviceSize
Length of arc segment in device coordinates.
MinorColor
Edge color
LineWidth
Line width of line primitives
LineStyle
Line style of line primitives
Fill
Polygon display flag
Edge
Polygon edge display flag
ProjMatrix
Projection matrix, used with device sizing
Size
Length of arc segment in world coordinates.
SizeType
Specify either world coordinate or device coordinate sizing
Viewport
Viewport limits, used with device sizing
XfmMatrix
Modelview matrix, used with device sizing
Trans
Transparency flag
If the ColorMap attribute object pointer is NULL, then it is assumed that vgl_DrawFunColor has been called prior to vis_TessDraw.

Table of Contents

9.18 Function Descriptions

The currently available Tess functions are described in detail in this section.


Table of Contents , Tess

NAME

*vis_TessBegin - create an instance of a Tess object

C SPECIFICATION

vis_Tess *vis_TessBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Tess object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Tess object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a Tess object using

     void vis_TessEnd (vis_Tess *tess)

Return the current value of a Tess object error flag using

     Vint vis_TessError (vis_Tess *tess)


Table of Contents , Tess

NAME

vis_TessGetInteger - get integer tesselation information

C SPECIFICATION

void vis_TessGetInteger (vis_Tess *tess,
                         Vint type,
                         Vint iparam[])

INPUT ARGUMENTS

tess         Pointer to Tess object.
type         Type of integer information to query
             =TESS_NUMUNREC          Number of unrecovered edges
             =TESS_NUMDRAWTRI        Number of triangles drawn
             =TESS_NUMDRAWEDGE       Number of edges drawn

OUTPUT ARGUMENTS

iparam       Returned integer information

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Query for integer tesselation information. If the number of unrecovered edges is non-zero, then the input geometry has a set of very small features which cause a numerical problem. If the number of drawn triangles is zero, then the input geometry is not closed.


Table of Contents , Tess

NAME

vis_TessSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_TessSetObject (vis_Tess *tess,
                        Vint objecttype,
                        Vobject *object)

INPUT ARGUMENTS

tess         Pointer to Tess object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_VISCONTEXT         VisContext object
             =VIS_COLORMAP           ColorMap object
             =VIS_TRANSMAP           TransMap object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object.


Table of Contents , Tess

NAME

vis_TessSetParamd - set tesselation double precision parameters.

C SPECIFICATION

void vis_TessSetParamd (vis_Tess *tess,
                        Vint type,
                        Vdouble paramd)

INPUT ARGUMENTS

tess         Pointer to Tess object.
type         Parameter type
             =TESS_INTERTOL          Tolerance for curve intersection
paramd       Parameter value

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Set tesselation floating point controlling parameters.

Use TESS_INTERTOL to specify the tolerance used to compute intersections of lines and arcs. Defaults to 2.e-7.


Table of Contents , Tess

NAME

vis_TessSetParami - set tesselation integer parameters.

C SPECIFICATION

void vis_TessSetParami (vis_Tess *tess,
                        Vint type,
                        Vint parami)

INPUT ARGUMENTS

tess         Pointer to Tess object.
type         Parameter type
             =TESS_EDGE              Type of edge to be drawn
parami       Parameter value
             =TESS_EDGE_ALL          Display all generated edges
             =TESS_EDGE_BOUND        Display all tesselated boundaries
             =TESS_EDGE_INPUT        Display the input curves
             =TESS_EDGE_DANGLING     Display dangling edges only
             =TESS_EDGE_OUTLINE      Display only the region's outline

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if either an improper type or an improper parami are specified.

DESCRIPTION

Set tesselation integer controlling parameters.

The parameter TESS_EDGE controls which edges are displayed if the Edge parameter in VisContext is turned on. TESS_EDGE_ALL displays all generated edges; TESS_EDGE_BOUND displays all geometry-related edges. These include the original line segments, as well as the tesselation of arcs. TESS_EDGE_OUTLINE displays edges that are present in only a single polygon and delineate the region of interest from empty space; and TESS_EDGE_INPUT displays the original input curves. In this case, arcs are displayed as two segments, as arcs are defined through three points. TESS_EDGE_DANGLING draws only those edges which are not on or in the interior of a closed loop of line segments. By Default TESS_EDGE is set to TESS_EDGE_OUTLINE.


Table of Contents , Tess

NAME

vis_TessDef - clear object and set new initial parameters

C SPECIFICATION

void vis_TessDef (vis_Tess *tess,
                  Vint npts,
                  Vint nlines)

INPUT ARGUMENTS

tess         Pointer to Tess object.
npts         Initial value for number of points
nlines       Initial value for number of lines and arcs

OUTPUT ARGUMENTS

None

DESCRIPTION

Use TessDef to clear an existing Tess module of its contents and to define initial parameters for a new tesselation. npts and nlines are estimates for the number of points and lines to be set. These values can be exceeded with SetPoint, SetLine, and SetArc.


Table of Contents , Tess

NAME

vis_TessSetArc - input an arc

C SPECIFICATION

void vis_TessSetArc(vis_Tess *tess,
                    Vint id,
                    Vint ix[3])

INPUT ARGUMENTS

tess         Pointer to Tess object.
id           Arc id
ix           Array with 3 points defining the arc

OUTPUT ARGUMENTS

None

DESCRIPTION

Specifies an arc defined by three consecutive points along the arc. The arc is defined from the first point to the third point, passing through the second point. The final tesselation will always contain these three points. Lines and arcs share the same id space.


Table of Contents , Tess

NAME

vis_TessSetLine - input a straight line

C SPECIFICATION

void vis_TessSetLine (vis_Tess *tess,
                      Vint id,
                      Vint ix[2])

INPUT ARGUMENTS

tess         Pointer to Tess object.
id           Line id
ix           Array with the line's two end points.

OUTPUT ARGUMENTS

None

DESCRIPTION

Specifies a straight segment for the tesselation. Lines and arcs share the same id space.


Table of Contents , Tess

NAME

vis_TessSetNormal - set normal to tesselation plane

C SPECIFICATION

void vis_TessSetNormal (vis_Tess *tess,
                        Vfloat v[3])
void vis_TessSetNormaldv (vis_Tess *tess,
                          Vdouble v[3])

INPUT ARGUMENTS

tess         Pointer to Tess object.
v            Normal vector to tesselation plane

OUTPUT ARGUMENTS

None

DESCRIPTION

Specifies a point to be used by lines and arcs.


Table of Contents , Tess

NAME

vis_TessSetPoint - draw a cone

C SPECIFICATION

void vis_TessSetPoint (vis_Tess *tess,
                       Vint id,
                       Vfloat x[3])
void vis_TessSetPointdv (vis_Tess *tess,
                         Vint id,
                         Vdouble x[3])

INPUT ARGUMENTS

tess         Pointer to Tess object.
id           Point id
x            Point coordinates.

OUTPUT ARGUMENTS

None

DESCRIPTION

Specifies a point to be used by lines and arcs.


Table of Contents , Tess

NAME

vis_TessDraw - draw a tesselation

C SPECIFICATION

void vis_TessDraw (vis_Tess *tess)

INPUT ARGUMENTS

tess         Pointer to Tess object.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if no DrawFun or VisContext attribute objects are set.

DESCRIPTION

Draw a tesselation using the geometry defined by points, lines, and arcs. Use vis_TessGetInteger to test for any failures to generate graphics primitives from the input geometry.


Table of Contents , Tess

NAME

vis_TessRead - read input geometry from file

C SPECIFICATION

void vis_TessRead (vis_Tess *tess,
                   Vint type,
                   const Vchar *path)

INPUT ARGUMENTS

tess         Pointer to Tess object.
type         File type
             =SYS_ASCII              ASCII format
             =SYS_BINARY             Binary format
path         File path

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified. SYS_ERROR_FILE is generated if the file can not be opened. SYS_ERROR_FORMAT is generated if the file contents are not correctly formatted.

DESCRIPTION

Read a geometry description from a file which has been previously written by vis_TessWrite. The format of the file is not published and is intended for internal use only.


Table of Contents , Tess

NAME

vis_TessWrite - write input geometry to file

C SPECIFICATION

void vis_TessWrite (vis_Tess *tess,
                        Vint type,
                        const Vchar *path)

INPUT ARGUMENTS

tess         Pointer to Tess object.
type         File type
             =SYS_ASCII              ASCII format
             =SYS_BINARY             Binary format
path         File path

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified. SYS_ERROR_FILE is generated if the file can not be opened. SYS_ERROR_OPERATION is generated if the input surface has not been defined.

DESCRIPTION

Write a geometry description to a file. The contents of the file is intended for internal use only. This function should be called immediately before vis_TessDraw. This file can then be transmitted to Visual Kinematics for debugging purposes. It is suggested that a file extension of .tes be used for ASCII files and .btes be used for BINARY files.


Table of Contents

9.19 Coordinate System Triads - Triad

The Triad module is designed to draw Cartesian, cylindrical, spherical and toroidal coordinate system icons. A coordinate system icon consists of three orthogonal vectors representing the orientation of the coordinate system. As an option, additional details may be drawn to illustrate the shape of the coordinate system or the radius and angle conventions of cylindrical, spherical and toroidal systems. All labelling is optional and may be performed using stroke or raster fonts. The methods associated with a Triad object are the following.

Instance a Triad object using vis_TriadBegin. Once a Triad object is instanced, set the attribute objects using vis_TriadSetObject and set display parameters using vis_TriadSetParami. The triad icon is drawn using vis_TriadDraw.

Coordinate systems are drawn given an origin and orientation relative to the world coordinate system. The orientation is specified by a direction cosine matrix which defines a local x',y',z' rectangular system in world coordinate space. The coordinate system to be drawn by Triad is aligned to the x',y',z' system. A Cartesian system is a rectangular coordinate system characterized by coordinates x',y',z'. A cylindrical system is characterized by coordinates r,theta,z' where theta is the angle about the z' axis (positive x' toward positive y'). An alternate definition of a cylindrical system is available in which theta is the angle about the z' axis (positive y' toward positive x'). A spherical system is characterized by coordinates r,theta,phi where theta is the angle about the z' axis (positive x' toward positive y') and phi is the angle about the x' axis (positive y' toward positive z'). An alternate definition of a spherical system is available (for specific support of NASTRAN spherical coordinate systems) in which theta is the angle about the negative x' axis (positive z' toward positive y') and phi is the angle about the z' axis (positive x' toward positive y'). A toroidal system is characterized by the radius of the torus and coordinates r,theta,phi where theta is the angle about the z' axis (positive x' toward positive y') and phi is the angle about the x' axis (positive y' toward positive z').

The triad display is parameterized in part by the parameters set using vis_TriadSetParami. The basic triad icon consists of three orthogonal vectors showing the orientation axes of the coordinate system. The axes are labeled with X,Y,Z, R,T,Z or R,T,P depending upon whether the coordinate system is Cartesian, cylindrical, spherical or toroidal.

The radius and angle conventions of cylindrical, spherical and toroidal systems may be displayed by setting the parameter TRIAD_DETAIL on. If detail is on, then the orientation axes are labeled as X,Y,Z regardless of coordinate system type. In addition a portion of a filled box, cylinder or sphere may be drawn in the first octant of the triad if TRIAD_SHAPE is set on.

The use of a stroked font as opposed to a raster font for drawing labels may be toggled on or off using the parameter TRIAD_STROKEFONT. The display of labels may be toggled on or off using the parameter TRIAD_LABELS.

The result of drawing triads in various styles are illustrated in Figures 9-5.


Figure 9-5a, Basic Triads

Figure 9-5b, Triads with Detail and Stroked Font

Figure 9-5c, Triads with Detail, Shape and Raster Font
Table of Contents

9.20 Attribute Objects

A Triad object uses a DrawFun, ColorMap, TransMap and VisContext objects to define attributes required to generate a triad icon. All attribute objects are set using vis_TriadSetObject. The ColorMap object is required to define all colors used to draw the triad. The TransMap object is optional and is used only for drawing the triad shape with transparency.

The VisContext attribute object is required for all drawing. The following VisContext components are used.

AColor
Color of X (or R) orientation vector label.
BColor
Color of Y (or T) orientation vector label.
CColor
Color of Z (or P) orientation vector label.
Color
Color of detail labels.
Flags
OR the following flags: VIS_VECTORNOHEAD inhibits the drawing of the head of the orientation axes vectors.
LineStyle
Line style of line drawn vectors.
LineWidth
Line width of line drawn vectors.
MinorColor
Color of detail axes and shape.
MinorLineStyle
Line style of detail axes.
MinorLineWidth
Line width of detail axes.
MinorSize
Size of detail axes and shape.
Size
Size of orientation vector axes.
Trans
Transparency of filled shape.
XColor
Color of X (or R) orientation vector axis.
YColor
Color of Y (or T) orientation vector axis.
ZColor
Color of Z (or P) orientation vector axis.
The Triad object calls the following drawing functions set in the DrawFun attribute object.

Color
ColorIndex
Only if ColorMap object type is COLORMAP_PSEUDOCOLOR.
LineStyle
LineWidth
Polygon
PolyLine
PolyPointDC
Only if raster font labels are drawn
Text
Only if raster font labels are drawn
Trans
TransIndex
Only if TransMap object type is TRANSMAP_INDEX.
Table of Contents

9.21 Function Descriptions

The currently available Triad functions are described in detail in this section.


Table of Contents , Triad

NAME

*vis_TriadBegin - create an instance of a Triad object

C SPECIFICATION

vis_Triad *vis_TriadBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Triad object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Triad object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL, Detail display is off, label drawing is on, shape display is off and stroked fonts are off.

Destroy an instance of a Triad object using

     void vis_TriadEnd (vis_Triad *triad)

Return the current value of a Triad object error flag using

     Vint vis_TriadError (vis_Triad *triad)


Table of Contents , Triad

NAME

vis_TriadDraw - draw a coordinate system triad

C SPECIFICATION

void vis_TriadDraw (vis_Triad *triad,
                    Vint type,
                    Vfloat x[3],
                    Vfloat tm[3][3])

INPUT ARGUMENTS

triad        Pointer to Triad object.
type         Coordinate system type.
             =SYS_CARTESIAN          Cartesian system
             =SYS_CYLINDRICAL        Cylindrical system
             =SYS_CYLINDRICAL_ALT    Cylindrical alternate system
             =SYS_SPHERICAL          Spherical system
             =SYS_SPHERICAL_ALT      Spherical alternate system
             =SYS_TOROIDAL           Toroidal system
x            Origin of triad icon.
tm           Direction cosine matrix of triad orientation.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified. VIS_ERROR_NULLOBJECT is generated if DrawFun, ColorMap and VisContext attribute objects are not set.

DESCRIPTION

Draw a triad representing a coordinate system of type, with the origin at x and orientation tm.


Table of Contents , Triad

NAME

vis_TriadSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_TriadSetObject (vis_Triad *triad,
                          Vint objecttype,
                          Vobject *object)

INPUT ARGUMENTS

triad       Pointer to Triad object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_COLORMAP           ColorMap object
             =VIS_TRANSMAP           TransMap object
             =VIS_VISCONTEXT         VisContext object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object.

Get object as an output argument using

     void vis_TriadGetObject (vis_Triad *triad,
                              Vint objecttype,
                              Vobject **object)


Table of Contents , Triad

NAME

vis_TriadSetParami - set display parameters

C SPECIFICATION

void vis_TriadSetParami (vis_Triad *triad,
                         Vint type,
                         Vint iparam)

INPUT ARGUMENTS

triad       Pointer to Triad object.
type         Type of display parameter to set
             =TRIAD_DETAIL            Toggle display of detail showing
                                      radius and angle conventions.
             =TRIAD_LABELS            Toggle display of all labels.
             =TRIAD_SHAPE             Toggle display of filled shape
             =TRIAD_STROKEFONT        Toggle use of stroked font labels.
iparam       Specifies the integer value that type will be set to.
             =VIS_ON                  Enable
             =VIS_OFF                 Disable

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Toggle the display of coordinate system detail which illustrates the radius and angle conventions of cylindrical, spherical and toroidal coordinate system. By default TRIAD_DETAIL is set to VIS_OFF.

Toggle the display of all labels. By default TRIAD_LABELS is set to VIS_ON.

Toggle the display of coordinate system shape. The shape consists of a portion of a filled box, cylinder, sphere or torus drawn in the first octant of the triad for Cartesian, cylindrical, spherical or toroidal systems respectively. An additional condition for shape drawing is TRIAD_DETAIL must be on. By default TRIAD_SHAPE is set to VIS_OFF.

Toggle the use of a stroked font as opposed to a raster font for drawing labels. By default TRIAD_STROKEFONT is set to VIS_OFF.