illuminance vex function

illuminance(position, [axis], [angle], [light_typemask], [lightmask])
{
    // Here, Cl and L will be set to the value/direction for the
    // current light source.

    // To force the shadow shader to be called, use:
    // shadow(Cl);
}

The shadow shader is not called unless you explicitly call it. 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 (e.g. diffuse, specular, ambient).

See the section on shading contexts for the values of the light mask.

The default value for the axis is the surface normal. The default value for the angle 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 loops through all light sources for which dot(L, axis) > cos(angle).

You can use the extra "categories" argument to specify the lights to loop over by categories instead of by masks:

illuminance(origin, normal, angle, "categories", "shadow|occlusion")
{
...
}

You can give additional pairs of string/value arguments to illuminance to pass named values to each light’s shader. For example, to pass the value of the N variable as orgN:

illuminance (P, nf, M_PI/2, "orgN", N) {
...
}

In the light’s shader, you can receive the value from the illuminance loop with the simport function.

vector orgN;
simport("orgN", orgN);

The simport function returns 1 if the import succeeds and 0 otherwise, so you can use it as the condition in an if statement.

Here’s a full example:

surface
exporter()
{
    vector nf = frontface(normalize(N), I);
    Cf = 0;
    illuminance(P, nf, M_PI/2, "orgN", N)
    {
        Cf += Cl;
    }
}

light
importer()
{
    vector orgN;
    if (!simport("orgN", orgN))
        orgN = N;
    // Use original N
    Cl = orgN;
}

• simport

• gather