Equalizer: Documentation: Developer: 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_IATTR_TYPE                 TCPIP | SDP | PIPE
     EQ_CONNECTION_IATTR_PORT                 unsigned
     EQ_CONNECTION_SATTR_PIPE_FILENAME        string
     EQ_CONFIG_FATTR_EYE_BASE                 float
     EQ_NODE_SATTR_LAUNCH_COMMAND             string
     EQ_NODE_CATTR_LAUNCH_COMMAND_QUOTE       'character'
     EQ_NODE_IATTR_THREAD_MODEL               ASYNC | DRAW_SYNC | LOCAL_SYNC
     EQ_NODE_IATTR_LAUNCH_TIMEOUT             unsigned
     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 | FBO
     EQ_WINDOW_IATTR_HINT_STATISTICS          OFF | FASTEST [ON] | NICEST
     EQ_WINDOW_IATTR_PLANES_COLOR             unsigned | RGBA16F | RGBA32F 
     EQ_WINDOW_IATTR_PLANES_ALPHA             unsigned
     EQ_WINDOW_IATTR_PLANES_DEPTH             unsigned
     EQ_WINDOW_IATTR_PLANES_STENCIL           unsigned
     EQ_WINDOW_IATTR_PLANES_ACCUM             unsigned
     EQ_WINDOW_IATTR_PLANES_ACCUM_ALPHA       unsigned
     EQ_WINDOW_IATTR_PLANES_SAMPLES           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 ]
}
server
{
    connection # 0-n times, listening connections of the server
    {
        type       TCPIP | SDP | PIPE
        port       unsigned # TCPIP, SDP
        filename   string   # PIPE
        hostname   string
    }

    config # 1-n times, currently only the first one is used by the server
    {
        latency int    # Number of frames nodes may fall behind app, default 1
        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 | PIPE
                port          unsigned
                hostname      string
                filename      string
            }
            attributes
            {
                thread_model ASYNC | DRAW_SYNC | LOCAL_SYNC
                launch_command       string      # render client launch command
                launch_command_quote 'character' # command argument quote char
                launch_timeout       unsigned    # timeout in milliseconds
            }
            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 | FBO
                        hint_statistics     OFF | FASTEST [ON] | NICEST
                        planes_color        unsigned | RGBA16F | RGBA32F
                        planes_alpha        unsigned
                        planes_depth        unsigned
                        planes_stencil      unsigned
                        planes_accum        unsigned
                        planes_accum_alpha  unsigned
                        planes_samples      unsigned
                    }
                    channel # 1-n times
                    {
                        name     string
                        viewport [ viewport ] #wrt window, default full window
                        drawable [ FBO_COLOR FBO_DEPTH FBO_STENCIL ]
                        attributes
                        {
                            hint_statistics     OFF | FASTEST [ON] | NICEST
                        }
                    }
                }
            }
        }
        
        observer # 0...n times
        {
            name    string
            eyeBase float
        }

        layout  # 0...n times
        {
            name string
            view  # 1...n times
            {
                name     string
                observer observer-ref
                viewport [ viewport ]

                wall       # frustum description
                {
                    bottom_left  [ float float float ]
                    bottom_right [ float float float ]
                    top_left     [ float float float ]
                    type         fixed | HMD
                }
                projection # alternate frustum description, last one wins
                {
                    origin       [ float float float ]
                    distance     float
                    fov          [ float float ]
                    hpr          [ float float float ]
                }
            }
        }

        canvas  # 0...n times
        {
            name    string
            layout  layout-ref   # 1...n times

            wall       
            {
                    bottom_left  [ float float float ]
                    bottom_right [ float float float ]
                    top_left     [ float float float ]
                    type         fixed | HMD
            }
            projection
            {
                    origin       [ float float float ]
                    distance     float
                    fov          [ float float ]
                    hpr          [ float float float ]
            }
            
            segment # 1...n times
            {
                channel  string
                name     string
                viewport [ viewport ] 

                wall       # frustum description
                {
                    bottom_left  [ float float float ]
                    bottom_right [ float float float ]
                    top_left     [ float float float ]
                    type         fixed | HMD
                }
                projection # alternate frustum description, last one wins
                {
                    origin       [ float float float ]
                    distance     float
                    fov          [ float float ]
                    hpr          [ float float float ]
                }
            }
        }
        
        compound # 1-n times
        {
            name     string
            channel  channel-ref           # see below

            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 int int ]   # pixel decomposition (x y w h)
            subpixel [ int int ]           # subpixel decomposition (index size)
            eye      [ CYCLOP LEFT RIGHT ] # monoscopic or stereo view
            zoom     [ float float ]       # up/downscale of parent pvp
            period   int                   # DPlex period
            phase    int                   # DPlex phase

            load_equalizer # adapt 2D tiling or DB range of children
            {
                mode 2D | DB | VERTICAL | HORIZONTAL
                damping float # 0: no damping, 1: no changes
				boundary [ x y ] | float    # x,y: tile boundary for 2D, float: range
            }
            DFR_equalizer # adapt ZOOM to achieve constant framerate
            {
                framerate float # target framerate
                damping float   # 0: no damping, 1: no changes
            }
            framerate_equalizer {} # smoothen window swapbuffer rate (DPlex)
            monitor_equalizer {}   # set frame zoom when monitoring other views

            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
            }

            wall       # frustum description
            {
                bottom_left  [ float float float ]
                bottom_right [ float float float ]
                top_left     [ float float float ]
                type         fixed | HMD
            }
            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
                NV_group OFF | ON | unsigned
                NV_barrier OFF | ON | unsigned
            }
            outputframe
            {
                name   string
                buffer [ COLOR DEPTH ]
                type texture | memory
            }
            inputframe
            {
                name string # corresponding output frame
            }
        }
    }
}

