FAQ

• 1 General usage:
  • 1.1 Where can I download BMRT?
  • 1.2 Where can I learn more about RenderMan, download shaders, or learn how to write shaders?
  • 1.3 How do I create a CSG model?
  • 1.4 How do I create a Sweep? My Sweep is always flat.
  • 1.5 How do I create a reflecting material? How do I change the reflectivity of a material?
  • 1.6 How do I create shadows?
  • 1.6.1 How do I map images onto objects?
  • 1.7 Ayam does not find my renderer (rgl/rendrib), how do I set this up?
  • 1.8 How do I actually get a rendered image file (a TIFF or JPEG) out of Ayam?
  • 1.9 How do I set up Ayam to scan my shaders?
  • 1.10 How do I load a plugin? I always get some Tcl error message.
  • 1.11 My shader parsing plugin does not work at all; are there known incompatibilities?
  • 1.12 How do I change the keyboard shortcut for the Alt-rotate view-action?
  • 1.13 Where is the PDF version of the Ayam documentation?
  • 1.14 Is feature X available on platform Y?
  • 1.15 After upgrading Ayam the new keyboard shortcuts do not work as documented?

• 2 Renderer specific questions:
  • 2.1 The rendering windows of Aqsis do not close.
  • 2.2 Viewport rendering with Aqsis fails.
  • 2.3 When switching virtual desktops BMRT rendering windows do not repaint.
  • 2.4 How do I enable raytracing with Pixie?
  • 2.5 How do I make viewport rendering work?
  • 2.6 How do I enable preview rendering from Ayam with Pixie on Windows?

• 3 Windows related questions:
  • 3.1 I cannot render anything, all I get is some Tcl error message?
  • 3.2 When loading scene files, I get an error message. Is this a bug in Ayam?
  • 3.3 I have set up the BMRT Shaders correctly, but Ayam still does not scan them?
  • 3.4 Where is the RRIB-Plugin?
  • 3.5 How do I compile Ayam on Windows; are there any project files?
  • 3.6 Where can I get a "cat.exe" for the RenderGUI feature?
  • 3.7 How can I use Ayam with a renderer without working shader parsing plugin?
  • 3.8 Ayam is not drawing the selection rectangle! What can I do about this?
  • 3.9 I cannot see any plugins (DLL files) when I try to load them via "Load Plugin".
  • 3.10 I cannot select font description files from "c:\winnt\fonts" for the Text object.
  • 3.11 Ayam 1.14 (and up) do not start on Windows XP.

• 4 Linux related questions:
  • 4.1 Rendering from Ayam leaves many zombie processes around, how do I get rid of them?
  • 4.2 I cannot see the control points of NURBS curves to edit them, even though the right modelling action ("Edit Points") is active.
  • 4.3 The "Edit Points" and "Tag (Select) Points" modelling actions do not work, I can click on points but nothing happens.
  • 4.4 Ayam looks strange on my desktop, with black, thick scrollbars and buttons. How can I change this?
  • 4.5 The AutoFocus feature does not work? What can I do?
  • 4.6 How can I set a good looking font in Ayam?
  • 4.7 The official Ayam executable does not start. How can I make it run?
  • 4.8 The repairAyam.tcl script fails to send itself to Ayam. How can I make it work?

• 5 IRIX related questions:
  • 5.1 What can I do about flashing menus and horizontal stripes?
  • 5.2 Ayam does not draw NURBS curves, and prints "color_flag = 0" to the console. What can I do about this?

• 6 Solaris related questions:
  • 6.1 Ayam can not open any view windows, but prints an error message about a failed Xmu colormap lookup. What can I do?

• 7 Mac OS X related questions:
  • 7.1 Ayam does not remember my preference settings.
  • 7.2 Box objects are drawn in wireframe.
  • 7.3 AutoFocus does not work in Aqua?
  • 7.4 Ayam can not start Safari to show the documentation?
  • 7.5 How do I disable the splash screen?

• 8 Project related questions:
  • 8.1 When will you implement feature X?
  • 8.2 I would like to contribute, how do I? Do you accept patches?
  • 8.3 I would like to contribute, but I am no developer?
  • 8.4 I think I found a bug. How do I submit a bug report?
  • 8.5 How do I check out the Ayam sources from Mercurial version control?
  • 8.6 Is there documentation on the Ayam scene file format? How can I parse this format?

• 9 Questions related to self compiled executables:
  • 9.1 How do I compile Ayam? I typed "make" but just got errors.
  • 9.2 My self compiled Ayam crashes when I try to open a view window.
  • 9.3 Can I use plugins from the official binary distribution with my self compiled executables?
  • 9.4 I get Tcl errors when I try to drag and drop objects in the object tree widget. Is this a bug in Ayam?
  • 9.5 How can I compile Ayam with Tcl/Tk 8.4.x?
  • 9.6 How do I compile a shader parsing plugin?

