1 /*
2  * Copyright (c) 2009-2012 jMonkeyEngine
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are
7  * met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  *   notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  *   notice, this list of conditions and the following disclaimer in the
14  *   documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
17  *   may be used to endorse or promote products derived from this software
18  *   without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 package com.jme3.renderer;
34 
35 import com.jme3.math.ColorRGBA;
36 import com.jme3.post.SceneProcessor;
37 import com.jme3.renderer.queue.RenderQueue;
38 import com.jme3.scene.Spatial;
39 import com.jme3.texture.FrameBuffer;
40 import java.util.ArrayList;
41 import java.util.List;
42 
43 /**
44  * A <code>ViewPort</code> represents a view inside the display
45  * window or a {@link FrameBuffer} to which scenes will be rendered.
46  * <p>
47  * A viewport has a {@link #ViewPort(java.lang.String, com.jme3.renderer.Camera) camera}
48  * which is used to render a set of {@link #attachScene(com.jme3.scene.Spatial) scenes}.
49  * A view port has a location on the screen as set by the
50  * {@link Camera#setViewPort(float, float, float, float) } method.
51  * By default, a view port does not clear the framebuffer, but it can be
52  * set to {@link #setClearFlags(boolean, boolean, boolean) clear the framebuffer}.
53  * The background color which the color buffer is cleared to can be specified
54  * via the {@link #setBackgroundColor(com.jme3.math.ColorRGBA)} method.
55  * <p>
56  * A ViewPort has a list of {@link SceneProcessor}s which can
57  * control how the ViewPort is rendered by the {@link RenderManager}.
58  *
59  * @author Kirill Vainer
60  *
61  * @see RenderManager
62  * @see SceneProcessor
63  * @see Spatial
64  * @see Camera
65  */
66 public class ViewPort {
67 
68     protected final String name;
69     protected final Camera cam;
70     protected final RenderQueue queue = new RenderQueue();
71     protected final ArrayList<Spatial> sceneList = new ArrayList<Spatial>();
72     protected final ArrayList<SceneProcessor> processors = new ArrayList<SceneProcessor>();
73     protected FrameBuffer out = null;
74 
75     protected final ColorRGBA backColor = new ColorRGBA(0,0,0,0);
76     protected boolean clearDepth = false, clearColor = false, clearStencil = false;
77     private boolean enabled = true;
78 
79     /**
80      * Create a new viewport. User code should generally use these methods instead:<br>
81      * <ul>
82      * <li>{@link RenderManager#createPreView(java.lang.String, com.jme3.renderer.Camera) }</li>
83      * <li>{@link RenderManager#createMainView(java.lang.String, com.jme3.renderer.Camera)  }</li>
84      * <li>{@link RenderManager#createPostView(java.lang.String, com.jme3.renderer.Camera)  }</li>
85      * </ul>
86      *
87      * @param name The name of the viewport. Used for debugging only.
88      * @param cam The camera through which the viewport is rendered. The camera
89      * cannot be swapped to a different one after creating the viewport.
90      */
ViewPort(String name, Camera cam)91     public ViewPort(String name, Camera cam) {
92         this.name = name;
93         this.cam = cam;
94     }
95 
96     /**
97      * Returns the name of the viewport as set in the constructor.
98      *
99      * @return the name of the viewport
100      *
101      * @see #ViewPort(java.lang.String, com.jme3.renderer.Camera)
102      */
getName()103     public String getName() {
104         return name;
105     }
106 
107     /**
108      * Get the list of {@link SceneProcessor scene processors} that were
109      * added to this <code>ViewPort</code>
110      *
111      * @return the list of processors attached to this ViewPort
112      *
113      * @see #addProcessor(com.jme3.post.SceneProcessor)
114      */
getProcessors()115     public List<SceneProcessor> getProcessors(){
116         return processors;
117     }
118 
119     /**
120      * Adds a {@link SceneProcessor} to this ViewPort.
121      * <p>
122      * SceneProcessors that are added to the ViewPort will be notified
123      * of events as the ViewPort is being rendered by the {@link RenderManager}.
124      *
125      * @param processor The processor to add
126      *
127      * @see SceneProcessor
128      */
addProcessor(SceneProcessor processor)129     public void addProcessor(SceneProcessor processor){
130         processors.add(processor);
131     }
132 
133     /**
134      * Removes a {@link SceneProcessor} from this ViewPort.
135      * <p>
136      * The processor will no longer receive events occurring to this ViewPort.
137      *
138      * @param processor The processor to remove
139      *
140      * @see SceneProcessor
141      */
removeProcessor(SceneProcessor processor)142     public void removeProcessor(SceneProcessor processor){
143         processors.remove(processor);
144         processor.cleanup();
145     }
146 
147     /**
148      * Check if depth buffer clearing is enabled.
149      *
150      * @return true if depth buffer clearing is enabled.
151      *
152      * @see #setClearDepth(boolean)
153      */
isClearDepth()154     public boolean isClearDepth() {
155         return clearDepth;
156     }
157 
158     /**
159      * Enable or disable clearing of the depth buffer for this ViewPort.
160      * <p>
161      * By default depth clearing is disabled.
162      *
163      * @param clearDepth Enable/disable depth buffer clearing.
164      */
setClearDepth(boolean clearDepth)165     public void setClearDepth(boolean clearDepth) {
166         this.clearDepth = clearDepth;
167     }
168 
169     /**
170      * Check if color buffer clearing is enabled.
171      *
172      * @return true if color buffer clearing is enabled.
173      *
174      * @see #setClearColor(boolean)
175      */
isClearColor()176     public boolean isClearColor() {
177         return clearColor;
178     }
179 
180     /**
181      * Enable or disable clearing of the color buffer for this ViewPort.
182      * <p>
183      * By default color clearing is disabled.
184      *
185      * @param clearColor Enable/disable color buffer clearing.
186      */
setClearColor(boolean clearColor)187     public void setClearColor(boolean clearColor) {
188         this.clearColor = clearColor;
189     }
190 
191     /**
192      * Check if stencil buffer clearing is enabled.
193      *
194      * @return true if stencil buffer clearing is enabled.
195      *
196      * @see #setClearStencil(boolean)
197      */
isClearStencil()198     public boolean isClearStencil() {
199         return clearStencil;
200     }
201 
202     /**
203      * Enable or disable clearing of the stencil buffer for this ViewPort.
204      * <p>
205      * By default stencil clearing is disabled.
206      *
207      * @param clearStencil Enable/disable stencil buffer clearing.
208      */
setClearStencil(boolean clearStencil)209     public void setClearStencil(boolean clearStencil) {
210         this.clearStencil = clearStencil;
211     }
212 
213     /**
214      * Set the clear flags (color, depth, stencil) in one call.
215      *
216      * @param color If color buffer clearing should be enabled.
217      * @param depth If depth buffer clearing should be enabled.
218      * @param stencil If stencil buffer clearing should be enabled.
219      *
220      * @see #setClearColor(boolean)
221      * @see #setClearDepth(boolean)
222      * @see #setClearStencil(boolean)
223      */
setClearFlags(boolean color, boolean depth, boolean stencil)224     public void setClearFlags(boolean color, boolean depth, boolean stencil){
225         this.clearColor = color;
226         this.clearDepth = depth;
227         this.clearStencil = stencil;
228     }
229 
230     /**
231      * Returns the framebuffer where this ViewPort's scenes are
232      * rendered to.
233      *
234      * @return the framebuffer where this ViewPort's scenes are
235      * rendered to.
236      *
237      * @see #setOutputFrameBuffer(com.jme3.texture.FrameBuffer)
238      */
getOutputFrameBuffer()239     public FrameBuffer getOutputFrameBuffer() {
240         return out;
241     }
242 
243     /**
244      * Sets the output framebuffer for the ViewPort.
245      * <p>
246      * The output framebuffer specifies where the scenes attached
247      * to this ViewPort are rendered to. By default this is <code>null</code>
248      * which indicates the scenes are rendered to the display window.
249      *
250      * @param out The framebuffer to render scenes to, or null if to render
251      * to the screen.
252      */
setOutputFrameBuffer(FrameBuffer out)253     public void setOutputFrameBuffer(FrameBuffer out) {
254         this.out = out;
255     }
256 
257     /**
258      * Returns the camera which renders the attached scenes.
259      *
260      * @return the camera which renders the attached scenes.
261      *
262      * @see Camera
263      */
getCamera()264     public Camera getCamera() {
265         return cam;
266     }
267 
268     /**
269      * Internal use only.
270      */
getQueue()271     public RenderQueue getQueue() {
272         return queue;
273     }
274 
275     /**
276      * Attaches a new scene to render in this ViewPort.
277      *
278      * @param scene The scene to attach
279      *
280      * @see Spatial
281      */
attachScene(Spatial scene)282     public void attachScene(Spatial scene){
283         sceneList.add(scene);
284     }
285 
286     /**
287      * Detaches a scene from rendering.
288      *
289      * @param scene The scene to detach
290      *
291      * @see #attachScene(com.jme3.scene.Spatial)
292      */
detachScene(Spatial scene)293     public void detachScene(Spatial scene){
294         sceneList.remove(scene);
295     }
296 
297     /**
298      * Removes all attached scenes.
299      *
300      * @see #attachScene(com.jme3.scene.Spatial)
301      */
clearScenes()302     public void clearScenes() {
303         sceneList.clear();
304     }
305 
306     /**
307      * Returns a list of all attached scenes.
308      *
309      * @return a list of all attached scenes.
310      *
311      * @see #attachScene(com.jme3.scene.Spatial)
312      */
getScenes()313     public List<Spatial> getScenes(){
314         return sceneList;
315     }
316 
317     /**
318      * Sets the background color.
319      * <p>
320      * When the ViewPort's color buffer is cleared
321      * (if {@link #setClearColor(boolean) color clearing} is enabled),
322      * this specifies the color to which the color buffer is set to.
323      * By default the background color is black without alpha.
324      *
325      * @param background the background color.
326      */
setBackgroundColor(ColorRGBA background)327     public void setBackgroundColor(ColorRGBA background){
328         backColor.set(background);
329     }
330 
331     /**
332      * Returns the background color of this ViewPort
333      *
334      * @return the background color of this ViewPort
335      *
336      * @see #setBackgroundColor(com.jme3.math.ColorRGBA)
337      */
getBackgroundColor()338     public ColorRGBA getBackgroundColor(){
339         return backColor;
340     }
341 
342     /**
343      * Enable or disable this ViewPort.
344      * <p>
345      * Disabled ViewPorts are skipped by the {@link RenderManager} when
346      * rendering. By default all ViewPorts are enabled.
347      *
348      * @param enable If the viewport should be disabled or enabled.
349      */
setEnabled(boolean enable)350     public void setEnabled(boolean enable) {
351         this.enabled = enable;
352     }
353 
354     /**
355      * Returns true if the viewport is enabled, false otherwise.
356      * @return true if the viewport is enabled, false otherwise.
357      * @see #setEnabled(boolean)
358      */
isEnabled()359     public boolean isEnabled() {
360         return enabled;
361     }
362 
363 }
364