MathEnv member functions

General notation: output parameters are marked with "/* out */"; all other parameters are input parameters. If input parameters are pointers they are considered to be "const" - the "const" keyword is however never used to allow for maximum compiler compatibility.

A general word on return values:
Functions that return values will act synchronously when called over the remote interface provided by the MathServer/MathClient projects; functions that return void may be sent batched to the server and will thereofore provide better performance in a remote situation. It may be advisable to implement local replacement functions for the former functions when in a remote setup, to prevent unnecessary roundtrips (though it is not necessary - this is only a matter of speed). If any error occurs during the execution of an asynchronous function (void return type) the error will be ignored - the only result will be that some graphics primitive will not be displayed.

2D Graphics support
3D Graphics support
Text I/O and user interaction
2D Marker support
Expression parser support
Statistics
Error handling

2D Graphics support

int InitGraphics( MATHCOLOR bkgnd = MATHRGB(0,0,0), MATHCOLOR fgnd = MATHRGB(0,255,0), int width = -1, int height = -1 ) ;

Initializes a 2D graphics window. If width and height are set to -1, the window is primarily used for vector graphics; if width and height are given they are specified in pixels - the window has then a preferred size and can always be reset to this size. Such a window is primarily used for pixel graphics, though pixel and vector graphics can be mixed. bkgnd sepcifies the background color, while fgnd specifies the default foreground color. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
0: success
non 0: failure.

void SetDimensions( GraphicsSetup2D *pDim ) ;

Sets up the dimensions of a 2D graphics window. With this call the left, right, upper and lower border of the 2D drawing area can be defined.

Definition of GraphicsSetup2D:

struct GraphicsSetup2D
{
 double xMin ;
 double xMax ;

 double yMin ;
 double yMax ;
} ;

Return values:
none

int GetDimensions( /* out */ GraphicsSetup2D *pDim ) ;

Gets the current dimension of 2D graphics window. Left, right, upper and lower border as well as x and y tickmark distances are retrieved.

Definition of GraphicsSetup2D:

struct GraphicsSetup2D
{
 double xMin ;
 double xMax ;

 double yMin ;
 double yMax ;
} ;

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

int GetPixelDimensions( /* out */ int *pwidth, /* out */ int *pheight ) ;

Gets the width and height in pixels of the 2D graphics window. This call can be issued for both pixel or vector graphics oriented 2D windows. pwidth and pheight must point to storage that can hold a 32 bit integer each.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

void SetGrid( /* in */ GraphicsGridSetup2D *pGrid ) ;

Sets the axis and grid that are displayed in the 2D window. Note: the user may change these values when doubleclicking in the 2D window via the 2D properties dialog.

Definition of GraphicsGridSetup2D:

struct GraphicsGridSetup2D
{
BOOL bDrawAxis ;
BOOL bDrawAxisLabels ;
BOOL bDrawBackGrid ;

double xOffset ;
double xTick ;
int xMajorTick ;
char *pszXLabel ;

double yOffset ;
double yTick ;
int yMajorTick ;
char *pszYLabel ;
}

Return values:
none

int GetGrid( /* out */ GraphicsGridSetup2D *pGrid ) ;

Gets the current axis and grid that are displayed in the 2D window.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

void DrawAxis( double xOffset = 0.0, double yOffset = 0.0, double xTick = 1.0, double yTick = 1.0, char *pszXLabel = NULL, char *pszYLabel = NULL ) ;

Draws an axis cross. xOffset and yOffset allow to specify where the axis cross intersects; xTick and yTick allow to modify the current minor tick setting (Attention: this will modify the content of the GraphicsGridSetup2D - see above), while pszXLabel and pszYLabel allow to define the text label that is drawn for each axis. If pszXLabel is NULL, "x" is used as label for the x-axis; if pszYLabel is NULL, "y" is used as lable for the y-axis.

Return values:
none

void SetPixel( int x, int y, MATHCOLOR colorPixel = MATHRGB(0,255,0), BOOL bShowImmediate = FALSE ) ;

Sets a pixel with the specified color at the location (x,y).

