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