VIEW3D REFERENCE

Viewer Functions

The following convenience functions are defined for creating and manipulating the View3D widget.

Function Name Description
XintCreateView3D Creates an unmanaged View3D widget.
XintView3DAddObject Adds an object to the display list of a View3D widget.
XintView3DAddObjectAndMaterial. Adds an object to the display list of a View3D widget and assigns the object the specified material.
XintView3DDeselectAll To deselect all selected objects.
XintView3DFreeze To freeze/unfreeze the display.
XintView3DGetModelLimits Returns the limits of the X, Y and Z axes.
XintView3DGetObjectPickable Tells whether or not the specified object is pickable.
XintView3DGetObjectSelectable Tells whether or not the specified object is selectable.
XintView3DGetObjectSelected Tells whether or not an object is selected.
XintView3DGetOrientation Returns the orientation of the specified viewer.
XintView3DGetTranslation Returns the translation of the specified viewer.
XintView3DGetZoom Returns the zoom of the specified viewer.
XintView3DPopFreeze Pop a freeze off of the stack (allow redraws).
XintView3DPushFreeze Push a freeze onto the stack (prevent redraws).
XintView3DRecenter To recenter the display.
XintView3DRedraw Redraws the entire display of a View3D widget.
XintView3DRemoveObject Removes an object from the display list of a View3D widget.
XintView3DScale Adjusts the scaling of the display.
XintView3DSelectAll To select all the objects displayed in the view.
XintView3DSelectObject Selects or deselects the specified object.
XintView3DSetClipPlanesByEquation Sets the clipping plane based on equation.
XintView3DSetClipPlanesByAngle Sets the clipping plane based on angle.
XintView3DSetLight Sets the light attributes of a viewer.
XintView3DSetLightRaysAndSpheres Tells whether or not to identify active light sources.
XintView3DSetMaterial Assigns a material to an object for the specified viewer.
XintView3DSetOrientation Sets the orientation of the specified viewer.
XintView3DSetPickable Sets the pickable state of the specified object.
XintView3DSetSelectable Sets the selectable state of the specified object.
XintView3DSetTranslation Sets the translation of the specified viewer.
XintView3DSetZoom Sets the zoom of the specified viewer.

Function Name	Description
XintCreateView3D	Creates an unmanaged View3D widget.
XintView3DAddObject	Adds an object to the display list of a View3D widget.
XintView3DAddObjectAndMaterial.	Adds an object to the display list of a View3D widget and assigns the object the specified material.
XintView3DDeselectAll	To deselect all selected objects.
XintView3DFreeze	To freeze/unfreeze the display.
XintView3DGetModelLimits	Returns the limits of the X, Y and Z axes.
XintView3DGetObjectPickable	Tells whether or not the specified object is pickable.
XintView3DGetObjectSelectable	Tells whether or not the specified object is selectable.
XintView3DGetObjectSelected	Tells whether or not an object is selected.
XintView3DGetOrientation	Returns the orientation of the specified viewer.
XintView3DGetTranslation	Returns the translation of the specified viewer.
XintView3DGetZoom	Returns the zoom of the specified viewer.
XintView3DPopFreeze	Pop a freeze off of the stack (allow redraws).
XintView3DPushFreeze	Push a freeze onto the stack (prevent redraws).
XintView3DRecenter	To recenter the display.
XintView3DRedraw	Redraws the entire display of a View3D widget.
XintView3DRemoveObject	Removes an object from the display list of a View3D widget.
XintView3DScale	Adjusts the scaling of the display.
XintView3DSelectAll	To select all the objects displayed in the view.
XintView3DSelectObject	Selects or deselects the specified object.
XintView3DSetClipPlanesByEquation	Sets the clipping plane based on equation.
XintView3DSetClipPlanesByAngle	Sets the clipping plane based on angle.
XintView3DSetLight	Sets the light attributes of a viewer.
XintView3DSetLightRaysAndSpheres	Tells whether or not to identify active light sources.
XintView3DSetMaterial	Assigns a material to an object for the specified viewer.
XintView3DSetOrientation	Sets the orientation of the specified viewer.
XintView3DSetPickable	Sets the pickable state of the specified object.
XintView3DSetSelectable	Sets the selectable state of the specified object.
XintView3DSetTranslation	Sets the translation of the specified viewer.
XintView3DSetZoom	Sets the zoom of the specified viewer.

