SDL: The Alias Scene Description Language Introduction > Inserting comments in SDL

SDL: The Alias Scene Description Language

Introduction

SDL is the Scene Description Language. SDL programs, in the form of ASCII text files, specify all the information necessary to render a scene, including models, shaders, lights, and animation.

Because they are simple text files, SDL programs can be created "by hand". That is, it is possible to create a scene entirely using SDL commands. Usually, however, you will not need to directly edit SDL files. Instead, they will be generated by an interactive modeling program. In fact, most people will never need to read an SDL file, and will simply output SDL from the modeler directly to the renderer automatically.

There are some cases where you may want to use SDL:

for absolute, mathematical control over scene elements such as models, animation paths, and shaders
to modify a generated SDL file manually, or with another program
to create new procedural effects using the general programming features of SDL

Applying basic programming constructs to scene descriptions allows useful and spectacular effects that would be tedious or impossible to create with the interactive modeler alone. SDL can augment the dynamics and particle systems of the interactive modeler with the flexibility of a programming language.

Once you have an SDL file describing a scene, you will run it through a renderer to create an image of the scene.

Renderers

The renderers take an SDL file and create an image or images, as if it built the world described in the SDL file and then photographed it. AliasStudio supports two methods of converting the procedural information of the SDL file into an image: RayCasting and RayTracing.

RayCasting

The RayCaster follows a line (ray) for each pixel on the screen, from the camera eye into the scene. As the rays meet objects in the scene, the RayCaster calculates the light reflected off the object at that point. In effect the RayCaster work backwards from the real world, by tracing light hitting the eye back to the object that reflected it.

> How It Works

This illustration shows how the raycaster works:

Ray 1 doesn't hit any object, and so hits the background. The RayCaster assigns the background color (or picture) to the pixel where the rays passed through the screen.
Rays 2,3,4, and 6 hit opaque objects in the scene. The RayCaster calculates the color of the objects where the rays hit them. It then takes into account lights, shaders, and special effects (such as fog). Then it assigns that color to the pixel where the rays passed through the screen.
Ray 5 passes through a translucent sphere before hitting the tabletop. The RayCaster calculates the color of the tabletop at that point, just as for rays 2,3,4, and 6. Then it adds the amount of color the ray received from passing through the sphere. Finally it assigns that color to the pixel where the ray passed through the screen.

At each intersection between a ray and an object, the RayCaster combines the surface geometry, the lights in the scene, and the surface shading model to calculate the color for that spot. The shading model is a mathematical expression of the way the surface interacts with light. It is controlled by several parameters, such as surface color and shinyness, that can be constant over the surface (for solid colors), vary with U and V (for 2D textures), vary with XYZ (for solid textures), or vary with time (for animated colors and textures).

After calculating the color of the surface hit, the RayCaster takes into account atmospheric effects. That is, the medium through which the rays travel (for example, fog or water). These effects are controlled in the ENVIRONMENT section of SDL.

Once the RayCaster has completely processed a ray, taking into account surfaces and atmospheric effects, it has an RGB color value for the corresponding pixel on the screen. Depending on the options set when the RayCaster was run, it will use assign this color to the pixel, or calculate many rays per pixel and average their colors together for a "representative" color. This averaging is called anti-aliasing, and it helps to smooth out the blocky look of computer graphics. The amount of anti-aliasing is controlled in the DEFINITION section of SDL.

RayTracing

RayTracing is similar to RayCasting in many ways, but has one important difference - the ray of light doesn't necessarily stop when it hits an opaque object. It can bounce off to another object and another and another, retracing and reflecting everything it sees in the scene. The AliasStudio RayTracer follows as many bounces as you want.

RayTracing is more time-consuming than RayCasting, and for most scenes is not worth the extra time. However, it gives you the most realistic image possible. Because the ray is traced through multiple bounces, the RayTracer is able to produce effects the RayCaster cannot:

true reflections from reflective surfaces (to save rendering time, AliasStudio lets you choose which objects in a scene will have reflections)
true refraction through transparent surfaces
true shadows from multiple light sources
shadows cast through transparent objects

> How It Works

The RayTracer follows the path of rays from the camera eye into the scene. Rays originating at the camera are the primary rays. As the primary rays intersect objects, they may reflect or refract according to simplified optical physics, and produce secondary rays. The secondary rays are followed in the same manner, and so on.

Each time a ray intersects an object, the RayTracer traces shadow rays from that point toward each lights set to cast shadows. If the shadow ray meets another surface before reaching the light, the point is shaded from the light.

