sdk/jme3-documentation/src/com/jme3/gde/docs/jme3/advanced/multiple_camera_views.html

   1
   2 <h1><a>Multiple Camera Views</a></h1>
   3 <div>
   4
   5 <p>
   6
   7 You can split the screen and look into the 3D scene from different camera angles at the same time. E.g. you can have two rootnodes with different scene graphs, and two viewPorts, each of which can only see its own subset of the scene with its own subset of port-processing filters, so you get two very different views of the scene.
   8 </p>
   9
  10 <p>
  11 The packages used in this example are <code>com.jme3.renderer.Camera</code> and <code>com.jme3.renderer.ViewPort</code>. You can get the full sample code here: <object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer"><param name="content" value="http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/renderer/TestMultiViews.java"><param name="text" value="<html><u>TestMultiViews.java</u></html>"><param name="textColor" value="blue"></object>
  12 </p>
  13
  14 </div>
  15 <!-- EDIT1 SECTION "Multiple Camera Views" [1-650] -->
  16 <h2><a>How to resize and Position ViewPorts</a></h2>
  17 <div>
  18
  19 <p>
  20
  21 The default viewPort is as big as the window. If you have several, they must be of different sizes, either overlapping or adjacent to one another. How do you tell jME which of the ViewPorts should appear where on the screen, and how big they should be?
  22 </p>
  23
  24 <p>
  25 Imagine the window as a 1.0f x 1.0f rectangle. The default cam&#039;s viewPort is set to
  26
  27 </p>
  28 <pre>cam.setViewPort&#40;0f, 1f, 0f, 1f&#41;;</pre>
  29
  30 <p>
  31
  32 This setting makes the ViewPort take up the whole rectangle.
  33 </p>
  34
  35 <p>
  36 The four values are read in the following order:
  37 </p>
  38 <pre>cam.setViewPort&#40;x1,x2 , y1,y2&#41;;</pre>
  39 <ul>
  40 <li><div> <strong>X-axis</strong> from left to right</div>
  41 </li>
  42 <li><div> <strong>Y-axis</strong> upwards from bottom to top</div>
  43 </li>
  44 </ul>
  45
  46 <p>
  47
  48 Here are a few examples:
  49
  50 </p>
  51 <pre>cam1.setViewPort&#40; 0.0f , 1.0f   ,   0.0f , 1.0f &#41;;
  52 cam2.setViewPort&#40; 0.5f , 1.0f   ,   0.0f , 0.5f &#41;;</pre>
  53
  54 <p>
  55 These viewport parameters are, (in this order) the left-right extend, and the bottom-top extend of a views&#039;s rectangle on the screen.
  56 </p>
  57 <pre>0.0 , 1.0       1.0 , 1.0
  58        +-----+-----+
  59        |cam1       |
  60        |           |
  61        |     +-----+
  62        |     |     |
  63        |     |cam2 |
  64        +-----+-----+
  65 0.0 , 0.0       1.0 , 0.0</pre>
  66
  67 <p>
  68 Example: Cam2&#039;s rectangle is int he bottom right: It extends from mid (x1=0.5f) bottom (y1=0.0f), to right (x2=1.0f) mid (y2=0.5f)
  69 </p>
  70
  71 <p>
  72 <p><div>If you scale the views in a way so that the aspect ratio of a ViewPort is different than the window&#039;s aspect ratio, then the ViewPort appears distorted. In these cases, you must recreate (not clone) the ViewPort&#039;s cam object with the right aspect ratio. For example: <code>Camera cam5 = new Camera(100,100);</code>
  73 </div></p>
  74 </p>
  75
  76 </div>
  77 <!-- EDIT2 SECTION "How to resize and Position ViewPorts" [651-2294] -->
  78 <h2><a>Four-Time Split Screen</a></h2>
  79 <div>
  80
  81 <p>
  82
  83 In this example, you create four views (2x2) with the same aspect ratio as the window, but each is only half the width and height.
  84 </p>
  85
  86 </div>
  87 <!-- EDIT3 SECTION "Four-Time Split Screen" [2295-2463] -->
  88 <h3><a>Set up the First View</a></h3>
  89 <div>
  90
  91 <p>
  92
  93 You use the preconfigured Camera <code>cam</code> and <code>viewPort</code> from <code>SimpleApplication</code> for the first view. It&#039;s in the bottom right.
  94
  95 </p>
  96 <pre>cam.setViewPort&#40;.5f, 1f, 0f, 0.5f&#41;; // Resize the viewPort to half its size, bottom right.</pre>
  97
  98 <p>
  99
 100 Optionally, place the main camera in the scene and rotate it in its start position.
 101
 102 </p>
 103 <pre>cam.setLocation&#40;new Vector3f&#40;3.32f, 4.48f, 4.28f&#41;&#41;;
 104 cam.setRotation&#40;new Quaternion &#40;-0.07f, 0.92f, -0.25f, -0.27f&#41;&#41;;</pre>
 105
 106 </div>
 107 <!-- EDIT4 SECTION "Set up the First View" [2464-2960] -->
 108 <h3><a>Set Up Three More Views</a></h3>
 109 <div>
 110
 111 <p>
 112
 113 Here is the outline for how you create the three other cams and viewPorts (<object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer"><param name="content" value="http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/renderer/TestMultiViews.java"><param name="text" value="<html><u>Full code sample is here</u></html>"><param name="textColor" value="blue"></object>.) In the code snippet, <code>cam_n</code> stand for <code>cam_2</code> - <code>cam_4</code>, respectively, same for <code>view_n</code>.
 114
 115 </p>
 116 <ol>
 117 <li><div> Clone the first cam to reuse its settings</div>
 118 </li>
 119 <li><div> Resize and position the cam&#039;s viewPort with setViewPort().</div>
 120 </li>
 121 <li><div> (Optionally) Move the cameras in the scene and rotate them so they face what you want to see.</div>
 122 </li>
 123 <li><div> Create a ViewPort for each camera</div>
 124 </li>
 125 <li><div> Reset the camera&#039;s enabled statuses</div>
 126 </li>
 127 <li><div> Attach the Node to be displayed to this ViewPort. <br/>
 128 The camera doesn&#039;t have to look at the rootNode, but that is the most common use case.</div>
 129 </li>
 130 </ol>
 131
 132 <p>
 133
 134 Here is the abstract code sample for camera <code>n</code>:
 135
 136 </p>
 137 <pre>Camera cam_n    = cam.clone&#40;&#41;;
 138 cam_n.setViewPort&#40;...&#41;; // resize the viewPort
 139 cam_n.setLocation&#40;new Vector3f&#40;...&#41;&#41;;
 140 cam_n.setRotation&#40;new Quaternion&#40;...&#41;&#41;;
 141 &nbsp;
 142 ViewPort view_n = renderManager.createMainView&#40;&quot;View of camera #n&quot;, cam_n&#41;;
 143 view_n.setClearEnabled&#40;true&#41;;
 144 view_n.attachScene&#40;rootNode&#41;;
 145 view_n.setBackgroundColor&#40;ColorRGBA.Black&#41;;</pre>
 146
 147 <p>
 148 To visualize what you do, use the following drawing of the viewport positions:
 149 </p>
 150 <pre>0.0 , 1.0       1.0 , 1.0
 151        +-----+-----+
 152        |     |     |
 153        |cam3 |cam4 |
 154        +-----------+
 155        |     |     |
 156        |cam2 |cam1 |
 157        +-----+-----+
 158 0.0 , 0.0       1.0 , 0.0</pre>
 159
 160 <p>
 161 This are the lines of code that set the four cameras to create a four-times split screen.
 162 </p>
 163 <pre>cam1.setViewPort&#40; 0.5f , 1.0f  ,  0.0f , 0.5f&#41;;
 164 ...
 165 cam2.setViewPort&#40; 0.0f , 0.5f  ,  0.0f , 0.5f&#41;;
 166 ...
 167 cam3.setViewPort&#40; 0.0f , 0.5f  ,  0.5f , 1.0f&#41;;
 168 ...
 169 cam4.setViewPort&#40; 0.5f , 1.0f  ,  0.5f , 1.0f&#41;;</pre>
 170
 171 </div>
 172 <!-- EDIT5 SECTION "Set Up Three More Views" [2961-4771] -->
 173 <h2><a>Picture in Picture</a></h2>
 174 <div>
 175
 176 <p>
 177
 178 The following code snippet sets up two views, one covers the whole screen, and the second is a small view in the top center.
 179 </p>
 180 <pre>       +-----+-----+
 181        |   |cam|   |
 182        |   | 2 |   |
 183        +   +---+   +
 184        |           |
 185        |    cam    |
 186        +-----+-----+</pre>
 187 <pre>// Setup first full-window view
 188 cam.setViewPort&#40;0f, 1f, 0f, 1f&#41;;
 189 cam.setLocation&#40;new Vector3f&#40;3.32f, 4.48f, 4.28f&#41;&#41;;
 190 cam.setRotation&#40;new Quaternion&#40;-0.07f, 0.92f, -0.25f, -0.27f&#41;&#41;;
 191 &nbsp;
 192 // Setup second, smaller PiP view
 193 Camera cam2 = cam.clone&#40;&#41;;
 194 cam2.setViewPort&#40;.4f, .6f, 0.8f, 1f&#41;;
 195 cam2.setLocation&#40;new Vector3f&#40;-0.10f, 1.57f, 4.81f&#41;&#41;;
 196 cam2.setRotation&#40;new Quaternion&#40;0.00f, 0.99f, -0.04f, 0.02f&#41;&#41;;
 197 ViewPort viewPort2 = renderManager.createMainView&#40;&quot;PiP&quot;, cam2&#41;;
 198 viewPort2.setClearFlags&#40;true, true, true&#41;;
 199 viewPort2.attachScene&#40;rootNode&#41;;</pre>
 200
 201 </div>
 202 <!-- EDIT6 SECTION "Picture in Picture" [4772-5652] -->
 203 <h2><a>ViewPort Settings</a></h2>
 204 <div>
 205
 206 <p>
 207
 208 You can customize the camera and the viewPort of each view individually. For example, each view can have a different background color:
 209
 210 </p>
 211 <pre>viewPort.setBackgroundColor&#40;ColorRGBA.Blue&#41;;</pre>
 212
 213 <p>
 214
 215 You have full control to determine which Nodes the camera can see! It can see the full rootNode???
 216
 217 </p>
 218 <pre>viewPort1.attachScene&#40;rootNode&#41;;</pre>
 219
 220 <p>
 221
 222 ??? or you can give each camera a special node whose content it can see:
 223
 224 </p>
 225 <pre>viewPort2.attachScene&#40;spookyGhostDetectorNode&#41;;</pre>
 226 <div><span>
 227         <a href="/wiki/doku.php/tag:camera?do=showtag&amp;tag=tag%3Acamera">camera</a>,
 228         <a href="/wiki/doku.php/tag:documentation?do=showtag&amp;tag=tag%3Adocumentation">documentation</a>
 229 </span></div>
 230
 231 </div>
 232 <!-- EDIT7 SECTION "ViewPort Settings" [5653-] -->
 233 <p><em><a href="http://jmonkeyengine.org/wiki/doku.php/jme3:advanced:multiple_camera_views?do=export_xhtmlbody">view online version</a></em></p>