Configuration File Format

Author: eilemann@gmail.com
State: Implemented

The configuration file format for the Equalizer server is described below. The examples directory does contain some example configuration files. The configuration tool automatically creates some standard configuration files.

The file format is not described in detail here. Please refer to the Programming Guide in general, and to the changes section below for individual feature specifications. The actual implementation may differ slightly from this specification, but we try to keep it up to date. The loader implementation is the reference for the file format, look at src/server/loader.y, if you understand lex/yacc code.

Note that this format is the representation for the server's low-level scalable rendering engine. Eventually this file format will be replaced by a higher-level format or API, and may even be partially hidden from the user. Automatic configuration and load balancing are not yet implemented, hence the need to have these low-level configuration files.

All Equalizer units are in meters. This applies currently to the wall coordinates and the eye base, as well as the head matrix supplied programmatically.

Global values have useful default parameters, which can be overriden with environment variables of the same name. For enumeration values, e.g., EQ_COMPOUND_IATTR_STEREO_MODE, the corresponding integer value has to be used. The global values in the config file override these defaults, and are in turn overriden by the corresponding attributes sections of the associated entities.

global
{
     EQ_CONNECTION_SATTR_HOSTNAME             string
     EQ_CONNECTION_SATTR_LAUNCH_COMMAND       string
     EQ_CONNECTION_CATTR_LAUNCH_COMMAND_QUOTE 'character'
     EQ_CONNECTION_IATTR_TYPE                 TCPIP | SDP
     EQ_CONNECTION_IATTR_TCPIP_PORT           unsigned
     EQ_CONNECTION_IATTR_LAUNCH_TIMEOUT       unsigned
     EQ_CONFIG_FATTR_EYE_BASE                 float
     EQ_PIPE_IATTR_HINT_THREAD                OFF | ON
     EQ_WINDOW_IATTR_HINT_STEREO              OFF | ON | AUTO
     EQ_WINDOW_IATTR_HINT_DOUBLEBUFFER        OFF | ON | AUTO
     EQ_WINDOW_IATTR_HINT_DECORATION          OFF | ON
     EQ_WINDOW_IATTR_HINT_FULLSCREEN          OFF | ON
     EQ_WINDOW_IATTR_HINT_SWAPSYNC            OFF | ON   // AGL, WGL only
     EQ_WINDOW_IATTR_HINT_DRAWABLE            window | pbuffer
     EQ_WINDOW_IATTR_HINT_STATISTICS          OFF | FASTEST [ON] | NICEST
     EQ_WINDOW_IATTR_PLANES_COLOR             unsigned
     EQ_WINDOW_IATTR_PLANES_ALPHA             unsigned
     EQ_WINDOW_IATTR_PLANES_DEPTH             unsigned
     EQ_WINDOW_IATTR_PLANES_STENCIL           unsigned
     EQ_CHANNEL_IATTR_HINT_STATISTICS         OFF | FASTEST [ ON ] | NICEST
     EQ_COMPOUND_IATTR_STEREO_MODE                 QUAD | ANAGLYPH
     EQ_COMPOUND_IATTR_STEREO_ANAGLYPH_LEFT_MASK   [ RED GREEN BLUE ]
     EQ_COMPOUND_IATTR_STEREO_ANAGLYPH_RIGHT_MASK  [ RED GREEN BLUE ]
     EQ_COMPOUND_IATTR_UPDATE_FOV             HORIZONTAL [ON] | VERTICAL | OFF
}
server
{
    connection // 0-n times, listening connections of the server
    {
        type       TCPIP | SDP
        TCPIP_port unsigned
        hostname   string
    }

    config // 1-n times, currently only the first one is used by the server
    {
        latency int    // # of frames pipes may fall behind application
        attributes
        {
             eye_base float // distance between left and right eye
        }

        (node|appNode) // 1-n times, a system in the cluster
                       // 0|1 appNode: launches render thread within app process
        {
            name     string
            connection // 0-n times, possible connections to this node
            {
                type          TCPIP | SDP
                TCPIP_port    unsigned
                hostname      string
                command       string      // render client launch command
                command_quote 'character' // launch command argument quote char
                timeout       unsigned    // timeout in milliseconds for launch
            }
            pipe // 1-n times
            {
                name     string
                port     unsigned     // X server number or ignored
                device   unsigned     // graphics adapter number
                viewport [ viewport ] // default: autodetect
                attributes
                {
                    hint_thread   OFF | ON   // default ON
                }

                window // 1-n times
                {
                    name     string
                    viewport [ viewport ] // wrt pipe, default full screen

                    attributes
                    {
                        hint_stereo         OFF | ON | AUTO
                        hint_doublebuffer   OFF | ON | AUTO
                        hint_decoration     OFF | ON
                        hint_fullscreen     OFF | ON
                        hint_swapsync       OFF | ON         // AGL, WGL only
                        hint_drawable       window | pbuffer
                        hint_statistics     off | fastest [on] | nicest
                        planes_color        unsigned
                        planes_alpha        unsigned
                        planes_depth        unsigned
                        planes_stencil      unsigned
                    }
                    channel // 1-n times
                    {
                        name     string
                        viewport [ viewport ] //wrt window, default full window

                        attributes
                        {
                            hint_statistics     OFF | FASTEST [ON] | NICEST
                        }
                    }
                }
            }
        }
        compound // 1-n times
        {
            name     string
            channel  string   // where the compound's tasks are executed
            task     [ CLEAR DRAW READBACK ASSEMBLE ] // CULL later
            buffer   [ COLOR DEPTH ]         // default COLOR
            viewport [ viewport ]            // wrt parent compound, sort-first
            range    [ float float ]         // DB-range for sort-last
            pixel    [ int int ]             // pixel decomposition (step size)
            eye      [ CYCLOP LEFT RIGHT ]   // monoscopic or stereo view
            attributes
            {
                stereo_mode                  QUAD | ANAGLYPH    // default QUAD
                stereo_anaglyph_left_mask    [ RED GREEN BLUE ] // default red
                stereo_anaglyph_right_mask   [ RED GREEN BLUE ] // df green blue
                update_FOV                   HORIZONTAL [ON] | VERTICAL | OFF
            }

            wall       // frustum description
            {
                bottom_left  [ float float float ]
                bottom_right [ float float float ]
                top_left     [ float float float ]
            }
            projection // alternate frustum description, last one wins
            {
                origin       [ float float float ]
                distance     float
                fov          [ float float ]
                hpr          [ float float float ]
            }
            
            child-compounds

            swapbarrier  // compounds with the same barriername sync swap
            {
                name string
            }
            outputframe
            {
                name   string
                buffer [ COLOR DEPTH ]
            }
            inputframe
            {
                name string // corresponding output frame
            }
        }
    }
}

