CONTENTS LOADARRAY S, A LLOAD2DARRAY S, A, SX, SY LIBVER POLYGON R, T SPIRAL N, R, T ELLIPSE Xc, Yc, A, B, Phi 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 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 Defining and Drawing 3D Orthogonal Objects Defining and Drawing 3D Stereoscopic Objects Defining and Drawing 3D Perspective Objects A Word On The Hidden Line Algorithm ___________________________________ 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 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 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). 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 following is a list of lbrary functions included in the current release: 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 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). 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 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:
The code snippets below are extracted from the example program.Specifically, the example program shows you: Loading the library: CHAIN "\My Documents\NSBasic\Visual3D.nsb",FALSE You may need to change this line if you've placed the library in a different directory. Drawing the x, y axes: SUB AXISCHECK IF Axis.Value THEN DRAWAXIS2 <--- draw the x,y axes
Visual3D GRAPHICS LIBRARY DOCUMENTATION