CS 4451, Fall 2004

Project 1: Transformations and Projection

Due: Wednesday, September 8, 2004, 11:59pm

Objective

The goal of this assignment is to write the routines that allow a user to transform and view 3D graphical objects. In particular, you will write the routines for creating line drawings of both orthographic and perspective scenes. The transformation routines that you create will implement a matrix stack and will allow you to arbitrarily rotate, translate and scale an object. To make this assignment easier, routines will be provided for you that implement line clipping and line drawing. The images that you create for this exercise will be three dimensional line drawings of scenes with no hidden surfaces or filled polygons. All of the lines will be uniformly white so that you will not need to perform color interpolation.

Routines You Will Create

In this assignment you will be creating routines that mimic the behavior of several OpenGL library routines. Below is the list of routines that you will create for this assignment.

gtInitialize(): The gtInitialize command should initialize your matrix stack to have just a single matrix on the stack. This matrix should be the identity matrix.
gtPushMatrix() gtPopMatrix(): The gtPushMatrix command replicates the matrix at the top of the matrix stack and places this new matrix on top of the stack. This new top matrix is now the current transformation matrix. The gtPopMatrix command pops the top matrix off the stack, causing the next matrix down to become the current transformation matrix. An error message should be printed if a pop is attempted when only one matrix is on the stack. As described under the gtInitialize command, the matrix stack is initially created with an identity matrix as the only matrix on the stack. Your stack only needs to handle up to 10 matrices on it at any one time.
gtTranslate(float tx, float ty, float tz): Multiply the current transformation matrix on the right by a matrix specifying a translation of (tx, ty, tz). The current transformation matrix is defined to be the top matrix on the matrix stack.
gtScale(float sx, float sy, float sz): Multiply the current transformation matrix on the right by a matrix specifying a (possibly non-uniform) scaling of (sx, sy, sz).
gtRotate(float angle, float ax, float ay, float az): Multiply the current transformation matrix on the right by a matrix that specifies a rotation of "angle" degrees about the axis (ax, ay, az). The rotation is counter-clockwise as one looks from the position (ax, ay, az) towards the origin. For example, the command gtRotate (30.0, 1.0, 0.0, 0.0) specifies a 30 degree rotation counter- clockwise around the x-axis.
gtOrtho(float left, float right, float bottom, float top, float near, float far): Specifies that a parallel projection will be performed on subsequent vertices. The direction of projection is assumed to be along the z-axis. The six values passed to this routine describe a box to which all lines will be clipped. The "left" and "right" values specify the minimum and maximum x values that will be mapped to the left and right edges of the framebuffer. The "bottom" and "top" values specify the y values that map to the bottom and top edges of the framebuffer. The "near" and "far" values specify the nearest and farthest z values that will be drawn. The eye point is assumed to be facing the negative z-axis, so the "near" and "far" values actually define clipping planes along negative z.
gtPerspective(float fov, float near, float far): Specifies that a perspective projection will be performed on subsequent vertices. The center of projection is assumed to be the origin, and the viewing direction is along the negative z-axis. The value "fov" is an angle in degrees that describes the field of view. In order to make it easier to write this routine, we will assume that all screen sizes will be square, so you don't need to worry about the vertical and horizontal field-of-view being different. The "near" and "far" values specify the locations along the negative z-axis at which to perform near and far clipping in z (just as in the gtOrtho command).
OpenGL uses a separate matrix to do projection that is different than the current transformation matrix and its associated stack. This means that in OpenGL, you can specify projections at any time before you draw lines and polygons. We will do the same for our assignment. Which ever projection that you specify (gtOrtho or gtPerspective) should be the last transformation that is applied to the line endpoints, regardless of where those procedure calls appear with respect to other transformations.
gtBegin(GT_LINES) gtEnd() gtVertex3f(float x, float y, float z): The gtBegin and gtEnd commands signal the start and end of a list of endpoints for line segments that are to be drawn. Each call to the routine gtVertex3f between these two commands specifies a 3D vertex that is a line endpoint. White lines are drawn between successive odd/even pairs of these vertices. If, for example, the four vertices v1, v2, v3, v4 are given in four sequential gtVertex3f commands then two line segments will be drawn, one between v1 and v2 and another between v3 and v4.
The vertices of the lines are modified in turn by the current transformation matrix and then by which ever projection was most recently described (gtOrtho or gtPerspective). Only one of gtOrtho or gtPerspective is in effect at any one time. These projections do not affect the matrix stack and the current transformation matrix. Your gtBegin, gtVertex3f and gtEnd commands must be able to draw any number of lines. You should draw the lines as soon as both vertices are given to you (using gtVertex3f), so there is no need to store more than two vertex positions at any time.

