Aqsis User Manual

Table of Contents Introduction ...... 1 Rendering Images with Aqsis ...... 1 The Aqsis Command Line Renderer ...... 2 The Aqsl Shader Compiler ...... 6 The Teqser Texture Processor ...... 7 Asset Searchpaths ...... 9 Aqsis Options and Attributes ...... 10 Copyrights & Trademarks ...... 14 Licensing ...... 14

Introduction

Aqsis is a suite of tools for rendering 3D images. Aqsis uses the interfaces defined by Pixar as part of the Renderman® specification for communicating with other tools.

This document explains the basic use of the tools provided with the Aqsis suite. It is not intended to be an introduction or tutorial to Renderman®, readers are referred to the bibliography at the end of this document for material that is suited to this purpose.

The Aqsis suite consists of the following tools, the use of each tool will be described in detail in subsequent sections.

aqsis A command line renderer that accepts files in the RIB (Renderman® Interface Bytestream) format.

aqsl A compiler for shaders written in the RSL (Renderman® Shading Language) programming language.

teqser A program to process image maps for use in scenes rendered with Aqsis. Image maps pre-processed using teqser are in a format to allow Aqsis to maximise efficiency and quality.

aqsltell A program to interrogate compiled shaders (compiled with aqsl) and report the argument names and types that it accepts.

Rendering Images with Aqsis

The process of rendering 3D images with Aqsis involves a number of asset file types, including…

1 Aqsis User Manual

RIB files Scene description files in the Renderman® Interface Bytestream format. These files can be plain ASCII or binary encoded, and either format can be gzip compressed.

SL files Shaders in the Renderman® Shading Language format. These files need to be compiled into a form usable within Aqsis by the command line compiler aqsl.

Texture files Images used for texture mapping and shadowmapping. For maximum efficiency, these files should be pre-processed with the teqser tool. Aqsis can use plain TIFF files (and some other formats, depending on external plugins), but will not operate at maximum memory efficiency.

The Aqsis Command Line Renderer

Aqsis is the main tool of suite, responsible for combining the various assets and producing a final rendered image. It responds to a series of instructions in a RIB file, as described in the Renderman® Spec. The instructions in the RIB file will cause Aqsis to process other asset types, such as shaders and textures during the process of rendering.

The command line renderer is launched with a command line similar to the following…

aqsis [options] file.rib

where [options] can include the following command line options.

-version Display the version of Aqsis and exit immediately.

-help, -h Display a summary of the command line options, and the initial settings for various options, and exit.

-pause Wait for a keypress when rendering is complete before exiting.

-progress Print to the standard output a string identifying how far through the rendering process Aqsis is. The value displayed is a percentage of the total number of buckets rendered, and as such, does not indicate a completion level in terms of time. As a render progresses, different areas of the image may have more detail, resulting in slower rendering for those buckets. Aqsis will also output the duration of the render up to the current point, and an estimate of how long is still to go. This value is subject to the same limitations, i.e. the expected duration will change as the render progresses.

-Progress Print progress messages in a simplified format that is compatible with PRMan®, and more importantly, Alfred® from Pixar. Alfred® is a render scheduling tool that expects to see information on the standard output in a specific format in order to determine render progress, this option will ensure that Aqsis outputs this information.

-progressformat=string

2 Aqsis User Manual

Control the format of the string displayed if iprogress is enabled. This argument takes a string with various placeholders in it that will be replaced at runtime by Aqsis with calculated progress values. The possible placeholders are…

%p The current percentage complete, calculated as the number of completed buckets as a percentage of the total number of buckets.

%s The total number of seconds spent rendering so far.

%S The estimated number of seconds remaining.

%m The total number of minutes spent rendering so far.

%M The estimated number of minutes remaining.

%h The total number of hours spent rendering so far.

%H The estimated number of hours remaining.

%t The time spent rendering so far, formatted as hh:mm:ss.

%T The estimated time remaining formatted as hh::mm::ss.

%f The current frame number being rendered, as defined by the FrameBegin Ri request.

%% A literal % character.

-endofframe=integer Output statistics information after each frame. The verbosity of the information is controlled by the value passed.

• 0 = Just output the time for the frame, and the total time.

