1 /* GDK - The GIMP Drawing Kit
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * Modified by the GTK+ Team and others 1997-2010. See the AUTHORS
22 * file for a list of people on the GTK+ Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
29 #include "gdkframeclock.h"
33 * @Short_description: Frame clock syncs painting to a window or display
36 * A #GdkFrameClock tells the application when to repaint a window.
37 * This may be synced to the vertical refresh rate of the monitor, for
38 * example. Even when the frame clock uses a simple timer rather than
39 * a hardware-based vertical sync, the frame clock helps because it
40 * ensures everything paints at the same time (reducing the total
41 * number of frames). The frame clock can also automatically stop
42 * painting when it knows the frames will not be visible, or scale back
43 * animation framerates.
45 * #GdkFrameClock is designed to be compatible with an OpenGL-based
46 * implementation or with mozRequestAnimationFrame in Firefox,
49 * A frame clock is idle until someone requests a frame with
50 * gdk_frame_clock_request_frame(). At that time, the frame clock
51 * emits its GdkFrameClock:frame-requested signal if no frame was
54 * At some later time after the frame is requested, the frame clock
55 * MAY indicate that a frame should be painted. To paint a frame the
56 * clock will: Emit GdkFrameClock:before-paint; update the frame time
57 * in the default handler for GdkFrameClock:before-paint; emit
58 * GdkFrameClock:paint; emit GdkFrameClock:after-paint. The app
59 * should paint in a handler for the paint signal.
61 * If a given frame is not painted (the clock is idle), the frame time
62 * should still update to a conceptual "last frame." i.e. the frame
63 * time will keep moving forward roughly with wall clock time.
65 * The frame time is in milliseconds. However, it should not be
66 * thought of as having any particular relationship to wall clock
67 * time. Unlike wall clock time, it "snaps" to conceptual frame times
68 * so is low-resolution; it is guaranteed to never move backward (so
69 * say you reset your computer clock, the frame clock will not reset);
70 * and the frame clock is allowed to drift. For example nicer
71 * results when painting with vertical refresh sync may be obtained by
72 * painting as rapidly as possible, but always incrementing the frame
73 * time by the frame length on each frame. This results in a frame
74 * time that doesn't have a lot to do with wall clock time.
77 G_DEFINE_INTERFACE (GdkFrameClock, gdk_frame_clock, G_TYPE_OBJECT)
88 static guint signals[LAST_SIGNAL];
91 gdk_frame_clock_default_init (GdkFrameClockInterface *iface)
94 * GdkFrameClock::frame-requested:
95 * @clock: the frame clock emitting the signal
97 * This signal is emitted when a frame is not pending, and
98 * gdk_frame_clock_request_frame() is called to request a frame.
100 signals[FRAME_REQUESTED] =
101 g_signal_new (g_intern_static_string ("frame-requested"),
102 GDK_TYPE_FRAME_CLOCK,
106 g_cclosure_marshal_VOID__VOID,
110 * GdkFrameClock::before-paint:
111 * @clock: the frame clock emitting the signal
113 * This signal is emitted immediately before the paint signal and
114 * indicates that the frame time has been updated, and signal
115 * handlers should perform any preparatory work before painting.
117 signals[BEFORE_PAINT] =
118 g_signal_new (g_intern_static_string ("before-paint"),
119 GDK_TYPE_FRAME_CLOCK,
123 g_cclosure_marshal_VOID__VOID,
127 * GdkFrameClock::layout:
128 * @clock: the frame clock emitting the signal
130 * This signal is emitted immediately before the paint signal and
131 * indicates that the frame time has been updated, and signal
132 * handlers should perform any preparatory work before painting.
135 g_signal_new (g_intern_static_string ("layout"),
136 GDK_TYPE_FRAME_CLOCK,
140 g_cclosure_marshal_VOID__VOID,
144 * GdkFrameClock::paint:
145 * @clock: the frame clock emitting the signal
147 * Signal handlers for this signal should paint the window, screen,
148 * or whatever they normally paint.
151 g_signal_new (g_intern_static_string ("paint"),
152 GDK_TYPE_FRAME_CLOCK,
156 g_cclosure_marshal_VOID__VOID,
160 * GdkFrameClock::after-paint:
161 * @clock: the frame clock emitting the signal
163 * This signal is emitted immediately after the paint signal and
164 * allows signal handlers to do anything they'd like to do after
165 * painting has been completed. This is a relatively good time to do
166 * "expensive" processing in order to get it done in between frames.
168 signals[AFTER_PAINT] =
169 g_signal_new (g_intern_static_string ("after-paint"),
170 GDK_TYPE_FRAME_CLOCK,
174 g_cclosure_marshal_VOID__VOID,
179 * gdk_frame_clock_get_frame_time:
182 * Gets the time that should currently be used for animations. Inside
183 * a paint, it's the time used to compute the animation position of
184 * everything in a frame. Outside a paint, it's the time of the
185 * conceptual "previous frame," which may be either the actual
186 * previous frame time, or if that's too old, an updated time.
188 * The returned time has no relationship to wall clock time. It
189 * increases roughly at 1 millisecond per wall clock millisecond, and
190 * it never decreases, but its value is only meaningful relative to
191 * previous frame clock times.
195 * Return value: a timestamp in milliseconds
198 gdk_frame_clock_get_frame_time (GdkFrameClock *clock)
200 g_return_val_if_fail (GDK_IS_FRAME_CLOCK (clock), 0);
202 return GDK_FRAME_CLOCK_GET_IFACE (clock)->get_frame_time (clock);
206 * gdk_frame_clock_request_frame:
209 * Asks the frame clock to paint a frame. The frame
210 * may or may not ever be painted (the frame clock may
211 * stop itself for whatever reason), but the goal in
212 * normal circumstances would be to paint the frame
213 * at the next expected frame time. For example
214 * if the clock is running at 60fps the frame would
215 * ideally be painted within 1000/60=16 milliseconds.
220 gdk_frame_clock_request_frame (GdkFrameClock *clock)
222 g_return_if_fail (GDK_IS_FRAME_CLOCK (clock));
224 GDK_FRAME_CLOCK_GET_IFACE (clock)->request_frame (clock);
228 * gdk_frame_clock_get_frame_requested:
231 * Gets whether a frame paint has been requested but has not been
236 * Return value: TRUE if a frame paint is pending
239 gdk_frame_clock_get_frame_requested (GdkFrameClock *clock)
241 g_return_val_if_fail (GDK_IS_FRAME_CLOCK (clock), FALSE);
243 return GDK_FRAME_CLOCK_GET_IFACE (clock)->get_frame_requested (clock);
247 * gdk_frame_clock_get_frame_time_val:
249 * @timeval: #GTimeVal to fill in with frame time
251 * Like gdk_frame_clock_get_frame_time() but returns the time as a
252 * #GTimeVal which may be handy with some APIs (such as
253 * #GdkPixbufAnimation).
256 gdk_frame_clock_get_frame_time_val (GdkFrameClock *clock,
261 g_return_if_fail (GDK_IS_FRAME_CLOCK (clock));
263 time_ms = gdk_frame_clock_get_frame_time (clock);
265 timeval->tv_sec = time_ms / 1000;
266 timeval->tv_usec = (time_ms % 1000) * 1000;
270 * gdk_frame_clock_frame_requested:
273 * Emits the frame-requested signal. Used in implementations of the
274 * #GdkFrameClock interface.
277 gdk_frame_clock_frame_requested (GdkFrameClock *clock)
279 g_return_if_fail (GDK_IS_FRAME_CLOCK (clock));
281 g_signal_emit (G_OBJECT (clock),
282 signals[FRAME_REQUESTED], 0);
286 * gdk_frame_clock_paint:
289 * Emits the before-paint, paint, and after-paint signals. Used in
290 * implementations of the #GdkFrameClock interface.
293 gdk_frame_clock_paint (GdkFrameClock *clock)
295 g_return_if_fail (GDK_IS_FRAME_CLOCK (clock));
297 g_signal_emit (G_OBJECT (clock),
298 signals[BEFORE_PAINT], 0);
300 g_signal_emit (G_OBJECT (clock),
303 g_signal_emit (G_OBJECT (clock),
306 g_signal_emit (G_OBJECT (clock),
307 signals[AFTER_PAINT], 0);