The following illustration shows what would happen to ray 5 of the RayCasting example above, if it were rendered with RayTracing.

The ray (a) travels from the eye to the sphere. Where it contacts the shiny translucent sphere, it splits into secondary rays (b) and (d). One secondary ray (b) refracts through the sphere a different angle (according to the material of the sphere). The other secondary ray (d) reflects off the sphere and hits the tabletop. The refracted ray (b) hits the other side of the sphere and refracts again (c), hitting the tabletop at a different place.

The RayTracer processes all this information and calculates a color for the pixel where the ray passed through the screen. To save rendering time, the RayTracer lets you limit the number of bounces or secondary rays it will generate from an intersection with a surface.

PowerCaster and PowerTracer

PowerCaster and PowerTracer are multiprocessor versions of the RayCaster and RayTracer.

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 manageable pieces. Before rendering, you use the C Pre-Processor to replace the "#include" statements with the smaller auxiliary files.

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

allows you to isolate and separately 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:

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.
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.
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"
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 AliasStudio interactive software and the renderit script both run cpp on SDL files automatically.

To manually expand an SDL file for rendering:

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.
At the prompt, type
renderer temp
This runs the renderer on the recreated file.

The Rendering Pipeline

In the pre-processing phase, the RayCaster:

Takes face, patch, and polygon statements from the SDL file.
Transforms the control vertices of each object according to the SDL hierarchy of transformations.
Converts the geometry into triangles.
The number of triangles depends on the tessellation control settings. The vertex of each triangle stores surface U and V parameters, tangent vectors, surface normal, and position in world space.
Applies the perspective viewing transformation, which includes the camera location, viewpoint, field of view, and twist.
This step converts the triangles from world space to perspective (screen) space.
The triangles are "scanned out" to the triangle buffer (each pixel inside the two-dimensional boundary of the screen space triangle is identified).

In the rendering phase, the RayCaster loops through each pixel of the new image and calculates:

The light reflected toward the camera by each surface.
U and V parameter values, tangent vectors, surface normal, and position for each intersection point with a triangle (calculated by interpolating from the information on the intersected triangle in the triangle buffer).
Color and transparency values for the intersected triangle(s) based on the geometry of the intersecting point, the lights in the scene, and the surface shading model.
Final color (RGB) and transparency (alpha) of the pixel based on the colors and transparencies of the intersected triangle(s).

The final step of combining all the intersected triangles into a final color is complex.

If the ray intersects more than one triangle, the list of intersections is sorted by distance from the camera and processed from back to front. The renderer builds the final color and transparency by combining the colors and transparencies of each triangle, along with the atmospheric effects between the triangles. See the Procedural Textures and Natural Phenomena section of the SDL Reference Manual for more information on how these colors are calculated and combined.

This illustration shows the complex process by which the renderer combines the colors of the intersected triangles. It does not show the additional complexities introduced by motion blur.

The following illustration shows an example of how both the surfaces and ray segments are used to calculate the color and transparency of a pixel.

To calculate the ray illustrated above, the renderer starts with the color and transparency of the background. Then it calculates the atmospheric effects of the rightmost ray segment (the segment between the farthest surface and the background) and adds them to the color and transparency of the background. Then it adds the color and transparency of the farthest surface, then the next closest, and so on. Note that if any of the surfaces are opaque (transparency 0), the color information of farther surfaces is lost, since the opaque surface completely obscures the surfaces behind it.

Command Line Options

Any options you give the renderer on the command line override internal variables in the SDL file. These options allow you to change the behavior of the renderer without having to edit the SDL file.

Usage

To use the command line options

Use the cd command to move to your project directory (for example, cd user_data/demo).
Enter the command for the renderer, followed by any options (see below), and the name of the SDL file (for example, renderer -s10 sdl/animation_1).

Options

