====== Frequently Asked Questions ======
Answers to common question regarding the Aqsis suite of tools.
Before editing/submitting any content be sure to read the information on the [[:index|Index]] page first.
===== Questions =====
==== 1. General ====
* 1.1: [[faq:index#1.1whatisaqsis|What is Aqsis?]]
* 1.2: [[faq:index#1.2whyuseaqsis|Why/when should I use Aqsis over my current renderer?]]
* 1.3: [[faq:index#1.3aqsisversionnumbering|What is the difference between the 'Odd' and 'Even' Aqsis release numbers (like 1.0/1.1)?]]
* 1.4: [[faq:index#1.4scanlinevsraytracing|What is the difference between scanline rendering and raytracing?]]
* 1.5: [[faq:index#1.5moreinformationonrenderman|Where can I find more information about RenderMan?]]
==== 2. Tools ====
* 2.1: [[faq:index#2.1whatismaxeyespliterror|What does the error message "Max eyesplits for object ??? exceeded" mean?]]
* 2.2: [[faq:index#2.2whydoesaqslgivesyntaxerroronshaders|Why does Aqsl give "...l : 1 : syntax error" on any shader?]]
* 2.3: [[faq:index#2.3whydoesaqsissegfaultorgivebuserrors|Why does Aqsis segfault or give "bus error" when run on the examples rib files?]]
==== 3. Primitives ====
* 3.1: [[faq:index#3.1whatisrisubdivisionmeshnon-manifolderror|What does the error message "RiSubdivisionMesh contains non-manifold data" mean?]]
==== 4. Libraries ====
* 4.1: [[faq:index#4.1whatiswindowsri2rib.lib__imp_error|When I link against ri2rib.lib under Windows I get lots of undefined references to __imp_???]]
* 4.2: [[faq:index#4.2fedorarelocerror|When running aqsis I get ".../libaqsis.so: cannot restore segment prot after reloc: Permission denied"]]
==== 5. Other ====
* 5.1: [[faq:index#5.1reducerendertime|How can I cut my render-times?]]
===== Answers =====
==== 1. General ====
=== 1.1 What is Aqsis ===
Aqsis is an Open Source implementation of the Renderman(r) standard.
[[doc:renderman|Renderman]](r) is a standard defined by [[http://www.pixar.com|Pixar]] to define a method of communications between modelling/animation software and renderers. It is designed to be rendering technology agnostic.
Aqsis implements all the required features of the [[doc:renderman|Renderman]](r) standard, and some of the optional features. It is a fully functional [[doc:reyes|Reyes]] (a scanline rendering algorithm) renderer. It supports procedural
shaders in the Renderman Shading Language ([[doc:rsl|RSL]]) format, via the shader compiler aqsl, one of the suite of tools that makes up the Aqsis toolset.
=== 1.2 Why use Aqsis ===
* Aqsis is Open Source \\ Therefore, not only is it free to use, but you can make modifications yourself if it doesn't quite fit your specific requirements.
* Aqsis is based on [[doc:renderman|RenderMan]](r) \\ The basis on which Aqsis is built has a long history of use in all area's of the CG industry. Through its [[doc:renderman|RenderMan]](r) heritage, it provides some key features that are important particularly in high end CG production, such as [[doc:dof|depth of field]], [[doc:mb|motion blur]] and [[doc:rsl|programmable shading]].
=== 1.3 Aqsis Version Numbering ===
'Odd' numbers (like 1.1 and 1.3) denote a development/testing release of Aqsis, while 'Even' numbers (like 1.0 and 1.2) denote a stable, production-ready release.
=== 1.4 Scanline vs Raytracing ===
Although there are many different rendering methodologies, the
two most common are [[doc:rt|Raytracing]] and Scanline. In fact, both
names actually describe ''classes'' of rendering.
| ^ Raytracing ^^ Scanline ^^
| ^ Pros ^ Cons ^ Pros ^ Cons ^
^ Advanced Lighting | Possible | Slow | More design control | Need to cheat |
^ Shadows | Easy | Slower, less control | Faster, more control | Need separate pass |
^ Reflection/Refraction | Easy | Slower, less control | Faster, More control | Need separate pass |
^ Geometry | | Requires more memory | Requires less memory | |
=== 1.5 More Information on RenderMan ===
There are lots of places on the Internet where you can find
RenderMan-related information. Here are some specific links
we can recommend. There are many others.
== General resources ==
* [[http://www.renderman.org|The RenderMan Repository]]
* [[http://www.rendermanacademy.com|RenderMan Academy]]
* Steve May's [[http://accad.osu.edu/~smay/RManNotes/rmannotes.html|RenderMan Notes]]
* [[https://renderman.pixar.com/products/rispec/index.htm|The RenderMan Interface Specification]] from Pixar
== RIB file syntax ==
* [[http://www.siggraph.org/education/materials/renderman/pdf_tutorial/poets.pdf|RenderMan for Poets]], by Larry Gritz
== SL and shaders ==
* Malcolm Kesson's [[http://www.fundza.com/|RenderMan resources]]
==== 2. Tools ====
=== 2.1 What is "Max Eyesplit" Error ===
Aqsis is based on the [[doc:reyes|Reyes]] image rendering system. This system works by splitting surfaces repeatedly until they are within certain size constraints, then dicing these small surfaces into micropolygons that are then rendered.
The process of splitting the surfaces requires that Aqsis determine the on-screen size of the surface. This can only reliably be done for surfaces entirely in front of the camera. If a surface is entirely behind the camera, it is discarded. However, if a surface spans the camera plane, it cannot be easily dealt with. So Aqsis will split it until it is either entirely in front, or entirely behind. This is called an eyesplit, because the split has been forced due to the surface crossing the eye plane. Sometimes, no matter how many times a surface is split, part of it will still cross the eye plane. When this happens, Aqsis has to bail out to avoid entering an infinite loop. When this happens it reports it has hit the max eyesplits limit for this surface. The remainder is then discarded.
The best way to avoid this error is to not have surfaces that pass across the camera plane.
If you find Aqsis seems to have stalled when rendering, it could be that it is creating large amounts of eyesplits. To overcome this you can tweak the point at which Aqsis bails out. To do this add a line like...
Option "limits" "eyesplits" [n]
where n is the number of times Aqsis will split a surface due to crossing the eye plane. The default is 10. If you set it too high, render times will soar, too low and you will start to lose some surfaces as they get discarded. Note that this number means that Aqsis will do 2^10 eyesplits (1024), so you should be really careful with it (exponential behaviour!).
=== 2.2 Why Does Aqsl Give Syntax Error on Shaders ===
This problem is caused by having a version of [[http://www.gnu.org/software/flex|Flex]] which is too recent. [[http://www.gnu.org/software/flex|Flex]] 2.5.4, and some earlier version, are known to work. Many distributions now ship 2.5.31, this release breaks the [[doc:rsl|SL]] parser in aqsis. It is not known at this time as to why.
Debian has a ''flex-old'' package which fixes this.
=== 2.3 Why Does Aqsis Segfault or Give Bus Errors ===
When compiling aqsis, check to see if you see error messages saying...
../../../../boost/boost/config/compiler/gcc:hp:81:7: warning: #warning "Unknown compiler version - please run the conigure tests and report the results"
These errors indicate that the [[http://www.boost.org|Boost]] headers you are using are not compatible with your compiler. For version of aqsis less that 1.1 we shipped a set of [[http://www.boost.org|Boost]] headers, these may be too old to work with your compiler. Rather than using the [[http://www.boost.org|Boost]] headers we shipped you can install it yourself and configure aqsis with...
./configure --with-boost-include=/usr/include
...being sure to give the correct path to [[http://www.boost.org|Boost]].
==== 3. Primitives ====
=== 3.1 What is RiSubdivisionMesh Non-Manifold Error ===
[[doc:sds|Subdivision]] meshes rendered with the [[doc:glossary|Catmull-Clark]] scheme need to follow some topological rules. The main rule is that the surface must be manifold. In essence this means that it must be possible to 'unfold' the surface of the mesh and end up with a single flat surface that doesn't cross itself.
More specifically, there are two common cases where a mesh can be non-manifold. If a single edge in the mesh is shared by more than two faces, or if a point is shared by two faces that don't share an edge. As illustrated below.
{{faq:non-manifold.png?320}}
So if you see the non-manifold error message, check your meshes carefully for any instances of those two cases.
==== 4. Libraries ====
=== 4.1 What is Windows ri2rib.lib "__imp_" Error ===
Under [[http://www.microsoft.com|Windows]], ri2rib can be used in one of two ways...
* As part of aqsis.dll complete with all the rendering functionality.
* As a standalone static library ri2rib.lib for use in thirdparty applications.
In the first case, the Ri* calls all need to be exported from the DLL so that applications linking agains aqsis.dll can see them. In the second case, the library is static, so they don't need to be.
To accomodate this dual system, the ri.h header file has a preprocessor macro defined AQSIS_STATIC_LINK to control whether to use %%__declspec(dllexport)%% to mark the functions as exported from a DLL. So if you are using ri2rib.lib as a static library, declare this #define to avoid the %%__imp_Ri*%% errors.
=== 4.2 When running aqsis I get ".../libaqsis.so: cannot restore segment prot after reloc: Permission denied" ===
When running under Fedora Core 5 with SELinux policies being enforced (and possibly other SELinux enabled distibutions), the build system does not set the correct context for the shared libraries and leaves them in the users standard context. Which basicaly means that they might look like libraries, but SELiunux wont let them be used as libraries.
To fix this run...
chcon -t texrel_shlib_t output/bin/*.so
No doubt the context name is different for other disutributions. Using lib_t doesn't seem to work, check the context of anything you have built yourself (e.g. ls -Z /usr/local/lib). Other sites suggest disabling SELinux, but we don't.
==== 5. Other ====
=== 5.1 Reduce Render Time ===
???