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.

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'.

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 (4) 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.

` --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. See also Predefined Macros.

` -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.

` --no-array-check'

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

` --use-shadeops'

` --dont-use-shadeops'

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

` --searchpath-debug'

Displays a trace of where shadeops are searched.

` --strict'

Enable strict RSL syntax and semantics (see Strict RSL Syntax).

` -v'

` --version'

Prints the compiler version number and exits.

` -h'

` --help'

Prints a help message and exits.

Predefined Macros

shaderdl always defines the following macros:

• DELIGHT
• A platform specific macro (LINUX, DARWIN or WIN32).
• DELIGHT_VERSION to a numeric value of the form 8501 (for version 8.5.1).

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.

Strict RSL Syntax

The `--strict' option to shaderdl disables some non-standard syntax and semantics. By default shaderdl is quite permissive in order to be compatible with other RSL shader compilers. By using this option the shader writer can write shaders that are more in-line with the good practices of RSL programming. Follows a list of features that are disabled by the `--strict' option.

• Error instead of a wrning for varying strings. Writing the following code would produce an error:

  varying string bad = "something";
  

• Error when accessing pre-defined variables without the extern keyword. The following surface will print an error in strict mode (only a warning by default):

  void test()
  {
      P = 0;
  }
  
  surface strict_test() { test(); }
  

  Note that for RSL 2.0 shaders there is no need to use the extern keyword since predefined variables are considered as class members.
• Error when extern declaration has detail mismatch. For example,

  void test()
  {
      extern uniform point P;
      P = 0;
  }
  
  surface strict_test() { test(); }
  

  Will print an error since P should be declared as varying point.
• Error when assigning to a non-output function parameter. For example,

  void test( float in ) { in = 0; }
  
  surface strict_test()
  {
      float tmp = 0;
      test( tmp );
  }
  

  Will produce and error because in parameter to the test function is not declared as output.
• Error on ambiguous function call. For example,

  void test() { }
  float test() { }
  
  surface strict_test() { test( ); }
  

  Will produce an error because it is not clear which function to call.

3Delight 10.0. Copyright 2000-2011 The 3Delight Team. All Rights Reserved.