src/framework/*: improve the doxygen documentation (work in progress). This also...

[mlt] / src / framework / mlt_service.h

diff --git a/src/framework/mlt_service.h b/src/framework/mlt_service.h
index a2d71a5d9bf793b79dc53fe0caec3c75e5a47770..96a560a99f7f34b977eebd43715fe22702e86e5a 100644 (file)
--- a/src/framework/mlt_service.h
+++ b/src/framework/mlt_service.h
@@ -1,7 +1,9 @@
-/*
- * mlt_service.h -- interface for all service classes
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_service.h
+ * \brief interface declaration for all service classes
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -24,27 +26,50 @@
 #include "mlt_properties.h"
 #include "mlt_profile.h"
 
-/** The interface definition for all services.
-*/
+/** \brief Service abstract base class
+ *
+ * \extends mlt_properties
+ * The service is the base class for all of the interesting classes and
+ * plugins for MLT. A service can have multiple inputs connections to
+ * other services called its "producers" but only a single output to another
+ * service called its "consumer." A service that has both producer and
+ * consumer connections is called a filter. Any service can have zero or more
+ * filters "attached" to it. We call any collection of services and their
+ * connections a "service network," which is similar to what DirectShow calls
+ * a filter graph or what gstreamer calls an element pipeline.
+ *
+ * \event \em service-changed
+ * \event \em property-changed
+ * \properties \em mlt_type identifies the subclass
+ * \properties \em resource is either the stream identifier or grandchild-class
+ * \properties \em in where to start playing
+ * \properties \em _filter_private Set this on a service to ensure that attached filters are handled privately.
+ * See modules/core/filter_region.c and modules/core/filter_watermark.c for examples.
+ * \properties \em disable Set this on a filter to disable it while keeping it in the object model.
+ * \properties \em _profile stores the mlt_profile for a service
+ */
 
 struct mlt_service_s
 {
-       /* We're extending properties here */
-       struct mlt_properties_s parent;
+       struct mlt_properties_s parent; /**< \private */
 
-       /* Protected virtual */
+       /** Get a frame of data (virtual function).
+        *
+        * \param mlt_producer a producer
+        * \param mlt_frame_ptr a frame pointer by reference
+        * \param int an index
+        * \return true if there was an error
+        */
        int ( *get_frame )( mlt_service self, mlt_frame_ptr frame, int index );
+
+       /** the destructor virtual function */
        mlt_destructor close;
-       void *close_object;
+       void *close_object; /**< the object supplied to the close virtual function */
 
-       /* Private data */
-       void *local;
-       void *child;
+       void *local; /**< \private instance object */
+       void *child; /**< \private the object of a subclass */
 };
 
-/** The public API.
-*/
-
 #define MLT_SERVICE_PROPERTIES( service )      ( &( service )->parent )
 
 extern int mlt_service_init( mlt_service self, void *child );
@@ -52,6 +77,7 @@ extern void mlt_service_lock( mlt_service self );
 extern void mlt_service_unlock( mlt_service self );
 extern mlt_service_type mlt_service_identify( mlt_service self );
 extern int mlt_service_connect_producer( mlt_service self, mlt_service producer, int index );
+extern mlt_service mlt_service_get_producer( mlt_service self );
 extern int mlt_service_get_frame( mlt_service self, mlt_frame_ptr frame, int index );
 extern mlt_properties mlt_service_properties( mlt_service self );
 extern mlt_service mlt_service_consumer( mlt_service self );
@@ -61,11 +87,7 @@ extern int mlt_service_detach( mlt_service self, mlt_filter filter );
 extern void mlt_service_apply_filters( mlt_service self, mlt_frame frame, int index );
 extern mlt_filter mlt_service_filter( mlt_service self, int index );
 extern mlt_profile mlt_service_profile( mlt_service self );
-
 extern void mlt_service_close( mlt_service self );
 
-/* I'm not sure about self one - leaving it out of docs for now (only used in consumer_westley) */
-extern mlt_service mlt_service_get_producer( mlt_service self );
-
 #endif