• 1 = Output additional information about the timings of various rendering processes.

• 2 = Output additional information about the processing of geometry and sampling during the rendering process.

• 3 = Output additional information about texture memory use and processing.

-nostandard Force Aqsis to not declare the standard Renderman® variable type names. By default Aqsis will pre-declare such things as "P", "N" etc. as used by default in many Ri requests. Specifying this option will override that behaviour, resulting in a completely clean parsing state.

Note

Be aware that enabling this option will mean that Aqsis by default will not recognise such

3 Aqsis User Manual

primitive variables as "P", the user will have to Declare these manually.

-verbose=integer, -v=integer Aqsis outputs various messages to the standard error stream. It uses a logging system to categorise these messages. This option allows you to control the maximum level of messages you will see.

• 0 = errors

• 1 = warnings (default)

• 2 = information

• 3 = debug

-renderinfo If this option is enabled, Aqsis will print out various information about the current render prior to rendering. This information includes resolution, sampling and filtering information.

Note

The information is output via the logging system as information level messages. So if the verbose level is <2, you will not see the information.

-type=string Force the Display type to the specified display mode. The possible values for this argument matches the possible types for the Display request, i.e. "file", "framebuffer", "shadow", or "zfile" by default. Any additional display types that you may have installed can be used as well.

-addtype=string As -type except instead of overriding any Display requests in the RIB file, this option will add to them. For example, if the RIB specifies output to a "file", using -addtype="framebuffer" will cause Aqsis to display the render to a framebuffer in addition to the file.

-mode=string If a -addtype or -type option is specified, this option will control the mode used for that display. The possible values for this argument match the possible arguments for the mode parameter of the Display request, i.e. "rgba", "rgb" etc.

-fb, -d This option is the exact equivalent of -type="framebuffer" -mode="rgb".

-crop x1 x2 y1 y2 This option allows you to specify a crop window. It is exactly equivalent to the CropWindow request. The values passed in are in NDC space, i.e. 0—>1. For example, to render the top left corner of an image specify -crop 0 0.5 0 0.5.

-frames f1 f2 Tell Aqsis to only render frames betwee (inclusive) f1 and f2.

4 Aqsis User Manual

-frameslist=string This is a more flexible option for controlling which frames are rendered from a RIB file with multiple frames. The value should contain a list of frame ranges, separated with a ,. Single numerical values specify a single frame, a range of frames can be specified by placing a - between the start and end frame number (inclusive). For example, to render frames 1, 2, 8 and 15 to 20, specify -frameslist="1,2,8,15-20".

-nocolor, -nc The log messages that Aqsis outputs, as controlled by the -verbose option, are normally color coded by their type, green for info, red for error, etc. This option will prevent that color coding. It may be useful to turn the color coding off if redirecting the log to a file, otherwise you will get all the color change control codes in the logfile.

-beep Force Aqsis to emit a console beep when each frame is rendered.

-res x y By default, Aqsis will render to the resolution specified in the Format request in the RIB (or to the Renderman® default of 640x480 if there is no Format request). This option allows the user to override this setting.

-option=string This is a catch all command line option. The value is a snippet of RIB, usually a Option level request, such as Format, PixelSamples etc. You can specify multiple -option arguments on the command line, each one will be processed in turn and parsed by the renderer as if they were placed just before the WorldEnd request. This allows you to override pretty much any option specified in the RIB file. For example…

-option="PixelSamples 2 2"

would set the pixel samples to 2x2 irrespective of what is specified in the RIB file.

-rc=string Specify the location of the .aqsisrc file used by the command line renderer as a configuration file. The file .aqsisrc is a plain RIB file and can contain any RIB requests, however, it is normal to specify only Option level requests. Particularly useful for specifying default searchpath locations for a particular installation.

-shaders=string Override the default shader searchpath, see the section called “Asset Searchpaths”

-archives=string Override the default archive searchpath, see the section called “Asset Searchpaths”

-textures=string Override the default texture searchpath, see the section called “Asset Searchpaths”

-displays=string Override the default display searchpath, see the section called “Asset Searchpaths”

-dsolibs=string Override the default dso searchpath, see the section called “Asset Searchpaths”