x and y are both interpreted to be integer pixel coordinates; the left, upper corner is (0,0) while the right lower corner is (with,height).

If bShowImmediate is true, the 2D graphics window will normally show the pixel immediately (if not switched off somewhere else).
If set to false, a bunch of SetPixels is executed at once, which may be much quicker, though it may not reveal the dynamic of the equation generating the pixels as well.

Return values:
none

void SetPoint( double x, double y ) ;

Sets a single point at the location (x,y) with the default foreground color. x and y are transformed to the viewport according to the values set during a SetDimensions call.

Return values:
none

void SetPoint( double x, double y, MATHCOLOR color ) ;

Sets a single point at the location (x,y) with the specified color. x and y are transformed to the viewport according to the values set during a SetDimensions call. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

void MoveTo( double x, double y ) ;

Moves the current position (as used in LineTo) to the specified point (x,y).

Return values:
none

void LineTo( double x, double y ) ;

Draws a line from the current position as specified by either MoveTo or the last LineTo call to (x,y) in the default foreground color.

Return values:
none

void LineTo( double x, double y, MATHCOLOR color ) ;

Draws a line from the current position as specified by either MoveTo or the last LineTo call to (x,y) in the specified foreground color. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

void SetText( double x, double y, char *pszText, int width = -1 ) ;

Displays the specified text (pszText) at the logical coordinates x,y in a 2D view in the default foreground color. If width is given only the number of characters specified by width is displayed; if width = -1 (default), the string is assumed to be 0-terminated.

Return values:
none

void SetText( double x, double y, char *pszText, int width, MATHCOLOR fgnd ) ;

Displays the specified text (pszText) at the logical coordinates x,y in a 2D view in the specified color. If width is given only the number of characters specified by width is displayed; if width = -1 (default), the string is assumed to be 0-terminated. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

void SetRectangle( double x, double y, double width, double height, BOOL bFilled ) ;

Displays the specified rectangle with the given width and height at the logical coordinates x,y (lower left corner) in a 2D view in the default foreground color. If bFilled is TRUE, the rectangle will be drawn as a filled block.

Return values:
none

void SetRectangle( double x, double y, double width, double height, BOOL bFilled, MATHCOLOR fgnd ) ;

Displays the specified rectangle with the given width and height at the logical coordinates x,y (lower left corner) in a 2D view in the specified color. If bFilled is TRUE, the rectangle will be drawn as a filled block. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

void SetEllipse( double x, double y, double width, double height, BOOL bFilled ) ;

Displays the specified ellipse with the given width and height at the logical coordinates x,y (center) in a 2D view in the default foreground color. If bFilled is TRUE, the ellipse will be drawn filled.

Return values:
none

void SetEllipse( double x, double y, double width, double height, BOOL bFilled, MATHCOLOR color ) ;

Displays the specified ellipse with the given width and height at the logical coordinates x,y (center) in a 2D view in the specified color. If bFilled is TRUE, the ellipse will be drawn filled. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

void SetCircle( double x, double y, double radius, BOOL bFilled ) ;

Displays the specified circle with the given radius at the logical coordinates x,y (center) in a 2D view in the default foreground color. If bFilled is TRUE, the circle will be drawn filled.

Return values:
none

void SetCircle( double x, double y, double radius, BOOL bFilled, MATHCOLOR color ) ;

Displays the specified circle with the given radius at the logical coordinates x,y (center) in a 2D view in the specified color. If bFilled is TRUE, the circle will be drawn filled. Color values can be assembled with the MATHRGB(r,g,b) macro.

Return values:
none

void SetBkgndColor( MATHCOLOR color ) ;

Sets the current background color in a 2D window. The default is black or as specified during InitGraphics.

Return values:
none

void SetFgndColor( MATHCOLOR color ) ;

Sets the current foreground color in a 2D window. All 2D primitives drawn afterwards without a color specification as well as the axis cross and grid will be drawn in this color

Return values:
none

void SetCurrentColor( MATHCOLOR color ) ;

