Ayam Win32 Setup

This document describes how to set up Ayam on the Win32 platform.

In addition, there are frequently asked questions that may be of some help, if something does not work as advertised.

0. Installation, Starting the Application

The executable of Ayam ("ayam.exe") is located in the directory named "bin".
You do not need to install Ayam in the system, you can start it directly with a double click from where you unpacked the archive. If you get error messages about input or output file handles when trying to render directly from Ayam, please use the accompanying batch file "ayam.bat" to start Ayam instead of directly using "ayam.exe".

To start Ayam more easily, you can add an icon to your desktop by double clicking on the "make_shortcut.vbs" script.
Since Ayam 1.8 there are also two more scripts named "make_ftassoc.vbs" and "remove_ftassoc.vbs" that add and remove a file type association with Ayam scene files (extension .ay) to/from your desktop. After running the "make_ftassoc.vbs" script, you should be able to start Ayam by double clicking on Ayam scene files. On newer versions of Windows, where users do not have write access to the HKCR tree of the registry, use "make_ftassoc_w7.vbs" and "remove_ftassoc_w7.vbs" respectively.

1. Saving Preferences

All preference settings (Menu: "Edit/Preferences") are automatically saved when you leave Ayam.

The preferences are saved to the file:
"$(HOME)/ayamrc" if the environment variable "HOME" exists
"$(TEMP)/ayamrc" else.

The following steps need to be done if you (for some reason) do not like it that way, or the preferences end up in silly places (e.g. Win95 is setting your $(HOME) to "C:/", so that the preferences are saved to "C:/ayamrc"...).
However, if everything is fine with you, just skip to Step 2 now.

You can change the path and filename of the preference settings using the environment variable "AYAMRC".
How do you set an environment variable?

An easy way to do this is to edit the batch file "ayam.bat", and use it to start Ayam (this route does not work on Windows-NT4!):

quit Ayam
edit the file "ayam.bat"
remove the leading "rem" from the line "rem SET AYAMRC=D:/Ayam/ayamrc"
you should change the path "D:/Ayam/ayamrc" to a more appropriate setting; notice that the drive and the path you use already have to exist, and that you should have write permissions to the path that you choose
save the file "ayam.bat"
use the batch file "ayam.bat" to start Ayam
remember to always use the file "ayam.bat" to start Ayam in the future

Alternatively:

quit Ayam
WinXP: open "Start/Control Panel/System/Advanced/Environment Variables"
Add a new variable named "AYAMRC" and set it e.g. to "D:/ayam/ayamrc"; notice that the drive and the path you use already have to exist, and that you should have write permissions to the path that you choose
WinNT/2000: open "Start/Settings/Control Panel/System/Environment"
Add a new variable named "AYAMRC" (On Win2000 you need to be administrator to be able to do this.) and set it e.g. to "D:/ayam/ayamrc"; notice that the drive and the path you use already have to exist, and that you should have write permissions to the path that you choose
Win95/98/98SE: From the start menu, choose "Run" and enter "sysedit", then click "Ok". Select the window that is displaying "AUTOEXEC.BAT". Add the line
SET AYAMRC=D:/ayam/ayamrc
to it. Notice that the drive and the path you use already have to exist, and that you should have write permissions to the path that you choose.
WinME: Open "Start/Programs/Accessories/System Tools/System Information". This brings up a window titled "Microsoft Help and Support". From here, choose the "Tools" menu, then select the "System-Configuration" utility. Click the "Environment" tab. Add a new variable named "AYAMRC" and set it e.g. to "D:/ayam/ayamrc"; notice that the drive and the path you use already have to exist, and that you should have write permissions to the path that you choose.
restart Windows
start Ayam again

Remember: NEVER use backslashes (\) in any path or filename you enter to Ayam.

2. Setting up the Renderer

Download and install a preferred RenderMan compatible renderer. Open the Ayam main menu "Special/Select Renderer" then choose the renderer you want to work with. Do not use the "ScanShaders" option as the shaders are not set up properly yet.

