From 179f6c4f3b784dcd36d258aaf8d136b4e30b837d Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Wed, 9 Nov 2005 10:06:30 +0000 Subject: [PATCH] gst/base/gstbasesink.c: Add the beginning of docs here -- have to work on something else now tho... Original commit message from CVS: 2005-11-09 Andy Wingo * gst/base/gstbasesink.c: Add the beginning of docs here -- have to work on something else now tho... --- ChangeLog | 3 ++ gst/base/gstbasesink.c | 56 ++++++++++++++++++++++++++++++------- libs/gst/base/gstbasesink.c | 56 ++++++++++++++++++++++++++++++------- 3 files changed, 95 insertions(+), 20 deletions(-) diff --git a/ChangeLog b/ChangeLog index f12f835c3a..a5e533ba2c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ 2005-11-09 Andy Wingo + * gst/base/gstbasesink.c: Add the beginning of docs here -- have + to work on something else now tho... + * gst/base/gstadapter.c: More adapter docs. * gst/elements/gstfilesink.c (gst_file_sink_start) diff --git a/gst/base/gstbasesink.c b/gst/base/gstbasesink.c index 87bd6d2404..bbc2525a4a 100644 --- a/gst/base/gstbasesink.c +++ b/gst/base/gstbasesink.c @@ -1,7 +1,7 @@ /* GStreamer * Copyright (C) 2005 Wim Taymans * - * gstbasesink.c: + * gstbasesink.c: Base class for sink elements * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -24,16 +24,52 @@ * @short_description: Base class for sink elements * @see_also: #GstBaseTransform, #GstBaseSource * - * This class is for elements that do output operations. + * GstBaseSink is the base class for sink elements in GStreamer, such as + * xvimagesink or filesink. It is a layer on top of #GstElement that provides a + * simplified interface to plugin writers. GstBaseSink handles many details for + * you, for example preroll, clock synchronization, state changes, activation in + * push or pull mode, and queries. In most cases, when writing sink elements, + * there is no need to implement class methods from #GstElement or to set + * functions on pads, because the GstBaseSink infrastructure is sufficient. * - * - * one sinkpad - * handles state changes - * pull/push mode - * handles seeking/query - * handles preroll - * EOS handling - * + * There is only support in GstBaseSink for one sink pad, which should be named + * "sink". A sink implementation (subclass of GstBaseSink) should install a pad + * template in its base_init function, like so: + * + * static void + * my_element_base_init (gpointer g_class) + * { + * GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class); + * + * // sinktemplate should be a #GstStaticPadTemplate with direction + * // #GST_PAD_SINK and name "sink" + * gst_element_class_add_pad_template (gstelement_class, + * gst_static_pad_template_get (&sinktemplate)); + * // see #GstElementDetails + * gst_element_class_set_details (gstelement_class, &details); + * } + * + * + * The one method which all subclasses of GstBaseSink must implement is + * GstBaseSink::render. This method will be called... + * + * preroll() + * + * event(): mostly useful for file-like sinks (seeking or flushing) + * + * get_caps/set_caps/buffer_alloc + * + * start/stop for resource allocation + * + * unlock if you block on an fd, for example + * + * get_times i'm sure is for something :P + * + * provide example of textsink + * + * admonishment not to try to implement your own sink with prerolling... + * + * extending via subclassing, setting pad functions, gstelement vmethods. */ #ifdef HAVE_CONFIG_H diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c index 87bd6d2404..bbc2525a4a 100644 --- a/libs/gst/base/gstbasesink.c +++ b/libs/gst/base/gstbasesink.c @@ -1,7 +1,7 @@ /* GStreamer * Copyright (C) 2005 Wim Taymans * - * gstbasesink.c: + * gstbasesink.c: Base class for sink elements * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public @@ -24,16 +24,52 @@ * @short_description: Base class for sink elements * @see_also: #GstBaseTransform, #GstBaseSource * - * This class is for elements that do output operations. + * GstBaseSink is the base class for sink elements in GStreamer, such as + * xvimagesink or filesink. It is a layer on top of #GstElement that provides a + * simplified interface to plugin writers. GstBaseSink handles many details for + * you, for example preroll, clock synchronization, state changes, activation in + * push or pull mode, and queries. In most cases, when writing sink elements, + * there is no need to implement class methods from #GstElement or to set + * functions on pads, because the GstBaseSink infrastructure is sufficient. * - * - * one sinkpad - * handles state changes - * pull/push mode - * handles seeking/query - * handles preroll - * EOS handling - * + * There is only support in GstBaseSink for one sink pad, which should be named + * "sink". A sink implementation (subclass of GstBaseSink) should install a pad + * template in its base_init function, like so: + * + * static void + * my_element_base_init (gpointer g_class) + * { + * GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class); + * + * // sinktemplate should be a #GstStaticPadTemplate with direction + * // #GST_PAD_SINK and name "sink" + * gst_element_class_add_pad_template (gstelement_class, + * gst_static_pad_template_get (&sinktemplate)); + * // see #GstElementDetails + * gst_element_class_set_details (gstelement_class, &details); + * } + * + * + * The one method which all subclasses of GstBaseSink must implement is + * GstBaseSink::render. This method will be called... + * + * preroll() + * + * event(): mostly useful for file-like sinks (seeking or flushing) + * + * get_caps/set_caps/buffer_alloc + * + * start/stop for resource allocation + * + * unlock if you block on an fd, for example + * + * get_times i'm sure is for something :P + * + * provide example of textsink + * + * admonishment not to try to implement your own sink with prerolling... + * + * extending via subclassing, setting pad functions, gstelement vmethods. */ #ifdef HAVE_CONFIG_H