R E A D M E
-----------

G & RT RI :

Geometry & Rendering Tools 
RenderMan Interface Lua Binding Module.

Current Version 0.2 see CHANGES for differences between older versions

This Lua module provides a RIB (RenderMan Bytestream) 
outputter following Pixar's RenderMan Interface(tm) Spec
version 3.2.

EXAMPLES

For examples see bin/ritest.lua, additionally see interfcae/interface.lua
for the full supported spec plus some additional functions.

KNOWN LIMITATIONS

There currently is no attribute checking on the input, at this
point the module relies on checking user input further down
the pipeline, ie. when rendering. This again will be addressed
before version 1.

There is limited testing. Later versions will include an automated
testing suite of lua scripts which as well as provide testing will
also prove to be useful for documentation and examples.

At present there is no easy method of adding custom functions to the
interface. 

No build for other platforms besides UNIX-like.

SUPPORTED ENVIRONMENTS

As of this release only UNIX-like operating systems are supported
out of the box via the scons build system. 

A Windows build should be possible with the current codebase, abiet 
with some modifications for building dynamic object libraries and
a build system for this platform is required. However this should
not be a difficult job to undertake. 

Later versions will have a build system in place for Windows OS. 
Also a Makefile based system is penned for the next release.

If anybody produces a new build system for this code for any
platform then please let us know so that we can offically 
support that platform.

BUILDING


You will also require Lua 5.1+ and the scons build environment.
The build is simple enough for you to build from a more traditional
makefile. A makefile will be provided for in a later version. 

In summary: 

+ Lua (5.1 +)
+ scons (any version)

The module provides a build shell script. src/rib.h and src/rib.cpp
are automagically generated in the build script. If you build manually
ie. call scons rather then use the build script, please ensure these
two source files are present. If not, take a peek at the build script
to find out how to generate them. 

ADDING INTERFACE COMMANDS

If you need to add a new Lua function to the interface you need to add an 
entry in interface/interface.lua (see for examples) and then re-generate the 
interface code (see above for details).

TESTING

There is a short test script called ritest.lua in the bin directory, a
second script ritest_co.lua has the same ri content but shows how to
implement it as two coroutines.  

The examples are abit specific at the moment due to laziness. They are known
to work under Pixie. The shaders required will need compiling for different 
renderers and are found under bin/shaders. 

INSTALLING

This should be as simple as copying bin/grt_ri.so into the module path for
Lua. Place in the Lua install directory for localling to your scripts.
See Lua Module Documentation if unsure. 

PROBLEMS

Then please feel free to tell us about them at http://www.luaforge.net/projects/grt.