Recently, I have been working in Shockwave3D in Lingo and JavaScript syntax. Regardless of what I am writing, I keep running into issues that can be summed up by the following phrase: I don't know exactly what I'm doing. More precisely, I don't know exactly what I am doing when I am doing it. I'm figuring it out. And that's what programming interactive things is all about: finding a way to do what you need to do, such that the user has the experience you want them to have. Unfortunately it is sometimes difficult to tell exactly what your code is doing, and this is particularly true in 3D environments.

So with these issues in the back of my mind, I was working on my lightmap generation tool, and I was really getting stuck. A "lightmapper" is a tool that pre-generates, through raytracing or other means, a series of maps that represent the lighting in a 3D scene as textures on the individual objects. This is a very popular technique in game-level design, as Brian Robbins noted at MAX, and as several authors have noted in the game development community. Figure 1 shows a few sample renders from my tool in progress.

The problem I was having was in projecting the shadows, particularly in figuring out the angle to each light from the points along the surface. I was never really "sure" of exactly where the ray was that I was checking against. This is relatively easy to figure out for a single light, but I was getting very confused when calculating multiple light sources (see Figure 2). In order to figure out just what was going on, I used a strategy that I have used in the past: build a visual "prop," or "stand-in" of the ray itself. The only complication is that Shockwave3D has no #line primitive. No problem! Just make a very long, skinny triangle. Listing 1 shows a Lingo handler that creates a "connector" object: it has a triangle that it uses as a "line," which it can snap between a beginning and end point. Additionally, it can color each end of the "line" a different color, and blends the two together along the triangle face.

Using these lines, I was able to trace out each and every light path in the scene, and get a sense of whether or not it was doing what I wanted it to do (see Figure 3). This was very handy, but this tool isn't limited to that specific use. I've used it in the past to represent surface normals (something I wish S3D had a #debug flag for), direction vectors, a "point at" vector between two objects, and even rotational axes when I haven't been able to see the ones drawn through the #debug flag. (For some reason, the axes generated by Director are all black when drawn with the DirectX7_0 renderer on my nVidia cards). Because each end of the "line" can be colored separately, they can be used to represent directional vectors, rather than just a straight connection between two points.

In order to get the "lines" to show up well in a debug environment, I generally create a custom shader that ramps up the emissive and ambient qualities (and sets some flags so that the vertex colors actually have an effect). For the script in Listing 1, I used the shader props set in Listing 2. I've also used "lines" in a similar way in JavaScript syntax.

Being able to "see" what is actually going on has proved invaluable for this and several other projects. Using color and shape makes it much easier to tell what the code is doing than an iterative Orun and see' approach. By thinking of debugging visually, tools can be constructed that make it easier to see just what is going on. If you have either already built tools, or are thinking of writing some after seeing these simple examples, I encourage you to share them with the community as you are able, to build up a library of visual aids that help us in our daily work.

• Figure 1
• Figure 2
• Figure 3
• Source Code