-procedurals=string 5 Aqsis User Manual

Override the default procedural searchpath, see the section called “Asset Searchpaths”

-plugins=string Override the default plugin searchpath, see the section called “Asset Searchpaths”

The Aqsl Shader Compiler

Aqsis supports programmable shaders in the Renderman® Shading Language format. Shaders are supplied as text files in RSL, and need to be compiled into a custom format that Aqsis can execute during rendering. Aqsis comes with a tool called aqsl that compiles RSL shaders into .slx files that the shader virtual machine in Aqsis can process.

The compiler is launched with a command line similar to the following…

aqsl [options] file.sl

which will by default, result in a compiled shader file in the same location. The compiled shader has the name of the shader with an extension of .slx. Note

The shader name is not necessarily the same as the shader source file name. The default name of the compiled shader file is defined by the shader definition in the source file.

Command line [options] to aqsl include…

-version Display the version of aqsl and exit immediately.

-help, -h Display a summary of the command line options and exit.

-o name This allows you to override the output name and location of the compiled shader. name should be a fully qualified file name. The compiled shader will be written to that file. Warning

If the extension of the file is not .slx Aqsis will not be able to find the shader at render time.

-ipath, -Ipath The RSL allows for the inclusion of external header files. Normally, aqsl will look for these in the same location as the shader source file. This option allows you to specify additional locations to look for header files. You can specify this option multiple times to provide many additional search locations.

-Dsym[=value] Define a preprocessor symbol with an optional value. The preprocessor built into aqsl can perform conditional compilation and macro expansion based on such definitions.

6 Aqsis User Manual

-Usym Undefine a preprocessor symbol. This allows you to undefine a default symbol. The default symbols are listed in Table 1, “Default Preprocessor Symbols”

Table 1. Default Preprocessor Symbols

NameValue PI 3.141592654 AQSIS

The Teqser Texture Processor

Aqsis can utilise bitmap images during rendering for various uses. It is able to use normal TIFF images, or various other formats via TIFF conversion plugins. However this does not result in the most efficient use of memory during rendering. Aqsis processes bitmap images by creating a MIPMAP of the image to make high quality sampling efficient during rendering. This increases the size of an image in memory by a third.

Aqsis uses a least recently used system for caching image data. That is, if the designated cache area for textures exceeds its limit, Aqsis will try to dump the least recently used image data from the cache, to allow room for other texture data to be loaded. If a plain TIFF bitmap is used during rendering, the whole image is loaded, and MIPMAPped into the cache. This takes a large amount of cache memory, and can only be removed as a whole, meaning that if the texture is again needed later during rendering, the MIPMAPping process needs to be repeated.

To avoid this situation, teqser pre-mipmap's the images, but more importantly, converts them to a tiled format. Aqsis will only load the tiles that it needs into the cache, and individual tiles can be removed from the cache as they become redundant. This makes for much more efficient rendering, as such it is recommended that all bitmap images be converted using teqser.

Teqser is launched with a command line similar to the following…

teqser [options] infile.tiff outfile.tx

Command line [options] to teqser include…

-version:: Display the version of teqser and exit immediately.

-help, -h Display a summary of the command line options and exit.

-compression=string When writing the resulting output file, this option controls any compression applied. As Aqsis uses the TIFF format to store its MIPMAPped files, any valid TIFF compression format is accepted, i.e. none, lzw, packbits, deflate.

7 Aqsis User Manual

-quality=float When -compression is used, this option controls the quality for those compression methods that support it.

-envcube px nx py ny pz nz Aqsis can use two types of environment map as required by the Renderman® spec., cubeface, and latlong. This option tells teqser to produce a cubeface environment map. The 6 bitmaps that make up the faces of the cube are provided as parameters to this option, px is the image to apply to the positive x face of the cube, nx, applies to the negative x face, and so on.

-fov=float This option only applies when creating a cubeface environment map using the -envcube option. The image for each face is normally presumed to cover an angle of 90 degrees, however, increasing this value results in some overlap of the images, which can reduce sampling errors at the corners of the cube.

