Aqsis User Manual Introduction Rendering Images with Aqsis
Total Page:16
File Type:pdf, Size:1020Kb
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