JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLAnimatorControl.java
Go to the documentation of this file.
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
29package com.jogamp.opengl;
30
31/**
32 * An animator control interface,
33 * which implementation may drive a {@link com.jogamp.opengl.GLAutoDrawable} animation.
34 */
35public 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 */
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 */
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 */
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 */
101 boolean isPaused();
102
103 /**
104 * @return The animation thread if running, otherwise null.
105 *
106 * @see #start()
107 * @see #stop()
108 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
237}
FPSCounter feature.
Definition: FPSCounter.java:37
A registered UncaughtExceptionHandler instance is invoked when an animator abruptly stops due to an u...
void uncaughtException(final GLAnimatorControl animator, final GLAutoDrawable drawable, final Throwable cause)
Method invoked when the given GLAnimatorControl is stopped due to the given uncaught exception happen...
An animator control interface, which implementation may drive a com.jogamp.opengl....
boolean start()
Starts this animator, if not running.
boolean isPaused()
Indicates whether this animator is started and either manually paused or paused automatically due to ...
boolean resume()
Resumes animation if paused.
boolean isAnimating()
Indicates whether this animator is started and is not paused.
UncaughtExceptionHandler getUncaughtExceptionHandler()
Returns the UncaughtExceptionHandler invoked when this animator abruptly stops due to an uncaught exc...
boolean stop()
Stops this animator.
boolean pause()
Pauses this animator.
void setUncaughtExceptionHandler(final UncaughtExceptionHandler handler)
Set the handler invoked when this animator abruptly stops due to an uncaught exception from one of it...
boolean isStarted()
Indicates whether this animator has been started.
void add(GLAutoDrawable drawable)
Adds a drawable to this animator's list of rendering drawables.
A higher-level abstraction than GLDrawable which supplies an event based mechanism (GLEventListener) ...