1 General usage:

• 1.1 Where can I download BMRT?
  ^‌I do not know. Really. Try your favourite search engine with the obvious search terms.

• 1.2 Where can I learn more about RenderMan, download shaders, or learn how to write shaders?
  ^‌Just browse to The RenderMan Repository on http://www.renderman.org/ which is maintained by Tal Lancaster and has much information on RenderMan, many shaders, and links.
  The original resource is now unfortunately offline, try your luck with the Internet Archive copy from 12. Dec 2011.
  You might also want to try some courses in The RenderMan Academy.
  The original resource is now unfortunately offline, try your luck with the Internet Archive copy from 19. Dec 2007.

• 1.3 How do I create a CSG model?
  ^‌Just create a Level object of appropriate type (Union, Difference, or Intersection) and place the objects that you want to combine with this CSG operation in this level.

• 1.4 How do I create a Sweep? My Sweep is always flat.
  ^‌Make sure, that the cross section curve (the first child of the Sweep object) is defined in the XZ-plane (a standard circular curve as created by the toolbox is in the XY-plane, and thus needs to be rotated by 90 degrees around the Y-axis). The documentation of the Sweep object also contains a mini tutorial on how to create a sweep.

• 1.5 How do I create a reflecting material? How do I change the reflectivity of a material?
  ^‌You simply need to use an appropriate surface shader, e.g. "shiny" from "BMRT2.6b". Those shaders usually have parameters to adapt the reflectivity. Note that since those shaders often use the optional shading language function "trace()", they may not work with every renderer (so called scanline renderers need to create reflections using reflection maps instead). Check the documentation of your renderer!

• 1.6 How do I create shadows?
  ^‌This depends on your renderer. They either create raytraced shadows (like e.g. BMRT) or use so called "shadow maps" (like e.g. Aqsis).
  For BMRT, it is sufficient to switch on the "Shadows" attribute of the light object (plus, since BMRT 2.6, the object onto which the shadow is cast must have atleast the "matte" surface shader assigned, which is guaranteed by Ayam unless you switched the default material to "none"). For other renderers, consult the respective documentation of the renderer!
  If your renderer creates shadows by "shadow maps", follow these instructions in the Ayam documentation.

• 1.6.1 How do I map images onto objects?
  ^‌You simply need to use an appropriate surface shader that uses the shading language function "texture()". Those shaders usually have a parameter for an image file, where you may specify a TIFF image file to be mapped onto the object. An example is "paintedplastic" from "BMRT2.6b".

• 1.7 Ayam does not find my renderer (rgl/rendrib), how do I set this up?
  ^‌You need to make sure, that your renderer (rgl/rendrib) is in your executable search path (the executable search path is usally stored in the environment variable "PATH"). If you e.g. installed BMRT in "/usr/local/bmrt", add "/usr/local/bmrt/bin" to your search path. The installation instructions of the renderer normally contain further help on how to modify the executable search path and make other adjustments needed (e.g. to the LD_LIBRARY_PATH environment variable). From Ayam you can easily check the setting of environment variables (as seen by Ayam) by typing "parray env" (without "") in the console window. You can also immediately try to start renderers from here, just type e.g. "exec rgl" (without "").
  As general rule of thumb, remember: if you can start the renderer from a shell, Ayam will find it too.

• 1.8 How do I actually get a rendered image file (a TIFF or JPEG) out of Ayam?
  ^‌Since Ayam 1.12, there is a render to file feature (see the view menu).
  The other route is to:
  1. Export the scene to a RIB file (e.g. using the main menu entry "File/Export/RenderMan RIB") and
  2. render this file using a RenderMan compliant renderer, e.g. if you use BMRT, type

     » rendrib <ribfile>

     into a shell (substituting <ribfile> with the file name of the RIB). You can also use the Ayam console for this, just type

     » exec rendrib <ribfile>

     into the Ayam console. The latter has the advantage, that you do not explicitly have to open a shell. Furthermore, you are immediately in the right directory and the environment variable SHADERS is set up correctly. However, Ayam is completely blocked while rendering.
  After rendering there should be a TIFF image file on your disk which may be processed further, e.g. converted to JPEG etc.

• 1.9 How do I set up Ayam to scan my shaders?
  ^‌In short: load a shader parsing plugin, adapt the "Shaders" preference setting, press the "Scan Shaders" button in the preferences.
  See also the file "Setup.txt" (for UNIX) or "SetupWin32.htm" (for Windows) in your Ayam directory. In addition, the Ayam documentation has a section about shader parsing plugins.
  See also the next question.

