COS 426: Computer Graphics Spring 2019

Overview

In this assignment, you will implement some of the core components of a raytracer program.

You will mainly be working in GLSL, which is the shading language for OpenGL. The GLSL syntax is very similar to C.

Deadline: This assignment is due 11:55pm on Sunday, April 7th.

Download the Starter Code

This section of the instructions are analogous those of the previous assignments, so by now this should be very familiar.

To get started, download this zip file and unzip it on your computer. Change to the subdirectory cos426-assign3 and run the command python3 -m http.server (or whichever variant is appropriate for your operating system and version of Python), which will launch a web server on your computer, rooted at this directory. (See previous assignment description about why we do this instead of opening the files directly.)

Once you have started the local web server, direct your browser to http://localhost:8000. For now, you should see the assignment information on the top left, but an otherwise black screen.

Using your favorite text/code editor, edit the file js/student.js and fill in your name and NetID. Reload the web page in your browser, and now your information should appear in the top left.

Driver Setup: Most machines should be ready to go without any additional steps. However, if you are running MacOS High Sierra and have a dedicated NVIDIA graphics card, there is a bug in some of the built-in graphics drivers that will break this assignment. If you have an affected machine (likely a high end Macbook Pro or iMac from 2014 or earlier), you must do one of the following three things:

