CPSC 424, Computer Graphics, Spring 2010
Lab 3: Moving Into 3D


It is time to begin programming 3D applications with Jogl/OpenGL. The first part of this lab is an exercise that asks you to build two particular 3D objects from some basic component objects. The second part asks you to create a set of classes for building scene graphs in 3D and to use them to build a scene.

I have found that my Jogl programs and applets will not work on the small iMac computers in the Math/CS lab. Those computers seem to have some problem with GLJPanel. However, the Jogl programs will work if you substiture GLCanvas for GLJPanel. The large iMacs have no problem with GLJPanel, and you should work on those if possible.

You can use either Eclipse or Netbeans for your Jogl projects in this course, but I suggest that we stick to Eclipse. To use Jogl in Eclipse, you must set up your projects to tell them where to find the Jogl jar files and native libraries (and also, for better editor support, the Jogl documentation). I have placed a copy of the necessary material in the folder /opt/jogl-1.1.1-linux-i586, and you can set up Eclipse to use it from there. If you want to use Jogl in Eclipse on your own computer, you will need to grab the appropriate archive for your platform from

http://download.java.net/media/jogl/builds/archive/jsr-231-1.1.1a/

You should also get the documentation zip file at the same time, from the same place.

To use Jogl 1.1.1 in Eclipse, start by creating a Java project, as usual. Then:

  1. Right-click the project name in the Package Explorer. In the pop-up menu, go to "Build Path" / "Configure Build Path...".
  2. Click the "Libraries" tab under "Java Build Path."
  3. Click the "Add External Jars" button.
  4. In the file browser that pops up, navigate into the "lib" subdirectory of the Jogl directory, /opt/jogl-1.1.1-linux-i586/lib. Select both of the jar files, gluegen-rt.jar and jogl.jar, and click "OK". The jar files will be added to the list of Libraries for your project.
  5. Set the native library location for gluegen-rt.jar as follows: Click the small triangle next to the name of the jar file. In the list that appears, click "Native Library Location." Click the "Edit" button. In the pop-up dialog, click "External Folder." Browse to the Jogl "lib" directory, and click "OK" (twice). The native library location should be set in the Libraries list.
  6. Do the same thing to set the native library location for jogl.jar.
  7. Under jogl.jar, set the "Javadoc Location", using the same technique, to be the documentation directory, /opt/jogl-1.1.1-linux-i586/jogl-1.1.1-docs.

If you have set things up correctly, you should be able to compile and run OpenGL/Jogl programs in the project that you have configured. Once you have a working project, you can copy-and-paste it to create a new project; that way, you can avoid going through all the configuration again.


For this lab, you will need the files in the directory files_for_basic_3D, which you can find in /classes/s10/cs424. In particular, you will find BasicJoglApp3D.java, which is a main program that is an outline for basic 3D Jogl applications. You can use it as a starting point for the programs that you write for this lab. You will also find a package named glutil that contains several classes that you will need. You should add the main program and the glutil package to your project. There is also a scengraph2D package that you can add to your project if you want. It contains the classes that were used to make 2D scene graphs in Section 1.1.5. You might refer to them for ideas in Part 2 of the lab.

Your work for this lab will be due in two weeks. Next week's lab will be an introduction to Blender and will not involve any programming. To submit the lab, you should put copies of all the programs that you have written in your homework directory in /classes/s10/cs424/homework. You should also post an applet version of your scene graph program on your course web site. Information about how to do this can be found in the last section of this web page.


Part 1: Building Some Odd Objects

As an exercise in using basic shape classes and applying transformations, you should write a program in which you build the Spiky Sphere and Bumpy Cube that are shown in the following image. Furthermore, your program should be able to animate the spikes moving into and out of the sun and the bumps moving into and out of the cube. A working version of the program is shown as an applet at the bottom of the web page.

Your program will use some classes from the glutil package to render the basic shapes. The picture contains a sphere, a cube, six tori, and sixteen cones. You can render these shapes using objects defined by the classes UVSphere, Cube, UVTorus, and UVCone from the package glutil. (You will only need one object of each type. You can use the same UVTorus object to draw all the tori and the same UVCone object to draw all the cones.)

To write your program, you can start with a copy of BasicJoglApp3D.java. You should take some time to understand it. It has a frameNumber variable that is incremented when the animation is running. It has objects of type Camera and TrackBall from the glutil package that let the user rotate the view by dragging the mouse. Animation and mousing are already built into the program, and you do not have to do anything to make them work (except to use frameNumber in your drawing).