• 1.10 How do I load a plugin? I always get some Tcl error message.
  ^‌Use the main menu entry "File/Load Plugin", select the appropriate file (plugins usually have the file name extension ".so" on UNIX and ".dll" on Windows), then press the "Ok" button. If loading of a plugin via "File/Load Plugin" fails, make sure that:
  • the corresponding Tcl script is in the same directory as the shared object,
  • UNIX: your LD_LIBRARY_PATH environment variable contains the path of the plugin or ".",
  • UNIX: if you use a self compiled binary built with gcc, you added "-rdynamic" to the EXLDFLAGS for compilation,
  • LD_LIBRARY_PATH or PATH contain the paths of additional libraries wanted by the plugin.
    Since a plugin may be dynamically linked with other libraries, the paths to those libraries also have to be included in your LD_LIBRARY_PATH environment variable (on UNIX) or in your PATH environment variable (on Windows). On UNIX, try

    » ldd <plugin>.so

    in your shell to check, whether the plugin is dynamically linked with other libraries.
    On MacOSX, use

    » otool -L <plugin>.so

    instead.
    On Win32, check the file SetupWin32.htm for information on additionally required libraries or use "depends.exe".
  Note that some UNIX operating systems offer additional ways of managing library search paths, e.g. on Linux you can also use the configuration file "/etc/ld.so.conf" and the ldconfig tool (if you are root).

• 1.11 My shader parsing plugin does not work at all; are there known incompatibilities?
  ^‌Yes, there are some versions of renderers with broken or incompatible shader parsing libraries:

  Since (including) version 1.0.0b, the 3Delight shader parsing plugin does not work anymore on Linux. Private communication with the 3Delight author(s) revealed, that 3Delight is compiled with Intels "icc", which may result in "libc" incompatibilities leading to crashes; if you have "icc" on your system, please try to compile Ayam and the ayslo3d plugin with it, and report, whether this fixes things).
  Update: 3Delight 8.5 shader parsing works again (in Ayam 1.16).

  Aqsis 0.7.4 and 0.7.5 libslxargs seems to be broken (0.7.3 works ok and the authors are informed of this).
  Aqsis 0.7.6 through 0.7.8 libslxargs ignore the last element of the shader search path; if you have just one element, Ayam will not find a single shader. Solution: always add an ":." to your shader search path.
  Aqsis 0.7.9 and 0.7.12 seem to work ok completely.
  The interface of Aqsis 0.7.19 libslxargs changed in some incompatible way, so that the Ayam 1.5 (and below) shader parsing plugin will not work with Aqsis 0.7.19 and up.
  The interface of Aqsis 0.9.3 libslxargs again changed in some incompatible way, so that the Ayam 1.8 (and below) shader parsing plugin will not work with Aqsis 0.9.3 (and up) compiled shaders.
  The interface of Aqsis 1.2 libslxargs again changed in some incompatible way, so that the Ayam 1.13 (and below) shader parsing plugin will not work with Aqsis 1.2 (and up).
  The interface of Aqsis 1.6 libslxargs again changed in some incompatible way, so that the Ayam 1.16 (and below) shader parsing plugin will not work with Aqsis 1.6 (see also the Aqsis forum for details).
  Note that the latter two incompatibilities only hurt you, if you are compiling Ayam and the shader parsing plugin from source. The Aqsis shader parsing plugin distributed with the official Ayam binaries can indeed parse shaders compiled with Aqsis from version 1.0.1 to 1.6.

  Pixie 1.3.3 shader parsing on Win32 only works, when the shader search path contains just a single element.

  To parse BMRT/slc compiled shaders with the ayslc plugin on Win32, all ".intelnt.slc" files may need to be removed.

  Some renderers (e.g. 3Delight) distribute wrong or old compiled shaders that may not be parsed with the corresponding shader parsing plugin unless the shaders are recompiled from source with the shader compiler of the renderer distribution. Ayam may even crash while scanning for shaders if this is the case. To debug this situation, start with a single shader directory with one compiled shader. Then add shaders until it crashes again. Also, take a look at time stamps and magic bytes at the start of the compiled shader files. Do not trust the compiled shaders distributed with a renderer, always compile everything from source!

  As last resort, if you cannot get the shader parsing plugins to work, see also the question 3.7 How can I use Ayam with a different renderer.... below.

