gstreamer/ges/ges-clip.h

/* GStreamer Editing Services
 * Copyright (C) 2009 Edward Hervey <edward.hervey@collabora.co.uk>
 *               2009 Nokia Corporation
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 */

#ifndef _GES_CLIP
#define _GES_CLIP

#include <glib-object.h>
#include <gst/gst.h>
#include <ges/ges-timeline-element.h>
#include <ges/ges-container.h>
#include <ges/ges-types.h>
#include <ges/ges-track.h>

G_BEGIN_DECLS

#define GES_TYPE_CLIP             ges_clip_get_type()
#define GES_CLIP(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GES_TYPE_CLIP, GESClip))
#define GES_CLIP_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GES_TYPE_CLIP, GESClipClass))
#define GES_IS_CLIP(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GES_TYPE_CLIP))
#define GES_IS_CLIP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GES_TYPE_CLIP))
#define GES_CLIP_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GES_TYPE_CLIP, GESClipClass))

typedef struct _GESClipPrivate GESClipPrivate;

/**
 * GESFillTrackElementFunc:
 * @clip: the #GESClip controlling the track elements
 * @track_element: the #GESTrackElement
 * @gnlobj: the GNonLin object that needs to be filled.
 *
 * A function that will be called when the GNonLin object of a corresponding
 * track element needs to be filled.
 *
 * The implementer of this function shall add the proper #GstElement to @gnlobj
 * using gst_bin_add().
 *
 * Returns: TRUE if the implementer succesfully filled the @gnlobj, else #FALSE.
 */
typedef gboolean (*GESFillTrackElementFunc) (GESClip *clip,
                                            GESTrackElement *track_element,
                                            GstElement *gnlobj);

/**
 * GESCreateTrackElementFunc:
 * @clip: a #GESClip
 * @type: a #GESTrackType
 *
 * Creates the 'primary' track element for this @clip.
 *
 * Subclasses should implement this method if they only provide a
 * single #GESTrackElement per track.
 *
 * If the subclass needs to create more than one #GESTrackElement for a
 * given track, then it should implement the 'create_track_elements'
 * method instead.
 *
 * The implementer of this function shall return the proper #GESTrackElement
 * that should be controlled by @clip for the given @track.
 *
 * The returned #GESTrackElement will be automatically added to the list
 * of objects controlled by the #GESClip.
 *
 * Returns: the #GESTrackElement to be used, or %NULL if it can't provide one
 * for the given @track.
 */
typedef GESTrackElement *(*GESCreateTrackElementFunc) (GESClip * clip,
                                                     GESTrackType type);

/**
 * GESCreateTrackElementsFunc:
 * @clip: a #GESClip
 * @type: a #GESTrackType
 *
 * Create all track elements this clip handles for this type of track.
 *
 * Subclasses should implement this method if they potentially need to
 * return more than one #GESTrackElement(s) for a given #GESTrack.
 *
 * Returns: %TRUE on success %FALSE on failure.
 */

typedef GList * (*GESCreateTrackElementsFunc) (GESClip * clip, GESTrackType type);

/**
 * GESClip:
 *
 * The #GESClip base class.
 */
struct _GESClip
{
  GESContainer parent;

  /*< private >*/
  GESClipPrivate *priv;

  /* Padding for API extension */
  gpointer _ges_reserved[GES_PADDING_LARGE];
};

/**
 * GESClipClass:
 * @create_track_element: method to create a single #GESTrackElement for a given #GESTrack.
 * @create_track_elements: method to create multiple #GESTrackElements for a
 * #GESTrack.
 * @fill_track_element: method to fill an associated #GESTrackElement.
 * @need_fill_track: Set to TRUE if @fill_track_element needs to be called.
 *
 * Subclasses can override the @create_track_element and @fill_track_element methods.
 */
struct _GESClipClass
{
  /*< private > */
  GESContainerClass parent_class;

  /*< public > */
  GESCreateTrackElementFunc create_track_element;
  GESCreateTrackElementsFunc create_track_elements;

  /* FIXME : might need a release_track_element */
  GESFillTrackElementFunc fill_track_element;
  gboolean need_fill_track;

  /*< private >*/
  /* Padding for API extension */
  gpointer _ges_reserved[GES_PADDING_LARGE];
};

GType ges_clip_get_type (void);

/* Setters */
void ges_clip_set_layer            (GESClip *clip,
                                               GESTimelineLayer  *layer);

/* TrackElement handling */
GESTrackType ges_clip_get_supported_formats    (GESClip *clip);
GESTrackElement *ges_clip_create_track_element (GESClip *clip, GESTrackType type);
GList * ges_clip_create_track_elements         (GESClip *clip, GESTrackType type);
void ges_clip_set_supported_formats            (GESClip *clip, GESTrackType       supportedformats);

gboolean ges_clip_add_asset               (GESClip *clip, GESAsset       *asset);
gboolean ges_clip_fill_track_element          (GESClip *clip, GESTrackElement    *trackelement, GstElement *gnlobj);
GESTrackElement *ges_clip_find_track_element   (GESClip *clip, GESTrack          *track,    GType      type);

/* Layer */
GESTimelineLayer *ges_clip_get_layer   (GESClip *clip);
gboolean ges_clip_is_moving_from_layer (GESClip *clip);
gboolean ges_clip_move_to_layer        (GESClip *clip, GESTimelineLayer  *layer);
void ges_clip_set_moving_from_layer    (GESClip *clip, gboolean is_moving);

/* Effects */
GList* ges_clip_get_top_effects           (GESClip *clip);
gint   ges_clip_get_top_effect_position   (GESClip *clip, GESBaseEffect *effect);
gboolean ges_clip_set_top_effect_priority (GESClip *clip, GESBaseEffect *effect, guint newpriority);

/* Editing */
GESClip *ges_clip_split  (GESClip *clip, guint64  position);

gboolean ges_clip_edit             (GESClip *clip, GList   *layers,
                                               gint  new_layer_priority, GESEditMode mode,
                                               GESEdge edge, guint64 position);

G_END_DECLS
#endif /* _GES_CLIP */