3. Setting 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 already come with your RenderMan compatible renderer but you may also create your own.
After the installation of the preferred RenderMan compliant renderer you need to point Ayam to the directories where the compiled shaders of this renderer are stored in order to use them with the material objects in Ayam.
This is done using the preference setting "Main/Shaders". Just open the preferences using the main menu entry "Edit/Preferences" and enter the appropriate paths (separated by semicolons ";") into the string entry labeled "Shaders".
An example string could look like this:
C:/Program Files/Aqsis/shaders/;D:/Ayam/scn/shaders/
Now press the "Scan Shaders" button below and watch the console for error messages.

If Ayam fails to scan the shaders, probably a shader parsing plugin must be loaded first.

In the directory "ayam/bin/plugins" there are the following shader parsing plugins: ayslc.dll for BMRT2.6, aysdr.dll for Pixie, ayslb.dll for Air, ayslo3d.dll for 3Delight, ayslo.dll for PRMan, and ayso.dll for RenderDotC.

The plugins may be loaded manually (using the main menu entry: "File/Load Custom") or automatically (using a script). In order to load a plugin automatically on each start of Ayam, just add the name of the corresponding Tcl script (e.g. loadaysdr.tcl) to the "Scripts" preference setting and restart Ayam. An example setting setting could look like this:
loadayslc.tcl
Note that some plugins require additional DLL files to be present in the DLL search path. Depending on the flavour of your Win32 you may need to adapt the PATH environment variable to include the directories with those DLL files. You can also just copy them to the directory where the plugin is located. If a plugin does not find the corresponding DLL files it needs, you will get "invalid argument" Tcl error messages upon loading, or the plugin will fail to scan shaders later on.

Furthermore, all plugins have been compiled and tested against a specific version of the corresponding renderer (as outlined below); parsing shaders of other versions of those renderers possibly will not work.

Plugin-DLL: Renderer Compiled Version / Tested Version, DLL dependency

ayslx.dll: Aqsis 1.0.1 / 1.4.2, does not depend on other DLL files

aysdr.dll: Pixie 2.0.1 / 2.6, depends on "sdr.dll"

ayslb.dll: Air 2.6, does not depend on other DLL files

ayslc.dll: BMRT 2.6 / 2.6, does not depend on other DLL files

ayslo3d.dll: 3Delight 8.5 / 8.5, depends on "3delight.dll"

ayso.dll: RenderDotC 3.4 / 3.4, depends on "soargs.dll"
Since RenderDotC compiles all shaders as shared native code (into DLL files), all paths of the "Shaders" preference setting should also be present in the DLL search path.

ayslo.dll: Photorealistic RenderMan 11.5, does not depend on other DLL files

aygso.dll: Gelato 2.2 / 2.2, depends on "libgelato.dll"

This version information may be outdated; current information can be obtained from the download page of the Ayam project, or the respective "File Release Notes" document on the SourceForge download page of the Ayam project.

Finally, mind that you can only load one shader parsing plugin at a time into Ayam.

Remember: NEVER use backslashes (\) in any path or filename you enter to Ayam.

4. Creating and Saving a Working Environment (View Windows)

The working environment is simply an almost empty Ayam scene file, that contains the specification of some view windows (and the pane configuration). This file 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, Perspective). To create your own working environment, follow the steps below:

Start Ayam.
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 then probably something with your OpenGL setup is seriously broken. Fix this, then return here.
Save the environment using the menu entry "Special/Save Environment". This will save the environment to the file given in the preference setting "Main/EnvFile". The default setting is "~/2view.ay". The tilde "~" always expands to the home directory of the current user. If you have a single or no user on your system you might want to put an absolute path into the preference setting "Main/EnvFile" first (e.g. set it to "D:/ayam/2view.ay"). Notice that the drive and the path you use already have to exist, and that you should have write permissions.
You can immediately try to load the new environment using the main menu entry "File/New".

Remember: NEVER use backslashes (\) in any path or filename you enter to Ayam.

We are set. Quit Ayam and start it again, check the console for errors; then download "Tutorial #1" from http://www.ayam3d.org/ and read it.

For further information, see also the documentation of Ayam and the list of frequently asked questions (FAQ).

Randolf Schultz, 14. May 2011
http://www.ayam3d.org/ Reconstruct the World!