gst-libs/gst/video/video-event.c

   1 /* GStreamer
   2  * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
   3  * Library       <2002> Ronald Bultje <rbultje@ronald.bitfreak.net>
   4  * Copyright (C) 2007 David A. Schleef <ds@schleef.org>
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22 #include "video-event.h"
  23
  24 #define GST_VIDEO_EVENT_STILL_STATE_NAME "GstEventStillFrame"
  25
  26 /**
  27  * gst_video_event_new_still_frame:
  28  * @in_still: boolean value for the still-frame state of the event.
  29  *
  30  * Creates a new Still Frame event. If @in_still is %TRUE, then the event
  31  * represents the start of a still frame sequence. If it is %FALSE, then
  32  * the event ends a still frame sequence.
  33  *
  34  * To parse an event created by gst_video_event_new_still_frame() use
  35  * gst_video_event_parse_still_frame().
  36  *
  37  * Returns: The new GstEvent
  38  */
  39 GstEvent *
  40 gst_video_event_new_still_frame (gboolean in_still)
  41 {
  42   GstEvent *still_event;
  43   GstStructure *s;
  44
  45   s = gst_structure_new (GST_VIDEO_EVENT_STILL_STATE_NAME,
  46       "still-state", G_TYPE_BOOLEAN, in_still, NULL);
  47   still_event = gst_event_new_custom (GST_EVENT_CUSTOM_DOWNSTREAM, s);
  48
  49   return still_event;
  50 }
  51
  52 /**
  53  * gst_video_event_parse_still_frame:
  54  * @event: A #GstEvent to parse
  55  * @in_still: (out):
  56  *     A boolean to receive the still-frame status from the event, or NULL
  57  *
  58  * Parse a #GstEvent, identify if it is a Still Frame event, and
  59  * return the still-frame state from the event if it is.
  60  * If the event represents the start of a still frame, the in_still
  61  * variable will be set to TRUE, otherwise FALSE. It is OK to pass NULL for the
  62  * in_still variable order to just check whether the event is a valid still-frame
  63  * event.
  64  *
  65  * Create a still frame event using gst_video_event_new_still_frame()
  66  *
  67  * Returns: %TRUE if the event is a valid still-frame event. %FALSE if not
  68  */
  69 gboolean
  70 gst_video_event_parse_still_frame (GstEvent * event, gboolean * in_still)
  71 {
  72   const GstStructure *s;
  73   gboolean ev_still_state;
  74
  75   g_return_val_if_fail (event != NULL, FALSE);
  76
  77   if (GST_EVENT_TYPE (event) != GST_EVENT_CUSTOM_DOWNSTREAM)
  78     return FALSE;               /* Not a still frame event */
  79
  80   s = gst_event_get_structure (event);
  81   if (s == NULL
  82       || !gst_structure_has_name (s, GST_VIDEO_EVENT_STILL_STATE_NAME))
  83     return FALSE;               /* Not a still frame event */
  84   if (!gst_structure_get_boolean (s, "still-state", &ev_still_state))
  85     return FALSE;               /* Not a still frame event */
  86   if (in_still)
  87     *in_still = ev_still_state;
  88   return TRUE;
  89 }
  90
  91 #define GST_VIDEO_EVENT_FORCE_KEY_UNIT_NAME "GstForceKeyUnit"
  92
  93 /**
  94  * gst_video_event_new_downstream_force_key_unit:
  95  * @timestamp: the timestamp of the buffer that starts a new key unit
  96  * @stream_time: the stream_time of the buffer that starts a new key unit
  97  * @running_time: the running_time of the buffer that starts a new key unit
  98  * @all_headers: %TRUE to produce headers when starting a new key unit
  99  * @count: integer that can be used to number key units
 100  *
 101  * Creates a new downstream force key unit event. A downstream force key unit
 102  * event can be sent down the pipeline to request downstream elements to produce
 103  * a key unit. A downstream force key unit event must also be sent when handling
 104  * an upstream force key unit event to notify downstream that the latter has been
 105  * handled.
 106  *
 107  * To parse an event created by gst_video_event_new_downstream_force_key_unit() use
 108  * gst_video_event_parse_downstream_force_key_unit().
 109  *
 110  * Returns: The new GstEvent
 111  */
 112 GstEvent *
 113 gst_video_event_new_downstream_force_key_unit (GstClockTime timestamp,
 114     GstClockTime stream_time, GstClockTime running_time, gboolean all_headers,
 115     guint count)
 116 {
 117   GstEvent *force_key_unit_event;
 118   GstStructure *s;
 119
 120   s = gst_structure_new (GST_VIDEO_EVENT_FORCE_KEY_UNIT_NAME,
 121       "timestamp", G_TYPE_UINT64, timestamp,
 122       "stream-time", G_TYPE_UINT64, stream_time,
 123       "running-time", G_TYPE_UINT64, running_time,
 124       "all-headers", G_TYPE_BOOLEAN, all_headers,
 125       "count", G_TYPE_UINT, count, NULL);
 126   force_key_unit_event = gst_event_new_custom (GST_EVENT_CUSTOM_DOWNSTREAM, s);
 127
 128   return force_key_unit_event;
 129 }
 130
 131 /**
 132  * gst_video_event_new_upstream_force_key_unit:
 133  * @running_time: the running_time at which a new key unit should be produced
 134  * @all_headers: %TRUE to produce headers when starting a new key unit
 135  * @count: integer that can be used to number key units
 136  *
 137  * Creates a new upstream force key unit event. An upstream force key unit event
 138  * can be sent to request upstream elements to produce a key unit.
 139  *
 140  * @running_time can be set to request a new key unit at a specific
 141  * running_time. If set to GST_CLOCK_TIME_NONE, upstream elements will produce a
 142  * new key unit as soon as possible.
 143  *
 144  * To parse an event created by gst_video_event_new_downstream_force_key_unit() use
 145  * gst_video_event_parse_downstream_force_key_unit().
 146  *
 147  * Returns: The new GstEvent
 148  */
 149 GstEvent *
 150 gst_video_event_new_upstream_force_key_unit (GstClockTime running_time,
 151     gboolean all_headers, guint count)
 152 {
 153   GstEvent *force_key_unit_event;
 154   GstStructure *s;
 155
 156   s = gst_structure_new (GST_VIDEO_EVENT_FORCE_KEY_UNIT_NAME,
 157       "running-time", GST_TYPE_CLOCK_TIME, running_time,
 158       "all-headers", G_TYPE_BOOLEAN, all_headers,
 159       "count", G_TYPE_UINT, count, NULL);
 160   force_key_unit_event = gst_event_new_custom (GST_EVENT_CUSTOM_UPSTREAM, s);
 161
 162   return force_key_unit_event;
 163 }
 164
 165 /**
 166  * gst_video_event_is_force_key_unit:
 167  * @event: A #GstEvent to check
 168  *
 169  * Checks if an event is a force key unit event. Returns true for both upstream
 170  * and downstream force key unit events.
 171  *
 172  * Returns: %TRUE if the event is a valid force key unit event
 173  */
 174 gboolean
 175 gst_video_event_is_force_key_unit (GstEvent * event)
 176 {
 177   const GstStructure *s;
 178
 179   g_return_val_if_fail (event != NULL, FALSE);
 180
 181   if (GST_EVENT_TYPE (event) != GST_EVENT_CUSTOM_DOWNSTREAM &&
 182       GST_EVENT_TYPE (event) != GST_EVENT_CUSTOM_UPSTREAM)
 183     return FALSE;               /* Not a force key unit event */
 184
 185   s = gst_event_get_structure (event);
 186   if (s == NULL
 187       || !gst_structure_has_name (s, GST_VIDEO_EVENT_FORCE_KEY_UNIT_NAME))
 188     return FALSE;
 189
 190   return TRUE;
 191 }
 192
 193 /**
 194  * gst_video_event_parse_downstream_force_key_unit:
 195  * @event: A #GstEvent to parse
 196  * @timestamp: (out): A pointer to the timestamp in the event
 197  * @stream_time: (out): A pointer to the stream-time in the event
 198  * @running_time: (out): A pointer to the running-time in the event
 199  * @all_headers: (out): A pointer to the all_headers flag in the event
 200  * @count: (out): A pointer to the count field of the event
 201  *
 202  * Get timestamp, stream-time, running-time, all-headers and count in the force
 203  * key unit event. See gst_video_event_new_downstream_force_key_unit() for a
 204  * full description of the downstream force key unit event.
 205  *
 206  * @running_time will be adjusted for any pad offsets of pads it was passing through.
 207  *
 208  * Returns: %TRUE if the event is a valid downstream force key unit event.
 209  */
 210 gboolean
 211 gst_video_event_parse_downstream_force_key_unit (GstEvent * event,
 212     GstClockTime * timestamp, GstClockTime * stream_time,
 213     GstClockTime * running_time, gboolean * all_headers, guint * count)
 214 {
 215   const GstStructure *s;
 216   GstClockTime ev_timestamp, ev_stream_time, ev_running_time;
 217   gboolean ev_all_headers;
 218   guint ev_count;
 219
 220   g_return_val_if_fail (event != NULL, FALSE);
 221
 222   if (GST_EVENT_TYPE (event) != GST_EVENT_CUSTOM_DOWNSTREAM)
 223     return FALSE;               /* Not a force key unit event */
 224
 225   s = gst_event_get_structure (event);
 226   if (s == NULL
 227       || !gst_structure_has_name (s, GST_VIDEO_EVENT_FORCE_KEY_UNIT_NAME))
 228     return FALSE;
 229
 230   if (!gst_structure_get_clock_time (s, "timestamp", &ev_timestamp))
 231     ev_timestamp = GST_CLOCK_TIME_NONE;
 232   if (!gst_structure_get_clock_time (s, "stream-time", &ev_stream_time))
 233     ev_stream_time = GST_CLOCK_TIME_NONE;
 234   if (!gst_structure_get_clock_time (s, "running-time", &ev_running_time))
 235     ev_running_time = GST_CLOCK_TIME_NONE;
 236   if (!gst_structure_get_boolean (s, "all-headers", &ev_all_headers))
 237     ev_all_headers = FALSE;
 238   if (!gst_structure_get_uint (s, "count", &ev_count))
 239     ev_count = 0;
 240
 241   if (timestamp)
 242     *timestamp = ev_timestamp;
 243
 244   if (stream_time)
 245     *stream_time = ev_stream_time;
 246
 247   if (running_time) {
 248     gint64 offset = gst_event_get_running_time_offset (event);
 249
 250     *running_time = ev_running_time;
 251     /* Catch underflows */
 252     if (*running_time > -offset)
 253       *running_time += offset;
 254     else
 255       *running_time = 0;
 256   }
 257
 258   if (all_headers)
 259     *all_headers = ev_all_headers;
 260
 261   if (count)
 262     *count = ev_count;
 263
 264   return TRUE;
 265 }
 266
 267 /**
 268  * gst_video_event_parse_upstream_force_key_unit:
 269  * @event: A #GstEvent to parse
 270  * @running_time: (out): A pointer to the running_time in the event
 271  * @all_headers: (out): A pointer to the all_headers flag in the event
 272  * @count: (out): A pointer to the count field in the event
 273  *
 274  * Get running-time, all-headers and count in the force key unit event. See
 275  * gst_video_event_new_upstream_force_key_unit() for a full description of the
 276  * upstream force key unit event.
 277  *
 278  * Create an upstream force key unit event using  gst_video_event_new_upstream_force_key_unit()
 279  *
 280  * @running_time will be adjusted for any pad offsets of pads it was passing through.
 281  *
 282  * Returns: %TRUE if the event is a valid upstream force-key-unit event. %FALSE if not
 283  */
 284 gboolean
 285 gst_video_event_parse_upstream_force_key_unit (GstEvent * event,
 286     GstClockTime * running_time, gboolean * all_headers, guint * count)
 287 {
 288   const GstStructure *s;
 289   GstClockTime ev_running_time;
 290   gboolean ev_all_headers;
 291   guint ev_count;
 292
 293   g_return_val_if_fail (event != NULL, FALSE);
 294
 295   if (GST_EVENT_TYPE (event) != GST_EVENT_CUSTOM_UPSTREAM)
 296     return FALSE;               /* Not a force key unit event */
 297
 298   s = gst_event_get_structure (event);
 299   if (s == NULL
 300       || !gst_structure_has_name (s, GST_VIDEO_EVENT_FORCE_KEY_UNIT_NAME))
 301     return FALSE;
 302
 303   if (!gst_structure_get_clock_time (s, "running-time", &ev_running_time))
 304     ev_running_time = GST_CLOCK_TIME_NONE;
 305   if (!gst_structure_get_boolean (s, "all-headers", &ev_all_headers))
 306     ev_all_headers = FALSE;
 307   if (!gst_structure_get_uint (s, "count", &ev_count))
 308     ev_count = 0;
 309
 310
 311   if (running_time) {
 312     gint64 offset = gst_event_get_running_time_offset (event);
 313
 314     *running_time = ev_running_time;
 315     /* Catch underflows */
 316     if (*running_time > -offset)
 317       *running_time += offset;
 318     else
 319       *running_time = 0;
 320   }
 321
 322   if (all_headers)
 323     *all_headers = ev_all_headers;
 324
 325   if (count)
 326     *count = ev_count;
 327
 328   return TRUE;
 329 }