mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-27 10:40:34 +00:00
docs: update GESExtractable
This commit is contained in:
Henry Wilkes
Thibault Saunier
parent
dfe3b805f3
commit
e55c87c5e5
2 changed files with 109 additions and 16 deletions
|
|
@ -21,9 +21,25 @@
|
|||
/**
|
||||
* SECTION: gesextractable
|
||||
* @title: GESExtractable Interface
|
||||
* @short_description: An interface for objects which can be extracted from a GESAsset
|
||||
* @short_description: An interface for objects which can be extracted
|
||||
* from a #GESAsset
|
||||
*
|
||||
* FIXME: Long description needed
|
||||
* A #GObject that implements the #GESExtractable interface can be
|
||||
* extracted from a #GESAsset using ges_asset_extract().
|
||||
*
|
||||
* Each extractable type will have its own way of interpreting the
|
||||
* #GESAsset:id of an asset (or, if it is associated with a specific
|
||||
* subclass of #GESAsset, the asset subclass may handle the
|
||||
* interpretation of the #GESAsset:id). By default, the requested asset
|
||||
* #GESAsset:id will be ignored by a #GESExtractable and will be set to
|
||||
* the type name of the extractable instead. Also by default, when the
|
||||
* requested asset is extracted, the returned object will simply be a
|
||||
* newly created default object of that extractable type. You should check
|
||||
* the documentation for each extractable type to see if they differ from
|
||||
* the default.
|
||||
*
|
||||
* After the object is extracted, it will have a reference to the asset it
|
||||
* came from, which you can retrieve using ges_extractable_get_asset().
|
||||
*/
|
||||
#ifdef HAVE_CONFIG_H
|
||||
#include "config.h"
|
||||
|
|
@ -86,12 +102,12 @@ ges_extractable_default_init (GESExtractableInterface * iface)
|
|||
|
||||
/**
|
||||
* ges_extractable_get_asset:
|
||||
* @self: The #GESExtractable from which to retrieve a #GESAsset
|
||||
* @self: A #GESExtractable
|
||||
*
|
||||
* Method for getting an asset from a #GESExtractable
|
||||
* Get the asset that has been set on the extractable object.
|
||||
*
|
||||
* Returns: (transfer none) (nullable): The #GESAsset or %NULL if none has
|
||||
* been set
|
||||
* Returns: (transfer none) (nullable): The asset set on @self, or %NULL
|
||||
* if no asset has been set.
|
||||
*/
|
||||
GESAsset *
|
||||
ges_extractable_get_asset (GESExtractable * self)
|
||||
|
|
@ -103,12 +119,22 @@ ges_extractable_get_asset (GESExtractable * self)
|
|||
|
||||
/**
|
||||
* ges_extractable_set_asset:
|
||||
* @self: Target object
|
||||
* @asset: (transfer none): The #GESAsset to set
|
||||
* @self: A #GESExtractable
|
||||
* @asset: (transfer none): The asset to set
|
||||
*
|
||||
* Method to set the asset which instantiated the specified object
|
||||
* Sets the asset for this extractable object.
|
||||
*
|
||||
* Return: %TRUE if @asset could be set %FALSE otherwize
|
||||
* When an object is extracted from an asset using ges_asset_extract() its
|
||||
* asset will be automatically set. Note that many classes that implement
|
||||
* #GESExtractable will automatically create their objects using assets
|
||||
* when you call their @new methods. However, you can use this method to
|
||||
* associate an object with a compatible asset if it was created by other
|
||||
* means and does not yet have an asset. Or, for some implementations of
|
||||
* #GESExtractable, you can use this to change the asset of the given
|
||||
* extractable object, which will lead to a change in its state to
|
||||
* match the new asset #GESAsset:id.
|
||||
*
|
||||
* Returns: %TRUE if @asset could be successfully set on @self.
|
||||
*/
|
||||
gboolean
|
||||
ges_extractable_set_asset (GESExtractable * self, GESAsset * asset)
|
||||
|
|
@ -123,15 +149,19 @@ ges_extractable_set_asset (GESExtractable * self, GESAsset * asset)
|
|||
if (iface->can_update_asset == FALSE &&
|
||||
g_object_get_qdata (G_OBJECT (self), ges_asset_key)) {
|
||||
GST_WARNING_OBJECT (self, "Can not reset asset on object");
|
||||
/* FIXME: do not fail if the same asset */
|
||||
|
||||
return FALSE;
|
||||
}
|
||||
/* FIXME: shouldn't we check that the extractable-type of the asset
|
||||
* matches our type? */
|
||||
|
||||
g_object_set_qdata_full (G_OBJECT (self), ges_asset_key,
|
||||
gst_object_ref (asset), gst_object_unref);
|
||||
|
||||
/* Let classes that implement the interface know that a asset has been set */
|
||||
if (iface->set_asset_full)
|
||||
/* FIXME: return to the previous asset if the setting fails */
|
||||
return iface->set_asset_full (self, asset);
|
||||
|
||||
if (iface->set_asset)
|
||||
|
|
@ -142,9 +172,18 @@ ges_extractable_set_asset (GESExtractable * self, GESAsset * asset)
|
|||
|
||||
/**
|
||||
* ges_extractable_get_id:
|
||||
* @self: The #GESExtractable
|
||||
* @self: A #GESExtractable
|
||||
*
|
||||
* Returns: (transfer full): The #id of the associated #GESAsset, free with #g_free
|
||||
* Gets the #GESAsset:id of some associated asset. It may be the case
|
||||
* that the object has no set asset, or even that such an asset does not
|
||||
* yet exist in the GES cache. Instead, this will return the asset
|
||||
* #GESAsset:id that is _compatible_ with the current state of the object,
|
||||
* as determined by the #GESExtractable implementer. If it was indeed
|
||||
* extracted from an asset, this should return the same as its
|
||||
* corresponding asset #GESAsset:id.
|
||||
*
|
||||
* Returns: (transfer full): The #GESAsset:id of some associated #GESAsset
|
||||
* that is compatible with @self's current state.
|
||||
*/
|
||||
gchar *
|
||||
ges_extractable_get_id (GESExtractable * self)
|
||||
|
|
|
|||
|
|
@ -42,18 +42,72 @@ GType ges_extractable_get_type (void);
|
|||
|
||||
/**
|
||||
* GESExtractableCheckId:
|
||||
* @type: The #GType to check @id for:
|
||||
* @id: The id to check
|
||||
* @type: The #GESExtractable type to check @id for
|
||||
* @id: The ID to check
|
||||
* @error: An error that can be set if needed
|
||||
*
|
||||
* Returns: The ID to use for the asset or %NULL if @id is not valid
|
||||
* Method for checking that an ID is valid for the given #GESExtractable
|
||||
* type. If the given ID is considered valid, it can be adjusted into some
|
||||
* standard and returned to prevent the creation of separate #GESAsset-s,
|
||||
* with different #GESAsset:id, that would otherwise act the same.
|
||||
*
|
||||
* Returns (transfer full) (nullable): The actual #GESAsset:id to set on
|
||||
* any corresponding assets, based on @id, or %NULL if @id is not valid.
|
||||
*/
|
||||
|
||||
typedef gchar* (*GESExtractableCheckId) (GType type, const gchar *id,
|
||||
GError **error);
|
||||
|
||||
/**
|
||||
* GESExtractable:
|
||||
* GESExtractableInterface:
|
||||
* @asset_type: The subclass type of #GESAsset that should be created when
|
||||
* an asset with the corresponding #GESAsset:extractable-type is
|
||||
* requested.
|
||||
* @check_id: The method to call to check whether a given ID is valid as
|
||||
* an asset #GESAsset:id for the given #GESAsset:extractable-type. The
|
||||
* returned ID is the actual #GESAsset:id that is set on the asset. The
|
||||
* default implementation will simply always return the type name of the
|
||||
* #GESAsset:extractable-type, even if the received ID is %NULL. As such,
|
||||
* any given ID is considered valid (or is ignored), but only one is
|
||||
* actually ever set on an asset, which means the given
|
||||
* #GESAsset:extractable-type can only have one associated asset.
|
||||
* @can_update_asset: Whether an object of this class can have its
|
||||
* #GESAsset change over its lifetime. This should be set to %TRUE if one
|
||||
* of the object's parameters that is associated with its ID can change
|
||||
* after construction, which would require an asset with a new ID. Note
|
||||
* that the subclass is required to handle the requesting and setting of
|
||||
* the new asset on the object.
|
||||
* @set_asset: This method is called after the #GESAsset of an object is
|
||||
* set. If your class supports the asset of an object changing, then you
|
||||
* can use this method to change the parameters of the object to match the
|
||||
* new asset #GESAsset:id. If setting the asset should be able to fail,
|
||||
* you should implement @set_asset_full instead.
|
||||
* @set_asset_full: Like @set_asset, but also allows you to return %FALSE
|
||||
* to indicate a failure to change the object in response to a change in
|
||||
* its asset.
|
||||
* @get_parameters_from_id: The method to call to get the object
|
||||
* properties corresponding to a given asset #GESAsset:id. The default
|
||||
* implementation will simply return no parameters. The default #GESAsset
|
||||
* will call this to set the returned properties on the extracted object,
|
||||
* but other subclasses may ignore this method.
|
||||
* @get_id: The method to fetch the #GESAsset:id of some associated asset.
|
||||
* Note that it may be the case that the object does not have its asset
|
||||
* set, or even that an asset with such an #GESAsset:id does not exist in
|
||||
* the GES cache. Instead, this should return the #GESAsset:id that is
|
||||
* _compatible_ with the current state of the object. The default
|
||||
* implementation simply returns the type name of the object, which is
|
||||
* what is used as the #GESAsset:id by default.
|
||||
* @get_real_extractable_type: The method to call to get the actual
|
||||
* #GESAsset:extractable-type an asset should have set, given the
|
||||
* requested #GESAsset:id. The default implementation simply returns the
|
||||
* same type as given. You can overwrite this if it is more appropriate
|
||||
* to extract the object from a subclass, depending on the requested
|
||||
* #GESAsset:id. Note that when an asset is requested, this method will be
|
||||
* called before the other class methods. In particular, this means that
|
||||
* the @check_id and @get_parameters_from_id class methods of the returned
|
||||
* type will be used (instead of our own).
|
||||
* @register_metas: The method to set metadata on an asset. This is called
|
||||
* on initiation of the asset, but before it begins to load its state.
|
||||
*/
|
||||
G_GNUC_BEGIN_IGNORE_DEPRECATIONS
|
||||
struct _GESExtractableInterface
|
||||
|
|
|
|||
Loading…
Reference in a new issue