XintCreateView3D

This function creates an unmanaged View3D widget.

     Object XintCreateView3D (...)

Widget parent Parent of new View3D widget.
char * name Name of new View3D widget.
ArgList arglist List of resource settings for the new widget.
Cardinal argcount Number of resources set by arglist.

XintView3DAddObject

This function adds an object to the list of objects displayed by a View3D widget. It increases the reference count of the object by 1. It should be used only if the object has already been assigned a material (See function XintView3DSetMaterial to assign a material to an object). Also, use this function to add back an object that was removed from the display list of a viewer using function XintView3DRemoveObject.

     Boolean XintView3DAddObject (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the 3D object to add.

XintView3DAddObject returns True if the object was successfully added to the display list and False otherwise.

XintView3DAddObjectAndMaterial

This function adds an object to the list of objects displayed by a View3D widget and assigns a material to the object for that viewer. The function increases the reference count of the object by 1.

     Boolean XintView3DAddObjectAndMaterial (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the 3D object to add.
XintView3DMaterial * front Front material for the object.
XintView3DMaterial * back Back material or NULL if object does not support a back material or if the back material should be the same as the front.

This function returns True if the object was successfully added to the display list and False otherwise.

XintView3DDeselectAll

This function deselects all the selected objects in the list of objects displayed by a View3D widget.

     void XintView3DDeselectAll (...)

Widget widget ID of the View3D widget.

XintView3DFreeze

This function allows the application to freeze the display, so that changes in the display list or in the object characteristics don't generate a redraw until the freeze state is turned off. This function is typically used when several objects are added or removed from the display list to minimize the number of redraws.

     void XintView3DFreeze(...)

Widget widget ID of the View3D widget.
Boolean freeze True to freeze the display, False to unfreeze and redraw the display.

A typical code fragment, where multiple objects are added to the display list might appear as follows:

     XintView3DFreeze(view3d, True);
     XintView3DAddObject(view3D, object1);
     ....
     XintView3DAddObject(view3d, objectn);
     XintView3DFreeze(view3d, False);

XintView3DGetModelLimits

This function retrieves the limits of the X, Y and Z axes.

     void XintView3DGetModelLimits (...)

Widget widget ID of the View3D widget.
XintRealLimits * x_limits Axis limits in the X direction.
XintRealLimits * y_limits Axis limits in the Y direction.
XintRealLimits * z_limits Axis limits in the Z direction.

XintView3DGetObjectPickable

This function returns True if the specified object is pickable, False otherwise.

     Boolean XintView3DGetObjectPickable (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the 3D object.

XintView3DGetObjectSelectable

This function returns True if the specified object is selectable. Otherwise it returns False.

     Boolean XintView3DGetObjectSelectable (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the object.

XintView3DGetObjectSelected

This function returns True if the specified object is selected inside widget . Otherwise it returns False.

     Boolean XintView3DGetObjectSelected (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the object.

XintView3DGetOrientation

This function retrieves the current orientation of the widget.

     void XintView3DGetOrientation (...)

Widget	widget	ID of the View3D widget.
XintReal *	azimuth	Azimuth of widget.
XintReal *	dip	Dip of widget.
XintReal *	twist	Twist of widget.

XintView3DGetTranslation

This function retrieves the current translation of the widget.

     void XintView3DGetTranslation (...)

Widget	widget	ID of the View3D widget.
XintReal *	x_offset	X offset of display.
XintReal *	y_offset	Y offset of display.

XintView3DGetZoom

This function retrieves the current zoom of the widget.

     XintReal XintView3DGetZoom (...)

Widget

widget

ID of the View3D widget.

XintView3DPopFreeze

This function allows the View3D widget to redraw.

     void XintView3DPopFreeze (...)

Widget

widget

ID of the View3D widget.

This function pops a freeze off of the stack. If there are any freezes on the stack, the View3D widget will not redraw. You can use the older API call XintView3DFreeze() to remove all freezes from the stack.

XintView3DPushFreeze

This function prevents the View3D widget from redrawing.

     void XintView3DPushFreeze (...)

Widget

widget

ID of the View3D widget.

This function pushes a freeze onto the stack. If there are any freezes on the stack, the View3D widget will not redraw. You can use XintView3DPopFreeze() or the older API call XintView3DFreeze() to remove all freezes from the stack.

XintView3DRecenter

This function recenters and resets the display of a View3D object, undoing all zooming and translation operations previously applied by an end-user.

     void XintView3DRecenter (...)

Widget widget ID of the View3D widget.

XintView3DRedraw

This function redraws the entire View3D widget window.

     void XintView3DRedraw (...)

Widget widget ID of the View3D widget.

XintView3DRemoveObject

This function removes an object from the display list of a 3D widget. The object removed will be destroyed unless it is used by another viewer or its reference count has been incremented using function XintView3DRefObject.

     Boolean XintView3DRemoveObject (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the object to remove.

This function returns False if the object was not found in the list of objects displayed by the View3D widget. Otherwise it returns True.

XintView3DScale

This function scales the display.

     XintView3DScale (...)

Widget widget ID of the View3D widget.
char axis Set to 'X' for the X axis, 'Y' for the Y axis, or 'Z' for the Z axis.
XintReal scale Amount to scale the axis. 1.0 makes no change. Set < 1.0 to make the axis smaller. Set > 1.0 to make it larger.

XintView3DSelectAll

This function selects all the objects in the display list of a View3D widget.

     void XintView3DSelectAll (...)

Widget widget ID of the View3D widget.

XintView3DSelectObject

This function selects or deselects the specified object. If the argument object is set to NULL, the action affects all objects displayed by the View3D widget.

     void XintView3DSelectObject (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the 3D object.
Boolean select True to select, False to deselect.

XintView3DSetClipPlanesByEquation

This function sets a clipping plane based on the following equation:

Ax + By + Cz + D = 0;

     void XintView3DSetClipPlanesByEquation (...)

Widget widget ID of the View3D widget.
int plane Which plane to set.
Boolean on Set to True to enable the clipping plane.
XintVector4 equation The clipping plane parameters (A,B,C,D).

Argument plane must be specified as one of the following constants:

Defined Constant Description
XintCLIP_PLANE0 The default position is at quarter scale to +X edge and parallel to yz plane.
XintCLIP_PLANE1 The default position is at quarter scale to -X edge and parallel to yz plane.
XintCLIP_PLANE2 The default position is at quarter scale to +Y edge and parallel to xz plane.
XintCLIP_PLANE3 The default position is at quarter scale to -Y edge and parallel to xz plane.
XintCLIP_PLANE4 The default position is at quarter scale to +Z edge and parallel to xy plane.
XintCLIP_PLANE5 The default position is at quarter scale to -Z edge and parallel to xy plane.

Defined Constant	Description
XintCLIP_PLANE0	The default position is at quarter scale to +X edge and parallel to yz plane.
XintCLIP_PLANE1	The default position is at quarter scale to -X edge and parallel to yz plane.
XintCLIP_PLANE2	The default position is at quarter scale to +Y edge and parallel to xz plane.
XintCLIP_PLANE3	The default position is at quarter scale to -Y edge and parallel to xz plane.
XintCLIP_PLANE4	The default position is at quarter scale to +Z edge and parallel to xy plane.
XintCLIP_PLANE5	The default position is at quarter scale to -Z edge and parallel to xy plane.

XintView3DSetClipPlanesByAngle

This function sets a clipping plane based on the user defined angle:

     void XintView3DSetClipPlanesByAngle (...)

Widget widget ID of the View3D widget.
int plane Which plane to set.
Boolean on Set to True to enable the clipping plane.
int azimuth The angle between +X vector and the plane normal's projection on the xz plane.
int dip The angle between plane normal and its projection on the xy plane.
XintVector3 offset The distance from the original to the clipping plane.

Argument plane must be specified as one of the following constants:

Defined Constant	Description
XintCLIP_PLANE0	The default position is at quarter scale to +X edge and parallel to yz plane.
XintCLIP_PLANE1	The default position is at quarter scale to -X edge and parallel to yz plane.
XintCLIP_PLANE2	The default position is at quarter scale to +Y edge and parallel to xz plane.
XintCLIP_PLANE3	The default position is at quarter scale to -Y edge and parallel to xz plane.
XintCLIP_PLANE4	The default position is at quarter scale to +Z edge and parallel to xy plane.
XintCLIP_PLANE5	The default position is at quarter scale to -Z edge and parallel to xy plane.

XintView3DSetLight

A View3D viewer can handle up to seven light sources, including a head light source with a fixed position and six light sources that rotate with the scene. Function XintView3DSetLight allows the application to control the state (on or off), the position and the intensity of each light source. For convenience, light sources are named according to their default position.

     void XintView3DSetLight (...)

Widget widget ID of the View3D widget.
int light Which light to set.
Boolean on Set to True to turn on the light and False to turn it off.
int intensity Intensity of the light (from 0 to XintLIGHT_MAX_INTENSITY)
int dip An angle between -90� and +90� that specifies the position of the light source with respect to the z axis (-90� is parallel to the +Z axis and +90� is parallel to the -Z axis.).
int azimuth An angle between -180� and +180� that specifies the position of the light source in the XY plane (angle 0� corresponds to the -Y axis).

Argument light must be specified as one of the following constants:

Defined Constant Description
XintLIGHT_HEAD Head light. The position and intensity (set to XintLIGHT_MAX_INTENSITY) cannot be changed.
XintLIGHT_1 Light positioned in the positive X direction (default position is dip = 0 and azimuth = 90).
XintLIGHT_2 Light positioned in the negative X direction (default position is dip = 0 and azimuth = -90).
XintLIGHT_3 Light positioned in the positive Y direction (default position is dip = 0 and azimuth = -180).
XintLIGHT_4 Light positioned in the negative Y direction (default position is dip = 0 and azimuth = 0).
XintLIGHT_5 Light positioned in the positive Z direction (default position is dip = -90 and azimuth = 0).
XintLIGHT_6 Light positioned in the negative Z direction (default position is dip = 90 and azimuth = 0).

Defined Constant	Description
XintLIGHT_HEAD	Head light. The position and intensity (set to XintLIGHT_MAX_INTENSITY) cannot be changed.
XintLIGHT_1	Light positioned in the positive X direction (default position is dip = 0 and azimuth = 90).
XintLIGHT_2	Light positioned in the negative X direction (default position is dip = 0 and azimuth = -90).
XintLIGHT_3	Light positioned in the positive Y direction (default position is dip = 0 and azimuth = -180).
XintLIGHT_4	Light positioned in the negative Y direction (default position is dip = 0 and azimuth = 0).
XintLIGHT_5	Light positioned in the positive Z direction (default position is dip = -90 and azimuth = 0).
XintLIGHT_6	Light positioned in the negative Z direction (default position is dip = 90 and azimuth = 0).

XintView3DSetLightRaysAndSpheres

This function is used to specify whether or not a sphere is drawn at the light position to indicate an active light source and whether or not a ray is traced to indicate the direction of the light.

     void XintView3DSetLightRaysAndSpheres (...)

Widget	widget	ID of the View3D widget viewer.
Boolean	show_rays	True to draw the active light rays; False otherwise.
Boolean	show_spheres	True to draw the active light spheres; False otherwise.

XintView3DSetMaterial

This function assigns a material to the specified object when displayed within a particular viewer.

     void XintView3DSetMaterial (...)

Widget widget ID of the View3D widget viewer.
XintView3DObject * object ID of the 3D object
XintView3DMaterial * front Front material for the object.
XintView3DMaterial * back Back material or NULL if object does not support a back material or if the back material should be the same as the front.

XintView3DSetOrientation

This function sets the current orientation of the widget.

     void XintView3DSetOrientation (...)

Widget widget ID of the View3D widget viewer.
XintReal azimuth Azimuth of widget.
XintReal dip Dip of widget.
XintReal twist Twist of widget.

XintView3DSetPickable

This function sets the pickable state of the specified object.

     void XintView3DSetPickable (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the 3D object.
Boolean state True to enable picking, False to disable picking.

XintView3DSetSelectable

This function sets the selectable state of the specified object.

     void XintView3DSetSelectable (...)

Widget widget ID of the View3D widget.
XintView3DObject * object ID of the 3D object.
Boolean state True to enable selection, False to disable selection.

XintView3DSetTranslation

This function sets the current translation of the widget.

     void XintView3DSetTranslation (...)

Widget widget ID of the View3D widget viewer.
XintReal x_offset X offset of display.
XintReal y_offset Y offset of display.

XintView3DSetZoom

This function sets the current zoom of the widget.

     void XintView3DSetZoom (...)

Widget widget ID of the View3D widget viewer.
XintReal zoom Zoom of widget.

Widget	parent	Parent of new View3D widget.
char *	name	Name of new View3D widget.
ArgList	arglist	List of resource settings for the new widget.
Cardinal	argcount	Number of resources set by arglist.