elaborate some comments

CVS patchset: 3417
CVS date: 2002/12/03 21:59:46

3 files changed, 45 insertions, 10 deletions

diff --git a/include/xine.h.in b/include/xine.h.in
index 58f28d329..2e8abe96a 100644
--- a/include/xine.h.in
+++ b/include/xine.h.in
@@ -17,7 +17,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: xine.h.in,v 1.42 2002/12/01 15:18:13 mroi Exp $
+ * $Id: xine.h.in,v 1.43 2002/12/03 21:59:46 mroi Exp $
  *
  * public xine-lib (libxine) interface and documentation
  *
@@ -303,13 +303,13 @@ struct xine_post_s {
 
   /* a NULL-terminated array of audio input ports this post plugin
    * provides; you can hand these to other post plugin's outputs or
-   * pass it to the initialization of a stream
+   * pass them to the initialization of streams
    */
   xine_audio_port_t **audio_input;
   
   /* a NULL-terminated array of video input ports this post plugin
    * provides; you can hand these to other post plugin's outputs or
-   * pass it to the initialization of a stream
+   * pass them to the initialization of streams
    */
   xine_video_port_t **video_input;
   
@@ -414,9 +414,29 @@ void xine_post_dispose(xine_t *xine, xine_post_t *self);
 
 
 /* post plugin data types */
+
+/* video port data
+ * input->data is a xine_video_port_t*
+ * output->data is a xine_video_port_t**
+ */
 #define XINE_POST_DATA_VIDEO          0
+
+/* audio port data
+ * input->data is a xine_audio_port_t*
+ * output->data is a xine_audio_port_t**
+ */
 #define XINE_POST_DATA_AUDIO          1
+
+/* integer data
+ * input->data is a int*
+ * output->data is a int*
+ */
 #define XINE_POST_DATA_INT            3
+
+/* double precision floating point data
+ * input->data is a double*
+ * output->data is a double*
+ */
 #define XINE_POST_DATA_DOUBLE         4
 
 
diff --git a/src/xine-engine/post.c b/src/xine-engine/post.c
index c65e53400..40cb30aab 100644
--- a/src/xine-engine/post.c
+++ b/src/xine-engine/post.c
@@ -17,7 +17,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: post.c,v 1.1 2002/12/01 14:52:55 mroi Exp $
+ * $Id: post.c,v 1.2 2002/12/03 21:59:46 mroi Exp $
  */
  
 /*
@@ -99,7 +99,7 @@ post_video_port_t *post_intercept_video_port(xine_video_port_t *original) {
 }
 
 
-/* functions intercepting frame calls */
+/* dummy intercept functions for frames */
 static void post_frame_free(vo_frame_t *vo_img) {
   post_video_port_t *port = (post_video_port_t *)vo_img->port;
   post_restore_video_frame(vo_img, port);
diff --git a/src/xine-engine/post.h b/src/xine-engine/post.h
index 373480c46..156347dc0 100644
--- a/src/xine-engine/post.h
+++ b/src/xine-engine/post.h
@@ -17,7 +17,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
  *
- * $Id: post.h,v 1.1 2002/12/01 14:52:56 mroi Exp $
+ * $Id: post.h,v 1.2 2002/12/03 21:59:46 mroi Exp $
  *
  * post plugin definitions
  *
@@ -92,6 +92,17 @@ struct post_plugin_s {
 };
 
 
+/* Post plugins work by intercepting calls to video or audio ports
+ * in the sense of the decorator design pattern. They reuse the
+ * functions of a given target port, but add own functionality in
+ * front of that port by creating a new port structure and filling in
+ * the function pointers with pointers to own functions that
+ * would do something and then call the original port function.
+ *
+ * Much the same is done with video frames which have their own
+ * set of functions attached that you might need to decorate.
+ */
+
 /* helper structure for intercepting video port calls */
 typedef struct post_video_port_s post_video_port_t;
 struct post_video_port_s {
@@ -104,14 +115,18 @@ struct post_video_port_s {
   
   /* here you can keep information about the frames */
   vo_frame_t         original_frame;
+  
+  /* backward reference so that you have access to the post plugin
+   * when the call only gives you the port */
+  xine_post_t       *post;
 };
 
-/* use this to create a new video port in which port functions can
- * be replaced with own implementation */
+/* use this to create a new, trivially decorated video port in which
+ * port functions can be replaced with own implementations */
 post_video_port_t *post_intercept_video_port(xine_video_port_t *port);
 
-/* use this to modify a frame to so that functions can be replaced
- * with own implementations */
+/* use this to decorate and to undecorate a frame so that its functions
+ * can be replaced with own implementations */
 void post_intercept_video_frame(vo_frame_t *frame, post_video_port_t *port);
 void post_restore_video_frame(vo_frame_t *frame, post_video_port_t *port);