I Introduction

II Contents

Overview

Shading Language

Interface with POV-Ray

Examples

First shaders

Advanced shaders

Bump mapping

POV-Ray vs. shader

Parametric mapping and opacity

Anisotropic scattering

Bricks, bricks, bricks

"Cellular pattern (a.k.a. Voronoi function)

Skin shader

X-Rays?

Isosurfaces with SL

Torus

Menger's sponge

Shading Language reference and useful links

Implementation notes

Limitations/shortcomings

POV-Ray specific notes

How slow are shaders?

Changes list

Legal stuff

Contact information

Overview

Shading Language

• surface shader. This shader is attached to geometry and computes color and opacity value for given surface point.
• volume shader. This shader type calculates changes in color, caused by volume (e.g. by atmosphere)
• light source shader. Shaders of this type calculate light color, which is emitted by light source.
• displacement shader. Shaders of this type change geometry's sample point position and/or its normal.

This program implements surface shaders. Surface shader has access to various geometry attributes (shading point, surface normal at shading point, ray direction, eye position, initial surface color and opacity) and should calculate resulting surface color and opacity. List of some shader built-in variables, which are used for communication between POV-Ray and shader virtual machine, is given below.
 

Name	Type	Description
Input parameters
Cs	color	Default color for geometry surface
Os	color	default opacity for geometry surface
P	point	shading point
Ng	normal	surface normal at shading point
u,v	float	surface parameters
E	point	eye position
I	vector	incident ray direction
Output parameters
Ci	color	output color
Oi	color	output opacity
N	normal	surface normal

Shading language contains following types:
float
color
vector
normal
point
Types other than floats could be referred as triples, last 3 as geometric triples.

Following operators between these types are supported:
unary(-,!)
arithmetic (+, -, *, /)
geometric (., ^) (dot product and cross product)
logical (==, !=, >, >=, <, <=, &&, ||)
assignment (=, +=, -=, *=, /=)
conditional (?:)

If operation is involved between float and triple, then float is promoted automatically to appropriate type.
Additionally, there is number of built-in functions (mathematical, geometric, color, shading and lighting), which implement most useful operations.
Shading Language supports following language constructs:
blocks  ({})
conditionals (if,else)
loops (while, for, continue, break, illuminance)
user defined functions (return expression).

Interface with POV-Ray

Examples

First shaders

surface red(){
    Ci = color (1,0,0);
}

First line specifies, that this shader is surface shader. In parentheses are shader parameters specified. This simple shader does not use any parameters, so we leave it just empty.
Second line assigns color (1,0,0) to output color. Colors are described in triples (R,G,B).

By saving this code into file red.sl (as custom, shader files have extension .sl) and compiling:
>povslc red.sl
we should have file red.slp, which contains byte code for our shader. Test POV-Ray file (red.pov) is as follows:

camera {
    location <0.5, 1, -3>
    direction <0, 0, 1>
    up <0, 1, 0>
    right <4/3, 0,0>
    look_at <0,0,0>
}
light_source{
    <10, 10, -10>
    color <1,1,1>
}    

sphere{
    <0,0,0>, 1
    texture{
        pigment{
            shader{
                shader_file "red.slp"
            }
        }
        finish{
            ambient 1
            diffuse 0
        }
    }
}

This scene contains sphere, which pigment is calculated by shader. By rendering this scene, we can see, that sphere has indeed red color.

Now lets try to change color of sphere from POV-Ray, as modifying shader and recompiling it each time is a little bit cumbersome. For this we take shader parameters in use.
(Following examples are located in examples/params )
First the shader file (params.sl):

surface params(color ResultCol = color(1,1,1);)
{
    Ci 0 ResultCol;
}

texture{
    pigment{
        shader{
            shader_file "params.slp"
            "ResultCol"  <1,1,0>
        }
    }
}

    "Cs" <;1,1,0>

    Ci = Cs;

Advanced shaders

Bump mapping

surface bumps(float scale=25, amp=1)
{
    point w,x;
    x = noise(transform("shader", P)*scale)*amp;
    w = normalize(N) + x/2;
    if (I.w <= 0){
        N = normalize(w);
    }
    Oi = Os;
    Ci = Cs;
}

POV-Ray vs. shader

surface povshad(){ 

    normal Nf = normalize(N); 
    float Ka = 0.5; 
    float Kd = 0.0; 
    float Ks = 0.6; 
    float Kp = 0.0; 
    float roughness = 0.5; 
    color base = color (1,1,1)*0.8; 

    color spec = specular(Nf, -normalize(I), roughness); 
    Ci = base *(Ka*ambient() + Kd * diffuse(Nf)) + 
        Ks * spec + Kp*phong(Nf, -normalize(I), 5); 

} 

