Visual3D GRAPHICS LIBRARY DOCUMENTATION
by Serg Koren
Serg@VisualNewt.com
http://www.VisualNewt.com
07/27/1999 - 1.0.8
CONTENTS
Introduction
Registering
Using the Library
Global Variables
The API Functions
Specialized Functions
LOADARRAY S, A
LLOAD2DARRAY S, A, SX, SY
LIBVER
POLYGON R, T
SPIRAL N, R, T
ELLIPSE Xc, Yc, A, B, Phi
2-D Functions
SETORIGIN X,Y
PLOTMOVETO X,Y,N
PLOT X1, Y1, X2, Y2
INITGRAF X1, Y1, X2, Y2
INTER X1, Y1, X2, Y2, X3, Y3, X4, Y4, X, Y
ANGLE X, Y, A
ANGLIN X1, Y1, X2, Y2
TRANS2 Tx, Ty, M
SCALE2 Sx, Sy, M
ROT2 Theta, M
MULT2 M1, M2, M3
CLIP X1, Y1, X2, Y2
COVER X1, Y1, X2, Y2
r = DOT (V1, V2)
VECPROD V1, V2, R
DRAWAXIS2
3-D FUNCTIONS
PTOFXSECT K, N, B, D
INV M, MI
PTPLANES N, K, PT
LINEPLANES P, Q, K, D, B
TRAN Tx, Ty, Tz, M
SCALE( Sx,Sy,Sz,A)
ROT D,Theta, M
MULT M1, M2, M3
OBSERVE M
ORTHOGONAL M
PERSPECTIVE M
STEREO M
CUBEINPERSPECTiVE M
DRAWAXIS
The Coordinate System
Defining and Drawing 3D Orthogonal Objects
Defining and Drawing 3D Stereoscopic Objects
Defining and Drawing 3D Perspective Objects
The Example Program
A Word On The Hidden Line Algorithm
Planned Enhancements
Support
___________________________________
Introduction
This is a document detailing the API for the Visual3D(tm) graphics library.Visual3D(tm)gives developers using NSbasic the ability to plot and draw two and three-dimensional graphics.The library supports simple plotting, orthogonal as well as perspective views.It supports both clipping and covering.In addition, the library exposes utility as well as matrix transformation functions.
Registering
Registering the Visual3D(tm) graphics library allows you to create applications with the library and distribute them.Registering also removes the shareware notice.You will also receive the next version (2.0) for free.Site licenses (beyond a single user) are available.
Register via either:
Internet:http://www.VisualNewt.com/Visual3D.html
Postal: Send $15.00 in check or postal money order made out in US funds to:
Serg Koren
485 Brown Briar Cir.
Horsham, PA 19044-1974USA
Using the Library
The graphics library is located in the file Visual3D.nsb and this file must be CHAINed via the statement:
CHAIN "<path>\Visual3D.nsb",FALSE
You must then initialize the library with a call to INITGRAF (see API functions).
Global Variables
X,Y
OldX, OldY
OldOX,OldOY
Reserved by library.Do not use.
ScaleFact
Generic scaling factor.Use for simple scaling.For accurate scaling see SCALE2 for 2D scaling and SCALE for 3D scaling.
Clipping
Flag indicating whether object should be clipped.
0 - do not clip
1 - clip
Covering
Flag indicating whether object should be covered.
0 - do not cover
1 - cover
ClipX, ClipY
CoverX, CoverY
Defines the clipping and covering rectangles.The dimensions of the rectangles are +/-2ClipX, +/-2ClipY and +/-2CoverX, +/-2CoverY centered at the origin.
Screen
The name of the graphics drawing area.This is an NSbasic PictureBox object.See INITGRAF for default values.
NumVert
Defines the number of vertices contained in the 3D object to be drawn.An object can contain 500 vertices.
VertX, VertY, VertZ
Arrays defining the x, y, and z coordinates of the vertices contained in the 3D objec to be drawn.Each is dimensioned to 500.
AXISTRANSFORM
Transformation matrix (4 x 4) for 3D axes.This is initialized to the identity matrix.This matrix is used to plot the x,y,z axes in 3D space.
NumLines
Defines the number of lines connecting the vertices of the 3D object to be drawn.An object can have up to 500 lines.
LineV
Array defining the index of connected vertices.That is, LineV(1,j) Line(2,j) points to the index of the corresponding coordinate to connect.The (3,j) element of the array determines the color to be used when drawing the line.
(3,1) = -n - use n as the color for all line segmnts
(3,1) = -1 - use a random color for each line segment.
The dimensions of LineV are (3 x 500).
ActiveColor
The default color used to draw lines.This defaults to vbBlack.If ActiveColor is set to -1 it will generate a random color each time a line is drawn.
XOff, YOff
The x and y offsets into Screen indicating the (0,0) origin point.That is, the (x,y) in Screen coordinates of the center of Screen.
DIST
The distance from the viewpoint to the origin.
PPD
The distance from the eye to the perspective plane.
EYEDIF
The distance from the bridge of the nose to the center of the eye.This defaults to 4.4.This variable is only used to produce stereoscopic views.
NumFacets
The number of sides an object has.Used in drawing perspective views.
LineF
An array (100,500) indicating the index of the Ith line bounding the Jth facet.Facet lines must be defined consistenly clockwise or counterclockwise.This array is used in drawing perspective views.
IndexF
An array (500) specifying the number of lines (LineF) bounding the Jth facet. This array is used in drawing perspective views.
IHID
A flag indicating how hidden lines will be drawn.Only used for drawing perspective views.
True - hidden lines are removed
False - hidden lines are drawn as dashed perspective lines.
The API Functions
The following is a list of lbrary functions included in the current release:
Specialized Functions
V = LIBVER
Returns the version number of the graphics library
V - returned string
LOADARRAY S, A
Load an array from a comma-delimited string.
S - A comma-delimited string containing values to be loaded into the array.
A - A one dimensional array to be loaded.
LOAD2DARRAY S, A, SX, SY
Load a 2D array, having dimensions (SX x SY) from a comma-delimited string.
S - A comma-delimited string containing values to be loaded into the array.
A - A two-dimensional array to be loaded.
SX - Size of X dimension of the array A.
SY - Size of Y dimension of the array A.
POLYGON R, T
Draw a polygon having 100 segments of a given radius having a segment every T radians.This can be used to draw circles providing the angle T is small enough.
R - radius
T - angle to increment by (radians)
SPIRAL N, R, T
Draw a spiral having N turns, outer radius R, with initial angle T
N - number of spiral turns
R - outer radius
T - initial angle with respect to x axis
ELLIPSE Xc, Yc, A, B, Phi
Draw an ellipse with major axis A, minor axis B centered at (Xc, Yc) with the major axis making an angle Phi with the positive x direction.
Xc, Yc - ellipse center
A - major axis
B - minor axis
Phi - rotation angle
2-D Functions
SETORIGIN X,Y
Sets the origin of the universe to x,y.Initially, this is the center point of Screen.
X, Y - (x,y) coordinates relative to existing origin.
PLOTMOVETO X,Y,N
Move or draw to a point.This routine is the only one you should use to move the current pen point without drawing.This routine ignores the clipping and covering routines.If you wish to have a line clipped or covered use PLOT
X,Y- x and y coordinates of a point in local coordinates.
N - control flag:
2 plot to X, Y
3 move pen to X, Y
-2 plot to X, Y and make X, Y the new origin
-3 move pen to X, Y and make X, Y the new origin
PLOT X1, Y1, X2, Y2
This routine draws a line from (X1, Y1) to (X2,Y2).This routine invokes CLIP and COVER based on the settings of the Clipping and Covering global variables.
X1, Y1 - the x and y coordinates of the first endpoint of the line
X2, Y2 - the x and y coordinates of the other endpoint of the line
INITGRAF X1, Y1, X2, Y2
Initializes the graphics library.Initializes a drawing area (an NSbasic PictureBox object called "Screen").The default scale (SCALEFACT) is set to 20 and the origin to the center point with respect to Screen.The default clipping rectangle is set to 50x8 (ClipX = 25, ClipY = 4).The default covering rectangle is set to 8x50 (CoverX = 4, CoverY = 25).The default drawing color (ActiveColor) is set to black (vbBlack). The default viewpoint (EyeX, EyeY, EyeZ) for 3d objects is (130,40,100).The distance to the perspective plane (PPD) is set to 100.
X1, Y1 - upper left coordinate of drawing area.
X2, Y2 - lower right coordinate of drawing area
INTER X1, Y1, X2, Y2, X3, Y3, X4, Y4, X, Y
Find X, Y the intersection point of two lines from (X1, Y1) to (X2, Y2) and (X3, Y3) and (X4, Y4).
(X1, Y1) (X2, Y2) - x, y coordinates of the first line
(X3, Y3) (X4, Y4) - x, y coordinates of second line
X, Y - x, y coordinates of intersection point
ANGLE X, Y, A
Find angle of a line from (0, 0) to (X, Y) with respect to the x axis
X, Y - x,y coordinates of a point on the line
A - angle
ANGLIN X1, Y1, X2, Y2
Find acute angle between two lines which both pass through (0, 0)
X1, Y1 - point on first line
X2, Y2 - point on second line
TRANS2 Tx, Ty, M
Two-dimensional axis translation matrix.
Tx - Translation of x
Ty - Translation of y
M - returned translation matrix (3 x 3)
SCALE2 Sx, Sy, M
Two-dimensional scaling matrix.
Sx - Scaling of x
Sy - Scaling of y
M - returned scaling matrix (3 x 3)
ROT2 Theta, M
Two-dimensional rotation matrix.
Theta - Angle to rotate (in radians)
M - returned rotation matrix (3 x 3)
MULT2 M1, M2, M3
Matrix multiplication.
M1 - Matrix 1 (3 x 3)
M2 - Matrix 2 (3 x 3)
M3 - returned matrix product (3 x 3)
CLIP X1, Y1, X2, Y2
Clip and draw line (X1, Y1) to (X2, Y2) to global rectangle having size (+/-2ClipX, +/-2ClipY).(See Globals).
(X1, Y1) (X2, Y2) - line to clip.
COVER X1, Y1, X2, Y2
Cover and draw line (X1, Y1) to (X2, Y2) with global rectangle having size (+/-2CoverX, +/-2CoverY).(See Globals).NOTE:Covering is the compliment of clipping.
(X1, Y1) (X2, Y2) - line to cover.
r = DOT (V1, V2)
Find the dot product of two vectors.
r - dot product
V1 - first vector (3)
V2 - second vector (3)
VECPROD V1, V2, R
Find the vector product R of two vectors.
V1 - first vector (3)
V2 - second vector (3)
R - returned vector product
DRAWAXIS2
Draw the x and y axes centered at the origin (0, 0).
3-D FUNCTIONS
PTOFXSECT K, N, B, D
Find point of intersection between a line (B = RMU * D) and a plane (N . X = K).
K - scalar
N - vector (x, y, z) normal to plane (N . X = K)
(B, D) - base vector (x,y,z) to (x1,y1,z1)
INV M, MI
Find the inverse matrix MI of the matrix M.
M - matrix to invert (3 x 3)
MI - returned inverse matrix (3 x 3)
PTPLANES N, K, PT
Find the point of intersection of three planes N(I, ) . X = K(I); I = 1,2 or 3.N(I, ) represents the normal to the Ith plane.
N - array of normals to the planes (3 x 3)
K - column vector (3)
PT - returned intersection point (3)
LINEPLANES P, Q, K, D, B
Find the line (B + RMU * D) common to two planes (P . X=K(1) and Q . X=K(2)
P - normal to first plane (3)
Q - normal to second plane (3)
K - constants for two planes (3)
D - returned directional vector of line (3)
B - returned base point of line (3)
TRAN Tx, Ty, Tz, M
Calculate 3-d axes translation matrix
Tx - translation of x axis
Ty - translation of y axis
Tz - translation of z axis
M - returned translation matrix (4 x 4)
SCALE Sx, Sy, Sz, M
Calculate 3-d axes scaling matrix
Sx - scaling of x axis
Sy - scaling of y axis
Sz - scaling of z axis
M - returned scaling matrix (4 x 4)
ROT D,Theta, M
Calculate 3-d axes rotation matrix about a direction.
D - axis to rotate around
1 - x
2 - y
3 - z
Theta - angle of rotation
M - returned rotation matrix (4 x 4)
MULT M1, M2, M3
3-d matrix multiplication (4 x 4)
M1 - matrix one (4 x 4)
M2 - matrix two (4 x 4)
M3 - returned matrix product (4 x 4)
OBSERVE M
Determine the observation matrix taking into account the observer's coordinare (EyeX, EyeY,EyeZ) and maintaining the vertical. This function is called by ORTHOGONAL.
M - Returned observation matrix.
ORTHOGONAL M
Draw the orthogonal view of the objects having NumLines (stored in LineV), and NumVerts vertices (stored in VertX, VertY, VertZ).
M - transformed object matrix for object to be drawn.
PERSPECTIVE M
Draws the perspective view of the object having NumLines (stored in LineV), and NumVerts vertices (stored in VertX, VertY, VertZ), and NumFacets sides.The global array LineF(I,J) defines the index of the Ith line bounding the Jth facet.The number of lines is defined by the global array IndexF(J).This routine supports hidden line removal.
M - transformed object matrix for object to be drawn.
STEREO M
Draws a stereoscopic view of an object using orthogonal projections.The seperation of views is determined by the global variable EyeDif.
M - transformed object matrix for object to be drawn.
CUBEINPERSPECTVE M
Draws a cube in perspective.This is an optimized cube drawing routine and does not support hidden line removal.
DRAWAXIS
Draw the x, y and z axes using the transformation matrix stored in AXISTRANSFORM.
The Example Program
The example program provides sample code on how to use the library.The complete example is found in the file 3DDemo.nsb, and provides a runnable set of graphics examples which use the library.To run the example, start NSbasic, load 3DDemo.nsb, and exceute it.
Here are some sample values to try for some of the 3d samples.
· For orthogonal objects try setting the viewpoint to (0,0,0)
· Turn off axis, scale 40, for perspective objects.Compare what the hidden lines checkbos does.(You may need to erase the screen to see the effect.)
· For a stereoscopic cube try a viewpoint of (10,30,40) and with the perspective plane 25.
· Play around with the controls and settings to get a feel for the library's capabilities.
Please note that the demo program only demonstrates using the API, you can define and draw any objects you want in your own programs.Also, the program uses two additional libraries, and the following lines may need to be changed:
