Survey of STL

One thing you should definitely be aware of for the Trace project is that it makes extensive use of the Standard Template Library, or STL.

The STL is a very large collection of templated C++ classes that implement a large number of data structures and algorithms.  Here, we have used the STL to keep track of several data items, including a list of light sources – something you will need to use.  As such, this is a very brief description of how to use the STL list structure.

Access to the STL's container classes, like ‘list,’ is managed through objects called iterators, which give a clean way to operate on each member of the list.  If I defined this:

class foo_c { /* some stuff */ };
list<foo_c> foolist;

It makes a STL list of class foo_c. It also defines an iterator type called "list<foo_c>::iterator". Normally, to make typing easier on yourself, you would put a type-def on the iterator.

class foo_c { /* some stuff */ };
list<foo_c> foolist;

Now, when I'm ready to add stuff to that list, I use "push_front" to add items to the beginning.

foo_c myFoo;
/* do what you want to myFoo */
foolist.push_front( myFoo );

And when I want to access the list items, I iterate through them like this:

list<foo_c>::iterator iter1;
for( iter1 = foo.begin(); iter1 != foo.end(); ++iter1 ) {
  // At this point, *iter1 is the current list item, just
  // as if iter1 were a pointer.
  cout << *iter1;
  *iter1 = something;
}

And finally, it's easy to delete an item from the list too. If you have an iterator pointing to the item you want to get rid of, you can call this:

foolist.erase( iter2 );

That's in general, how any of the storage classes work, whether a list or some other type.  Applied to the trace program, you would for instance use an iterator to loop through all the lights in the scene.  The only additional trick is that some of the data you might want to access is encapsulated with member functions to get at it.  For instance, the Scene::beginLights() and Scene::endLights() methods exist for no reason than to pass back iterators to the list of lights.