Equalizer logo
Collage logo
GPU-SD logo

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