-envlatl This option produces a latlong type environment map. The resulting texture file is a plain MIPMAPped file, with an identifier embedded to mark it as having been prepared as a latlong environment map. This is to support possible future optimisations to the handling of latlong environment mapping. Therefore, although any image can be used as a latlong environment map, it is recommeded to pre-process images using teqser with this option for latlong environment mapping.

-shadow For historical reasons, the zfile display driver will produce a proprietary binary format depth file. This option will tell teqser to convert such a depth file into a shadowmap which can be used by the RSL shadow() commands. Note

It is recommended to use the shadow display driver to produce shadow maps, as it produces a usable shadow map directly, therefore negating the need for additional conversion steps.

-swrap=string, -smode=string see the section called “Texture Wrapping Modes”

-twrap=string, -tmode=string see the section called “Texture Wrapping Modes”

-wrap=string, -mode=string see the section called “Texture Wrapping Modes”

-filter=string When creating the various levels of the MIPMAP, Aqsis will need to filter the data from the image to produce a lower resolution representation. This option controls which filter kernel will be used during this downsampling. Options are…

• "box"

8 Aqsis User Manual

• "bessel"

• "catmull-rom"

• "disk"

• "gaussian"

• "sinc"

• "triangle"

-swidth=float This controls the width of the downsampling filter in the s direction. See also -filter

-twidth=float This controls the width of the downsampling filter in the t direction. See also -filter

-width=float This controls the width of the downsampling filter in both directions. See also -filter

-bake=float This option is specific to the conversion of bake files as output by the custom RSL bake() command. It controls the final resolution of the bitmap that represents the baked data.

-resize=string This option is not used, it is included purely for compatibility with existing similar tools from other Renderman® toolsets.

Texture Wrapping Modes

When Aqsis samples information from a bitmap texture, it needs to know what to do should the requested coordinates lie outside the texture area. It can do one of 3 things.

1. Return black or zero, depending on the type of information being returned from the texture RSL command. This mode is called black.

2. Wrap the texture coordinates round to the opposite side of the texture. This is called periodic, and has the effect of tiling the texture.

3. Clamp the texture coordinates to remain within the valid range. This has the effect of repeating the last color in the given direction for all out of range values. This mode is called, unsurprisingly, clamp.

Asset Searchpaths

To locate the various external asset files that it needs during rendering, Aqsis uses a Renderman® custom option called "searchpath". This contains a number of parameters, each one describing a set of paths in which to look for specific types of asset. The paths are separated in the string by a ":" or ";" character, we recommend using the ":" character as this is more commonly used in other implementations.

9 Aqsis User Manual

Aqsis will accept full Windows style drivespecs such as C:\Path without the ":" causing any problems, it can recognise the use of ":" as a drive identifier as opposed to a path separator.

Aqsis will accept path specifications using either forward slash "/", or backslash "\" separation on Windows, so it is recommended to use forward slash "/" for maximum portability of content.

Aqsis will recognise the "&" character and replace that with the previous contents of the "searchpath" parameter allowing you to modify a searchpath, rather than overwrite it. This is particularly useful, as the command line renderer will set these searchpaths to sensible defaults based on the installation of Aqsis, to allow it to locate the default assets provided with the installation. For example, to add a path to the "searchpath" for shaders use the following form…

Option "searchpath" "shader" ["/my/shader/path:&"]

The recognised parameters for the "searchpath" option are as follows…

"shader" The searchpath used to locate compiled shaders during rendering.

"archive" The searchpath used to locate archive files, i.e. RIB files included into another via the ReadArchive request.

"texture" The searchpath used to locate all texture related files, including shadow maps and environment maps.

"display" The searchpath used to locate display drivers, including the displays.ini configuration file.

"dsolibs" The searchpath used to locate Dynamic Shade Ops, these are dynamic libraries that provide custom shading language functionality.

"procedural" The searchpath used to locate procedural plugins by the Procedural request.

"plugin" The searchpath used to locate plugin image handlers. These are custom dynamic libraries that allow Aqsis to use textures in formats other than TIFF and its own custom format produced by teqser.

Aqsis Options and Attributes

Aqsis supports various options and attributes via the RiOption and RiAttribute functions. These allow the user to control the behaviour of the renderer in various ways.

Options apply to the scene/render as a whole, they are generally used to provide global settings to the renderer. Options are fixed and cannot be modified after the RiWorldBegin function is called, so all options should be set prior to that call.

