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 | RDMA | PIPE
    EQ_CONNECTION_IATTR_PORT                 unsigned
    EQ_CONNECTION_SATTR_PIPE_FILENAME        string
    EQ_CONFIG_FATTR_EYE_BASE                 float
    EQ_CONFIG_IATTR_ROBUSTNESS               OFF | ON
    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_PIPE_IATTR_HINT_AFFINITY     AUTO | OFF | CORE unsigned | SOCKET unsigned
    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 | OFF
    EQ_WINDOW_IATTR_HINT_STATISTICS          OFF | FASTEST [ON] | NICEST
    EQ_WINDOW_IATTR_HINT_GRAB_POINTER        OFF | [ON]
    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_CHANNEL_SATTR_DUMP_IMAGE              string
    EQ_COMPOUND_IATTR_STEREO_MODE            AUTO | QUAD | ANAGLYPH | PASSIVE
    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 | RDMA | PIPE | RSP
        port       unsigned # TCPIP, SDP
        filename   string   # PIPE
        hostname   string
        interface  string   # RSP
    }

    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
            robustness   OFF | ON  # tolerate resource failures (init only)
        }

        (node|appNode) # 1-n times, a system in the cluster
                       # 0|1 appNode: launches render thread within app process
        {
            name     string
            host     string  # Used to auto-launch render nodes
            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
                    hint_affinity AUTO | OFF | CORE unsigned | SOCKET unsigned
                }

                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 | OFF
                        hint_statistics     OFF | FASTEST [ON] | NICEST
                        hint_grab_pointer   OFF | [ON]
                        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
                            dump_image          string
                        }
                    }
                }
            }
        }

        observer # 0...n times
        {
            name     string
            eye_base float   # convenience
            eye_left   [ float float float ]
            eye_cyclop [ float float float ]
            eye_right  [ float float float ]
            focus_distance float
            focus_mode     fixed | relative_to_origin | relative_to_observer
            opencv_camera [OFF] | AUTO | ON | integer  # head tracker
            vrpn_tracker string                      # head tracker device name
        }

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

                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 | OFF   # 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 ]
            }
            swapbarrier  # default swap barrier for all segments of canvas
            {
                name string
                NV_group OFF | ON | unsigned
                NV_barrier OFF | ON | unsigned
            }

            segment # 1...n times
            {
                channel  string
                name     string
                viewport [ viewport ]
                eye [ CYCLOP LEFT RIGHT ] # eye passes, default all

                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 ]
                }
                swapbarrier {...}  # set as barrier on all dest compounds
        }

        compound # 1-n times
        {
            name     string
            channel  channel-ref           # see below

            task     [ CLEAR DRAW READBACK ASSEMBLE ] # CULL later
            buffer   [ COLOR DEPTH ]       # default COLOR

            eye      [ CYCLOP LEFT RIGHT ] # eyes handled, default all

            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)
            zoom     [ float float ]      # up/downscale of parent pvp
            period   int                  # DPlex period
            phase    int                  # DPlex phase

            view_equalizer {} # assign resources to child load_equalizers
            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 ]          # 2D tile boundary
                boundary float            # DB range granularity
                resistance [ x y ]        # 2D tile pixel delta
                resistance float          # DB range delta
                assemble_only_limit float # limit for using dest as src
            }
            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
            tile_equalizer
            {
                name string
                size [ int int ]     # tile size
            }

            attributes
            {
                stereo_mode    AUTO | QUAD | ANAGLYPH | PASSIVE # default AUTO
                stereo_anaglyph_left_mask    [ RED GREEN BLUE ] # default red
                stereo_anaglyph_right_mask   [ RED GREEN BLUE ] # df green blue
            }

            wall  # frustum description, deprecated by view and segment frustum
            {
                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 ]
            }

            swapbarrier {...}  # compounds with the same name sync swap

            child-compounds

            outputframe
            {
                name   string
                buffer [ COLOR DEPTH ]
                type texture | memory
            }
            inputframe
            {
                name string # corresponding output frame
            }
            outputtiles
            {
                name   string
                size [ int int ]     # tile size
            }
            inputtiles
            {
                name string # corresponding output tiles
            }
        }
    }
}

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

VRPN head tracking added:

        observer # 0...n times
        {
            vrpn_tracker string                      # head tracker device name
        }

Camera-based head tracking using OpenCV added:

        observer # 0...n times
        {
            opencv_camera [AUTO] | OFF | ON | integer  # head tracker
        }

Tile compounds added:

      compound
      {
          tile_equalizer
          {
              name string
              size [ int int ]     # tile size
          }
          outputtiles
          {
              name   string
              size [ int int ]     # tile size
          }
          inputtiles
          {
              name string # corresponding output tiles
          }
      }

Asymmetric eye position added:

        observer # 0...n times
        {
            eye_left   [ float float float ]
            eye_cyclop [ float float float ]
            eye_right  [ float float float ]
        }

Resistance for 2D load-balancers added:

      compound
      {
          load_equalizer
          {
              mode     [ 2D | VERTICAL | HORIZONTAL | DB ]
              resistance [ x y ] | float  # x,y: minimum pixel delta for 2D, float: range
          }
      }

Mouse capture/grab added:

global
{
    EQ_WINDOW_IATTR_HINT_GRAB_POINTER        OFF | [ON]
}
                window # 1-n times
                {
                    attributes
                    {
                        hint_grab_pointer   OFF | [ON]
                    }
                }

Automatic thread placement added:

global
{
    EQ_PIPE_IATTR_HINT_AFFINITY     AUTO | OFF | CORE unsigned | SOCKET unsigned
}
            pipe # 1-n times
            {
                attributes
                {
                    hint_affinity AUTO | OFF | CORE unsigned | SOCKET unsigned
                }
            }

Per-segment swap barriers added:

      canvas
      {
          swapbarrier // default for all segments
          {
              name "barrier-name" // sync's compound's window swap buffers
              // NV_swap_group (G-Sync) support
              NV_group    OFF | ON (1) | unsigned // use HW group n
              NV_barrier  OFF | ON (1) | unsigned // use HW barrier n
          }
          segment
          {
              swapbarrier { ..as above.. }
          }
      }

Focus distance support added:

    config // 1-n times, currently only the first one is used by the server
    {
        observer
        {
             focus_distance float
             focus_mode     fixed | relative_to_origin | relative_to_observer
        }
    }

Render nodes without listening connections added:

      #Equalizer 1.2 ascii
      node
      {
          host     string  # Used to auto-launch render nodes
          ...
      }

Runtime Stereo Switch added:

      #Equalizer 1.1 ascii
      view
      {
          mode MONO | STEREO
      }
      segment
      {
          ...
          eye [ CYCLOP LEFT RIGHT ] # eye passes, default all
      }
      compound
      {
          attributes
          {
              stereo_mode QUAD | ANAGLYPH | AUTO # new AUTO, also new default
          }
      }

RFE 3132979 added:

      global
      {
          EQ_COMPOUND_IATTR_STEREO_MODE      AUTO | QUAD | ANAGLYPH | PASSIVE
      }
      compound # 1-n times
      {
          attributes
          {
              stereo_mode        AUTO | QUAD | ANAGLYPH | PASSIVE # default AUTO
          }
      }

load equalizer: auto-disable of dest channel added:

      load_equalizer # adapt 2D tiling or DB range of children
      {
           assemble_only_limit float # resource limit for using dest as src
      }

Multicast data transfer:

      connection
      {
          type RSP
          interface "10.1.1.1"
      }

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
      }

Cross-Segment Load Balancing added:

    compound
    {
        view_equalizer{}
    }

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