GESClip

## GESClip GESClip — Base Class for objects in a GESLayer |

## Synopsis

    #include <ges/ges.h>

                        GESClip;
                        GESClipClass;
    GESTrackElement *   (*GESCreateTrackElementFunc)        (GESClip *clip,
                                                             GESTrackType type);
    GList *             (*GESCreateTrackElementsFunc)       (GESClip *clip,
                                                             GESTrackType type);
    gboolean            (*GESFillTrackElementFunc)          (GESClip *clip,
                                                             GESTrackElement *track_element,
                                                             GstElement *gnlobj);
    GESLayer *          ges_clip_get_layer                  (GESClip *clip);
    GESTrackElement *   ges_clip_find_track_element         (GESClip *clip,
                                                             GESTrack *track,
                                                             GType type);
    GESTrackElement *   ges_clip_add_asset                  (GESClip *clip,
                                                             GESAsset *asset);
    GList *             ges_clip_get_top_effects            (GESClip *clip);
    gint                ges_clip_get_top_effect_position    (GESClip *clip,
                                                             GESBaseEffect *effect);
    gboolean            ges_clip_move_to_layer              (GESClip *clip,
                                                             GESLayer *layer);
    gboolean            ges_clip_set_top_effect_priority    (GESClip *clip,
                                                             GESBaseEffect *effect,
                                                             guint newpriority);
    void                ges_clip_set_supported_formats      (GESClip *clip,
                                                             GESTrackType supportedformats);
    GESTrackType        ges_clip_get_supported_formats      (GESClip *clip);
    GESClip *           ges_clip_split                      (GESClip *clip,
                                                             guint64 position);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GESTimelineElement
                   +----GESContainer
                         +----GESClip
                               +----GESOperationClip
                               +----GESSourceClip

## Implemented Interfaces

GESClip implements GESExtractable and GESMetaContainer.

## Properties

      "layer"                    GESLayer*             : Read
      "supported-formats"        GESTrackType          : Read / Write / Construct

## Description

A GESClip is a 'natural' object which controls one or more GESTrackElement(s) in one or more GESTrack(s).

Keeps a reference to the GESTrackElement(s) it created and sets/updates their properties.

## Details

### GESClip

    typedef struct _GESClip GESClip;

The GESClip base class.

### GESClipClass

    typedef struct {
      GESCreateTrackElementFunc  create_track_element;
      GESCreateTrackElementsFunc create_track_elements;
    } GESClipClass;

Subclasses can override the `create_track_element`.

GESCreateTrackElementFunc `create_track_element`; | method to create a single GESTrackElement for a given GESTrack.
GESCreateTrackElementsFunc `create_track_elements`; | method to create multiple GESTrackElements for a GESTrack.

### GESCreateTrackElementFunc ()

    GESTrackElement *   (*GESCreateTrackElementFunc)        (GESClip *clip,
                                                             GESTrackType type);

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.

`clip` : | a GESClip
`type` : | a GESTrackType
Returns : | the GESTrackElement to be used, or `NULL` if it can't provide one for the given `track`.

### GESCreateTrackElementsFunc ()

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

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.

`clip` : | a GESClip
`type` : | a GESTrackType
Returns : | `TRUE` on success `FALSE` on failure.