Sets the current color in a 2D window. All 2D primitives drawn afterwards without a color specification will be drawn in this color

Return values:
none

void ClearScreen() ;

Completely clears the screen (both 2D graphics and 3D graphics), thereby removing all pixels, points, lines and other graphical primitives.

Return values:
none

void RefreshScreen() ;

Triggers a repaint of the screen (both 2D graphics and 3D graphics). This function is mainly useful, if the automatic screen refresh every 250 milliseconds has been disabled - with this functionality the MLL has fine grained control over when to display what. (can be used for animations)

Return values:
none

void EnableAutoScreenRefresh( BOOL bTrue ) ;

This function allows to switch the automatic screen refresh on and off (if bTrue is TRUE, screen refresh is enabled; if it is FALSE screen refresh is disabled). Automatic screen refresh happens every 250 milliseconds and displays all the graphics primitives drawn so far - this will usually not result in a smooth animation of the progress, but a bulk update. This mode of operation is a good compromise between speed and interactivity. To get even more speed, switch the screen refresh off completely and call RefreshScreen only once when the whole calculation is completed. To get a smooth animation, also switch automatic screen refresh off and call RefreshScreen everytime an animation frame is completed.

This function works on both 2D and 3D graphics windows.

Return values:
none

int CvtPixel2Log( int x, int y, /* out */ double *px, /* out */ double *py ) ;

This function converts the integer pixel coordiantes (x,y) to the viewport relative double coordinates (*px,*py) - the viewport beeing defined by SetDimensions. px and py must point to storage that can hold 8 byte IEEE doubles.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

int CvtLog2Pixel( double x, double y, /* out */ int *px, /* out */ int *py ) ;

This function converts the viewport relative double coordinates (x,y) to the integer pixel coordinates (*px,*py). - the viewport beeing defined by SetDimension. px and py must point to storage that can hold 32 bit integers.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

void SetRotation( double rCenterX, double rCenterY, double phi ) ;

This function allows to apply a world transformation to a 2D graphics window by specifying an angle around which the whole 2D graphics output is to be rotated. The axis cross (if present) is not transformed. The rotation happens around the point specified by (rCenterX,rCenterY); the angle phi must be specified in rad, where 2*pi is a rotation around 360° .

Return values:
none

void SetTranslation( double x, double y ) ;

This function allows to apply a world transformation to a 2D graphics window by specifying a 2D vector (x,y) by which all graphics primitives are translated. The axis cross (if present) is not transformed.

Return values:
none

Text I/O and user interaction

void ConsoleWrite( char *pszText ) ;

This function adds the specified text to the console window. For a more convenient interface use the wout stream based console output, by defining MATH_IOSTREAM before including MathEnv.h, and calling:

wout.SetEnv( pEnv ) ;

in the MathEntry procedure.

Use wout just like cout. E.g.:

wout << "Hello world...some data: " << 4711 << endl ;

Console output is asynchronous in every case; normally the console output goes to the console window only, from which it will be discarded after a certain maximum number of lines is reached (default is around 1000 lines). If you want to save the console output permanently, use the "Tools" / "Log To File" menu and specify a logfile name. Everything that has been written to the console so far and all further output is the dumped to this logfile.

Return values:
none

int ConsoleRead( /* in, out */ char *pszText, int iBufSize ) ;

This function reads one line from the console; when it is invoked, a console input line appears at the bottom of the console window; as soon as the user presses enter in this line the input is transferred to the buffer specified by pszText whose size must have been specified in iBufSize.If the buffer contained already 0-terminated text before ConsoleRead was called, this text will be displayed in the input line as default input.

Return values:
0: success
non 0: failure

int ShowPopup( char *pszText, /* SP_XXX */ int iType = SP_OK,
/* SPRC_XXX */ /* out */ int *piAnswer = NULL ) ;

This function allows for synchronous output: it displays a messagebox and stops MLL execution until the user commits or cancels the message. Various types of message boxes are possible:

