A.3. Lights plugs (internal; at vertex or fragment shader)

The plugs in this section are available at the same shader stage where the lighting is calculated.

We have not yet devised a portable way to specify them, to work regardless of the shading method used. A simple solution would be to allow a stage name like "LIGHT" that is an alias for "FRAGMENT" or "VERTEX", depending on the current shading model (that may change for each Shape node).

Please treat these plugs as internal for now. We may break the compatibility of these plugs!

void PLUG_light_scale(
  inout float light_scale,
  const in vec3 normal_eye,
  const in vec3 light_dir)

Scale the light source contribution. This plug is available at light source nodes' effects, to scale a particular light. It can also be used in shape or group effects, in which case it will affect the contribution of all the lights on given shape.

The light_dir vector is a normalized direction to the light, in eye space.

void PLUG_material_light_ambient(
  inout vec4 ambient)

Ambient color may be changed here. The initial value is a multiplication of material and light ambient colors.

void PLUG_material_light_diffuse(
  inout vec4 diffuse,
  const in vec4 vertex_eye,
  const in vec3 normal_eye)

Diffuse color may be changed here. This is usually a multiplication of material and light diffuse colors, but you can change it here into anything you like.

void PLUG_material_light_specular(
  inout vec4 specular)

Specular color may be changed here. The initial value is a multiplication of material and light specular colors.

void PLUG_material_shininess(
  inout float shininess)

Shininess exponent may be changed here. The initial value is the material shininess exponent.

Note: the X3D Material.shininess and CommonSurfaceShader.shininessFactor are usually in a [0..1] range, and they are multiplied by 128.0 to calculate the actual exponent for light equations. This plug works with the actual exponent.

void PLUG_add_light_contribution(
  inout vec4 color,
  const in vec4 vertex_eye,
  const in vec3 normal_eye,
  in float material_shininess,
  in vec4 color_per_vertex)

Add color coming from lighting this material. This is used internally to add the light sources, with each light source adding another add_light_contribution plug.

void PLUG_lighting_apply(
  inout vec4 fragment_color,
  const vec4 vertex_eye,
  const vec3 normal_eye_fragment)

At this point, the lighting is calculated. Light contributions are summed, along with material emissive and global scene ambient colors, result is clamped to 1.0, and the alpha value is set correctly.

There's a big difference between how Phong and Gouraud shading interact with this plug:

  • In Phong shading, this plug is called in fragment stage, after both lighting and textures are applied. Because for Phong shading, the lighting is calculated after textures.

  • In Gouraud shading this plug is called in vertex stage, after lighting but before texture application. Because for Gouraud shading, the texture is applied later, in fragment shader.