Attributes are stored as part of the changing graphics state. They are stored and restored with RiAttributeBegin/End, and RiTransformBegin/End. There effect on the scene is localised to the attribute

10 Aqsis User Manual

block they exist within. Options

Option "limits" "integer gridsize" [256] Option "limits" "integer[2] [16 16] bucketsize" Option "limits" "integer eyesplits" [10] Option "limits" "integer [number of buckets in a row] bucketmodulo" Option "limits" "color zthreshold" [1.0 1.0 1.0] Option "limits" "integer [8192] texturememory" Option "shadow" "float bias0" [0] Option "shadow" "float bias1" [0] Option "shadow" "float bias" [0] Option "shutter" "float offset" [0] Option "statistics" "integer [0] renderinfo" Option "statistics" "integer [0] endofframe" Option "texture" "integer lerp" [0]

Grid Size The gridsize option controls the maximum number of micropolygons a primitive will split into. This allows the user to control the amount of memory a render will use. Increasing this number will increase the number of micropolygons that could potentially be in memory at any one time for sampling. The counter argument for larger grid sizes is that the shader system can more efficiently shade larger grids as it takes advantage of the coherence of large groups of microplygons.

By default the value is "limits" "gridsize" [ 256 ]

Bucket Size Aqsis splits the image into rectangular sections known as buckets for rendering. This gives memory and performance benefits, each bucket is rendered in turn, and all the surfaces, micropolygons and image data that is generated for a bucket is released before moving to the next, this reduces the amount of memory required during rendering, particularly for high resolution renders. The bucketsize option controls the size of the buckets in pixels.

By default the value is "limits" "bucketsize" [ 16 16 ]

Eyesplits

11 Aqsis User Manual

The number of times Aqsis will attempt to split primitives that intersect both the near clipping plane and the eye plane. In order to work on only one bucket-worth of data at a time, Aqsis splits geometric primitives that are passed to it. In this process, any primitives that lie entirely outside of the viewing volume are culled. Unfortunately, problems may arise with primitives that span both the near clipping plane of the camera and the eye plane. These primitives should appear in the scene, because they span the near clipping plane and therefore are partly within the view of the camera. However, because they also span the eye plane, they are partly behind the eye (or camera) and therefore cannot be projected into the 2D space of the image for rendering. Aqsis will try to further split such primitives until all that remains are primitives that span only the near clipping plane and not the eye plane. However, in some cases, this cannot be done, and the renderer must discard the offending geometry. The number of times that the renderer will try to split the primitives that span the eye plane is given by the "eyesplits" option. If the number of eyesplits is exceeded then a warning will be produced. If this warning appears, several steps can be taken:

1. Place the near clipping plane further away from the camera.

2. Avoid using a "worm's eye view" of the scene, and place the camera more realistically. A real camera cannot have geometry that intersects its lens.

3. Increase the eyesplits value. Note, however, that increasing the eyesplits value can dramatically increase the number of geometric primitives that the renderer must handle, and can lead to excessive rendering times as a result.

By default the value is "limits" "eyessplits" [ 10 ]

Bucket Modulo (Microsoft Windows Only) Controls the frequency of calls to control virtual memory under Windows. While rendering, Aqsis (together with all of the other running processes) may consume more memory than the computer has available as RAM. This is a normal phenomenon, and the solution is that the Operating System (OS) will store some of the memory on disk as a swap file. In order to access the memory stored on disk, it must be paged off the disk by the OS and back into RAM. The paging operation slows Aqsis because accessing a disk is slower than accessing RAM. Aqsis periodically requests the OS to allocate as much memory as possible in RAM (called the working set of Aqsis), to try to minimize the amount of paging. By default, it does this at the end of every row of rendered buckets, but this can be changed using the "bucketmodulo" option. "bucketmodulo" is the number of buckets between requests to use the largest working set. So, for example, a "bucketmodulo" value of 3 will make a request about the working set after every 3rd bucket has finished rendering. This option is ignored on non-Windows platforms such as Linux and OSX.

By default the value is "limits" "bucketmodulo" equal to number of X buckets

