mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-23 10:11:08 +00:00
design: Add asset design document
Co-Authored-By: Volodymyr Rudyi <vladimir.rudoy@gmail.com>
This commit is contained in:
Thibault Saunier
parent
30e12995fd
commit
9209b3f69d
1 changed files with 321 additions and 0 deletions
321
docs/design/asset.txt
Normal file
321
docs/design/asset.txt
Normal file
|
|
@ -0,0 +1,321 @@
|
|||
Assets
|
||||
~~~~~~~~~
|
||||
|
||||
This draft document describes a possible design for asset objects.
|
||||
|
||||
The assets should be used in order to instantiate objects of differents
|
||||
types.
|
||||
|
||||
Terminology: A asset is an object from which objects can be extracted.
|
||||
|
||||
Summary
|
||||
~~~~~~~~~
|
||||
|
||||
1. Basic ideas
|
||||
2. Problems
|
||||
3. Propositions to solve those problems
|
||||
4. Use-cases
|
||||
5. API draft
|
||||
A. Asset API draft
|
||||
B. Source asset API draft
|
||||
C. Project asset API draft
|
||||
D. Extractable/Asset Interface API draft
|
||||
E. Methods that should be added to other classes
|
||||
|
||||
1. Basic ideas
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Basically, asset is a way of avoiding duplicating data between object and avoid
|
||||
processing when the same processing would happen several times for an 2 different
|
||||
objects of a same type.
|
||||
|
||||
* There will be a listing of avalaible, ready to use assets
|
||||
* Asset allow to create some particular types of object that implement the GESExtractable
|
||||
interface
|
||||
* Assets will hold metadatas
|
||||
* Assets can be either, created by the user, or will be created by GES itself
|
||||
when initializing, there should be a way to disable that feature on demand.
|
||||
|
||||
Some ideas of asset(especially for TimelineSource objects) can be found in docs/random/design.
|
||||
|
||||
2. Problems (Not in any particular order)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
1) We have avoid to various times the same file on the system
|
||||
2) We must be able to query assets by some criteria
|
||||
a. By type of TimelineObject that it can produce
|
||||
b. By type of supported tracks
|
||||
c. Should we have filters by some specific properties of source asset
|
||||
- like duration, width, height, etc?
|
||||
3) We must be able to get reference to origin asset of any extracted object
|
||||
4) We need a way to describe projects
|
||||
5) GESAssets can be instantiated asynchronously
|
||||
6) The instantiation of a asset can fail
|
||||
7) Users need to get informations about the instantiation failures
|
||||
8) User should be able to cancel the creation of a GESAsset (especially
|
||||
in case of asynchronous Asset creation)
|
||||
|
||||
3. Propositions to solve those problems
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1) We should have an interface that needs to be implemented by classes that need to be extractable.
|
||||
We can call it GESExtractable. It should be responsible for:
|
||||
* letting the user get the Asset from which an extracted object comes from
|
||||
* Making it possible to instantiate a GESAsset only from a GType which means that:
|
||||
- It needs to contain a reference to a GES_TYPE_ASSET (or subclass) so the proper GESAsset type will be instantiated.
|
||||
- It need to contain some mapping between the ID (string) of the asset, and the property of the object that is used as its ID.
|
||||
For a property to be usable as an ID for its asset, each objects extracted from a same asset must have the same value for the property
|
||||
Examples:
|
||||
GESTimelineFileSource -> URI
|
||||
GESTrackParseLaunchEffect -> bin_description
|
||||
GESProject -> project name / uri of the stored serialized
|
||||
|
||||
2) A list of all available, ready to be used assets should be cached and
|
||||
reused whenever it is possible.
|
||||
Basically it will look like:
|
||||
GESAsset.id -> asset
|
||||
(the ID is computed thanks to the mapping)
|
||||
|
||||
4) To allow users to implement some sort of library (media, effects, transitions...)
|
||||
we must be able to query assets by using some criteria,
|
||||
e.g. GType of the extractable object, URI, supported track types, etc...
|
||||
|
||||
5) We can instantiate a GESAsset only from a GType, the appropriate checks need
|
||||
to be done and it can return subclasses of GESAsset thanks to the
|
||||
information included in the GESExtractable interface.
|
||||
|
||||
6) Instanciation can happen asyncronously in some cases. For example, a
|
||||
asset that needs to discover a file to be properly filled needs.
|
||||
|
||||
4. Use cases
|
||||
~~~~~~~~~~~~~
|
||||
UC-1. Define media files and discover them
|
||||
UC-2. Define project - reference all assets
|
||||
UC-3. Define titles
|
||||
UC-4. Define operations
|
||||
- Transitions - 1 asset per transition type
|
||||
- Effects - 1 asset per effects type
|
||||
- TextOverlay
|
||||
UC-5. Handle metadata
|
||||
UC-6. Add operations (only effects?) to a GESTimelineObject
|
||||
UC-7. User want to 'invent' a new operation, we need to be able
|
||||
to let him define it
|
||||
UC-8. The user want to make an object from a GESAsset
|
||||
|
||||
|
||||
5. API Draft
|
||||
~~~~~~~~~~~~
|
||||
|
||||
A. GESExtractable API
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
GESExtractable is responsible for telling what GESAsset subclass need to
|
||||
be instantiated.
|
||||
|
||||
/**
|
||||
* ges_extractable_object_get_asset:
|
||||
* @object: Target object
|
||||
* Method to get asset which was used to instaniate specified object
|
||||
* Returns: origin asset
|
||||
*/
|
||||
GESAsset *
|
||||
ges_extractable_get_asset(GESExtractable *extractable);
|
||||
|
||||
/**
|
||||
* ges_extractable_object_set_asset:
|
||||
* @object: Target object
|
||||
* @asset: (transfer none): The #GESAsset to set
|
||||
*
|
||||
* Method to set asset which was used to instaniate specified object
|
||||
*/
|
||||
void
|
||||
ges_extractable_set_asset (GESExtractable * self, GESAsset * asset)
|
||||
|
||||
/**
|
||||
* ges_extractable_get_asset_type:
|
||||
* @class: Get the #GType of the GESAsset that should be used to extract
|
||||
* the object that implements that #GESExtractable interface
|
||||
*
|
||||
* Lets user know the type of GESAsset that should be used to extract the
|
||||
* object that implement that interface.
|
||||
*/
|
||||
GType
|
||||
ges_extractable_get_asset_type (GESExtractableClass *class)
|
||||
|
||||
/**
|
||||
* ges_extractable_get_id:
|
||||
* @self: The #GESExtractable
|
||||
*
|
||||
* Returns: The #id of the associated #GESAsset
|
||||
*/
|
||||
const gchar *
|
||||
ges_extractable_get_id (GESExtractable * self)
|
||||
|
||||
/**
|
||||
* ges_extractable_type_get_parameters_for_id:
|
||||
* @type: The #GType implementing #GESExtractable
|
||||
* @id: The ID of the Extractable
|
||||
* @n_params: (out): Return location for the returned array
|
||||
*
|
||||
* Returns: (transfer full) (array length=n_params): an array of #GParameter
|
||||
* needed to extract the #GESExtractable from a #GESAsset of @id
|
||||
*/
|
||||
GParameter *
|
||||
ges_extractable_type_get_parameters_from_id (GType type, const gchar * id,
|
||||
guint * n_params)
|
||||
|
||||
/**
|
||||
* ges_extractable_type_get_asset_type:
|
||||
* @type: The #GType implementing #GESExtractable
|
||||
*
|
||||
* Get the #GType, subclass of #GES_TYPE_ASSET to instanciate
|
||||
* to be able to extract a @type
|
||||
*
|
||||
* Returns: the #GType to use to create a asset to extract @type
|
||||
*/
|
||||
GType
|
||||
ges_extractable_type_get_asset_type (GType type)
|
||||
|
||||
/**
|
||||
* ges_extractable_type_check_id:
|
||||
* @type: The #GType implementing #GESExtractable
|
||||
* @id: The ID to check
|
||||
*
|
||||
* Check if @id is valid for @type
|
||||
*
|
||||
* Returns: Return %TRUE if @id is valid, %FALSE otherwise
|
||||
*/
|
||||
gchar *
|
||||
ges_extractable_type_check_id (GType type, const gchar * id)
|
||||
|
||||
|
||||
A. Asset And subclasses API draft
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
a) GESAsset
|
||||
| ~~~~~~~~~~~
|
||||
|
|
||||
| Will implement GESMetdata
|
||||
|
|
||||
| Virtual method type:
|
||||
| -------------------
|
||||
|
|
||||
| /**
|
||||
| * GESAssetCreatedCallback:
|
||||
| * @asset: the #newly created #GESAsset or %NULL if something went wrong
|
||||
| * @error: The #GError filled if previsouly provided in the constructor or %NULL
|
||||
| * @user_data: The user data pointer
|
||||
| *
|
||||
| * A function that will be called when a #GESAsset is ready to be used.
|
||||
| */
|
||||
| typedef void (*GESAssetCreatedCallback)(GESAsset *asset, GError *error, gpointer user_data);
|
||||
|
|
||||
|
|
||||
| Methods prototypes:
|
||||
| -------------------
|
||||
| /**
|
||||
| * ges_asset_request:
|
||||
| * @extractable_type: The #GType of the object that can be extracted from the new asset.
|
||||
| * The class must implement the #GESExtractable interface.
|
||||
| * @callback: a #GAsyncReadyCallback to call when the initialization is finished
|
||||
| * @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
|
||||
| * GESTrackParseLaunchEffect, it will be the pipeline description, for a GESTimelineFileSource 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.
|
||||
| *
|
||||
| * Creates a new #GESAsset asyncronously, @callback will be called when the materail is loaded
|
||||
| *
|
||||
| * Returns: %TRUE if the asset could be loaded to load %FALSE otherwize
|
||||
| */
|
||||
| gboolean
|
||||
| ges_asset_request (GType extractable_type, GESAssetCreatedCallback callback,
|
||||
| gpointer user_data, const gchar *id);
|
||||
|
|
||||
|->b) GESAssetTimelineObject
|
||||
| | ~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
| | /**
|
||||
| | * ges_asset_timeline_object_get_track_types:
|
||||
| | * @asset: a #GESAssetTimelineObject
|
||||
| | *
|
||||
| | * Method that returns track types that are supported by given asset
|
||||
| | *
|
||||
| | * Returns: Track types that are supported by asset
|
||||
| | */
|
||||
| | GESTrackType
|
||||
| | ges_asset_timeline_object_get_track_types (GESAssetTimelineObject *asset);
|
||||
| |
|
||||
| |
|
||||
| |-> c) GESAssetFileSource
|
||||
| ~~~~~~~~~~~~~~~~~~~~~
|
||||
| /**
|
||||
| * ges_asset_file_source_get_stream_info:
|
||||
| * @asset: a #GESAsset of extractable_type GES_TIMELINE_FILE_SOURCE
|
||||
| * Method that returns discoverer data of specified asset so user could work with
|
||||
| * it directly
|
||||
| * Returns: discover info of asset
|
||||
| */
|
||||
| GstDiscovererStreamInfo *
|
||||
| ges_asset_file_source_get_stream_info (GESAssetFileSource *asset);
|
||||
|
|
||||
|
|
||||
|-> d) GESProjectAsset asset API
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A project is a GESAsset that has GES_TYPE_TIMELINE or subclasses as extractable_type
|
||||
|
||||
FIXME: This special case that should be thought thoroughly.
|
||||
|
||||
/**
|
||||
* ges_asset_project_list_assets:
|
||||
* @asset: Project asset
|
||||
* @type: Type of asset to list
|
||||
* Method for listing assets of specified type that are available in
|
||||
* particular project.
|
||||
*
|
||||
* Returns: list of available assets of given type in project
|
||||
*/
|
||||
ges_asset_project_list_assets (GESAsset *project,
|
||||
GType type)
|
||||
|
||||
E. Methods that should be added to other classes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
/**
|
||||
* ges_timeline_layer_add_asset:
|
||||
*
|
||||
* Creates TimelineObject from asset, adds it to layer and
|
||||
* returns reference to it.
|
||||
*
|
||||
* Returns: Created #GESTimelineObject
|
||||
*/
|
||||
GESTimelineObject * ges_timeline_layer_add_asset (GESTimelineLayer *layer,
|
||||
GESAssetTimelineObject *asset,
|
||||
GstClockTime start,
|
||||
GstClockTime inpoint,
|
||||
GstClockTime duration,
|
||||
|
||||
/**
|
||||
* ges_timeline_remove_extracted_from_asset:
|
||||
* @timeline: A #GESTimeline from which to remove objects
|
||||
* @asset: The #GESAssetTimelineObject to remove from @timeline
|
||||
*
|
||||
* Removes all asset in @timeline that have been extracted from @asset
|
||||
*
|
||||
* Returns: %TRUE if everything could be done properly %FALSE otherwize
|
||||
*/
|
||||
gboolean ges_timeline_layer_add_asset (GESTimeline *timeline, GESAsset *asset);
|
||||
|
||||
/**
|
||||
* ges_timeline_object_add_asset:
|
||||
* @object: Target #GESTimelineObject
|
||||
* @asset: a #GESAsset that must have a GES_TYPE_TRACK_OPERATION as extractable_type
|
||||
* @priority: The priority of the new #GESTrackObject
|
||||
*
|
||||
* Adds an operation (GESTrackObject(s)) to a GESTimelineObject
|
||||
*
|
||||
* Returns: (transfer full):The newly created #GESTrackObject.
|
||||
*/
|
||||
GESTrackObject
|
||||
ges_timeline_object_add_asset (GESTimelineObject *object,
|
||||
GESAsset *asset,
|
||||
guint32 priority);
|
||||
Loading…
Reference in a new issue