src/com/jme/renderer/pass/Pass.java

   1 /*
   2  * Copyright (c) 2003-2009 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.jme.renderer.pass;
  34
  35 import java.io.Serializable;
  36 import java.util.ArrayList;
  37
  38 import com.jme.renderer.RenderContext;
  39 import com.jme.renderer.Renderer;
  40 import com.jme.scene.Spatial;
  41 import com.jme.scene.state.RenderState;
  42 import com.jme.system.DisplaySystem;
  43
  44 /**
  45  * <code>Pass</code> encapsulates logic necessary for rendering one or more
  46  * steps in a multipass technique.
  47  *
  48  * Rendering:
  49  *
  50  *      When renderPass is called, a check is first made to see if the
  51  *      pass isEnabled(). Then any states set on this pass are enforced via
  52  *      Spatial.enforceState(RenderState). This is useful for doing things such
  53  *      as causing this pass to be blended to a previous pass via enforcing an
  54  *      BlendState, etc.  Next, doRender(Renderer) is called to do the actual
  55  *      rendering work.  Finally, any enforced states set before this pass was
  56  *      run are restored.
  57  *
  58  * @author Joshua Slack
  59  * @version $Id: Pass.java,v 1.9 2007/08/14 13:41:40 rherlitz Exp $
  60  */
  61 public abstract class Pass implements Serializable {
  62
  63         private static final long serialVersionUID = -2608939114161492853L;
  64
  65         /** list of spatials registered with this pass. */
  66     protected ArrayList<Spatial> spatials = new ArrayList<Spatial>();
  67
  68     /** if false, pass will not be updated or rendered. */
  69     protected boolean enabled = true;
  70
  71     /** offset params to use to differentiate multiple passes of the same scene in the zbuffer. */
  72     protected float zFactor;
  73     protected float zOffset;
  74
  75     /**
  76      * RenderStates registered with this pass - if a given state is not null it
  77      * overrides the corresponding state set during rendering.
  78      */
  79     protected RenderState[] passStates = new RenderState[RenderState.StateType.values().length];
  80
  81     /** a place to internally save previous states setup before rendering this pass */
  82     protected RenderState[] savedStates = new RenderState[RenderState.StateType.values().length];
  83
  84     protected RenderContext<?> context = null;
  85
  86     /** if enabled, set the states for this pass and then render. */
  87     public final void renderPass(Renderer r) {
  88         if (!enabled) return;
  89         context  = DisplaySystem.getDisplaySystem().getCurrentContext();
  90         applyPassStates();
  91         r.setPolygonOffset(zFactor, zOffset);
  92         doRender(r);
  93         r.clearPolygonOffset();
  94         resetOldStates();
  95         context = null;
  96     }
  97
  98     /**
  99      * Enforce a particular state. In other words, the given state will override
 100      * any state of the same type set on a scene object. Remember to clear the
 101      * state when done enforcing. Very useful for multipass techniques where
 102      * multiple sets of states need to be applied to a scenegraph drawn multiple
 103      * times.
 104      *
 105      * @param state
 106      *            state to enforce
 107      */
 108     public void setPassState(RenderState state) {
 109
 110         passStates[state.getStateType().ordinal()] = state;
 111     }
 112
 113     /**
 114      * Returns the requested RenderState that this Pass currently has set or
 115      * null if none is set.
 116      *
 117      * @param type
 118      *            the renderstate type to retrieve
 119      * @return a renderstate at the given position or null
 120      * @deprecated As of 2.0, use {@link #getRenderState(com.jme.scene.state.RenderState.StateType)} instead.
 121      */
 122     public RenderState getRenderState(int type) {
 123         return passStates != null ? passStates[type] : null;
 124     }
 125
 126     /**
 127      * Returns the requested RenderState that this Pass currently has set or
 128      * null if none is set.
 129      *
 130      * @param type
 131      *            the renderstate type to retrieve
 132      * @return a renderstate at the given position or null
 133      */
 134     public RenderState getRenderState(RenderState.StateType type) {
 135
 136         return passStates != null ? passStates[type.ordinal()] : null;
 137     }
 138
 139     /**
 140      * Clears an enforced render state index by setting it to null. This allows
 141      * object specific states to be used.
 142      *
 143      * @param renderStateType
 144      *            The type of RenderState to clear enforcement on.
 145      * @deprecated As of 2.0, use {@link #clearPassState(com.jme.scene.state.RenderState.StateType)} instead.
 146      */
 147     public void clearPassState(int renderStateType) {
 148         passStates[renderStateType] = null;
 149     }
 150
 151     /**
 152      * Clears an enforced render state by setting it to null. This allows
 153      * object specific states to be used.
 154      *
 155      * @param type
 156      *            The type of RenderState to clear enforcement on.
 157      */
 158     public void clearPassState(RenderState.StateType type) {
 159         passStates[type.ordinal()] = null;
 160     }
 161
 162     /**
 163      * sets all enforced states to null.
 164      *
 165      * @see RenderContext#clearEnforcedState(int)
 166      */
 167     public void clearPassStates() {
 168         for (int i = 0; i < passStates.length; i++)
 169             passStates[i] = null;
 170     }
 171
 172     protected void applyPassStates() {
 173         for (int x = RenderState.StateType.values().length; --x >= 0;) {
 174             if (passStates[x] != null) {
 175                 savedStates[x] = context.enforcedStateList[x];
 176                 context.enforcedStateList[x] = passStates[x];
 177             }
 178         }
 179     }
 180
 181     protected abstract void doRender(Renderer r);
 182
 183     protected void resetOldStates() {
 184         for (int x = RenderState.StateType.values().length; --x >= 0;) {
 185             if (passStates[x] != null) {
 186                 context.enforcedStateList[x] = savedStates[x];
 187             }
 188         }
 189     }
 190
 191     /** if enabled, call doUpdate to update information for this pass. */
 192     public final void updatePass(float tpf) {
 193         if (!enabled) return;
 194         doUpdate(tpf);
 195     }
 196
 197     protected void doUpdate(float tpf) {
 198     }
 199
 200
 201     public void add(Spatial toAdd) {
 202         spatials.add(toAdd);
 203     }
 204
 205     public Spatial get(int index) {
 206         return spatials.get(index);
 207     }
 208
 209     public boolean contains(Spatial s) {
 210         return spatials.contains(s);
 211     }
 212
 213     public boolean remove(Spatial toRemove) {
 214         return spatials.remove(toRemove);
 215     }
 216
 217
 218     public void removeAll() {
 219         spatials.clear();
 220     }
 221
 222     public int size() {
 223         return spatials.size();
 224     }
 225
 226     /**
 227      * @return Returns the enabled.
 228      */
 229     public boolean isEnabled() {
 230         return enabled;
 231     }
 232
 233     /**
 234      * @param enabled The enabled to set.
 235      */
 236     public void setEnabled(boolean enabled) {
 237         this.enabled = enabled;
 238     }
 239
 240     /**
 241      * @return Returns the zFactor.
 242      */
 243     public float getZFactor() {
 244         return zFactor;
 245     }
 246
 247     /**
 248      * Sets the polygon offset param - factor - for this Pass.
 249      *
 250      * @param factor
 251      *            The zFactor to set.
 252      */
 253     public void setZFactor(float factor) {
 254         zFactor = factor;
 255     }
 256
 257     /**
 258      * @return Returns the zOffset.
 259      */
 260     public float getZOffset() {
 261         return zOffset;
 262     }
 263
 264     /**
 265      * Sets the polygon offset param - offset - for this Pass.
 266      *
 267      * @param offset
 268      *            The zOffset to set.
 269      */
 270     public void setZOffset(float offset) {
 271         zOffset = offset;
 272     }
 273
 274     public void cleanUp() {
 275     }
 276
 277 }