Code Provided

We will provide the following low-level routines that you must use in order to complete this assignment:

gtBeginGraphics (int w, int h); gtEndGraphics (); gtWriteFramebuffer (char *filename); gtClear (int red, int green, int blue);

The above low-level graphics routines draws nothing on the screen, but instead operates purely on a memory-only version of the framebuffer. Here are descriptions of each of the provided library routines:

gtBeginGraphics (int w, int h);: Creates a framebuffer in memory that is w pixels across and h pixels high.
gtEndGraphics ();: This routine tells the graphics library that you are finished making graphics calls.
gtWriteFramebuffer (char *filename);: This routine writes the entire contents of the framebuffer to an image file. The type of the image file that it writes is known as a PPM file, which stands for Portable PixMap. This file format is understood by many image display programs on various platforms.
gtClear (int red, int green, int blue);: This clears all the pixels in the framebuffer.

In order to use the provided graphics library, you will need to add the following include line to your C code:

#include "gtGraphics.h"

Two routines will be provided for you that will perform the necessary clipping and drawing of lines. This means that there is no need for you to write any clipping or line drawing code. These routines are:

near_far_clip(near, far, x0, y0, z0, x1, y1, z1)

This routine clips the line from (x0, y0, z0) to (x1, y1, z1) to the specified "near" and "far" clip distances along the z-axis. The "near" and "far" values are floats. The other six values are pointers to floats so that they may be altered by the routine. This routine returns a value of 1 if at least part of the line is visible, and 0 if it is entirely outside the window. DO NOT DRAW THE LINE IF THIS ROUTINE RETURNS 0.

draw_line(float x0, float y0, float x1, float y1)

This routine draws a white line from (x0, y0) to (x1, y1). The coordinates are 2D pixel coordinates for the currently defined framebuffer. If, for example, the framebuffer is 100 pixels wide, the left edge of the screen is x = 0 and the right is x = 100. This routine performs clipping to the framebuffer window.

All these library routines can be downloaded here:

prog1.zip (for Visual Studio .NET.)

prog1_vc6.zip (for Visual C++ 6.0)

What You Will Write

You will write code ONLY in at most two files: matlib.c and matlib.h. All of your routines should be contained in matlib.c, and matlib.h should contain any header information that you require. We have provided a "dummy" version of matlib.c that you can use as a starting point for creating your own complete version.

All test samples have already been contained in our codes. Put command arguments from 1 to 10 can let you choose each test sample. Under MS Visual Studio environment, the command line can be added when debugging: In the menu, click "project -> prog1 properties -> Debugging -> Command Arguments", then type the command line, like "1", "2", ...or "10".

Suggested Approach

First, become familiar with using the draw_line routine. Second, implement the matrix stack and the gtTranslate and gtScale commands. Test them out by applying the current transformation matrix to the line endpoints and then just draw lines by ignoring the z-values. Third, write the gtOrtho command. This should be fairly straightforward once you have already drawn some lines by ignoring the z-values of the transformed vertices. Fourth, implement the gtPerspective command. The best way to test out this routine is to carefully work out some simple test cases on paper and match the execution of your code with these worked-out examples. Finish by implementing the gtRotate command. Logically this command should be implemented together with gtScale and gtTranslate, but it is a little tricker. You will need to create and manipulate matrices and vertices in order to implement the transformation routines. Here are possible definitions:

typedef float gtMatrix [4][4];

typedef float gtVertex [4];

