1 /* GDK - The GIMP Drawing Kit
2 * Copyright (C) 2012 Red Hat, Inc.
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, see <http://www.gnu.org/licenses/>.
20 #include "gdkframeclockprivate.h"
23 * SECTION:frametimings
24 * @Short_description: Object holding timing information for a single frame
25 * @Title: Frame timings
27 * A #GdkFrameTimings object holds timing information for a single frame
28 * of the application's displays. To retrieve #GdkFrameTimings objects,
29 * use gdk_frame_clock_get_timings() or gdk_frame_clock_get_current_timings().
30 * The information in #GdkFrameTimings is useful for precise synchronization
31 * of video with the event or audio streams, and for measuring
32 * quality metrics for the application's display, such as latency and jitter.
35 G_DEFINE_BOXED_TYPE (GdkFrameTimings, gdk_frame_timings,
36 gdk_frame_timings_ref,
37 gdk_frame_timings_unref)
40 _gdk_frame_timings_new (gint64 frame_counter)
42 GdkFrameTimings *timings;
44 timings = g_slice_new0 (GdkFrameTimings);
45 timings->ref_count = 1;
46 timings->frame_counter = frame_counter;
52 * gdk_frame_timings_ref:
53 * @timings: a #GdkFrameTimings
55 * Increases the reference count of @timings.
61 gdk_frame_timings_ref (GdkFrameTimings *timings)
63 g_return_val_if_fail (timings != NULL, NULL);
71 * gdk_frame_timings_unref:
72 * @timings: a #GdkFrameTimings
74 * Decreases the reference count of @timings. If @timings
75 * is no longer referenced, it will be freed.
80 gdk_frame_timings_unref (GdkFrameTimings *timings)
82 g_return_if_fail (timings != NULL);
83 g_return_if_fail (timings->ref_count > 0);
86 if (timings->ref_count == 0)
88 g_slice_free (GdkFrameTimings, timings);
93 * gdk_frame_timings_get_frame_counter:
94 * @timings: a #GdkFrameTimings
96 * Gets the frame counter value of the #GdkFrameClock when this
97 * this frame was drawn.
99 * Returns: the frame counter value for this frame
103 gdk_frame_timings_get_frame_counter (GdkFrameTimings *timings)
105 return timings->frame_counter;
109 * gdk_frame_timings_complete:
110 * @timings: a #GdkFrameTimings
112 * The timing information in a #GdkFrameTimings is filled in
113 * incrementally as the frame as drawn and passed off to the
114 * window system for processing and display to the user. The
115 * accessor functions for #GdkFrameTimings can return 0 to
116 * indicate an unavailable value for two reasons: either because
117 * the information is not yet available, or because it isn't
118 * available at all. Once gdk_frame_timings_complete() returns
119 * %TRUE for a frame, you can be certain that no further values
120 * will become available and be stored in the #GdkFrameTimings.
122 * Returns: %TRUE if all information that will be available
123 * for the frame has been filled in.
127 gdk_frame_timings_get_complete (GdkFrameTimings *timings)
129 g_return_val_if_fail (timings != NULL, FALSE);
131 return timings->complete;
135 * gdk_frame_timings_get_frame_time:
136 * @timings: A #GdkFrameTimings
138 * Returns the frame time for the frame. This is the time value
139 * that is typically used to time animations for the frame. See
140 * gdk_frame_clock_get_frame_time().
142 * Returns: the frame time for the frame, in the timescale
143 * of g_get_monotonic_time()
146 gdk_frame_timings_get_frame_time (GdkFrameTimings *timings)
148 g_return_val_if_fail (timings != NULL, 0);
150 return timings->frame_time;
154 * gdk_frame_timings_get_presentation_time:
155 * @timings: a #GdkFrameTimings
157 * Reurns the presentation time. This is the time at which the frame
158 * became visible to the user.
160 * Returns: the time the frame was displayed to the user, in the
161 * timescale of g_get_monotonic_time(), or 0 if no presentation
162 * time is available. See gdk_frame_timings_get_complete()
166 gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
168 g_return_val_if_fail (timings != NULL, 0);
170 return timings->presentation_time;
174 * gdk_frame_timings_get_predicted_presentation_time:
175 * @timings: a #GdkFrameTimings
177 * Gets the predicted time at which this frame will be displayed. Although
178 * no predicted time may be available, if one is available, it will
179 * be available while the frame is being generated, in contrast to
180 * gdk_frame_timings_get_presentation_time(), which is only available
181 * after the frame has been presented. In general, if you are simply
182 * animating, you should use gdk_frame_clock_get_frame_time() rather
183 * than this function, but this function is useful for applications
184 * that want exact control over latency. For example, a movie player
185 * may want this information for Audio/Video synchronization.
187 * Returns: The predicted time at which the frame will be presented,
188 * in the timescale of g_get_monotonic_time(), or 0 if no predicted
189 * presentation time is available.
193 gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
195 g_return_val_if_fail (timings != NULL, 0);
197 return timings->predicted_presentation_time;
201 * gdk_frame_timings_get_refresh_interval:
202 * @timings: a #GdkFrameTimings
204 * Gets the natural interval between presentation times for
205 * the display that this frame was displayed on. Frame presentation
206 * usually happens during the "vertical blanking interval".
208 * Returns: the refresh interval of the display, in microseconds,
209 * or 0 if the refresh interval is not available.
210 * See gdk_frame_timings_get_complete().
214 gdk_frame_timings_get_refresh_interval (GdkFrameTimings *timings)
216 g_return_val_if_fail (timings != NULL, 0);
218 return timings->refresh_interval;