camera { 
    location  <0, 1, -13> 
    direction <0, 0,  1> 
    up        <0, 1,  0> 
    right     <4/3, 0,0> 
    look_at   <0, 0, 0> 
} 

light_source{ 
    <0, 10, 1>*1000 
    color <1,1,1> 
} 

sphere{ 
  <-4,0,0>,3 

  texture{ 
    pigment{ 
      shader{ 
        shader_file "povshad.slp" 
      } 
    } 
    finish{ 
      ambient 1 
      diffuse 0 
    } 
  } 
} 

sphere{ 
  <4,0,0>,3 
  texture{ 
    pigment{ 
        color rgb<1,1,1>*0.8 
    } 
    finish{ 
      ambient 0.5 
      diffuse 0. 
      specular 0.6 
      roughness 0.5 
    } 
  } 
} 

Parametric mapping and opacity

surface uvtest(){ 
    Oi=Os; 
    if (mod(u*150,10)<4){ 
        Ci=(1,0,1); 
    } 
    else if(mod(v*150, 10)<4){ 
        Ci=(1,1,0); 
    } 
    else{ 
        Ci = 1; 
        Oi = 0; 
    } 
} 

Anisotropic scattering

Bricks, bricks, bricks

Cellular pattern (a.k.a. Voronoi function)

Skin shader

X-Rays?

Isosurfaces with SL

Torus

Menger's sponge

Shading Language Reference and useful links

Additionally, books "Advanced RenderMan" and "Texturing & Modeling" are recommended reading, as they contain good deal of information about shading language.
Additional online references:
BMRT homepage: http://www.bmrt.org
RenderMan Repository (contains number of shaders): http://www.renderman.org
Usenet newsgroup news://comp.graphics.rendering.renderman is useful place for discussion about Shading Language.

Implementation notes

Limitations/shortcomings of shading language

Partially implemented/to be improved:

Not yet implemented/planned in next version(s):

Not implemented/implementation under consideration.

Not implemented/not planned:

POV-Ray specific notes

Overview

• Creating (or downloading) shader code and compiling it into byte code.
• Creating (or modifying) POV-Ray scene file, which uses this byte code.

Compiled byte code is in ASCII format, so it does not depend from system endianess, floating point representation etc. ASCII format means also, that use of byte code does not require binary "linking" to POV-Ray ( as it would require, if .DLL-s or binary modules were created).
Interpreting byte code is slower, than running pre-compiled machine code, of course; this is the price to pay for flexibility.
 

Shading Language Compiler

• Support for (C) preprocessor. For using preprocessor following environment variables should be set:
• POVSLCPP - this should specify preprocessor. If this variable is not set, then preprocessor is not executed and input file is passed to compiler as is.
• POVSLCPP_PARAM - this variable could specify default parameters for preprocessor. Useful ones could be path to shader header files (usually -I option in C preprocessor) and generation of #line directives (usually this is on by default): shader compiler takes #line [0-9]+ and #[0-9]+ directives into account during error reporting. Additional options could be passed from command line to preprocessor by prefixing option with dash: e.g. in order to specify -P option to preprocessor, use --P, to specify /P use -/P.
• Inlining of user functions: this means, that there is no execution overhead in function call. This will result in bigger byte code, but in case of shaders speed is only thing, what matters.
• optional dumping of "assembler code": -c option. This means, that machine code mnemonic names with their parameters are dumped into result file: good for spotting errors in shader. This does not affect usability of shader file.
• generation of check ops into result code: -v option. Check ops run assertion statements during shader execution. This facilitates locating of error in virtual machine or compiler.
• optional generation of warnings in source code: -w option.
• specification of output file: -o option. If not specified, then default extension .slp is added to source file's base name
• Compiler has following code size limitations (in order to change them, recompilation is needed, but it is quite unlikely, that such shader will be written, where these limits will be met; if one tries to compile such shader, then error is reported and compilation is stopped.):
• Maximum number of nested functions: 50
• Maximum number of nested blocks in function or shader: 50
• Maximum number of active symbols (i.e. variables, available from current block): 1000
• compilation is stopped on first error occurrence, i.e. the rest of file will not be parsed and errors, which are after first one, will not be reported.
• Shader compiler grammar file has 2 shift-reduce conflicts: one is "standard" dangling-else conflict (curse from C-syntax), other is from array subscription optimization (when array is subscribed with constant expression, then direct address of variable is calculated). If compiler compiler reports more errors, then beware!

