C Pre-Processor "#include" Statements

Even a basic scene composed of cubes - each of which is represented by six patches - can look very imposing when printed out in a single SDL file.

To reduce the bulk of SDL files, you can use "#include" statements in the main SDL file and break the monolithic scene description into smaller, more managable pieces. Before rendering, you use the C Pre-Processor to replace the "#include" statements with the smaller auxilliary files.

This method has several benefits when working with large SDL files by hand:

• allows you to isolate and seperately maintain different types of scene description (for example, CV lists in one file, lights in another file, shaders in another file)
• makes it easier to edit files (smaller files load and display faster in an editor)
• allows you to replace redundant geometry (for example, two identical objects in a scene) with #include statements referencing the same file, while the different transformations for the objects remain in the main SDL file

Setting Up Include Files

Before beginning to create include files, consider creating a directory called include in the sdl directory. Putting SDL include files there reduces clutter and confusion.

To move parts of a master SDL file into smaller include files:

1. Copy the SDL text you want to include into a new file.

   Candidates for replacement are long CV lists, lights, shaders, repetitive or complex geometry and transformations, and animation definitions.

2. Give a meaningful name to the new file containing the text to be included.

   By convention, include files end with ".h", but you can give them any name you want.

3. In the master SDL file, replace the text you just copied with a line beginning with #include, followed by a space and the quoted path to the file to be included. For example: #include "/h/frank/includes/geom.h"
4. Repeat for each section of SDL text you want to move into an include file.

Recreating the SDL File for Rendering

Before you can render SDL files with #include statements, you must expand them by replacing the #include statements in the master SDL file with the text contained in the corresponding include files. To do this, you will run the master SDL file through the C Pre-Processor, cpp.

The Alias interactive software and the renderit script both run cpp on SDL files automatically.

To manually expand an SDL file for rendering:

1. At a shell prompt, type

   /lib/cpp -C -P sdl/masterSDLfile temp

   Where masterSDLfile is the name of the SDL file with the include statements. This runs the master SDL file through cpp and creates a new file called temp, which is the result of replacing the "#include" statements.

2. At the prompt, type

   renderer temp

   This runs the renderer on the recreated file.