![]() |
VEX Language Reference - Version 6.5Side Effects Software Inc. 2003 |
Variable | Type | Description |
Cf | vector | The final color for the surface. The vector represents the RGB color for the surface. |
Of | vector | The final opacity for the surface. A value of {1,1,0} will be opaque in red/green, but let through blue light from behind. |
Af | float | The final alpha for the surface. This is the value which is placed in the alpha channel of the output image. |
P | vector | The position of the point on the surface being shaded. In light or shadow shaders, the P variable contains the point on the light source |
Pz | float | The z component of the point being shaded. |
Ps | vector | In light & shadow shaders, this is the position of the point on the surface being illuminated. |
I | vector | The direction from the eye to the point being shaded. This may or may not be a normalized vector. |
Eye | vector | The position of the eye. |
s | float | The parametric s (sometimes called u) coordinate of the surface being shaded. |
t | float | The parametric t (sometimes called v) coordinate of the surface being shaded. |
dPds, dPdt | vector | The change in position with respect to the parametric coordinates s, t |
N | vector | The shading normal for the surface. |
Ng | vector | The geometric normal for the surface. This normal represents the "true" normal of the surface being shaded. For example, with Phong shading, the N variable represents the interpolated normal, while the Ng variable represents the true polygon normal |
Cl | vector | Light color |
L | vector | The vector from the point on the surface to the light source. The length of this vector represents the distance to the light source. Please see here for further information on how the L variable is initialized |
Lz | vector | The z-axis in the space of the light. This is a unit vector. |
Each context is responsible for setting or modifying different variables. For example, the displacement context can modify the position of the surface being rendered, while the light context is responsible for setting the color of the light source. The Read/Write access of the variables for each context can be described below.
Variable | Displacement | Surface | Light | Shadow | Fog | Photon |
Cf | N/A | Write | N/A | N/A | Read/Write | N/A |
Of | N/A | Write | N/A | N/A | Read/Write | N/A |
Af | N/A | Write | N/A | N/A | Read/Write | N/A |
P | Read/Write | Read/Write(*) | Read | Read | Read | Read |
Pz | Read | Read | N/A | N/A | Read | Read |
Ps | N/A | N/A | Read | Read | N/A | N/A |
I | N/A | Read | Read | Read | Read | Read |
Eye | N/A | Read | Read | Read | Read | Read |
s | Read | Read | Read | Read | Read | Read |
t | Read | Read | Read | Read | Read | Read |
dPds, dPdt | Read | Read | Read | Read | Read | Read |
N | Read/Write | Read/Write | Read | Read | Read | Read |
Ng | Read | Read | Read | Read | Read | Read |
Cl | N/A | Read/Write | Write | Read/Write | Read/Write | Read |
L | N/A | Read | Read/Write | Read | Read | Read |
Lz | N/A | N/A | Read | Read | N/A | Read |
Parameter | Functions | Description |
"scope", string spec | all |
This option allows an override of the scope for ray-intersections. More information on specification of scope can be found here. |
"bias", float value | irradiance occlusion |
The irradiance and occlusion functions take an optional bias parameter which gives control over self-intersection. |
"maxdist", float value | all | This option allows an override of the maximum distance the ray can travel when testing for intersections. Some functions (i.e. fastshadow()) have the maximum distance implicitly defined (by the length of the ray) and should probably avoid using this option. However, this option can be used effectively when computing reflections, global illumination, refraction etc. |
"variance", float value | reflectlight refractlight fastshadow filtershadow trace | This option overrides the global variance control (mantra's -v option) which is used to determine anti-aliasing quality of ray tracing. For more information please refer to the documentation on mantra. |
"angle", float value | reflectlight refractlight fastshadow filtershadow trace |
This value of this parameter specifies a cone angle over which samples will be distributed. To be effective, the samples parameter should also be specified. The value is specified in radians. |
"samples", int value | reflectlight refractlight fastshadow filtershadow trace irradiance occlusion |
The value of this parameter tells how many samples should be sent out to filter rays. For the irradiance and occlusion functions, specifying a samples parameter will override the default irradiance sampling. |
"environment", string map | reflectlight refractlight trace irradiance occlusion |
If the ray sent out to the scene misses everything, then
it's possible to specify an environment map to evaluate.
Using the ray's direction, the environment map specified
will be evaluated and the resulting color will be
returned. Most likely, it will be necessary to specify a
transform space for the environment map evaluations. In the case of refractlight and trace the Of and Af variables will be set to 0 regardless of the background color specified. the resulting color. When an environment map is specified, the standard texture filtering options are also supported. |
"envobject", string objectname "envlight", string lightname "envfog", "string fogname |
reflectlight refractlight trace irradiance occlusion |
If an environment map is used, the orientation of
the environment map can be specified by transforming the
ray into the space of another object, light or fog object
in the scene. In Houdini, null objects can be used
to specify the orientation. For example:
|
"envtint", vector color | reflectlight refractlight trace irradiance occlusion |
If an environment map is used, it's possible to "tint" the resulting color. |
"background", vector color | reflectlight refractlight trace irradiance occlusion |
If a ray misses all objects, it's possible to specify
the background color of the scene. In the case of refractlight and trace the Of and Af variables will be set to 0 regardless of the background color specified. |
"distribution", string style | irradiance | This determines the distribution for computing irradiance. The default is to use a cosine distribution (diffuse illumination). The possible values for the style are: |
Some example patterns are: For reference these are the ray-intersection scopes used by default for each ray-tracing function.
Function | Light/Shadow Shader | Surface Shader |
fastshadow() | Light's shadow scope | Object's reflection scope |
filtershadow() | Light's shadow scope | Object's reflection scope |
rayhittest() | Light's shadow scope | Object's reflection scope |
reflectlight() | Object's reflection scope | Object's reflection scope |
refractlight() | All objects (scope = "*") | All objects (scope = "*") |
trace() | Object's reflection scope | Object's reflection scope |
irradiance() | Object's reflection scope | Object's reflection scope |
occlusion() | Light's shadow scope | Object's reflection scope |
If an empty string is passed as a lightmask, the default lightmask will be used.
Extrapolation of deriatives can be used to hint that derivatives are "smooth" across patch boundaries. In most cases this is true and if extrapolation is turned on, derivative computation should be exact for C2 surfaces. However, when the VEX variables are changing with a high frequency (i.e. a high frequency displacement map will cause high frequency changes to the P variable), extrapolation of derivative computation may cause exaggeration of discontinuities between patch boundaries.
Derivative "smoothing" will cause the magnitude of the differentials to be adjusted non-uniformly over patches. This will usually help to get rid of patch discontinuities in displacement/textured shaders. However, in some odd cases, it may be desirable to turn this feature off.
All of the functions which compute derivatives take additional arguments to allow tuning of the derivative computation:
Keyword | Values |
extrapolate | Turns derivative extrapolation on or off (default is off) |
smooth |
Turns derivative smoothing on or off (default is on) Note: This option is only valid for shading contexts. |
Inside the surface context, it is possible to loop through all light
sources in the scene computing their illumination and shadows. This
is done using the illuminance() construct. This creates will loop
through all light sources, calling the light shader for each light
source to ensure that the Cl and L variables are set
properly. The shadow shader will not be called unless specifically
requested. However, once the shadow shader has been called, the value
of Cl will be changed for the duration of the surface shader.
The shadow shader is automatically called when using any of the
built-in lighting calls (i.e. diffuse(), specular(),
ambient()). The structure of an illuminance clause is:
The default value for the axis is the surface normal. The default
value for the axis is PI/2. The default value for the light
mask is LIGHT_DIFFUSE|LIGHT_SPECULAR (please see shading.h for
the light definitions). The illuminance() statement will loop through
all light sources which meet the criteria dot(L, axis) >
cos(angle).
When mantra is rendering a photon map, photons are spawned from light
sources. Each photon represents a "bit" of energy that has left the
light and will interact with the scene. When a surface is hit by a
photon, the photon shader is invoked.
When a photon hits a surface, a fraction of the photon's energy will
be absorbed by the surface, and another portion of the energy will be
reflected into the scene. For example, a mirror surface would absorb
very little of the energy of the photon, but reflect a large amount of
the energy back into the scene (creating a caustic effect), while a
diffuse surface would be more likely to absorb energy, but might still
distribute a fraction of the energy (creating color bleeding).
However, to create "good" photon maps, all of the photons stored in
the map should have roughly the same energy levels (otherwise
filtering will be biased). Thus, instead of storing a fraction of the
energy and distributing the remainder, the typical method distributing
photons is to use a monte-carlo technique called "Russian Roulette".
Rather than dealing with fractions of the energy, it's better to deal
with fractions of photons. For example, instead of storing a photon
with 30% of the incoming energy, instead, only store 30% of the
photons which hit the surface (and reflect the other 70%).
When a photon strikes a surface, there are four standard light paths
for spawning new photons.
However, it's also possible to pre-compute the combined illumination
The meaning of the global variables in the photon context are:
Surface Shader Specific Functions
Photon Shading Context
In some ways, the structure of the photon shader is dependent on how
the photon map will be accessed. Typically, the photon map will store
incoming illumination. That is, photons directly from the light
sources, or indirectly from other surfaces. Before a photon is
reflected from the photon shader, the "color" of the surface would be
used to modulate the photon color. That is, if the surface were red,
the photon color would be tinted red.Photon Global Variables
Variable
Description
P
The position on the surface being shaded (similar to the
surface context).
Pz
The Z coordinate of P
I
The incoming direction of the photon.
Eye
The origin of the photon (the light source or reflecting
surface).
s, t
The parametric coordinates of the surface being
shaded.
dPds, dPdt
The surface derivatives.
N, Ng
The interpolated and geometric normal at the point being shaded.
Cl
The incoming energy of the photon.
L
The direction from the light to the surface (this is the
same as I, but may have a different magnitude).
Lz
The Z-axis in the space of the light.
Photon Shader Specific Functions
Displacement Shading Context
There are no functions specific to displacement shading.
The shadow context is typically used to separate illumination from expensive ray-tracing calls (like fastshadow() or filtershadow()). This allows fog shaders (or surface shaders) to bypass shadow testing.
Shadow Shader Specific Functions
Fog Shading Context
In Houdini, lights can have either perspective or orthographic projections. An orthographic light in Houdini is used to represent an infinite (or very distant) light source which has all the light rays parallel with each other. A perspective light acts more as a point light source.
When a perspective light shader runs, the L variable is initialized as follows:
In a light shader, it is possible to change the L variable to any value you choose. However, this is how the L variable is initialized.
Variable | Context | Description |
__nondiffuse | Light | If this variable is set to a non-zero value, the light shader will not contribute to diffuse illumination in the standard diffuse() functions. |
__nonspecular | Light | If this variable is set to a non-zero value, the light shader will not contribute to specular illumination in the standard phong(), blinn(), or specular() functions. |
__nofog | Surface | If this variable is set to a non-zero value, no fog shaders will affect the surface color. |
In all VEX contexts, global variables are in "world" space. In the mantra renderer, this space is defined with the camera at the origin pointing down the positive Z axis. Each shader has a local "object" space associated with it. This is the space which defined as the object at the origin of the space. Displacement, Surface and Light shaders also have a special "NDC" space associated with them.
Context | Space | Description |
Displacement Surface |
World | The space which has the camera at the origin, looking down the positive Z axis. |
Displacement Surface |
Shader | Often, this is the same as object space. However, in Houdini, it is possible to define different spaces for displacement/surface shading. The functions wt_space(), wt_vspace(), wt_nspace() will transform from world to texture space. Typically, this space should be used for shading purposes. |
Displacement Surface |
Object | This is defined as the space which has the object at its origin. This is basically the inverse of the object's transform. To get from world to object space, use wo_space(), wo_vspace(), wo_nspace(). |
Displacement Surface |
NDC | This is a special "Normal Device Coordinate" space. A position in world space can be converted to NDC space by calling the toNDC() function. This will transform the X & Y components of the position so that {0,0,z} will be the bottom left hand corner of the image plane as viewed from the camera. The top right hand corner will be represented by {1,1,z}. The Z component of the position remains unchanged by the NDC transformations. Given a point in NDC space, it is possible to find it's world space position by calling fromNDC(). |
Light Shadow |
World | The space which has the camera at the origin, looking down the positive Z axis. |
Light Shadow |
Shader | For Light & Shadow contexts, this is the same as object space. |
Light Shadow |
Object | This is defined as the space which has the light at the origin, pointing down the positive Z axis. |
Light Shadow |
NDC | Since light sources in Houdini have the same attributes as cameras, NDC space is defined for light sources as well. To transform a position into the NDC space for the light source, the object space position should be used in the toNDC space call. The Z component of the object space position will remain unchanged. Given a point in NDC space, it is possible to find it's world space position by calling fromNDC(). |
Fog | World | The space which has the camera at the origin, looking down the positive Z axis. |
Fog | Shader | For fog shaders, this is the same as object space. |
Fog | Object | This is defined as the space which has the fog object at the origin, pointing down the positive Z axis. |
Fog | NDC | This is a special "Normal Device Coordinate" space. A position in world space can be converted to NDC space by calling the toNDC() function. This will transform the X & Y components of the position so that {0,0,z} will be the bottom left hand corner of the image plane as viewed from the camera. The top right hand corner will be represented by {1,1,z}. The Z component of the position remains unchanged by the NDC transformations. Given a point in NDC space, it is possible to find it's world space position by calling fromNDC(). |
The Af variable is used to decide what value gets put into the alpha channel of an RGBA image. If the Af variable is not set by a shader, it is automatically assigned by using:
For example, the following shader simulates a blue screen:
It is also possible to set the Af variable to be something other than 1, meaning that the background image will appear "shadowed" where the matte surface is rendered. This is the theory behind the "shadowmatte" shader.