mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-10-02 08:42:32 +00:00
Code Issues 1 Projects Releases Wiki Activity

Formatter: Extend and fixup documentation

Browse source
This commit is contained in:
Edward Hervey 2010-11-26 18:39:26 +01:00
parent 2ff3d8ce12
commit 3a9e4cdd74
4 changed files with 167 additions and 102 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
docs/libs/ges-sections.txt
View file

@ -204,6 +204,7 @@ GESTimeline
GESTimelineClass GESTimelineClass
ges_timeline_new ges_timeline_new
ges_timeline_new_audio_video ges_timeline_new_audio_video
ges_timeline_new_from_uri
ges_timeline_add_layer ges_timeline_add_layer
ges_timeline_remove_layer ges_timeline_remove_layer
ges_timeline_add_track ges_timeline_add_track
@ -443,7 +444,6 @@ GES_TIMELINE_TITLE_SOURCE_GET_CLASS
GESTimelineTextOverlay GESTimelineTextOverlay
GESTimelineTextOverlayClass GESTimelineTextOverlayClass
ges_timeline_text_overlay_new ges_timeline_text_overlay_new
ges_timeline_new_from_uri
<SUBSECTION Standard> <SUBSECTION Standard>
ges_tl_text_overlay_get_type ges_tl_text_overlay_get_type
GES_IS_TIMELINE_TEXT_OVERLAY GES_IS_TIMELINE_TEXT_OVERLAY
@ -536,17 +536,14 @@ GES_TYPE_TRACK_TEXT_OVERLAY
<TITLE>GESFormatter</TITLE> <TITLE>GESFormatter</TITLE>
GESFormatter GESFormatter
GESFormatterClass GESFormatterClass
GESFormatterLoadFromURIMethod
GESFormatterSaveToURIMethod
ges_default_formatter_new ges_default_formatter_new
ges_formatter_load_from_uri ges_formatter_load_from_uri
ges_formatter_save_to_uri ges_formatter_save_to_uri
ges_formatter_new_for_uri ges_formatter_new_for_uri
ges_formatter_can_load_uri ges_formatter_can_load_uri
ges_formatter_can_save_uri ges_formatter_can_save_uri
ges_formatter_load
ges_formatter_save
ges_formatter_set_data
ges_formatter_clear_data
ges_formatter_get_data
<SUBSECTION Standard> <SUBSECTION Standard>
ges_formatter_get_type ges_formatter_get_type
GES_FORMATTER GES_FORMATTER
@ -555,11 +552,21 @@ GES_FORMATTER_GET_CLASS
GES_IS_FORMATTER GES_IS_FORMATTER
GES_IS_FORMATTER_CLASS GES_IS_FORMATTER_CLASS
GES_TYPE_FORMATTER GES_TYPE_FORMATTER
<SUBSECTION Private>
ges_formatter_load
ges_formatter_save
ges_formatter_set_data
ges_formatter_clear_data
ges_formatter_get_data
GESFormatterCanLoadURIMethod
GESFormatterCanSaveURIMethod
GESFormatterLoadMethod
GESFormatterSaveMethod
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>ges-keyfile-formatter</FILE> <FILE>ges-keyfile-formatter</FILE>
<TITLE>GESFormatter</TITLE> <TITLE>GESKeyFileFormatter</TITLE>
GESKeyfileFormatter GESKeyfileFormatter
GESKeyfileFormatterClass GESKeyfileFormatterClass
ges_keyfile_formatter_new ges_keyfile_formatter_new

135
ges/ges-formatter.c
View file

