User Manual for Graphico

This documentation serves for both the Java and C++ versions of Graphico. Since the reference manual was generated automatically from Java source code, this documentation is written with Java syntax. The C++ syntax would require additional pointer syntax. See Go.h in the C++ source distribution of Graphico for the C++ class declarations.

Index

Category Index
Overview
Example
Using Graphico with Java
Using Graphico with C++/OpenGL
Interface
Context
Rendering
Matrix Transformations
Color
Name
Lighting
Selection
Feedback
Bound Box

Category Index

Context 
Go()
Go(int width, int height)

void  size(int width, int height)
int   width()
int   height()
Render 
void         renderMode(int mode)
void         render(GoVertex data)
void         render(GoVertex data, int startIndex, int endIndex)
GoSelection  selection()
GoFeedback   feedback(boolean sort)
GoBoundBox   boundBox()
void         clear(int flags)
void         enable(int flags)
void         disable(int flags)
Light 
void  light(int number, boolean enabled)
void  light(int number, GoLight light)
void  light(int number, int type, double x, double y, double z)
Color 
void  background(GoColor color)
void  background(double r, double g, double b)
void  color(GoColor color)
void  color(double r, double g, double b)
Name 
void  name(int name)
Matrix 
void  matrixMode(int mode)
void  load(GoMatrix matrix)
void  multiply(GoMatrix matrix)
void  identity()
void  inverse()
void  translate(double tx, double ty, double tz)
void  scale(double sx, double sy, double sz)
void  rotate(double angle, double rx, double ry, double rz)
void  ortho(double left, double right,
            double bottom, double top,
            double zNear, double zFar)
void  frustum(double left, double right,
              double bottom, double top,
              double zNear, double zFar)
void  lookAt(double eyeX, double eyeY, double eyeZ,
             double centerX, double centerY, double centerZ,
             double upX, double upY, double upZ)
void  perspective(double fovy, double aspect,
                  double zNear, double zFar)
void  select(double x, double y,
             double width, double height)
Push & Pop 
void  push(int flags)
void  pop(int flags)
Get 
int      getRenderMode()
int      getFlags()
boolean  getLight(int number)
void     getLight(int number, GoLight light)
void     getBackground(GoColor color)
void     getColor(GoColor color)
int      getName()
int      getMatrixMode()
void     getMatrix(GoMatrix matrix)
void     getModelView(GoMatrix matrix)
void     getProjection(GoMatrix matrix)

Overview

Graphico (simply known as Go) is an open source 3D graphics application programming interface (API) distributed under the terms of the GNU Lesser General Public License.

Graphico works with either Java or C++. The design of Graphico is based on OpenGL. Two independent Java versions of Graphico exist. The first version renders to a Java image that can be displayed in a Java application or any internet browser capable of executing Java 1.1 code. The second version uses Java 3D for increased performance. The C++ version uses OpenGL.

The different versions of Graphico are known as:

GoJava
This version uses Java to do all of the rendering. The Java 3D extension is not utilized. Using this version of Graphico allows for displaying in any browser capable of executing Java 1.1 code, which includes Internet Explorer and Netscape. With this version of Graphico it is possible to integrate Graphico into HTML documents. Since this version is the most portable and integrates well with the internet, all examples with this distribution use this version of Graphico. While this version is suitable for many things, it is not suitable for rendering complex large scenes at high animation frame rates. When better animation performance is required, the same Java applet/application can run with the GoJava3D implementation of Graphico.
GoJava3D
This version makes use of Java 3D. If you have have special 3D graphics hardware and an implementation of Java 3D that is set up to work with the graphics hardware, then this is the best way to run a Graphico applet/application. With this version it is more difficult to reach all internet users with Graphico graphics and to incorporate Graphico into an HTML document, which is why the GoJava implementation exists.
GoCpp
This version is a C++ version that uses OpenGL as the Graphico rendering engine. It serves as an easy way to move Graphico graphics code between Java and C++. This version is not implemented with any special GUI (Graphical User Interface) in mind. While all the C++ example in this distribution use the GLUT (OpenGL Utility Toolkit) via GoGlutInterface, it is not necessary to do so. Just like OpenGL, Graphico leaves all GUI specific code up to the programmer.

