gst/gstpipeline.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2004,2005 Wim Taymans <wim@fluendo.com>
   4  *
   5  * gstpipeline.c: Overall pipeline management element
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstpipeline
  25  * @short_description: Top-level bin with clocking and bus management
  26                        functionality.
  27  * @see_also: #GstBin
  28  *
  29  * In almost all cases, you'll want to use a GstPipeline when creating a filter
  30  * graph.  The GstPipeline will manage the selection and distribution of a
  31  * global
  32  * clock as well as provide a GstBus to the application.
  33  *
  34  * The pipeline will also use the selected clock to calculate the stream time
  35  * of the pipeline.
  36  *
  37  * When sending a seek event to a GstPipeline, it will make sure that the
  38  * pipeline is properly PAUSED and resumed as well as update the new stream
  39  * time after the seek.
  40  *
  41  * gst_pipeline_new() is used to create a pipeline. when you are done with
  42  * the pipeline, use gst_object_unref() to free its resources including all
  43  * added #GstElement objects (if not otherwiese referenced).
  44  */
  45
  46 #include "gst_private.h"
  47
  48 #include "gstpipeline.h"
  49 #include "gstinfo.h"
  50 #include "gstsystemclock.h"
  51
  52 static GstElementDetails gst_pipeline_details =
  53 GST_ELEMENT_DETAILS ("Pipeline object",
  54     "Generic/Bin",
  55     "Complete pipeline object",
  56     "Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim@fluendo.com>");
  57
  58 /* Pipeline signals and args */
  59 enum
  60 {
  61   /* FILL ME */
  62   LAST_SIGNAL
  63 };
  64
  65 #define DEFAULT_DELAY 0
  66
  67 enum
  68 {
  69   PROP_0,
  70   PROP_DELAY,
  71   /* FILL ME */
  72 };
  73
  74
  75 static void gst_pipeline_base_init (gpointer g_class);
  76 static void gst_pipeline_class_init (gpointer g_class, gpointer class_data);
  77 static void gst_pipeline_init (GTypeInstance * instance, gpointer g_class);
  78
  79 static void gst_pipeline_dispose (GObject * object);
  80 static void gst_pipeline_set_property (GObject * object, guint prop_id,
  81     const GValue * value, GParamSpec * pspec);
  82 static void gst_pipeline_get_property (GObject * object, guint prop_id,
  83     GValue * value, GParamSpec * pspec);
  84
  85 static gboolean gst_pipeline_send_event (GstElement * element,
  86     GstEvent * event);
  87
  88 static GstClock *gst_pipeline_provide_clock_func (GstElement * element);
  89 static GstStateChangeReturn gst_pipeline_change_state (GstElement * element,
  90     GstStateChange transition);
  91
  92 static GstBinClass *parent_class = NULL;
  93
  94 /* static guint gst_pipeline_signals[LAST_SIGNAL] = { 0 }; */
  95
  96 GType
  97 gst_pipeline_get_type (void)
  98 {
  99   static GType pipeline_type = 0;
 100
 101   if (!pipeline_type) {
 102     static const GTypeInfo pipeline_info = {
 103       sizeof (GstPipelineClass),
 104       gst_pipeline_base_init,
 105       NULL,
 106       (GClassInitFunc) gst_pipeline_class_init,
 107       NULL,
 108       NULL,
 109       sizeof (GstPipeline),
 110       0,
 111       gst_pipeline_init,
 112       NULL
 113     };
 114
 115     pipeline_type =
 116         g_type_register_static (GST_TYPE_BIN, "GstPipeline", &pipeline_info, 0);
 117   }
 118   return pipeline_type;
 119 }
 120
 121 static void
 122 gst_pipeline_base_init (gpointer g_class)
 123 {
 124   GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);
 125
 126   gst_element_class_set_details (gstelement_class, &gst_pipeline_details);
 127 }
 128
 129 static void
 130 gst_pipeline_class_init (gpointer g_class, gpointer class_data)
 131 {
 132   GObjectClass *gobject_class = G_OBJECT_CLASS (g_class);
 133   GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);
 134   GstPipelineClass *klass = GST_PIPELINE_CLASS (g_class);
 135
 136   parent_class = g_type_class_peek_parent (klass);
 137
 138   gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_pipeline_set_property);
 139   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_pipeline_get_property);
 140
 141   g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_DELAY,
 142       g_param_spec_uint64 ("delay", "Delay",
 143           "Expected delay needed for elements "
 144           "to spin up to PLAYING in nanoseconds", 0, G_MAXUINT64, DEFAULT_DELAY,
 145           G_PARAM_READWRITE));
 146
 147   gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_pipeline_dispose);
 148
 149   gstelement_class->send_event = GST_DEBUG_FUNCPTR (gst_pipeline_send_event);
 150   gstelement_class->change_state =
 151       GST_DEBUG_FUNCPTR (gst_pipeline_change_state);
 152   gstelement_class->provide_clock =
 153       GST_DEBUG_FUNCPTR (gst_pipeline_provide_clock_func);
 154 }
 155
 156 static void
 157 gst_pipeline_init (GTypeInstance * instance, gpointer g_class)
 158 {
 159   GstPipeline *pipeline = GST_PIPELINE (instance);
 160   GstBus *bus;
 161
 162   pipeline->delay = DEFAULT_DELAY;
 163
 164   bus = g_object_new (gst_bus_get_type (), NULL);
 165   gst_element_set_bus (GST_ELEMENT_CAST (pipeline), bus);
 166   gst_object_unref (bus);
 167 }
 168
 169 static void
 170 gst_pipeline_dispose (GObject * object)
 171 {
 172   GstPipeline *pipeline = GST_PIPELINE (object);
 173
 174   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, pipeline, "dispose");
 175
 176   gst_object_replace ((GstObject **) & pipeline->fixed_clock, NULL);
 177
 178   G_OBJECT_CLASS (parent_class)->dispose (object);
 179 }
 180
 181 static void
 182 gst_pipeline_set_property (GObject * object, guint prop_id,
 183     const GValue * value, GParamSpec * pspec)
 184 {
 185   GstPipeline *pipeline = GST_PIPELINE (object);
 186
 187   GST_LOCK (pipeline);
 188   switch (prop_id) {
 189     case PROP_DELAY:
 190       pipeline->delay = g_value_get_uint64 (value);
 191       break;
 192     default:
 193       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 194       break;
 195   }
 196   GST_UNLOCK (pipeline);
 197 }
 198
 199 static void
 200 gst_pipeline_get_property (GObject * object, guint prop_id,
 201     GValue * value, GParamSpec * pspec)
 202 {
 203   GstPipeline *pipeline = GST_PIPELINE (object);
 204
 205   GST_LOCK (pipeline);
 206   switch (prop_id) {
 207     case PROP_DELAY:
 208       g_value_set_uint64 (value, pipeline->delay);
 209       break;
 210     default:
 211       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 212       break;
 213   }
 214   GST_UNLOCK (pipeline);
 215 }
 216
 217 static gboolean
 218 do_pipeline_seek (GstElement * element, GstEvent * event)
 219 {
 220   gdouble rate;
 221   GstSeekFlags flags;
 222   gboolean flush;
 223   gboolean was_playing = FALSE;
 224   gboolean res;
 225
 226   gst_event_parse_seek (event, &rate, NULL, &flags, NULL, NULL, NULL, NULL);
 227
 228   flush = flags & GST_SEEK_FLAG_FLUSH;
 229
 230   if (flush) {
 231     GstState state;
 232
 233     /* need to call _get_state() since a bin state is only updated
 234      * with this call. */
 235     gst_element_get_state (element, &state, NULL, 0);
 236     was_playing = state == GST_STATE_PLAYING;
 237
 238     if (was_playing) {
 239       gst_element_set_state (element, GST_STATE_PAUSED);
 240     }
 241   }
 242
 243   res = GST_ELEMENT_CLASS (parent_class)->send_event (element, event);
 244
 245   if (flush && res) {
 246     gboolean need_reset;
 247
 248     GST_LOCK (element);
 249     need_reset = GST_PIPELINE (element)->stream_time != GST_CLOCK_TIME_NONE;
 250     GST_UNLOCK (element);
 251
 252     /* need to reset the stream time to 0 after a flushing seek, unless the user
 253        explicitly disabled this behavior by setting stream time to NONE */
 254     if (need_reset)
 255       gst_pipeline_set_new_stream_time (GST_PIPELINE (element), 0);
 256
 257     if (was_playing)
 258       /* and continue playing */
 259       gst_element_set_state (element, GST_STATE_PLAYING);
 260   }
 261   return res;
 262 }
 263
 264 /* sending a seek event on the pipeline pauses the pipeline if it
 265  * was playing.
 266  */
 267 static gboolean
 268 gst_pipeline_send_event (GstElement * element, GstEvent * event)
 269 {
 270   gboolean res;
 271   GstEventType event_type = GST_EVENT_TYPE (event);
 272
 273   switch (event_type) {
 274     case GST_EVENT_SEEK:
 275       res = do_pipeline_seek (element, event);
 276       break;
 277     default:
 278       res = GST_ELEMENT_CLASS (parent_class)->send_event (element, event);
 279       break;
 280   }
 281
 282   return res;
 283 }
 284
 285 /**
 286  * gst_pipeline_new:
 287  * @name: name of new pipeline
 288  *
 289  * Create a new pipeline with the given name.
 290  *
 291  * Returns: newly created GstPipeline
 292  *
 293  * MT safe.
 294  */
 295 GstElement *
 296 gst_pipeline_new (const gchar * name)
 297 {
 298   return gst_element_factory_make ("pipeline", name);
 299 }
 300
 301 /* MT safe */
 302 static GstStateChangeReturn
 303 gst_pipeline_change_state (GstElement * element, GstStateChange transition)
 304 {
 305   GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
 306   GstPipeline *pipeline = GST_PIPELINE (element);
 307   GstClock *clock;
 308
 309   switch (transition) {
 310     case GST_STATE_CHANGE_NULL_TO_READY:
 311       GST_LOCK (element);
 312       if (element->bus)
 313         gst_bus_set_flushing (element->bus, FALSE);
 314       GST_UNLOCK (element);
 315       break;
 316     case GST_STATE_CHANGE_READY_TO_PAUSED:
 317       break;
 318     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
 319     {
 320       GstClockTime new_base_time;
 321
 322       /* when going to playing, select a clock */
 323       clock = gst_element_provide_clock (element);
 324
 325       if (clock) {
 326         GstClockTime start_time, stream_time, delay;
 327         gboolean new_clock;
 328
 329         start_time = gst_clock_get_time (clock);
 330
 331         GST_LOCK (element);
 332         new_clock = element->clock != clock;
 333         stream_time = pipeline->stream_time;
 334         delay = pipeline->delay;
 335         GST_UNLOCK (element);
 336
 337         if (new_clock) {
 338           /* now distribute the clock (which could be NULL I guess) */
 339           gst_element_set_clock (element, clock);
 340
 341           /* if we selected a new clock, let the app know about it */
 342           gst_element_post_message (element,
 343               gst_message_new_new_clock (GST_OBJECT_CAST (element), clock));
 344         }
 345
 346         if (stream_time != GST_CLOCK_TIME_NONE)
 347           new_base_time = start_time - stream_time + delay;
 348         else
 349           new_base_time = GST_CLOCK_TIME_NONE;
 350
 351         gst_object_unref (clock);
 352       } else {
 353         GST_DEBUG ("no clock, using base time of 0");
 354         new_base_time = 0;
 355       }
 356
 357       if (new_base_time != GST_CLOCK_TIME_NONE)
 358         gst_element_set_base_time (element, new_base_time);
 359       else
 360         GST_DEBUG_OBJECT (pipeline,
 361             "NOT adjusting base time because stream time is NONE");
 362     }
 363       break;
 364     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
 365     case GST_STATE_CHANGE_PAUSED_TO_READY:
 366     case GST_STATE_CHANGE_READY_TO_NULL:
 367       break;
 368   }
 369
 370   result = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
 371
 372   switch (transition) {
 373     case GST_STATE_CHANGE_NULL_TO_READY:
 374       break;
 375     case GST_STATE_CHANGE_READY_TO_PAUSED:
 376     {
 377       gboolean need_reset;
 378
 379       GST_LOCK (element);
 380       need_reset = pipeline->stream_time != GST_CLOCK_TIME_NONE;
 381       GST_UNLOCK (element);
 382
 383       if (need_reset)
 384         gst_pipeline_set_new_stream_time (pipeline, 0);
 385     }
 386       break;
 387     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
 388       break;
 389     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
 390       GST_LOCK (element);
 391       if ((clock = element->clock)) {
 392         GstClockTime now;
 393
 394         gst_object_ref (clock);
 395         GST_UNLOCK (element);
 396
 397         /* calculate the time when we stopped */
 398         now = gst_clock_get_time (clock);
 399         gst_object_unref (clock);
 400
 401         GST_LOCK (element);
 402         /* store the current stream time */
 403         if (pipeline->stream_time != GST_CLOCK_TIME_NONE)
 404           pipeline->stream_time = now - element->base_time;
 405         GST_DEBUG ("stream_time=%" GST_TIME_FORMAT ", now=%" GST_TIME_FORMAT
 406             ", base time %" GST_TIME_FORMAT,
 407             GST_TIME_ARGS (pipeline->stream_time),
 408             GST_TIME_ARGS (now), GST_TIME_ARGS (element->base_time));
 409       }
 410       GST_UNLOCK (element);
 411       break;
 412     case GST_STATE_CHANGE_PAUSED_TO_READY:
 413       break;
 414     case GST_STATE_CHANGE_READY_TO_NULL:
 415       GST_LOCK (element);
 416       if (element->bus) {
 417         gst_bus_set_flushing (element->bus, TRUE);
 418       }
 419       GST_UNLOCK (element);
 420       break;
 421   }
 422   return result;
 423 }
 424
 425 /**
 426  * gst_pipeline_get_bus:
 427  * @pipeline: the pipeline
 428  *
 429  * Gets the #GstBus of this pipeline.
 430  *
 431  * Returns: a GstBus
 432  *
 433  * MT safe.
 434  */
 435 GstBus *
 436 gst_pipeline_get_bus (GstPipeline * pipeline)
 437 {
 438   return gst_element_get_bus (GST_ELEMENT (pipeline));
 439 }
 440
 441 /**
 442  * gst_pipeline_set_new_stream_time:
 443  * @pipeline: the pipeline
 444  * @time: the new stream time to set
 445  *
 446  * Set the new stream time of the pipeline. The stream time is used to
 447  * set the base time on the elements (see @gst_element_set_base_time())
 448  * in the PAUSED->PLAYING state transition.
 449  *
 450  * Setting @time to #GST_CLOCK_TIME_NONE will disable the pipeline's management
 451  * of element base time. The application will then be responsible for
 452  * performing base time distribution. This is sometimes useful if you want to
 453  * synchronize capture from multiple pipelines, and you can also ensure that the
 454  * pipelines have the same clock.
 455  *
 456  * MT safe.
 457  */
 458 void
 459 gst_pipeline_set_new_stream_time (GstPipeline * pipeline, GstClockTime time)
 460 {
 461   g_return_if_fail (GST_IS_PIPELINE (pipeline));
 462
 463   GST_LOCK (pipeline);
 464   pipeline->stream_time = time;
 465   GST_UNLOCK (pipeline);
 466
 467   GST_DEBUG_OBJECT (pipeline, "set new stream_time to %" GST_TIME_FORMAT,
 468       GST_TIME_ARGS (time));
 469
 470   if (time == GST_CLOCK_TIME_NONE)
 471     GST_DEBUG_OBJECT (pipeline, "told not to adjust base time");
 472 }
 473
 474 /**
 475  * gst_pipeline_get_last_stream_time:
 476  * @pipeline: the pipeline
 477  *
 478  * Gets the last stream time of the pipeline. If the pipeline is PLAYING,
 479  * the returned time is the stream time used to configure the elements
 480  * in the PAUSED->PLAYING state. If the pipeline is PAUSED, the returned
 481  * time is the stream time when the pipeline was paused.
 482  *
 483  * Returns: a GstClockTime
 484  *
 485  * MT safe.
 486  */
 487 GstClockTime
 488 gst_pipeline_get_last_stream_time (GstPipeline * pipeline)
 489 {
 490   GstClockTime result;
 491
 492   g_return_val_if_fail (GST_IS_PIPELINE (pipeline), GST_CLOCK_TIME_NONE);
 493
 494   GST_LOCK (pipeline);
 495   result = pipeline->stream_time;
 496   GST_UNLOCK (pipeline);
 497
 498   return result;
 499 }
 500
 501 static GstClock *
 502 gst_pipeline_provide_clock_func (GstElement * element)
 503 {
 504   GstClock *clock = NULL;
 505   GstPipeline *pipeline = GST_PIPELINE (element);
 506
 507   /* if we have a fixed clock, use that one */
 508   GST_LOCK (pipeline);
 509   if (GST_OBJECT_FLAG_IS_SET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK)) {
 510     clock = pipeline->fixed_clock;
 511     gst_object_ref (clock);
 512     GST_UNLOCK (pipeline);
 513
 514     GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using fixed clock %p (%s)",
 515         clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
 516   } else {
 517     GST_UNLOCK (pipeline);
 518     clock =
 519         GST_ELEMENT_CLASS (parent_class)->
 520         provide_clock (GST_ELEMENT (pipeline));
 521     /* no clock, use a system clock */
 522     if (!clock) {
 523       clock = gst_system_clock_obtain ();
 524
 525       GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline obtained system clock: %p (%s)",
 526           clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
 527     } else {
 528       GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline obtained clock: %p (%s)",
 529           clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
 530     }
 531   }
 532   return clock;
 533 }
 534
 535 /**
 536  * gst_pipeline_get_clock:
 537  * @pipeline: the pipeline
 538  *
 539  * Gets the current clock used by the pipeline.
 540  *
 541  * Returns: a GstClock
 542  */
 543 GstClock *
 544 gst_pipeline_get_clock (GstPipeline * pipeline)
 545 {
 546   g_return_val_if_fail (GST_IS_PIPELINE (pipeline), NULL);
 547
 548   return gst_pipeline_provide_clock_func (GST_ELEMENT (pipeline));
 549 }
 550
 551
 552 /**
 553  * gst_pipeline_use_clock:
 554  * @pipeline: the pipeline
 555  * @clock: the clock to use
 556  *
 557  * Force the pipeline to use the given clock. The pipeline will
 558  * always use the given clock even if new clock providers are added
 559  * to this pipeline.
 560  *
 561  * MT safe.
 562  */
 563 void
 564 gst_pipeline_use_clock (GstPipeline * pipeline, GstClock * clock)
 565 {
 566   g_return_if_fail (GST_IS_PIPELINE (pipeline));
 567
 568   GST_LOCK (pipeline);
 569   GST_OBJECT_FLAG_SET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK);
 570
 571   gst_object_replace ((GstObject **) & pipeline->fixed_clock,
 572       (GstObject *) clock);
 573   GST_UNLOCK (pipeline);
 574
 575   GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using fixed clock %p (%s)", clock,
 576       (clock ? GST_OBJECT_NAME (clock) : "nil"));
 577 }
 578
 579 /**
 580  * gst_pipeline_set_clock:
 581  * @pipeline: the pipeline
 582  * @clock: the clock to set
 583  *
 584  * Set the clock for the pipeline. The clock will be distributed
 585  * to all the elements managed by the pipeline.
 586  *
 587  * MT safe.
 588  */
 589 void
 590 gst_pipeline_set_clock (GstPipeline * pipeline, GstClock * clock)
 591 {
 592   g_return_if_fail (pipeline != NULL);
 593   g_return_if_fail (GST_IS_PIPELINE (pipeline));
 594
 595   GST_ELEMENT_CLASS (parent_class)->set_clock (GST_ELEMENT (pipeline), clock);
 596 }
 597
 598 /**
 599  * gst_pipeline_auto_clock:
 600  * @pipeline: the pipeline
 601  *
 602  * Let the pipeline select a clock automatically.
 603  *
 604  * MT safe.
 605  */
 606 void
 607 gst_pipeline_auto_clock (GstPipeline * pipeline)
 608 {
 609   g_return_if_fail (pipeline != NULL);
 610   g_return_if_fail (GST_IS_PIPELINE (pipeline));
 611
 612   GST_LOCK (pipeline);
 613   GST_OBJECT_FLAG_UNSET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK);
 614
 615   gst_object_replace ((GstObject **) & pipeline->fixed_clock, NULL);
 616   GST_UNLOCK (pipeline);
 617
 618   GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using automatic clock");
 619 }