renderer|raytracer [-H] [-an] [-bn] [-en] [-f script] [-gn][-hn] [-m filename] [-p filename] [-d filename] [-C color_map_filename] [-c quantized_output_file] [-j] [-k] [-Kn] [-on] [-O][-qn][-P][-sn] [-Sn] [-Bn] [-En] [-rn] [-tn] [-wn] [-Wn] [-xn] [-yn] [-Yn] [-zn] [-Zn] [filename]
-an	Use the integer n as the aalevel.
-tn	Use the integer n as the aathreshold.
-sn	Use the float n as the starting frame number.
-bn	Use the float n as the by frame number.
-en	Use the float n as the ending frame number.
-Sn	Use the integer n as the start extension.
-Bn	Use the integer n as the by extension.
-En	Use the integer n as the size extension.
-fstring	invoke the program string after each frame.
-gn	Use the float n as the gamma correction value.
-mstring	Produce a matte file and Use string as the filename.
-pstring	Use string as the pix filename.
-dstring	Use string as the depth file name.
-C string	Use the SGI imagelib image format file to quantize to after each frame.
-c string	Output the quantized image to the file string after each frame.
-j	Raytrace transparent objects without attenuation (Beere's law ignored).
-k	Keep depth maps in memory after reading (read them once). If used, a depth map file will be read ONCE, or if depth map saving is not turned on, the map will be created ONCE and used for all subsequent frames.
-Kn	Turn depth maps on disk usage to n. 0=off, non-zero =on. If used, a depth map file named the same as the light will be created if it doesn't exist, and used if it does exist.
-O	Use byframe of 1.0 as applied to motion-blur.
-on	Use byframe of n as applied to motion-blur.
-P	Preserve the non-glowed image.
-qn	Set the quiet flag to n (0 or 1).
-Tn	Use the integer n as the number of Y pixels in a tile.
-hn	Use the integer n as the image height.
-wn	Use the integer n as the image width.
-Wn	Use the integer n as the ylow for backgrounds.
-xn	Use the integer n as the xleft.
-yn	Use the integer n as the ylow.
-Yn	Use the integer n as the yhigh for backgrounds.
-rn	Use the float n as the aspect ratio. If more than one camera is defined in the SDL file, this option only affects the first camera.
-Gn	Turn saved geometry on (non-zero n) or off (0).
filename	Use filename as the SDL filename. If no filename is present standard input will be used.
-zn	Make camera depth output respect transparency, if transparency is greater or equal to n. This allows transparency mapped objects to affect the camera depth output files. If the flag is set to 1, anything that is at least 1% transparent will not show up in the depth file. If the flag is set to 50, anything that is more than 50% transparent will not show up in the depth file. If it is set to 99, only things that are totally transparent will not show up in the camera depth file.
-Zn	Set fast_shading to n (0 or 1).
-H	Print a usage message.

PowerCaster and PowerTracer Options

The multi-processor renderers have a few extra options for controlling how they use multiple CPUs.]

powertracer|powercaster [-H] [-an] [-bn] [-en] [-f script] [-gn][-hn] [-m filename] [-p filename] [-d filename] [-C color_map_filename] [-c quantized_output_file] [-qn] [-sn] [-Sn] [-Bn] [-En] [-rn] [-Wn] [-Yn] [-k] [-Kn] [-on] [-O] [-P][-tn] [-wn] [-xn] [-yn] [-nn] [-I] [-Tn] [-U] [-zn] [-Zn] [filename]
-nn	Use the integer n as the number of processors to PowerTrace on.
-I	Print out statistics at the end of the PowerTrace.
-Tn	Use the integer n as the number of Y pixels in a tile.
-U	Leave output pix file uncompressed (not Run Length Encoded).
All other options are identical to the single processor commands.

Examples

> Example 1

To render every other frame ("by frame" of 2) of frames 4 through 8 of an animation, but number the output files 10,11 and 12, enter:

renderer -s 4 -e 8 -b 2 -S 10 -B 1 sdl/animation_scene_1 

This produces the following pix files:

pix/animation_scene1.10 (which is frame 4) 
pix/animation_scene1.11 (which is frame 6) 
pix/animation_scene1.12 (which is frame 8) 

> Example 2

To test a few frames of an animation (say, frames 1 to 5) without overwriting existing pix files, enter:

renderer -e 5 -p pix/test_anim -m mask/test_anim sdl/
animation_scene_1 

This produces the following pix and mask files:

pix/test_anim.1 
pix/test_anim.2 
pix/test_anim.3 
pix/test_anim.4 
pix/test_anim.5 
mask/test_anim.1 
mask/test_anim.2 
mask/test_anim.3 
mask/test_anim.4 
mask/test_anim.5 

Inserting comments in SDL

To insert comments in an SDL file, enclose the line or lines with a "C style" slash-asterisk pair:

/* comment */ 

or

/* 
	comment 
	comment 
	comment 
*/ 

You cannot nest comments.

The numeric sign (#) followed by a blank space is not a comment.