From 9209b3f69de2a115d0b134cd07597885ada337f5 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Mon, 17 Dec 2012 15:27:52 -0300 Subject: [PATCH] design: Add asset design document Co-Authored-By: Volodymyr Rudyi --- docs/design/asset.txt | 321 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 docs/design/asset.txt diff --git a/docs/design/asset.txt b/docs/design/asset.txt new file mode 100644 index 0000000000..548908b730 --- /dev/null +++ b/docs/design/asset.txt @@ -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);