Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
A Asset
in the GStreamer Editing Services represents a resources
that can be used. In particular, any class that implements the
Extractable
interface may have some associated assets with a
corresponding Asset:extractableType, from which its objects can be
extracted using assetExtract
. Some examples would be
Clip
, Formatter
and TrackElement
.
All assets that are created within GES are stored in a cache; one per
each Asset:id and Asset:extractableType pair. These assets can
be fetched, and initialized if they do not yet exist in the cache,
using assetRequest
.
c code
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));
The advantage of using assets, rather than simply creating the object
directly, is that the currently loaded resources can be listed with
listAssets
and displayed to an end user. For example, to show
which media files have been loaded, and a standard list of effects. In
fact, the GES library already creates assets for TransitionClip
and
Formatter
, which you can use to list all the available transition
types and supported formats.
The other advantage is that Asset
implements MetaContainer
, so
metadata can be set on the asset, with some subclasses automatically
creating this metadata on initiation.
For example, to display information about the supported formats, you could do the following: > > 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) { > gst_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); >
ID
Each asset is uniquely defined in the cache by its
Asset:extractableType and Asset:id. Depending on the
Asset:extractableType, the Asset:id can be used to parametrise
the creation of the object upon extraction. By default, a class that
implements Extractable
will only have a single associated asset,
with an Asset:id set to the type name of its objects. However, this
is overwritten by some implementations, which allow a class to have
multiple associated assets. For example, for TransitionClip
the
Asset:id will be a nickname of the TransitionClip:vtype. You
should check the documentation for each extractable type to see if they
differ from the default.
Moreover, each Asset:extractableType may also associate itself with a specific asset subclass. In such cases, when their asset is requested, an asset of this subclass will be returned instead.
Managing
You can use a Project
to easily manage the assets of a
Timeline
.
Proxies
Some assets can (temporarily) act as the Asset:proxy of another
asset. When the original asset is requested from the cache, the proxy
will be returned in its place. This can be useful if, say, you want
to substitute a UriClipAsset
corresponding to a high resolution
media file with the asset of a lower resolution stand in.
An asset may even have several proxies, the first of which will act as
its default and be returned on requests, but the others will be ordered
to take its place once it is removed. You can add a proxy to an asset,
or set its default, using assetSetProxy
, and you can remove
them with assetUnproxy
.
Synopsis
- newtype Asset = Asset (ManagedPtr Asset)
- class (GObject o, IsDescendantOf Asset o) => IsAsset o
- toAsset :: (MonadIO m, IsAsset o) => o -> m Asset
- assetExtract :: (HasCallStack, MonadIO m, IsAsset a) => a -> m Extractable
- assetGetError :: (HasCallStack, MonadIO m, IsAsset a) => a -> m (Maybe GError)
- assetGetExtractableType :: (HasCallStack, MonadIO m, IsAsset a) => a -> m GType
- assetGetId :: (HasCallStack, MonadIO m, IsAsset a) => a -> m Text
- assetGetProxy :: (HasCallStack, MonadIO m, IsAsset a) => a -> m (Maybe Asset)
- assetGetProxyTarget :: (HasCallStack, MonadIO m, IsAsset a) => a -> m (Maybe Asset)
- assetListProxies :: (HasCallStack, MonadIO m, IsAsset a) => a -> m [Asset]
- assetNeedsReload :: (HasCallStack, MonadIO m) => GType -> Maybe Text -> m Bool
- assetRequest :: (HasCallStack, MonadIO m) => GType -> Maybe Text -> m (Maybe Asset)
- assetRequestAsync :: (HasCallStack, MonadIO m, IsCancellable a) => GType -> Maybe Text -> Maybe a -> Maybe AsyncReadyCallback -> m ()
- assetRequestFinish :: (HasCallStack, MonadIO m, IsAsyncResult a) => a -> m Asset
- assetSetProxy :: (HasCallStack, MonadIO m, IsAsset a, IsAsset b) => a -> Maybe b -> m Bool
- assetUnproxy :: (HasCallStack, MonadIO m, IsAsset a, IsAsset b) => a -> b -> m Bool
- constructAssetExtractableType :: (IsAsset o, MonadIO m) => GType -> m (GValueConstruct o)
- getAssetExtractableType :: (MonadIO m, IsAsset o) => o -> m GType
- constructAssetId :: (IsAsset o, MonadIO m) => Text -> m (GValueConstruct o)
- getAssetId :: (MonadIO m, IsAsset o) => o -> m Text
- clearAssetProxy :: (MonadIO m, IsAsset o) => o -> m ()
- constructAssetProxy :: (IsAsset o, MonadIO m, IsAsset a) => a -> m (GValueConstruct o)
- getAssetProxy :: (MonadIO m, IsAsset o) => o -> m (Maybe Asset)
- setAssetProxy :: (MonadIO m, IsAsset o, IsAsset a) => o -> a -> m ()
- getAssetProxyTarget :: (MonadIO m, IsAsset o) => o -> m (Maybe Asset)
Exported types
Memory-managed wrapper type.
Instances
Eq Asset Source # | |
GObject Asset Source # | |
Defined in GI.GES.Objects.Asset | |
ManagedPtrNewtype Asset Source # | |
Defined in GI.GES.Objects.Asset toManagedPtr :: Asset -> ManagedPtr Asset | |
TypedObject Asset Source # | |
Defined in GI.GES.Objects.Asset | |
HasParentTypes Asset Source # | |
Defined in GI.GES.Objects.Asset | |
IsGValue (Maybe Asset) Source # | Convert |
Defined in GI.GES.Objects.Asset gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Asset -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Asset) | |
type ParentTypes Asset Source # | |
Defined in GI.GES.Objects.Asset |
class (GObject o, IsDescendantOf Asset o) => IsAsset o Source #
Instances
(GObject o, IsDescendantOf Asset o) => IsAsset o Source # | |
Defined in GI.GES.Objects.Asset |
Methods
Click to display all available methods, including inherited ones
Methods
addMetasFromString, bindProperty, bindPropertyFull, checkMetaRegistered, extract, forceFloating, foreach, freezeNotify, getv, init, initAsync, initFinish, isFloating, listProxies, metasToString, newFinish, notify, notifyByPspec, ref, refSink, registerMeta, registerMetaBoolean, registerMetaDate, registerMetaDateTime, registerMetaDouble, registerMetaFloat, registerMetaInt, registerMetaInt64, registerMetaString, registerMetaUint, registerMetaUint64, registerStaticMeta, runDispose, stealData, stealQdata, thawNotify, unproxy, unref, watchClosure.
Getters
getBoolean, getData, getDate, getDateTime, getDouble, getError, getExtractableType, getFloat, getId, getInt, getInt64, getMarkerList, getMeta, getProperty, getProxy, getProxyTarget, getQdata, getString, getUint, getUint64.
Setters
setBoolean, setData, setDataFull, setDate, setDateTime, setDouble, setFloat, setInt, setInt64, setMarkerList, setMeta, setProperty, setProxy, setString, setUint, setUint64.
extract
:: (HasCallStack, MonadIO m, IsAsset a) | |
=> a |
|
-> m Extractable | Returns: A newly created object, or |
Extracts a new Asset:extractableType object from the asset. The Asset:id of the asset may determine the properties and state of the newly created object.
getError
:: (HasCallStack, MonadIO m, IsAsset a) | |
=> a |
|
-> m (Maybe GError) | Returns: The error set on |
Retrieve the error that was set on the asset when it was loaded.
Since: 1.8
getExtractableType
assetGetExtractableType Source #
:: (HasCallStack, MonadIO m, IsAsset a) | |
=> a |
|
-> m GType | Returns: The extractable type of |
Gets the Asset:extractableType of the asset.
getId
:: (HasCallStack, MonadIO m, IsAsset a) | |
=> a |
|
-> m Text | Returns: The ID of |
Gets the Asset:id of the asset.
getProxy
:: (HasCallStack, MonadIO m, IsAsset a) | |
=> a |
|
-> m (Maybe Asset) | Returns: The default proxy of |
Gets the default Asset:proxy of the asset.
getProxyTarget
:: (HasCallStack, MonadIO m, IsAsset a) | |
=> a |
|
-> m (Maybe Asset) | Returns: The asset that |
Gets the Asset:proxyTarget of the asset.
Note that the proxy target may have loaded with an error, so you should
call assetGetError
on the returned target.
listProxies
:: (HasCallStack, MonadIO m, IsAsset a) | |
=> a |
|
-> m [Asset] | Returns: The list of proxies
that |
Get all the proxies that the asset has. The first item of the list will be the default Asset:proxy. The second will be the proxy that is 'next in line' to be default, and so on.
needsReload
:: (HasCallStack, MonadIO m) | |
=> GType |
|
-> Maybe Text |
|
-> m Bool | Returns: |
Indicate that an existing Asset
in the cache should be reloaded
upon the next request. This can be used when some condition has
changed, which may require that an existing asset should be updated.
For example, if an external resource has changed or now become
available.
Note, the asset is not immediately changed, but will only actually
reload on the next call to assetRequest
or
assetRequestAsync
.
request
:: (HasCallStack, MonadIO m) | |
=> GType |
|
-> Maybe Text |
|
-> m (Maybe Asset) | Returns: A reference to the requested
asset, or |
Returns an asset with the given properties. If such an asset already exists in the cache (it has been previously created in GES), then a reference to the existing asset is returned. Otherwise, a newly created asset is returned, and also added to the cache.
If the requested asset has been loaded with an error, then error
is
set, if given, and Nothing
will be returned instead.
Note that the given id
may not be exactly the Asset:id that is
set on the returned asset. For instance, it may be adjusted into a
standard format. Or, if a Extractable
type does not have its
extraction parametrised, as is the case by default, then the given id
may be ignored entirely and the Asset:id set to some standard, in
which case a Nothing
id
can be given.
Similarly, the given extractableType
may not be exactly the
Asset:extractableType that is set on the returned asset. Instead,
the actual extractable type may correspond to a subclass of the given
extractableType
, depending on the given id
.
Moreover, depending on the given extractableType
, the returned asset
may belong to a subclass of Asset
.
Finally, if the requested asset has a Asset:proxy, then the proxy that is found at the end of the chain of proxies is returned (a proxy's proxy will take its place, and so on, unless it has no proxy).
Some asset subclasses only support asynchronous construction of its
assets, such as UriClip
. For such assets this method will fail, and
you should use assetRequestAsync
instead. In the case of
UriClip
, you can use uriClipAssetRequestSync
if you only
want to wait for the request to finish.
requestAsync
:: (HasCallStack, MonadIO m, IsCancellable a) | |
=> GType |
|
-> Maybe Text |
|
-> Maybe a |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Requests an asset with the given properties asynchronously (see
assetRequest
). When the asset has been initialized or fetched
from the cache, the given callback function will be called. The
asset can then be retrieved in the callback using the
assetRequestFinish
method on the given AsyncResult
.
Note that the source object passed to the callback will be the
Asset
corresponding to the request, but it may not have loaded
correctly and therefore can not be used as is. Instead,
assetRequestFinish
should be used to fetch a usable asset, or
indicate that an error occurred in the asset's creation.
Note that the callback will be called in the MainLoop
running under
the same MainContext
that init
was called in. So, if you wish
the callback to be invoked outside the default MainContext
, you can
call mainContextPushThreadDefault
in a new thread before
calling init
.
Example of an asynchronous asset request:
c code
// 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) { gst_print ("The file: %s is usable as a GESUriClip", ges_asset_get_id (asset)); } else { gst_print ("The file: %s is *not* usable as a GESUriClip because: %s", ges_asset_get_id (source), error->message); } gst_object_unref (asset); } // The request: ges_asset_request_async (GES_TYPE_URI_CLIP, some_uri, NULL, (GAsyncReadyCallback) asset_loaded_cb, user_data);
requestFinish
:: (HasCallStack, MonadIO m, IsAsyncResult a) | |
=> a |
|
-> m Asset | Returns: The requested asset, or |
Fetches an asset requested by assetRequestAsync
, which
finalises the request.
setProxy
:: (HasCallStack, MonadIO m, IsAsset a, IsAsset b) | |
=> a |
|
-> Maybe b |
|
-> m Bool | Returns: |
Sets the Asset:proxy for the asset.
If proxy
is among the existing proxies of the asset (see
assetListProxies
) it will be moved to become the default
proxy. Otherwise, if proxy
is not Nothing
, it will be added to the list
of proxies, as the new default. The previous default proxy will become
'next in line' for if the new one is removed, and so on. As such, this
will **not** actually remove the previous default proxy (use
assetUnproxy
for that).
Note that an asset can only act as a proxy for one other asset.
As a special case, if proxy
is Nothing
, then this method will actually
remove **all** proxies from the asset.
unproxy
:: (HasCallStack, MonadIO m, IsAsset a, IsAsset b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: |
Removes the proxy from the available list of proxies for the asset. If
the given proxy is the default proxy of the list, then the next proxy
in the available list (see assetListProxies
) will become the
default. If there are no other proxies, then the asset will no longer
have a default Asset:proxy.
Properties
extractableType
The Extractable
object type that can be extracted from the asset.
constructAssetExtractableType :: (IsAsset o, MonadIO m) => GType -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “extractable-type
” property. This is rarely needed directly, but it is used by new
.
getAssetExtractableType :: (MonadIO m, IsAsset o) => o -> m GType Source #
Get the value of the “extractable-type
” property.
When overloading is enabled, this is equivalent to
get
asset #extractableType
id
The ID of the asset. This should be unique amongst all assets with
the same Asset:extractableType. Depending on the associated
Extractable
implementation, this id may convey some information
about the Object
that should be extracted. Note that, as such, the
ID will have an expected format, and you can not choose this value
arbitrarily. By default, this will be set to the type name of the
Asset:extractableType, but you should check the documentation
of the extractable type to see whether they differ from the
default behaviour.
constructAssetId :: (IsAsset o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “id
” property. This is rarely needed directly, but it is used by new
.
getAssetId :: (MonadIO m, IsAsset o) => o -> m Text Source #
Get the value of the “id
” property.
When overloading is enabled, this is equivalent to
get
asset #id
proxy
The default proxy for this asset, or Nothing
if it has no proxy. A
proxy will act as a substitute for the original asset when the
original is requested (see assetRequest
).
Setting this property will not usually remove the existing proxy, but
will replace it as the default (see assetSetProxy
).
clearAssetProxy :: (MonadIO m, IsAsset o) => o -> m () Source #
Set the value of the “proxy
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#proxy
constructAssetProxy :: (IsAsset o, MonadIO m, IsAsset a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “proxy
” property. This is rarely needed directly, but it is used by new
.
getAssetProxy :: (MonadIO m, IsAsset o) => o -> m (Maybe Asset) Source #
Get the value of the “proxy
” property.
When overloading is enabled, this is equivalent to
get
asset #proxy
setAssetProxy :: (MonadIO m, IsAsset o, IsAsset a) => o -> a -> m () Source #
Set the value of the “proxy
” property.
When overloading is enabled, this is equivalent to
set
asset [ #proxy:=
value ]
proxyTarget
The asset that this asset is a proxy for, or Nothing
if it is not a
proxy for another asset.
Note that even if this asset is acting as a proxy for another asset,
but this asset is not the default Asset:proxy, then proxy
-target
will *still* point to this other asset. So you should check the
Asset:proxy property of target
-proxy before assuming it is the
current default proxy for the target.
Note that the Object::notify for this property is emitted after the Asset:proxy Object::notify for the corresponding (if any) asset it is now the proxy of/no longer the proxy of.
getAssetProxyTarget :: (MonadIO m, IsAsset o) => o -> m (Maybe Asset) Source #
Get the value of the “proxy-target
” property.
When overloading is enabled, this is equivalent to
get
asset #proxyTarget