• 1.12 How do I change the keyboard shortcut for the Alt-rotate view-action?
  
  • Open your ayamrc file in a text editor while Ayam is not running.
  • Look for, and change the following lines:
    set ayviewshortcuts(RotModKey) {Alt_L}
    set ayviewshortcuts(RotMod) {Alt}
    to e.g.:
    set ayviewshortcuts(RotModKey) {Control_L}
    set ayviewshortcuts(RotMod) {Control}
    
  • Start Ayam.
  Now you can rotate your views with the Control-key held down, instead of the default setting using the Alt-key. See the manual page of the Tk bind command for a number of possible settings (modifiers) for RotMod and e.g. the output of "xev" or "xkeycaps" for the keysym associated with this modifier key. Remember to always change both settings and to put the modifier into RotMod and the keysym into RotModKey (hence the naming of those options).

• 1.13 Where is the PDF version of the Ayam documentation?
  ^‌The PDF version of the Ayam documentation is distributed with every release archive in the "doc" folder.

• 1.14 Is feature X available on platform Y?
  ^‌While the Ayam core functionality (modelling, RIB export) is available everywhere, functionality that is realized through plugins is not available on every platform. This is mainly due to deficiencies in operating system implementations and limited availability of third party software.
  The following table gives a short overview over the features that are not available on every platform.

  Feature	Win32	Linux	Mac OS X (X11	Mac OS X (Aqua)	IRIX	Generic UNIX4
  CSG Preview	Yes	Yes	No1	No2	No3	Yes
  IDR	No	Yes	Yes	Yes	Yes	Yes
  JavaScript Interpreter	Yes	Yes	Yes	Yes	No	?
  Aqsis Shader Parsing	Yes	Yes	Yes	Yes	No	Yes
  Pixie Shader Parsing	Yes	Yes	Yes	Yes	No	?
  PRMan Shader Parsing	Yes	Yes	No5	No5	Yes	No
  RDC Shader Parsing	Yes	Yes	No	No	Yes	No
  BMRT Shader Parsing	Yes	Yes	No	No	Yes	No
  Gelato Shader Parsing	Yes	Yes	No	No	No	No

  ¹ GLX implementation does not support PBuffers extension.
  ² RenderTexture is not available for Mac OS X Aqua.
  ³ Could not compile OpenCSG (C++ compiler too old; might work with gcc>3.0 or MIPSPro>7.2).
  ⁴ e.g. FreeBSD, NetBSD, Solaris
  ⁵ Could work, but the Ayam team has no access to the relevant link libraries on that platform.
  

• 1.15 After upgrading Ayam the new keyboard shortcuts do not work as documented?
  ^‌This is because the upgrade process is not changing your "ayamrc" file, which holds all keyboard shortcuts. Your options are
  1. to reset this file completely via the main menu entry "Special/Reset Preferences" (the easy way; not recommended since you lose all preferences) or
  2. to reset this file partially; type into the Ayam console:

     » unset aymainshortcuts

     then

     » unset ayviewshortcuts

     then restart Ayam.

2 Renderer specific questions:

• 2.1 The rendering windows of Aqsis do not close.
  ^‌Aqsis is using two processes when rendering. Ayam can only kill the first one (which is directly spawned by Ayam). Unfortunately, if the first process dies, the second process (which controls the window) is not notified about this and the window stays open. The work-around is to press "Esc" in the rendering window.

• 2.2 Viewport rendering with Aqsis fails.
  ^‌Viewport rendering with Aqsis fails with the error message

  ERROR: Parse error at /tmp/ayamBIezgJ.rib:49 (col 1) while reading WorldEnd: Cannot find the primary display(0) driver "framebuffer"

  even though everything seems to be set up correctly. The solution is to remove the -fb command line option from the corresponding render command preference setting.

• 2.3 When switching virtual desktops BMRT rendering windows do not repaint.
  ^‌This is a bug in BMRT 2.6 that was, unfortunately, never fixed. It also happens if other windows obscure BMRT windows or if BMRT windows are iconified. This bug is not present in BMRT 2.5.

• 2.4 How do I enable raytracing with Pixie?
  ^‌Set the hider to "raytrace" by adding a RiHider tag to the Root object or by setting the corresponding option in the RIB-Export preferences and add a global RiAttribute tag (to the Root object): visibility,specular,i,1.
  For raytraced shadows:
  • use a custom light with one of the shadow* light shaders as light source,
  • set the "shadowname" shader parameter to "raytrace", and
  • add a global RiAttribute tag (to the Root object): visibility,transmission,i,1.

• 2.5 How do I make viewport rendering work?
  ^‌Check that
  • the correct display driver is set (use pixiefifodspy for Pixie),
  • the renderer command used does not contain options that force rendering to a different display than that specified in the RIB,
  • the display driver used is of the correct machine type (it must match the machine type of the renderer used), the machine type of the plugin in the Ayam binary distributions matches that of Ayam, other plugins can be downloaded from the SourceForge project download page.
  • the hidden preference option DisplayPath contains the path to the display driver, check by entering

    » puts $ayprefs(DisplayPath)

    in the Ayam console. Set this to "" for Pixie on Windows, i.e. enter to the console:

    » set ayprefs(DisplayPath) ""

    and copy the "pixiefifodspy.dll" file from Ayam to the Pixie installation directory, more specifically: to the "displays" sub-directory.
    
  • on Windows, if the error message is "openpipe: CreateFile failed." check for left over files in the %TEMP%-directory that are named like "ayam2.fifo"; remove these files; if they are held by previously launched renderer processes, kill these processes first.
    These files were created by a buggy fifodspy/pixiefifodspy plugin, that are now available in a new version, please download version 2 of these plugins from the SourceForge File Release System and install it/them into/for your renderer. See also the corresponding Ayam bug.
  See also the next question.

• 2.6 How do I enable preview rendering from Ayam with Pixie on Windows?
  ^‌Set the temporary directory to "." and load the "aysdr" shader parsing plugin, it contains code that transforms the shaders preference setting to a Pixie compatible style.
  See also the question above.

3 Windows related questions:

• 3.1 I cannot render anything, all I get is some Tcl error message?
  ^‌If the error message is "Error: couldn't duplicate input handle: bad file number", please try to start Ayam via the provided batch file "ayam.bat".

• 3.2 When loading scene files, I get an error message. Is this a bug in Ayam?
  ^‌This issue should be resolved since Ayam 1.8.
  When the error message is "Error: can't read "type": no such variable" you were probably using a double-click to select the scene file and start loading it. This, unfortunately, does not work due to a bug in the Windows file requester. If this happens to you, you need to restart Ayam and please remember to always use the "Ok"-button in the file requester on Windows. See also this Tcl-Wiki page for a more complete discussion.
  This issue should be resolved since Ayam 1.8.

• 3.3 I have set up the BMRT Shaders correctly, but Ayam still does not scan them?
  ^‌Please remove all "<shadername>.intelnt.slc" files from your shader path(s).

• 3.4 Where is the RRIB-Plugin?
  ^‌Since Ayam 1.12, there is full plugin support and the RIB import plugin available also on the Win32 platform.

• 3.5 How do I compile Ayam on Windows; are there any project files?
  ^‌Since Ayam 1.10, there is a complete workspace for Visual C++ 2005 Express available for download.

• 3.6 Where can I get a "cat.exe" for the RenderGUI feature?
  ^‌A working "cat.exe" is available from the UnxUtils project on SourceForge.
  Since Ayam 1.7 a "cat.exe" is distributed with Ayam.

• 3.7 How can I use Ayam with a renderer without working shader parsing plugin?
  ^‌You simply have to compile all your shaders with two shader compilers:
  1. the shader compiler from a renderer where shader parsing works and
  2. the shader compiler of the renderer you use.
  Then use the first set of shaders with the shader parsing plugin that works in Ayam but render with the other set of shaders. The Ayam distribution contains a Makefile (in "ayam/scn/shaders") that shows how this can be set up without much hassle.
  

• 3.8 Ayam is not drawing the selection rectangle! What can I do about this?
  ^‌Download and install the latest OpenGL drivers for your graphics card. If it still does not work, you can also try to put the "opengl.dll" file from "opengl95.exe" into the "bin" directory of Ayam (this is where the file "ayam.exe" is located). Yes, unfortunately, you will then lose hardware acceleration in Ayam. But this is not too bad if your machine is moderately fast.

• 3.9 I cannot see any plugins (DLL files) when I try to load them via "Load Plugin".
  ^‌The Windows file requester does not show any DLL files unless the folder option "hide system files" is switched off  in the explorer preferences (WinXP: "Tools/Folder Options/View").

• 3.10 I cannot select font description files from "c:\winnt\fonts" for the Text object.
  ^‌This issue should be resolved since Ayam 1.33, which simply uses a different file requester.
  The Windows file requester does not show font description file names from the directory "c:\winnt\fonts" but only font names. Ayam can not use these font names but only font description file names. Consequently, you need to copy the corresponding font description file (e.g. "arial.ttf") to a different directory on your disk to select it using the file requester or enter the path and filename manually into the entry field in the Text object property.

• 3.11 Ayam 1.14 (and up) do not start on Windows XP.
  ^‌Just download and install vcredist_x86.exe or the .Net framework in version 2.0 (or newer).
  For Ayam 1.16 (and up) you need this version of vcredist_x86.exe instead.
  See this webpage for a detailed description of the problems related to deploying executables on Windows XP.

4 Linux related questions:

• 4.1 Rendering from Ayam leaves many zombie processes around, how do I get rid of them?
  ^‌Make sure you set "-DAYENABLEWAIT" in your CFLAGS for compilation (the official Linux binary is compiled this way) and set the preference variable ayprefs(Wait) to "waitPid" in your ayamrc file.

• 4.2 I cannot see the control points of NURBS curves to edit them, even though the right modelling action ("Edit Points") is active.
  ^‌This is probably caused by a broken OpenGL implementation. Bad OpenGL implementations known are: Mesa DRI for a range of graphics cards with ATI chipsets (vendor: VA Linux Systems, Inc), and Mesa 4.0.4.
  Mesa 5.0 and 5.0.1 are known to work. To resolve this, install a recent Mesa in the system or install it somewhere else and point Ayam to it via LD_LIBRARY_PATH, or compile it statically (make linux-static) and re-compile Ayam with this static OpenGL library (adapt GLINCDIR and GLLIBS in the Ayam Makefile). Yes, unfortunately, you will then lose hardware acceleration in Ayam. But this is not too bad if your machine is moderately fast.
  You may also try to change the preference setting "Modeling/HandleSize". Some OpenGL implementations just allow point sizes of 5 at maximum.

• 4.3 The "Edit Points" and "Tag (Select) Points" modelling actions do not work, I can click on points but nothing happens.
  ^‌See the question above. Alternatively, if it does not work when you zoom in to your models, check and decrease the preference setting "Modeling/PickEpsilon".

• 4.4 Ayam looks strange on my desktop, with black, thick scrollbars and buttons. How can I change this?
  ^‌Your Linux distribution probably defines some evil X resources that make the scrollbars (or other GUI elements) look black and thick. To cure this search for "Xresource" or "Xdefaults" files in your home directory, "/usr/X11R6/lib/X11", and "/etc/X11" and its sub directories and see if you find lines like: "*ScrollBar*Foreground: black" or "*ForeGround: Black" in those files. Comment out those lines using an exclamation mark ("!") as first character. Note that you may need to restart the X server to let these changes take effect.

• 4.5 The AutoFocus feature does not work? What can I do?
  ^‌Some recent versions of kwm (the KDE window manager) do not allow applications to manage the focus on their own, thus AutoFocus does not work. You can check this easily by typing

  » toplevel .tw; focus .tw

  into the Ayam console. If the focus does not change to the new empty window you are out of luck and your options are to switch to a different window manager or to enable auto focus in the window manager configuration.

• 4.6 How can I set a good looking font in Ayam?
  ^‌Add the following to your ~/.Xresources file:
  

  Ayam*Font: 7x14

  Instead of 7x14, you can of course pick any font that appeals to you. You may derive available font names using "xfontsel".

• 4.7 The official Ayam executable does not start. How can I make it run?
  ^‌If the error message is

  No resource found
      while executing
  "error $msg"
      invoked from within
  "if {[catch {::wrap::source ayam.tcl} msg]} {
  	error $msg
  }"
  

  the Ayam executable was stripped. Do not strip the Ayam executable.