SP_OK a messagebox with on ok button
SP_OKCANCEL a messagebox with an ok and a cancel button
SP_ABORTRETRYIGNORE a messagebox with an abort, a retry and an ignore button
SP_YESNOCANCEL a messagebox with a yes, a no and a cancel button
SP_YESNO a messagebox with a yes and a no button
SP_RETRYCANCEL a messagebox with a retry and a cancel button

The return value can be one of:

SPRC_OK Ok was selected
SPRC_CANCEL Cancel was selected
SPRC_ABORT Abort was selected
SPRC_RETRY Retry was selected
SPRC_IGNORE Ignore was selected
SPRC_YES Yes was selected
SPRC_NO No was selected
MathParam *GetParameters( BOOL bInit = TRUE, char *pszDatFile = NULL ) ;

This function displays a parameter editing dialog, if bInit is TRUE, that is defined by the XML DAT file specified in pszDatFile. If pszDatFile is NULL, a DAT file with the same name as the MLL but with the extension .DAT is searched for the definition of the parameters. If bInit is FALSE, no dialog is displayed. In any case, a pointer to a MathParam object is returned, that can be queried for the parameter values that the user entered. The MathParam object need not and must not be deleted - the system takes care for the memory.

Return values:
An allocated MathParam interface. This interface supports the following functions:

void GetValue( char *pszName, char *pszBuf, int sizeOfBuf );gets an arbitrary string value
int GetValueInt( char *pszName );gets an integer value
double GetValueDouble( char *pszName );gets a float value
BOOL GetValueBool( char *pszName );gets a boolean value; the user may either enter "yes" or "true" (caseinsensitive) for a boolean true or "no" or "false" (caseinsensitive) for a boolean false
MATHCOLOR GetValueColor( char *pszName );gets an RGB color value triple; the value may be entered as "R,G,B" (with delimiting commas) or via a color selection dialog
int GetNumberOfKeys();gets the number of all paramters specified in the DAT file
void GetKey( int i, char *pszBuf, int sizeOfBuf );gets the name of the i'th parameter specified in the DAT file.
int GetValueLen( char *pszName );gets the length of a value specified by name.
void GetValueMatrix( char *pszName, MathMatrix &matrix );gets the parameter with name pszName as matrix object.
Formulas in the matrix will be evaluated left to right, top to bottom as necessary to yield a matrix of double values.
If formula evaluation is not necessary, the whole matrix can be fetched in string form via GetValue(pszName,pszBuf,sizeOfBuf).
The matrix will manage its memory automatically and should preferably be allocated as stack object.

void RegisterMenuFunction( char *pszMenuText, int iCommandCode ) ;

This function adds a new custom menu to the Tools menu pulldown; pszMenuText contains the text to be displayed; iCommandCode contains the commandcode that will be sent to the MathEntry routine of the MLL every time the menu is selected.

Return values:
none

int BreakRequested() ;

This function asks the runtimesystem whether or not the MLL processing should stop, because a break was requested by the user or the system. This break can be triggered either by the use selecting the Break menu or by trying to close one of the MLLs windows or by closing the whole MathFrame.

Furtheron, if the user requested Pause, the function will not return until Pause was selected once again, or an additional Break Request happened.

This function should therefore be called and the return value checked by all MLLs in lengthy loops.

Return values:
0: no break request
1: yes, break was requested

void Sleep( int iMilliSeconds ) ;

This function pauses the MLL execution for the specified number of milliseconds - it is most useful for predictable timing during playing animation loops.

Return values:
none

int Pause() ;

This function sets the MLL to the pause mode as if the user requested Pause - MLL execution is halted, and the titlebar will display a blinking PAUSED message. This function is especially useful for debugging MLLs in single steps.

Return values:
0: success
non 0: failure

2D Marker support

int GetNumberOfMarkers( /* out */ int *piNumber ) ;

This function retrieves the number of currently set markers; it will be returned in *piNumber. piNumber must be a pointer that points to storage that can hold a 32bit integer.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

int GetMarker( int iMarkerIndex, /* out */ double *px, /* out */ double *py ) ;

This function gets the x and y coordiantes of the marker specified by the index iMarkerIndex. iMarkerIndex is allowed to be in the range from 0 to (*piNumber-1) as returned from GetNumberOfMarkers (inclusive range)