Changes

• Added during implementation of the Statistics Overlay:

        global
        {
            EQ_WINDOW_IATTR_HINT_STATISTICS    off | fastest [on] | nicest
        }
        window
        {
            attributes
            {
                hint_statistics     off | fastest [on] | nicest
            }
        }
      

• PBuffer Support added:

        global
        {
            EQ_WINDOW_IATTR_HINT_DRAWABLE    window | pbuffer
        }
  
        window
        {
            attributes
            {
                hint_drawable    window | pbuffer
            }
        }
      

• Configurable launch command argument quotes were added after v0.4.1:

        global
        {
             EQ_CONNECTION_CATTR_LAUNCH_COMMAND_QUOTE 'character'
        }
  
        node
        {
            connection // 0-n times, possible connections to this node
            {
                type          TCPIP | SDP
                TCPIP_port    unsigned
                hostname      string
                command       string      // render client launch command
                command_quote 'character' // launch command argument quote char
                timeout       unsigned    // timeout in milliseconds for launch
            }
        }
      

• Pixel Decompositions added:

        compound
        {
            pixel    [ int int ]             // pixel decomposition (step size)
        }
      

• Fixed Aspect Ratio added:

        global
        {
            EQ_COMPOUND_IATTR_UPDATE_FOV     HORIZONTAL [ON] | VERTICAL | OFF
        }
  
        compound
        {
            attributes
            {
                update_FOV                   HORIZONTAL [ON] | VERTICAL | OFF
            }
        }
      

• Nonthreaded Rendering added:

        global
        {
            EQ_PIPE_IATTR_HINT_THREAD   off | on
        }
      
        pipe
        {
            attributes
            {
                hint_thread   off | on
            }
        }
      

• Anaglyphic Stereo added:

        global
        {
            EQ_COMPOUND_IATTR_STEREO_MODE                 QUAD | ANAGLYPH
            EQ_COMPOUND_IATTR_STEREO_ANAGLYPH_LEFT_MASK   [ RED GREEN BLUE ]
            EQ_COMPOUND_IATTR_STEREO_ANAGLYPH_RIGHT_MASK  [ RED GREEN BLUE ]
        }
        compound // 1-n times
        {
            attributes
            {
                stereo_mode                  QUAD | ANAGLYPH    // default QUAD
                // enable visible color components
                stereo_anaglyph_left_mask    [ RED GREEN BLUE ] // default red
                stereo_anaglyph_right_mask   [ RED GREEN BLUE ] // df green blue
            }
        }
      

• Stereo and Head Tracking added:

        global
        {
            EQ_CONFIG_FATTR_EYE_BASE            float
            EQ_WINDOW_IATTR_HINT_STEREO         OFF | ON | AUTO
        }
        config // 1-n times, currently only the first one is used by the server
        {
            attributes
            {
                 eye_base float // distance between left and right eye
            }
        }
        window
        {
            attributes
            {
                hint_stereo         off | on | auto
            }
        }
        compound
        {
            eye      [ CYCLOP LEFT RIGHT ]   // monoscopic or stereo view
        }
      

• Statistics Interface added:

        global
        {
            EQ_CHANNEL_IATTR_HINT_STATISTICS    off | fastest [on] | nicest
        }
        channel
        {
            attributes
            {
                hint_statistics     off | fastest [on] | nicest
            }
        }
      

• Compounds added:

        global
        {
            EQ_COMPOUND_*
        }
        compound // 1-n times
        {
            ...
        }