Reasons for developing Graphico include

Graphico is a low-level API that knows how to draw lines and triangles based on surrounding light. General features available include A primary feature of Graphico is the ability to render primitives to an image bitmap as well as to produce depth sorted vector based graphics. For this reason, bitmap specific rendering features that do not easily translate into a vector based equivalent are not included. This means that Graphico does not do such things as texture mapping, alpha blending, antialiasing and fog.

Graphico is a complete core level graphics API. Graphico is open source and adding and removing features is encouraged.

Example

A simple example of using Graphico with Java and C++ can be found as square.html. The important thing to note in this example is that the class GoSquare is essentially the same, with the exception of syntax, for Java and C++. The class GoSquare is responsible for the construction and rendering of the square drawn in this example.

For the differences between Java and C++ see Using Graphico with Java and Using Graphico with C++/OpenGL for more detail.

Using Graphico with Java

The Java version of Graphico implements a class called GoInterface that serves as the interface to the Java AWT (Abstract Window Toolkit). In the GoJava version of Graphico, GoInterface extends the Java Canvas class, while the GoJava3D implementation of GoInterface extends the Java Canvas3D class. In general, to remain portable between GoJava and GoJava3D, it is best to not make any Canvas3D specific calls (unless, of coarse, you extend or modify GoInterface to meets you needs).

Looking at the Java source from the example square.html, the following list points out the Java specific calls when using Graphico. 


    1: import java.applet.Applet;
    2: import java.awt.*;
    3: import go.*;
    4: 
    5: //
    6: // GoSquare class containing data representing a square,
    7: // and a render method for drawing the square.
    8: //
    9: 
   10: class GoSquare extends GoInterface
   11: {
   12:     GoTriangleFan  data;
   13: 
   14:     GoSquare()
   15:     {
   16:         data = new GoTriangleFan(4);
   17: 
   18:         data.xyz(0, -0.5, -0.5, 0.0);
   19:         data.xyz(1,  0.5, -0.5, 0.0);
   20:         data.xyz(2,  0.5,  0.5, 0.0);
   21:         data.xyz(3, -0.5,  0.5, 0.0);
   22:     }
   23: 
   24:     public void render()
   25:     {
   26:         go.clear(Go.IMAGE);
   27:         go.render(data);
   28:         swap();
   29:     }
   30: }
   31: 
   32: //
   33: // Java applet
   34: //
   35: 
   36: public class square extends Applet
   37: {
   38:     public void init()
   39:     {
   40:         setLayout(new BorderLayout());
   41:         add("Center", new GoSquare());
   42:     }
   43: }

Using Graphico with C++/OpenGL

When using the GoCpp version of Graphico, any OpenGL-GUI interface will work. Note that no GoInterface class exists for the GoCpp version of Graphico; this is because the C++ version has no ties with a GUI. The C++ source from the example square.html uses a GLUT (OpenGL Utility Toolkit) implementation of the GoIntefrace class, which is called GoGlutInterface. Since GLUT is available on all platforms, the GoGlutInterface class is what is used for all the examples in this distribution.

