10. Manipulators - HandleBox,PolyBox,WorkPlane

The manipulator objects are designed to facilitate drawing glyphs with pickable handles which provide a user interface for manipulating, querying and constructing 3D geometry.

The HandleBox module is used to manipulate a rectilinear box oriented to the world coordinate system containing six clipping planes. The polybox may also be used for picking purposes.

The PolyBox module is used to construct polygons in the plane of the graphics screen which can be used for clipping and picking purposes.

The WorkPlane module is used to draw planar rectangular grids arbitrarily oriented in space to use as a reference for geometry construction. The work plane may be optionally used as a clipping plane.

Table of Contents

10.1 Handle Box - HandleBox

Use HandleBox to manipulate a rectilinear box in 3D space. The handlebox is oriented to the world coordinate axes and contains selectable handles at each of its eight corners to translate any of the six individual faces of the box. The six faces are meant to be used primarily as clipping planes. The box may be used for node or element picking.

The following functions are associated with a HandleBox object.

Begin and end an instance of an object, return object error flag

*vis_HandleBoxBegin     - create an instance of a HandleBox object
vis_HandleBoxEnd        - destroy an instance of a HandleBox object
vis_HandleBoxError      - return HandleBox object error flag

Set attributes

vis_HandleBoxGetClipPlanes - get clipping plane equations
vis_HandleBoxSetExtent  - set handlebox extent
             GetExtent  - get handlebox extent
vis_HandleBoxGetBox     - get eight corners of handlebox
vis_HandleBoxSetObject  - set pointers to attribute objects.
             GetObject  - get pointers to attribute objects.
vis_HandleBoxSetParami  - set handlebox display parameters
             GetParami  - get handlebox display parameters

Operations

vis_HandleBoxTestHit    - test for handle hit
vis_HandleBoxGetHit     - get internal hit status
vis_HandleBoxInitHit    - initialize internal hit status
vis_HandleBoxCurrentDrag - get current drag status
vis_HandleBoxDrag       - drag the handlebox 
vis_HandleBoxDraw       - draw the handlebox

Instance a HandleBox object using vis_HandleBoxBegin. Once a HandleBox object is instanced, define the extents of the handlebox using vis_HandleBoxSetExtent. The function vis_HandleBoxSetParami may be used to toggle various aspects of the handlebox display. The handlebox manipulation handles consist of 3 vectors at each corner. Each vector is normal to one of the three faces connected to a given corner. Therefore each vector uniquely identifies a face and a direction. Use vis_HandleBoxTestHit to check for manipulation handle hits at a given screen location. Use vis_HandleBoxGetHit to get details of the picked handles. Use vis_HandleBoxInitHit to clear the picked handles.

Figure 10-1, HandleBox

The vis_HandleBoxDraw function is used to draw the handlebox. Any picked handles detected with vis_HandleBoxTestHit will be highlighted. The picked handles may be used with the vis_HandleBoxDrag function to interactively translate the faces of the handlebox.

The handlebox is primarily meant to be used as 3 sets of parallel clipping planes. The user may either activate an internal call to the vgl_DrawFunClipPlane function for each plane or query for the current clipping plane equations using vis_HandleBoxGetClipPlanes and manage the clipping plane interface to the graphics subsystem externally.

The function vis_HandleBoxGetBox may be used to return the world coordinates of the eight corners of the handlebox. This array of world coordinates may be passed directly to the Space object function vis_SpaceBoxGroup to query for all element entities lying in the box or vis_SpaceBoxNodeGroup to query for all node entities lying in the box. Selected faces or edges of the box may be passed to vis_SpacePlaneGroup or vis_SpaceLineGroup to select elements intersecting the respective face or edge.

Table of Contents

10.2 Attribute Objects

A HandleBox object uses ColorMap, DrawFun and VisContext objects to define attributes required to generate a handlebox visualization entity. A HandleBox object uses the following VisContext components.

Color: Handles
ColorA: Handle highlight color
LineWidth: Edge width
MinorColor: Edge color
ProjMatrix: Projection matrix, used for picking
Viewport: Viewport, used for picking
XfmMatrix: Modelview matrix, used for picking

A HandleBox object references the following DrawFun functions.

vgl_DrawFunClipPlane
vgl_DrawFunColor
vgl_DrawFunLineWidth
vgl_DrawFunPolygon
vgl_DrawFunPolyLine

Table of Contents

10.3 Function Descriptions

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

Table of Contents , HandleBox

NAME

*vis_HandleBoxBegin - create an instance of a HandleBox object

C SPECIFICATION

vis_HandleBox *vis_HandleBoxBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a HandleBox 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 handlebox extents are (0., 0., 0.) and (1., 1., 1.).

Destroy an instance of a HandleBox object using

     void vis_HandleBoxEnd (vis_HandleBox *handlebox)

