This section contains all information about Ayam not fitting elsewhere.
Using the undo system you may correct mistakes you made while modelling. However, it is currently not possible to undo any changes to the object hierarchy, including clipboard and Drag-and-Drop operations. If you delete an object, it is gone! If you, accidentally, move an object using Drag-and-Drop, undo will not help! Only changes to objects are undoable. This includes changes made by modelling actions, changes made using property GUIs, but also changes to views (type changes or changes to the camera settings associated with a view).
The undo system works by storing copies of the different
states of changed objects in an undo buffer. The storage space occupied by
the undo buffer may be adjusted using the preferences
("Prefs/Modelling/UndoLevels"
). Note that a value of -1 for
UndoLevels completely disables the undo system.
You may step backward through the saved states using
<Ctrl+z>
(undo) but also forward using <Ctrl+y>
(redo).
Several actions will completely clear the undo buffer (no undo is possible after those actions): Delete Object, New Scene, Open (Replace) Scene, and Close View.
Note that undo/redo will also modify objects that currently reside in the object clipboard if they have saved states in the undo buffer.
To customize Ayam the ayamrc file may be used.
This file is either pointed to by the environment
variable AYAMRC
or is determined as following:
"~/.ayamrc"
, where "~"
denotes the home directory of the current user."$(HOME)/ayamrc"
if the environment variable
HOME
exists, else "$(TEMP)/ayamrc"
.
"~/Library/Preferences/.ayamrc"
, where "~"
denotes the home directory of the current user.The ayamrc file is read on each start of Ayam and saved again on exit
(if the preference setting "Main/AutoSavePrefs"
is enabled).
The ayamrc file contains:
You may edit the file by hand, but keep in mind, that the file will be
parsed by Tcl. Should you, for some reason, destroy your ayamrc so that
Ayam does not start correctly anymore you may start Ayam with the command
line option "-failsafe"
.
When the application is left the next time, or the main menu entry
"File/Save Prefs"
is invoked, a correct ayamrc file will be
created again.
All preference settings will be reset to factory defaults, however!
Another way to reset the ayamrc is to simply delete it using the
main menu entry "Special/Reset Preferences"
.
To reset single elements to factory defaults, just remove the corresponding lines from the ayamrc file.
You may adapt the keyboard shortcuts used in the GUI to your special
needs using the ayamrc file. Note that if you do that the GUI (the menu
entries and the "Show Shortcuts"
window)
will adapt to your changes but certainly neither this documentation nor
the tutorials!
Ayam does not check for clashes! This means, the last set binding
for a key will be used.
On Unix, the output of the program "xev"
and the
manual page for the "bind"
command of Tk provide helpful
information about which strings may be used to describe
key presses.
You can also directly use the Ayam console to infer key names, just enter:
toplevel .keytest bind .keytest <Key> {puts %K}
For your convenience, the special string "Ctrl"
will be replaced by
"Control"
before a shortcut is handed to the bind
command.
Example:
set aymainshortcuts(Prefs) {Ctrl-p}
<Ctrl+p>
.
See the ayamrc file itself for a complete listing of available shortcuts.
The ayamrc file currently contains the following adjustable hidden preference settings:
"Balloon"
: time in ms until the tooltip window appears
(default: 1500ms - 1.5s)
"EFlush"
: time in ms between two flushes of the error message
buffer (default: 2000ms - 2s)
"toolBoxList"
: a list of sections or groups of buttons
describing the appearance of the toolbox window (default, using all
available sections: {trafo trafo2 solids misco nurbs toolobjs points
nctools1 nctools2 camera misc}
)
"Kill"
: name of a program that kills other processes and accepts
a process id as argument (used by the Rendering GUI)
(default: "kill"
) (a setting of "kill"
will be
automatically replaced by "kill.exe"
on Win32)
On the Win32 platform you may also use an internal kill command
"w32kill"
that has been introduced in Ayam 1.4.
"Cat"
: name of a program that can read from and write to
a pipe (used by the Rendering GUI) (default: "cat"
)
(a setting of "cat"
will be
automatically replaced by "cat.exe"
on Win32)
"KeepNTmpFiles"
: how many
incarnations of the scene in RIB form (which actually may be split
in more than one file due to e.g. instances) created when directly
rendering from a view window should be kept on disk (default: 5)
"Wpclip_pastetosel"
: should
"Special/Clipboard/Paste Property to Selected"
raise a warning
requester? (default: 1 - yes)
"DailyTips"
: a list of strings that appear as tips
on startup in the console (default: large)
"PickTolerance"
: the tolerance used to determine whether an object
should be picked or not (default: 5); this setting determines the size
of a rectangular area around the picked point in pixels, all objects that
are inside or touch this area are considered picked
"MaxTagLen"
: the maximum number of characters to be displayed
in the buttons in the Tag Property GUI (default: 30)
"Wait"
: set this to "waitPid"
if you want to enable
the work around for zombie processes created by the Rendering GUI.
This is e.g. necessary for the Linux platform.
"Prompt"
: controls the prompt for the console. If
set to an empty string a default of
\[Undo:$ay(undoo)/Redo:$ay(redoo)\].../[file tail [pwd]]>
"[pwd]>"
to see just the full path
name of the current directory. If you want to display the value of a
variable in the prompt (e.g. designating the current level in
the scene hierarchy) you need to bind a write-trace to that variable,
that calls the procedure "update_prompt"
. This write-trace
may e.g. be established using a small script like this:
"trace variable <vname> update_prompt"
.
"BackupExt"
: is the file name extension to be used for backup
files. Default values are "~"
for Unix and
".bak"
for Win32.
"SelXOR_R"
, "SelXOR_G"
, "SelXOR_B"
: determine
a color value that is used for drag selection rectangles.
Note that the color is not used directly but combined with the
color value of already drawn pixels by XOR. The default values
are 255 for the red, 128 for the green, and 0 for the blue component.
"IconGamma"
: this setting may be used to adapt the contrast
of all icons (in view menu and the toolbox) to your display gamma. If you
are on a SGI it is recommended to set this to about "0.7".
"AddViewParams"
allows to add custom parameters to the
view OpenGL widget creation, like e.g. "-stereo true"
.
"AskScriptDisable"
controls the warning dialog that
appears if scenes with script objects or tags are loaded.
"WarnUnknownTag"
controls the warning messages for
unknown tag types.
"FixX11Menu"
enables a workaround for non-sticky menus
on X11 (displaced menus do not stay open). This option is enabled
by default and not used on the Win32 platform.
"SafeAutoFocus"
disables AutoFocus
(see section
preference settings)
when certain dialog windows are open, so that they do not get
shuffled under other windows by accidental mouse movements on systems
where the window manager does only auto raise in conjunction with
auto focus.
This option is enabled by default on Win32.
"UseInternalFD"
switches to an internal file dialog for loading
of plugins. This option is only used on MacOSX/Aqua (not X11!), because
there the normal file dialog will not enter application bundle directory
structures. This option is enabled by default on MacOSX/Aqua.
"SwapMB"
, "SwapMBSC"
allow to swap mouse buttons 2 and 3
on MacOSX/Aqua (not X11!) for specified mouse bindings ("SwapMBSC"
),
because on MacOSX/Aqua, traditionally, the naming of the
middle and rightmost mouse button is reversed compared to X11/Win32.
This option is enabled by default on MacOSX/Aqua and allows to use
the same set of mouse bindings (the same ayamrc file) for X11 and
Aqua without sacrificing user experience. The middle mouse button,
by default, zooms the view, and the right one moves the view.
"CursorEnd"
, this option is enabled by default. If switched
on, the first click into the console will move the cursor to the input
prompt, ready for command input, instead of moving the cursor to the
point of the click.
"PrepDiaCap"
, this option prepends the title of a message box
that is normally displayed in the window frame of the message box to the
message in the box. This may be necessary because on some systems the title
string might be displayed in an unreadable font or not at all.
On Mac OS X Aqua (not X11!) this option is enabled by default.
On all other systems this option is disabled by default.
"LineWidth"
, line width used for drawing the lines of
unselected objects (blue lines in standard color configuration).
The default value is 1.0. Ayam is not checking, whether the specified
value is supported by the OpenGL implementation used.
"SelLineWidth"
, line width used for drawing the lines of
selected objects (white lines in standard color configuration).
The default value is 1.0. Ayam is not checking, whether the specified
value is supported by the OpenGL implementation used.
"ALFileTypes"
, "ALPlugins"
two lists that describe
file name extensions and corresponding plugins that import and export
files of the type designated by the file name extensions.
"AUCommands"
, commands that will be run in the console
when <Shift+Return>
is used instead of <Return>
.
See also section
Updating the GUI.
Using your ayamrc file, you may also adapt the database of RiOptions and RiAttributes to your rendering system.
You can then easily add those options and attributes
to your scenes using tags and the main menu entries
"Special/Tags/Add RiOption"
and
"Special/Tags/Add RiAttribute"
,
see also sections
RiAttribute Tag and
RiOption Tag.
The syntax for a new RiOption is quite simple as the following example shows:
set riopt(runtime) { { verbosity s { "silent" "normal" "stats" "debug" } } }
"runtime"
and adds a single
option, "verbosity"
, to it. The option is declared to be of type
string using "s"
and provided with a list of default values:
"{ "silent" "normal" "stats" "debug" }"
.
To add another option to this section, say the option "op"
which shall be an integer value you have to change the aforementioned
snippet to:
set riopt(runtime) { { verbosity s { "silent" "normal" "stats" "debug"} } { op i } }
Available types of parameters are:
{{0.0 0.0 0.0}{1.0 1.0 1.0}}
{{0.0 0.0 0.0}{1.0 1.0 1.0}}
This section documents the environment variables used by Ayam.
"AYAMRC"
: designates the full filename of the ayamrc file."HOME"
: path to the ayamrc file (used on Win32 if
"AYAMRC"
is not set)."TEMP"
: path to the ayamrc file (used on Win32 if
"AYAMRC"
and "HOME"
are not set); also initial value of the
"TmpDir"
preference setting (used on Win32 if no ayamrc file exists,
that specifies "TmpDir"
)."AYNOSPLASH"
: if this variable is set to 1, the splash
screen will not be shown"BROWSER"
: filename of the preferred WWW browser (used to
display the documentation URL)"NETSCAPE"
: (if "BROWSER"
does not exist) filename
of the Netscape WWW browser (used to display the documentation URL)"SHADERS"
: initial value of "Shaders"
preference
setting (used if no ayamrc file exists).Since Ayam 1.3, the following plugins are provided to allow
parsing of shaders: "ayslb"
for Air, "ayslx"
for Aqsis,
"ayso"
for RDC, "ayslo"
for PRMan, "ayslo3d"
for 3Delight,
(since Ayam 1.6) "aysdr"
for Pixie, and (since Ayam 1.11)
"aygso"
for Gelato.
After loading of one of the aforementioned plugins, Ayam will be able to parse shaders compiled with the shader compiler of the respective renderer.
A shader parsing plugin may be loaded
automatically on startup of Ayam using one of the provided Tcl scripts:
"loadayslb.tcl"
, "loadayslo.tcl"
, "loadayslo3d.tcl"
,
"loadayslx.tcl"
, "loadayso.tcl"
, "loadaysdr.tcl"
,
and "loadaygso.tcl"
.
To automatically load a plugin simply add the appropriate
script to the preference setting
"Main/Scripts"
using the "Add"
button in the
preferences editor.
Additionally, those scripts may be further adapted to
set a different "Shaders"
preference setting or to immediately
scan for shaders after loading of the plugin. For that, just remove
the leading hash-marks (#) from the corresponding lines in the script.
Changing the scripts is not necessary if you load the shader parsing plugin
automatically on startup of Ayam, as the loading of the scripts will
happen before the Ayam startup sequence executes the initial shader scanning
pass.
However, the standard behavior of the loading script while manually
loading of such a plugin requires you to adapt the shaders search path
manually and to scan manually for shaders too.
Both actions may be carried out using the preferences editor. Scanning
for shaders may also be started using the main menu:
"Special/Scan Shaders"
.
To better accomodate the fast changing world of RenderMan renderers, since Ayam 1.11 all shader parsing plugins are Ayam version independent. This allows to distribute updated shader parsing plugins without updating Ayam too and thus in a higher frequency.
Automatic Instancing is available via the main menu entry:
"Special/Instances/Automatic Instancing"
.
Automatic Instancing creates instances from all instantiable
objects from the current level and below,
using a simple algorithm that recursively compares
objects. The comparison of materials and tags may be turned off in the
small dialog that pops up after selection of the menu entry
"Special/Instances/Automatic Instancing"
.
The algorithm is able to create instances of grouping objects too (objects with child objects, e.g. levels or tool-objects like revolve). However, in order for two grouping objects to be instantiated not only all child objects and the grouping objects have to be instantiable, but the child objects also have to be in the right order. It is not sufficient, that for every child of the potential master, a matching child of the potential instance exists. Instantiation of grouping objects may drastically decrease the total number of objects in a scene.
Note that before the automatic instantiation starts, all currently existing instances will be resolved! After instantiation some statistics will be displayed in the console.
More information about this subject can be found in:
Schultz, R., and Schumann, H.: "Automatic Instancing of Hierarchically Organized Objects", in: Kunii T.L. (ed.): Spring Conference on Computer Graphics (SCCG 2001) Conference Proceedings, Budmerice, Slovakia, 25-28 April 2001, ISBN 80-223-1606-7
The importance driven rendering plugin may be used to drastically reduce rendering times while developing a scene. It works in three main steps:
"RiMatte"
statements.Many options exist to assign importance and parameterize the rendering passes:
Elements of the scenes may be geometric objects, regions in image space, or regions in object space. Importance values are currently just binary values. Assignment may take place manually (using IDR tags) or half-automatic by derivation of importance from currently selected or changed objects. To avoid inconsistency in the resulting images, importance values may be propagated between (geometrically or hierarchically) near objects, or between objects that are related (e.g. from a material to a geometric object).
Parameterisation of the two rendering passes currently includes selection of a different renderer and the possibility to reduce rendering resolution and shading rate. To further reduce rendering times for raytracing renderers, the size of the region to render may be automatically adapted to the elements of the current importance value (including an optimisation run that balances renderer startup times and times needed to render regions not originally occupied by two regions to merge).
Furthermore, caching of partial images is possible. However, the implementation
of this feature is not very sophisticated at the moment, as it
uses the Unix text tool "diff"
to decide whether two RIB streams are
identical and hence need no re-rendering.
To start using IDR:
"File/Load Plugin"
),"Custom/Open IDR"
,"Selection"
,"Pot"
),"Render!"
button.IDR requires that atleast the renderer of the second rendering pass honours RiMatte! Since rgl does not honour RiMatte, it is sometimes necessary to simply exclude objects of different importance value. No wrong images are to be expected from this, as rgl does not calculate other than local lighting effects.
More information about this subject can be found in:
Schultz, R., and Schumann, H.: "Importance Driven Rendering - Using Importance Information in the Rendering Process", in: Hamza M., Sarfraz M. (ed.): Computer Graphics and Imaging (CGIM 2001) Conference Proceedings, Honolulu, Hawaii, 13-16 August 2001, ISBN 0-88986-303-2
CSG preview example (left without, right with CSG)
The AyCSG plugin may be used to resolve and preview CSG operations. For this, the plugin uses image based CSG rendering algorithms provided by the OpenCSG library. The OpenCSG library, currently, supports the Goldfeather and the SCS algorithm. The latter only works properly with convex primitives. Since both, Goldfeather and SCS, are image based rendering algorithms, there is no limit in geometric object types that may be used in CSG hierarchies. You may e.g. use Quadrics, NURBS, and Metaballs in every possible combination. You just have to make sure, that every CSG primitive describes a closed space.
In order for the CSG rendering algorithms to work properly, the depth
complexity (convexity) of a primitive must be known.
The depth complexity of a primitive determines the maximum number
of forward oriented surfaces any ray through this primitive would pass.
A regular sphere has a depth complexity of 1, a torus of 2, but do
not confuse depth complexity with genus, they are different values!
A 3D representation of the letter A e.g. has a genus of
1 but a depth complexity of 3.
The depth complexity of a primitive should be stored in a "DC"
tag.
A torus would e.g. get a tag named "DC"
with the value "2"
.
If no "DC"
tag is present for a primitive, a default value for
the depth complexity of "1"
will be used.
If you fail to correctly specify the depth complexity, rendering
errors, like missing parts of surfaces, will occur.
Note that the correct operation of AyCSG not only depends on the
depth complexity but also the winding order of the OpenGL primitives
(triangles or quads) used for drawing of the CSG primitives. The
winding order has to be consistent in a scene, so that the rendering
algorithm can decide what is inside and what is outside by looking
at a single OpenGL primitive. For all quadric primitives of Ayam
the winding order is always consistent. However, for NURBS patches
the winding order depends on the orientation of the patch dimensions.
If NURBS patches are used in CSG operations you, consequently, may
need to revert the patches (e.g. using the "RevertU"
tool,
see
Revert U tool).
If the winding order of some of the primitives in a CSG hierarchy
is not right, the respective primitives will not be effective
in the CSG operations to the extent that the rendered image becomes
completely empty.
The AyCSG rendering obeys the "Draw Selection only"
and
"Draw Level only"
view options as well as the hide attribute
of objects. If the CSG rendering fails for complete complex scenes,
you might still get a preview of the important CSG using objects by
selecting them and enabling the "Draw Selection only"
view
option.
Also note that CSG rendering requires fast graphics hardware
(the more fillrate, the better). Furthermore, your OpenGL subsystem
has to support the PBuffers extension and, depending on the
rendering options chosen, a stencil buffer. Speedups may be
achieved using the "GL_ARB_occlusion_query"
or
"GL_NV_occlusion_query"
extensions (if available to you).
Once the AyCSG plugin is loaded successfully you can render the CSG
preview in any view window using the keyboard shortcut
<Ctrl+Shift+c>
or using the new button in the menu
bar of every view window. If you hold down <Shift>
while pressing the button the view will continually render CSG
(the button stays pressed to signify this) until you click onto
the button again.
The AyCSG plugin supports the following options, that are available
through the main menu entry "Custom/AyCSG Preferences"
:
"Algorithm"
allows to switch between the Goldfeather and
SCS algorithm. Note again that the SCS algorithm only works correctly
for convex primitives. The "Automatic"
setting chooses one
of the algorithms based on whether concave primitives (depth complexity
> 1) are present or not."DCSampling"
determines a depth complexity sampling
strategy. Quoting from the OpenCSG documentation, the following options
are available:
"NoDCSampling"
: Does not employ the depth complexity. This essentially
makes the algorithm O(n^2), but with low constant costs.
"OcclusionQuery"
: Uses occlusion queries to profit implicitly from
depth complexity without calculating it. This is especially useful for the
SCS algorithm where this strategy is applied at shape level, resulting in
a O(n*k') algorithm (where k' <= k), without significant constant overhead.
This strategy requires hardware occlusion queries, i.E., the OpenGL
extension "GL_ARB_occlusion_query"
or
"GL_NV_occlusion_query"
.
"DCSampling"
: Calculates the depth complexity k using the stencil
buffer. This makes the algorithm O(n*k), but with high constant costs.
In case of the Goldfeather algorithm, the literature denotes this as
layered Goldfeather algorithm.
"CalcBBS"
determines whether bounding boxes should be
calculated and used for speed up (not working at the moment).See also: Kirsch F. and Doellner J.: "Rendering Techniques for Hardware-Accelerated Image-Based CSG", in: Skala V. (ed.): Journal of WSCG'04, 221-228, ISSN 1213-6972
In case of sluggish response of the user interface of Ayam (not accounting for long tree update operations) several things to increase drawing speed can be done:
"Hide"
in the "Tools"
menu.<Ctrl+d>
manually."UseMatColor"
.Due to the way Ayam is implemented, several restrictions and deficiencies exist:
"TclPrecision"
preference setting, however). Ayam user interface deficiencies:
Helping to make Ayam even better will spice up your life too! Here is how to do it:
Please do not implement custom objects like simple triangles or polygons. This would be something that really is not intended by the Ayam Team, and it would surely show the limits of the current design of all code operating on the scene structure.
Ayam objects should be high-level objects!
Reading the last paragraph you might think that we are a bit biased against polygonal models. We are not. Polygonal models are the only way to preview complex geometry using hardware accelerated graphics, for the moment. But even while RenderMan supports rendering of polygonal models, their use as a primitive is not recommended for good reasons. In other words, use polygonal models in the modeler as quick representation of your higher level objects, but please, if you are going to actually render something, do not use that polygonal representation. If you want to go a complete polygonal way instead, voila, there are good modelers out there.
Suggested reading:
WWW resources:
http://www.ayam3d.org/tut1/tutorial1.html
http://www.ayam3d.org/faq.html
http://www.renderman.org/
http://www.rendermanacademy.com/
First of all, I would like to express a big "Thank you!" to Bernd (Pink) Sieker. He is the first real Mops user and beta tester, who urged me during the last years via E-Mail and on IRC to fix this particular bug, add some essential features, move the lights again etc. pp. in countless iterations. Bernd, without your help I surely would not be that far, thanks!
Furthermore, I would like to thank the following people:
OpenGL (R) is a registered trademark of Silicon Graphics, Inc.
The RenderMan (R) Interface Procedures and Protocol are: Copyright 1988, 1989, 2000 Pixar All Rights Reserved
RenderMan (R) is a registered trademark of Pixar
The Affine Libraries and Tools are Copyright (c) 1995, 1996, 1997, 1998 Thomas E. Burge All rights reserved.
Affine (R) is a registered trademark of Thomas E. Burge.
TIFF Software is Copyright (c) 1988-1997 Sam Leffler Copyright (c) 1991-1997 Silicon Graphics, Inc.
Dime is Copyright (c) 1998-1999 Systems In Motion, SA All rights reserved.
AutoCAD (R) is a registered trademark of Autodesk, Inc.
DXF (R) is a registered trademark of Autodesk, Inc.