RenderMan Shader Profiling

March 2006

1 Introduction

Shader profiling identifies hotspots in shaders, taking the guesswork out of optimization. Shader hotspots include call stacks, allowing a detailed understanding of the context in which heavily used library routines are called. Each hotspot is linked to its source code, simplifying browsing and analysis.

Profiling is enabled with the following RIB option, which specifies an output filename:

    Option "statistics" "shaderprofile" ["profile.xml"]

When profiling is enabled, single-threaded rendering should be used to ensure accurate timing, i.e. using "prman -t:1"

The impact on execution time and memory is modest. Profiling typically increases overall time by less than 5% and uses a few hundred kilobytes per shader.

Important: Shaders compiled with older versions of the shader compiler (before Release 13) will not be profiled. The output of the profiler includes a list of any shaders that require recompilation.

2 Viewing hotspots

The output file is XML, which is linked to a stylesheet. Simply load the file in a Web browser (IE 6, NS 7, or Firefox) to browse the results. The profiling results contain a list of shading hotspots, each of which includes the elapsed time, source filename and line number, and the name of the calling function.

If problems arise, try the following:

Make sure JavaScript is enabled.
The output file contains an <xml-stylesheet> tag that specifies the location of a stylesheet. Sometimes the Web browser is unable to locate the stylesheet. This commonly occurs if the statistics are generated on a renderfarm but viewed on workstation that does not have the stylesheet in the same location.

A simple workaround is to edit the output file to specify the correct location of the stylesheet, which is normally located in $RMANTREE/etc/html where $RMANTREE is the location of the RenderMan installation directory. The current stylesheet filename is rmProfileHtml_1.0.xml, but subsequent releases will likely use a different version number.
Alternatively, the location of the stylesheet can be specified in the rendermn.ini configuration file, which is located in the etc subdirectory of the RenderMan installation directory. Administrators of large installations may find it convenient to copy the stylesheet to a central location (e.g. a Web server) and update rendermn.ini to reference that location:
```
    /prman/statistics/profilestylesheet   http://megacorp.com/render/profileStyle.xml
```
However, beware that "cross-domain security" featuers in some browsers do not permit an XML file to use a stylesheet in a different domain (e.g. if the XML is loaded from the local filesystem, the stylesheet cannot be loaded from a web server).
If necessary, an offline processor can be used to convert the XML file to HTML using the profiling stylesheet. This allows profiling results to be viewed in Opera and older versions of other Web browsers. To perform this conversion, use a command-line XSLT processor like xsltproc, which is distributed with libxslt (xmlsoft.org/XSLT). See the XSLT FAQ for other tools (www.dpawson.co.uk/xsl/xslfaq.html).

3 Browsing source code

Simply click on the line number of a hotspot to inspect its source code:

Filesystem issues can complicate source code browsing. The full path to each source file (including header files) is recorded when a shader is compiled. If those paths are not valid on the computer where the results are viewed, source browsing is not possible. A simple workaround is to search-and-replace directory names in the profiler output file.

Other issues may arise:

Make sure JavaScript is enabled.
Mysteriously, some browsers will not load source code that starts with "#define". (This is probably a relic of Unix file type conventions.) Simply add a comment to the start of such files and try again.
Line numbers in the source code browser are sometimes off by one. This is due to a browser bug that discards the first blank line of any text file. The source code browser provides a button to adjust for this quirk. Or simply edit such files to eliminate leading blank lines.
Some browsers will not load files with unknown filename extensions (such as ".sl"). It might be possible to work around such issues by changing MIME types or file associations. For example, in Firefox this can be accomplished by editing a file called mimeTypes.rdf in your Firefox profile directory, which is usually located in the following directory:
- Unix: $HOME/.mozilla/firefox/*.default/
- Windows: /Documents and Settings/userid/Application Data/Mozilla/Firefox/Profiles/*.default/
Look for the description of mimetype:text/plain, and add the filename extensions sl and h:
```
  <RDF:Description RDF:about="urn:mimetype:text/plain" NC:value="text/plain">
    <NC:fileExtensions>txt</NC:fileExtensions>
    <NC:fileExtensions>text</NC:fileExtensions>
    <NC:fileExtensions>sl</NC:fileExtensions>
    <NC:fileExtensions>h</NC:fileExtensions>
    <NC:handlerProp RDF:resource="urn:mimetype:handler:text/plain"/>
  </RDF:Description>
```
If all else fails, contact your system administrator for assistance, or tap the wisdom of other users on the RenderMan Forums (renderman.pixar.com/forum/).

4 Viewing hotspot contexts

If a hotspot is in a function with more than one caller, you might want to know which call site was the most expensive. Simply click on the "Details" checkbox to see the list of callers, along with the percentage contributed by each call site:

5 Viewing call stacks

The complete call stack of a hotspot can also be examined by selecting the "Details" checkbox of a particular caller: