Pileus Git - ~andy/gtk/blob - gdk/gdkframetimings.c

   1 /* GDK - The GIMP Drawing Kit
   2  * Copyright (C) 2012 Red Hat, Inc.
   3  *
   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.
   8  *
   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.
  13  *
  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/>.
  16  */
  17
  18 #include "config.h"
  19
  20 #include "gdkframeclockprivate.h"
  21
  22 /**
  23  * SECTION:frametimings
  24  * @Short_description: Object holding timing information for a single frame
  25  * @Title: Frame timings
  26  *
  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.
  33  */
  34
  35 G_DEFINE_BOXED_TYPE (GdkFrameTimings, gdk_frame_timings,
  36                      gdk_frame_timings_ref,
  37                      gdk_frame_timings_unref)
  38
  39 GdkFrameTimings *
  40 _gdk_frame_timings_new (gint64 frame_counter)
  41 {
  42   GdkFrameTimings *timings;
  43
  44   timings = g_slice_new0 (GdkFrameTimings);
  45   timings->ref_count = 1;
  46   timings->frame_counter = frame_counter;
  47
  48   return timings;
  49 }
  50
  51 /**
  52  * gdk_frame_timings_ref:
  53  * @timings: a #GdkFrameTimings
  54  *
  55  * Increases the reference count of @timings.
  56  *
  57  * Returns: @timings
  58  * Since: 3.8
  59  */
  60 GdkFrameTimings *
  61 gdk_frame_timings_ref (GdkFrameTimings *timings)
  62 {
  63   g_return_val_if_fail (timings != NULL, NULL);
  64
  65   timings->ref_count++;
  66
  67   return timings;
  68 }
  69
  70 /**
  71  * gdk_frame_timings_unref:
  72  * @timings: a #GdkFrameTimings
  73  *
  74  * Decreases the reference count of @timings. If @timings
  75  * is no longer referenced, it will be freed.
  76  *
  77  * Since: 3.8
  78  */
  79 void
  80 gdk_frame_timings_unref (GdkFrameTimings *timings)
  81 {
  82   g_return_if_fail (timings != NULL);
  83   g_return_if_fail (timings->ref_count > 0);
  84
  85   timings->ref_count--;
  86   if (timings->ref_count == 0)
  87     {
  88       g_slice_free (GdkFrameTimings, timings);
  89     }
  90 }
  91
  92 /**
  93  * gdk_frame_timings_get_frame_counter:
  94  * @timings: a #GdkFrameTimings
  95  *
  96  * Gets the frame counter value of the #GdkFrameClock when this
  97  * this frame was drawn.
  98  *
  99  * Returns: the frame counter value for this frame
 100  * Since: 3.8
 101  */
 102 gint64
 103 gdk_frame_timings_get_frame_counter (GdkFrameTimings *timings)
 104 {
 105   return timings->frame_counter;
 106 }
 107
 108 /**
 109  * gdk_frame_timings_complete:
 110  * @timings: a #GdkFrameTimings
 111  *
 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.
 121  *
 122  * Returns: %TRUE if all information that will be available
 123  *  for the frame has been filled in.
 124  * Since: 3.8
 125  */
 126 gboolean
 127 gdk_frame_timings_get_complete (GdkFrameTimings *timings)
 128 {
 129   g_return_val_if_fail (timings != NULL, FALSE);
 130
 131   return timings->complete;
 132 }
 133
 134 /**
 135  * gdk_frame_timings_get_frame_time:
 136  * @timings: A #GdkFrameTimings
 137  *
 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().
 141  *
 142  * Returns: the frame time for the frame, in the timescale
 143  *  of g_get_monotonic_time()
 144  */
 145 gint64
 146 gdk_frame_timings_get_frame_time (GdkFrameTimings *timings)
 147 {
 148   g_return_val_if_fail (timings != NULL, 0);
 149
 150   return timings->frame_time;
 151 }
 152
 153 /**
 154  * gdk_frame_timings_get_presentation_time:
 155  * @timings: a #GdkFrameTimings
 156  *
 157  * Reurns the presentation time. This is the time at which the frame
 158  * became visible to the user.
 159  *
 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()
 163  * Since: 3.8
 164  */
 165 gint64
 166 gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
 167 {
 168   g_return_val_if_fail (timings != NULL, 0);
 169
 170   return timings->presentation_time;
 171 }
 172
 173 /**
 174  * gdk_frame_timings_get_predicted_presentation_time:
 175  * @timings: a #GdkFrameTimings
 176  *
 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.
 186  *
 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.
 190  * Since: 3.8
 191  */
 192 gint64
 193 gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
 194 {
 195   g_return_val_if_fail (timings != NULL, 0);
 196
 197   return timings->predicted_presentation_time;
 198 }
 199
 200 /**
 201  * gdk_frame_timings_get_refresh_interval:
 202  * @timings: a #GdkFrameTimings
 203  *
 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".
 207  *
 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().
 211  * Since: 3.8
 212  */
 213 gint64
 214 gdk_frame_timings_get_refresh_interval (GdkFrameTimings *timings)
 215 {
 216   g_return_val_if_fail (timings != NULL, 0);
 217
 218   return timings->refresh_interval;
 219 }