• 4.8 The repairAyam.tcl script fails to send itself to Ayam. How can I make it work?
  ^‌If the error message is

  X server insecure (must use xauth-style authorization); command ignored
  

  check with the command

  xhost
  

  whether there are foreign hosts allowed to connect to your X server. If there are any, you are really running a insecure setup and the complaint is valid. But if the output contains just a single entry, i.e. looks like this:

  access control enabled, only authorized clients can connect
  SI:localuser:username
  

  where username is your user name, you can make the repairAyam.tcl script work by issuing the command

  xhost -SI:localuser:username
  

  again substituting username with your user name.

5 IRIX related questions:

• 5.1 What can I do about flashing menus and horizontal stripes?
  ^‌Disable "save unders" in your 4DWM configuration.

• 5.2 Ayam does not draw NURBS curves, and prints "color_flag = 0" to the console. What can I do about this?
  ^‌Add -DAYIRIXBUG to your CFLAGS and recompile Ayam (the official IRIX binary is compiled this way).

6 Solaris related questions:

• 6.1 Ayam can not open any view windows, but prints an error message about a failed Xmu colormap lookup. What can I do?
  ^‌Add -DSOLARIS_BUG to your CFLAGS and recompile Ayam.

7 Mac OS X related questions:

• 7.1 Ayam does not remember my preference settings.
  ^‌This only applies to the X11 version! Please use "Ctrl+q" to quit Ayam and not "Apple+q".

