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