@ -20,27 +20,41 @@
/** /**
* SECTION:ges-formatter * SECTION:ges-formatter
* @short_description: Base Class for loading and saving #GESTimeline data. * @short_description: Timeline saving and loading.
* *
* Responsible for loading and/or saving the contents of a #GESTimeline to/from * The #GESFormatter is the object responsible for loading and/or saving the contents
* various formats. * of a #GESTimeline to/from various formats.
*
* In order to save a #GESTimeline, you can either let GES pick a default formatter by
* using ges_timeline_save_to_uri(), or pick your own formatter and use
* ges_formatter_save_to_uri().
*
* To load a #GESTimeline, you might want to be able to track the progress of the loading,
* in which case you should create an empty #GESTimeline, connect to the relevant signals
* and call ges_formatter_load_from_uri().
*
* If you do not care about tracking the loading progress, you can use the convenience
* ges_timeline_new_from_uri() method.
*
* Support for saving or loading new formats can be added by creating a subclass of
* #GESFormatter and implement the various vmethods of #GESFormatterClass.
**/ **/
#include <gst/gst.h> #include <gst/gst.h>
#include <stdlib.h> #include <stdlib.h>
#include "ges-formatter.h" #include "ges-formatter.h"
#include "ges.h" #include "ges-keyfile-formatter.h"
#include "ges-internal.h" #include "ges-internal.h"
G_DEFINE_TYPE (GESFormatter, ges_formatter, G_TYPE_OBJECT); G_DEFINE_TYPE (GESFormatter, ges_formatter, G_TYPE_OBJECT);
static void ges_formatter_dispose (GObject * object); static void ges_formatter_dispose (GObject * object);
static void ges_formatter_finalize (GObject * object);
static gboolean load_from_uri (GESFormatter * formatter, GESTimeline * static gboolean load_from_uri (GESFormatter * formatter, GESTimeline *
timeline, gchar * uri); timeline, gchar * uri);
static gboolean save_to_uri (GESFormatter * formatter, GESTimeline * static gboolean save_to_uri (GESFormatter * formatter, GESTimeline *
timeline, gchar * uri); timeline, gchar * uri);
static gboolean default_can_load_uri (gchar * uri);
static gboolean default_can_save_uri (gchar * uri);
static void static void
ges_formatter_class_init (GESFormatterClass * klass) ges_formatter_class_init (GESFormatterClass * klass)
@ -48,8 +62,9 @@ ges_formatter_class_init (GESFormatterClass * klass)
GObjectClass *object_class = G_OBJECT_CLASS (klass); GObjectClass *object_class = G_OBJECT_CLASS (klass);
object_class->dispose = ges_formatter_dispose; object_class->dispose = ges_formatter_dispose;
object_class->finalize = ges_formatter_finalize;
klass->can_load_uri = default_can_load_uri;
klass->can_save_uri = default_can_save_uri;
klass->load_from_uri = load_from_uri; klass->load_from_uri = load_from_uri;
klass->save_to_uri = save_to_uri; klass->save_to_uri = save_to_uri;
} }
@ -70,18 +85,13 @@ ges_formatter_dispose (GObject * object)
} }
} }
static void
ges_formatter_finalize (GObject * formatter)
{
}
/** /**
* ges_formatter_new_for_uri: * ges_formatter_new_for_uri:
* @uri: a #gchar * pointing to the uri * @uri: a #gchar * pointing to the uri
* *
* Creates a #GESFormatter that can handle the given URI. * Creates a #GESFormatter that can handle the given URI.
* *
* Returns: A GESFormatter or subclass that can load the given uri, or NULL if * Returns: A GESFormatter that can load the given uri, or NULL if
* the uri is not supported. * the uri is not supported.
*/ */
@ -94,7 +104,7 @@ ges_formatter_new_for_uri (gchar * uri)
} }
/** /**
* ges_formatter_default_new: * ges_default_formatter_new:
* *
* Creates a new instance of the default GESFormatter type on this system * Creates a new instance of the default GESFormatter type on this system
* (currently #GESKeyFileFormatter). * (currently #GESKeyFileFormatter).
@ -108,15 +118,29 @@ ges_default_formatter_new (void)
return GES_FORMATTER (ges_keyfile_formatter_new ()); return GES_FORMATTER (ges_keyfile_formatter_new ());
} }
static gboolean
default_can_load_uri (gchar * uri)
{
GST_ERROR ("No 'can_load_uri' vmethod implementation");
return FALSE;
}
static gboolean
default_can_save_uri (gchar * uri)
{
GST_ERROR ("No 'can_save_uri' vmethod implementation");
return FALSE;
}
/** /**
* ges_formatter_can_load_uri: * ges_formatter_can_load_uri:
* @uri: a #gchar * pointing to the URI * @uri: a #gchar * pointing to the URI
* *
* Returns true if there is a #GESFormatterClass derivative registered with * Checks if there is a #GESFormatter available which can load a #GESTimeline
* the system which can load data from the given URI. * from the given URI.
* *
* Returns: TRUE if the given uri is supported or FALSE if the uri is * Returns: TRUE if there is a #GESFormatter that can support the given uri
* not supported. * or FALSE if not.
*/ */
gboolean gboolean
@ -142,14 +166,13 @@ ges_formatter_can_load_uri (gchar * uri)
} }
/** /**
* ges_formatter_can_load_uri: * ges_formatter_can_save_uri:
* @uri: a #gchar * pointing to a URI * @uri: a #gchar * pointing to a URI
* *
* Returns TRUE if thereis a #GESFormatterClass derivative registered with the * Returns TRUE if there is a #GESFormatter available which can save a
* system which can save data to the given URI. * #GESTimeline to the given URI.
* *
* Returns: TRUE if the given uri is supported or FALSE if the given URI is * Returns: TRUE if the given @uri is supported, else FALSE.
* not suported.
*/ */
gboolean gboolean
@ -172,19 +195,18 @@ ges_formatter_can_save_uri (gchar * uri)
* handle the URI.*/ * handle the URI.*/
return TRUE; return TRUE;
return FALSE;
} }
/** /**
* ges_formatter_set_data: * ges_formatter_set_data:
* @formatter: a pointer to a #GESFormatter instance or subclass * @formatter: a #GESFormatter
* @data: a pointer to the data to be set on the formatter * @data: the data to be set on the formatter
* @length: a #gsize indicating the length of the data in bytes * @length: the length of the data in bytes
* *
* Set the data that this formatter will use for loading. The formatter will * Set the data that this formatter will use for loading. The formatter will
* takes ownership of the data and will free the data if * takes ownership of the data and will free the data if
* ges_formatter_set_data is called again or when the formatter itself is * @ges_formatter_set_data is called again or when the formatter itself is
* disposed. You should calle ges_formatter_clear_data () if you do not wish * disposed. You should call @ges_formatter_clear_data () if you do not wish
* this to happen. * this to happen.
*/ */
@ -199,9 +221,8 @@ ges_formatter_set_data (GESFormatter * formatter, void *data, gsize length)
/** /**
* ges_formatter_get_data: * ges_formatter_get_data:
* @formatter: a pointer to a #GESFormatter * @formatter: a #GESFormatter
* @length: a pointer to a location into which to store the size of the * @length: location into which to store the size of the data in bytes.
* data in bytes.
* *
* Returns: a pointer to the data. * Returns: a pointer to the data.
*/ */
@ -216,7 +237,7 @@ ges_formatter_get_data (GESFormatter * formatter, gsize * length)
/** /**
* ges_formatter_clear_data: * ges_formatter_clear_data:
* @formatter: a pointer to a #GESFormatter * @formatter: a #GESFormatter
* *
* clears the data from a #GESFormatter without freeing it. You should call * clears the data from a #GESFormatter without freeing it. You should call
* this before disposing or setting data on a #GESFormatter if the current data * this before disposing or setting data on a #GESFormatter if the current data
@ -232,12 +253,12 @@ ges_formatter_clear_data (GESFormatter * formatter)
/** /**
* ges_formatter_load: * ges_formatter_load:
* @formatter: a pointer to a #GESFormatter instance or subclass. * @formatter: a #GESFormatter
* @timeline: a pointer to a #GESTimeline * @timeline: a #GESTimeline
* *
* Loads data from formatter to into timeline. You should first call * Loads data from formatter to into timeline. You should first call
* ges_formatter_set_data () with the location and size of a block of data * ges_formatter_set_data() with the location and size of a block of data
* from which to read. This method is only implemented in subclasses. * from which to read.
* *
* Returns: TRUE if the data was successfully loaded into timeline * Returns: TRUE if the data was successfully loaded into timeline
* or FALSE if an error occured during loading. * or FALSE if an error occured during loading.
@ -258,12 +279,11 @@ ges_formatter_load (GESFormatter * formatter, GESTimeline * timeline)
/** /**
* ges_formatter_save: * ges_formatter_save:
* @formatter: a pointer to a #GESFormatter instance or subclass. * @formatter: a #GESFormatter
* @timeline: a pointer to a #GESTimeline * @timeline: a #GESTimeline
* *
* Save data from timeline into a block of data. You can retrieve the location * Save data from timeline into a block of data. You can retrieve the location
* and size of this data with ges_formatter_get_data(). This method is only * and size of this data with ges_formatter_get_data().
* implemented in subclasses.
* *
* Returns: TRUE if the timeline data was successfully saved for FALSE if * Returns: TRUE if the timeline data was successfully saved for FALSE if
* an error occured during saving. * an error occured during saving.
@ -289,20 +309,14 @@ ges_formatter_save (GESFormatter * formatter, GESTimeline * timeline)
/** /**
* ges_formatter_load_from_uri: * ges_formatter_load_from_uri:
* @formatter: a pointer to a #GESFormatter instance or subclass * @formatter: a #GESFormatter
* @timeline: a pointer to a #GESTimeline * @timeline: a #GESTimeline
* @uri: a #gchar * pointing to a URI * @uri: a #gchar * pointing to a URI
* *
* Load data from the given URI into timeline. The default implementation * Load data from the given URI into timeline.
* loads the entire contents of the uri with g_file_get_contents, then calls
* ges_formatter_load(). It works only on valid URIs pointing to local files.
* *
* Subclasses should override the class method load_from_uri if they want to * Returns: TRUE if the timeline data was successfully loaded from the URI,
* handle other types of URIs. They should also override the class method * else FALSE.
* can_load_uri() to indicate that they can handle other types of URI.
*
* Returns: TRUE if the timeline data was successfully loaded from the URI or
* FALSE if an error occured during loading.
*/ */
gboolean gboolean
@ -352,21 +366,14 @@ load_from_uri (GESFormatter * formatter, GESTimeline * timeline, gchar * uri)
/** /**
* ges_formatter_save_to_uri: * ges_formatter_save_to_uri:
* @formatter: a pointer to a #GESFormatter instance or subclass * @formatter: a #GESFormatter
* @timeline: a pointer to a #GESTimeline * @timeline: a #GESTimeline
* @uri: a #gchar * pointing to a URI * @uri: a #gchar * pointing to a URI
* *
* Save data from timeline to the given URI. The default implementation first * Save data from timeline to the given URI.
* calls ges_formatter_save () and then writes the entire contents of the data
* field to a local file using g_file_set_contents. It works only for local
* files.
* *
* Subclasses should override the class method save_to_uri if they want to * Returns: TRUE if the timeline data was successfully saved to the URI
* handle other types of URIs. They should also override the class method * else FALSE.
* can_save_uri to return true for custom URIs.
*
* Returns: TRUE if the timeline data was successfully saved to the URI or
* FALSE if an error occured during saving.
*/ */
gboolean gboolean

