]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.multiscreen
Document fixed-near-far.
[flightgear.git] / 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>