docs-mini/README.multiscreen

   1 The Open Scene Graph library, which current FlightGear uses for its 3D
   2 graphics, provides excellent support for multiple views of a
   3 scene. FlightGear uses the osgViewer::Viewer class, which implements a
   4 "master" camera with "slave" cameras that are offset from the master's
   5 position and orientation. FlightGear provides the "camera group"
   6 abstraction which allows the configuration of slave cameras via the
   7 property tree.
   8
   9 Slave cameras can be mapped to windows that are open on different
  10 screens, or all in one window, or a combination of those two schemes,
  11 according to the video hardware capabilities of a machine. It is not
  12 advisable to open more than one window on a single graphics card due
  13 to the added cost of OpenGL context switching between the
  14 windows. Usually, multiple monitors attached to a single graphics card
  15 are mapped to different pieces of the same desktop, so a window can be
  16 opened that spans all the monitors. This is implemented by Nvidia's
  17 TwinView technology and the Matrox TripleHead2Go hardware.
  18
  19 The camera group is configured by the /sim/rendering/camera-group node
  20 in the property tree. It can be set up by, among other things, XML in
  21 preferences.xml or in an XML file specified on the command line with
  22 the --config option.
  23
  24 Here are the XML tags for defining camera groups.
  25
  26 camera-group
  27 For the moment there can be only one camera group. It can contain
  28 window, camera, or gui tags.
  29
  30  window
  31  A window defines a graphics window. It can be at the camera-group
  32  level or defined within a camera. The window contains these tags:
  33
  34   name - string
  35   The name of the window which might be displayed in the window's
  36   title bar. It is also used to refer to a previously defined
  37   window. A window can contain just a name node, in which case
  38   the whole window definition refers to a previously defined window.
  39
  40   host-name - string
  41   The name of the host on which the window is opened. Usually this is
  42   empty.
  43
  44   display - int
  45   The display number on which the window is opened.
  46
  47   screen - int
  48   The screen number on which the window is opened.
  49
  50   x, y - int
  51   The location on the screen at which the window is opened. This is in
  52   the window system coordinates, which usually puts 0,0 at the upper
  53   left of the screen XXX check this for Windows.
  54
  55   width, height - int
  56   The dimensions of the window.
  57
  58   decoration - bool
  59   Whether the window manager should decorate the window.
  60
  61   fullscreen - bool
  62   Shorthand for a window that occupies the entire screen with no
  63   decoration.
  64
  65  camera
  66  The camera node contains viewing parameters.
  67
  68   window
  69   This specifies the window which displays the camera. Either it
  70   contains just a name that refers to a previous window definition, or
  71   it is a full window definition.
  72
  73   viewport
  74   The viewport positions a camera within a window. It is most useful
  75   when several cameras share a window.
  76
  77    x, y - int
  78    The position of the lower left corner of the viewport, in y-up
  79    coordinates.
  80
  81    width, height - int
  82    The dimensions of the viewport
  83
  84   physical-dimensions
  85   The physical dimension of the projection surface.
  86   Use this together with the master-perspective, right-of-perspective
  87   left-of-perspective, above-perspective, below-perspective or
  88   reference-points-perspective
  89
  90    width, height - double
  91    The dimensions of the projection plane, if unset the veiwport values
  92    are taken as default.
  93
  94    bezel
  95    Gives informantion about the bezel of monitors for a seamless view.
  96
  97     right
  98     right bezel with in the same units than with and height above
  99
 100     left
 101     left bezel with in the same units than with and height above
 102
 103     top
 104     top bezel with in the same units than with and height above
 105
 106     bottom
 107     bottom bezel with in the same units than with and height above
 108
 109   view
 110   The view node specifies the origin and direction of the camera in
 111   relation to the whole camera group. The coordinate system is +y up,
 112   -z forward in the direction of the camera group view. This is the
 113   same as the OpenGL viewing coordinates.
 114
 115    x,y,z - double
 116    Coordinates of the view origin.
 117
 118    heading-deg, pitch-deg, roll-deg - double
 119    Orientation of the view in degrees. These are specified using the
 120    right-hand rule, so a positive heading turns the view to the left,
 121    a positive roll rolls the view to the left.
 122
 123   perspective
 124   This node is one way of specifying the viewing volume camera
 125   parameters. It corresponds to the OpenGL gluPerspective function.
 126
 127    fovy-deg - double
 128    The vertical field-of-view
 129
 130    aspect-ratio - double
 131    Aspect ratio of camera rectangle (not the ratio between the
 132    vertical and horizontal fields of view).
 133
 134    near, far - double
 135    The near and far planes, in meters from the camera eye point. Note
 136    that FlightGear assumes that the far plane is far away, currently
 137    120km. The far plane specified here will be respected, but the sky
 138    and other background elements may not be drawn if the view plane is
 139    closer than 120km.
 140
 141    offset-x, offset-y - double
 142    Offsets of the viewing volume specified by the other parameters in
 143    the near plane, in meters.
 144
 145   frustum
 146   This specifies the perspective viewing volume using values for the near
 147   and far planes and coordinates of the viewing rectangle in the near
 148   plane.
 149
 150    left, bottom - double
 151    right, top - double
 152    The coordinates of the viewing rectangle.
 153
 154    near, far - double
 155    The near and far planes, in meters from the camera eye point.
 156
 157   ortho
 158   This specifies an orthographic view. The parameters are the sames as
 159   the frustum node's.
 160
 161   master-perspective
 162   Defines a persective projection matrix for use as the leading display
 163   in a seamless multiscreen configuration. This kind of perspective
 164   projection is zoomable.
 165
 166    eye-distance - double
 167    The distance of the eyepoint from the projection surface in units of
 168    the physical-dimensions values above.
 169
 170    x-offset, y-offset - double
 171    Offset of the eyelpint from the center of the screen in units of
 172    the physical-dimensions values above.
 173
 174   left-of-perspective, right-of-perspective, above-perspective,
 175   below-perspective
 176   Defines a perspective projection matrix for use as derived display
 177   in a seamless multiscreen configuration. The projection matrix
 178   is computed so that the respective edge of this display matches the
 179   assiciated other edge of the other display. For example the right edge
 180   of a left-of-perspective display matches the left edge of the parent
 181   display. This also works with different zoom levels, leading to distorted
 182   but still seamless multiview configurations.
 183   The bezel with configured in the physical dimensions of this screen and
 184   the parent screen are taken into account for this type of projection.
 185
 186    parent-camera - string
 187    Name of the parent camera.
 188
 189   reference-points-perspective
 190   Defines a perspective projection matrix for use as derived display
 191   in a seamless multiscreen configuration. This type is very similar to
 192   left-of-perspective and friends. It is just a more flexible but less
 193   convenient way to get the same effect. A child display is configured
 194   by 2 sets of reference points one in this current camera and one in
 195   the parrent camera which should match in the final view.
 196
 197    parent-camera - string
 198    Name of the parent camera.
 199
 200    this
 201    reference points for this projection.
 202
 203     point - array of two points
 204
 205      x, y - double
 206      x and y coodinates of the reference points in units of this
 207      physical-dimensions.
 208
 209    parent
 210    reference points for the parent projection.
 211
 212     point - array of two points
 213
 214      x, y - double
 215      x and y coodinates of the reference points in units of the
 216      parents physical-dimensions.
 217
 218   texture
 219   This tag indicates that the camera renders to a texture instead of the
 220   framebuffer. For now the following tags are supported, but obviously
 221   different  texture formats should be specified too.
 222    name - string
 223    The name of the texture. This can be referred to by other cameras.
 224    width, height - double
 225    The dimensions of the texture
 226
 227   panoramic-distortion
 228   This tag cause the camera to create distortion geometry that
 229   corrects for projection onto a spherical screen. It is equivalent to
 230   the --panoramic-sd option to osgviewer.
 231
 232    texture - string
 233    The name of a texture, created by another camera, that will be
 234    rendered on the distortion correction geometry.
 235
 236    radius - double
 237    Radius of string
 238
 239    collar - double
 240    size of screen collar.
 241
 242  gui
 243  This is a special camera node that displays the 2D GUI.
 244
 245   viewport
 246   This specifies the position and dimensions of the GUI within a
 247   window, *however* at the moment the origin must be at 0,0.
 248
 249 Here's an example that uses a single window mapped across 3
 250 displays. The displays are in a video wall configuration in a
 251 horizontal row.
 252
 253 <PropertyList>
 254   <sim>
 255     <rendering>
 256       <camera-group>
 257         <window>
 258           <name>wide</name>
 259           <host-name type="string"></host-name>
 260           <display>0</display>
 261           <screen>0</screen>
 262           <width>3840</width>
 263           <height>1024</height>
 264           <decoration type = "bool">false</decoration>
 265         </window>
 266         <camera>
 267           <window>
 268             <name>wide</name>
 269           </window>
 270           <viewport>
 271             <x>0</x>
 272             <y>0</y>
 273             <width>1280</width>
 274             <height>1024</height>
 275           </viewport>
 276           <view>
 277             <heading-deg type = "double">0</heading-deg>
 278           </view>
 279           <frustum>
 280             <top>0.133</top>
 281             <bottom>-0.133</bottom>
 282             <left>-.5004</left>
 283             <right>-.1668</right>
 284             <near>0.4</near>
 285             <far>120000.0</far>
 286           </frustum>
 287         </camera>
 288         <camera>
 289           <window>
 290             <name type="string">wide</name>
 291           </window>
 292           <viewport>
 293             <x>1280</x>
 294             <y>0</y>
 295             <width>1280</width>
 296             <height>1024</height>
 297           </viewport>
 298           <view>
 299             <heading-deg type = "double">0</heading-deg>
 300           </view>
 301           <frustum>
 302             <top>0.133</top>
 303             <bottom>-0.133</bottom>
 304             <left>-.1668</left>
 305             <right>.1668</right>
 306             <near>0.4</near>
 307             <far>120000.0</far>
 308           </frustum>
 309         </camera>
 310         <camera>
 311           <window>
 312             <name>wide</name>
 313           </window>
 314           <viewport>
 315             <x>2560</x>
 316             <y>0</y>
 317             <width>1280</width>
 318             <height>1024</height>
 319           </viewport>
 320           <view>
 321             <heading-deg type = "double">0</heading-deg>
 322           </view>
 323           <frustum>
 324             <top>0.133</top>
 325             <bottom>-0.133</bottom>
 326             <left>.1668</left>
 327             <right>.5004</right>
 328             <near>0.4</near>
 329             <far>120000.0</far>
 330           </frustum>
 331         </camera>
 332         <gui>
 333           <window>
 334             <name type="string">wide</name>
 335           </window>
 336         </gui>
 337       </camera-group>
 338     </rendering>
 339   </sim>
 340 </PropertyList>
 341
 342 Here's a complete example that uses a seperate window on each
 343 display. The displays are arranged in a shallow arc with the left and
 344 right displays at a 45.3 degree angle to the center display because,
 345 at the assumed screen dimensions, the horizontal field of view of one
 346 display is 45.3 degrees. Each camera has its own window definition;
 347 the center window is given the name "main" so that the GUI definition
 348 can refer to it.  Note that the borders of the displays are not
 349 accounted for.
 350
 351 <PropertyList>
 352   <sim>
 353     <rendering>
 354       <camera-group>
 355         <camera>
 356           <window>
 357             <host-name type="string"></host-name>
 358             <display>0</display>
 359             <screen>0</screen>
 360             <fullscreen type = "bool">true</fullscreen>
 361           </window>
 362           <view>
 363             <heading-deg type = "double">45.3</heading-deg>
 364           </view>
 365           <frustum>
 366             <top>0.133</top>
 367             <bottom>-0.133</bottom>
 368             <left>-.1668</left>
 369             <right>.1668</right>
 370             <near>0.4</near>
 371             <far>120000.0</far>
 372           </frustum>
 373         </camera>
 374         <camera>
 375           <window>
 376             <name type="string">main</name>
 377             <host-name type="string"></host-name>
 378             <display>0</display>
 379             <screen>1</screen>
 380             <fullscreen type = "bool">true</fullscreen>
 381           </window>
 382           <view>
 383             <heading-deg type = "double">0</heading-deg>
 384           </view>
 385           <frustum>
 386             <top>0.133</top>
 387             <bottom>-0.133</bottom>
 388             <left>-.1668</left>
 389             <right>.1668</right>
 390             <near>0.4</near>
 391             <far>120000.0</far>
 392           </frustum>
 393         </camera>
 394         <camera>
 395           <window>
 396             <host-name type="string"></host-name>
 397             <display>0</display>
 398             <screen>2</screen>
 399             <fullscreen type = "bool">true</fullscreen>
 400           </window>
 401           <view>
 402             <heading-deg type = "double">-45.3</heading-deg>
 403           </view>
 404           <frustum>
 405             <top>0.133</top>
 406             <bottom>-0.133</bottom>
 407             <left>-.1668</left>
 408             <right>.1668</right>
 409             <near>0.4</near>
 410             <far>120000.0</far>
 411           </frustum>
 412         </camera>
 413         <gui>
 414           <window>
 415             <name type="string">main</name>
 416           </window>
 417         </gui>
 418       </camera-group>
 419     </rendering>
 420   </sim>
 421 </PropertyList>
 422
 423 This example renders the scene for projection onto a spherical screen.
 424
 425 <PropertyList>
 426   <sim>
 427     <rendering>
 428       <camera-group>
 429         <camera>
 430           <window>
 431             <name type="string">main</name>
 432             <host-name type="string"></host-name>
 433             <display>0</display>
 434             <screen>0</screen>
 435             <!-- <fullscreen type = "bool">true</fullscreen>-->
 436             <width>1024</width>
 437             <height>768</height>
 438           </window>
 439           <view>
 440             <heading-deg type = "double">0</heading-deg>
 441           </view>
 442           <frustum>
 443             <top>0.133</top>
 444             <bottom>-0.133</bottom>
 445             <left>-.1668</left>
 446             <right>.1668</right>
 447             <near>0.4</near>
 448             <far>120000.0</far>
 449           </frustum>
 450           <texture>
 451             <name>mainview</name>
 452             <width>1024</width>
 453             <height>768</height>
 454           </texture>
 455         </camera>
 456         <camera>
 457           <window><name>main</name></window>
 458           <ortho>
 459             <top>768</top>
 460             <bottom>0</bottom>
 461             <left>0</left>
 462             <right>1024</right>
 463             <near>-1.0</near>
 464             <far>1.0</far>
 465           </ortho>
 466           <panoramic-spherical>
 467             <texture>mainview</texture>
 468           </panoramic-spherical>
 469         </camera>
 470         <gui>
 471           <window>
 472             <name type="string">main</name>
 473           </window>
 474         </gui>
 475       </camera-group>
 476     </rendering>
 477   </sim>
 478 </PropertyList>
 479
 480 Here is an example for a 3 screen seamless zoomable multiscreen
 481 configuration using 3 533mmx300mm displays each with a 23mm bezel.
 482 The side views are angled with 45 deg.
 483 The commented out reference-points-perspective shows the
 484 aequivalent configuration than the active right-of-perspective.
 485 This is done by just using two reference points at the outer
 486 edge of the bezel of the respective display.
 487
 488 <PropertyList>
 489   <sim>
 490     <view n="0">
 491       <config>
 492         <pitch-offset-deg>0.0</pitch-offset-deg>
 493       </config>
 494     </view>
 495
 496     <rendering>
 497       <camera-group>
 498         <window>
 499           <name type="string">0.0</name>
 500           <host-name type="string"></host-name>
 501           <display>0</display>
 502           <screen>0</screen>
 503           <fullscreen type="bool">true</fullscreen>
 504         </window>
 505
 506         <window>
 507           <name type="string">0.1</name>
 508           <host-name type="string"></host-name>
 509           <display>0</display>
 510           <screen>1</screen>
 511           <fullscreen type="bool">true</fullscreen>
 512         </window>
 513
 514         <camera>
 515           <name type="string">CenterCamera</name>
 516           <window>
 517             <name>0.0</name>
 518           </window>
 519           <viewport>
 520             <x>0</x>
 521             <y>0</y>
 522             <width>1920</width>
 523             <height>1080</height>
 524           </viewport>
 525           <view>
 526             <heading-deg type="double">0.0</heading-deg>
 527             <roll-deg type="double">0.0</roll-deg>
 528             <pitch-deg type="double">0.0</pitch-deg>
 529           </view>
 530           <physical-dimensions>
 531             <!-- The size of the projection plane: 533mm 300mm -->
 532             <width>533</width>
 533             <height>300</height>
 534             <bezel>
 535               <right>23</right>
 536               <left>23</left>
 537               <top>23</top>
 538               <bottom>23</bottom>
 539             </bezel>
 540           </physical-dimensions>
 541           <master-perspective>
 542             <!-- Cheating, the real distance is about 800mm.
 543                  But then the screen does not show what is needed to fly.
 544                  By shortening this pictures get bigger but the view also gets
 545                  less realistic.
 546             -->
 547             <eye-distance>450</eye-distance>
 548             <x-offset>0</x-offset>
 549             <y-offset>130</y-offset>
 550           </master-perspective>
 551         </camera>
 552         <camera>
 553           <name type="string">RightCamera</name>
 554           <window>
 555             <name>0.0</name>
 556           </window>
 557           <viewport>
 558             <x>1920</x>
 559             <y>0</y>
 560             <width>1920</width>
 561             <height>1080</height>
 562           </viewport>
 563           <view>
 564             <heading-deg type="double">-45</heading-deg>
 565             <roll-deg type="double">0</roll-deg>
 566             <pitch-deg type="double">0</pitch-deg>
 567           </view>
 568           <physical-dimensions>
 569             <!-- The size of the projection plane: 533mm 300mm -->
 570             <width>533</width>
 571             <height>300</height>
 572             <bezel>
 573               <right>23</right>
 574               <left>23</left>
 575               <top>23</top>
 576               <bottom>23</bottom>
 577             </bezel>
 578           </physical-dimensions>
 579           <right-of-perspective>
 580             <parent-camera type="string">CenterCamera</parent-camera>
 581           </right-of-perspective>
 582           <!-- <reference-points-perspective> -->
 583           <!--   <parent-camera type="string">CenterCamera</parent-camera> -->
 584           <!--   <parent> -->
 585           <!--     <point n="0"> -->
 586           <!--       <x>289.5</x> -->
 587           <!--       <y>100</y> -->
 588           <!--     </point> -->
 589           <!--     <point n="1"> -->
 590           <!--       <x>289.5</x> -->
 591           <!--       <y>-100</y> -->
 592           <!--     </point> -->
 593           <!--   </parent> -->
 594           <!--   <this> -->
 595           <!--     <point n="0"> -->
 596           <!--       <x>-289.5</x> -->
 597           <!--       <y>100</y> -->
 598           <!--     </point> -->
 599           <!--     <point n="1"> -->
 600           <!--       <x>-289.5</x> -->
 601           <!--       <y>-100</y> -->
 602           <!--     </point> -->
 603           <!--   </this> -->
 604           <!-- </reference-points-perspective> -->
 605         </camera>
 606
 607         <camera>
 608           <name type="string">LeftCamera</name>
 609           <window>
 610             <name>0.1</name>
 611           </window>
 612           <viewport>
 613             <x>0</x>
 614             <y>0</y>
 615             <width>1920</width>
 616             <height>1080</height>
 617           </viewport>
 618           <view>
 619             <heading-deg type="double">45</heading-deg>
 620             <roll-deg type="double">0</roll-deg>
 621             <pitch-deg type="double">0</pitch-deg>
 622           </view>
 623           <physical-dimensions>
 624             <!-- The size of the projection plane: 533mm 300mm -->
 625             <width>533</width>
 626             <height>300</height>
 627             <bezel>
 628               <right>23</right>
 629               <left>23</left>
 630               <top>23</top>
 631               <bottom>23</bottom>
 632             </bezel>
 633           </physical-dimensions>
 634           <left-of-perspective>
 635             <parent-camera type="string">CenterCamera</parent-camera>
 636           </left-of-perspective>
 637         </camera>
 638         <gui>
 639           <window>
 640             <name type="string">0.0</name>
 641           </window>
 642         </gui>
 643       </camera-group>
 644     </rendering>
 645   </sim>
 646 </PropertyList>