docs: Update documentation
[platform/upstream/gstreamer.git] / ges / ges-track.c
1 /* GStreamer Editing Services
2  * Copyright (C) 2009 Edward Hervey <edward.hervey@collabora.co.uk>
3  *               2009 Nokia Corporation
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Library General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Library General Public License for more details.
14  *
15  * You should have received a copy of the GNU Library General Public
16  * License along with this library; if not, write to the
17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18  * Boston, MA 02111-1307, USA.
19  */
20
21 /**
22  * SECTION:ges-track
23  * @short_description: Composition of objects
24  *
25  * Corresponds to one output format (i.e. audio OR video).
26  *
27  * Contains the compatible TrackObject(s).
28  *
29  * Wraps GNonLin's 'gnlcomposition' element.
30  */
31
32 #include "ges-internal.h"
33 #include "ges-track.h"
34 #include "ges-track-object.h"
35 #include "gesmarshal.h"
36
37 G_DEFINE_TYPE (GESTrack, ges_track, GST_TYPE_BIN);
38
39 struct _GESTrackPrivate
40 {
41   /*< private > */
42   GESTimeline *timeline;
43   GList *trackobjects;
44   guint64 duration;
45
46   GstCaps *caps;
47
48   GstElement *composition;      /* The composition associated with this track */
49   GstElement *background;       /* The backgrond, handle the gaps in the track */
50   GstPad *srcpad;               /* The source GhostPad */
51 };
52
53 enum
54 {
55   ARG_0,
56   ARG_CAPS,
57   ARG_TYPE,
58   ARG_DURATION,
59   ARG_LAST,
60   TRACK_OBJECT_ADDED,
61   TRACK_OBJECT_REMOVED,
62   LAST_SIGNAL
63 };
64
65 static guint ges_track_signals[LAST_SIGNAL] = { 0 };
66
67 static GParamSpec *properties[ARG_LAST];
68
69 static void pad_added_cb (GstElement * element, GstPad * pad, GESTrack * track);
70 static void
71 pad_removed_cb (GstElement * element, GstPad * pad, GESTrack * track);
72 static void composition_duration_cb (GstElement * composition, GParamSpec * arg
73     G_GNUC_UNUSED, GESTrack * obj);
74 static void
75 sort_track_objects_cb (GESTrackObject * child,
76     GParamSpec * arg G_GNUC_UNUSED, GESTrack * track);
77
78 static void
79 ges_track_get_property (GObject * object, guint property_id,
80     GValue * value, GParamSpec * pspec)
81 {
82   GESTrack *track = GES_TRACK (object);
83
84   switch (property_id) {
85     case ARG_CAPS:
86       gst_value_set_caps (value, track->priv->caps);
87       break;
88     case ARG_TYPE:
89       g_value_set_flags (value, track->type);
90       break;
91     case ARG_DURATION:
92       g_value_set_uint64 (value, track->priv->duration);
93       break;
94     default:
95       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
96   }
97 }
98
99 static void
100 ges_track_set_property (GObject * object, guint property_id,
101     const GValue * value, GParamSpec * pspec)
102 {
103   GESTrack *track = GES_TRACK (object);
104
105   switch (property_id) {
106     case ARG_CAPS:
107       ges_track_set_caps (track, gst_value_get_caps (value));
108       break;
109     case ARG_TYPE:
110       track->type = g_value_get_flags (value);
111       break;
112     default:
113       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
114   }
115 }
116
117 static void
118 ges_track_dispose (GObject * object)
119 {
120   GESTrack *track = (GESTrack *) object;
121   GESTrackPrivate *priv = track->priv;
122
123   while (priv->trackobjects) {
124     GESTrackObject *trobj = GES_TRACK_OBJECT (priv->trackobjects->data);
125     ges_track_remove_object (track, trobj);
126     ges_timeline_object_release_track_object ((GESTimelineObject *)
127         ges_track_object_get_timeline_object (trobj), trobj);
128   }
129
130   if (priv->composition) {
131     gst_bin_remove (GST_BIN (object), priv->composition);
132     priv->composition = NULL;
133   }
134
135   if (priv->caps) {
136     gst_caps_unref (priv->caps);
137     priv->caps = NULL;
138   }
139
140   G_OBJECT_CLASS (ges_track_parent_class)->dispose (object);
141 }
142
143 static void
144 ges_track_constructed (GObject * object)
145 {
146   GObjectClass *parent_class;
147   GstElement *background = NULL;
148   GESTrack *self = GES_TRACK (object);
149   GESTrackPrivate *priv = self->priv;
150
151   if ((priv->background = gst_element_factory_make ("gnlsource", "background"))) {
152     g_object_set (G_OBJECT (self->priv->background), "expandable", TRUE,
153         "priority", G_MAXINT, NULL);
154
155     switch (self->type) {
156       case GES_TRACK_TYPE_VIDEO:
157         background = gst_element_factory_make ("videotestsrc", "background");
158         g_object_set (background, "pattern", 2, NULL);
159         break;
160       case GES_TRACK_TYPE_AUDIO:
161         background = gst_element_factory_make ("audiotestsrc", "background");
162         g_object_set (background, "wave", 4, NULL);
163         break;
164       default:
165         break;
166     }
167
168     if (background) {
169       if (!gst_bin_add (GST_BIN (priv->background), background))
170         GST_ERROR ("Couldn't add background");
171       else {
172         if (!gst_bin_add (GST_BIN (priv->composition), priv->background))
173           GST_ERROR ("Couldn't add background");
174       }
175
176     }
177   }
178
179   parent_class = ges_track_parent_class;
180   if (parent_class->constructed)
181     parent_class->constructed (object);
182
183   G_OBJECT_CLASS (parent_class)->constructed (object);
184 }
185
186 static void
187 ges_track_finalize (GObject * object)
188 {
189   G_OBJECT_CLASS (ges_track_parent_class)->finalize (object);
190 }
191
192 static void
193 ges_track_class_init (GESTrackClass * klass)
194 {
195   GObjectClass *object_class = G_OBJECT_CLASS (klass);
196
197   g_type_class_add_private (klass, sizeof (GESTrackPrivate));
198
199   object_class->get_property = ges_track_get_property;
200   object_class->set_property = ges_track_set_property;
201   object_class->dispose = ges_track_dispose;
202   object_class->finalize = ges_track_finalize;
203   object_class->constructed = ges_track_constructed;
204
205   /**
206    * GESTrack:caps
207    *
208    * Caps used to filter/choose the output stream. This is generally set to
209    * a generic set of caps like 'video/x-raw-rgb;video/x-raw-yuv' for raw video.
210    *
211    * Default value: #GST_CAPS_ANY.
212    */
213   properties[ARG_CAPS] = g_param_spec_boxed ("caps", "Caps",
214       "Caps used to filter/choose the output stream",
215       GST_TYPE_CAPS, G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
216   g_object_class_install_property (object_class, ARG_CAPS,
217       properties[ARG_CAPS]);
218
219   /**
220    * GESTrack:duration
221    *
222    * Current duration of the track
223    *
224    * Default value: O
225    */
226   properties[ARG_DURATION] = g_param_spec_uint64 ("duration", "Duration",
227       "The current duration of the track", 0, G_MAXUINT64, GST_SECOND,
228       G_PARAM_READABLE);
229   g_object_class_install_property (object_class, ARG_DURATION,
230       properties[ARG_DURATION]);
231
232   /**
233    * GESTrack:track-type
234    *
235    * Type of stream the track outputs. This is used when creating the #GESTrack
236    * to specify in generic terms what type of content will be outputted.
237    *
238    * It also serves as a 'fast' way to check what type of data will be outputted
239    * from the #GESTrack without having to actually check the #GESTrack's caps
240    * property.
241    */
242   properties[ARG_TYPE] = g_param_spec_flags ("track-type", "TrackType",
243       "Type of stream the track outputs",
244       GES_TYPE_TRACK_TYPE, GES_TRACK_TYPE_CUSTOM,
245       G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY);
246   g_object_class_install_property (object_class, ARG_TYPE,
247       properties[ARG_TYPE]);
248
249   /**
250    * GESTrack::track-object-added
251    * @object: the #GESTrack
252    * @effect: the #GESTrackObject that was added.
253    *
254    * Will be emitted after a track object was added to the track.
255    *
256    * Since: 0.10.2
257    */
258   ges_track_signals[TRACK_OBJECT_ADDED] =
259       g_signal_new ("track-object-added", G_TYPE_FROM_CLASS (klass),
260       G_SIGNAL_RUN_FIRST, 0, NULL, NULL, ges_marshal_VOID__OBJECT,
261       G_TYPE_NONE, 1, GES_TYPE_TRACK_OBJECT);
262
263   /**
264    * GESTrack::track-object-removed
265    * @object: the #GESTrack
266    * @effect: the #GESTrackObject that was removed.
267    *
268    * Will be emitted after a track object was removed from the track.
269    *
270    * Since: 0.10.2
271    */
272   ges_track_signals[TRACK_OBJECT_REMOVED] =
273       g_signal_new ("track-object-removed", G_TYPE_FROM_CLASS (klass),
274       G_SIGNAL_RUN_FIRST, 0, NULL, NULL, ges_marshal_VOID__OBJECT,
275       G_TYPE_NONE, 1, GES_TYPE_TRACK_OBJECT);
276 }
277
278 static void
279 ges_track_init (GESTrack * self)
280 {
281   self->priv = G_TYPE_INSTANCE_GET_PRIVATE (self,
282       GES_TYPE_TRACK, GESTrackPrivate);
283
284   self->priv->composition = gst_element_factory_make ("gnlcomposition", NULL);
285
286   g_signal_connect (G_OBJECT (self->priv->composition), "notify::duration",
287       G_CALLBACK (composition_duration_cb), self);
288   g_signal_connect (self->priv->composition, "pad-added",
289       (GCallback) pad_added_cb, self);
290   g_signal_connect (self->priv->composition, "pad-removed",
291       (GCallback) pad_removed_cb, self);
292
293   if (!gst_bin_add (GST_BIN (self), self->priv->composition))
294     GST_ERROR ("Couldn't add composition to bin !");
295 }
296
297 /**
298  * ges_track_new:
299  * @type: The type of track
300  * @caps: The caps to restrict the output of the track to.
301  *
302  * Creates a new #GESTrack with the given @type and @caps.
303  *
304  * The newly created track will steal a reference to the caps. If you wish to 
305  * use those caps elsewhere, you will have to take an extra reference.
306  *
307  * Returns: A new #GESTrack.
308  */
309 GESTrack *
310 ges_track_new (GESTrackType type, GstCaps * caps)
311 {
312   GESTrack *track;
313
314   track = g_object_new (GES_TYPE_TRACK, "caps", caps, "track-type", type, NULL);
315   gst_caps_unref (caps);
316
317   return track;
318 }
319
320 /**
321  * ges_track_video_raw_new:
322  *
323  * Creates a new #GESTrack of type #GES_TRACK_TYPE_VIDEO and with generic
324  * raw video caps ("video/x-raw-yuv;video/x-raw-rgb");
325  *
326  * Returns: A new #GESTrack.
327  */
328 GESTrack *
329 ges_track_video_raw_new (void)
330 {
331   GESTrack *track;
332   GstCaps *caps = gst_caps_from_string ("video/x-raw-yuv;video/x-raw-rgb");
333
334   track = ges_track_new (GES_TRACK_TYPE_VIDEO, caps);
335
336   return track;
337 }
338
339 /**
340  * ges_track_audio_raw_new:
341  *
342  * Creates a new #GESTrack of type #GES_TRACK_TYPE_AUDIO and with generic
343  * raw audio caps ("audio/x-raw-int;audio/x-raw-float");
344  *
345  * Returns: A new #GESTrack.
346  */
347 GESTrack *
348 ges_track_audio_raw_new (void)
349 {
350   GESTrack *track;
351   GstCaps *caps = gst_caps_from_string ("audio/x-raw-int;audio/x-raw-float");
352
353   track = ges_track_new (GES_TRACK_TYPE_AUDIO, caps);
354
355   return track;
356 }
357
358 /**
359  * ges_track_set_timeline:
360  * @track: a #GESTrack
361  * @timeline: a #GESTimeline
362  *
363  * Sets @timeline as the timeline controlling @track.
364  */
365 void
366 ges_track_set_timeline (GESTrack * track, GESTimeline * timeline)
367 {
368   GST_DEBUG ("track:%p, timeline:%p", track, timeline);
369
370   track->priv->timeline = timeline;
371 }
372
373 /**
374  * ges_track_set_caps:
375  * @track: a #GESTrack
376  * @caps: the #GstCaps to set
377  *
378  * Sets the given @caps on the track.
379  */
380 void
381 ges_track_set_caps (GESTrack * track, const GstCaps * caps)
382 {
383   GESTrackPrivate *priv;
384
385   g_return_if_fail (GES_IS_TRACK (track));
386   g_return_if_fail (GST_IS_CAPS (caps));
387
388   GST_DEBUG ("track:%p, caps:%" GST_PTR_FORMAT, track, caps);
389
390   priv = track->priv;
391
392   if (priv->caps)
393     gst_caps_unref (priv->caps);
394   priv->caps = gst_caps_copy (caps);
395
396   g_object_set (priv->composition, "caps", caps, NULL);
397   /* FIXME : update all trackobjects ? */
398 }
399
400
401 /* FIXME : put the compare function in the utils */
402
403 static gint
404 objects_start_compare (GESTrackObject * a, GESTrackObject * b)
405 {
406   if (a->start == b->start) {
407     if (a->priority < b->priority)
408       return -1;
409     if (a->priority > b->priority)
410       return 1;
411     return 0;
412   }
413   if (a->start < b->start)
414     return -1;
415   if (a->start > b->start)
416     return 1;
417   return 0;
418 }
419
420 /**
421  * ges_track_add_object:
422  * @track: a #GESTrack
423  * @object: (transfer full): the #GESTrackObject to add
424  *
425  * Adds the given object to the track. Sets the object's controlling track,
426  * and thus takes ownership of the @object.
427  *
428  * An object can only be added to one track.
429  *
430  * Returns: #TRUE if the object was properly added. #FALSE if the track does not
431  * want to accept the object.
432  */
433 gboolean
434 ges_track_add_object (GESTrack * track, GESTrackObject * object)
435 {
436   g_return_val_if_fail (GES_IS_TRACK (track), FALSE);
437   g_return_val_if_fail (GES_IS_TRACK_OBJECT (object), FALSE);
438
439   GST_DEBUG ("track:%p, object:%p", track, object);
440
441   if (G_UNLIKELY (ges_track_object_get_track (object) != NULL)) {
442     GST_WARNING ("Object already belongs to another track");
443     return FALSE;
444   }
445
446   /* At this point, the track object shouldn't have any gnlobject since
447    * it hasn't been added to a track yet.
448    * FIXME : This check seems a bit obsolete */
449   if (G_UNLIKELY (ges_track_object_get_gnlobject (object) != NULL)) {
450     GST_ERROR ("TrackObject already controls a gnlobject !");
451     return FALSE;
452   }
453
454   if (G_UNLIKELY (!ges_track_object_set_track (object, track))) {
455     GST_ERROR ("Couldn't properly add the object to the Track");
456     return FALSE;
457   }
458
459   GST_DEBUG ("Adding object %s to ourself %s",
460       GST_OBJECT_NAME (ges_track_object_get_gnlobject (object)),
461       GST_OBJECT_NAME (track->priv->composition));
462
463   if (G_UNLIKELY (!gst_bin_add (GST_BIN (track->priv->composition),
464               ges_track_object_get_gnlobject (object)))) {
465     GST_WARNING ("Couldn't add object to the GnlComposition");
466     return FALSE;
467   }
468
469   g_object_ref_sink (object);
470   track->priv->trackobjects =
471       g_list_insert_sorted (track->priv->trackobjects, object,
472       (GCompareFunc) objects_start_compare);
473
474   g_signal_emit (track, ges_track_signals[TRACK_OBJECT_ADDED], 0,
475       GES_TRACK_OBJECT (object));
476
477   g_signal_connect (GES_TRACK_OBJECT (object), "notify::start",
478       G_CALLBACK (sort_track_objects_cb), track);
479
480   g_signal_connect (GES_TRACK_OBJECT (object), "notify::priority",
481       G_CALLBACK (sort_track_objects_cb), track);
482
483   return TRUE;
484 }
485
486 /**
487  * ges_track_get_objects:
488  * @track: a #GESTrack
489  *
490  * Gets the #GESTrackObject contained in @track
491  *
492  * Returns: (transfer full) (element-type GESTrackObject): the list of
493  * #GESTrackObject present in the Track sorted by priority and start.
494  */
495 GList *
496 ges_track_get_objects (GESTrack * track)
497 {
498   GList *ret = NULL;
499   GList *tmp;
500
501   g_return_val_if_fail (GES_IS_TRACK (track), NULL);
502
503   for (tmp = track->priv->trackobjects; tmp; tmp = tmp->next) {
504     ret = g_list_prepend (ret, tmp->data);
505     g_object_ref (tmp->data);
506   }
507
508   ret = g_list_reverse (ret);
509   return ret;
510 }
511
512 /**
513  * ges_track_remove_object:
514  * @track: a #GESTrack
515  * @object: the #GESTrackObject to remove
516  *
517  * Removes the object from the track and unparents it.
518  * Unparenting it means the reference owned by @track on the @object will be
519  * removed. If you wish to use the @object after this function, make sure you
520  * call g_object_ref() before removing it from the @track.
521  *
522  * Returns: #TRUE if the object was removed, else #FALSE if the track
523  * could not remove the object (like if it didn't belong to the track).
524  */
525 gboolean
526 ges_track_remove_object (GESTrack * track, GESTrackObject * object)
527 {
528   GESTrackPrivate *priv;
529   GstElement *gnlobject;
530
531   g_return_val_if_fail (GES_IS_TRACK (track), FALSE);
532   g_return_val_if_fail (GES_IS_TRACK_OBJECT (object), FALSE);
533
534   GST_DEBUG ("track:%p, object:%p", track, object);
535
536   priv = track->priv;
537
538   if (G_UNLIKELY (ges_track_object_get_track (object) != track)) {
539     GST_WARNING ("Object belongs to another track");
540     return FALSE;
541   }
542
543   if ((gnlobject = ges_track_object_get_gnlobject (object))) {
544     GST_DEBUG ("Removing GnlObject '%s' from composition '%s'",
545         GST_ELEMENT_NAME (gnlobject), GST_ELEMENT_NAME (priv->composition));
546     if (!gst_bin_remove (GST_BIN (priv->composition), gnlobject)) {
547       GST_WARNING ("Failed to remove gnlobject from composition");
548       return FALSE;
549     }
550   }
551
552   ges_track_object_set_track (object, NULL);
553
554   g_signal_emit (track, ges_track_signals[TRACK_OBJECT_REMOVED], 0,
555       GES_TRACK_OBJECT (object));
556
557   priv->trackobjects = g_list_remove (priv->trackobjects, object);
558
559   g_object_unref (object);
560
561   return TRUE;
562 }
563
564 static void
565 pad_added_cb (GstElement * element, GstPad * pad, GESTrack * track)
566 {
567   GESTrackPrivate *priv = track->priv;
568
569   GST_DEBUG ("track:%p, pad %s:%s", track, GST_DEBUG_PAD_NAME (pad));
570
571   /* ghost the pad */
572   priv->srcpad = gst_ghost_pad_new ("src", pad);
573
574   gst_pad_set_active (priv->srcpad, TRUE);
575
576   gst_element_add_pad (GST_ELEMENT (track), priv->srcpad);
577
578   GST_DEBUG ("done");
579 }
580
581 static void
582 pad_removed_cb (GstElement * element, GstPad * pad, GESTrack * track)
583 {
584   GESTrackPrivate *priv = track->priv;
585
586   GST_DEBUG ("track:%p, pad %s:%s", track, GST_DEBUG_PAD_NAME (pad));
587
588   if (G_LIKELY (priv->srcpad)) {
589     gst_pad_set_active (priv->srcpad, FALSE);
590     gst_element_remove_pad (GST_ELEMENT (track), priv->srcpad);
591     priv->srcpad = NULL;
592   }
593
594   GST_DEBUG ("done");
595 }
596
597 static void
598 composition_duration_cb (GstElement * composition,
599     GParamSpec * arg G_GNUC_UNUSED, GESTrack * obj)
600 {
601   guint64 duration;
602
603   g_object_get (composition, "duration", &duration, NULL);
604
605
606   if (obj->priv->duration != duration) {
607     GST_DEBUG ("composition duration : %" GST_TIME_FORMAT " current : %"
608         GST_TIME_FORMAT, GST_TIME_ARGS (duration),
609         GST_TIME_ARGS (obj->priv->duration));
610
611     obj->priv->duration = duration;
612
613 #if GLIB_CHECK_VERSION(2,26,0)
614     g_object_notify_by_pspec (G_OBJECT (obj), properties[ARG_DURATION]);
615 #else
616     g_object_notify (G_OBJECT (obj), "duration");
617 #endif
618   }
619 }
620
621 static void
622 sort_track_objects_cb (GESTrackObject * child,
623     GParamSpec * arg G_GNUC_UNUSED, GESTrack * track)
624 {
625   track->priv->trackobjects =
626       g_list_sort (track->priv->trackobjects,
627       (GCompareFunc) objects_start_compare);
628 }
629
630 /**
631  * ges_track_get_caps:
632  * @track: a #GESTrack
633  *
634  * Get the #GstCaps this track is configured to output.
635  *
636  * Returns: The #GstCaps this track is configured to output.
637  */
638 const GstCaps *
639 ges_track_get_caps (GESTrack * track)
640 {
641   g_return_val_if_fail (GES_IS_TRACK (track), NULL);
642
643   return track->priv->caps;
644 }
645
646 /**
647  * ges_track_get_timeline:
648  * @track: a #GESTrack
649  *
650  * Get the #GESTimeline this track belongs to. Can be %NULL.
651  *
652  * Returns: The #GESTimeline this track belongs to. Can be %NULL.
653  */
654 const GESTimeline *
655 ges_track_get_timeline (GESTrack * track)
656 {
657   g_return_val_if_fail (GES_IS_TRACK (track), NULL);
658
659   return track->priv->timeline;
660 }
661
662 /**
663  * ges_track_enable_update:
664  * @track: a #GESTrack
665  * @enabled: %TRUE if the composition must be updated, FALSE otherwise.
666  *
667  * Sets the @track 's composition update property to @enabled .
668  *
669  * Returns: True if success, %FALSE otherwise.
670  */
671 gboolean
672 ges_track_enable_update (GESTrack * track, gboolean enabled)
673 {
674   gboolean update;
675
676   g_object_set (track->priv->composition, "update", enabled, NULL);
677
678   g_object_get (track->priv->composition, "update", &update, NULL);
679
680   if (update == enabled) {
681     return TRUE;
682   } else {
683     return FALSE;
684   }
685 }