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_OBJECT_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_OBJECT_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_OBJECT_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_OBJECT_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_OBJECT_LOCK (element);
 249     need_reset = GST_PIPELINE (element)->stream_time != GST_CLOCK_TIME_NONE;
 250     GST_OBJECT_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_OBJECT_LOCK (element);
 312       if (element->bus)
 313         gst_bus_set_flushing (element->bus, FALSE);
 314       GST_OBJECT_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_OBJECT_LOCK (element);
 332         new_clock = element->clock != clock;
 333         stream_time = pipeline->stream_time;
 334         delay = pipeline->delay;
 335         GST_OBJECT_UNLOCK (element);
 336
 337         if (new_clock) {
 338           /* now distribute the clock (which could be NULL I guess) */
 339           if (!gst_element_set_clock (element, clock))
 340             goto invalid_clock;
 341
 342           /* if we selected a new clock, let the app know about it */
 343           gst_element_post_message (element,
 344               gst_message_new_new_clock (GST_OBJECT_CAST (element), clock));
 345         }
 346
 347         if (stream_time != GST_CLOCK_TIME_NONE)
 348           new_base_time = start_time - stream_time + delay;
 349         else
 350           new_base_time = GST_CLOCK_TIME_NONE;
 351
 352         gst_object_unref (clock);
 353       } else {
 354         GST_DEBUG ("no clock, using base time of 0");
 355         new_base_time = 0;
 356       }
 357
 358       if (new_base_time != GST_CLOCK_TIME_NONE)
 359         gst_element_set_base_time (element, new_base_time);
 360       else
 361         GST_DEBUG_OBJECT (pipeline,
 362             "NOT adjusting base time because stream time is NONE");
 363     }
 364       break;
 365     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
 366     case GST_STATE_CHANGE_PAUSED_TO_READY:
 367     case GST_STATE_CHANGE_READY_TO_NULL:
 368       break;
 369   }
 370
 371   result = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
 372
 373   switch (transition) {
 374     case GST_STATE_CHANGE_NULL_TO_READY:
 375       break;
 376     case GST_STATE_CHANGE_READY_TO_PAUSED:
 377     {
 378       gboolean need_reset;
 379
 380       GST_OBJECT_LOCK (element);
 381       need_reset = pipeline->stream_time != GST_CLOCK_TIME_NONE;
 382       GST_OBJECT_UNLOCK (element);
 383
 384       if (need_reset)
 385         gst_pipeline_set_new_stream_time (pipeline, 0);
 386     }
 387       break;
 388     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
 389       break;
 390     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
 391       GST_OBJECT_LOCK (element);
 392       if ((clock = element->clock)) {
 393         GstClockTime now;
 394
 395         gst_object_ref (clock);
 396         GST_OBJECT_UNLOCK (element);
 397
 398         /* calculate the time when we stopped */
 399         now = gst_clock_get_time (clock);
 400         gst_object_unref (clock);
 401
 402         GST_OBJECT_LOCK (element);
 403         /* store the current stream time */
 404         if (pipeline->stream_time != GST_CLOCK_TIME_NONE)
 405           pipeline->stream_time = now - element->base_time;
 406         GST_DEBUG_OBJECT (element,
 407             "stream_time=%" GST_TIME_FORMAT ", now=%" GST_TIME_FORMAT
 408             ", base time %" GST_TIME_FORMAT,
 409             GST_TIME_ARGS (pipeline->stream_time), GST_TIME_ARGS (now),
 410             GST_TIME_ARGS (element->base_time));
 411       }
 412       GST_OBJECT_UNLOCK (element);
 413       break;
 414     case GST_STATE_CHANGE_PAUSED_TO_READY:
 415       break;
 416     case GST_STATE_CHANGE_READY_TO_NULL:
 417       GST_OBJECT_LOCK (element);
 418       if (element->bus) {
 419         gst_bus_set_flushing (element->bus, TRUE);
 420       }
 421       GST_OBJECT_UNLOCK (element);
 422       break;
 423   }
 424   return result;
 425
 426 invalid_clock:
 427   {
 428     /* FIXME, post error message */
 429     GST_DEBUG_OBJECT (pipeline,
 430         "Pipeline cannot operate with selected clock %p", clock);
 431     return GST_STATE_CHANGE_FAILURE;
 432   }
 433 }
 434
 435 /**
 436  * gst_pipeline_get_bus:
 437  * @pipeline: the pipeline
 438  *
 439  * Gets the #GstBus of this pipeline.
 440  *
 441  * Returns: a GstBus
 442  *
 443  * MT safe.
 444  */
 445 GstBus *
 446 gst_pipeline_get_bus (GstPipeline * pipeline)
 447 {
 448   return gst_element_get_bus (GST_ELEMENT (pipeline));
 449 }
 450
 451 /**
 452  * gst_pipeline_set_new_stream_time:
 453  * @pipeline: the pipeline
 454  * @time: the new stream time to set
 455  *
 456  * Set the new stream time of the pipeline. The stream time is used to
 457  * set the base time on the elements (see @gst_element_set_base_time())
 458  * in the PAUSED->PLAYING state transition.
 459  *
 460  * Setting @time to #GST_CLOCK_TIME_NONE will disable the pipeline's management
 461  * of element base time. The application will then be responsible for
 462  * performing base time distribution. This is sometimes useful if you want to
 463  * synchronize capture from multiple pipelines, and you can also ensure that the
 464  * pipelines have the same clock.
 465  *
 466  * MT safe.
 467  */
 468 void
 469 gst_pipeline_set_new_stream_time (GstPipeline * pipeline, GstClockTime time)
 470 {
 471   g_return_if_fail (GST_IS_PIPELINE (pipeline));
 472
 473   GST_OBJECT_LOCK (pipeline);
 474   pipeline->stream_time = time;
 475   GST_OBJECT_UNLOCK (pipeline);
 476
 477   GST_DEBUG_OBJECT (pipeline, "set new stream_time to %" GST_TIME_FORMAT,
 478       GST_TIME_ARGS (time));
 479
 480   if (time == GST_CLOCK_TIME_NONE)
 481     GST_DEBUG_OBJECT (pipeline, "told not to adjust base time");
 482 }
 483
 484 /**
 485  * gst_pipeline_get_last_stream_time:
 486  * @pipeline: the pipeline
 487  *
 488  * Gets the last stream time of the pipeline. If the pipeline is PLAYING,
 489  * the returned time is the stream time used to configure the elements
 490  * in the PAUSED->PLAYING state. If the pipeline is PAUSED, the returned
 491  * time is the stream time when the pipeline was paused.
 492  *
 493  * Returns: a GstClockTime
 494  *
 495  * MT safe.
 496  */
 497 GstClockTime
 498 gst_pipeline_get_last_stream_time (GstPipeline * pipeline)
 499 {
 500   GstClockTime result;
 501
 502   g_return_val_if_fail (GST_IS_PIPELINE (pipeline), GST_CLOCK_TIME_NONE);
 503
 504   GST_OBJECT_LOCK (pipeline);
 505   result = pipeline->stream_time;
 506   GST_OBJECT_UNLOCK (pipeline);
 507
 508   return result;
 509 }
 510
 511 static GstClock *
 512 gst_pipeline_provide_clock_func (GstElement * element)
 513 {
 514   GstClock *clock = NULL;
 515   GstPipeline *pipeline = GST_PIPELINE (element);
 516
 517   /* if we have a fixed clock, use that one */
 518   GST_OBJECT_LOCK (pipeline);
 519   if (GST_OBJECT_FLAG_IS_SET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK)) {
 520     clock = pipeline->fixed_clock;
 521     gst_object_ref (clock);
 522     GST_OBJECT_UNLOCK (pipeline);
 523
 524     GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using fixed clock %p (%s)",
 525         clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
 526   } else {
 527     GST_OBJECT_UNLOCK (pipeline);
 528     clock =
 529         GST_ELEMENT_CLASS (parent_class)->
 530         provide_clock (GST_ELEMENT (pipeline));
 531     /* no clock, use a system clock */
 532     if (!clock) {
 533       clock = gst_system_clock_obtain ();
 534
 535       GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline obtained system clock: %p (%s)",
 536           clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
 537     } else {
 538       GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline obtained clock: %p (%s)",
 539           clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
 540     }
 541   }
 542   return clock;
 543 }
 544
 545 /**
 546  * gst_pipeline_get_clock:
 547  * @pipeline: the pipeline
 548  *
 549  * Gets the current clock used by the pipeline.
 550  *
 551  * Returns: a GstClock
 552  */
 553 GstClock *
 554 gst_pipeline_get_clock (GstPipeline * pipeline)
 555 {
 556   g_return_val_if_fail (GST_IS_PIPELINE (pipeline), NULL);
 557
 558   return gst_pipeline_provide_clock_func (GST_ELEMENT (pipeline));
 559 }
 560
 561
 562 /**
 563  * gst_pipeline_use_clock:
 564  * @pipeline: the pipeline
 565  * @clock: the clock to use
 566  *
 567  * Force the pipeline to use the given clock. The pipeline will
 568  * always use the given clock even if new clock providers are added
 569  * to this pipeline.
 570  *
 571  * MT safe.
 572  */
 573 void
 574 gst_pipeline_use_clock (GstPipeline * pipeline, GstClock * clock)
 575 {
 576   g_return_if_fail (GST_IS_PIPELINE (pipeline));
 577
 578   GST_OBJECT_LOCK (pipeline);
 579   GST_OBJECT_FLAG_SET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK);
 580
 581   gst_object_replace ((GstObject **) & pipeline->fixed_clock,
 582       (GstObject *) clock);
 583   GST_OBJECT_UNLOCK (pipeline);
 584
 585   GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using fixed clock %p (%s)", clock,
 586       (clock ? GST_OBJECT_NAME (clock) : "nil"));
 587 }
 588
 589 /**
 590  * gst_pipeline_set_clock:
 591  * @pipeline: the pipeline
 592  * @clock: the clock to set
 593  *
 594  * Set the clock for the pipeline. The clock will be distributed
 595  * to all the elements managed by the pipeline.
 596  *
 597  * Returns: TRUE if the clock could be set on the pipeline.
 598  *
 599  * MT safe.
 600  */
 601 gboolean
 602 gst_pipeline_set_clock (GstPipeline * pipeline, GstClock * clock)
 603 {
 604   g_return_val_if_fail (pipeline != NULL, FALSE);
 605   g_return_val_if_fail (GST_IS_PIPELINE (pipeline), FALSE);
 606
 607   return GST_ELEMENT_CLASS (parent_class)->set_clock (GST_ELEMENT (pipeline),
 608       clock);
 609 }
 610
 611 /**
 612  * gst_pipeline_auto_clock:
 613  * @pipeline: the pipeline
 614  *
 615  * Let the pipeline select a clock automatically.
 616  *
 617  * MT safe.
 618  */
 619 void
 620 gst_pipeline_auto_clock (GstPipeline * pipeline)
 621 {
 622   g_return_if_fail (pipeline != NULL);
 623   g_return_if_fail (GST_IS_PIPELINE (pipeline));
 624
 625   GST_OBJECT_LOCK (pipeline);
 626   GST_OBJECT_FLAG_UNSET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK);
 627
 628   gst_object_replace ((GstObject **) & pipeline->fixed_clock, NULL);
 629   GST_OBJECT_UNLOCK (pipeline);
 630
 631   GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using automatic clock");
 632 }