• Install the latest Web Driver directly from NVIDIA. Note that installing this driver will also install the "NVIDIA Driver Manager" for switching between macOS and NVIDIA drivers. Once the driver manager is installed, click the NVIDIA logo in the top right tray and make sure "NVIDIA Web Driver" is selected. This is the recommended option for patching the bug- once you are using the latest web driver, you can be sure the bug isn't affecting you.
• Disable the NVIDIA card, either through the BIOS or with a tool like gfxCardStatus. This should get the job done, as the integrated intel gpu drivers don't have any issues. However, it is less recommended because it is slower, and Chrome may try to use the discrete card in spite of gfxCardStatus even when passing the --force_integrated_gpu flag. You can check whether the current Chrome window is using the NVIDIA card by navigating to "about:gpu".
• Use a different computer for assignments 3 and 4. :(

If you have any doubts as to whether one of the fixes above has been correctly applied, please ask on Piazza. If it hasn't been patched then correct code will sometimes, but not always, work.

New GUI features in this Assignment

• In this assignment, the raytracer only works in batch mode, because there are relatively few parameters to specify.
• The raytracer specifies parameters on the command line, for example: index.html?scene=default&width=600&height=400 — this names the scene and sets the dimensions. If you omit the scene name it will use 'default'. The scenes are specified in json format in the folder scenes/ and the default scene (for example) is found in scenes/default.json. The width and height default to full screen.
• You can rotate the camera using the mouse, and move forward and backward using the up and down arrow. If the frame rate is too clunky, we recommend reducing the size of the rendering window (see previous bullet in the instructions).
• Pressing the 'I' key will capture an image of the current rendering. (In different browsers you may get slightly different behavior. In Chrome it should force a download while in some other browsers it may open in a different window or tab.) It should be a PNG file; you may need to rename it adding the file extension '.png'. You should use this feature to download your results for your writeup.

Overview of the Codebase

Here is a quick overview of some of the interesting subdirectories.

• coursejs/: infrastructure code for the GUI and raytracer
• js/: contains a single file, student.js, which you should fill out with your information
• scenes/: contains .obj and .json files which are used to represent different scenes to be rendered. We provide two scenes for you to use to test your raytracer's functionality, scenes/default.json and scenes/mesh.json. You may choose to create your own scene as a non-required feature, which would be added here.
• shaders/: contains a fragment shader and a vertex shader GLSL program. To implement the features below, you will only need to make changes to shaders/fragmentShader.glsl, which implements the ray tracer. The vertex shader program does not require any modification.

Before You Start Coding...

The coding for this assignment is done almost entirely in GLSL. It is a powerful language, but tricky to debug. So we recommend making small, incremental changes to the code as you edit, reloading the page often. A compiler error in the shader code will pop up as an alert in JavaScript. For tips on GLSL, see the FAQ below for useful links to references, as well as the precept slides.

Before getting started with coding, make sure the downloaded code works on your computer and browser. When you launch the raytracer, you will not be able to see anything (just a black scene), but you should verify that there are no errors in your console.

In order to get this relatively advanced functionality out of the graphics engine, unfortunately, we are working in a relatively new software interface, and there are variations among browsers and operating systems. It may require some experimentation to find a computer/browser combination that works for you. If you cannot find a good development combination on your own computer, try using a computer running on one of Princeton's computing clusters.

We have tested heavily on Chrome and Firefox on MacOS and these seem to work well.

Features

IMPORTANT: As you work through the assignment be sure to reference this page for further instructions, guidance, tips, and examples for the features below.

The assignment is worth 20 points. The following is an overview of the features that you may implement. You are encouraged to work through the features from the top down, since there are some significant dependencies.

The number in front of the feature corresponds to how many points the feature is worth for the complete and correct implementation. Partial or partially-correct solutions will receive partial credit. Some features are required, and you may choose among the remaining non-required features to reach the total 20 points.

• Ray Tracing Pipeline:
  • [REQUIRED] (2.0) Trace a ray through the scene. Complete the traceRay and calculateColor functions.
• Ray-Primitive Intersection - intersect a ray with various primitive shapes:
  • (0.0) Plane. This is given as an example.
  • [REQUIRED] (2.0) Triangle.
  • [REQUIRED] (2.0) Sphere.
  • [REQUIRED] (2.5) Axis-aligned box (rectangular prism).
  • (3.0) Cylinder. This is represented as an open cylinder plus two discs, which are the two ends.
  • (3.0) Cone. This is represented as an open cone, with a disc that represents the base.
• Lighting and Materials:
  • [REQUIRED] (1.0) Shadows. Cast a single ray to the light to see if a point is in shadow.
  • (3.0) Soft shadows. Cast multiple rays towards an area around the light position to get a fractional contribution for that light.
  • [REQUIRED] (2.0) Transmission rays (refraction). For glass-like surfaces, you need to calculate refraction rays based on Snell's law.
  • [REQUIRED] (1.0) Checkerboard. Modulate diffuse color with a checkerboard pattern based on spatial position.
  • [REQUIRED] (1.5) Phong material. Add the Phong specular term to the lighting calculation to get specular highlights.
  • (1.5) Special material. Create your own material. For example, incorporate a parametric noise texture (like Perlin noise). Feel free to reuse someone else's GLSL implementation of noise, but list your sources.
• Art:
  • (1.0) Scene. Model a scene of your choosing. Be careful that there is a maximum number of triangle faces and increasing this number will slow the program and can also cause the program to fail (depending on your graphics system), so be mindful of going overboard with the complexity of your scene. Check out the provided scenes which are done in JSON format, and place your custom scene in the same directory.
  • (2.0) Animation. Animate a scene (you can access the uniform variable "frame" in the fragment shader - read more on GLSL uniform variables first). To enable this feature you need to add "?animated=1" to the URL. The provided codebase does not save animations, but you can simply provide a link in your submission file and we can see the result. If you really want to save a movie, try using screen-capture software such as QuickTime. If you do, try saving and submitting your animations in .gif format. These files can be rather large, so try to limit the duration and number of the animations you submit.
• Art Contest: You may submit either a static scene or an animation of your scene for the art contest (from the Art section above). Participation in the art contest counts for 1 point, being selected for the art gallery counts for 1.5 points, and being a winner counts for 2 points.

By implementing all the required features, you get 14 points. Full credit for this assignment is 20 points, so to complement the required features you may choose from the optional features listed above and participate in the art contest.

Your final score is based on the following factors:

• r: your score on the required features (up to R = 14 points)
• n: your score on the non-required features (value diminishes when n > N = 6) .
• a: your participation in the art contest (1 point for participating, 1.5 for being selected for gallery, 2 for winning).
• d: diminishing return factor (d = 3/4 in this assignment)

Submitting

You should submit your solution via CS dropbox here. The submitted zip file should preserve the directory structure of the skeleton code we provided in the zip file above.

The writeup.html file should be an HTML document demonstrating the effects of the features you have implemented and would like scored. We recommend that you capture screenshots using the 'I' key of your results incrementally, as you implement each of the features.

For this assignment, please provide results for the given scenes, iff they are relevant to the feature that you have implemented. You will probably provide mostly example screenshots of the scenes/default.json, but will need to use scenes/mesh.json to show us your triangle intersection code, for example.

You should start from the the example writeup.html provided. At the top of that file are a list of features that you might implement, linking to the section where you talk about them. Please remove any features that you do not implement, but otherwise leave this header section intact. To save space, please submit images in png format.

Note that you are expected to use good programming style at all times, including meaningful variable names, a comment or three describing what the code is doing, etc. Partial credit may not be assigned for code without comments. We have mostly tried to conform to the idiomatic JS style conventions.

Feedback: Optionally, please submit feedback at the bottom of your writeup to let us know what your experience was like working on this assignment. For example, you could share how many hours you spent on it, what you thought was difficult, and give us some suggestions on how to improve the assignment for the future. Thank you for your feedback!

FAQ

• What browsers are supported?
  The code has been pretty heavily tested on Chrome and Firefox running on MacOSX. It is possible it will not work on some configurations. We have seen some problems in Safari. If you load the page and see black from the outset, try a different browser or a different computer.

• What version of GLSL are we using?
  In this assignment, we are using WebGL which is an implementation based on OpenGL ES 2.0 that runs in your browser. WebGL only accepts shader programs that conform to the GLSL ES 1.00 specification.

• Where can I learn more about GLSL?
  There are many resources online, including these:

  • OpenGL ES 2.0 / GLSL ES 1.0 Quick Reference Card (see pages 3-4 for GLSL)
  • A general introduction to OpenGL (WebGL) and GLSL
  • OpenGL ES Shading Language Reference (http://www.shaderific.com/glsl/)
  • An overview of differences between C and GLSL (https://www.opengl.org/wiki/Core_Language_%28GLSL%29)
  • Examples and interactive sandbox for GLSL shader programs (http://glslsandbox.com/)