• 7.2 Box objects are drawn in wireframe.
  ^‌Box objects may be drawn in wireframe mode (instead of being shaded) when NURBS patches also exist in the scene. This is a bug in Apple OpenGL that has been reported on 13. Jan 2006. Since their first reply to the bug report was on 9. Jun 2006, extrapolating from this speed, I expect them to acknowledge the bug in December 2006, fix it to June 2007, and roll the bug fix out to customers in December 2007. Happy waiting.
  Meanwhile, a workaround has been found and implemented that will be available for Ayam 1.11.
  This story found a very embarrassing ending, as the bug was silently removed from the bug database after a demonstrating program was provided that took me 30min to create. You think I will ever report another bug?

• 7.3 AutoFocus does not work in Aqua?
  ^‌Yes and it will never work and you should be glad about it, because if it would work and you would browse from the main window to the menu bar over a view window, you would never be able to access the main menu bar, because AutoFocus would change the main menu bar immediately to the view menu bar...

• 7.4 Ayam can not start Safari to show the documentation?
  ^‌When Safari does not start, most probably the preference setting "Main/Docs" is pointing to a non existing file. Correct this using the preferences editor and it should work again.

• 7.5 How do I disable the splash screen?
  ^‌Open the Ayam.app directory in the Finder using the context menu; browse to "Ayam.app/Contents"; Double click on the "Info.plist" file. Search for the "LSEnvironment" dictionary, open it and set the value of the "AYNOSPLASH" key to 1. Save the Info.plist file.

