Multiple viewports to display one world

Table of Contents

1. Introduction
2. Usage
3. Sound listener
4. Examples

1. Introduction

It is possible to have multiple viewports visible at the same time. As TCastleViewport is a regular user interface control, you can add as many viewports as you like on a particular TCastleView. And you can configure the size and position of each viewport.

These viewports may even display the same world (but from different cameras). This feature is very useful for split-screen games. Or if you want to show additional view of the world (e.g. from the camera attached to a missile, or from camera observing the world from the top).

2. Usage

To use this feature, just set the Items property of one viewport to Items from another viewport. Like this:

NewViewport.Items := ExistingViewport.Items;

Note	You cannot (yet) do this from the CGE editor. In the editor you can set multiple viewports and their cameras, but you cannot yet make them share the same items.

Moreover, when sharing Items across multiple viewports, all the cameras (from all the viewports) should also be added to the same Items (TCastleRootTransform). You always want to keep the connection that "the camera used by viewport, set in Viewport.Camera, is also part of the Viewport.Items ".

This usually means you should extend above example to remove NewViewport.Camera from the old world and add it to the new one. Like this:

NewViewport.Items.Remove(NewViewport.Camera);
NewViewport.Items := ExistingViewport.Items;
NewViewport.Items.Add(NewViewport.Camera);

3. Sound listener

If you use 3D sound in your application, for example through the TCastleSoundSource behavior, you need to consider which viewport’s camera should control the "sound listener". The sound listener determines the position and orientation of the "ears" in the 3D sound model, that determine which sounds (and how loud) go to left or right speaker.

To do this, make sure TCastleViewport.UpdateSoundListener is set to true on one and only one TCastleViewport instance.

4. Examples

zombie_fighter example. The viewport setup there is described in the chapter about user interface.
multiple_viewports example. Shows a window split into 4 viewports, all showing the same scene, but with a bit different effects.
fps_game example. Shows using additional viewport for an "overview" camera looking at map from the top.

To improve this documentation just edit this page and create a pull request to cge-www repository.