Manual page for INTRO(3s)

Shader Writing Library

Introduction

Description

Syntax

Parameters

Introduction to PhotoRealistic RenderMan shaders

There are two categories of shaders included with PhotoRealistic RenderMan. The first is the set of standard shaders required by the RenderMan Interface. The other is the set of example shaders included to illustrate various concepts of shader writing and use.

The four types of shaders are surface shaders, displacement shaders, light shaders, and volume shaders. For an explanation of these, see Steve Upstill's The RenderMan Companion: A Programmer's Guide to Realistic Computer Graphics (Reading: Addison-Wesley, 1990), pp. 170-180. Although the standard shaders include samples of all four types, there are no volume shaders with the examples.

The format used to document each of these shaders is borrowed from the standard UNIX man pages. Non-UNIX users may ignore the section designation “3s” on all the pages -- they are there for historical reasons. The designation is a carry over from the UNIX convention of using Section 3 for the similar category of “library functions and subroutines”. The “s” is to help distinguish these shaders from the C functions found normally in Section 3, and in particular from the “Standard I/O Functions” in Section 3S.

SYNTAX

The SYNOPSIS line of each shader's page lists the syntax that would be used to call the shader from a RIB file. A different syntax would be needed for a call in the RenderMan Interface. For example, the wood surface shader could be called with the following RIB line:

Surface "wood" "Ka" [0.6] "Ks" [0.5] "specularcolor" [1 1 1]

and with the equivalent line as written in the RenderMan Interface:

RiSurface(wood, "Ka", 0.6, "Ks", 0.5,
          "specularcolor", [1 1 1], RI_NULL);

The first word of the SYNOPSIS line will be the RIB command used to call the shader and will thus indicate whether the shader is a Surface, Displacement, Light, or a Volume shader.

PARAMETERS

The PARAMETERS part of each man page lists the default values for each of the parameters accepted by the shader. Only those parameters whose values you wish to change from the default need be specified in the shader call.

Most parameters are numbers (floats) whose range of valid values is determined by each individual shader. In RIB parameter lists, each number must be enclosed in square brackets.

Some parameters represent points in space and are given as an ordered triple of numbers, (three numbers separated by spaces and enclosed in square brackets). Point parameters are used by light shaders, for example, to determine the location of the light source in space or the direction it is pointing.

Still other parameters are colors. A color is an ordered triple with the numbers representing the red, green and blue components of the color (its RGB value). Although it is possible for a shader to use a different representation of color, (for example with more than three components), the shaders included here all expect an RGB triple.

Other parameters can be strings of characters enclosed in quotes. This is generally used to specify the name of a file to be used as a texture map by the shader.

Several parameters appear often enough in the standard shaders and example shaders to imply somewhat of a convention. These conventions are not mandatory, and in fact may not be followed by the all the shaders documented in the pages that follow, but it is useful to list some commonly used parameters here.

Surface shaders commonly use the following parameters:

Ka: The ambient component of light reflected from a surface.
Kd: The diffuse coefficient of light used to compute the light that is scattered by the surface.
Kr: The reflection coefficient used to compute the amount of the surrounding environment reflected in a surface.
Ks: The specular coefficient used to compute the light reflected from a surface in the mirror direction, producing a highlight.
roughness: The roughness of the surface. A rougher surface produces a less pronounced highlight.
specularcolor: The color of light coming from a specular reflection. This takes an RGB color value.
texturename: This is simply a string specifying the name of a texture map file.

Displacement shaders often use another kind of coefficient.

Km: The displacement coefficient used to compute the extent to which the local geometry of a surface is deformed at each point.

Light shaders commonly use some or all of the following parameters:

intensity: This is the intensity of the light, with 0 meaning that the light is effectively turned off, while 1 is simply a convenient unit to use for “some” light. Depending on how distant the object is, and whether there is any attentuation or falloff of the light, this value could be any positive number.
lightcolor: This is the color of the light coming from the source, an RGB triple.
from: This is a point (an ordered triple) generally representing the location of the light source in space, or the direction from which light is coming (when used with the to parameter).
to: This is also a point (an ordered triple) representing the direction of light emitted from the light source.

Volume shaders (atmosphere shaders) commonly use parameters that define spacial boundaries for the effect of the shader, and some background color that gets mixed in with object colors to obtain the effect.

distance: This is a number representing the distance from the viewer at which the atmospheric effect is strongest (or weakest). There may be two or more such distance parameters representing different “clipping planes” where the effect may change or reach a minimum or maximum.
background: This is a color (an RGB triple) which is mixed in some way with the computed colors in the scene to produce the desired atmospheric effect.