Due February 3rd (assn1a)
You can use your own computer (Windows, Mac or Linux) for this class. If you do not have a suitable computer, it is possible to arrange remote access to computers on campus. Contact me directly if you think you will need this.
The first part of this assignment is just to make sure you are set up and will be able to submit later.
You will need some local git tools. It will not be enough to just use the github web interface. A graphical user interface for git can make some operations easier, though it is good to develop some familiarity with the command-line git tools as well.
- Command-line tools:
- Github desktop (Windows/Mac): Popular, though not as polished looking or capable as some others.
- Sourcetree (Windows/Mac): Used to be my preferred git GUI. Need to register (free) to use.
- Fork (Windows/Mac): This is the one I currently use. $50 license, but free evaluation.
- Many more (including some for Linux).
CMake is a cross-platform tool for making build files (Visual Studio solutions, XCode projects, Makefiles, etc.) from a common text-file description. This will help make sure we don't actually need to use the same OS as you to build, run, and test your code.
You will be using C++ for all of the programming assignments this semester.
- Linux: Probably already installed. You'll want the C++ compiler and make or eclipse.
- Windows: Install Visual Studio. The free "Community Edition" is fine. Make sure you have it set up with the "Desktop Development with C++" and "Game Development with C++" workflows. You can re-run the Visual Studio setup to change or add workflows if you aleady have it without these.
- Mac: Install Xcode
You will be doing your work this semester in a class git repository.
- If you do not already have an account on github, make one
- Fill out this google form to tell us your github username (you will need to be logged in with your umbc account to access the form).
- Once you receive and accept the GitHub team invitation email, you will be able to see the class repository at github.com/UMBCGAIM/graphics21.
- Fork the repository, then in "Settings" > "Manage access" for your fork, add "olano" with Admin permissions. See the in-class demo, or look at some of the many git tutorials online.
- Make your own local clone of your personal repository on your computer. You'll see a trace directory, containing a CMakeLists.txt file. You will put your source code for the first assignment in this directory.
To make sure you do not have last-minute problems, you must set up your git, make a local clone, and do an intial commit, push, and tag to your repository by February 3rd.
- Create an assn1a.txt file at the top level of the repository and put whatever comments you want in there.
- Use your local git command-line or GUI tools to add and commit that file.
- Using the command line, "
git status" lists files that might need to be committed.
git add" listing individual file names or "
git add ." adds them to the list to be committed.
git commit -m 'message'" commits those files with a descriptive message.
- Using the command line, "
- Push those changes back to github.
- Command line: Just "
- Command line: Just "
- Tag that commit with an "assn1a" tag, and push that tag to github. Git tags are typically used for software releases. We will be using tagged releases for each assignment so we know which commit to grade, even if you keep working and pushing changes after your submission commit.
- Command line: "
git tag assn1a" to tag locally.
- Then "
git push origin assn1a" to push that tag to github.
- Command line: "
Due February 14 (assn1)
For this assignment, you must write a C or C++ program that will render spheres using ray tracing. The input is in a subset of the rayshade (.ray) file format, containing information about the view and objects in the scene. You will read a .ray scene from a file, and ray trace the single image described there. Rays that hit an object should be rendered in the object color, while rays that do not hit any object should use the background color of the scene. Do not try to include any of the more advanced ray tracing features you may read about (shadows, reflection, refraction, lights, etc.), we will get to those later. Your output should be an image file in PPM format.
We are using the PPM image file format because it is exceedingly simple to write. See the specification for details. PPM files can be viewed directly or converted to other image formats for viewing. The Mac Preview app will open these files. On Windows or Linux, the ImageMagick package includes a "
display" program to view these files and "
convert" convert PPM into most other image formats. Alternately, the Gimp package can both display PPM images and save in other formats.
To create a PPM file, first you should store your image in an array of bytes in y/x/color index order:
unsigned char *pixels = new unsigned char[HEIGHT*WIDTH*3];
When filling in this array, remember that it is in y/x order, not the more familiar x/y order, with 0,0 in the top left corner of the image. The third index of the array is the color component, with red=0, green=1 and blue=2. Color values range from 0 to 255. Color values in your ray tracer should be floating point fractions, so you will need to scale to convert them to a byte. Be careful to check for overflow or underflow when mapping floating point values into a byte. For example, this would store a floating point color value
g into the green component of the pixel at x=50 and y=25:
pixels[25*WIDTH*3 + 50*3 + 1]= (g<0) ? 0 : (g>1) ? 255 : (unsigned char)(g*255);
Once you've filled in the
pixels array, actually writing the PPM file is quite simple. It is just a text header consisting of the characters, "P6" (identifying a binary color PPM file), text lines containing information about the image, followed by the raw binary data. Here's the complete stdio-based code necessary to write a PPM file:
FILE *f = fopen("trace.ppm","wb"); fprintf(f, "P6\n%d %d\n255\n", WIDTH, HEIGHT); fwrite(pixels, 1, HEIGHT*WIDTH*3, f); fclose(f);
Other people's code
Ray tracing is a popular rendering technique, and the internet contains lots of resources for ray tracers in general and things like ray-object intersection in particular. Other than the PPM snippet above, YOU MAY NOT USE ANY OUTSIDE CODE. All code that you use must be strictly your own.
To use CMake, create a "
build" directory under "
cdinto the build directory.
- Run "
cmake -h" to find the list of generators.
- Run cmake with the appropriate generator selected for your build environment, with "
.." (or the path to the
tracedirectory) as the final argument. For example, "
cmake -G 'Visual Studio 16 2019' ..".
- Open the resulting Visual Studio solution, Xcode project, or run "
- "Where is the source code": locate your
- "Where to build the binaries": locate the
- Click "Configure".
- Click "Generate".
- Click "Open Project", or navigate to build directory and open it.
This is a big assignment. Start NOW, or you will probably not finish. No, really, I promise you will not be able to do it in the last two days. Even before we get to all of the details of the ray tracing itself, you can still start working on your file parsing.
I have created a separate page with some additional development suggestions.
What to turn in
Turn in this assignment electronically by pushing your source code to your class git repository by 11:59 PM on the day of the deadline and tagging the commit
assn1. Do your development in the
trace directory so we can find it.
Also include an
assn1.txt file at the top level of your repository telling us about your assignment. Tell us what works, and what does not. Also tell us what (if any) help you received from books, web sites, or people other than the instructor and TA.
You must make multiple commits along the way with useful checkin messages. We will be looking at your development process, so a complete and perfectly working ray tracer submitted in a single checkin one minute before the deadline will NOT get full credit. Individual checkins of complete files one at a time will not count as incremental commits. Do be sure to check in all of your source code, but no build files, log files, generated images, zip files, libraries, or other non-code content.