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    fixed-near-far - bool
 142    If true the near and far values are taken from above, if false
 143    near and far are adapted from the scene and visibility.
 144    Defaults to true.
 145
 146    offset-x, offset-y - double
 147    Offsets of the viewing volume specified by the other parameters in
 148    the near plane, in meters.
 149
 150   frustum
 151   This specifies the perspective viewing volume using values for the near
 152   and far planes and coordinates of the viewing rectangle in the near
 153   plane.
 154
 155    left, bottom - double
 156    right, top - double
 157    The coordinates of the viewing rectangle.
 158
 159    near, far - double
 160    The near and far planes, in meters from the camera eye point.
 161
 162    fixed-near-far - bool
 163    If true the near and far values are taken from above, if false
 164    near and far are adapted from the scene and visibility.
 165    Defaults to true.
 166
 167   ortho
 168   This specifies an orthographic view. The parameters are the sames as
 169   the frustum node's.
 170
 171    fixed-near-far - bool
 172    If true the near and far values are taken from above, if false
 173    near and far are adapted from the scene and visibility.
 174    Defaults to true.
 175
 176   master-perspective
 177   Defines a persective projection matrix for use as the leading display
 178   in a seamless multiscreen configuration. This kind of perspective
 179   projection is zoomable.
 180
 181    eye-distance - double
 182    The distance of the eyepoint from the projection surface in units of
 183    the physical-dimensions values above.
 184
 185    x-offset, y-offset - double
 186    Offset of the eyelpint from the center of the screen in units of
 187    the physical-dimensions values above.
 188
 189   left-of-perspective, right-of-perspective, above-perspective,
 190   below-perspective
 191   Defines a perspective projection matrix for use as derived display
 192   in a seamless multiscreen configuration. The projection matrix
 193   is computed so that the respective edge of this display matches the
 194   assiciated other edge of the other display. For example the right edge
 195   of a left-of-perspective display matches the left edge of the parent
 196   display. This also works with different zoom levels, leading to distorted
 197   but still seamless multiview configurations.
 198   The bezel with configured in the physical dimensions of this screen and
 199   the parent screen are taken into account for this type of projection.
 200
 201    parent-camera - string
 202    Name of the parent camera.
 203
 204   reference-points-perspective
 205   Defines a perspective projection matrix for use as derived display
 206   in a seamless multiscreen configuration. This type is very similar to
 207   left-of-perspective and friends. It is just a more flexible but less
 208   convenient way to get the same effect. A child display is configured
 209   by 2 sets of reference points one in this current camera and one in
 210   the parrent camera which should match in the final view.
 211
 212    parent-camera - string
 213    Name of the parent camera.
 214
 215    this
 216    reference points for this projection.
 217
 218     point - array of two points
 219
 220      x, y - double
 221      x and y coodinates of the reference points in units of this
 222      physical-dimensions.
 223
 224    parent
 225    reference points for the parent projection.
 226
 227     point - array of two points
 228
 229      x, y - double
 230      x and y coodinates of the reference points in units of the
 231      parents physical-dimensions.
 232
 233   texture
 234   This tag indicates that the camera renders to a texture instead of the
 235   framebuffer. For now the following tags are supported, but obviously
 236   different  texture formats should be specified too.
 237    name - string
 238    The name of the texture. This can be referred to by other cameras.
 239    width, height - double
 240    The dimensions of the texture
 241
 242   panoramic-distortion
 243   This tag cause the camera to create distortion geometry that
 244   corrects for projection onto a spherical screen. It is equivalent to
 245   the --panoramic-sd option to osgviewer.
 246
 247    texture - string
 248    The name of a texture, created by another camera, that will be
 249    rendered on the distortion correction geometry.
 250
 251    radius - double
 252    Radius of string
 253
 254    collar - double
 255    size of screen collar.
 256
 257  gui
 258  This is a special camera node that displays the 2D GUI.
 259
 260   viewport
 261   This specifies the position and dimensions of the GUI within a
 262   window, *however* at the moment the origin must be at 0,0.
 263
 264 Here's an example that uses a single window mapped across 3
 265 displays. The displays are in a video wall configuration in a
 266 horizontal row.
 267
 268 <PropertyList>
 269   <sim>
 270     <rendering>
 271       <camera-group>
 272         <window>
 273           <name>wide</name>
 274           <host-name type="string"></host-name>
 275           <display>0</display>
 276           <screen>0</screen>
 277           <width>3840</width>
 278           <height>1024</height>
 279           <decoration type = "bool">false</decoration>
 280         </window>
 281         <camera>
 282           <window>
 283             <name>wide</name>
 284           </window>
 285           <viewport>
 286             <x>0</x>
 287             <y>0</y>
 288             <width>1280</width>
 289             <height>1024</height>
 290           </viewport>
 291           <view>
 292             <heading-deg type = "double">0</heading-deg>
 293           </view>
 294           <frustum>
 295             <top>0.133</top>
 296             <bottom>-0.133</bottom>
 297             <left>-.5004</left>
 298             <right>-.1668</right>
 299             <near>0.4</near>
 300             <far>120000.0</far>
 301           </frustum>
 302         </camera>
 303         <camera>
 304           <window>
 305             <name type="string">wide</name>
 306           </window>
 307           <viewport>
 308             <x>1280</x>
 309             <y>0</y>
 310             <width>1280</width>
 311             <height>1024</height>
 312           </viewport>
 313           <view>
 314             <heading-deg type = "double">0</heading-deg>
 315           </view>
 316           <frustum>
 317             <top>0.133</top>
 318             <bottom>-0.133</bottom>
 319             <left>-.1668</left>
 320             <right>.1668</right>
 321             <near>0.4</near>
 322             <far>120000.0</far>
 323           </frustum>
 324         </camera>
 325         <camera>
 326           <window>
 327             <name>wide</name>
 328           </window>
 329           <viewport>
 330             <x>2560</x>
 331             <y>0</y>
 332             <width>1280</width>
 333             <height>1024</height>
 334           </viewport>
 335           <view>
 336             <heading-deg type = "double">0</heading-deg>
 337           </view>
 338           <frustum>
 339             <top>0.133</top>
 340             <bottom>-0.133</bottom>
 341             <left>.1668</left>
 342             <right>.5004</right>
 343             <near>0.4</near>
 344             <far>120000.0</far>
 345           </frustum>
 346         </camera>
 347         <gui>
 348           <window>
 349             <name type="string">wide</name>
 350           </window>
 351         </gui>
 352       </camera-group>
 353     </rendering>
 354   </sim>
 355 </PropertyList>
 356
 357 Here's a complete example that uses a seperate window on each
 358 display. The displays are arranged in a shallow arc with the left and
 359 right displays at a 45.3 degree angle to the center display because,
 360 at the assumed screen dimensions, the horizontal field of view of one
 361 display is 45.3 degrees. Each camera has its own window definition;
 362 the center window is given the name "main" so that the GUI definition
 363 can refer to it.  Note that the borders of the displays are not
 364 accounted for.
 365
 366 <PropertyList>
 367   <sim>
 368     <rendering>
 369       <camera-group>
 370         <camera>
 371           <window>
 372             <host-name type="string"></host-name>
 373             <display>0</display>
 374             <screen>0</screen>
 375             <fullscreen type = "bool">true</fullscreen>
 376           </window>
 377           <view>
 378             <heading-deg type = "double">45.3</heading-deg>
 379           </view>
 380           <frustum>
 381             <top>0.133</top>
 382             <bottom>-0.133</bottom>
 383             <left>-.1668</left>
 384             <right>.1668</right>
 385             <near>0.4</near>
 386             <far>120000.0</far>
 387           </frustum>
 388         </camera>
 389         <camera>
 390           <window>
 391             <name type="string">main</name>
 392             <host-name type="string"></host-name>
 393             <display>0</display>
 394             <screen>1</screen>
 395             <fullscreen type = "bool">true</fullscreen>
 396           </window>
 397           <view>
 398             <heading-deg type = "double">0</heading-deg>
 399           </view>
 400           <frustum>
 401             <top>0.133</top>
 402             <bottom>-0.133</bottom>
 403             <left>-.1668</left>
 404             <right>.1668</right>
 405             <near>0.4</near>
 406             <far>120000.0</far>
 407           </frustum>
 408         </camera>
 409         <camera>
 410           <window>
 411             <host-name type="string"></host-name>
 412             <display>0</display>
 413             <screen>2</screen>
 414             <fullscreen type = "bool">true</fullscreen>
 415           </window>
 416           <view>
 417             <heading-deg type = "double">-45.3</heading-deg>
 418           </view>
 419           <frustum>
 420             <top>0.133</top>
 421             <bottom>-0.133</bottom>
 422             <left>-.1668</left>
 423             <right>.1668</right>
 424             <near>0.4</near>
 425             <far>120000.0</far>
 426           </frustum>
 427         </camera>
 428         <gui>
 429           <window>
 430             <name type="string">main</name>
 431           </window>
 432         </gui>
 433       </camera-group>
 434     </rendering>
 435   </sim>
 436 </PropertyList>
 437
 438 This example renders the scene for projection onto a spherical screen.
 439
 440 <PropertyList>
 441   <sim>
 442     <rendering>
 443       <camera-group>
 444         <camera>
 445           <window>
 446             <name type="string">main</name>
 447             <host-name type="string"></host-name>
 448             <display>0</display>
 449             <screen>0</screen>
 450             <!-- <fullscreen type = "bool">true</fullscreen>-->
 451             <width>1024</width>
 452             <height>768</height>
 453           </window>
 454           <view>
 455             <heading-deg type = "double">0</heading-deg>
 456           </view>
 457           <frustum>
 458             <top>0.133</top>
 459             <bottom>-0.133</bottom>
 460             <left>-.1668</left>
 461             <right>.1668</right>
 462             <near>0.4</near>
 463             <far>120000.0</far>
 464           </frustum>
 465           <texture>
 466             <name>mainview</name>
 467             <width>1024</width>
 468             <height>768</height>
 469           </texture>
 470         </camera>
 471         <camera>
 472           <window><name>main</name></window>
 473           <ortho>
 474             <top>768</top>
 475             <bottom>0</bottom>
 476             <left>0</left>
 477             <right>1024</right>
 478             <near>-1.0</near>
 479             <far>1.0</far>
 480           </ortho>
 481           <panoramic-spherical>
 482             <texture>mainview</texture>
 483           </panoramic-spherical>
 484         </camera>
 485         <gui>
 486           <window>
 487             <name type="string">main</name>
 488           </window>
 489         </gui>
 490       </camera-group>
 491     </rendering>
 492   </sim>
 493 </PropertyList>
 494
 495 Here is an example for a 3 screen seamless zoomable multiscreen
 496 configuration using 3 533mmx300mm displays each with a 23mm bezel.
 497 The side views are angled with 45 deg.
 498 The commented out reference-points-perspective shows the
 499 aequivalent configuration than the active right-of-perspective.
 500 This is done by just using two reference points at the outer
 501 edge of the bezel of the respective display.
 502
 503 <PropertyList>
 504   <sim>
 505     <view n="0">
 506       <config>
 507         <pitch-offset-deg>0.0</pitch-offset-deg>
 508       </config>
 509     </view>
 510
 511     <rendering>
 512       <camera-group>
 513         <window>
 514           <name type="string">0.0</name>
 515           <host-name type="string"></host-name>
 516           <display>0</display>
 517           <screen>0</screen>
 518           <fullscreen type="bool">true</fullscreen>
 519         </window>
 520
 521         <window>
 522           <name type="string">0.1</name>
 523           <host-name type="string"></host-name>
 524           <display>0</display>
 525           <screen>1</screen>
 526           <fullscreen type="bool">true</fullscreen>
 527         </window>
 528
 529         <camera>
 530           <name type="string">CenterCamera</name>
 531           <window>
 532             <name>0.0</name>
 533           </window>
 534           <viewport>
 535             <x>0</x>
 536             <y>0</y>
 537             <width>1920</width>
 538             <height>1080</height>
 539           </viewport>
 540           <view>
 541             <heading-deg type="double">0.0</heading-deg>
 542             <roll-deg type="double">0.0</roll-deg>
 543             <pitch-deg type="double">0.0</pitch-deg>
 544           </view>
 545           <physical-dimensions>
 546             <!-- The size of the projection plane: 533mm 300mm -->
 547             <width>533</width>
 548             <height>300</height>
 549             <bezel>
 550               <right>23</right>
 551               <left>23</left>
 552               <top>23</top>
 553               <bottom>23</bottom>
 554             </bezel>
 555           </physical-dimensions>
 556           <master-perspective>
 557             <!-- Cheating, the real distance is about 800mm.
 558                  But then the screen does not show what is needed to fly.
 559                  By shortening this pictures get bigger but the view also gets
 560                  less realistic.
 561             -->
 562             <eye-distance>450</eye-distance>
 563             <x-offset>0</x-offset>
 564             <y-offset>130</y-offset>
 565           </master-perspective>
 566         </camera>
 567         <camera>
 568           <name type="string">RightCamera</name>
 569           <window>
 570             <name>0.0</name>
 571           </window>
 572           <viewport>
 573             <x>1920</x>
 574             <y>0</y>
 575             <width>1920</width>
 576             <height>1080</height>
 577           </viewport>
 578           <view>
 579             <heading-deg type="double">-45</heading-deg>
 580             <roll-deg type="double">0</roll-deg>
 581             <pitch-deg type="double">0</pitch-deg>
 582           </view>
 583           <physical-dimensions>
 584             <!-- The size of the projection plane: 533mm 300mm -->
 585             <width>533</width>
 586             <height>300</height>
 587             <bezel>
 588               <right>23</right>
 589               <left>23</left>
 590               <top>23</top>
 591               <bottom>23</bottom>
 592             </bezel>
 593           </physical-dimensions>
 594           <right-of-perspective>
 595             <parent-camera type="string">CenterCamera</parent-camera>
 596           </right-of-perspective>
 597           <!-- <reference-points-perspective> -->
 598           <!--   <parent-camera type="string">CenterCamera</parent-camera> -->
 599           <!--   <parent> -->
 600           <!--     <point n="0"> -->
 601           <!--       <x>289.5</x> -->
 602           <!--       <y>100</y> -->
 603           <!--     </point> -->
 604           <!--     <point n="1"> -->
 605           <!--       <x>289.5</x> -->
 606           <!--       <y>-100</y> -->
 607           <!--     </point> -->
 608           <!--   </parent> -->
 609           <!--   <this> -->
 610           <!--     <point n="0"> -->
 611           <!--       <x>-289.5</x> -->
 612           <!--       <y>100</y> -->
 613           <!--     </point> -->
 614           <!--     <point n="1"> -->
 615           <!--       <x>-289.5</x> -->
 616           <!--       <y>-100</y> -->
 617           <!--     </point> -->
 618           <!--   </this> -->
 619           <!-- </reference-points-perspective> -->
 620         </camera>
 621
 622         <camera>
 623           <name type="string">LeftCamera</name>
 624           <window>
 625             <name>0.1</name>
 626           </window>
 627           <viewport>
 628             <x>0</x>
 629             <y>0</y>
 630             <width>1920</width>
 631             <height>1080</height>
 632           </viewport>
 633           <view>
 634             <heading-deg type="double">45</heading-deg>
 635             <roll-deg type="double">0</roll-deg>
 636             <pitch-deg type="double">0</pitch-deg>
 637           </view>
 638           <physical-dimensions>
 639             <!-- The size of the projection plane: 533mm 300mm -->
 640             <width>533</width>
 641             <height>300</height>
 642             <bezel>
 643               <right>23</right>
 644               <left>23</left>
 645               <top>23</top>
 646               <bottom>23</bottom>
 647             </bezel>
 648           </physical-dimensions>
 649           <left-of-perspective>
 650             <parent-camera type="string">CenterCamera</parent-camera>
 651           </left-of-perspective>
 652         </camera>
 653         <gui>
 654           <window>
 655             <name type="string">0.0</name>
 656           </window>
 657         </gui>
 658       </camera-group>
 659     </rendering>
 660   </sim>
 661 </PropertyList>