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 page first.


1. General

2. Tools

3. Primitives

4. Libraries

5. Other


1. General

1.1 What is Aqsis

Aqsis is an Open Source implementation of the Renderman® standard.

Renderman® is a standard defined by 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 Renderman® standard, and some of the optional features. It is a fully functional Reyes (a scanline rendering algorithm) renderer. It supports procedural shaders in the Renderman Shading Language (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 RenderMan®
    The basis on which Aqsis is built has a long history of use in all area's of the CG industry. Through its RenderMan® heritage, it provides some key features that are important particularly in high end CG production, such as depth of field, motion blur and 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 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
RIB file syntax
SL and shaders

2. Tools

2.1 What is "Max Eyesplit" Error

Aqsis is based on the 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 was caused in some previous releases by having a version of Flex which was too recent. Flex 2.5.4, and some earlier version, were found to work in these cases. The culprit was flex 2.5.31, which seemed to break the SL parser in aqsis. It is not known at this time as to why, and the problem seems to have disappeared with more recent versions of Aqsis and flex (flex version 2.5.35 is known to work for Aqsis 1.6.0).

Debian has a flex-old package which fixes this problem if you still run into it.

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 Boost headers you are using are not compatible with your compiler. For version of aqsis less that 1.1 we shipped a set of Boost headers, these may be too old to work with your compiler. Rather than using the 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 Boost.

3. Primitives

3.1 What is RiSubdivisionMesh Non-Manifold Error

Subdivision meshes rendered with the 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.

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 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 ".../ 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 distributions. 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


Personal Tools