Contents

• Program Startup
• Saving a Shader
• Saving a Compiled Shader
• Render a Shader
• Exporting All Shader Files

Program Startup

The following describes how the main program starts up. This may be useful if you are trying to figure out the startup file load order, etc.

1. User runs 'ShadeTree'. The ShadeTree program handles command line arguments:

   -f <strfile>

   load a '.str' file. ShadeTree also supports opening files through drag and drop.

2. Setup environment.
   1. Checks for $STREE_DIR. If it isn't set, it sets it to 'C:\ShadeTree'.
   2. Checks for $STREE_LIB. If it isn't set, it sets it to '$STREE_DIR\mray'.

3. Creates the Render Options Editor.
4. Load 'stree.def' files.
   1. First load the main definitions file in $STREE_LIB\stree.def
   2. Checks for '$HOMEDRIVE\$HOMEPATH\stree.def', and load if it exists
   3. Checks for '.\stree.def', and load if it exists

5. Setup Work Directory.
   1. Checks for $STREE_TMPDIR. If it isn't set, it sets it to 'C:\Temp'.
   2. If $STREE_TMPDIR doesn't exist, creates it.
   3. Set STREE_WORKDIR to '$STREE_TMPDIR\stree.$PID' where $PID is the process id.
   4. Creates $STREE_WORKDIR.

6. Creates the Export Options Editor.
7. Create File Browsers.
8. Build Operation Menus from all files in $STREE_LIB\menu and additional menu directories specified by the 'menudir' command in the 'stree.def' files.
   NOTE: Directories beginning with "_" are ignored.
9. Load any str files specified on command line via -f <strfile> or by drag and drop.
10. Enter the main event loop. This is a 'forever' loop, until the user exits the application.
11. When it exits, ShadeTree removes the $STREE_WORKDIR directory tree.

Back to top

Saving a Shader

1. Walk the boxes in reverse order, generate source code
   1. Define internal macro variables
      _SHADERNAME_ - the filename of the shader, sans extension
   2. If savehelp is enabled, help messages are included in source code

2. Save Render Options to a file.
   > Save all settings to the file specified by $STREE_RENOPTS
3. Save the source to output filename
   > If 'sourcecodeprefilter' is set to '-', just save the file. Otherwise, assume setting to be a prefilter script to pipe the source code through, to do necessary modifications, such as line breaks, 'sed' style replacement of _KEYWORDS_, etc. An example invocation might be:

   $STREE_LIB\bin\codefilter lava

   Description of what script should expect:

   STDIN

   - raw source code from the code generator

   STDOUT

   - the modified source code

   STDERR

   - tty

   CWD

   - undefined

   ENVIRONMENT

   - The STREE_* environment variables may be used to affect operation of the code, including accessing the Render Options file, etc.

   ARGUMENTS

   $1 - shader name, eg. 'lava'

   EXIT REQUIREMENTS

   EXIT CODE

   - Should be 0, unless an error occurred, in which case an error should be displayed on stderr.

4. Save the GUI information for all shader arguments
   > Depending on the value of 'guiprefilter' in stree.def:

   If 'guiprefilter' in stree.def is NOT set to '-', then invoke the script specified. An example invocation:

   $STREE_LIB\bin\guiprefilter c:\usr\you\lava

   Description of what script should expect:

   STDIN

   - ascii formatted gui information for each unconnected input button flagged in the Argument Editor.

   STDOUT

   - tty

   STDERR

   - tty

   CWD

   - undefined

   ARGUMENTS

   $1 - full path to output file, WITHOUT filename extension. It is up to the script to determine the extension. An actual $1 example might be:

   c:\usr\you\lava

   EXIT REQUIREMENTS

   OUTPUT FILE

   - It is up to the script to save an output file based on $1.$STREE_GUIEXT. Use $STREE_GUIEXT to determine type of output expected, eg:

   .sli - a renderman '.sli' file
   .mat - a SoftImage material description file (etc)

   EXIT CODE

   - Should be 0, unless an error occurred, in which case an error should be displayed on stderr.