Part 2: Scene Graphs for 3D

Part 1 of the lab was just a warm-up. The main point of the lab is to design and write a set of classes for representing scene graphs in 3D and to use them to create an animated scene of moderate complexity. For your scene, you might want to do something like my "Diskwold" example, shown below along with a closeup of the car, but you can also make up your own scene if you want. (A 3D mobile of some sort is another idea.) In my animation, the car drives around the edge of the world, its wheels turn, and the tree at the center grows for the first 1000 frames.

The glutil package contains several classes for drawing 3D objects: Cube, UVDisk, UVSphere, UVCylinder, UVCone, and UVTorus. You can use these for the basic geometric objects on the bottom level of your scene graphs. You can add additional basic shapes, such as lines and rectangles, if you need them. (But consider that a stretched-out cylinder might look better than a line.)

You will need to create a class to represent complex objects. Your class hierarchy will need a top-level class, most likely abstract, to represent the general idea of a node in the scene graph. You will need to think about how to handle transforms and attributes. Color is probably the only attribute that you need to worry about for now. (However, we will cover textures before the assignment is due, and you might want to add some support for textures as well.)

You can use the 2D scene graph classes in the scenegraph2D package for ideas. You should make sure that you understand how scene graphs are constructed and used. (The sample program JoglHM2DWithSceneGraph.java has a 2D example.)


Adding an OpenGL Applet to your Web Page

All the sample programs that we have used so far in this course are written as subclasses of JPanel, and they include a main() routine that just creates a window to display the panel. It's easy enough to make an applet class to do the same thing. For example, if the main program class is called Lab3Part1, you can write an applet version of the program, Lab3Part1Applet, as follows:

   import javax.swing.JApplet;
   
   public class Lab3Part1Applet extends JApplet {
      public void init() {
         setContentPane( new Lab3Part1() );
      }
   }

To add your applet to a web page, you will need to create a jar file that contains the applet class and all the other classes used by your program. To make such a jar file in Eclipse, hilite the required source files in the Package Explorer. (For the program from Part 2, hilite the source for applet class, the main program, and any required packages such as glutil. You can right-click an item to add it to the selected items.) Then right-click in the Package Explorer, and choose "Export" from the pop-up menu. In the dialog box, select "Jar File" under "Java", and click "Next". Fill in the Jar file location/name under "Select the export destination". (You want to enter a full path name for the file that will be created; you can use the Browse button to enter the path using a file chooser dialog.) Click "Finish", and the jar file should be created. You should copy the jar file to your web site, in the same directory as the web page that will use it.

An OpenGL applet needs a lot of support files to run. Fortunately, all that you need to do is use the correct <applet> tag on the web page, and the Java runtime will download the required support files from the web. (When a user visits the web page, they might get a warning about accepting a certificate for the downloaded files. You might want to warn them about this -- and about the fact that OpenGL applets are not completely reliable yet.)

Here is an applet tag for an applet that uses Jogl 1.1.1, with the part that you have to modify shown in bold red. This is the tag for the applet that appears at the bottom of this page. It uses a jar file named "SphereAndCube.jar", and the applet class that is to be executed is "SphereAndCubeApplet":

   <p align="center">
   <applet code="org.jdesktop.applet.util.JNLPAppletLauncher"
         width="500"
         height="520"
         archive="SphereAndCube.jar,
                  http://download.java.net/media/applet-launcher/applet-launcher.jar,
                  http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jar,
                  http://download.java.net/media/gluegen/webstart/gluegen-rt.jar,
                  http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl-demos.jar">
      <param name="codebase_lookup" value="false">
      <param name="subapplet.classname" value="SphereAndCubeApplet">
      <param name="subapplet.displayname" value="Sphere And Cube">
      <param name="noddraw.check" value="true">
      <param name="progressbar" value="true">
      <param name="jnlpNumExtensions" value="1">
      <param name="jnlpExtension1"
             value="http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jnlp">
   </applet>

The main things that you need to do are to put the name of your own jar file in the archive attribute of the <applet> tag, in place of "SphereAndCube.jar", and to set the value of the "subapplet.classname" param to the name of your own applet class, instead of "SphereAndCubeApplet". You will also want to set the width and height of the applet. You can set the "subapplet.displayname", but it's not really important. Everything else should be left exactly as shown here. (The value of the archive attribute might be better on one line, but it seems to work spread out over several lines as I've shown it here.)


David Eck for CPSC 424