channel-ref:  'string' | '(' channel-segment-ref ')'
channel-segment-ref: ( canvas-ref ) segment-ref ( layout-ref ) view-ref
canvas-ref:   'string' | 'index'
segment-ref:  'string' | 'index'
layout-ref:   'string' | 'index'
view-ref:     'string' | 'index'
observer-ref: 'string' | 'index'

Changes

Subpixel compounds:

      compound
      {
          subpixel [ int int ]           # subpixel decomposition (index size)
      }

Tile and Range Boundaries:

      compound
      {
          load_equalizer
          {
              mode     [ 2D | VERTICAL | HORIZONTAL | DB ]
              boundary [ x y ] | float  # x,y: tile boundary for 2D, float: range
          }
      }

Launch parameter cleanup after 0.9 changed launch parameters to:

      global
      {
          EQ_NODE_SATTR_LAUNCH_COMMAND             string
          EQ_NODE_CATTR_LAUNCH_COMMAND_QUOTE       'character'
          EQ_NODE_IATTR_LAUNCH_TIMEOUT             unsigned
      }
      node
      {
          attributes
          {
              launch_command       string      # render client launch command
              launch_command_quote 'character' # command argument quote char
              launch_timeout       unsigned    # timeout in milliseconds
          }
      }

Local named pipe communcation support added:

      global
      {
          EQ_CONNECTION_IATTR_TYPE            PIPE
          EQ_CONNECTION_SATTR_FILENAME        string
      }

      connection
      {
        type     PIPE
        filename string
      }

Equalizer cleanup deprecated loadBalancer {} section and added:

      compound
      {
          load_equalizer # adapt 2D tiling or DB range of children
          {
              mode 2D | DB | VERTICAL | HORIZONTAL
              damping float # 0: no damping, 1: no changes
          }
          DFR_equalizer # adapt ZOOM to achieve constant framerate
          {
              framerate float # target framerate
              damping float   # 0: no damping, 1: no changes
          }
          framerate_equalizer {} # smoothen window swapbuffer rate (DPlex)
          monitor_equalizer {}   # set frame zoom when monitoring other views
      }

Support for multiple observers added:

    observer # 0...n times
    {
        name    string
        eyeBase float
    }

    view  # 1...n times
    {
        observer observer-ref
        ...
    }

Floating point pipeline support added:

      global
      {
          EQ_WINDOW_IATTR_PLANES_COLOR   unsigned | RGBA16F | RGBA32F
      }

      window
      {
          attributes
          {
              planes_color    unsigned | RGBA16F | RGBA32F
          }
      }

HMD support added:

    wall
    {
        ...
        type fixed | HMD
    }

Layout API added:

       layout  # 1...n times
       {
            name string
            view  # 1...n times
            {
                name     string
                viewport [ viewport ]

                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 ]
                }
            }
        }

        canvas  # 1...n times
        {
            name   string
            layout string

            wall       
            {
                    bottom_left  [ float float float ]
                    bottom_right [ float float float ]
                    top_left     [ float float float ]
            }
            projection
            {
                    origin       [ float float float ]
                    distance     float
                    fov          [ float float ]
                    hpr          [ float float float ]
            }
            
            segment # 1...n times
            {
                channel  string
                name     string
                viewport [ viewport ] 

                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 ]
                }
            }
        }


        }
        compound
        {
            channel channel-ref
            ...
        }

NV_swap_group (G-Sync) support added:

      swapbarrier 
      {
         NV_group   OFF | ON | unsigned
         NV_barrier OFF | ON | unsigned
      }

Dynamic frame resolution added:

      compound
      {
          zoom     [ float float ]         # up/downscale of parent pvp
          loadBalancer 
          {
             mode DFR
             framerate float
          }
          outputframe
          {
              type texture | memory
          }
      }

FBO Support added:

      global
      {
          EQ_WINDOW_IATTR_HINT_DRAWABLE    window | pbuffer | FBO
      }

      window
      {
          attributes
          {
              hint_drawable    window | pbuffer | FBO
          }
          channel
          {
              drawable [ FBO_COLOR FBO_DEPTH FBO_STENCIL ]
          }
      }

Easier thread model selection added:

      global
      {
          EQ_NODE_IATTR_THREAD_MODEL    ASYNC | DRAW_SYNC | LOCAL_SYNC
      }
      node
      {
          attributes
          {
              thread_model    async | draw_sync | local_sync
          }
      }

Support for accumulation buffer and multisampling added:

      global
      {
          EQ_WINDOW_IATTR_PLANES_ACCUM             unsigned
          EQ_WINDOW_IATTR_PLANES_ACCUM_ALPHA       unsigned
          EQ_WINDOW_IATTR_PLANES_SAMPLES           unsigned
      }
      window
      {
          attributes
          {
              planes_accum        unsigned
              planes_accum_alpha  unsigned
              planes_samples      unsigned
          }
      }

Load-Balancing added:

      compound
      {
          loadBalancer 
          {
               mode [ 2D | DB | VERTICAL | HORIZONTAL ]
          }
      }

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
              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 int int ]     # pixel decomposition (x y w h)
      }

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
      {
          ...
      }

Subpixel Decompositions added:

      compound
      {
          subpixel    [ int int ]     # subpixel decomposition (index size)
      }