8 Project related questions:

• 8.1 When will you implement feature X?
  ^‌Probably never! You should consider contribution. See also Question 8.3. The documentation also lists numerous ways of contribution. See also the following questions.

• 8.2 I would like to contribute, how do I? Do you accept patches?
  ^‌You are very welcome to send me your patches against the Mercurial-Tip for review and later inclusion. How do you get the Mercurial-Tip? Here is a small guide on how to work with the Ayam Mercurial repository.
  When writing or changing code, please follow the guidelines in the file "ayam/src/Ayam-codingstyle.txt".
  In order to avoid conflicts (e.g. double work), the feature request tracker on SourceForge is used for coordination of the development.

• 8.3 I would like to contribute, but I am no developer?
  ^‌This is really not a problem at all. There are many things that you can do. You could e.g.
  • translate the documentation (for that, check out the "docs" module from the Ayam Mercurial repository),
  • translate the balloon help texts (see "ayam/src/tcl/ms.tcl"),
  • draw new icons (Many functions of Ayam are just accessible via main menu and not via toolbox, because there are no icons for them!),
  • create example objects, scenes, or images,
  • write or translate tutorials,
  • if you are on Linux/ix86: run Ayam with Valgrind, execute your favourite modelling actions, and report your findings,
  • "Baby-Hackers" may e.g. improve the source code documentation by converting it to a Doxygen compatible format,
  • etc. pp.; your own ideas here.

• 8.4 I think I found a bug. How do I submit a bug report?
  ^‌You are very welcome to submit bug reports. Please follow the steps below to report bugs:
  1. Make sure that the bug is not already reported (see the bug database).
  2. Collect all necessary information to describe and reproduce the bug:
     • describe what you were trying to do and what went wrong,
     • versions (of your operating system, Ayam, Tcl/Tk, OpenGL, renderers etc.; you may derive much of this information easily from the Ayam about requester),
     • error messages from the console/log file(s),
     • your ayamrc file (if helpful to reproduce the bug),
     • scene file(s) (if helpful to reproduce the bug).
  3. Not mandatory: Verify the presence of the problem on different platforms and verify rendering problems with different renderers.
  4. Not mandatory: Create a work-around and/or a patch that fixes the bug based on the Mercurial-Tip.
  5. Send the bug report
     • to the bug database (if you are sure about it),
     • to the public forum (if you are not that sure) or
     • just send mail instead.
     Use only one of these three options!
     If you posted to the bug database, please monitor the entry you made for about a week for possible questions or comments by the person who tries to reproduce/fix the bug. Note that monitoring will be easier if you do not post anonymously, because you will receive email on your SF account if the item (bug report, feature request) is touched.

  Furthermore, there are some Windows specific issues, that are not bugs in Ayam itself, so please do not report one of the following known issues:

  • Win98: the grid menu is not drawn completely (Tk vs. Win98 problem),
  • Win98: Ayam does not scan shaders, if intelnt.slc-files are present (libslcargs vs. Win98 problem),
  • WinNT: "ayam.bat" does not work correctly, it is not possible to inherit the value of "AYAMRC" to Ayam (WinNT "security" policy problem),
  • Win2000: the RenderGUI progress meter does not update correctly until the window is manually activated once (Tcl/Tk vs. Win2000 problem),
  • Win2000: Ayam can not execute other programs (e.g. renderers) if ayam.exe is started directly and not via ayam.bat (Tcl vs. Win2000 problem),
  • Win2000/XP: Menu entries with check marks are not drawn correctly until the mouse pointer is moved over the menu entry (Tk vs. Win2000/XP problem), the menu problems partially go away if you disable the menu animations (transition effects) on your desktop,
  • all Windows systems: Ayam immediately crashes if NURBS patches with invalid trimcurves are drawn using GLU (bug in Microsoft glu32.dll).
  • Win2000 (depending on graphics card, OpenGL driver version): opening view windows takes a long time (>1s) if the user is not "Administrator"
  Please verify the presence of those problems on Win95/WinME/WinXP and mail me your results. If you find a bug in the Mercurial-Tip of Ayam that is not present in the current official release, please, do not enter it to the bug tracking system, but rather send e-mail or post into the public forum.

