====== Support Library Documentation ======

===== RIB Client Library (ri2rib) =====

==== Windows ====

=== Version 1.0 (stable) ===

There are three versions of the library provided as part of the developer install for the 1.0.x stable release.

  * Static_MT
  * Static_ST
  * Dynamic (default)

Each of these is linked against a different Microsoft runtime library, the choice of which to use will be driven by any external requirements. For instance if you are using another thirdparty library that is only available in one //flavor//, then you should use the same one from Aqsis to ensure the use of a common runtime throughout your product. The choice of runtime library is made in the //Code Generation// section of the //C++// pane in the project settings dialog.

{{:dev:codegen.png|Code Generation}}

The libraries supplied as part of the developer installer are all built using Microsoft Visual C++ 6.0, if you need the libraries for a different version of the tools, you will need to build them from source.

To link with //ri2rib// you will also need a suitable version of the **zlib** library, the source and binaries for this are available from [[http://www.zlib.net|here]].

To compile, you will need to ensure that Visual Studio can find the Aqsis header files, these are in the //include// folder in the location that you installed Aqsis to, by default **C:\Program Files\Aqsis\include**. You will also need to define a macro to inform the Aqsis headers that they are being used in the context of a static library (the ri2rib library is static, whereas the aqsis library is dynamic, but both use the same headers). In the //Preprocessor// section of the settings, set the following macro...

  * AQSIS_STATIC_LINK

...it doesn't need to be set to anything, as long as it is there. In your main file you will need to include the **"ri.h"** file to get access to the RenderMan API function.

{{:dev:preprocessor_settings.png|Preprocessor}}

To link a program with the //ri2rib// library you will need to add the following libraries to your link options in Visual Studio...

  * ri2rib.lib
  * zlib.lib

...and make sure that Visual Studio knows where to find the libraries. Remember the link path depends on the runtime library you have chosen, here the runtime is //Multithreaded DLL// so the lication is the //lib// folder, by default **C:\Program Files\Aqsis\lib**. If you are using //Multithreaded// in the code generation pane, choose the **lib\Static_MT** folder, if using //Single-Threaded// use **lib\Static_ST**.

{{:dev:link_settings.png|Link Settings}}

<note>
If linking with the debug runtimes, append **_d** to the library name, i.e. ** ri2rib_d.lib**, all other settings remain the same.
</note>

A simple Visual Studio 6.0 project that illustrates these steps can be found {{:dev:ri2rib_sample.zip|ri2rib sample project}}

=== Development Version ===

//To be defined//

==== Linux ====

=== Version 1.2 ===

Version 1.2 of aqsis provides a shared library (libri2rib.so) to perform
conversions from RI calls to RIB text.

To link with libri2rib, 
  - You need to specify the correct library and include search paths when compiling
  - The libri2rib must be in the dynamic linker path when running the resulting program.

The first one of these is all you need to worry about if you or your package
manager has installed aqsis in a standard place.  In the following, we assume
that aqsis has been installed into the /usr/local heiarchy (note that package
managers usually will install into /usr).

Suppose our program looks like the following (main.c):
<code c>
#include "ri.h"

int main(int argc, char** argv)
{
  RiBegin(RI_NULL);

  RiFormat(320, 240, 1.0f);
  RiDisplay("ri2rib_test", "framebuffer", "rgba", RI_NULL);
  RiTranslate(0.0f, 0.0f, 3.0f);

  RiWorldBegin();
  RiSphere(1.0f, -1.0f, 1.0f, 360.0f, RI_NULL);
  RiWorldEnd();

  RiEnd();
}
</code>

== Compiling ==

To compile our program with gcc, run the following at the command line:
<code>
gcc -o ri2ribtest main.c -I/usr/local/include/aqsis -lri2rib
</code>

== Running ==

If aqsis is installed in /usr/local, you should be able to run the command
<code>
./ri2ribtest 
</code>
from the compilation directory, and you should see the output on stdout.

Neat trick: to get aqsis to //render// the output, just use a pipe:
<code>
./ri2ribtest | aqsis
</code>


== Makefile and example ==

A project consisting of a makefile and main.c is available {{dev:ri2rib_eg_linux.tar.gz|here}}.

In the case that you've installed aqsis in a non-standard location (like your
home directory) you'll need to pull a few extra tricks to get the linker to
find libri2rib.so at compile and runtime.  Examine the Makefile above for the
necessary compile options.

==== OSX ====

//To be defined//