Resources Documentation RenderMan :Developers' Guide :REYES :The PRMan SDK :

Compiling Plugins & Linking Applications

Compiling Plugins

Compiling and using a new plugin requires three steps:

Compiling the C++ file that contains your plugin functions.

Compiling the shader that uses your functions.

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).

Important
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.

Important

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.

Linux

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

OS X

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

Windows

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

Important
Unlike Linux or OS X, a plugin linked for prman.exe cannot (in general) be loaded into RenderMan for Maya. You will need to link different versions of your plugin for each scenario:
```
link -nologo -DLL -out:myRfMfunc.dll myfunc.obj %RMSTREE%\lib\RenderMan_for_Maya.lib
```
```
link -nologo -DLL -out:myRefunc.dll myfunc.obj %RMSTREE%\lib\rerender.lib
```