From dff4e20cb5ce3f9e6fcf73222ed08c1a7d053a22 Mon Sep 17 00:00:00 2001 From: Edward Hervey Date: Thu, 10 Sep 2009 18:40:51 +0200 Subject: [PATCH] More documentation. Coverage now at 25% --- docs/libs/ges-docs.sgml | 15 +++++++++++++++ docs/libs/ges-sections.txt | 4 ++-- ges/ges-custom-timeline-source.c | 10 ++++++++++ ges/ges-simple-timeline-layer.c | 8 ++++++++ ges/ges-timeline-layer.c | 13 +++++++------ ges/ges-timeline-object.c | 17 +++++++++-------- ges/ges-timeline-pipeline.c | 13 +++++++++---- ges/ges-timeline-source.c | 5 +++++ ges/ges-timeline-transition.c | 5 +++++ ges/ges-timeline.c | 22 +++++++++++++--------- ges/ges-track-object.c | 8 ++++++++ ges/ges-track-source.c | 5 +++++ ges/ges-track.c | 19 +++++++++++-------- ges/ges-track.h | 9 +++++++-- ges/ges.c | 12 ++++++++++++ 15 files changed, 126 insertions(+), 39 deletions(-) diff --git a/docs/libs/ges-docs.sgml b/docs/libs/ges-docs.sgml index 3f740beefc..e2c91f6ec0 100644 --- a/docs/libs/ges-docs.sgml +++ b/docs/libs/ges-docs.sgml @@ -13,7 +13,22 @@ + + GStreamer Editing Services Overview + + The "GStreamer Editing Services" is a library to simplify the creation +of multimedia editing applications. Based on the GStreamer multimedia framework +and the GNonLin set of plugins, its goals are to suit all types of editing-related +applications. + + + + The GStreamer Editing Services are cross-platform and work on most UNIX-like +platform as well as Windows. It is released under the GNU Library General Public License +(GNU LGPL). + + Base Classes diff --git a/docs/libs/ges-sections.txt b/docs/libs/ges-sections.txt index ea0555884b..96064417d1 100644 --- a/docs/libs/ges-sections.txt +++ b/docs/libs/ges-sections.txt @@ -10,8 +10,6 @@ ges_init GESTrack GESTrack GESTrackClass -FillTrackObjectFunc -FillTrackObjectUserFunc GESTrackType ges_track_add_object ges_track_audio_raw_new @@ -37,6 +35,8 @@ GES_TYPE_TRACK_TYPE GESTrackObject GESTrackObject GESTrackObjectClass +FillTrackObjectFunc +FillTrackObjectUserFunc ges_track_object_new ges_track_object_set_duration_internal ges_track_object_set_inpoint_internal diff --git a/ges/ges-custom-timeline-source.c b/ges/ges-custom-timeline-source.c index c9102d71c9..772fa04c34 100644 --- a/ges/ges-custom-timeline-source.c +++ b/ges/ges-custom-timeline-source.c @@ -17,6 +17,16 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-custom-timeline-source + * @short_description: Convenience #GESTimelineSource + * + * #GESCustomTimelineSource allows creating #GESTimelineSource(s) without the + * need to subclass. + * + * Its usage should be limited to testing and prototyping purposes. + */ + #include "ges-internal.h" #include "ges-custom-timeline-source.h" #include "ges-timeline-source.h" diff --git a/ges/ges-simple-timeline-layer.c b/ges/ges-simple-timeline-layer.c index bca635bc56..cd85a2cdf9 100644 --- a/ges/ges-simple-timeline-layer.c +++ b/ges/ges-simple-timeline-layer.c @@ -17,6 +17,14 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-simple-timeline-layer + * @short_description: High-level #GESTimelineLayer + * + * #GESSimpleTimelineLayer allows using #GESTimelineObject(s) with a list-like + * API. + */ + #include "ges-internal.h" #include "ges-simple-timeline-layer.h" diff --git a/ges/ges-timeline-layer.c b/ges/ges-timeline-layer.c index 8cdf5172a9..ba6712a11c 100644 --- a/ges/ges-timeline-layer.c +++ b/ges/ges-timeline-layer.c @@ -17,17 +17,18 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-timeline-layer + * @short_description: Non-overlaping sequence of #GESTimelineObject + * + * Responsible for the ordering of the various contained TimelineObject(s) + */ + #include "ges-internal.h" #include "gesmarshal.h" #include "ges-timeline-layer.h" #include "ges.h" -/** - * GESTimelineLayer - * - * Responsible for the ordering of the various contained TimelineObject(s) - */ - G_DEFINE_TYPE (GESTimelineLayer, ges_timeline_layer, G_TYPE_OBJECT); enum diff --git a/ges/ges-timeline-object.c b/ges/ges-timeline-object.c index c7071a9b27..0c77c2daaf 100644 --- a/ges/ges-timeline-object.c +++ b/ges/ges-timeline-object.c @@ -17,18 +17,19 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-timeline-object + * @short_description: Base Class for objects in a #GESTimelineLayer + * + * Responsible for creating the #GESTrackObject(s) for given #GESTimelineTrack(s) + * + * Keeps a reference to the #GESTrackObject(s) it created and sets/updates their properties. + */ + #include "ges-timeline-object.h" #include "ges.h" #include "ges-internal.h" -/** - * GESTimelineObject - * - * Responsible for creating the TrackObject(s) for given TimelineTrack(s) - * - * Keeps a reference to the TrackObject(s) it created and sets/updates their properties. - */ - G_DEFINE_TYPE (GESTimelineObject, ges_timeline_object, G_TYPE_OBJECT); diff --git a/ges/ges-timeline-pipeline.c b/ges/ges-timeline-pipeline.c index ec7f02a919..5c9fe85e54 100644 --- a/ges/ges-timeline-pipeline.c +++ b/ges/ges-timeline-pipeline.c @@ -17,13 +17,18 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-timeline-pipeline + * @short_description: Convenience #GstPipeline for editing. + * + * #GESTimelinePipeline allows developers to view and render #GESTimeline + * in a simple fashion. + * Its usage is inspired by the 'playbin' element from gst-plugins-base. + */ + #include "ges-internal.h" #include "ges-timeline-pipeline.h" -/* TimelinePipeline - * - */ - /* Structure corresponding to a timeline - sink link */ /* TODO : Don't forget we want to render also :) */ diff --git a/ges/ges-timeline-source.c b/ges/ges-timeline-source.c index 746d5d4b86..5fe1ab7b5c 100644 --- a/ges/ges-timeline-source.c +++ b/ges/ges-timeline-source.c @@ -17,6 +17,11 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-timeline-source + * @short_description: Base Class for sources of a #GESTimelineLayer + */ + #include "ges-internal.h" #include "ges-timeline-object.h" #include "ges-timeline-source.h" diff --git a/ges/ges-timeline-transition.c b/ges/ges-timeline-transition.c index a9277047fb..c4bf14350b 100644 --- a/ges/ges-timeline-transition.c +++ b/ges/ges-timeline-transition.c @@ -17,6 +17,11 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ges-timeline-transition + * @short_description: Base Class for transitions in a #GESTimelineLayer + */ + #include "ges-internal.h" #include "ges-timeline-transition.h" diff --git a/ges/ges-timeline.c b/ges/ges-timeline.c index 0892883350..ba2e6a2a89 100644 --- a/ges/ges-timeline.c +++ b/ges/ges-timeline.c @@ -17,6 +17,19 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-timeline + * @short_description: Multimedia timeline + * + * #GESTimeline is the central object for any multimedia timeline. + * + * Contains a list of #GESTimelineLayer which users should use to arrange the + * various timeline objects through time. + * + * The output type is determined by the #GESTimelineTrack that are set on + * the #GESTimeline. + */ + #include "gesmarshal.h" #include "ges-internal.h" #include "ges-timeline.h" @@ -24,15 +37,6 @@ #include "ges-timeline-layer.h" #include "ges.h" -/** - * GESTimelinePipeline - * - * Top-level container for pipelines - * - * Contains a list of TimelineLayer which users should use to arrange the - * various timeline objects. - * - */ G_DEFINE_TYPE (GESTimeline, ges_timeline, GST_TYPE_BIN); diff --git a/ges/ges-track-object.c b/ges/ges-track-object.c index 01d4b0a6e3..5dc31c82b4 100644 --- a/ges/ges-track-object.c +++ b/ges/ges-track-object.c @@ -17,6 +17,14 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-track-object + * @short_description: Base Class for objects contained in a #GESTrack + * + * #GESTrackObject is the Base Class for any object that can be contained in a + * #GESTrack. + */ + #include "ges-internal.h" #include "ges-track-object.h" #include "ges-timeline-object.h" diff --git a/ges/ges-track-source.c b/ges/ges-track-source.c index 1be5cc9f25..855e5db52d 100644 --- a/ges/ges-track-source.c +++ b/ges/ges-track-source.c @@ -17,6 +17,11 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-track-source + * @short_description: Base Class for single-media sources + */ + #include "ges-internal.h" #include "ges-track-object.h" #include "ges-track-source.h" diff --git a/ges/ges-track.c b/ges/ges-track.c index f6f9dabd64..934d6c2077 100644 --- a/ges/ges-track.c +++ b/ges/ges-track.c @@ -17,18 +17,21 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:ges-track + * @short_description: Composition of objects + * + * Corresponds to one output format (i.e. audio OR video). + * + * Contains the compatible TrackObject(s). + * + * Wraps GNonLin's 'gnlcomposition' element. + */ + #include "ges-internal.h" #include "ges-track.h" #include "ges-track-object.h" -/** - * GESTrack - * - * Corresponds to one output format (i.e. audio OR video) - * - * Contains the compatible TrackObject(s) - */ - G_DEFINE_TYPE (GESTrack, ges_track, GST_TYPE_BIN); enum diff --git a/ges/ges-track.h b/ges/ges-track.h index ccc4682c55..115717f3ed 100644 --- a/ges/ges-track.h +++ b/ges/ges-track.h @@ -54,7 +54,9 @@ GType ges_track_type_get_type (void); * @GES_TRACK_TYPE_TEXT: A text (subtitle) track * @GES_TRACK_TYPE_CUSTOM: A custom-content track * - * Types of content handled by a track. + * Types of content handled by a track. If the content is not one of + * @GEST_TRACK_TYPE_AUDIO, @GES_TRACK_TYPE_VIDEO or @GES_TRACK_TYPE_TEXT, + * the user of the #GESTrack must set the type to @GES_TRACK_TYPE_CUSTOM. */ typedef enum { @@ -67,9 +69,12 @@ typedef enum { struct _GESTrack { GstBin parent; - GESTimeline * timeline; + /*< public >*/ /* READ-ONLY */ GESTrackType type; + /*< private >*/ + GESTimeline * timeline; + GstCaps * caps; GstElement * composition; /* The composition associated with this track */ diff --git a/ges/ges.c b/ges/ges.c index 7ab00c530f..524055be36 100644 --- a/ges/ges.c +++ b/ges/ges.c @@ -22,6 +22,18 @@ GST_DEBUG_CATEGORY (ges_debug); +/** + * SECTION:ges + * @short_description: Initialization. + */ + +/** + * ges_init: + * + * Initialize the GStreamer Editing Service. Call this before any usage of + * GES. + */ + void ges_init (void) {