diff --git a/Docs/README.multiscreen b/Docs/README.multiscreen new file mode 100644 index 000000000..9954f13f9 --- /dev/null +++ b/Docs/README.multiscreen @@ -0,0 +1,315 @@ +The Open Scene Graph library, which current FlightGear uses for its 3D +graphics, provides excellent support for multiple views of a +scene. FlightGear uses the osgViewer::Viewer class, which implements a +"master" camera with "slave" cameras that are offset from the master's +position and orientation. FlightGear provides the "camera group" +abstraction which allows the configuration of slave cameras via the +property tree. + +Slave cameras can be mapped to windows that are open on different +screens, or all in one window, or a combination of those two schemes, +according to the video hardware capabilities of a machine. It is not +advisable to open more than one window on a single graphics card due +to the added cost of OpenGL context switching between the +windows. Usually, multiple monitors attached to a single graphics card +are mapped to different pieces of the same desktop, so a window can be +opened that spans all the monitors. This is implemented by Nvidia's +TwinView technology and the Matrox TripleHead2Go hardware. + +The camera group is configured by the /sim/rendering/camera-group node +in the property tree. It can be set up by, among other things, XML in +preferences.xml or in an XML file specified on the command line with +the --config option. + +Here are the XML tags for defining camera groups. + +camera-group +For the moment there can be only one camera group. It can contain +window, camera, or gui tags. + + window + A window defines a graphics window. It can be at the camera-group + level or defined within a camera. The window contains these tags: + + name - string + The name of the window which might be displayed in the window's + title bar. It is also used to refer to a previously defined + window. A window can contain just a name node, in which case + the whole window definition refers to a previously defined window. + + host-name - string + The name of the host on which the window is opened. Usually this is + empty. + + display - int + The display number on which the window is opened. + + screen - int + The screen number on which the window is opened. + + x, y - int + The location on the screen at which the window is opened. This is in + the window system coordinates, which usually puts 0,0 at the upper + left of the screen XXX check this for Windows. + + width, height - int + The dimensions of the window. + + decoration - bool + Whether the window manager should decorate the window. + + fullscreen - bool + Shorthand for a window that occupies the entire screen with no + decoration. + + camera + The camera node contains viewing parameters. + + window + This specifies the window which displays the camera. Either it + contains just a name that refers to a previous window definition, or + it is a full window definition. + + viewport + The viewport positions a camera within a window. It is most useful + when several cameras share a window. + + x, y - int + The position of the lower left corner of the viewport, in y-up + coordinates. + + width, height - int + The dimensions of the viewport + + view + The view node specifies the origin and direction of the camera in + relation to the whole camera group. The coordinate system is +y up, + -z forward in the direction of the camera group view. This is the + same as the OpenGL viewing coordinates. + + x,y,z - double + Coordinates of the view origin. + + heading-deg, pitch-deg, roll-deg - double + Orientation of the view in degrees. These are specified using the + right-hand rule, so a positive heading turns the view to the left, + a positive roll rolls the view to the left. + + perspective + This node is one way of specifying the viewing volume camera + parameters. It corresponds to the OpenGL gluPerspective function. + + fovy-deg - double + The vertical field-of-view + + aspect-ratio - double + Aspect ratio of camera rectangle (not the ratio between the + vertical and horizontal fields of view). + + near, far - double + The near and far planes, in meters from the camera eye point. Note + that FlightGear assumes that the far plane is far away, currently + 120km. The far plane specified here will be respected, but the sky + and other background elements may not be drawn if the view plane is + closer than 120km. + + offset-x, offset-y - double + Offsets of the viewing volume specified by the other parameters in + the near plane, in meters. + + frustum + This specifies the perspective viewing volume using values for the near + and far planes and coordinates of the viewing rectangle in the near + plane. + + left, bottom - double + right, top - double + The coordinates of the viewing rectangle. + + near, far - double + The near and far planes, in meters from the camera eye point. + + ortho + This specifies an orthographic view. The parameters are the sames as + the frustum node's. + + gui + This is a special camera node that displays the 2D GUI. + + viewport + This specifies the position and dimensions of the GUI within a + window, *however* at the moment the origin must be at 0,0. + +Here's an example that uses a single window mapped across 3 +displays. The displays are in a video wall configuration in a +horizontal row. + + + + + + + wide + + 0 + 0 + 3840 + 1024 + false + + + + wide + + + 0 + 0 + 1280 + 1024 + + + 0 + + + 0.133 + -0.133 + -.5004 + -.1668 + 0.4 + 120000.0 + + + + + wide + + + 1280 + 0 + 1280 + 1024 + + + 0 + + + 0.133 + -0.133 + -.1668 + .1668 + 0.4 + 120000.0 + + + + + wide + + + 2560 + 0 + 1280 + 1024 + + + 0 + + + 0.133 + -0.133 + .1668 + .5004 + 0.4 + 120000.0 + + + + + wide + + + + + + + +Here's a complete example that uses a seperate window on each +display. The displays are arranged in a shallow arc with the left and +right displays at a 45.3 degree angle to the center display because, +at the assumed screen dimensions, the horizontal field of view of one +display is 45.3 degrees. Each camera has its own window definition; +the center window is given the name "main" so that the GUI definition +can refer to it. Note that the borders of the displays are not +accounted for. + + + + + + + + + 0 + 0 + true + + + 45.3 + + + 0.133 + -0.133 + -.1668 + .1668 + 0.4 + 120000.0 + + + + + main + + 0 + 1 + true + + + 0 + + + 0.133 + -0.133 + -.1668 + .1668 + 0.4 + 120000.0 + + + + + + 0 + 2 + true + + + -45.3 + + + 0.133 + -0.133 + -.1668 + .1668 + 0.4 + 120000.0 + + + + + main + + + + + +