COMS W4160— Computer Graphics Spring 2021 Programming Assignment 1
out: Jan. 30, Saturday
due: Feb. 13, 10:00PM Saturday (submit to courseworks)
In this programming assignment, you will learn how to build an interactive graphics application in
OpenGL, and apply the geometric transformations that we discussed in class.
NOTE: This is your first programming assignment, and you have two weeks to finish the assignment.
There is a learning curve of OpenGL if you are not familiar with it. Also, you might need to refresh your skills of Java programming. We encourage you to start early on this assignment and do not procrastinate! If you leave only a few days on this assignment, it is unlikely to finish it with high quality.
1 Getting Started
Plenty of reference materials and tutorials exist online (such as the OpenGL Website, the OpenGL red book, the LWJGL Gitbook, and the supplemental materials we referred in class and course website). You are allowed to use any publicly available references to assist your programming. However, all code in your submission is expected to be your own. In addition, your submission must include a writeup doc- umenting your implementation ideas, important details, and all external references/sources used to complete your assignment.
A Java starter code can be found on courseworks. It illustrates the way to setup a basic OpenGL application that displays a simple 3D scene in perspective, along with some other basic functionalities for user interaction using the Java OpenGL library LWJGL. Yet, it contains no code for anything particularly interesting—you need to develop that code yourself.
Grading. Your code will be graded using JDK 15 and LWJGL 3. In addition, the starter code also use the Java math library JOML and a library, PNGJ. The latter is for saving a screenshot of your program into a PNG file, both of which are included in the starter code package (under the folder lib/). Please make sure your code can be successfully compiled under these settings. For this assignment, other external Java libraries, beside LWJGL, JOML, and PNGJ, are not allowed.
Please do not use other’s code or download code online. When grading, we are going to run plagiarism detector over all submissions. We also reserve the right to ask students to come to explain their code line by line. If you write your own code, you must be able to explain your code line by line. Clear-cut cases of dishonesty will result in failing the course and reporting to the Dean’s o ce.
1.1 OpenGL Demos and Tutorial
To help you become familiar with the OpenGL (and GLFW), I will show a few simple demos in the lecture (next Tuesday) and briefly described them. In the starter code folder, I include the demos in the subfolder OpenGL demos/, where there is also a tutorial (see OpenGL demos/tutorial.pdf) prepared by our previous course CA, Mandeep Bhutani (Thanks for his e↵ort!). Before starting working on your assignment, we encourage you to follow the tutorial step by step to understand the demo code.
Reading through the tutorial is not a requirement of this programming assignment. But if you are not familiar with OpenGL, it’s a good practice.
1/6
COMS W4160— Computer Graphics Spring 2021
Figure 1: Uninteresting display of the starter code.
1.2 Starter Code
We have prepared a Java starter code that uses the library LWJGL 3, which has been included in the lib/ folder. You can also download it online. You can compile the source code in your favorite IDE (such as Eclipse). Alternatively, if you installed the Apache Ant, after downloading the starter code you simply open a terminal1 and type
unzip pa1_starter.zip && cd pa1_starter && ant
To successfully run ant, you need to specify the library path of LWJGL in the file build.xml (i.e., change Line 5 of build.xml). If you are not familiar with Apache Ant, it is a tool for automating Java projects’ build processes, a replacement for the Make build tool of Unix. A simple tutorial for using Ant is available here.
A successful run of the above command will launch the starter code, which will display a cube with flat shading (see Figure 1) — a boring display for you to make it more interesting. Once the display window shows up, you can drag your mouse with the left mouse key down to rotate the object interactively.
Note. To run the starter code, it needs to enable a Java virtual machine option -XstartOnFirstThread, which we already included in the ant build file (e.g., see Line 73 of build.xml). This should work on most operational systems. But we realize that in some rare cases, you might have to disable that option on some platforms. So try to disable -XstartOnFirstThread (e.g., comment out Line 73 of build.xml) if your first run doesn’t work.
2 Programming Requirements
You first task is to read through the code and understand it. The starter code is more complex than the demos. The core OpenGL rendering logic is in w4160.game.Renderer and the core loop for user interaction is in w4160.engine.GameEngine, which uses the specific control logic implemented in w4160.game.SimpleGame.
1Here we illustrate the command using bash, which is available on both Mac OS and Linux. If you are using MS Windows, the commands are similar.
2/6
COMS W4160— Computer Graphics Spring 2021
Figure 2: A Java documentation providing explanations for the classes and methods you need to work on.
Certain parts of the code are about setting up GLSL shaders, lightings, and object materials. You don’t have to understand all those details if you are new to OpenGL. You will learn all those concepts later in the class. For now, you just need to understand what those code is for and use it.
To help you navigate through the classes, we prepared a Java documentation in the subfolder doc/. Open doc/index.html to see all classes and some explanations of the classes and methods related to your implementation (see Figure 2).
After you have a good sense of the starter code, you need to add your code to satisfy several specific requirements:
a. Changing the background color. As a test of your understanding of the code, we ask you for a simple task: Right now, the OpenGL background color is dark blue (see Figure 1). Find the code that sets up the background color and change it into pure black.
b. Key binding. Add a key binding to the key “1” such that when the user presses “1”, it captures a screenshot of current displaying window. We have already provided you the functionality of save the current displaying window into an image file. Find it and use it.
This feature will become useful in the next programming assignment for screen capturing a video or animation.
c. Loading a triangle mesh. Next, you need to write a piece of code to load a triangle mesh file stored in .obj file format. The OBJ file format is a simple file format that represents 3D geometry alone. You can refer to the online format specification for its format details. Your task is to complete the method of OBJLoader.loadMesh(String filename) which returns an instance of the Mesh class. (You need to read the code and comments to understand the data structure of the Mesh class first.)
Once you implement it correctly, you should now be able to load an .obj file and display it, for example, by running
3/6
COMS W4160— Computer Graphics Spring 2021
ant -Dargs=src/resources/models/bunny.obj
or using Java command line
java -XstartOnFirstThread -cp $[LWJGL]:lib/*:build/classes w4160.game.Main src/resources/models/bunny.obj
where $[LWJGL] must be replaced with the LWJGL folder on your computer.
Note. Caution needs to be taken to write a robust OBJ loader. For example, some OBJ file may
come without any texture coordinate while other files may have texture coordinates. Also, multiple sets of indices may be provided in the face section (such as a line f 1/1/2 2/3/2 4/2/1) of the OBJ file, for which the indices of positions, texture coordinates, and normals may be di↵erent. But the Mesh class expects a single index array to use in OpenGL. You need to reconcile them. Please refer to the comments in the OBJLoader.loadMesh(String filename) for some hints, and refer to the folder src/resources/models/ for a few examples of OBJ files.
d. Geometric transformation. After you complete OBJLoader, its method loadMesh returns an instance of the class Mesh. In this class, there are several empty methods that you need to implement in order to transform the triangle mesh.
1. translate(Vector3fc tran) Translate the mesh by a given vector.
2. scale(float sx, float sy, float sz) Scale the mesh by sx, sy, and sz along the x-, y-, and z- direction,
respectively.
3. rotate(Vector3fc axis, float angle) Rotate the mesh around the given axis by the degree angle. The rotation angle is given in degrees.
4. reflect(Vector3fc p, Vector3fc n) Reflect the mesh with respect to the given plane. The plane is specified by the equation
( x ̃ p ̃ ) · n~ = 0 .
After successfully implementing these methods, you should be able to press “0”, “9”, “8”, and “7” keys to manipulate the mesh. Please refer to the key binding function (at this point, you should know where it is) to see how the keys are mapped to specific methods of the Mesh class.
e. Camera projection. Next, you need to implement the projection, view, and model matrices yourself without using the OpenGL calls. The projection, view, and model matrices are transformation matrices used to project 3D objects on a 2D screen. The methods you need to complete are in Transformation.java. The methods in Transformation will be used in the method of Renderer.render. Please also refer to Chapter 7 of the textbook [S&M].
f. Displaying and manipulating multiple objects. So far your program can load and display only one OBJ file. Your next and last task is to modify the code to allow loading multiple OBJ files and manipulate them. You need to 1) modify w4160.game.Main.java to accept multiple OBJ file paths as the command line arguments. For example, the user should be able to run
java -XstartOnFirstThread -cp $[LWJGL]:lib/*:build/classes w4160.game.Main
src/resources/models/bunny.obj src/resources/models/monkey.obj
4/6
COMS W4160— Computer Graphics Spring 2021
to load two OBJ files. 2) Modify the code in w4160.game.SimpleGame.java to load multiple OBJ files. A starting point of your implementation is the constructor SimpleGame(String[] meshFile) in SimpleGame.java. To this goal, you also need to modify other parts of SimpleGame.java. 3) Add the key bindings so that the user can select a specific object to manipulate. In particular, if N objects are loaded, pressing “Q” should select the next object in the list (i.e., if the i-th object is currently selected, pressing “Q” chooses (i+1)%N-th object). And pressing “W” should select the previous object in the list (i.e., if the i-th object is currently selected, pressing “Q” chooses (i 1 + N)%N-th object). With these key bindings, the other existing key bindings, such as “9”, “8”, . . . , are to manipulate the currently selected object.
3 Submission and FAQ
Submission Checklist: Submit your assignment as a zip file via courseworks. Your submission must consist of the following parts:
1. Documented code: Include all of your code and libraries, with usage instructions. Your code should be reasonably documented and be readable/understandable by the CAs. If the CAs are not able to run and use your program, they will be unable to grade it. Try to avoid using obscure packages or OS-dependent libraries. To ensure the CAs can grade your assignment, it is highly suggested to compile your code with Java 8, and include details of compiling and running your code.
In the starter code, we also include a build.xml file which is used to ease your compile and run the code using the Apache Ant building system. It is optional to modify the ant building file for your project, while it will probably make the compile more organized and less tedious. It will also ease the grading work of CAs.
2. Brief report: Include a description of what you have attempted, special features you’ve implemented, and any instructions on how to run/use your program. In compliance with Columbia’s Code of Academic Integrity, please include references to any external sources or discussions that were used to achieve your results.
3. Instruction of running your code: You need to include a list of instructions to tell CAs how to run your code to demonstrate the functionality you implemented. Here is an example of the instruction list,
• Requirement a): just run ant
• Requirement b): run
ant -Dargs=src/resources/models/bunny.obj
and press “1”.
• Requirement c): run
ant -Dargs=src/resources/models/bunny.obj
• Requirement d): run
ant -Dargs=src/resources/models/bunny.obj
and press “0” for translation, “9” for rotation, “8” for scale, and “7” for reflection.
• Requirement e): run
ant -Dargs=src/resources/models/bunny.obj
5/6
COMS W4160— Computer Graphics
and drag the mouse.
• Requirement f): run
java -XstartOnFirstThread -cp $[LWJGL]:lib/*:build/classes w4160.game.Main
src/resources/models/bunny.obj src/resources/models/monkey.obj
and press “Q” and “W” to select the object.
Spring 2021
Since we have a large class, please keep in mind that it is your job to tell CAs clearly how to run your code and demonstrate the functionalities. The CAs may not be able to read through your code carefully to check the correctness of your code. They will run the code to check if the required functionalities are satisfied. So please tell them step by step how to run your code. It will save lots of their time and e↵ort.
Evaluation: Your work will be evaluated on how well you demonstrate proficiency with the requested OpenGL functionality, and the quality of the submitted code and documentation.
6/6