src/com/jme/app/FixedFramerateGame.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 // $Id$
  33 package com.jme.app;
  34
  35 import java.util.logging.Level;
  36 import java.util.logging.Logger;
  37
  38 import com.jme.input.InputSystem;
  39 import com.jme.util.Timer;
  40
  41 /**
  42  * A game that attempts to run at a fixed frame rate.
  43  * <p>
  44  * The main loop makes every effort to render at the specified rate, however
  45  * this is not guaranteed and the frame rate may dip below the desired value.
  46  * The game logic is updated at the same rate as the rendering; for example,
  47  * if the rendering is running at 60 frames per second, the logic will also
  48  * be updated 60 times per second.
  49  * <p>
  50  * Limiting the frame rate of the game is useful for playing nice with the
  51  * underlying operating system. That is, if the game loop is left unchecked,
  52  * it tends to use up 100% of the CPU cycles; while this may be fine for
  53  * fullscreen applications (as it will yield to important processes) it can
  54  * cause issues with applications running in a normal window.
  55  * <p>
  56  * If no frame rate is specified, the game will run at 60 frames per second.
  57  * <p>
  58  * Note that {@link #setFrameRate(int)} cannot be called prior to calling
  59  * {@link #start()} or a {@code NullPointerException} will be thrown.
  60  *
  61  * @author Eric Woroshow
  62  * @version $Revision$, $Date$
  63  */
  64 public abstract class FixedFramerateGame extends AbstractGame {
  65     private static final Logger logger = Logger
  66             .getLogger(FixedFramerateGame.class.getName());
  67
  68     //Frame-rate managing stuff
  69     private Timer timer;
  70
  71     private int frames = 0;
  72
  73     private long startTime;
  74
  75     private long preferredTicksPerFrame;
  76
  77     private long frameStartTick;
  78
  79     private long frameDurationTicks;
  80
  81     /**
  82      * Set preferred frame rate. The main loop will make every attempt to
  83      * maintain the given frame rate. This should not be called prior to the
  84      * application being <code>start()</code> -ed.
  85      *
  86      * @param fps
  87      *            the desired frame rate in frames per second
  88      */
  89     public void setFrameRate(int fps) {
  90         if (fps <= 0) {
  91                 throw new IllegalArgumentException(
  92                         "Frames per second cannot be less than one.");
  93         }
  94
  95         logger.info("Attempting to run at " + fps + " fps.");
  96         preferredTicksPerFrame = timer.getResolution() / fps;
  97     }
  98
  99     /**
 100      * Gets the current frame rate.
 101      *
 102      * @return the current number of frames rendering per second
 103      */
 104     public float getFramesPerSecond() {
 105         float time = (timer.getTime() - startTime)
 106                 / (float) timer.getResolution();
 107         float fps = frames / time;
 108
 109         startTime = timer.getTime();
 110         frames = 0;
 111
 112         return fps;
 113     }
 114
 115     /**
 116      * <code>startFrame</code> begin monitoring the current frame. This method
 117      * should be called every frame before update and drawing code.
 118      */
 119     private void startFrame() {
 120         frameStartTick = timer.getTime();
 121     }
 122
 123     /**
 124      * <code>endFrame</code> ends the current frame. Pads any excess time in
 125      * the frame by sleep()-ing the thread in order to maintain the desired
 126      * frame rate. No attempt is made to rectify frames which have taken too
 127      * much time.
 128      */
 129     private void endFrame() {
 130         frames++;
 131
 132         frameDurationTicks = timer.getTime() - frameStartTick;
 133
 134         while (frameDurationTicks < preferredTicksPerFrame) {
 135             long sleepTime = ((preferredTicksPerFrame - frameDurationTicks) * 1000)
 136                     / timer.getResolution();
 137
 138             try {
 139                 Thread.sleep(sleepTime);
 140             } catch (InterruptedException e) {
 141                 logger.warning("Error sleeping during main loop.");
 142             }
 143
 144             frameDurationTicks = timer.getTime() - frameStartTick;
 145         }
 146     }
 147
 148     /**
 149      * Render and update logic at a specified fixed rate.
 150      */
 151     public final void start() {
 152         logger.info("Application started.");
 153         try {
 154             getAttributes();
 155
 156             initSystem();
 157
 158             assertDisplayCreated();
 159
 160             timer = Timer.getTimer();
 161             setFrameRate(60); //default to 60 fps
 162
 163             initGame();
 164
 165             //main loop
 166             while (!finished && !display.isClosing()) {
 167                 startFrame();
 168
 169                 //handle input events prior to updating the scene
 170                 // - some applications may want to put this into update of the game state
 171                 InputSystem.update();
 172
 173                 //update game state, do not use interpolation parameter
 174                 update(-1.0f);
 175
 176                 //render, do not use interpolation parameter
 177                 render(-1.0f);
 178
 179                 //swap buffers
 180                 display.getRenderer().displayBackBuffer();
 181
 182                 endFrame();
 183
 184                 Thread.yield();
 185             }
 186
 187         } catch (Throwable t) {
 188             logger.logp(Level.SEVERE, this.getClass().toString(), "start()", "Exception in game loop", t);
 189         } finally {
 190             cleanup();
 191         }
 192         logger.info("Application ending.");
 193
 194         display.reset();
 195         quit();
 196     }
 197
 198     /**
 199      * Quits the program abruptly using <code>System.exit</code>.
 200      *
 201      * @see AbstractGame#quit()
 202      */
 203     protected void quit() {
 204         if (display != null) {
 205             display.close();
 206         }
 207         System.exit(0);
 208     }
 209
 210     /**
 211      * @param interpolation
 212      *            unused in this implementation
 213      * @see AbstractGame#update(float interpolation)
 214      */
 215     protected abstract void update(float interpolation);
 216
 217     /**
 218      * @param interpolation
 219      *            unused in this implementation
 220      * @see AbstractGame#render(float interpolation)
 221      */
 222     protected abstract void render(float interpolation);
 223
 224     /**
 225      * @see AbstractGame#initSystem()
 226      */
 227     protected abstract void initSystem();
 228
 229     /**
 230      * @see AbstractGame#initGame()
 231      */
 232     protected abstract void initGame();
 233
 234     /**
 235      * @see AbstractGame#reinit()
 236      */
 237     protected abstract void reinit();
 238
 239     /**
 240      * @see AbstractGame#cleanup()
 241      */
 242     protected abstract void cleanup();
 243 }