# Palomino - Shader Module

©2004,2009 Jim E. Brooks http://www.palomino3d.org

- Index
- Shaders
- Light classes
- Macros/Preprocessing
- Per-Model Shaders
- Modifying Models for Shaders
- Hardware Light
- Brightness
- Light Position
- Problems

## Shaders

[2009/01]

Shader programs can be attached to any node (this exposes an OSG capability which may differ from other scene-graphs). `ShaderFactory` caches pre-compiled shader programs. Shaders are identified by a name ("default", "metallic", etc). By default, SceneGraph places nodes under a generic shader. Effects code can attach a shader to a different group node and pass it to `SceneGraph::AttachBranchNode()`.

## Light Singleton and Light Classes

[2009/05]

Light sources are implemented by shaders except one hardware light is enabled for special-case 3D models. Therefore, the `Light` class serves as an interface over the private implementation classes `ShaderLight` and `HwLight`. `Light` is a method-forwarding class. `Light` provides a traditional OpenGL interface for light settings. `ShaderLight` hides the names of uniforms used as parameters to shaders.

    This diagram depicts forwarding of methods (it isn't a class hierarchy).

             +-----------+
             |   Light   |
             | interface |
             +---+---+---+
                /     \
               /       \
    +-------------+  +-----------+
    | ShaderLight |  |  HwLight  |
    |   (impl)    |  |   (impl)  |
    +-------------+  +-----------+

    Light::SetPosition() +--> ShaderLight::SetPosition()
                         +--> HwLight::SetPosition()

    Client usage:
    GET_LIGHT().SetLightPosition( lightNum, pos );
    GET_LIGHT().SetLightColor( lightNum, color );
    GET_LIGHT().SetFogDensity( fogDensity, fogMode );

## Macros/Preprocessing

[2009/05]

A very simple macro preprocessor is implemented. Macro keywords are prefixed by @.

### @include - load an include file

@include executes recursively to support nested include files.

    @include funcs.glsl
    void main()
    {
    }

## Per-Model Shaders

[2009/05]

Lua scripts load 3D models. Optionally, Lua can pick a shader for a particular 3D model.

        nodeSort = NodeSort:new( { shader="metallic" } )
        sim.SceneGraph:AttachObjectSpecial( object, nodeSort )

## Modifying Models for Shaders

[2009/05]

A few 3D models will need to be modified to render correctly with the shaders. Problems cases are transparent polygons such as canopy glass and exhaust flame.

Example of inserting a shader uniform:

    StateSet {
    ...
      Uniform {
        DataVariance STATIC
        name "uni_glass"
        bool 1
      }
    ...
    }

In some models, to insert a uniform, a new StateSet must be inserted into a Group:

    Group {
      DataVariance STATIC
      name "ExternalFlame"
      nodeMask 0xffffffff
      cullingActive TRUE
      num_children 3
    -- insert --
      StateSet {
        Uniform {
          DataVariance STATIC
          name "uni_alphaBias"
          float -0.5
        }
      }
    -- insert --
    ...
    }

When converting 3D models, osgconv should be run with `export OSG_OPTIMIZER=OFF`. This prevents conversion problems such as losing node names, distorted geometry, etc.

## Hardware Light

[2009/05]

A few 3D models aren't compatible with any shader. Therefore, if ShaderName="hw", ShaderFactory will produce a group node with the hardware light instead of a shader. `HwLight` singleton defines the hardware light (simulates the sun).

## Brightness

[2009/05]

Brightness is adjusted by:

- Changing the shader uniform `uni_brightness`.
- Changing the hw light's color.
- Changing the hw fog's color.

## Light Position

[2009/05]

C++ public methods set the position of lights in terms of world space. But shaders are written in terms of eye space. So, the C++ side transforms every light's position from world space to eye space.

Specifically, a PreDrawView listener is called before drawing every View which assigns a shader uniform variable with the light's transformed position. The root-level modelview matrix is obtained from the current View object being rendered.

### Shader Programming Notes

The following is a common mistake. Transforming a light position from world space to eye space, (as if it were a vertex) is incorrect, because the modelview matrix was computed for a particular node (3D model). The correct way is for the C++ side to transform the light position using the root-level (View) modelview matrix.

    uniform vec4 uni_light0_Position;  // defined in world space
    ...
        const vec4 ecPosition4 = gl_ModelViewMatrix * gl_Vertex;
        const vec4 ecLightPos = gl_ModelViewMatrix * uni_light0_position;  // WRONG

## Problems

[2009/05]

These 3D models weren't originally created for rendering by shaders. A major problem is transparent polygons. Some aircraft models specify cockpit glass in the alpha of the texture, others in the alpha of the RGBA color with textures disabled. Solution was to write different shaders for different models or inserting uniforms. A few models have proven virtual incompatible with shaders. These models are placed under a node with a hardware light instead of shaders.

Last modified: Sat Nov 7 14:57:23 CST 2009