### GESFillTrackElementFunc ()

    gboolean            (*GESFillTrackElementFunc)          (GESClip *clip,
                                                             GESTrackElement *track_element,
                                                             GstElement *gnlobj);

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()`.

`clip` : | the GESClip controlling the track elements
`track_element` : | the GESTrackElement
`gnlobj` : | the GNonLin object that needs to be filled.
Returns : | TRUE if the implementer succesfully filled the `gnlobj`, else FALSE.

### ges_clip_get_layer ()

    GESLayer *          ges_clip_get_layer                  (GESClip *clip);

Get the GESLayer to which this clip belongs.

`clip` : | a GESClip
Returns : | The GESLayer where this `clip` is being used, or `NULL` if it is not used on any layer. The caller should unref it usage. [transfer full]

### ges_clip_find_track_element ()

    GESTrackElement *   ges_clip_find_track_element         (GESClip *clip,
                                                             GESTrack *track,
                                                             GType type);

Finds the GESTrackElement controlled by `clip` that is used in `track`. You may optionally specify a GType to further narrow search criteria.

Note: If many objects match, then the one with the highest priority will be returned.

`clip` : | a GESClip
`track` : | a GESTrack or NULL
`type` : | a GType indicating the type of track element you are looking for or `G_TYPE_NONE` if you do not care about the track type.
Returns : | The GESTrackElement used by `track`, else `NULL`, Unref after usage. [transfer full]

### ges_clip_add_asset ()

    GESTrackElement *   ges_clip_add_asset                  (GESClip *clip,
                                                             GESAsset *asset);

Extracts a GESTrackElement from `asset` and adds it to the `clip`. Should only be called in order to add operations to a GESClip, ni other cases TrackElement are added automatically when adding the GESClip/GESAsset to a layer.

Takes a reference on `track_element`.

`clip` : | a GESClip
`asset` : | a GESAsset with GES_TYPE_TRACK_ELEMENT as extractable_type
Returns : | Created GESTrackElement or NULL if an error happened. [transfer none][allow-none]

### ges_clip_get_top_effects ()

    GList *             ges_clip_get_top_effects            (GESClip *clip);

Get effects applied on `clip`

`clip` : | The origin GESClip
Returns : | a GList of the GESBaseEffect that are applied on `clip` order by ascendant priorities. The refcount of the objects will be increased. The user will have to unref each GESBaseEffect and free the GList. [transfer full][element-type GESTrackElement]

Since 0.10.2

### ges_clip_get_top_effect_position ()

    gint                ges_clip_get_top_effect_position    (GESClip *clip,
                                                             GESBaseEffect *effect);

Gets the top position of an effect.

`clip` : | The origin GESClip
`effect` : | The GESBaseEffect we want to get the top position from
Returns : | The top position of the effect, -1 if something went wrong.

Since 0.10.2

### ges_clip_move_to_layer ()

    gboolean            ges_clip_move_to_layer              (GESClip *clip,
                                                             GESLayer *layer);

Moves `clip` to `layer`. If `clip` is not in any layer, it adds it to `layer`, else, it removes it from its current layer, and adds it to `layer`.

`clip` : | a GESClip
`layer` : | the new GESLayer
Returns : | `TRUE` if `clip` could be moved `FALSE` otherwize

### ges_clip_set_top_effect_priority ()

    gboolean            ges_clip_set_top_effect_priority    (GESClip *clip,
                                                             GESBaseEffect *effect,
                                                             guint newpriority);

This is a convenience method that lets you set the priority of a top effect.

`clip` : | The origin GESClip
`effect` : | The GESBaseEffect to move
`newpriority` : | the new position at which to move the `effect` inside this GESClip
Returns : | `TRUE` if `effect` was successfuly moved, `FALSE` otherwise.

Since 0.10.2

### ges_clip_set_supported_formats ()

    void                ges_clip_set_supported_formats      (GESClip *clip,
                                                             GESTrackType supportedformats);

Sets the formats supported by the file.

`clip` : | the GESClip to set supported formats on
`supportedformats` : | the GESTrackType defining formats supported by `clip`

Since 0.10.XX

### ges_clip_get_supported_formats ()

    GESTrackType        ges_clip_get_supported_formats      (GESClip *clip);

Get the formats supported by `clip`.

`clip` : | the GESClip
Returns : | The formats supported by `clip`.

Since 0.10.XX

### ges_clip_split ()

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

The function modifies `clip`, and creates another GESClip so we have two clips at the end, splitted at the time specified by `position`. The newly created clip will be added to the same layer as `clip` is in. This implies that `clip` must be in a GESLayer for the operation to be possible.

`clip` : | the GESClip to split
`position` : | a GstClockTime representing the position at which to split
Returns : | The newly created GESClip resulting from the splitting. [transfer none]

## Property Details

### The `"layer"` property

      "layer"                    GESLayer*             : Read

The GESLayer where this clip is being used. If you want to connect to its notify signal you should connect to it with g_signal_connect_after as the signal emission can be stop in the first fase.

### The `"supported-formats"` property

      "supported-formats"        GESTrackType          : Read / Write / Construct

The formats supported by the clip.

Default value: GES_TRACK_TYPE_AUDIO|GES_TRACK_TYPE_VIDEO

Since 0.10.XX