5.0.0 - INSTALLATION PROBLEMS
1.0.0 - BEGINNER GOTCHYAS
1.0.1 Where do I start? Are there some examples?
A good place to start is loading some examples, and rendering
some images.
1) Enter the software, hit File->Open, and bring up:
/usr/local/shadetree/prman/examples/chromy.stree # RenderMan
/usr/local/shadetree/mray/examples/chromy.stree # Mental Ray
2) When you hit Render, you should see a window come up
with a chrome ball, and a reflection in it.
Your sysadmin may have installed the software somewhere other
than /usr/local. If so, look at your $STREE_DIR variable, and
use that instead of /usr/local/shadetree in the above example.
1.0.2 How do I save (the desk, the .sl file, the image)?
SAVING THE DESK
---------------
File->Save or File->Save As from the main menu bar will save '.stree'
files that are ascii files that save the interface layout.
SAVING SHADER SOURCE
--------------------
File->Export->Shader Source File from the main menu bar will save
shader source files (prman: .sl files, mray: .C files).
SAVING COMPILED SHADERS
-----------------------
To save compiled shader files (prman: .slo files, mray: .so files),
use File->Export->Compiled Shader File from the main menu bar..
1.0.3 How do I load (the desk, an .sl file, an image)?
LOADING '.stree' FILES
----------------------
File->Open from the main menu bar will load your interface layouts.
LOADING SHADER SOURCE
---------------------
You don't load shader source. The only way ShadeTree can use shader
source code is when you create your own boxes; you put the source code
in the box definition. To make your own boxes, please refer to the
section CUSTOM BOXES in 'man shadetree-boxes'.
1.0.4 Is there documentation for the example shaders that come with ShadeTree?
Yes. In the main menu bar, choose Help->Shader Help. This opens
a window that contains help documentation for the shader you currently
have loaded. The help docs follow a 'man page' format.
Most of the example shaders have help documentation. At some point
they all will, time permitting.
1.0.5 Can I make my own help for shaders I create?
Yes. Just change the text in the Help -> Shader Help window, and
the next time you File -> Save your shader, the help you entered
will be saved with it.
Try to follow the format shown in the template (when you hit File -> New)
or follow the format of the docs that come with the examples.
1.0.6 The hotkeys don't work?
Make sure you don't have the caps lock key on.
2.0.0 - NORMAL USE GOTCHYAS
2.0.1 I get an error in the text window when I hit render. What do I do?
Check for problems:
> Are there any 'dotted connecting lines'?
> Are you forgetting an output variable?
> Do you have any boxes whose outputs don't go anywhere?
Dotted lines indicate you are probably connecting buttons together
that are not 'casted' correctly (connecting a color to a point,
for instance). If you have a dotted line, right mouse on the
button at either end of the dotted connection, and enter the
'Casts' sub menu, to see if you can change the cast to
something that matches the other end of the connection.
If the error message in the text window is telling you what
line number the error is in, then you can hit 'View Shader'
in the RENDER menu (or hit the F3 key) and go to that line
in the file; a few lines up there will be a comment that indicates
which 'box' is generating the error, which may help you track the
problem down.
2.0.2 Won't render examples (can't find renderer, permission denied)
These are problems your sysadmin may have to help you with.
Please see the section under SYSADMIN/SETUP GOTCHYAS for advice.
2.0.3 The image is not what I expected.. what do I do?
Pending description.
2.0.4 I'm displacing an object, and it renders with strange cracks and holes..?
In RenderMan, this is almost always due to Displacement Bounds being
'off'. It usually shows as strange 'clipping' artifacts: sharp edged
holes in the object.
It is best to keep Displacement Bounds 'off' unless you find you need
it, as the function can drastically impact render time. To enable the
function, open the Render Options Editor, and set the 'Displace Bounds'
to a value appropriate for your displacement.
For details, see the 'Displace Bounds' help button in the
'Render->Render Options Editor' from the main menu.
2.0.5 How can I render my scene, not just spheres and cylinders?
1) Custom Render Scripts.
In the Render Options Editor (in the Render menu), hit 'CUSTOM'
to invoke your own custom render script.
Please refer to the section CUSTOM RENDER SCRIPTS' in
'man shadetree-custom' for in depth information.
There are several examples of custom render scripts in:
/usr/local/shadetree/prman/bin/custom*
2) Your animation software.
Using your own animation software is the best way to render
your scene, or tweak animation curves, or manipulate your database
so you can zoom in on particular objects to check the shader.
Just enable 'Auto-Save Compiled Shader' in ShadeTree's options
menu; whenever you hit 'RENDER', ShadeTree will automatically
save out the compiled shader so your animation software can
pick it up the next time you re-render your scene.
2.0.6 I hit render, the machine slows down to a crawl.. what's up?
The machine is probably swapping, because you're using too much
ram for your render. Your scene is either too detailed, or you
are zoomed WAY in on an object, causing it to dice into many many
micro polygons.
Any of the following may help your situation:
1) Zooming out - the smaller objects are, the less
micro polygons are generated for the scene.
2) Decrease your Shading Rate and/or Sample Rate
4) Render a smaller image
Swapping is what usually makes the machine seem to crawl. Any of
the above will probably decrease the amount of memory your renders
use.
2.0.7 The sliders (along the left) take a long time to appear/disappear?
Yes, well, there's nothing to make that go any quicker.
However, you can make use of the FREEZE button (above the slider
area). When FREEZE is enabled, you can select boxes without having
sliders appear and disappear.
2.0.8 When boxes get close together, the inter-connection lines do weird stuff.
Yes, those routing lines are odd.. It's a matter of layout technique
to understand what they're doing, and to see how they are working for you.
Boxes have a region next to their buttons where it needs space to
create routes. Even if no lines exist their (yet), it reserves the
space for them, so that when the lines are added, there is space
for them to connect. It sort of forces the user to plan ahead of
time, rather than have all the lines reroute, and do weirder stuff.
These examples graphically show these avoid regions; the more buttons
on the box, the larger the region. These are areas where you don't
want other boxes to be in, so that there's room for the lines to route
up and down:
________________
________________ |________________|
|________________| :::::| | | |
:::::| | | | :::::|___| | |
:::::|___| | | :::::::::| | | |
:::::::::| | | | :::::::::|___| | |
:::::::::|___| | | :::::::::::::| | | |
:::::::::| | | | :::::::::::::|___| | |
:::::::::|___| | | :::::::::::::::::| | | |
:::::| | | | :::::::::::::::::|___| | |
:::::|___|________|___| :::::::::::::::::| | | |
:::::::::::::::::|___| | |
:::::::::::::| | | |
:::::::::::::|___| | |
:::::::::| | | |
:::::::::|___| | |
:::::| | | |
:::::|___|________|___|
3.0.0 - ADVANCED USER GOTCHYAS
3.0.1 What happens when you hit the 'Render' button?
Basically, it runs a script called:
/usr/local/shadetree/{prman,mray}/bin/render
See the CUSTOM RENDER SCRIPTS section of 'man shadetree-custom'
for more info.
3.0.2 How do I render my own scenes?
You create a custom render script. Follow examples in:
/usr/local/shadetree/{prman,mray}/bin/custom-render
/usr/local/shadetree/{prman,mray}/bin/custom-render-animate
/usr/local/shadetree/{prman,mray}/bin/custom-render-simple
Also, see the CUSTOM RENDER SCRIPTS section of 'man shadetree-custom'
for more in depth info.
3.0.3 How do I render a frame range?
In the Render Options Editor, there are options at the very bottom
to let you set a frame range, below the prompt for the custom render
script.
These frame ranges are passed to all render scripts as environment
variables:
STREE_SFRM - start frame
STREE_EFRM - end frame
STREE_IFRM - frame increment
An example of a custom render script that uses these variables
is shown in:
/usr/local/shadetree/prman/bin/custom-render-animate
See the CUSTOM RENDER SCRIPTS section in 'man shadetree-custom'
for more information.
3.0.4 Where's the source for some of these STREE_<pattern> functions?
Cinema Graphics is releasing the pattern functions as a library
only; the source for patterns is not being made available.
However, if you really feel strongly about it, leave us a message,
and we may be able to accomodate you, under certain circumstances.
3.0.5 What libraries should I include when rendering over a network?
When rendering with ShadeTree shaders, you will need to point the
renderer at ShadeTree's internal libraries:
RenderMan: /usr/local/shadetree/prman/include
Mental Ray: /usr/local/shadetree/mray/lib.render
3.0.6 How do I set up ShadeTree to 'see' custom boxes I've created?
To see an example of creating custom boxes, please refer to
'man shadetree-boxes', the section 'CUSTOM BOXES'.
3.0.7 How do I setup ShadeTree to work with netrender?
Use a custom script to do whatever you need.
Refer to the section 'CUSTOM RENDER SCRIPTS' in 'man shadetree-custom'.
3.0.8 How do I setup ShadeTree to work with a render queue?
Use a custom script to do whatever you need.
Refer to the section 'CUSTOM RENDER SCRIPTS' in 'man shadetree-custom'.
4.0.0 - SYSADMIN/SETUP GOTCHYAS
4.0.1 I (do something) and the (software, window mgr, machine) crashes!?
You probably have an Impact, and are seeing problems with other Motif
oriented software too, such as netscape(1), zmail(1), showcase(1).
These are bugs in the SGI operating system and the window manager, and
can be fixed by installing patches. In particular, the patches recommended
below, the section on installing patches under SYSADMIN/SETUP GOTCHYAS
in this document.
For IRIX 5.3, investigate and install in particular:
Patch #1187 - X server roll up (EXCLUDING Impact graphics)
Patch #1268 - 5.3/5.3xfs combined kernel rollup patch
Patch #1223 - Impact video and Graphics bug fixes
This information is considered up to date as of 07/18/96.. please
check with SGI for details.
To see what patches you have installed on your machine, run the
following command:
versions | grep patch
4.0.2 The hot keys don't work?
You are probably overriding them in one of your X windows
environment files.
Have a local X windows guru or sys admin look into it..
It is usually a matter of grepping all the 'dot files' in
your home directory (such as .Xdefaults or .Xresources),
or grepping any site-imposed X windows settings.
4.0.3 I choose "Render->View Shader", a window opens, but nothing is in it?
In older versions of the software (0.10.5 or less), the following
in the user's .Xresources or .Xdefaults caused the problem:
xwsh*autoFork: on
Solution for 0.10.5 or less: Set this to "xwsh*autoFork: off"
4.0.4 My EDITOR variable is set, but (emacs, gemacs) doesn't load
ShadeTree uses a special variable that allows you to specify how to
invoke your editor in the foreground, without changing your EDITOR
variable.
This variable is called STREE_EDITORCMD, and is usually unset unless
you have particular needs. See the next question for serious hacking
to make your favorite editor work..
4.0.5 'Render->View Shader' doesn't invoke my text editor (jot, emacs)
You may have an unusual editor, and may need to customize the
scripts:
/usr/local/shadetree/prman/bin/edit_file
/usr/local/shadetree/prman/bin/edit_and_rm
ShadeTree invokes these scripts when invoking 'Render->View Shader' from
the main menu bar, and also from 'Edit' in the box pop up menus.
edit_file wants to invoke an editor in the background (in it's own window)
for the file specified on the command line.
edit_and_rm wants to do the same thing, but wants to remove the file
after the editor exits. This can be tricky if your editor falls into
the background uncontrollably. You want the editor to run in the
foreground, so the rm command occurs after it exits. But you want
the _script_ to run in the background.
4.0.6 Tearoff menus have no borders - how do I move or kill them?
Prisms users often have this problem, and it's usually because
the following setting is somewhere in their X environment:
4Dwm*transientDecoration: none
Check your ~/.Xdefaults or other X resource files for this entry.
You can just delete or comment this line out (with '!') to disable
it, so that the windows have borders. Since this is a Window Manager
resource, you need to restart the window manager.. Either:
> Log out of the window manager entirely and log back in.
- OR -
> To avoid losing your windows, go into your toolchest,
and choose:
System -> Restart Window Manager
This is _supposed_ to restart the window manager
without killing all your windows, but DON'T COUNT ON IT.
Save everything first, just in case.
4.0.7 Won't render examples (can't find renderer, permission denied)
shader - Command not found
--------------------------
If you see this error message in your text window, then your renderman
environment isn't setup correctly, and you will need to re-run ShadeTree.
'shader' is the name of the renderman compiler, and should be in your
path.
render - Command not found
--------------------------
Same as above. 'render' is the name of renderman's renderer.
CC - Command not found
----------------------
If you are using Mental Ray, this means you probably don't have
the IRIX C++ compiler installed on your machine. ShadeTree generates
C++ source code to create the mental ray shaders, and you need to have
a C++ compiler installed somewhere.
If you are using the gnu C++, or other C++ compiler, then you need
to hack the /usr/local/shadetree/mray/renderit.mray script to use
your local compiler.
nice: No such file or directory: ray.irix5
------------------------------------------
If you see this error message in your text window, then your Mental Ray
or Softimage environment isn't setup correctly, and you will need to
re-run ShadeTree. 'ray.irix5' is the name of the Mental Ray renderer.
4.0.8 'elmrpt' gives the error '/usr/adm/elm.log: No such file or directory'
elmrpt needs to have log filenames as arguments, since the
default path (/usr/adm/elm.log) is not correct. The correct
usage for ShadeTree would be:
cd /usr/local/shadetree/etc/elm
./elmrpt /var/adm/shadetree/elmd-shadetree.log
Example output would be:
Total Total Over Number Number Percent Total
Feature Requests InUse SoftLim Issued Denied Denied Time Used
-----------------------------------------------------------------------------
01 156 4 156 0 0% 33:02:09
For more information, see the manpage ('man elmrpt'), or see the
program's own help: 'elmrpt -h'
5.0.0 - INSTALLATION PROBLEMS
These are problems with just getting the software interface up and
running properly.
5.0.1 I downloaded the software from the web, but what's a .enc file?
The distribution on the website is encrypted with crypt(1).
To decrypt a file called 'shadetree.tar.gz.enc', you would execute:
crypt < shadetree.tar.gz.enc > shadetree.tar.gz
By nature, the crypt program prompts for a password 'Key'. This is
to protect the software from casual downloads. Please contact
Cinema Graphics for the correct decryption key.
See the manual page 'shadetree-install.1' for details on extracting
the distribution.
5.0.2 Can't start the software..license error, or warns of 'DEMO MODE'
> When you extracted the tar file, were you logged in as 'root'?
(some license manager files must be owned as root.)
> Did you extract the tar distribution with the 'p' flag? eg:
tar xvfp stree-dist.0.10.2.tar
> Is the 'elmd-shadetree' daemon running? Check by typing:
ps -elf | grep 'elmd-[s]hadetree'
> Check the daemon log for errors:
tail -f /var/adm/shadetree/elm-shadetree.log
> Does the directory /var/adm/shadetree contain *.lic files?
If not, you may not have properly keyed the software. See the
manpage 'man/cat1/shadetree-install.1' for keying instructions.
> Does your /etc/services file contain a correct entry for shadetree? eg:
stree_elmd 1743/udp # ShadeTree Elan License Manager
All machines running ShadeTree _should_ have this entry in the services
file, though the system will work without any entry at all.
Port 1743 is registered with IANA (Internet Assigned Numbers Authority)
for use as a UDP port for the ShadeTree license daemon, and is the
default that is used if the entry doesn't exist in the services file.
However, if your site is already using this port for something else,
you CAN change the ShadeTree port number to something else, but if you
do so, all machines MUST have the entry in the services file in order
for ShadeTree to work properly.
5.0.3 When starting the software, I get errors such as 'Can't find libnsl.so'?
When trying to run the software, you may get a "can't find shared library"
error, something like:
% st
2636:/usr/local/shadetree/lib/stree: rld: Fatal Error: cannot map soname
'libnsl.so' using any of the filenames[..]
This almost always means something needs to be installed from the IRIX
installation CD. These days, software depends on dynamically loaded
'shared' libraries to ensure operating system upgrades don't break
precompiled software. This means the libraries are loaded (usually
from /usr/lib) when the software gets invoked.
Sometimes, you can get away with copying files from the /usr/lib of
another machine that has the libraries ShadeTree needs, but it is
better if you install from the IRIX installation CD.
5.0.4 When starting the software, I get an error 'Cannot create
"/usr/tmp/stree.15032": No such file or directory'. What's this about?
It means /usr/tmp is not a valid path. Try 'cd /usr/tmp'. If that
doesn't work, someone has corrupted the /usr/tmp symbolic link, or
has removed the directory the link points to.
When ShadeTree is invoked, it creates a temporary work directory
called /usr/tmp/stree.#####, where ##### is the PID of the executable.
You can tell ShadeTree to use a directory other than /usr/tmp by
changing the STREE_TMP environment variable.
5.0.5 I can bring up the interface, but can't find the examples to test it?
The examples are normally in:
/usr/local/shadetree/prman/examples # RENDER MAN
/usr/local/shadetree/mray/examples # MENTAL RAY
Enter File -> Open from the main menu, and point the file browser
at that directory.
If the directory isn't there, the software was probably installed
somewhere other than /usr/local. To find it, try:
echo $STREE_DIR
to see where your sysadmin might have put the distribution, then look
for a directory called 'examples'.
5.0.6 I can load the examples, but it won't render an image?
Check your text window for errors.
It probably isn't able to invoke the renderer. ShadeTree assumes your
environment is already setup correctly to access the RenderMan
(or mental ray) renderer.
AUTHOR
Greg Ercolano
mailto:[email protected]
COPYRIGHT
(C) Copyright 1996 Cinema Graphics, Inc. All Rights Reserved.
SUPPORT
If you encounter errors in this document, email [email protected].
Please supply the name of the file or manpage, enclose clippings of
the erroneous text, and describe the error.