ZThreshold This option is used when rendering shadow maps or other depth based files. It controls the level of opacity above which samples are included in such files. The default value of [1 1 1] means that no semi-transparent surfaces will appear in shadow maps. A value of [0.7 0.7 0.7] would mean that all samples with an opacity value greater than 0.7 in all channels will appear in a shadow map. This capability is useful for rendering shadows of objects whose shape is defined by an opacity map or function.

12 Aqsis User Manual

By default the value is "limits" "zthreshold" [ 1.0 1.0 1.0 ]

Texture Memory The amount of memory used for caching textures (measured in kB; 1 kB = 1024 bytes). Textures in Aqsis are stored in a cache so that the time spent loading them is minimized. If it happens that loaded textures have to be larger than the specified "texturememory" by necessity, then the renderer will still function correctly, but the effectiveness of the cache will be reduced.

By default the value is "limits" "texturememory" [ 8192 ]

Shadow Bias When using shadow maps, a surface may exhibit self-shadowing. This problem is caused by precision errors and quantization and appears as gray spots on the surface. This problem occurs when the distance of an object to a light source computed while rendering a shadow map is slightly less than the distance computed while rendering the image. To prevent self shadowing, specify a bias, which is a value that is added to the shadow map value. If `bias0' is different from `bias1', the renderer chooses a random value between them for each sample. The value of `bias0' and `bias1' should be set to `0' if the "midpoint" algorithm is used to compute the shadow map, see Options for more details on how to use the "midpoint" algorithm.

By default the value is "shadow" "bias0" [ 0.0 ] By default the value is "shadow" "bias1" [ 0.0 ] By default the value is "shadow" "bias" [ 0.0 ]

Shutter Offset An offset added to the shutter opening time when shading. When setting shutter opening and closing times, it is useful to set these times relative to the current frame (for example: RiShutter(0.2, 0.8)) rather than relative to the entire animation (eg: RiShutter(10.2, 10.8) for the 10th frame). This allows archives of motion-blurred material to be reused more easily. The disadvantage of frame-relative shutter timing is that any shaders which rely on the time variable will no longer have access to the correct time. This problem is overcome by setting the shutter offset option, which adds a constant offset to the time variable in shaders. The time that the shader will see is the offset plus the shutter opening time. The offset only applies to RiShutter calls that follow the declaration of the offset.

Statistics Output Aqsis can provide statistics about the rendering. The "renderinfo" flag functions as a boolean that switches the printing of initial rendering setup on or off (any non-zero value is true, while zero is false). "endofframe" controls the level of verbosity of statistics for processes that occur mostly during rendering itself (as opposed to initial setup). It can take on any value from 0 to 3 inclusive, where increasing values are increasing verbosity. "renderinfo" data is printed to stderr while "endofframe" data is printed to stdout.

Texture Lerp

13 Aqsis User Manual

Textures are filtered with either bilinear or trilinear mip-mapping. Trilinear gives higher image quality but takes a bit more time. To enable trilinear mip-mapping for the entire scene: Option "texture" "integer lerp" [1.0] Setting lerp to anything non-zero enables the trilinear mip-mapping option. Individual texture accesses may request bilinear or trilinear mip-mapping, but setting the lerp option to 0.0 will override. lerp is equivalent to "enable lerp" of RDC renderer. By default trilinear sampling is not enabled.

By default the value is "texture" "lerp" [ 0 ]

Copyrights & Trademarks

Aqsis uses some third party libraries and tools, their respective copyrights are detailed below.

libtiff The TIFF I/O library used by Aqsis is Copyright © 1988-1997 Sam Leffler, Copyright © 1991-1997 Silicon Graphics, Inc. It is freely available and can be downloaded from the libtiff site http://www.libtiff.org.

libjpeg The JPEG I/O library used by Aqsis is produced by the Independent JPEG Group [http://www.ijg.org] and is Copyright © 1991-1998, Thomas G. Lane. It is freely available and can be downloaded from the IJG site http://www.ijg.org.

Renderman® The Renderman® Interface Procedures and Protocol are: Copyright 1988, 1989, 2000, Pixar All Rights Reserved

Licensing

The Aqsis suite is Copyright © 2000 Paul C. Gregory

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

14