1 /** 2 * Copyright 2010 JogAmp Community. All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without modification, are 5 * permitted provided that the following conditions are met: 6 * 7 * 1. Redistributions of source code must retain the above copyright notice, this list of 8 * conditions and the following disclaimer. 9 * 10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 11 * of conditions and the following disclaimer in the documentation and/or other materials 12 * provided with the distribution. 13 * 14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED 15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR 17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 23 * 24 * The views and conclusions contained in the software and documentation are those of the 25 * authors and should not be interpreted as representing official policies, either expressed 26 * or implied, of JogAmp Community. 27 */ 28 29 package com.jogamp.opengl; 30 31 /** 32 * An animator control interface, 33 * which implementation may drive a {@link com.jogamp.opengl.GLAutoDrawable} animation. 34 */ 35 public interface GLAnimatorControl extends FPSCounter { 36 /** 37 * A {@link GLAnimatorControl#setUncaughtExceptionHandler(UncaughtExceptionHandler) registered} 38 * {@link UncaughtExceptionHandler} instance is invoked when an {@link GLAnimatorControl animator} abruptly {@link #stop() stops} 39 * due to an uncaught exception from one of its {@link GLAutoDrawable}s. 40 * @see #uncaughtException(GLAnimatorControl, GLAutoDrawable, Throwable) 41 * @see GLAnimatorControl#setUncaughtExceptionHandler(UncaughtExceptionHandler) 42 * @since 2.2 43 */ 44 public static interface UncaughtExceptionHandler { 45 /** 46 * Method invoked when the given {@link GLAnimatorControl} is {@link GLAnimatorControl#stop() stopped} due to the 47 * given uncaught exception happened on the given {@link GLAutoDrawable}. 48 * <p> 49 * The animator thread can still be retrieved via {@link GLAnimatorControl#getThread()}. 50 * </p> 51 * <p> 52 * All {@link GLAnimatorControl} states already reflect its stopped state. 53 * </p> 54 * <p> 55 * After this handler method is called, the {@link GLAnimatorControl} is stopped. 56 * </p> 57 * <p> 58 * Any exception thrown by this method will be ignored. 59 * </p> 60 * @param animator the {@link GLAnimatorControl} 61 * @param drawable the causing {@link GLAutoDrawable}, 62 * may be {@code null} in case {@link Throwable} caused unrelated to any {@link GLAutoDrawable}. 63 * @param cause the uncaught exception 64 * @see GLAnimatorControl#setUncaughtExceptionHandler(UncaughtExceptionHandler) 65 * @since 2.2 66 */ uncaughtException(final GLAnimatorControl animator, final GLAutoDrawable drawable, final Throwable cause)67 void uncaughtException(final GLAnimatorControl animator, final GLAutoDrawable drawable, final Throwable cause); 68 } 69 70 /** 71 * Indicates whether this animator has been {@link #start() started}. 72 * 73 * @see #start() 74 * @see #stop() 75 * @see #isPaused() 76 * @see #pause() 77 * @see #resume() 78 */ isStarted()79 boolean isStarted(); 80 81 /** 82 * Indicates whether this animator {@link #isStarted() is started} and {@link #isPaused() is not paused}. 83 * 84 * @see #start() 85 * @see #stop() 86 * @see #pause() 87 * @see #resume() 88 */ isAnimating()89 boolean isAnimating(); 90 91 /** 92 * Indicates whether this animator {@link #isStarted() is started} 93 * and either {@link #pause() manually paused} or paused 94 * automatically due to no {@link #add(GLAutoDrawable) added} {@link GLAutoDrawable}s. 95 * 96 * @see #start() 97 * @see #stop() 98 * @see #pause() 99 * @see #resume() 100 */ isPaused()101 boolean isPaused(); 102 103 /** 104 * @return The animation thread if running, otherwise null. 105 * 106 * @see #start() 107 * @see #stop() 108 */ getThread()109 Thread getThread(); 110 111 /** 112 * Starts this animator, if not running. 113 * <p> 114 * In most situations this method blocks until 115 * completion, except when called from the animation thread itself 116 * or in some cases from an implementation-internal thread like the 117 * AWT event queue thread. 118 * </p> 119 * <p> 120 * Note that an animator w/o {@link #add(GLAutoDrawable) added drawables} 121 * will be paused automatically. 122 * </p> 123 * <p> 124 * If started, all counters (time, frames, ..) are reset to zero. 125 * </p> 126 * 127 * @return true is started due to this call, 128 * otherwise false, ie started already or unable to start. 129 * 130 * @see #stop() 131 * @see #isAnimating() 132 * @see #isPaused() 133 * @see #getThread() 134 */ start()135 boolean start(); 136 137 /** 138 * Stops this animator. 139 * <p> 140 * In most situations this method blocks until 141 * completion, except when called from the animation thread itself 142 * or in some cases from an implementation-internal thread like the 143 * AWT event queue thread. 144 * </p> 145 * 146 * @return true is stopped due to this call, 147 * otherwise false, ie not started or unable to stop. 148 * 149 * @see #start() 150 * @see #isAnimating() 151 * @see #getThread() 152 */ stop()153 boolean stop(); 154 155 /** 156 * Pauses this animator. 157 * <p> 158 * In most situations this method blocks until 159 * completion, except when called from the animation thread itself 160 * or in some cases from an implementation-internal thread like the 161 * AWT event queue thread. 162 * </p> 163 * 164 * @return false if not started, already paused or failed to pause, otherwise true 165 * 166 * @see #resume() 167 * @see #isAnimating() 168 */ pause()169 boolean pause(); 170 171 /** 172 * Resumes animation if paused. 173 * <p> 174 * In most situations this method blocks until 175 * completion, except when called from the animation thread itself 176 * or in some cases from an implementation-internal thread like the 177 * AWT event queue thread. 178 * </p> 179 * <p> 180 * If resumed, all counters (time, frames, ..) are reset to zero. 181 * </p> 182 * 183 * @return false if not started, not paused or unable to resume, otherwise true 184 * 185 * @see #pause() 186 * @see #isAnimating() 187 */ resume()188 boolean resume(); 189 190 /** 191 * Adds a drawable to this animator's list of rendering drawables. 192 * <p> 193 * This allows the animator thread to become {@link #isAnimating() animating}, 194 * in case the first drawable is added and the animator {@link #isStarted() is started}. 195 * </p> 196 * 197 * @param drawable the drawable to be added 198 * @throws IllegalArgumentException if drawable was already added to this animator 199 */ add(GLAutoDrawable drawable)200 void add(GLAutoDrawable drawable); 201 202 /** 203 * Removes a drawable from the animator's list of rendering drawables. 204 * <p> 205 * This method should get called in case a drawable becomes invalid, 206 * and will not be recovered. 207 * </p> 208 * <p> 209 * This allows the animator thread to become {@link #isAnimating() not animating}, 210 * in case the last drawable has been removed. 211 * </p> 212 * 213 * @param drawable the drawable to be removed 214 * @throws IllegalArgumentException if drawable was not added to this animator 215 */ remove(GLAutoDrawable drawable)216 void remove(GLAutoDrawable drawable); 217 218 /** 219 * Returns the {@link UncaughtExceptionHandler} invoked when this {@link GLAnimatorControl animator} abruptly {@link #stop() stops} 220 * due to an uncaught exception from one of its {@link GLAutoDrawable}s. 221 * <p> 222 * Default is <code>null</code>. 223 * </p> 224 * @since 2.2 225 */ getUncaughtExceptionHandler()226 UncaughtExceptionHandler getUncaughtExceptionHandler(); 227 228 /** 229 * Set the handler invoked when this {@link GLAnimatorControl animator} abruptly {@link #stop() stops} 230 * due to an uncaught exception from one of its {@link GLAutoDrawable}s. 231 * @param handler the {@link UncaughtExceptionHandler} to use as this {@link GLAnimatorControl animator}'s uncaught exception 232 * handler. Pass <code>null</code> to unset the handler. 233 * @see UncaughtExceptionHandler#uncaughtException(GLAnimatorControl, GLAutoDrawable, Throwable) 234 * @since 2.2 235 */ setUncaughtExceptionHandler(final UncaughtExceptionHandler handler)236 void setUncaughtExceptionHandler(final UncaughtExceptionHandler handler); 237 } 238