The positions are returned in *px and *py and are meant to be viewport coordinates. px and py must point to storage that can hold 8byte IEEE double values.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

void RemoveMarkers() ;

This function removes all markers from system memory and the display.

Return values:
none

void AddMarker( double x, double y ) ;

This function adds a new marker at viewport coordiantes (x,y)

Return values:
none

void EditMarker( int iMarkerIndex, double x, double y ) ;

This function allows to change the position of a marker. The marker is identified by its index, that can be in the range 0 to (*piNumber-1) as returned by GetNumberOfMarkers. (inclusive range)

The new position is specified as double viewport coordinates (x,y).

Return values:
none

Expression parser support

void ResetVariables() ;

This function clears the variable dictionary for the expression parser.

Return values:
none

int SetVariable( char *pszVarName, double value, /* out */ int *key = NULL ) ;

This function sets a new named double variable. If necessary storage is allocated for the variable, whose name is specified in "pszVarName" and whose double value is specified in "value". *key contains an integer after the function returns that can be used to access and change that variable quickly by using the SetVariableByKey function. key must be a pointer that points to storage that can hold a 32bit integer.

Return values:
0: success
non 0: failure

void SetVariableByKey( int key, double value ) ;

Given the key that identifies a variable that was set by "SetVariable", changes the double value of that variable to "value". This function should be used to change the value of a variable instead of calling SetVariable again and again, since it is much quicker.

Return values:
none

int EvaluateExpression( char *pszExpression, /* out */ double *pResult ) ;

Given a mathematical expression specified in pszExpression, that can contain named variables (whose value was set before by the SetVariable calls), returns a double value that is the result of the expression evaluation in *pResult. pResult is a pointer that points to storage that can hold an 8byte IEEE double value.

Attention: this is currently not supported in a remote client.

The following operators are currently supported in the expression:

+ add
- subtract
* multiply
/ divide
^ power; "x^y" is shortcut notation for pow(x,y)
< 1 if x<y, 0 if x>=y
> 1 if x>y, 0 if x<=y
= 1 if x equals y, 0 otherwise
; sequence operator; delimits a subexpression
: defines a variable to the left with the subexpression to the right; e.g.: r:sqrt(x^2+y^2);sin(r)/r;

The following functions are currently supported in the expression:

Name Description Usage Arguments
sin Sinus sin(x) x: angle in rad
cos Cosinus cos(x) x: angle in rad
tan Tangens tan(x) x: angle in rad
asin Arcus Sinus asin(x) x: arcus length
acos Arcus Cosinus acos(x) x: arcus length
atan Arcus Tangens atan(x) x: arcus length
exp Exponential function (e^x) exp(x) double x
log Natural Logarithm log(x) double x
sqrt Square Root sqrt(x) double x
j0,j1,jn Bessel functions of first kind j0(x),j1(x),jn(n,x) double x, int n
y0,y1,yn Bessel functions of second kind y0(x),y1(x),yn(n,x) double x, int n
fact Factorial (x!) fact(x) integer x
mod x Modulo y mod(x,y) integer x, integer y
pow Power pow(x,y) double x, double y
time The time in seconds since program start time(-1 or 0 or 1) -1: time when expression evaluation was started
0: time when mll evaluation was started
1: current time
rand a random value in [0,1] rand()
abs absolute value abs(x) double x
floor the next smaller integer floor(x) double x
ceil the next bigger integer ceil(x) double x
if Conditional function

if(boolexpr,x,y)

e.g.: if(x=0,1,sin(x)/x)

boolexpr: true|false; e.g. x<10
double x
double y

Return values:
0: success
non 0: failure

3D Graphics support

int InitGraphics3D( MATHCOLOR bkgnd = MATHRGB(0,0,77), MATHCOLOR fgnd = MATHRGB(255,120,255), int width = -1, int height = -1 ) ;

This function initializes the 3D graphics window. At any given time there can be at max 1 such window. bkgnd is the default background color; fgnd is the default foreground color; width and height are a hint for the window size in pixels.