The following list points out the C++ specific calls when using Graphico with GoGlutInterface. 


    1: #include "Go.h"
    2: #include "GoGlutInterface.h"
    3: 
    4: //
    5: // GoSquare class containing data representing a square,
    6: // and a render method for drawing the square.
    7: //
    8: 
    9: class GoSquare : public GoGlutInterface
   10: {
   11:   public:
   12: 
   13:     GoTriangleFan  *data;
   14: 
   15:     GoSquare(void)
   16:     {
   17:         data = new GoTriangleFan(4);
   18: 
   19:         data->xyz(0, -0.5, -0.5, 0.0);
   20:         data->xyz(1,  0.5, -0.5, 0.0);
   21:         data->xyz(2,  0.5,  0.5, 0.0);
   22:         data->xyz(3, -0.5,  0.5, 0.0);
   23:     }
   24: 
   25:     void render(void)
   26:     {
   27:         go->clear(Go::IMAGE);
   28:         go->render(data);
   29:         swap();
   30:     }
   31: };
   32: 
   33: //
   34: // C++ main
   35: //
   36: 
   37: int main(int argc, char *argv[])
   38: {
   39:     GoGlutInterface::init(&argc, argv);
   40: 
   41:     GoSquare *square = new GoSquare();
   42: 
   43:     GoGlutInterface::mainLoop();
   44:     
   45:     return(0);
   46: }

Interface

Graphico, by itself, is completely independent of any GUI (Graphical User Interface). However, the GoJava and GoJava3D versions come with a class called GoInterface. As for the GoCpp version the GoGlutInterface is available.

It is impossible to capture all GUI related issues into a single Graphico interface, so, modify the distributed interfaces as needed. The GoInterface that comes with the Java versions will probably suffice for most things since is a subclass of the Java Canvas(3D) class, and hence is easy to integrate into the Java AWT (Abstract Window Toolkit) naturally. The GoGlutInterface that comes with the C++ version may need to be replaces completely if you wish to integrates Graphico into a more elaborate GUI that what GLUT (OpenGL Utility Toolkit) offers.

Context

A Graphico rendering context can be created with the following two constructors 
    Go()
    Go(int width, int height)
where width and height are the dimensions of the image bitmap belonging to the context.

To resize the context, use the method 

    size(int width, int height)
To get the width and height of the context, use the methods 
    width()
    height()
To push and pop the context stack, use the methods 
    push(Go.CONTEXT)
    pop(Go.CONTEXT)

Rendering

Rendering means drawing primitives. Graphico has the following classes to render lines and triangles Primitives are by default drawn to an image bitmap.

To clear the image with the image background color, use the method 

    clear(Go.IMAGE)
Depending on Graphico's current rendering mode, Graphico will do different things while rendering primitives.

To set the current rendering mode, use the method 

    renderMode(int mode)
To get the current rendering mode, use the method 
    getRenderMode()
To push and pop the rendering mode stack, use the methods 
    push(Go.RENDER_MODE)
    pop(Go.RENDER_MODE)
Say we want to create a triangle. We could do so with the following 
    GoTriangles triangle = new GoTriangles(3)
Then we would have a set of 3 vertices to define the triangle, who's coordinates could then be defined with 
    triangle.xyz(0, 1.2, 3.9, 5.0)
    triangle.xyz(1, 6.3, 8.4, 8.2)
    triangle.xyz(2, 7.3, 3.3, 9.7)
Other variations of setting and getting specific coordinate values include 
    triangle.x(0, 1.2)
    triangle.y(0, 3.9)
    triangle.z(0, 5.0)
    triangle.x(0)
    triangle.y(0)
    triangle.z(0)
Here triangle contains no color or normal information. If triangle were to be rendered, it would be rendered with the current foreground color and with no lighting applied.

To calculate lighting, we need per vertex normals. A normal vector for each vertex should be defined such that it is perpendicular to the plane in which the vertex lies. It is not necessary to specify the normal vector as a normalized one. To add normal information to triangle, it should be created as follows 

    GoTriangles triangle = new GoTriangles(3, Go.NORMAL)
Normals for the 3 vertices can then be defined with say the following normal values 
    triangle.ijk(0, 1.2, 5.9, 6.9)
    triangle.ijk(1, 6.3, 8.6, 3.2)
    triangle.ijk(2, 2.3, 3.9, 4.7)
Other variations of setting and getting specific normal values include 
    triangle.i(0, 1.2)
    triangle.j(0, 5.9)
    triangle.k(0, 6.9)
    triangle.i(0)
    triangle.j(0)
    triangle.k(0)