Return the current value of a HandleBox object error flag using

     Vint vis_HandleBoxError (vis_HandleBox *handlebox)

Table of Contents , HandleBox

NAME

vis_HandleBoxSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_HandleBoxSetObject (vis_HandleBox *handlebox,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox 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 , HandleBox

NAME

vis_HandleBoxGetClipPlanes - get clipping plane equations

C SPECIFICATION

void vis_HandleBoxGetClipPlanes (vis_HandleBox *handlebox,
                                 Vfloat eqn[6][4])

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object.

OUTPUT ARGUMENTS

eqn          Plane equations.

DESCRIPTION

Get plane equations. The planes are ordered xmin, xmax, ymin, ymax, zmin, zmax. The plane equation is this form is useful for defining clipping planes in a graphics subsystem.

Table of Contents , HandleBox

NAME

vis_HandleBoxSetExtent - set handlebox extent

C SPECIFICATION

void vis_HandleBoxSetExtent (vis_HandleBox *handlebox,
                             Vfloat extent[2][3])

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object.
extent       Extent

OUTPUT ARGUMENTS

None

DESCRIPTION

Set handlebox extents, extent[0] contains the point xmin,ymin,zmin, extent[1] contains the point xmax,ymax,zmax. By default the extents are 0.,0.,0. and 1.,1.,1.

Get current extent as an output argument using

     void vis_HandleBoxGetExtent (vis_HandleBox *handlebox,
                                  Vfloat extent[2][3])

Table of Contents , HandleBox

NAME

vis_HandleBoxGetBox - get eight corners of handlebox

C SPECIFICATION

void vis_HandleBoxGetBox (vis_HandleBox *handlebox,
                          Vfloat box[8][3])

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object.

OUTPUT ARGUMENTS

box          Array of coordinate locations of handlebox corners

DESCRIPTION

Get coordinates of the 8 corners of the handlebox. This function is useful for obtaining a specification of the handlebox which may be passed directly to the Space object to query for elements and/or node lying in the box.

Table of Contents , HandleBox

NAME

vis_HandleBoxSetParami - set handlebox display parameters

C SPECIFICATION

void vis_HandleBoxSetParami (vis_HandleBox *handlebox,
                             Vint type,
                             Vint param)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object.
type         Type of display parameter to set
             =HANDLEBOX_PIXTOL         Pixel tolerance for handles
             =HANDLEBOX_CLIPPLANE      Call ClipPlane drawing function
param        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

Set display parameters. The parameter HANDLEBOX_PIXTOL specifies the pixel distance tolerance for picking handles. By default HANDLEBOX_PIXTOL is set to 4.

The parameter HANDLEBOX_CLIPPLANE toggles the calling of the ClipPlane drawing function internally for each of the 6 faces. By default HANDLEBOX_CLIPPLANE is set to SYS_ON.

Table of Contents , HandleBox

NAME

vis_HandleBoxTestHit - test for handle hit

C SPECIFICATION

void vis_HandleBoxTestHit (vis_HandleBox *handlebox,
                           Vint ix, Vint iy,
                           Vint *hit)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object
ix           Horizontal device coordinate
iy           Vertical device coordinate

OUTPUT ARGUMENTS

hit          Hit flag

DESCRIPTION

Select a handle from the handlebox. The input point will be a location given in device coordinates. Device coordinates are expressed in terms of pixel coordinates on a graphics device. If the hit flag is non-zero then use vis_HandleBoxGetHit to find the manipulation handle. The hit manipulation handle will be highlighted when drawn using vis_HandleBoxDraw.

Table of Contents , HandleBox

NAME

vis_HandleBoxGetHit - get internal hit status

C SPECIFICATION

void vis_HandleBoxGetHit (vis_HandleBox *handlebox,
                          Vint *corner,
                          Vint *idir)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object

OUTPUT ARGUMENTS

corner       Corner
idir         Direction

DESCRIPTION

Get manipulation handle detected by a previous call to vis_HandleBoxTestHit. The returned corner argument is zero if no manipulation handle is hit. The corners are ordered zmin first followed by zmax. At a given z plane they are ordered xmin,ymin, xmax,ymin, xmax,ymax and xmin,ymax. The argument idir is 1, 2 or 3 for the x, y or z directions.

Table of Contents , HandleBox

NAME

vis_HandleBoxInitHit - initialize internal hit status

C SPECIFICATION

void vis_HandleBoxInitHit (vis_HandleBox *handlebox)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object

OUTPUT ARGUMENTS

None

DESCRIPTION

Initialize hit status. This sets the manipulation handle hit status to zero.

Table of Contents , HandleBox

NAME

vis_HandleBoxCurrentDrag - get current drag status

C SPECIFICATION

void vis_HandleBoxCurrentDrag (vis_HandleBox *handlebox,
                               Vint *action,
                               Vint *drag)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object

OUTPUT ARGUMENTS

action       Current drag action
drag         Current drag stage

DESCRIPTION

Return current drag action and stage used in the last call to vis_HandleBoxDrag.

Table of Contents , HandleBox

NAME

vis_HandleBoxDrag - drag the handlebox

C SPECIFICATION

void vis_HandleBoxDrag (vis_HandleBox *handlebox,
                        Vint action,
                        Vint drag,
                        Vint ix,
                        Vint iy)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object

OUTPUT ARGUMENTS

action       Drag action
             =VIS_ACTION_TRANSLATE     Translate handlebox
drag         Drag stage
             =VIS_DRAG_INIT            Dragger initialization
             =VIS_DRAG_MOVE            Dragger movement
             =VIS_DRAG_TERM            Dragger termination
ix           Horizontal device coordinate 
iy           Vertical device coordinate

DESCRIPTION

Perform a stage, specified by drag, of a dragger action as a function of device coordinate location ix and iy. When the drag stage VIS_DRAG_TERM is used the drag action is ignored and the internal drag action is set to VIS_ACTION_NONE. The drag action VIS_ACTION_TRANSLATE only operates when the manipulation handles of the handlebox are hit. The function vis_HandleBoxDraw is called internally by this function.

Table of Contents , HandleBox

NAME

vis_HandleBoxDraw - draw the handlebox

C SPECIFICATION

void vis_HandleBoxDraw (vis_HandleBox *handlebox)

INPUT ARGUMENTS

handlebox    Pointer to HandleBox object

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw the handlebox.

Table of Contents

10.4 Polygon Box - PolyBox

Use PolyBox to construct and manipulate a polygon in the plane of the graphics screen. The polygon may be used for clipping and picking purposes.

The following functions are associated with a PolyBox object.

Begin and end an instance of an object, return object error flag

*vis_PolyBoxBegin     - create an instance of a PolyBox object
vis_PolyBoxEnd        - destroy an instance of a PolyBox object
vis_PolyBoxError      - return PolyBox object error flag

Set attributes

vis_PolyBoxGetClipPlanes - get clipping plane equations
vis_PolyBoxInitPoly   - initialize polybox polygon to none
vis_PolyBoxSetPoly    - set polybox polygon
           GetPoly    - get polybox polygon
vis_PolyBoxGetTri     - get polygon triangulation
vis_PolyBoxGetPenta   - get polygon extrusion pentahedra 
vis_PolyBoxSetObject  - set pointers to attribute objects.
           GetObject  - get pointers to attribute objects.
vis_PolyBoxSetParami  - set polybox display parameters
           GetParami  - get polybox display parameters

Operations

vis_PolyBoxTestHit    - test for handle hit
vis_PolyBoxGetHit     - get internal hit status
vis_PolyBoxInitHit    - initialize internal hit status
vis_PolyBoxCurrentDrag - get current drag status
vis_PolyBoxDrag       - drag the polybox 
vis_PolyBoxDraw       - draw the polybox

Instance a PolyBox object using vis_PolyBoxBegin. Once a PolyBox object is instanced, a polygon may be set using vis_PolyBoxSetPoly or it may be constructed using vis_PolyBoxDrag. Query for a set or constructed polygon using vis_PolyBoxGetPoly

The function vis_PolyBoxSetParami may be used to toggle various aspects of the polybox display. Each of the polygon corner points is a selectable handle. Use vis_PolyBoxTestHit to check for handle hits at a given screen location. Use vis_PolyBoxGetHit to get details of the picked handles. Use vis_PolyBoxInitHit to clear the picked handles.

The vis_PolyBoxDraw function is used to draw the polybox. Any picked handles detected with vis_PolyBoxTestHit will be highlighted. The picked handles may be used with the vis_PolyBoxDrag function to interactively move the corners of the polybox.

The polybox is primarily meant to be used as a graphics screen oriented picking device. The function vis_PolyBoxGetTri may be used to return the triangulation of the corners of the polybox. The function vis_PolyBoxGetPenta may be used to get the extruded pentahedra which form the volume the the polybox extruded from the near to the far graphics system z clipping planes. This array of world coordinates and pentahedra connectivity may be passed directly to the Space object functions vis_SpaceBoxGroup and/or vis_SpaceBoxNodeGroup to query for all element and/or node entities lying in the extruded volume.

Table of Contents

10.5 Attribute Objects

A PolyBox object uses ColorMap, DrawFun and VisContext objects to define attributes required to generate a polybox visualization entity. A PolyBox object uses the following VisContext components.

Color: Handles
ColorA: Handle highlight color
LineWidth: Edge width
MinorColor: Edge color
ProjMatrix: Projection matrix, used for picking
Viewport: Viewport, used for picking
XfmMatrix: Modelview matrix, used for picking

A PolyBox object references the following DrawFun functions.

vgl_DrawFunClipPlane
vgl_DrawFunColor
vgl_DrawFunLineWidth
vgl_DrawFunPointSize
vgl_DrawFunPolyLine
vgl_DrawFunPolyPoint

Table of Contents

10.6 Function Descriptions

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

Table of Contents , PolyBox

NAME

*vis_PolyBoxBegin - create an instance of a PolyBox object

C SPECIFICATION

vis_PolyBox *vis_PolyBoxBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a PolyBox 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 PolyBox object using

     void vis_PolyBoxEnd (vis_PolyBox *polybox)

Return the current value of a PolyBox object error flag using

     Vint vis_PolyBoxError (vis_PolyBox *polybox)

Table of Contents , PolyBox

NAME

vis_PolyBoxSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_PolyBoxSetObject (vis_PolyBox *polybox,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

polybox      Pointer to PolyBox 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 , PolyBox

NAME

vis_PolyBoxGetClipPlanes - get clipping plane equations

C SPECIFICATION

void vis_PolyBoxGetClipPlanes (vis_PolyBox *polybox,
                               Vfloat eqn[6][4])

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.

OUTPUT ARGUMENTS

eqn          Plane equations.

DESCRIPTION

Get plane equations.

Table of Contents , PolyBox

NAME

vis_PolyBoxInitPoly - initialize polybox polygon to none

C SPECIFICATION

void vis_PolyBoxInitPoly (vis_PolyBox *polybox,

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Initialize polybox polygon to none.

Table of Contents , PolyBox

NAME

vis_PolyBoxSetPoly - set polybox polygon

C SPECIFICATION

void vis_PolyBoxSetPoly (vis_PolyBox *polybox,
                         Vint npts,
                         Vfloat pts[][2])

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.
npts         Number of points in polygon
pts          Pixel coordinates of points

OUTPUT ARGUMENTS

None

DESCRIPTION

Set polybox polygon.

Get defined polygon as an output argument using

     void vis_PolyBoxGetPoly (vis_PolyBox *polybox,
                              Vint *npts,
                              Vfloat pts[][2])

Table of Contents , PolyBox

NAME

vis_PolyBoxGetTri - get polygon triangulation

C SPECIFICATION

void vis_PolyBoxGetTri (vis_PolyBox *polybox,
                        Vint *ntri,
                        Vint tri[][3])

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.

OUTPUT ARGUMENTS

ntri         Number of triangles
tri          Connectivity of triangles

DESCRIPTION

Get triangulation of polygon corners. Use this triangulation for picking purposes.

Table of Contents , PolyBox

NAME

vis_PolyBoxGetPenta - get polygon extrusion pentahedra

C SPECIFICATION

void vis_PolyBoxGetTri (vis_PolyBox *polybox,
                        Vint *npts,
                        Vfloat pts[][3])
                        Vint *npenta,
                        Vint penta[][6])

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.

OUTPUT ARGUMENTS

npts         Number of points
pts          Point world coordinates
npenta       Number of pentahedra
penta        Pentahedra connectivity

DESCRIPTION

Get pentahedra which cover the extruded polygon from the near to far graphics system z clipping planes. Use this set of pentahedra for picking purposes.

Table of Contents , PolyBox

NAME

vis_PolyBoxSetParami - set polybox display parameters

C SPECIFICATION

void vis_PolyBoxSetParami (vis_PolyBox *polybox,
                           Vint type,
                           Vint param)

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.
type         Type of display parameter to set
             =POLYBOX_PIXTOL           Pixel tolerance for handles
param        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

Set display parameters. The parameter POLYBOX_PIXTOL specifies the pixel distance tolerance for picking handles. By default POLYBOX_PIXTOL is set to 4.

Table of Contents , PolyBox

NAME

vis_PolyBoxTestHit - test for handle hit

C SPECIFICATION

void vis_PolyBoxTestHit (vis_PolyBox *polybox,
                         Vint ix, Vint iy,
                         Vint *hit)

INPUT ARGUMENTS

polybox      Pointer to PolyBox object
ix           Horizontal device coordinate 
iy           Vertical device coordinate

OUTPUT ARGUMENTS

hit          Hit flag

DESCRIPTION

Select a handle from the polybox. The input point will be a location given in device coordinates. Device coordinates are expressed in terms of pixel coordinates on a graphics device. If the hit flag is non-zero then use vis_PolyBoxGetHit to find the manipulation handle. The hit manipulation handle will be highlighted when drawn using vis_PolyBoxDraw.

Table of Contents , PolyBox

NAME

vis_PolyBoxGetHit - get internal hit status

C SPECIFICATION

void vis_PolyBoxGetHit (vis_PolyBox *polybox,
                        Vint *corner)

INPUT ARGUMENTS

polybox      Pointer to PolyBox object

OUTPUT ARGUMENTS

corner       Corner

DESCRIPTION

Get manipulation handle detected by a previous call to vis_PolyBoxTestHit. The returned corner argument is zero if no manipulation handle is hit.

Table of Contents , PolyBox

NAME

vis_PolyBoxInitHit - initialize internal hit status

C SPECIFICATION

void vis_PolyBoxInitHit (vis_PolyBox *polybox)

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Initialize hit status. This sets the manipulation handle hit status to zero.

Table of Contents , PolyBox

NAME

vis_PolyBoxCurrentDrag - get current drag status

C SPECIFICATION

void vis_PolyBoxCurrentDrag (vis_PolyBox *polybox,
                             Vint *action,
                             Vint *drag)

INPUT ARGUMENTS

polybox      Pointer to PolyBox object.

OUTPUT ARGUMENTS

action       Current drag action
drag         Current drag stage

DESCRIPTION

Return current drag action and stage used in the last call to vis_PolyBoxDrag.

Table of Contents , PolyBox

NAME

vis_PolyBoxDrag - drag the polybox

C SPECIFICATION

void vis_PolyBoxDrag (vis_PolyBox *polybox,
                      Vint action,
                      Vint drag,
                      Vint ix,
                      Vint iy)

INPUT ARGUMENTS

polybox      Pointer to PolyBox object

OUTPUT ARGUMENTS

action       Drag action
             =POLYBOX_ACTION_CORNER    Place polygon corner
             =POLYBOX_ACTION_MOVECORNER Move polygon corner
             =POLYBOX_ACTION_LINE      Stretch line from placed corner.
             =POLYBOX_ACTION_TRANSLATE Translate polygon
drag         Drag stage
             =VIS_DRAG_INIT            Dragger initialization
             =VIS_DRAG_MOVE            Dragger movement
             =VIS_DRAG_TERM            Dragger termination
ix           Horizontal device coordinate 
iy           Vertical device coordinate

DESCRIPTION

Perform a stage, specified by drag, of a dragger action as a function of device coordinate location ix and iy. When the drag stage VIS_DRAG_TERM is used the drag action is ignored and the internal drag action is set to VIS_ACTION_NONE. The drag actions POLYBOX_ACTION_CORNER only operates when a corner handle of the polybox is hit. The function vis_PolyBoxDraw is called internally by this function.

Table of Contents , PolyBox

NAME

vis_PolyBoxDraw - draw the polybox

C SPECIFICATION

void vis_PolyBoxDraw (vis_PolyBox *polybox)

INPUT ARGUMENTS

polybox      Pointer to PolyBox object

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw the polybox.

Table of Contents

10.7 Work Plane - WorkPlane

Use WorkPlane to select points constrained to a 2D plane, called a workplane, embedded in 3D space. The workplane can be used to define a cross section of a geometric object (e.g., the cross section of a beam).

The WorkPlane object employs a local 2D coordinate system embedded in 3D space called the workplane to constrain the selection of points within a 2D plane. The workplane can be positioned arbitrarily in 3D space. The orientation of the workplane is defined by a pair of 3D vectors which specify the x-axis and y-axis of the local coordinate system of the workplane.

Grid points and/or grid lines may be drawn within the workplane to serve as visual references when selecting points. A snap option is also available which restricts the selection of points to grid points only. A set of pickable handles for translating and rotating the plane may be displayed and queried. The workplane may also be used as a clipping and picking plane.

The following functions are associated with a WorkPlane object.

Begin and end an instance of an object, return object error flag

*vis_WorkPlaneBegin     - create an instance of a WorkPlane object
vis_WorkPlaneEnd        - destroy an instance of a WorkPlane object
vis_WorkPlaneError      - return WorkPlane object error flag

Set attributes

vis_WorkPlaneGetClipPlane  - get clipping plane equation
vis_WorkPlaneSetDimensions - set workplane height, width, spacing
             GetDimensions - get workplane height, width, spacing
vis_WorkPlaneGetPlane    - get four corners of workplane
vis_WorkPlaneSetObject   - set pointers to attribute objects.
             GetObject   - get pointers to attribute objects.
vis_WorkPlaneSetOriginPlane - set workplane origin and plane
             GetOriginPlane - get workplane origin and plane
vis_WorkPlaneSetParami   - set workplane display parameters
             GetParami   - get workplane display parameters

Operations

vis_WorkPlaneTestHit     - test for handle hit
vis_WorkPlaneGetHit      - get internal hit status
vis_WorkPlaneInitHit     - initialize internal hit status
vis_WorkPlaneCurrentDrag - get current drag status
vis_WorkPlaneDrag        - drag the workplane 
vis_WorkPlaneDraw        - draw the workplane 
vis_WorkPlaneGridPoint   - get a grid point
vis_WorkPlaneNumGrid     - get number of grid points

Instance a WorkPlane object using vis_WorkPlaneBegin. Once a WorkPlane object is instanced, define the origin and orientation of the plane using vis_WorkPlaneSetOriginPlane. Define the outer width and height dimensions of the workplane and the grid (snap) point spacing using vis_WorkPlaneSetDimensions. The number of grid points in the width and height directions is computed from the spacing. The pickable entities on the workplane consist of the grid points and any manipulation handles which are active. The manipulation handles consist of three vector centered at the origin which point in the local x (width), y (height) and z (normal) directions. The function vis_WorkPlaneSetParami may be used to toggle various aspects of the workplane display. Use vis_WorkPlaneTestHit to check for grid point and manipulation handle hits at a given screen location. Use vis_WorkPlaneGetHit to get details of the picked grid points and handles. Use vis_WorkPlaneInitHit to clear the picked grid point and handles.

Figure 10-2, WorkPlane

The vis_WorkPlaneDraw function is used to draw the workplane. Any picked grid point and/or handle detected with vis_WorkPlaneTestHit will be highlighted. The picked handles may be used with the vis_WorkPlaneDrag function to interactively translate and rotate the workplane. Use vis_WorkPlaneGridPoint to return the world coordinate location of a given grid point.

The workplane may be optionally used as a clipping plane. The user may either activate an internal call to the vgl_DrawFunClipPlane function or query for the current clipping plane equation using vis_WorkPlaneGetClipPlane and manage the clipping plane interface to the graphics subsystem externally.

The function vis_WorkPlaneGetPlane may be used to return the world coordinates of the corners of the workplane. This array of world coordinates may be passed directly to the Space object function vis_SpacePlaneGroup to query for all element entities lying on the plane.

Table of Contents

10.8 Attribute Objects

A WorkPlane object uses ColorMap, DrawFun, TransMap and VisContext objects to define attributes required to generate a workplane visualization entity. A WorkPlane object requires a VisContext object for line color, width and style. A WorkPlane object uses the following VisContext components.

Color: Outline, origin, handles, fill, grid points and axes color
ColorA: Handle highlight color
ColorB: Grid point highlight color
Fill: Fill grid
LineWidth: Line width outline and grid lines
LineStyle: Line style for grid lines
MinorColor: Line color
PointSize: Point grid size
ProjMatrix: Projection matrix, used for picking
Trans: Fill grid transparency
Viewport: Viewport, used for picking
XfmMatrix: Modelview matrix, used for picking

A WorkPlane object references the following DrawFun functions.

vgl_DrawFunClipPlane
vgl_DrawFunColor
vgl_DrawFunLineStyle
vgl_DrawFunLineWidth
vgl_DrawFunPointSize
vgl_DrawFunPolygon
vgl_DrawFunPolyLine
vgl_DrawFunPolyPoint
vgl_DrawFunTrans

Table of Contents

10.9 Function Descriptions

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

Table of Contents , WorkPlane

NAME

*vis_WorkPlaneBegin - create an instance of a WorkPlane object

C SPECIFICATION

vis_WorkPlane *vis_WorkPlaneBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a WorkPlane 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 workplane is positioned at (0.0, 0.0, 0.0) and oriented with the x and y global coordinate axes.

Destroy an instance of a WorkPlane object using

     void vis_WorkPlaneEnd (vis_WorkPlane *workplane)

Return the current value of a WorkPlane object error flag using

     Vint vis_WorkPlaneError (vis_WorkPlane *workplane)

Table of Contents , WorkPlane

NAME

vis_WorkPlaneSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_WorkPlaneSetObject (vis_WorkPlane *workplane,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object.
objecttype   The name of the object type to be set.
             =VIS_COLORMAP           ColorMap object
             =VGL_DRAWFUN            DrawFun 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.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneGetClipPlane - get clipping plane equation

C SPECIFICATION

void vis_WorkPlaneGetClipPlane (vis_WorkPlane *workplane,
                                Vfloat eqn[4])

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object.

OUTPUT ARGUMENTS

eqn          Plane equation.

DESCRIPTION

Get plane equation. The plane equation is this form is useful for defining clipping planes in a graphics subsystem.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneSetDimensions - set workplane height, width, spacing

C SPECIFICATION

void vis_WorkPlaneSetDimensions (vis_WorkPlane *workplane,
                                 Vfloat xspace, Vfloat yspace,
                                 Vfloat negwidth, Vfloat poswidth,
                                 Vfloat negheight, Vfloat posheight)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object.
xspace       Grid x spacing 
yspace       Grid y spacing 
negwidth     Negative width
poswidth     Positive width
negheight    Negative height
posheight    Positive height

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if any input is less than or equal to zero.

DESCRIPTION

Set workplane dimensions. The negative and positive widths and heights are measured from the work plane origin. The dimensions negwidth and poswidth are the width of the workplane in the negative and positive x direction. The dimensions negheight and posheight are the height of the workplane in the negative and positive y direction. By default xspace and yspace are set to 1. and the positive and negative widths and heights are set to 2.

Get defined dimensions as output arguments using

     void vis_WorkPlaneGetDimensions (vis_WorkPlane *workplane,
                                      Vfloat *xspace, Vfloat *yspace,
                                      Vfloat *negwidth, Vfloat *poswidth,
                                      Vfloat *negheight, Vfloat *posheight)

Table of Contents , WorkPlane

NAME

vis_WorkPlaneGetPlane - get four corners of workplane

C SPECIFICATION

void vis_WorkPlaneGetPlane (vis_WorkPlane *workplane,
                            Vfloat pln[4][3])

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object.

OUTPUT ARGUMENTS

pln          Array of coordinate locations of workplane corners

DESCRIPTION

Get coordinates of the 4 corners of the workplane. This function is useful for obtaining a specification of the workplane which may be passed directly to the Space object function vis_SpacePlaneGroup to query for all element entities lying on the plane.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneSetOriginPlane - set workplane origin and plane

C SPECIFICATION

void vis_WorkPlaneSetOriginPlane (vis_WorkPlane *workplane,
                                  Vfloat origin[3],
                                  Vfloat right[3],
                                  Vfloat up[3])

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object
origin       Point at which the workplane origin will be located
right        Vector in direction of workplane local x' axis.
up           Vector in direction of workplane local y' axis.

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Set workplane plane. The workplane plane is specified as the plane formed by the right and up vectors passing through the point origin. The right vector defines the x' direction. The y' direction lies in the workplane plane perpendicular to x'. The cross product of the x' and y' vectors is in the same direction as the cross product of the right and up vectors. The right and up vectors need not be normalized or orthogonal but they cannot be parallel. By default the origin is (0.,0.,0.), the right vector is (1.,0.,0.) and the up vector is (0.,1.,0.).

Get origin, right and up as output arguments using

     void vis_WorkPlaneGetOriginPlane (vis_WorkPlane *workplane,
                                       Vfloat origin[3],
                                       Vfloat right[3],
                                       Vfloat up[3])

Table of Contents , WorkPlane

NAME

vis_WorkPlaneSetParami - set workplane display parameters

C SPECIFICATION

void vis_WorkPlaneSetParami (vis_WorkPlane *workplane,
                             Vint type,
                             Vint param)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object.
type         Type of display parameter to set
             =WORKPLANE_AXES           Draw workplane axes 
             =WORKPLANE_GRID           Draw workplane grid
             =WORKPLANE_GRID_LINE      Draw grid as lines    
             =WORKPLANE_GRID_POINT     Draw grid as points   
             =WORKPLANE_GRID_SNAP      Snap to grid location 
             =WORKPLANE_ORIGIN         Draw workplane origin 
             =WORKPLANE_OUTLINE        Draw workplane outline 
param        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

Set display parameters. The parameter WORKPLANE_AXES specifies that the workplane axes showing the orientation of the local 2D coordinate system will be drawn. By default WORKPLANE_AXES is set to VIS_ON.

The parameter WORKPLANE_GRID specifies that a grid will be drawn for the workplane. By default WORKPLANE_GRID is set to VIS_OFF.

The parameter WORKPLANE_GRID_LINE specifies that grid lines will be drawn for the workplane. By default WORKPLANE_GRID_LINE is set to VIS_OFF.

The parameter WORKPLANE_GRID_POINT specifies that grid points will be drawn for the workplane. By default WORKPLANE_GRID_POINT is set to VIS_OFF.

The parameter WORKPLANE_GRID_SNAP specifies that a point selected from the workplane will snap to the closest grid point. By default WORKPLANE_GRID_SNAP is set to VIS_OFF.

The parameter WORKPLANE_GRID_X_SPACE specifies in world coordinates the x spacing between grid points or lines. By default WORKPLANE_GRID_X_SPACE is set to 1.0.

The parameter WORKPLANE_ORIGIN specifies that the origin will be drawn for the workplane. By default WORKPLANE_ORIGIN is set to VIS_ON.

The parameter WORKPLANE_OUTLINE specifies that the outline of the workplane will be drawn. By default WORKPLANE_OUTLINE is set to VIS_ON.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneTestHit - test for handle hit

C SPECIFICATION

void vis_WorkPlaneTestHit (vis_WorkPlane *workplane,
                           Vint ix, Vint iy,
                           Vint *hit,
                           Vfloat pt[3])

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object
ix           Horizontal device coordinate 
iy           Vertical device coordinate

OUTPUT ARGUMENTS

hit          Hit flag
pt           Returned point on workplane in world coordinates

DESCRIPTION

Select a point from the workplane. The input point will be a location given in device coordinates. Device coordinates are expressed in terms of pixel coordinates on a graphics device. The returned point will be constrained to the workplane and will lie on a grid point if snap is on. If the selected screen point is outside of the workplane boundary then the closest point on the workplane to the point will be returned. If the hit flag is non-zero then use vis_WorkPlaneGetHit to find the hit grid point and/or manipulation handle. Use vis_WorkPlaneGridPoint to find the coordinate of any hit grid point. The hit grid point and/or manipulation handle will be highlighted when drawn using vis_WorkPlaneDraw.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneGetHit - get internal hit status

C SPECIFICATION

void vis_WorkPlaneGetHit (vis_WorkPlane *workplane,
                          Vint *igrid,
                          Vint *jgrid,
                          Vint *thand)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object

OUTPUT ARGUMENTS

igrid        Horizontal grid point
jgrid        Vertical grid point
thand        Manipulation handle

DESCRIPTION

Get grid point and/or manipulation handle detected by a previous call to vis_WorkPlaneTestHit. The returned thand argument is zero if no manipulation handle is hit. The value is 1 for the x-axis arrow, 2 for the y-axis arrow and 3 for the plane normal arrow.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneInitHit - initialize internal hit status

C SPECIFICATION

void vis_WorkPlaneInitHit (vis_WorkPlane *workplane)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object

OUTPUT ARGUMENTS

None

DESCRIPTION

Initialize hit status. This sets the grid point and manipulation handle hit status to zero.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneCurrentDrag - get current drag status

C SPECIFICATION

void vis_WorkPlaneCurrentDrag (vis_WorkPlane *workplane,
                               Vint *action,
                               Vint *drag)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object

OUTPUT ARGUMENTS

action       Current drag action
drag         Current drag stage

DESCRIPTION

Return current drag action and stage used in the last call to vis_WorkPlaneDrag.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneDrag - drag the workplane

C SPECIFICATION

void vis_WorkPlaneDrag (vis_WorkPlane *workplane,
                        Vint action,
                        Vint drag,
                        Vint ix,
                        Vint iy)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object

OUTPUT ARGUMENTS

action       Drag action
             =VIS_ACTION_TRANSLATE     Translate workplane
             =VIS_ACTION_ROTATE        Rotate workplane
drag         Drag stage
             =VIS_DRAG_INIT            Dragger initialization
             =VIS_DRAG_MOVE            Dragger movement
             =VIS_DRAG_TERM            Dragger termination
ix           Horizontal device coordinate 
iy           Vertical device coordinate

DESCRIPTION

Perform a stage, specified by drag, of a dragger action as a function of device coordinate location ix and iy. When the drag stage VIS_DRAG_TERM is used the drag action is ignored and the internal drag action is set to VIS_ACTION_NONE. The drag action VIS_ACTION_ROTATE only operates when the manipulation handles in the plane of the workplane are hit. The function vis_WorkPlaneDraw is called internally by this function.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneDraw - draw the workplane

C SPECIFICATION

void vis_WorkPlaneDraw (vis_WorkPlane *workplane)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw the workplane.

Table of Contents , WorkPlane

NAME

vis_WorkPlaneGridPoint - get a grid point from a workplane

C SPECIFICATION

void vis_WorkPlaneGridPoint (vis_WorkPlane *workplane,
                             Vint i, 
                             Vint j, 
                             Vfloat pt[3])

INPUT ARGUMENTS

i            I index for the grid point 
j            J index for the grid point

OUTPUT ARGUMENTS

pt           Returned grid point in world coordinates at i,j

ERRORS

VIS_ERROR_VALUE is generated if i or j is not within the valid limits.

DESCRIPTION

Get a grid point in world coordinates from a workplane given an i and j index. The grid points for a workplane can be thought of as a 2D array of points which can be accessed as a zero-based array (e.g., grid[i][j]). (0, 0) is located at the lower left of the workplane. The function vis_WorkPlaneNumGrid provides the valid limits of the indicies which are (0 <= i < num_i) and (0 <= j < num_j).

Table of Contents , WorkPlane

NAME

vis_WorkPlaneNumGrid - get the number of grid points for a workplane

C SPECIFICATION

void vis_WorkPlaneNumGrid (vis_WorkPlane *workplane,
                           Vint *numi,  
                           Vint *numj)

INPUT ARGUMENTS

workplane    Pointer to WorkPlane object

OUTPUT ARGUMENTS

numi         Number of grid points in the local x' direction.
numj         Number of grid points in the local y' direction.

DESCRIPTION

Get the number of grid points for a workplane.