[Setup.txt, 15. Jan 2006]

Setup instructions for Ayam (Unix only)
---------------------------------------

The executable of Ayam is located in the directory named "bin".
You can use Ayam directly from where you unpacked, or install it
into your system. If you want to install, just follow the instructions
in the file "bin/INSTALL" first.

Before you start modelling with Ayam, you should set it up
properly. The following things have to be done:

  1. Determine where to save the preferences
  2. Determine the type of the window manager
  3. Set up the shaders
  4. Set up the plugins
  5. Create and save a working environment


1. Determine where to save the preferences
------------------------------------------

By default, the preference settings are automatically saved to the file:
"~/.ayamrc" ("~/Library/Preferences/.ayamrc" on MacOSX/Aqua) when you
quit Ayam.

You can change location and name of the preference file using the
environment variable "AYAMRC".
How do you set an environment variable?

To set the AYAMRC environment variable, add to your profile:
 csh/tcsh: setenv AYAMRC /home/user/.myayamrc
 bash/ksh/zsh: export AYAMRC=/home/user/.myayamrc
replacing "/home/user/" with a more sensible setting.

You have to restart the shell and Ayam in order for these changes to
take effect.

You can switch off automatic saving of the preferences in the
preference settings (Pref: "Main/AutoSavePrefs").
If you switched off AutoSavePrefs, you can enforce saving of the
preferences using the main menu entry "File/Save Prefs".

On MacOSX/Aqua environment variables may be defined using
the file "~/.MacOSX/environment.plist".
See also:
http://developer.apple.com/qa/qa2001/qa1067.html


2. Determine the type of the window manager
-------------------------------------------

If you fail to correctly determine the type of your window
manager, Ayam will not be able to properly remember the geometry
of the main window and the toolbox. Furthermore, the main
window may jump, each time a new property is selected.
This is because, unfortunately, different X window managers
report different values for the geometries of top level windows,
some include the decoration, some other do not.

If the main window jumps, when you select the first property
of the "Root" object, your WM is "twm-compatible".
To check this, just start Ayam, click on "Root" in the tree view
then on "RiOptions" in the listbox to the right and watch
your main window.
If it jumps downward, you should set "TwmCompat" to "on" in the
preferences!

On MacOSX/Aqua the default setting ("on") does not need to be changed.


3. Set up the shaders
---------------------

What are shaders? For the moment, we can safely assume that
shaders are small files that carry material descriptions.
Some example shaders come with your RenderMan compatible renderer
(e.g. BMRT), but you may also create your own of course.
Unless you load a shader parsing plugin (see section 4 below),
Ayam can only work with shaders that have been compiled with "slc"
from BMRT, so you may want to get and install BMRT first.
Unfortunately, NVIDIA/Exluna stopped the official distribution of BMRT,
but it can be found using the obvious search terms with your favourite
search engine.
After the installation of BMRT you need to point Ayam to the directories
where your slc-compiled shaders reside in order to use them with the
material objects in Ayam.
This is done using the preference setting "Main/Shaders".
Just open the preferences (main menu: "Edit/Preferences") and enter the
appropriate paths (separated by ":") into the string entry labeled "Shaders".
If you installed BMRT before your first start of Ayam, the preference
setting "Main/Shaders" probably already contains the right path setting
(it will be fetched from the SHADERS environment variable, that has been set
while installing BMRT, if the Shaders preference setting is unconfigured).

Example:
If you installed BMRT2.6 into "/usr/local/BMRT2.6" you will want
to add "/usr/local/BMRT2.6/shaders/" to your "Shaders" preference
setting.

If you are ready, press the "Scan Shaders" button right below the "Shaders"
entry field and watch the console for error messages.

On MacOSX there is no BMRT; you have to download a different renderer like
e.g. Pixie, 3Delight or Aqsis (all available on MacOSX) and load a shader
parsing plugin, see below.


4. Set up the plugins
---------------------

The distribution of Ayam contains some plugins:
RRIB: RIB Import
ONIO: Rhino 3DM Import/Export
MFIO: 3DMF Import/Export
IDR: Importance Driven Rendering
MetaObj: the MetaBalls custom object
ayslx, ayslb, ayso, ayslo, ayslo3d, aysdr: shader parsing plugins

All plugins reside in the "ayam/bin/plugins" directory (on MacOSX/Aqua
they are located in the application bundle itself:
"Ayam.app/Contents/MacOS/plugins").

You may load the plugins
a) manually if you need them (using the main menu "File/Load Plugin") or
b) automatically on startup of Ayam.

If manual loading of a plugin fails, please consult the FAQ:
http://ayam.sourceforge.net/faq.html#q1.10
.

Add "<path>/load<pluginname>.tcl" to the preference setting
"Main/Scripts" if you want the plugin to load automatically on
startup. Use ":" to separate different entries.

Add the path to "metaobj.so" to the preference setting "Main/Plugins"
if you want the MetaBalls custom object to be automatically loaded
when a scene containing this type of object is being read.

Be sure to add the path to the respective shared object (file with
the file name extension ".so") _or_ "." to your LD_LIBRARY_PATH
environment variable, otherwise loading of the plugin will fail.

Note that on IRIX, you probably have to modify LD_LIBRARYN32_PATH
instead of LD_LIBRARY_PATH.

On MacOSX/Aqua you may have to modify the DYLD_LIBRARY_PATH instead
of the LD_LIBRARY_PATH variable.


5. Create and save a working environment
----------------------------------------

The working environment is simply an almost empty Ayam scene file.
This file just contains the specification of some view windows.
It is loaded automatically on every start of Ayam and presents you
with a standard working environment, consisting of e.g. a traditional
3-view layout (Front-, Side-, and Perspective-View).

How do you create such a file?

o Start Ayam.
o Open and arrange as many views as you like using the
  menu entry "Create/View".
  [If Ayam crashes or blocks during opening of a view
   something with your OpenGL setup is seriously broken.
   Fix this, then return here.]
o Save the environment using the main menu entry
  "Special/Save Environment". This will save the environment
  to the file given in the preference setting "Main/EnvFile".
  The default setting is "~/.ayam2view.ay"
  ("~/Library/Preferences/.ayam2view.ay" on MacOSX/Aqua).
  The next dialog will ask you, whether you want to make the new
  environment the default, answer with "Ok".
  Do not switch off the preference setting "Main/LoadEnv",
  as this would inhibit automatic loading of the working
  environment on startup.
  If the preference setting "Main/NewLoadsEnv" is enabled, the
  working environment will also be read if you clear the scene
  using the main menu entry "File/New".

Quit the application and start it again; then
download "Tutorial #1" and do it.

End of setup instructions.

-- 
http://www.ayam3d.org/    Reconstruct the World!