The coordinate system of the 3D window will be like:
x axis horizontal, positive to the right
y axis vertical, positive to the top
z axis normal to the screen plane, positive outwards (to the viewer)

The 3D window that will be opened uses OpenGL for rendering; depending on the local installation this may either be a software renderer or a hardware accelerated renderer - consult your graphics card driver manual for details.

Return values:
0: success
non 0: failure

void SetPoint3D( double x, double y, double z ) ;

This function creates a new point in 3D space at position (x,y,z) with the default color.

Return values:
none

void SetPoint3D( double x, double y, double z, MATHCOLOR fgnd ) ;

This function creates a new point in 3D space at position (x,y,z) with color fgnd. The MATHRGB macro can be used to assemble a color value out of red, green, blue components.

Return values:
none

void MoveTo3D( double x, double y, double z ) ;

This function moves the current position in 3D space to (x,y,z). The current position will be used and updated as well by the LineTo3D functions.

Return values:
none

void LineTo3D( double x, double y, double z ) ;

This function creates a line in 3D space from the current position (as set by MoveTo3D or the last LineTo3D call) to (x,y,z) with the default foreground color.

Return values:
none

void LineTo3D( double x, double y, double z, MATHCOLOR fgnd ) ;

This function creates a line in 3D space from the current position (as set by MoveTo3D or the last LineTo3D call) to (x,y,z) with the foreground color fgnd. The MATHRGB macro can be used to assemble a color value out of red, green, blue components.

Return values:
none

void SetTriangle3D( double x1, double y1, double z1, double x2, double y2, double z2, double x3, double y3, double z3 ) ;

This function creates a triangle polygon in 3D space. Edgepoints are: (x1,y1,z1) (x2,y2,z2) (x3,y3,z3). A normal vector will be calculated automatically that is perpendicular to the plane defined by the 3 edgepoints. (necessary if lighting is switched on). The color is the default foreground color. Currently only flat shading is possible with this function.

Return values:
none

void SetTriangle3D( double x1, double y1, double z1, double x2, double y2, double z2, double x3, double y3, double z3, MATHCOLOR fgnd ) ;

This function creates a triangle polygon in 3D space. Edgepoints are: (x1,y1,z1) (x2,y2,z2) (x3,y3,z3). A normal vector will be calculated automatically that is perpendicular to the plane defined by the 3 edgepoints. (necessary if lighting is switched on). The color is defined by fgnd. The MATHRGB macro can be used to assemble a color value out of red, green, blue components. Currently only flat shading is possible with this function.

Return values:
none

void SetVertex3D( double x, double y, double z ) ;

This function sends a 3D vertex to the MathFrame server which can later be used in SetIndexedTriangle3D. The order in which SetVertex3D is called determines the index that must later be used when referring to these vertices.

Return values:
none

void SetIndexedTriangle3D( int iVertex1, int iVertex2, int iVertex3, [MATHCOLOR fgnd] ) ;

This function creates a triangle polygon in 3D space. Edgepoints must have been defined earlier on via SetVertex3D; only the 0-based index of the 3 edges is sent. A normal vector will be calculated automatically that is perpendicular to the plane defined by the 3 edgepoints. (necessary if lighting is switched on). With this function it is possible to share vertices between triangles which allows for smooth shading as well (can be specified in 3D Properties window). The color is defined by fgnd; if left out the default foreground color will be used. The MATHRGB macro can be used to assemble a color value out of red, green, blue components.

Return values:
none

void SetQuad3D( double x1, double y1, double z1, double x2, double y2, double z2, double x3, double y3, double z3, double x4, double y4, double z4 ) ;

This function draws a quad polygon in 3D space. This is done by decomposing the quad to 2 triangles - the function is a convenience function that automatically does so and conceptually calls SetTriangle3D. See SetTriangle3D for details.

Return values:
none

void SetQuad3D( double x1, double y1, double z1, double x2, double y2, double z2, double x3, double y3, double z3, double x4, double y4, double z4, MATHCOLOR fgnd ) ;

