doc

Documentation

The documentation for this repository's content is the Shader Writing in Open Shading Language book itself.

However, some practical information about how to make use of this repository is provided here.

Requirements

• A command-line interface and its associated shell in which to enter commands.
• make
• python
• git, while optional, is highly recommended in order to clone this repository (or your own fork of this repository) and to provide source code version control if you indend to develop your own shaders.
• RenderMan^® was used to develop the shaders and the build system. Other rendering systems can still make use of the OSL shading nodes with little or no change.

While a Linux system was used to develop this repository's content, as long as your operating system has make and python commands, any necessary modifications to the Makefiles and python installation script should be minor or non-existent.

Installation

To use the supplied repository content as is:

1. Get a professional (paid) or non-commercial (free) license for RenderMan^®.

2. Install RenderMan^® and ensure it is functioning properly.

3. Set these environment variables appropriately. This is so the Makefiles used to build and install the shaders can find the OSL compiler that's provided by RenderMan^®:

   • PIXAR_ROOT
   • RMAN_VERSION

   For example, if your version of the RenderMan^® renderer is installed in /opt/pixar/RenderManProServer-26.2, then (for example) using bash shell:

   export PIXAR_ROOT="/opt/pixar"
   export RMAN_VERSION="26.2"

   And while it's not required by the Makefiles, since RenderMan^® requires an RMANTREE environment variable that's set to the renderer's installation location, you can conveniently use these to define that as well:

   export RMANTREE="${PIXAR_ROOT}/RenderManProServer-${RMAN_VERSION}"

4. Download or clone this repository (or your own fork of this repository).

5. Set this environment variable appropriately. It is required so the built shaders can be found by RenderMan^®:

   • RMAN_SHADERPATH

   For example, if you downloaded or cloned this repository to ${HOME}/ShaderWriting, then using bash shell:

   export RMAN_SHADERPATH="${HOME}/ShaderWriting/build/${RMAN_VERSION}/shaders:${RMAN_SHADERPATH}"

6. cd into the dowloaded or cloned repository's directory. For example, cd ${HOME}/ShaderWriting

7. At this point, you can use the make or make all command (they are equivalent) to build the shaders. You can also cd osl from the repository directory into the osl code directory and make the shaders there. The osl/Makefile will only make shaders for .osl files that are more recent than their complied .oso file. In this way, you can edit a source file and execute make from within the osl code directory and only the updated source file(s) will be built.

   make clean and make help can also be executed from either the top-level directory or the osl directory. make clean removes the built shaders, and make help provides additional information about the make system and how it's controlled.

Development

To modify the existing OSL shaders or to develop your own, cd osl from the top-level repository directory into the osl code directory. This is where you will run make in order to build any modified or new shaders during their development.

To add a new shader to an existing shader category, add the shader's .osl source file to the desired category directory. It will then be built along with the other shaders from that category.

To create a new category of shader, create a new directory with the category's name in the osl code directory and add it to the osl/Makefile SUBDIRS variable on line 32. Once that's done, any .osl files in this new category directory will also be built when make is executed from the osl code directory location.

To build the entire set of shaders from scratch, run make nuke and then make -j from the top-level repository directory location rather than the osl code directory (the -j option simply tells make to use all available processor threads so the build runs as fast as possible). This will build the shaders for the RenderMan^® version specified in the RMAN_VERSION environment variable. Or, if you have multiple RenderMan^® versions installed and those have been listed in the top-level Makefile rman_versions variable on line 15, you can ensure the shaders will be built for all those versions by unsetting the RMAN_VERSION environment variable only while the make command is running by using: make -j RMAN_VERSION=

If you cloned this repository (or your own fork of this repository) from GitHub you'll have created a local git repository on your computer, so all the source code management tools of git will be available to you. If you are not already famililar with the git command, it will be very worthwile to at least learn the basics of adding new files and committing changes to existing ones.

At this point you're all set to start modifying, writing, and using your very own OSL shaders!