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 END IF END SUB Drawing a circle using POLYGON: SUB Circle_click POLYGON 10,0.062831853 <--- draw a circle AXISCHECK END SUB8 A more complicated example:Whenever clipping or covering is involved you need to retain the endpoint of the previous line as the start of the current one. SUB Sine_click DIM X,Y,I DIM OX,OY PLOTMOVETO -8,SIN(-8) ,3 <--- move cursor OX = -8 <--- save previous location OY = SIN(-8) FOR I = -8 TO 8 STEP 0.02 X= I <---- get new location Y = SIN(X) PLOT X,Y,OX,OY <---- plot the line OX =X <---- make the last point, previous OY = Y NEXT AXISCHECK <---- plot axes? END SUB Draw an offset and rotated ellipse: SUB Ellips_click ELLIPSE 50,-10,10,30,36 <---- plot ellipse AXISCHECK END SUB Change the origin: (NOTE:The actual demo code uses a replacement INPUTBOX) SUB Origin_click DIM X,Y X = INPUTBOX ("Enter new X coordinate for origin.","Reset Origin X","1000") Y = INPUTBOX ("Enter new Y coordinate for origin.","Reset Origin Y","1500") PLOTMOVETO CINT(X),CINT(Y),-3 <---- move to x,y and make it (0, 0) END SUB Color handling: SUB SETUPCOLOR(Object) DIM I IFColorMap.Value = 0 THEN ActiveColor = vbBlack <---- set default color EXIT SUB END IF SELECT CASE Object CASE ACube FOR I = 1 TO NumLines <---- set each segment differently IF I MOD 2 =1 THEN LineV(3,I) = vbBlue ELSE LineV(3,I) = vbRed END IF NEXT LineV(3,4) = -1 <---- set a segment to random color CASE ASquare ActiveColor = vbGreen <...> CASE ATetrahedron LineV(3,1) = -vbRed <---- set entire object to red CASE AnIcosohedron LineV(3,1) = -1 <---- set each segment randomly CASE ELSE ActiveColor = vbBlack END SELECT END SUB Initialize the graphics library: SUB Main SetupGUI' and wait for events INITGRAF0,0,350,200 <---- initialize library END SUB The graphics library uses a flexible coordinate system located relative to the center coordinate point of the global variable Screen.This is (0,0,0) for the universe, but can be changed using various API calls. The x coordinate increases to the right and the y coordinate toward the bottom of the PictureBox.For 3D graphics, the z coordinate increases behind the screen (the z coordinate of your eyes is negative). The origin of the 2D coordinate system can be altered by changing the values found in the global coordinates X and Y, and then calling SETORIGIN to update its visual representation.To alter the origin of the 3D system, you should do so by utilizing the transformation functions ROT, TRANS, SCALE, multiply the individual resulting matrices together, and store the result in the global matrix AXISTRANSFORM. Defining and Drawing 3D Orthogonal Objects Before a 3D object can be drawn, its structure must first be defined.Defining a 3D object involves specifying the number of vertices in the object, the coordinates of the vertices, and the set of vertices that define the edges of the object, as well aas the actual number of edges. The sample program shows how this is done for several objects; we explain the process using a cube in detail. · Define the coordinates for the object's corners with the object centered at the origin (0,0,0).This example defines the vertices as threecomma-delimited strings (one for the x, y, and z coordinates) and uses the utility function LOADARRAY to load the array of vertices into the VertX, VertY, VertZ arrays.Alternately, you can load the VertX, VertY, VertZ arrays directly by reading the coordinates from a file, or by prompting the user.We also set the number of vertices in the cube in the global variable NumVerts. DIM Xs,Ys,Zs <----define temporary storagr NumVerts = 8 <---- define the number of vertices in the cube Xs = "1,1,1,1,-1,-1,-1,-1" <---- x coordinates of vertices Ys = "1,1,-1,-1,1,1,-1,-1" <---- y coordinate of vertices Zs = "1,-1,1,-1,1,-1,1,-1" <---- z coordinate of vertices LOADARRAY Xs,VertX <---- load x coordinates into global array LOADARRAY Ys,VertY <---- load y coordinates into global array LOADARRAY Zs,VertZ <---- load z coordinates into global array · Next, define the edges connecting the corners of the cube.These need to be stored in the form of indexes into the VertX, VertY, and VertZ arrays.These indexes are stored in the LineV array which has dimensions of (2,500).The ith edge is stored in elements (1,i) which corresponds to the index of the first corner, and (2,i) which corresponds to the index of the second corner.Again, although you could load these elements directly, the example program makes use of a utility function LOAD2DARRAY which corresponds to LOADARRAY, except that it loads a two-dimensional array.Again, we also must set the global variable containing the number of lines (edges) in the object. DIM Lines <---- get temporary space NumLines = 12 <---- define number of edges Lines = "1,2,2,4,4,3,3,1,5,6,6,8,8,7,7,5,1,5,2,6,3,7,4,8" <---- define adjoining index pairs into Vert array LOAD2DARRAY Lines,LineV,2,NumLines <---- load array sized (2,NumLines) · The definition of the structure of the cube is now complete.The next step is to transform the location of the cube from the origin (0,0,0), to its final position in space.This is done using the ROT, TRAN, SCALE functions.Each of these produces a transformation matrix.To get the final transformation matrix for the object, multiply the individual matrixes (using MULT).The cube example rotates the cube around the z axism translates it and then rotates it about the y axis. DIM A(4,4), B(4,4), C(4,4), S(4,4),PHI <---- get temporary space PHI = 0.92795218 <---- angle to rotate (in radians) ROT 3,PHI,A <---- rotate universe around z TRAN 1500.0,0.0,0.0,B <---- move origin to (1500,0,0) ROT 2,-PHI,C <---- rotate universe around -y MULT B,A,S MULT C,S,P <---- final transform is C x B x A · Next, detrmine the observer's viewpoint coordinates.This is done by setting the global variables EyeX, EyeY and EyeZ.In the sample program this is done via prompting the user in Viewpoint_click. · Finally, draw the defined and transformed object by calling the function ORTHOGONAL passing it the final transformation matrix ORTHOGONAL P <---- draw it Orthogonal drawings honor the settings of the global variables Clipping and Covering. Defining and Drawing 3D Stereoscopic Objects Drawing an object in stereoscopic mode is identical to drawing it in orthogonal mode except that you must set the global variable EyeDif to half the distance between two eyes, and call the routine STEREO instead ofORTHOGONAL. Defining and Drawing 3D Perspective Objects Perspective mode requires a bit more set up, and provides more options.First you must set up the definition of the object you want drawn, in the same manner done for an orthogonal view.Additionally, you must specify the distance from the viewpoint (EyeX, EyeY, EyeZ) and the perspective plane.The perspective plane is analogous to the screen through which the object is viewed.However, this is not necessarily the distance from your eye to your device's screen.The perspective plane is drawn on your screen, but it can be located any distance (even behind the object.The closer the plane is to your eye, the smaller the object will appear.Planes behind the object will display the object in larger than normal size.This distance is stored in the global variable PPD. In addition to the vertices and lines that make up the object you defined for orthogonal views, you must now also define the facets (sides) that make up the object. · Set the global variable NumFacets to the number of sides your object has (a cube has six). NumFacets = 6 · Set the distance PPD (eye to perspective plane). · Define the facets for the object (you need to define these consistently clockwise or counterclockwise.) InF = "4,4,4,4,4,4,4,4,4,4,4,4" LOADARRAY InF,IndexF LinF = "1,2,3,4,0,0,5,6,7,8,0,0,1,10,5,9,0,0,2,11,6,10,0,0,3,11,7,12,0,0,4,12,8,9,0,0" LOAD2DARRAY LinF,LineF,6,NumFacets · For perspective views to be drawn properly, the origin of viewer space needs to be inside the object. Use the IDENTITY matrix routine to return the proper observation matrix if the origin is inside the object.(Our cube setup has the origin at (0,0,0) and the vertices at 1 or -1 so the cube complies with this rule.) IDENTITY P · Set the value of the global variable IHID to either hide hidden lines, or draw them as dashed lines. · Now call either the PERSPECTIVE or CUBEINPERSPECTIVE to draw the object. A Word On The Hidden Line Algorithm The hidden line algorithm used by Visual3d(tm) assumes convex objects.Concave objects will produce undefined results. The next release of the Visual3D(tm)2.0 library will include a more general hidden line algorithm allowing concave objects, and support for bodies of rotation.Version 3.0 will have color fill and hidden plane removal. Suggestions, comments, questions, and bug reports should be sent to:Serg@VisualNewt.com. ----END DOC---
Visual3D GRAPHICS LIBRARY DOCUMENTATION
Sidebar[Skip]
By Platform
©2008, 2009, 2010 Serg Koren & VisualNewt Software. All rights reserved.