To create triangle such that normals will be automatically calculated, triangle should be created with the Go.AUTO_NORMAL flag in place of Go.NORMAL.

If we wish to not use the current foreground color for each vertex, but instead use supplied vertex colors, we will have to flag the GoTriangles constructor that we are interested in specifying color information. To add color information to triangle, it should be created as follows 

    GoTriangles triangle = new GoTriangles(3, Go.COLOR)
Colors for the 3 vertices can then be defined with say the following color values 
    triangle.rgb(0, 1.0, 0.0, 0.0)
    triangle.rgb(1, 0.0, 1.0, 0.0)
    triangle.rgb(2, 0.0, 0.0, 1.0)
Other variations of setting and getting specific color values include 
    triangle.r(0, 1.0)
    triangle.g(0, 0.0)
    triangle.b(0, 0.0)
    triangle.r(0)
    triangle.g(0)
    triangle.b(0)
Once the triangle has been defined, it can be rendered with the methods 
    render(GoVertex data)
    render(GoVertex data, int startIndex, int endIndex)

To append, insert or remove vertices from a data set, use the methods 

    triangle.append(int vertexNumber)
    triangle.insert(int index, int vertexNumber)
    triangle.remove(int index, int vertexNumber)
To find out the current number of vertices in a data set, use the method 
    triangle.vertexNumber()
To find out if a vertex data set has color or normal information, use the method 
    triangle.flags()
While rendering primitives, certain features can be enabled or disabled. These features include
culling
Enables back facing triangles to be culled (i.e. not rendered). A back facing triangle is a triangle who's projected vertices are defined in a clockwise manner. A front facing triangle is a triangle who's projected vertices are defined in a counterclockwise manner.
flat shading
Enables shading of lines and triangles to consist of a solid color.
To enable/disable a feature, use the methods 
    enable(int flags)
    disable(int flags)
To get the current enabled/disabled features, use the method 
    getFlags()
To push and pop the flags stack, use the methods 
    push(Go.FLAGS)
    pop(Go.FLAGS)

Matrix Transformations

Matrix operations are done similarly to OpenGL. There are two matrices that can be manipulated to produce the desired effect. The two matrices are the modelview matrix and the projection matrix.

The current value of the matrix mode indicates which of the two matrices will be the target matrix for any subsequent matrix operations. The current matrix mode is set with 

    matrixMode(int mode)
To get the current target matrix, use the method 
    getMatrixMode()
To push and pop the matrix mode stack, use the methods 
    push(Go.MATRIX_MODE)
    pop(Go.MATRIX_MODE)
To get the content of the modelview and projection matrices, use the methods 
    getMatrix(GoMatrix m)
    getModelView(GoMatrix m)
    getProjection(GoMatrix m)
To push and pop the current target matrix stack (see matrixMode), use the methods 
    push(Go.MATRIX)
    pop(Go.MATRIX)
To push and pop the modelview matrix and/or projection matrix stacks, use the methods 
    push(Go.MODELVIEW | Go.PROJECTION)
    pop(Go.MODELVIEW | Go.PROJECTION)
If no matrix transformations are performed, then the visible viewing volume is defined as a normalized bounding box, where 
    -1 <= x <= 1
    -1 <= y <= 1
    -1 <= z <= 1
The positive x-axis is horizontal and points to the right, the positive y-axis is vertical and points upward, and the positive z-axis is the result of x cross y of a right handed coordinate system. Any model coordinates falling outside of the bounds on this box will be clipped.

However, it is not always convenient to be drawing with normalized coordinates. A viewing volume of any size and location can be specified by defining the projection matrix with any of the following 

    ortho(double left, double right,
          double bottom, double top,
          double zNear, double zFar)
    frustum(double left, double right,
            double bottom, double top,
            double zNear, double zFar)
    perspective(double fovy, double aspect,
                double zNear, double zFar)
    select(double x, double y,
           double width, double height)