• 8.5 How do I check out the Ayam sources from the Mercurial repository?
  ^‌This question is answered in a separate document.

• 8.6 Is there documentation on the Ayam scene file format? How can I parse this format?
  ^‌There is no documentation on the .ay file format. It is merely a serialization of the internal Ayam object structure as laid out in the file ayam.h. The Ayam team recommends against trying to convert .ay-files directly. Instead, write (better) import filters for one of the export file formats of Ayam (RIB, MF3D (Apple), 3DM (Rhino), Wavefront OBJ, X3D) for your target system, or write a new export plugin for Ayam, obvious targets are U3D, FBX, IGES, COLLADA.

9 Questions related to self compiled executables:

• 9.1 How do I compile Ayam? I typed "make" but just got errors.
  ^‌There are extensive compilation instructions in the file "ayam/src/INSTALL", please read it.

• 9.2 My self compiled Ayam crashes when I try to open a view window.
  ^‌Please read the compilation instructions (file "ayam/src/INSTALL") more carefully and use the correct version of the Tcl/Tk sources to compile Ayam.

• 9.3 Can I use plugins from the official binary distribution with my self compiled executables?
  ^‌Yes, as long as the major version numbers of Ayam (e.g. "1.3") and Tcl/Tk are matching. If you use the sources from the Mercurial repository, you can simply check out a version with matching release tag to be on the safe side.

• 9.4 I get Tcl errors when I try to drag and drop objects in the object tree widget. Is this a bug in Ayam?
  ^‌This issue should be resolved since Ayam 1.5.
  This is not really a bug. Ayam (V1.4 and below) requests to load the BWidgets package without specifying an exact version. Unfortunately, newer BWidget versions than 1.2.1, which is distributed with Ayam, seem to have changed in incompatible ways which leads to Tcl errors while doing drag and drop. The newer versions of BWidgets may get loaded into Ayam in favour of BWidgets 1.2.1, if they are installed in your system. An easy fix for this is, consequently, to deinstall the newer BWidgets package, if no other of your Tcl/Tk applications depends on it. You can also change the package loading code in tree.tcl to "package require -exact BWidgets 1.2.1".
  This issue should be resolved since Ayam 1.5.

• 9.5 How can I compile Ayam with Tcl/Tk 8.4.x?
  ^‌The C-interface of Tcl/Tk changed in incompatible ways between versions 8.3.x and 8.4.x, so that Ayam will not compile cleanly unless you add "-DUSE_NON_CONST" to the CFLAGS variable in the Ayam Makefile.
  Please see this Tcl-Wiki page for more background information.

• 9.6 How do I compile a shader parsing plugin?
  ^‌Compiling shader parsing plugins is much easier since Ayam 1.11. The only prerequisite besides the renderer are the Tcl headers in the right version (the version Ayam uses). To compile a shader parsing plugin download and unpack the matching Tcl sources and run configure first. Then do:

  » cd ayam/src/plugins
  » g++ aySSS.cpp -o aySSS.o -I.. -Ipath-to-renderer-headers -Ipath-to-tcl-headers
  » g++ -shared aySSS.o -o aySSS.so -Lpath-to-renderer-libs -lrenderer-lib
  

  substituting SSS with the shader file name extension, e.g. so for RDC, slc for BMRT, slx for Aqsis etc.
  For example:

  » g++ ayslc.c -o ayslc.o -I.. -I../../BMRT2.6/include -I../../../tcl8.4.18/generic -I../../../tcl8.4.18/unix
  » g++ -shared ayslc.o -o ayslc.so -L../../../BMRT2.6/lib -lslcargs
  

  builds the ayslc.so plugin to scan BMRT compiled shaders.

top of page