Because the last row of a typical transformation matrix is 0 0 0 1, you may instead choose to use 4 by 3 matrices. You may also decide not to store the implicit 1 that is the fourth element of a homogeneous coordinate of a vertex. Two important routines that you will need to write are matrix-matrix multiplication and matrix-vector multiplication. Your choices of data structures will affect the details of these routines.

You will probably write routines that perform operations such as matrix multiply and vector cross-product. It is easy to accidentally write a routine that clobbers some of the results if the routine is called using the same matrix more than once. For example, the invocation "mult_matrices (a, b, b)" is meant to multiply a time b and put the result in b. If you are not careful, however, you will overwrite part of b before you use all of the values in that matrix. The best way to avoid this is to place all your results in a temporary matrix and then copy the results to the final destination when you are finished.

Authorship Rules

The code that you turn in entirely your own. You are allowed to talk to other members of the class and to the Professor and the TA about general implementation of the assignment. It is, for example, perfectly fine to discuss how one might organize the data for a matrix stack. It is also fine to seek the help of others for general C or C++ programming questions. You may not, however, use code that anyone other than yourself has written. Code that is explicitly not allowed includes code taken from the Web, from books, from previous assignments or from any source other than yourself. The only exception to this rule is that you should use the GT Graphics Library routines and the test code that we provide. You may NOT use other library routines for matrices and stacks such as STL (for C++). You should not show your code to other students. Feel free to seek the help of the Professor and the TA for suggestions about debugging your code.

Development Environment

You may use any environment you wish for developing your code, but it must compile in Windows ( MSVC++ 6.0 or Visual Studio.NET). The visual studio solution file, the project and workspace files should also be provided along with the .h and .c source files.

Setup For MSVC++ 6.0

Start MSVC++ 6.0.
Create a new empty console application. In the menu, click File --> New, select "Win32 Console Application", type in a Project name, select a directory location (under which a subdirectory named after the Project name will be created), and click OK. Select "An empty project" and click Finish, then OK.
Copy all provided source files into the newly created project directory.
Add the source files to the project. In the menu, click Project --> Add To Project, Files.... Select all the .h and .c files except draw.c and click OK.
Click the FileView tab and expand the list to see the source files.
Note that once you have confirmed the program works, you will want to remove drawtest.c from the project and add draw.c. To remove drawtest.c, click on it in the FileView and press delete.

Setup For Visual Studio .NET

Start Microsoft Visual Studio .NET.
Create a new empty console application. In the menu, click File --> New, select "Visual C++ project" as the project types and select "Win32 Project" as the templates, type in a Project name and select a directory location (under which a subdirectory named after the Project name will be created), then click OK. Select "Application Settings" folder, select "Console application" and "Empty Project", then click Finish.
Copy all provided source files into the newly created project directory.
Add the source files to the project. In the menu, click Project --> Add Existing Item. Select all the .h and .c files except draw.c and click OK.
View all header files and source files in your Solution Explorer. If it has been closed, open it again by select "View->Solution Explorer".
Note that once you have confirmed the program works, you will want to remove drawtest.c from the project and add draw.c. To remove drawtest.c, click on it in the Solution Explorer and press the delete button on your keyboard.

Viewing .ppm Files

The computers in the States Lab have the right software loaded to view .ppm files. In WinXP, CNS has installed Maya which has an image viewer that can handle .ppm files. Fortunately, this is the default viewer associated with the .ppm file type on these machines and you can simply double-click a .ppm file to view it. In linux, the appropriate image viewer can be invoked by typing "kview" from the command prompt. It may also be invoked via the RedHat menu --> Graphics --> More Graphics Applications --> Image Viewer.

Sample Results

What To Turn In

Create a .zip or .rar file of your matlib.h, matlib.cpp and other routine files you wrote if there are any. Name this zip file "p1_{your name}.zip", where {your name} is your full name without spaces. For example, Huamin Wang would create "p1_HuaminWang.zip".

Submit your assignment by email to the TA (whmin@cc.gatech.edu). Put "cs4451a: prog1" in the subject line.

You should get a confirmation email if your assignment has been received.