From ef5f73206dd3ad515abea7e2c1a8e24a3fcc2814 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Fri, 18 Feb 2011 11:58:44 +0100 Subject: [PATCH] decodebin2: Update documentation of the autoplug-* signals Add notes about the behaviour if multiple signal handlers are connected. For most autoplug-* signals only the first signal handler will ever be invoked. Also add to the autoplug-sort docs that the signal handler can return NULL to specify that the order should change and other handlers get the chance to sort the array. --- gst/playback/gstdecodebin2.c | 51 +++++++++++++++++++++++++++--------- 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/gst/playback/gstdecodebin2.c b/gst/playback/gstdecodebin2.c index 7d762a2918..f28ff4a70c 100644 --- a/gst/playback/gstdecodebin2.c +++ b/gst/playback/gstdecodebin2.c @@ -590,8 +590,8 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) /** * GstDecodeBin2::new-decoded-pad: - * @bin: The decodebin - * @pad: The newly created pad + * @bin: The decodebin. + * @pad: The newly created pad. * @islast: #TRUE if this is the last pad to be added. Deprecated. * * This signal gets emitted as soon as a new pad of the same type as one of @@ -609,8 +609,8 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) /** * GstDecodeBin2::removed-decoded-pad: - * @bin: The decodebin - * @pad: The pad that was removed + * @bin: The decodebin. + * @pad: The pad that was removed. * * This signal is emitted when a 'final' caps pad has been removed. * @@ -625,7 +625,7 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) /** * GstDecodeBin2::unknown-type: - * @bin: The decodebin + * @bin: The decodebin. * @pad: The new pad containing caps that cannot be resolved to a 'final' * stream type. * @caps: The #GstCaps of the pad that cannot be resolved. @@ -641,13 +641,19 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) /** * GstDecodeBin2::autoplug-continue: - * @bin: The decodebin + * @bin: The decodebin. * @pad: The #GstPad. * @caps: The #GstCaps found. * * This signal is emitted whenever decodebin2 finds a new stream. It is * emitted before looking for any elements that can handle that stream. * + * + * Invocation of signal handlers stops after the first signal handler + * returns #FALSE. Signal handlers are invoked in the order they were + * connected in. + * + * * Returns: #TRUE if you wish decodebin2 to look for elements that can * handle the given @caps. If #FALSE, those caps will be considered as * final and the pad will be exposed as such (see 'new-decoded-pad' @@ -661,7 +667,7 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) /** * GstDecodeBin2::autoplug-factories: - * @bin: The decodebin + * @bin: The decodebin. * @pad: The #GstPad. * @caps: The #GstCaps found. * @@ -672,7 +678,13 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) * If this function returns NULL, @pad will be exposed as a final caps. * * If this function returns an empty array, the pad will be considered as - * having an unhandled type media type. + * having an unhandled type media type. + * + * + * Only the signal handler that is connected first will ever by invoked. + * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * signal, they will never be invoked! + * * * Returns: a #GValueArray* with a list of factories to try. The factories are * by default tried in the returned order or based on the index returned by @@ -687,7 +699,7 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) /** * GstDecodeBin2::autoplug-sort: - * @bin: The decodebin + * @bin: The decodebin. * @pad: The #GstPad. * @caps: The #GstCaps. * @factories: A #GValueArray of possible #GstElementFactory to use. @@ -697,7 +709,16 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) * the application to perform additional sorting or filtering on the element * factory array. * - * The callee should copy and modify @factories. + * The callee should copy and modify @factories or return #NULL if the + * order should not change. + * + * + * Invocation of signal handlers stops after one signal handler has + * returned something else than #NULL. Signal handlers are invoked in + * the order they were connected in. + * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * signal, they will never be invoked! + * * * Returns: A new sorted array of #GstElementFactory objects. */ @@ -710,10 +731,10 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) /** * GstDecodeBin2::autoplug-select: - * @bin: The decodebin + * @bin: The decodebin. * @pad: The #GstPad. * @caps: The #GstCaps. - * @factory: A #GstElementFactory to use + * @factory: A #GstElementFactory to use. * * This signal is emitted once decodebin2 has found all the possible * #GstElementFactory that can be used to handle the given @caps. For each of @@ -731,6 +752,12 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass) * A value of #GST_AUTOPLUG_SELECT_SKIP will skip @factory and move to the * next factory. * + * + * Only the signal handler that is connected first will ever by invoked. + * Don't connect signal handlers with the #G_CONNECT_AFTER flag to this + * signal, they will never be invoked! + * + * * Returns: a #GST_TYPE_AUTOPLUG_SELECT_RESULT that indicates the required * operation. the default handler will always return * #GST_AUTOPLUG_SELECT_TRY.