This function draws a quad polygon in 3D space. This is done by decomposing the quad to 2 triangles - the function is a convenience function that automatically does so and conceptually calls SetTriangle3D with a color argument (fgnd). See SetTriangle3D for details.

Return values:
none

3D Higher order primitives

void SetSphere3D( double x, double y, double z, double r, int iTess = 16 ) ;

This function draws a sphere in 3D space at position (x,y,z), with radius r and a tesselation detail as defined by iTess. iTess = 16 (the default) gives already nicely rounded spheres. The sphere color is defined by the default foreground color. Spheres are always smooth shaded (if lighting is enabled)

Return values:
none

void SetSphere3D( double x, double y, double z, double r, MATHCOLOR fgnd, int iTess = 16 ) ;

This function draws a sphere in 3D space at position (x,y,z), with radius r and a tesselation detail as defined by iTess. iTess = 16 (the default) gives already nicely rounded spheres. The sphere color is defined by fgnd. The MATHRGB macro can be used to assemble a color value ot of red, green, blue components. Spheres are always smooth shaded (if lighting is enabled)

Return values:
none

void SetText3D( double x, double y, double z, char *pszText, int width = -1, [MATHCOLOR fgnd] ) ;

This function displays the text specified in pszText at position (x,y,z). If width is left out or set to -1, the pszText is assumed to be 0-terminated. The text color is defined by fgnd; if left out the default forergound color will be used. The MATHRGB macro can be used to assemble a color value ot of red, green, blue components.

Return values:
none

void SetCube3D( double x, double y, double z, double width, double height, double depth, [MATHCOLOR fgnd] ) ;

This function draws a cubus in 3D space at position (x,y,z), with the specified width, height and depth. The color is defined by fgnd; if left out the default foreground color will be used. The MATHRGB macro can be used to assemble a color value ot of red, green, blue components.

Return values:
none

3D World transformation

void SetRotation3D( double phi = 0.0, double rho = 0.0, double theta = 0.0 ) ;

This function defines a rotation around (0,0,0) with the euler angles phi, rho, theta. The angles must be specified in rad. phi ranges from 0 to 2*pi; rho from -pi/2 to pi/2 and theta from 0 to 2*pi. The so defined rotation is applied to all points, lines, polygons and higher order primitives, but not to the axes cross - it is assumed to be a world transformation of the defined geometry; not a view transformation.

Return values:
none

void SetTranslation3D( double x = 0.0, double y = 0.0, double z = 0.0 ) ;

This function defines a translation about the vector (x,y,z). The so defined translation is applied to all points, lines, polygons and higher order primitives, but not to the axes cross - it is assumed to be a world transformation of the defined geometry; not a view transformation.

Return values:
none

void DrawAxis3D( BOOL xAxis = TRUE, BOOL yAxis = TRUE, BOOL zAxis = TRUE,
double axisLen = 1.0, double arrowSize = 0.05,
double xOffset = 0.0, double yOffset = 0.0, double zOffset = 0.0,
char *pszXLabel = NULL, char *pszYLabel = NULL, char *pszZLabel = NULL,
MATHCOLOR xColor = MATHRGB(255,0,0),
MATHCOLOR yColor = MATHRGB(0,255,0),
MATHCOLOR zColor = MATHRGB(0,0,255) ) ;

This function draws a 3D axis cross - with its default settings it draws a red x axis, green y axis and blue z axis. The parameters in detail:
BOOL xAxis: if TRUE, x axis will be drawn
BOOL yAxis: if TRUE, y axis will be drawn
BOOL zAxis: if TRUE, z axis will be drawn
double axisLen: the length of all 3 axises - 1.0 is a reasonable default
double arrowSize: the length of the arrows at the end of the axis lines. 0.05 look good together with axisLen 1.0
pszXLabel, pszYLabel, pszZLabel: the texts to print at the end of the axis lines. If these parameters are NULL, "x", "y" and "z" are printed
MATHCOLOR xColor: color of x axis
MATHCOLOR yColor: color of y axis
MATHCOLOR zColor: color of z axis

