Details of the Trace project debugging user interface
One of the useful tools we are providing with the Trace project is a
debugging interface, which you can use to experiment with tracing
individual paths through the scene and visualize exactly what is going
on with your code. This is meant to be an introduction to the
capabilities of this UI.
The first thing you should note is that the UI is already there and
ready for you; you don't have to do anything to enable it. All you
have to do is load a scene file and toggle the "Debugging display"
check box to open the debugging window. Every time you call
Scene::intersect, the ray and its intersection is cached
so that it can be displayed. As long as you always use this method to
cast rays, they will hence be displayed (including shadow rays, if you
use this method in your shadow-handling code). The only thing you have
to do is when you are creating the ray that will be traced, identify
what kind of ray it is (the options are REFLECTION, REFRACTION,
VISIBILITY, and SHADOW). The cache is cleared out at the top-level
RayTracer::trace, so that when you view traced rays in
the debugging window, only the ones for a particular pixel are shown.
This is what you will see when you enable the debugging view with the
skeleton code. You will notice a number of features, each of which can
be turned on or off using the "Display" menu:
Notice also that even though the skeleton code does not have Phong
shading enabled, the debugging view does. This is, of course, because
the debugging display uses OpenGL for all of its shading. This has a
- A camera, which shows the center of projection and the projection
plane (for clarity, the rendered image appears on the projection
- The scene origin, with positive x, y, and z axes shown.
- Two directional lights (these are the groups of arrows).
Each is colored with its actual intensity.
If the scene had point lights, these would also show up.
- The yellow dotted line is a traced ray. At the place where it
intersects with the cone, the normal is shown in green. Note
that the UI takes the normal information from what is stored in the
isect class; if you calculate your normals wrong
when you are calculating intersections, they will appear
incorrect in the debugging view as well.
- You can use the same controls to zoom around in the window that you
used in the Modeler project.
- OpenGL does not support reflection and refraction. You will no doubt
find the UI a valuable tool for debugging your reflection and refraction
code, since you can easily see where your reflected and refracted rays
are going, but you will not be able to see the refraction effects in
the debugging view itself. Use the sample raytracer to see what the
results should look like.
- If you introduce your own primitives, they won't appear in the debugging
window. You are welcome to write your own "glDrawLocal" method if
you feel this will help in debugging. Model it after the ones in
Now, as described above, you can easily move in and around the scene
using the controls that you should be familiar with from Modeler. In
order to get the full use of the debugging window, you should use the
Rendered Image window to trace individual rays. Simply clicking on a
pixel in the image window will cause the raytracer to trace rays
through that pixel to the maximum depth specified by the depth slider.
- You have a variety of shading options. In particular, "wireframe"
will let you see through the opaque surfaces, which will be helpful
when you're debugging refraction.
- You can either use the default debugging lighting (which illuminates
everything so that you can see it) or turn on the actual scene
lighting if you're trying to debug the lighting code.
- Same as above for materials; this may be helpful if the materials
in the scene aren't showing up well in OpenGL.
- You can turn on and off any elements of the scene you want. In
particular, you can enable/disable any individual kind of ray, if
you only want to see visibility rays. Shadow rays are disabled
by default, and if enabled they show up in blue. But they won't
show up at all if you aren't labelling your rays correctly, or
you don't use the
- Objects will show up in the debugging window even if you haven't yet
written the intersection code that allows the objects to be rendered in
the Rendered Image window. So you can use the debugging window to get
a feel for what a scene should look like once you have your intersection
One problem you may encounter is that the camera code for the
debugging view uses heuristics to determine what should be a good view
of the scene. This seems to be correct for most reasonable scenes,
but there may be scenes where you find that the heuristics fail and
the scene itself starts out entirely out of the view frustrum. You
should be able to maneuver it back in if this happens.
If you try to open the debugging window without first loading a
scene file, the program will crash. Just make sure you have a scene
file loaded first.