GESAsset

## GESAsset GESAsset — Represents usable resources inside the GStreamer Editing Services |

## Synopsis

    #include <ges/ges.h>

                        GESAsset;
    GType               ges_asset_get_extractable_type      (GESAsset *self);
    const gchar *       ges_asset_get_id                    (GESAsset *self);
    GESAsset *          ges_asset_request                   (GType extractable_type,
                                                             const gchar *id,
                                                             GError **error);
    void                ges_asset_request_async             (GType extractable_type,
                                                             const gchar *id,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GESAsset *          ges_asset_request_finish            (GAsyncResult *res,
                                                             GError **error);
    GESExtractable *    ges_asset_extract                   (GESAsset *self,
                                                             GError **error);
    GList *             ges_list_assets                     (GType filter);

## Object Hierarchy

      GObject
       +----GESAsset
             +----GESProject
             +----GESClipAsset
             +----GESTrackElementAsset

## Implemented Interfaces

GESAsset implements GAsyncInitable, GInitable and GESMetaContainer.

## Description

The Assets in the GStreamer Editing Services represent the resources that can be used. You can create assets for any type that implements the GESExtractable interface, for example GESClips, GESFormatter, and GESTrackElement do implement it. This means that assets will represent for example a GESUriClips, GESBaseEffect etc, and then you can extract objects of those types with the appropriate parameters from the asset using the ges_asset_extract method:

    1
    2
    3
    4
    5
    6
    7
    8
    GESAsset *effect_asset;
    GESEffect *effect;

    // You create an asset for an effect
    effect_asset = ges_asset_request (GES_TYPE_EFFECT, "agingtv", NULL);

    // And now you can extract an instance of GESEffect from that asset
    effect = GES_EFFECT (ges_asset_extract (effect_asset));

In that example, the advantages of having a GESAsset are that you can know what effects you are working with and let your user know about the avalaible ones, you can add metadata to the GESAsset through the GESMetaContainer interface and you have a model for your custom effects. Note that GESAsset management is making easier thanks to the GESProject class.

Each asset is represented by a pair of `extractable_type` and `id` (string). Actually the `extractable_type` is the type that implements the GESExtractable interface, that means that for example for a GESUriClip, the type that implements the GESExtractable interface is GESClip. The identifier represents different things depending on the `extractable_type` and you should check the documentation of each type to know what the ID of GESAsset actually represents for that type. By default, we only have one GESAsset per type, and the `id` is the name of the type, but this behaviour is overriden to be more useful. For example, for GESTransitionClips, the ID is the vtype of the transition you will extract from it (ie crossfade, box-wipe-rc etc..) For GESEffect the ID is the `bin`-description property of the extracted objects (ie the gst-launch style description of the bin that will be used).

Each and every GESAsset is cached into GES, and you can query those with the ges_list_assets function. Also the system will automatically register GESAssets for GESFormatters and GESTransitionClips and standard effects (actually not implemented yet) and you can simply query those calling:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    GList *formatter_assets, *tmp;

    //  List all  the transitions
    formatter_assets = ges_list_assets (GES_TYPE_FORMATTER);

    // Print some infos about the formatter GESAsset
    for (tmp = formatter_assets; tmp; tmp = tmp->next) {
      g_print ("Name of the formatter: %s, file extension it produces: %s",
        ges_meta_container_get_string (GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_NAME),
        ges_meta_container_get_string (GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_EXTENSION));
    }

    g_list_free (transition_assets);

You can request the creation of GESAssets using either ges_asset_request_async or ges_asset_request_async. All the GESAssets are cached and thus any asset that has already been created can be requested again without overhead.

## Details

### GESAsset

    typedef struct _GESAsset GESAsset;

### ges_asset_get_extractable_type ()

    GType               ges_asset_get_extractable_type      (GESAsset *self);

Gets the type of object that can be extracted from `self`

`self` : | The GESAsset
Returns : | the type of object that can be extracted from `self`

### ges_asset_get_id ()

    const gchar *       ges_asset_get_id                    (GESAsset *self);

Gets the ID of a GESAsset

`self` : | The GESAsset to get ID from
Returns : | The ID of `self`

### ges_asset_request ()

    GESAsset *          ges_asset_request                   (GType extractable_type,
                                                             const gchar *id,
                                                             GError **error);

Create a GESAsset in the most simple cases, you should look at the `extractable_type` documentation to see if that constructor can be called for this particular type

As it is recommanded not to instanciate assets for GESUriClip synchronously, it will not work with this method, but you can instead use the specific ges_uri_clip_asset_request_sync method if you really want to.

`extractable_type` : | The GType of the object that can be extracted from the new asset.
`id` : | The Identifier or `NULL`. [allow-none]
`error` : | An error to be set in case something wrong happens or `NULL`. [allow-none]
Returns : | A reference to the wanted GESAsset or `NULL`. [transfer full][allow-none]

### ges_asset_request_async ()

    void                ges_asset_request_async             (GType extractable_type,
                                                             const gchar *id,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request a new GESAsset asyncronously, `callback` will be called when the materail is ready to be used or if an error occured.

Example of request of a GESAsset async:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    // The request callback
    static void
    asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user_data)
    {
      GESAsset *asset;
      GError *error = NULL;

      asset = ges_asset_request_finish (res, &error);
      if (asset) {
       g_print ("The file: %s is usable as a FileSource",
           ges_asset_get_id (asset));
      } else {
       g_print ("The file: %s is *not* usable as a FileSource because: %s",
           ges_asset_get_id (source), error->message);
      }

      gst_object_unref (mfs);
    }

    // The request:
    ges_asset_request_async (GES_TYPE_URI_CLIP, some_uri, NULL,
       (GAsyncReadyCallback) asset_loaded_cb, user_data);

`extractable_type` : | The GType of the object that can be extracted from the new asset. The class must implement the GESExtractable interface.
`id` : | The Identifier of the asset we want to create. This identifier depends of the extractable, type you want. By default it is the name of the class itself (or `NULL`), but for example for a GESEffect, it will be the pipeline description, for a GESUriClip it will be the name of the file, etc... You should refer to the documentation of the GESExtractable type you want to create a GESAsset for.
`cancellable` : | optional `GCancellable` object, `NULL` to ignore. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the initialization is finished, Note that the `source` of the callback will be the GESAsset, but you need to make sure that the asset is properly loaded using the ges_asset_request_finish method. This asset can not be used as is.
`user_data` : | The user data to pass when `callback` is called

### ges_asset_request_finish ()

    GESAsset *          ges_asset_request_finish            (GAsyncResult *res,
                                                             GError **error);

Finalize the request of an async GESAsset

`res` : | The GAsyncResult from which to get the newly created GESAsset
`error` : | An error to be set in case something wrong happens or `NULL`. [out][allow-none][transfer full]
Returns : | The GESAsset previously requested. [transfer full][allow-none]

### ges_asset_extract ()

    GESExtractable *    ges_asset_extract                   (GESAsset *self,
                                                             GError **error);

Extracts a new GObject from `asset`. The type of the object is defined by the extractable-type of `asset`, you can check what type will be extracted from `asset` using ges_asset_get_extractable_type

`self` : | The GESAsset to get extract an object from
`error` : | An error to be set in case something wrong happens or `NULL`. [allow-none]
Returns : | A newly created GESExtractable. [transfer floating][allow-none]

### ges_list_assets ()

    GList *             ges_list_assets                     (GType filter);

List all `asset` filtering per filter as defined by `filter`. It copies the asset and thus will not be updated in time.

`filter` : | Type of assets to list, GES_TYPE_EXTRACTABLE will list all assets
Returns : | The list of GESAsset the object contains. [transfer container][element-type GESAsset]