Return values:
none

void SetView3D( GraphicsSetup3D *pDim ) ;

This function sets various parameters that define the 3D view, like the camera position, the lookAt point, the far and near z clipping planes, whether or not pseudo realistic lighting should be used, and what the color and intensity of the 3 point standard light setup is (if lighting is used). This is the according definition of GraphicsSetup3D:

struct GraphicsSetup3D
{
unsigned short size ;

float cam_x ; // view
float cam_y ; // view
float cam_z ; // view

float lookAt_x ; // view
float lookAt_y ; // view
float lookAt_z ; // view

float znear ; // view
float zfar ; // view

bool bLighting ;
MATHCOLOR colorLight1 ;
MATHCOLOR colorLight2 ;
MATHCOLOR colorLight3 ;
BOOL bSmoothShadeShared ;
BOOL bShowBoundaries ;

GraphicsSetup3D() { size = sizeof( *this ) ; }
} ;

Return values:
none

int GetView3D( /* out */ GraphicsSetup3D *pDim ) ;

Get the current definitions of the 3D view. See the description of GraphicsSetup3D in "SetView3D".

Return values:
0: success
-1: no 3D graphics window open
non 0: other failure

Statistics and memory

int GetNumberOfObjects( int iObjectType, /* out */ int *piNumber ) ;

Gets the actually displayed number of 2D primitives. The kind of object to be counted is specified as iObjectType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT 1
#define MATH_OBJ_TYP_LINE 2
#define MATH_OBJ_TYP_POLYGON 3

The result is returned in the variable *piNumber; it must point to a 32 bit variable allocated by the caller.

Return values:
0: success
-1: no 2D graphics window open
non 0: other failure

void SetMaxNumberOfObjects( int iObjectType, int iNumber ) ;

Sets the maximum number of 2D primitives to be displayed. If the maximum is reached, last recently inserted objects are removed (FIFO). The kind of object for which this limit is to be set is specified as iObjectType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT 1
#define MATH_OBJ_TYP_LINE 2
#define MATH_OBJ_TYP_POLYGON 3

Currently the default for all objects is: 262400
To change this default, edit (or insert) the following registry key:
HKEY_CURRENT_USER\Software\MATHLIB\MathFrame\Settings\General\MaxGraphicsObjects

Return values:
none

int GetNumberOfObjects3D( int iObject3DType, /* out */ int *piNumber ) ;

Gets the actually displayed number of 3D primitives. The kind of object to be counted is specified as iObject3DType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT3D 10
#define MATH_OBJ_TYP_LINE3D 11
#define MATH_OBJ_TYP_TRIANGLE3D 12

The result is returned in the variable *piNumber; it must point to a 32 bit variable allocated by the caller.

Return values:
0: success
-1: no 3D graphics window open
non 0: other failure

void SetMaxNumberOfObjects3D( int iObject3DType, int iNumber ) ;

Sets the maximum number of 3D primitives to be displayed. If the maximum is reached, last recently inserted objects are removed (FIFO). The kind of object for which this limit is to be set is specified as iObject3DType; currently the following objects are recognised:
#define MATH_OBJ_TYP_POINT3D 10
#define MATH_OBJ_TYP_LINE3D 11
#define MATH_OBJ_TYP_TRIANGLE3D 12

Currently the default for all objects is: 262400
To change this default, edit (or insert) the following registry key:
HKEY_CURRENT_USER\Software\MATHLIB\MathFrame\Settings\General\Max3DGraphicsObjects

Return values:
none

Error handling

int GetLastError( /* out */ char *pszErrorTextBuf, int iErrorTextBufSize ) ;

If an error occured during the previous function call, a descriptive error text may be fetched with this function; the caller must allocate the buffer memory of the buffer pszErrorTextBuf and provide the size in iErrorTextBufSize. The error code of the last error is returned as return value of the function. The error code and message are dangling, meaning that successfull function invocations do not delete them - it is therefore possible to execute a batch of primitives and afterwards ask with GetLastError() whether or not any failed.

Return values:
the last error code