These methods map the specified viewing volume to a normalized one. This is important because Graphico works internally with normalized coordinates. Two things to remember that should be done prior to calling these methods are (1) make sure to call matrixMode(Go.PROJECTION) and (2) initialize the projection matrix with identity().

Once we have settled for a viewing volume, the model being viewed can be manipulated so that it displays as wished in the defined viewing volume. The methods available for manipulating the model view matrix are 

    translate(double x, double y, double z)
    scale(double x, double y, double z)
    rotate(double angle, double x, double y, double z)
    lookAt(double eyeX, double eyeY, double eyeZ,
           double centerX, double centerY, double centerZ,
           double upX, double upY, double upZ)
Make sure you call matrixMode(Go.MODELVIEW) prior to changing the modelview matrix. Also identity() may need to be called at times.

Other general purpose matrix operations include 

    load(GoMatrix m)
    multiply(GoMatrix m)
    identity()
    inverse()
Each and every vertex rendered gets transformed with the product of the modelview matrix and and the projection matrix. This will yield normalized coordinates (i.e. vertices are mapped between -1 and 1). If the rendering mode is set to FEEDBACK, then these normalized coordinate values are returned in the feedback buffer. If the rendering mode is IMAGE, then the normalized coordinates are mapped to the dimensions of the image bitmap. This final image bitmap transformation is what OpenGL refers to as the viewport transformation. Also note that Graphico does not implement perspective division.

Color

To set the background color, use the methods 
    background(GoColor color)
    background(double r, double g, double b)
To get the current background color, use the method 
    getBackground(GoColor color)
To push and pop the background color stack, use the methods 
    push(Go.BACKGROUND)
    pop(Go.BACKGROUND)
To set the foreground color, use the methods 
    color(GoColor color)
    color(double r, double g, double b)
To get the foreground color, use the method 
    getColor(GoColor color)
To push and pop the foreground color stack, use the methods 
    push(Go.COLOR)
    pop(Go.COLOR)

Name

To set the current name, use the method 
    name(int name)
To get the current name, use the method 
    getName()
To push and pop the name stack, use the methods 
    push(Go.NAME)
    pop(Go.NAME)

Lighting

Graphico has 4 light sources that can be turned on or off with the method 
    light(int number, boolean enabled)
To get the on/off state of a light, use the method 
    getLight(int number)
The direction or position of a light can be set with 
    light(int number, GoLight light)
    light(int number, int type, double x, double y, double z)
To get the current direction/position of a light, use the method 
    getLight(int number, GoLight light)
To push and pop specific light stacks, use the methods 
    push(Go.LIGHT_0 | Go.LIGHT_1 | Go.LIGHT_2 | Go.LIGHT_3)
    pop(Go.LIGHT_0 | Go.LIGHT_1 | Go.LIGHT_2 | Go.LIGHT_3)
To push and pop all light stacks, use the methods 
    push(Go.LIGHT)
    pop(Go.LIGHT)

Selection

If primitives have been rendered with the rendering mode set SELECTION (see renderMode), then the beginning of the selection list can be obtained with the method 
    selection()
To clear the selection list, use the method 
    clear(Go.SELECTION)
To set up the projection matrix, when the render mode set to SELECTION, it may be convenient to use the select(...) method. Examples of using selection mode can be found as select.html or selectSphere.html.

Feedback

This is the mechanism for producing vector based graphics.

If primitives have been rendered with the rendering mode set FEEDBACK (see renderMode), then the beginning of the feedback list can be obtained with the method 

    feedback(boolean sort)
All feedback coordinates are specified as normalized coordinates. See Matrix Transformations for more information.

To clear the feedback list, use the method 

    clear(Go.FEEDBACK)
An example of using feedback mode can be found in the source code for the goAdobeIllustrator package.

Bound Box

If primitives have been rendered with the rendering mode set BOUND_BOX (see renderMode), then the cumulative bounding box can be obtained with the method 
    boundBox()
To clear the cumulative bounding box, use the method 
    clear(Go.BOUNDBOX)