Back to top

Saving a Compiled Shader

1. Save the shader to a temp file
2. Save GUI information to a temp file
3. Invoke the compile command in the FOREGROUND. Example invocation:

   $STREE_LIB\bin\compileshader lava c:\usr\you\lava.slo

   Description of what script should expect:

   STDIN

   - tty

   STDOUT

   - tty

   STDERR

   - tty

   CWD

   - ?

   ARGUMENTS

   $1

   - Name of shader, without extension. Use this to determine where the actual source code to be compiled is, eg: $STREE_WORKDIR\$1

   $2

   - Full path to destination file, eg: c:\usr\you\lava.slo

   EXIT REQUIREMENTS

   OUTPUT FILE

   - $2 should be the created compiled shader.

   EXIT CODE

   - Should be 0, unless an error occurred, in which case an error should be displayed on stderr.

Back to top

Render a Shader

1. Save the shader to a temp file
   1. Create filename $STREE_WORKDIR\<shadername>
      $STREE_WORKDIR is set by the 'st' script the user invokes, and is usually set to something like
      c:\usr\tmp\stree.<pid>
   2. See above Saving a Shader', all steps.
   3. Fork/execute render script $STREE_LIB\bin\renderit in background. Runs in background to avoid 'hanging' the interface. Example invocation:

      c:\shadetree\mray\bin\renderit lava 12

      Description of what script should expect:

      STDIN

      - tty

      STDOUT

      - tty

      STDERR

      - tty

      CWD

      - A tmp directory for this particular execution of the main program, which is removed when the user exits ShadeTree. It is recommended the render script creates a temporary subdir ($STREE_WORKDIR\foo.<pid> and copy needed files in there, and remove the irectory when done (or when killed via SIGTERM)

      The following files will be available:

      • > $STREE_RENOPTS - the saved ROE state file
      • > .\$1 - The saved source code file (name is in $1)
      • > .\$1.$STREE_GUIEXT - a gui file (lava.sli, etc)

      ARGUMENTS

      $1

      - Name of shader. Can be used to determine the window name, if rendering to a window. This is also the name of the source code file sitting in the current directory. It is also the basename for the GUI file, if any.

      $2

      - A version number, used for render history. Can be used in window name if rendering to a window, to help identify history information. This number is different on each render.

      EXIT REQUIREMENTS

      OUTPUT FILE

      - A rendered image. Either to the screen, or to a file, or a series of files. Use environment variables to determine what to do.

      EXIT CODE

      - Should be 0, unless an error occurred, in which case an error should be displayed.

      TRAP SIGTERM

      - If script sees a SIGTERM, the script should remove any temp files or directories it creates.

   4. Save process ID of running process, incase user hits 'Stop Render'
      > If Stop Render is hit, use killpg(pid, SIGTERM)
   5. Advance the render counter (so that someday, we can have a render history)

   Note: Hitting 'Defaults' in the ROE reloads the $STREE_LIB\lib\render_options file.

   Back to top

   ---

   Exporting All Shader Files

   You can use 'File->Export All' (or the F7 hot key) to have ShadeTree save out the shader source code, the compiled shader, etc. all to pre-specified directories. You can even have it run a custom script after all the files are saved out.

   The 'File->Export Options' menu lets you set the pathnames for all the different exportable files, and using the toggle buttons, you can enable or disable which files are saved.

   'Export All' is useful in the development cycle of a shader, where you tweak it, then want to compile and save it, then invoke your own production render script to see the results, then go back and make tweaks.

   Using this browser, you can hit one key to save out everything, and invoke your own production render. Neat, huh?

   Using your $HOMEDRIVE\$HOMEPATH\stree.def file, or .\stree.def file, you can have ShadeTree come up with your own defaults for these menus. See streedefs.html section on 'exportoptions' command for syntax.

   Back to top

   ---

   If you encounter errors in this document, please email [email protected] with the URL, and enclose an example of the erroneous text, and what you feel to be the corrections, if possible.

   Copyright (c) 1996-1998 Cinema Graphics Inc. All Rights reserved.