Virtual Machine & POV-Ray

Shader is attached to POV-Ray as pigment. This means, that shader output color and opacity are seen by POV-Ray as pigment color (opacity is mapped to pigment transmittance by equation 1-comp(Oi,0) (or 1-'red component of opacity'). This means, that finish statements could modify shader output color. If shader calculates only "pure" color (without taking into account light sources), then it is acceptable. But if shader calculates color with respect to light sources (by using illuminance statement or diffuse, specular and phong functions), then finish statement should set ambient to 1 and diffuse to 0:

texture{
    pigment{
        shader{
            ...
        }
    }
    finish{
        ambient 1
        diffuse 0
    }
}

In order to change surface color Cs and opacity Os (by default Cs == color(1,1,1) and Os == color (1,1,1)), user can set them from POV-Ray scene file similar to shader parameters.

Shadow calculation for surface, which has shader as pigment, could execute shader again in order to determine whether surface is opaque or has transparency component (remember, that shader can change surface opacity arbitrarily). This leads to number of problems:

• Shaders should be reentrant and their memory should be allocated dynamically. This dynamic allocation means performance degradation.
• Lighting functions evaluate light sources in order to determine, whether particular light affects resulting color. This means, that shadows for objects should be taken into account and shader could be executed again. And this means big performance slowdowns. In order to avoid this performance slow-down, all functions, which perform lighting calculation (i.e. evaluate light sources) are made non reentrant: if they are executed from the shadow calculation, then do not find any light sources. Such functions are diffuse, specular and phong. Of course in some pelicular shader, where opacity depends from return value of these functions, result may be incorrect, but I have to see such shaders before I start to correct this behaviour.
• In some shaders this opacity evaluation may lead to infinite recursion: shader is evaluated in some point, in order to determine its result color illuminance statement is executed, illuminance statement will execute shadow calculation in order to determine, whether light source is visible from given point, this shadow calculation will execute shader etc. In order to avoid such behaviour, recursion depth is limited to 1: this means, that once illuminance loop is executed, it will not be entered again. If some shader requires recursive evaluation, then it could be set by predefined variable shader_recursion_depth, which specifies allowed depth for recursion.

Default value for shadow_type is opaque_shadow (i.e. surface has full shadow). Opacity value, returned by shader, is used for shadow calculations only in the case of shader_shadow (see examples/uvtest/uvtest.pov for example of partially transparent object with correct shadows).
Here is example of different shadow types (source could be found in examples/shadows). Shadow types from left to right: no_shadow, opaque_shadow, Os_shadow (Os=0.3), shader_shadow.

Built-in variables

Here is description of built-in variables.

Cs	Default surface color is set to white (1,1,1). Could be changed in POV-Ray scene file as shader parameter.
Os	Default surface opacity is set to full for all channels (1,1,1). Could be changed in scene file as shader parameter.
P	Intersection point
N	Surface normal at intersection point. This is normal after POV-Ray perturberation (bumps, dents, etc.) Normal direction is same with the surface normal direction (POV-Ray flips normals toward camera, but Shading Language assumes true geometric normal, without flipping, so shader code flips it back, if necessary). Modification of this normal from shader affects surface colouring calculation, if this is performed by POV-Ray (i.e. texture finish contains diffuse or specular component).
Ng	Surface geometric normal. This is normal, returned by intersection calculation.
I	Ray direction.
Ci	Result rgb component for color, which is sent to  POV-Ray as pigment color.
Oi	1-st channel's (R component) value is set as transmittance component of POV-Ray pigment color.
u	surface's u value
v	surface's v value
s	is set to u
t	is set to v
du	not used
dv	not used
time	is set equal to POV-Ray clock value
E	Camera position.
Cl	color of evaluated light source
L	direction of evaluated light source.
As	Ambient component, returned by ambient() function in shading language. Could be set in scene file as shader parameter. If this value in not set, then default value <0,0,0> is used instead.

POVMan supports in limited way non-object pigment definitions. By non-object here is meant POV-Ray features, which don't have all the properties of "usual objects", such as clearly defined intersection with ray, normal at given point, support for transformations etc. Example of such non-object is sky_sphere. If shader is used as pigment for such object, then available built-ins are:

• Intersection (or evaluation) point P
• Surface color Cs
• Surface opacity Os
• Output color - Ci
• Output opacity - Oi
• current clock value - time
• Camera position E
• Ambient component As

POVMan issues warning, if shader is used for such non-object, but does not limit shader use in such cases, so it is up to user to ensure, that no other built-in variables are used, as it may lead to undefined behaviour.

Additionally, non-object shaders do not support shading and lighting functions, such as illuminance, diffuse, etc.

POVMan version 0.7 has support for isosurface shaders, i.e. shading language could be used to calculate isosurface functions. Shading language has new keyword iso_function, which specifies, that current shader is used for isosurface calculation. iso_function should return float value, which is used in isosurface calculation as potential value for given point P. For example sphere could be created with following shader file:

iso_function sphere(float radius=1){
    return length(P)-radius;
}

#declare ShaderSphere = function{
    shader{
        shader_file "sphere.slp"
        "radius" 3
    }
}
isosurface{
    function{
        ShaderSphere
    }
    ...

How slow are shaders?

camera{
    location <0.5, 1, -7>
    direction <0, 0, 1>
    up <0, 1, 0>
    right <4/3, 0, 0>
    look_at <0.5, 1, 0>
}
light_source{
    <10, 10, -10>
    color rgb 1
}
// set this var. to 0 to test POV-Ray pigment
#declare TestShader=1;

sphere{
    0, 6
    texture{
        pigment{
            #if (TestShader)
            shader{shader_file "red.slp"}
            #else
            color <1,0,0>
            #end
        }
        finish{
            ambient 1
            diffuse 0
        }
    }
}

surface red(color cl=color(1,0,0)){
    Ci = cl;
}

If SL is used for isosurface functions, then this combination could be in some scenes even faster than MegaPOV's isosurface functions, which are written in scene description. Here are some results of isosurface measurments in seconds:

isosurface type	builtin function	user function	shader
sphere	35	68	46
torus	35	161	62
surfaces from math_pigm.pov	N/A	29	10
ridgedMF	300	N/A	658

As it could be seen, shaders are slower, than built-in functions, but faster than user functions. This of course depends from actual function, but given the flexibility of shader language (one can use loops and conditionals quite easily, e.g. see sponge scene!) and possible faster execution, it seems to be good idea to implement user defined functions in SL.
Additionally, it pays off to tinker with shader code a little bit and try various solutions for given algorithm. I've quite often reduced code size (and execution time) by factor of 2 after recoding. Thing to observe is code size in compiled file. And sometimes it is good to look at bytecode (compile with option -c) in order to get idea about possible optimizations.

Changes list

Version 0.71.3

• Updated cloth patch (many features added).
• bug fix in #default diretive parsing.
• bug fix in transformable warp patch.

Version 0.7

• Various speed optimizations.
• Added sqr (square) function to shading language.
• Added support for iso_function in shading language and support for shaders as functions in POV-Ray.
• Added Bouf's cloth patch For more information about this patch see http://tofbouf.free.fr/clothray/index.html
• Various bug fixes in shading language compiler. Most notably user functions were not correctly generated, if they were used in logical expressions.
• Removed support for built-in variables from POV-Ray finish.
• ambient() function behaviour was changed: if As is not specified, then default value is (0,0,0). Previously it was ambient value from POV-Ray's finish.

Version 0.62

• Added shader support for non-objects (e.g. for sky sphere).
• SL compiler fixes: fixed incorrect handling of logical not (!) operator.
• SL compiler function inlining didn't handled correctly ops with argument list longer than 2 bytes.

Legal stuff

"POV-Ray", "Persistence of Vision", "POV-Team" and "POV-Help" are trademarks of POV-Team.
RenderMan (R) is a registered trademark of Pixar.

This is unofficial version of POV-Ray. Do not ask the POV-Team for help with this patch. Official version of POV-Ray can be downloaded from http://www.povray.org  and POV-Ray licence could be found in povlegal.doc file.

Original POVMAN version was created and copyrighted by Bob Mercier, who kindly gave me permission to use his code for merging it with current POV-Ray version and adding new features. Original POVMAN version's homepage could be found in http://www.cinenet.com/~mercier/bigpict.html

Current version (0.7) contains cloth patch code from ClothMan program, created by Christophe Bouffartigue(tofbouf@free.fr) and used with his permission. Merci, Bouf!

This program is copyrighted freeware, which follows POV-Ray license agreement. If POV-Team decides to incorporate this patch to official version, then POV-Team team aquires rights, mentioned in POV-Ray licence agreement.

THIS SOFTWARE IS PROVIDED AS IS, WITHOUT ANY GUARANTEES OR WARRANTY. AUTHORS ARE NOT RESPONSIBLE FOR ANY DAMAGE OR LOSSES OF ANY KIND CAUSED BY USE OR MISUSE OF THIS SOFTWARE.
 

Contact information