3.2 Using the Shader Compiler - shaderdl

3Delight shaders are written in RenderMan Shading Language (SL). 3Delight also supports most of the common extensions to this language. The shader compiler produces either an object-code shader (a DSO on IRIX and Linux, a DLL on Windows) or a byte-code shader (commonly called interpreted shader). By default, the compiler produces byte-code shaders. If you have a C++ compiler installed on your computer, you can ask shaderdl to produce object-code shaders by setting the `--dso' command line switch.

The main advantage of byte-code (interpreted) shaders is their platform independentness: they can be used on IRIX, MacOSX, Linux or Windows computers. This is not the case with object-code shaders. Object-code shaders, however, can be faster than byte-code shaders. We suggest you produce object-code for those shaders that are computationally intensive, such as volume shaders.

To compile a shader, use the command:

% shaderdl shader.sl

As you may have noticed, you do not have to specify an output file name to shaderdl. The output file name is the name of the shader (the identifier following the keyword surface, displacement, light, or volume in the SL program) followed by the suffix `.sdl'.

Some renderers' shader compilers append the name of the platform at the end of object-code shader's name. 3Delight's shader compiler does not use this convention. An object-code shader always has the same name, regardless of the platform for which it is compiled. We recommend that you keep shaders compiled for different platforms in separate directories (this of course is not necessary for interpreted shaders).

Command Line Options

As with every compiler, shaderdl understands a set of command-line options that control the compilation process. These are specified before the input file name:

% shaderdl [options] [shader files or directories]

There is no need to specify an output file name to shaderdl since it is automatically set to the name of the shader (5) followed by the suffix `.sdl'.

The SHADERDL_OPTIONS environment variable is read for any option before reading those on the command line. The `-v' and `-h' options do not work if set in the variable.

Valid command line options are:

` -o <directory>'

Specifies the output file (and possibly the destination directory) for compiled shaders. If the specified file doesn't have the `.sdl' extension, it is not recognized by the renderer.

` -d <directory>'

Specifies the destination directory for compiled shaders. The default is the current working directory.

` --dso'

Generates object-code shaders. To use this option, you must have a C++ compiler installed. The compilation script included with 3Delight is configured to work with CC on IRIX, with g++ on Linux and with Visual C++ on Windows. If you have a different compiler installed, you have to set an environment variable or use the `--compiler' option. For more information, use the `--help-compiler' option.

` --compiler <compiler>'

This enables you to override the default C++ compiler used by `--dso' . Use the `--compiler-help' to see the different compilers available or how to build your own custom C++ compiler command.

` --help-compiler'

Explains how to pick a C++ compiler using the `--compiler' or by setting the SHADERDL_CC_COMMAND environment variable.

` --int'

Generates byte-code shaders (default).

` --embed-source'

Adds source code into the `.sdl'. This enables automatic recompilation when backward compatibility is broken. See `--recompile-sdl' for a more complete solution.

` --recompile-sdl'

When backward compatibility is broken, providing the `.sdl' was compiled with the `--embed-source' option, it is recompiled each time a render requires it, therefore slowing down the rendering process. This option makes the shader accept `.sdl' files, recompiles them (provided it contains its own source code) and replaces them. If a path is specified instead, all `.sdl' in it are affected. Only byte-code shaders may be updated with this option.

` -O<n>'

Specifies the optimization level, from 0 to 3. Refer to Optimization Levels.

` -w<n>'

Sepcifies warning level:

1. Disables all warnings (not recommended).
2. Logs important warnings only (default).
3. Logs all warnings.

` -I<directory>'

Specifies a directory to search for #include'd files.

` -D<symbol>'

Defines a preprocessor symbol.

` -E'

Stops after the preprocessing step.

` -c'

Stops after the shading language to C++ translation pass.

` --keep-cpp-file'

` --dont-keep-cpp-file'

Specifies whether or not to keep the intermediate files generated by the preprocessor. They are not kept by default.

` --keep-c++-file'

` --dont-keep-c++-file'

Specifies whether or not to keep the C++ files generated by the shading language translation pass. They are kept by default.

` --no-array-check'

Turns off array run time bound checking. Enabled by default.

` --use-shadeops'

` --dont-use-shadeops'

Enables [disables] use of shadeops. Disabled by default.

` -v'

` --version'

Prints the compiler version number and exits.

` -h'

` --help'

Prints a help message and exits.

Optimization Levels

shaderdl is an optimizing compiler: it implements most of the modern optimization techniques and also adds some special SIMD optimizations. Here is the list of optimizations enabled by each `-O' level.

` -00'

There are no optimizations.

` -O1'

Enables some basic optimizations that fight against the tendency of SIMD compilers to generate a lot of temporaries and loops:

• - Enables SIMD mechanisms.
• - Minimizes number of generated temporary variables.
• - Reuses temporary variables and SIMD booleans.
• - Regroups SIMD loops.

` -O2'

Sets some aggressive optimization, this is the recommended level and also the default. It includes:

• - Dead code elimination
• - Copy Propagation
• - Constant Folding
• - Arithmetic operations are reused if possible.
• - Removes code from loops or moves them outside, when possible.
• - Generates extra code to force some non-SIMD calls to become SIMD.
• - Converts varying variables to uniform variables when possible.

` -O3'

This level enables even more aggressive optimizations. We tend to put newly introduced optimizations in `-O3' and move them to `-O2' after they have been thoroughly tested. Experimental optimizations, which do not produce faster code in all cases, are also put here.

• - Disables array bounds checking.
• - Removes empty and useless loops, even if they are infinite.
• - Widens the scope of different optimizations. This makes them more thorough at a cost of extra compilation time.

3Delight 8.5. Copyright 2000-2009 The 3Delight Team. All Rights Reserved.