RenderMan SDK

Introduction

The RenderMan Software Developers Kit (SDK) is a collection of interfaces that allows users of RenderMan to extend the capabilities of the software in many varied and powerful ways. This document will provide an overview of each of the interfaces and detail how the SDK can be used on each of the platforms that supports Pixar's RenderMan.

There are two categories of interfaces in RenderMan: the first is plugins and the second is stand-alone applications. With plugins the interface can be bidirectional, meaning that the plugin will be expected to provide an entry point for the renderer to call into and the plugin can also make calls into entry points exposed by the renderer. Stand-alone programs will always simply make calls into entry points exposed by the renderer.

This is why providing a shared library that supports all the needs of the plugin interfaces and the stand-alone applications has great appeal. With a shared library, the executable prman simply loads the shared library at runtime and all plugins resolve their exported entry points against the shared library. Stand-alone programs can also resolve against the same shared library and can even embed the RenderMan renderer themselves. (A good example of this is the prman_for_python extension.) The downside of this is that stand-alone programs will now have to load the dynamic runtime library; however, all operating systems provide many mechanisms to meet this requirement and it is a small price to pay for the added flexibility it affords.

Plugin Interfaces

The following interfaces are only valid when used in the context of a plugin that is loaded by prman. Some of the calls could potentially be made by a standalone program, but for the most part they rely on some context provided by the renderer itself once it loads a plugin.

• Display Drivers
• RSL
• Implicit Field
• Rif
• Procedural Geometry
• Rx
• Rix

Application Interfaces

The following interfaces can be used in a stand-alone program outside the context of the renderer. However, this does not prevent plugins from utilizing these interfaces. For example, it might be very desirable to access a deep texture map within an RSL plugin.

• Slo Library
• RIB
• Pointclouds
• Brickmaps
• Deep Texturemaps
• Ri Control

Compiling Plugins

Compiling and using a new plugin requires three steps:

1. Compiling the C++ file that contains your plugin functions.
2. Compiling the shader that uses your functions.
3. Rendering a frame.

Compiling your C++ file is straightforward: just use the standard C++ compiler to generate an object (.o/.obj) file, then generate a shared object (.so/.dll) file from the object file. Remember that, though using C++, you must use C style linkage. You also must ensure that your C++ compiler and libraries are compatible with the compiler and runtime libraries used by PRMan (gcc for Linux and OS-X and Microsoft Visual C for Windows).

Plugin authors can confirm the compiler/library versions for the intended version of PRMan by running:

prman -version

Here are example commands for building a plugin on several architectures:

Linux

g++ -fPIC -I$RMANTREE/include -c myfunc.cpp
g++ -shared myfunc.o -o myfunc.so

Mac OS-X

g++ -I$RMANTREE/include -c myfunc.cpp
setenv MACOSX_DEPLOYMENT_TARGET 10.5
g++ -bundle -undefined dynamic_lookup myfunc.o -o myfunc.so

(On 64-bit OS-X: add -m64 after each g++.)

Windows

cl -nologo -MT -I"%RMANTREE%\include" -c myfunc.cpp
link -nologo -DLL -out:myfunc.dll myfunc.obj "%RMANTREE%\lib\libprman.lib"

The resulting file myfunc.so or myfunc.dll is the plugin that implements your new function. It is not important that the filename matches the name of the function.

On Unix-based platforms, plugins are linked such that symbols that resolve to entry points in libprman.so or libprman.dylib are left unresolved. An example of linking an RSL Plugin is provided below. Note that on Linux the use of -fPIC is important for code that will be used as a plugin and that there is no explicit linkage of libprman.so, even if the plugin makes reference to application interfaces, like deeptexture. On OS X, the linker must be explicitly told that the unresolved symbols will be resolved at runtime. On Windows, the libprman.lib must always be referenced to resolve the unresolved symbols in the plugin.

When compiling your shader, if the RSL compiler comes across a function reference that is neither a known built-in nor a function defined in RSL it will search all plugins defined with the plugin directive until it finds one within the exported RslPublicFunctions table. Note that the plugin file must be specified with the plugin directive. (The .so or .dll extension is not required.) The path to plugins can be relative and can be modified with the -I command line option of the RSL compiler. The RSL compiler will typecheck your function call and issue a warning if you pass arguments that do not match any of the entries in the RslPublicFunctions table of your plugin.

Once your shader is successfully compiled, you are ready to render. The renderer requires the plugin to be in one of the directories that it searches for shaders. In other words, the searchpath specified with the option Option "searchpath" "shader" also specifies the searchpath for the RSL function plugins.

Linking Applications

For applications, on all platforms the libprman library will be linked against the application. Of course, the application will also need to be told where to find the library. This can be done at link-time or at runtime via various mechanisms on each platform.

g++ -c -fPIC -I$RMANTREE/include myapp.cpp
g++ myapp.o -L$RMANTREE/lib -lprman -o myapp

g++ -c -I$RMANTREE/include myapp.cpp
g++ myapp.o -L$RMANTREE/lib -lprman -o myapp
install_name_tool -add_rpath $RMANTREE/lib myapp

cl /nologo /MT /TP /DWIN32 /I"%RMANTREE%\include" -c myapp.cpp
link /nologo /out:myapp.exe /LIBPATH:"%RMANTREE%\lib" libprman.lib myapp.obj