105
ges/ges-formatter.h
View file

@ -53,54 +53,109 @@ struct _GESFormatter {
/*< private >*/ /*< private >*/
gchar *data; gchar *data;
gsize length; gsize length;
gpointer _ges_reserved[GST_PADDING];
}; };
typedef gboolean (*GESFormatterCanLoadURIMethod) (gchar * uri);
typedef gboolean (*GESFormatterCanSaveURIMethod) (gchar * uri);
/**
* GESFormatterLoadFromURIMethod:
* @formatter: a #GESFormatter
* @timeline: a #GESTimeline
* @uri: the URI to load from
*
* Virtual method for loading a timeline from a given URI.
*
* Every #GESFormatter subclass needs to implement this method.
*
* Returns: TRUE if the @timeline was properly loaded from the given @uri,
* else FALSE.
**/
typedef gboolean (*GESFormatterLoadFromURIMethod) (GESFormatter *formatter,
GESTimeline *timeline,
gchar * uri);
/**
* GESFormatterSaveToURIMethod:
* @formatter: a #GESFormatter
* @timeline: a #GESTimeline
* @uri: the URI to save to
*
* Virtual method for saving a timeline to a uri.
*
* Every #GESFormatter subclass needs to implement this method.
*
* Returns: TRUE if the @timeline was properly stored to the given @uri,
* else FALSE.
*/
typedef gboolean (*GESFormatterSaveToURIMethod) (GESFormatter *formatter,
GESTimeline *timeline,
gchar * uri);
typedef gboolean (*GESFormatterSaveMethod) (GESFormatter * formatter,
GESTimeline * timeline);
typedef gboolean (*GESFormatterLoadMethod) (GESFormatter * formatter,
GESTimeline * timeline);
/** /**
* GESFormatterClass: * GESFormatterClass:
* @parent_class: parent class * @parent_class: the parent class structure
* @can_load_uri: class method which returns true if a #GESFormatterClass can read * @can_load_uri: Whether the URI can be loaded
* from a given URI. * @can_save_uri: Whether the URI can be saved
* @can_save_uri: class method which rturns true of a #GEFormatterClass can
* write to a given URI.
* @load_from_uri: class method to deserialize data from a URI * @load_from_uri: class method to deserialize data from a URI
* @save_to_uri: class method to serialize data to a URI * @save_to_uri: class method to serialize data to a URI
* @save: method to save timeline data * @save: Save the contents of the timeline to the internal data pointer.
* @load: method to load timeline data * @load: Load the timeline with the contents of the internal data pointer.
* *
* GES Formatter class. Override the vmethods to implement the formatter functionnality.
*/ */
struct _GESFormatterClass { struct _GESFormatterClass {
GObjectClass parent_class; GObjectClass parent_class;
gboolean (*can_load_uri) (gchar * uri); /* FIXME : formatter name */
gboolean (*can_save_uri) (gchar * uri); /* FIXME : formatter description */
gboolean (*load_from_uri) (GESFormatter *, GESTimeline *, gchar * uri); /* FIXME : format name/mime-type */
gboolean (*save_to_uri) (GESFormatter *, GESTimeline *, gchar * uri);
gboolean (*save) (GESFormatter * formatter, GESTimeline * timeline); GESFormatterCanLoadURIMethod can_load_uri;
gboolean (*load) (GESFormatter * formatter, GESTimeline * timeline); GESFormatterCanSaveURIMethod can_save_uri;
GESFormatterLoadFromURIMethod load_from_uri;
GESFormatterSaveToURIMethod save_to_uri;
GESFormatterSaveMethod save;
GESFormatterLoadMethod load;
gpointer _ges_reserved[GST_PADDING];
}; };
GType ges_formatter_get_type (void); GType ges_formatter_get_type (void);
/* Main Formatter methods */
GESFormatter *ges_formatter_new_for_uri (gchar *uri); GESFormatter *ges_formatter_new_for_uri (gchar *uri);
GESFormatter *ges_default_formatter_new (void); GESFormatter *ges_default_formatter_new (void);
gboolean ges_formatter_can_load_uri (gchar * uri); gboolean ges_formatter_can_load_uri (gchar * uri);
gboolean ges_formatter_can_save_uri (gchar * uri); gboolean ges_formatter_can_save_uri (gchar * uri);
gboolean ges_formatter_load_from_uri (GESFormatter * formatter, GESTimeline gboolean ges_formatter_load_from_uri (GESFormatter * formatter,
*timeline, gchar *uri); GESTimeline *timeline,
gchar *uri);
gboolean ges_formatter_save_to_uri (GESFormatter * formatter, GESTimeline *timeline, gboolean ges_formatter_save_to_uri (GESFormatter * formatter,
gchar *uri); GESTimeline *timeline,
gchar *uri);
void ges_formatter_set_data (GESFormatter * formatter, void *data, gsize /* Non-standard methods */
length); gboolean ges_formatter_load (GESFormatter * formatter,
GESTimeline * timeline);
gboolean ges_formatter_save (GESFormatter * formatter,
GESTimeline * timeline);
void *ges_formatter_get_data (GESFormatter *formatter, gsize *length); void ges_formatter_set_data (GESFormatter * formatter,
void ges_formatter_clear_data (GESFormatter *formatter); void *data, gsize length);
void *ges_formatter_get_data (GESFormatter *formatter,
gsize *length);
void ges_formatter_clear_data (GESFormatter *formatter);
gboolean ges_formatter_load (GESFormatter * formatter, GESTimeline * timeline);
gboolean ges_formatter_save (GESFormatter * formatter, GESTimeline * timeline);
#endif /* _GES_FORMATTER */ #endif /* _GES_FORMATTER */

6
ges/ges-keyfile-formatter.c
View file

@ -20,10 +20,7 @@
/** /**
* SECTION:ges-keyfile-formatter * SECTION:ges-keyfile-formatter
* @short_description: Base Class for loading and saving #GESTimeline data. * @short_description: GKeyFile formatter
*
* Responsible for loading and/or saving the contents of a #GESTimeline to/from
* various formats.
**/ **/
#include <gst/gst.h> #include <gst/gst.h>
@ -51,7 +48,6 @@ ges_keyfile_formatter_class_init (GESKeyfileFormatterClass * klass)
object_class = G_OBJECT_CLASS (klass); object_class = G_OBJECT_CLASS (klass);
formatter_klass = GES_FORMATTER_CLASS (klass); formatter_klass = GES_FORMATTER_CLASS (klass);
object_class->dispose = ges_keyfile_formatter_dispose; object_class->dispose = ges_keyfile_formatter_dispose;
object_class->finalize = ges_keyfile_formatter_finalize; object_class->finalize = ges_keyfile_formatter_finalize;