FCL/sf/mw/gstreamer: comparison gst_plugins_base/gst-libs/gst/interfaces/tuner.c

equal deleted inserted replaced

-:4b0c6ed43234
+:8e837d1bf446
 #include <string.h>
 /**
 * SECTION:gsttuner
 * @short_description: Interface for elements providing tuner operations
+*
+* <refsect2>
+* <para>
+* The GstTuner interface is provided by elements that have the ability to
+* tune into multiple input signals, for example TV or radio capture cards.
+* </para><para>
+* The interpretation of 'tuning into' an input stream depends on the element
+* implementing the interface. For v4lsrc, it might imply selection of an
+* input source and/or frequency to be configured on a TV card. Another
+* GstTuner implementation might be to allow selection of an active input pad
+* from multiple input pads.
+* </para><para>
+* That said, the GstTuner interface functions are biased toward the
+* TV capture scenario.
+* </para><para>
+* The general parameters provided are for configuration are:
+* <itemizedlist>
+* <listitem>Selection of a current #GstTunerChannel. The current channel
+* represents the input source (e.g. Composite, S-Video etc for TV capture).
+* </listitem>
+* <listitem>The #GstTunerNorm for the channel. The norm chooses the
+* interpretation of the incoming signal for the current channel. For example,
+* PAL or NTSC, or more specific variants there-of.
+* </listitem>
+* <listitem>Channel frequency. If the current channel has the ability to tune
+* between multiple frequencies (if it has the GST_TUNER_CHANNEL_FREQUENCY flag)
+* then the frequency can be changed/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
+retrieved via the
+* gst_tuner_set_frequency() and gst_tuner_get_frequency() methods.
+* </listitem>
+* </itemizedlist>
+* </para>
+* <para>
+* Where applicable, the signal strength can be retrieved and/or monitored
+* via a signal.
+* </para>
+* </refsect2>
 */
 enum
 {
 NORM_CHANGED,
 gst_tuner_class_init (GstTunerClass * klass)
 {
 static gboolean initialized = FALSE;
 if (!initialized) {
+/**
+* GstTuner::norm-changed:
+* @tuner: The element providing the GstTuner interface
+* @norm: The new configured norm.
+*
+* Reports that the current #GstTunerNorm has changed.
+*/
 gst_tuner_signals[NORM_CHANGED] =
 g_signal_new ("norm-changed",
 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
 G_STRUCT_OFFSET (GstTunerClass, norm_changed),
 NULL, NULL,
 g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_TUNER_NORM);
+/**
+* GstTuner::channel-changed:
+* @tuner: The element providing the GstTuner interface
+* @channel: The new configured channel.
+*
+* Reports that the current #GstTunerChannel has changed.
+*/
 gst_tuner_signals[CHANNEL_CHANGED] =
 g_signal_new ("channel-changed",
 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
 G_STRUCT_OFFSET (GstTunerClass, channel_changed),
 NULL, NULL,
 g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
 GST_TYPE_TUNER_CHANNEL);
+/**
+* GstTuner::frequency-changed:
+* @tuner: The element providing the GstTuner interface
+* @frequency: The new frequency (an unsigned long)
+*
+* Reports that the current frequency has changed.
+*/
 gst_tuner_signals[FREQUENCY_CHANGED] =
 g_signal_new ("frequency-changed",
 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
 G_STRUCT_OFFSET (GstTunerClass, frequency_changed),
 NULL, NULL,
 gst_interfaces_marshal_VOID__OBJECT_ULONG, G_TYPE_NONE, 2,
 GST_TYPE_TUNER_CHANNEL, G_TYPE_ULONG);
+/**
+* GstTuner::signal-changed:
+* @tuner: The element providing the GstTuner interface
+* @channel: The current #GstTunerChannel
+* @signal: The new signal strength (an integer)
+*
+* Reports that the signal strength has changed.
+*
+* See Also: gst_tuner_signal_strength()
+*/
 gst_tuner_signals[SIGNAL_CHANGED] =
 g_signal_new ("signal-changed",
 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
 G_STRUCT_OFFSET (GstTunerClass, signal_changed),
 NULL, NULL,
 /**
 * gst_tuner_list_channels:
 * @tuner: the #GstTuner (a #GstElement) to get the channels from.
 *
-* Retrieve a list of channels (e.g. 'composite', 's-video', ...)
+* Retrieve a #GList of #GstTunerChannels available
-* from the given tuner object.
+* (e.g. 'composite', 's-video', ...) from the given tuner object.
 *
-* Returns: a list of channels available on this tuner.
+* Returns: A list of channels available on this tuner. The list is
-*/
+*          owned by the GstTuner and must not be freed.
-#ifdef __SYMBIAN32__
+*/
-EXPORT_C
+#ifdef __SYMBIAN32__
-#endif
+EXPORT_C
+#endif
 const GList *
 gst_tuner_list_channels (GstTuner * tuner)
 {
 GstTunerClass *klass;
 klass->set_channel (tuner, channel);
 }
 }
 /**
-* gst_Tuner_get_channel:
+* gst_tuner_get_channel:
 * @tuner: the #GstTuner (a #GstElement) to get the current channel from.
 *
 * Retrieve the current channel from the tuner.
 *
 * Returns: the current channel of the tuner object.
 return NULL;
 }
 /**
-* gst_tuner_get_norms_list:
+* gst_tuner_list_norms:
 * @tuner: the #GstTuner (*a #GstElement) to get the list of norms from.
 *
-* Retrieve a list of available norms on the currently tuned channel
+* Retrieve a GList of available #GstTunerNorm settings for the currently
-* from the given tuner object.
+* tuned channel on the given tuner object.
 *
 * Returns: A list of norms available on the current channel for this
-*          tuner object.
+*          tuner object. The list is owned by the GstTuner and must not
+*          be freed.
 */
 #ifdef __SYMBIAN32__
 EXPORT_C
 #endif
 return NULL;
 }
 /**
 * gst_tuner_set_frequency:
-* @tuner: the #Gsttuner (a #GstElement) that owns the given channel.
+* @tuner: The #Gsttuner (a #GstElement) that owns the given channel.
-* @channel: the #GstTunerChannel to set the frequency on.
+* @channel: The #GstTunerChannel to set the frequency on.
-* @frequency: the frequency to tune in to.
+* @frequency: The frequency to tune in to.
 *
 * Sets a tuning frequency on the given tuner/channel. Note that this
 * requires the given channel to be a "tuning" channel, which can be
 * checked using GST_TUNER_CHANNEL_HAS_FLAG (), with the proper flag
 * being GST_TUNER_CHANNEL_FREQUENCY.
-*/
+*
-#ifdef __SYMBIAN32__
+* The frequency is in Hz, with minimum steps indicated by the
-EXPORT_C
+* frequency_multiplicator provided in the #GstTunerChannel. The
-#endif
+* valid range is provided in the min_frequency and max_frequency properties
+* of the #GstTunerChannel.
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 void
 gst_tuner_set_frequency (GstTuner * tuner,
 GstTunerChannel * channel, gulong frequency)
 {
 }
 }
 /**
 * gst_tuner_get_frequency:
-* @tuner: the #GstTuner (a #GstElement) that owns the given channel.
+* @tuner: The #GstTuner (a #GstElement) that owns the given channel.
-* @channel: the #GstTunerChannel to retrieve the frequency from.
+* @channel: The #GstTunerChannel to retrieve the frequency from.
 *
-* Retrieve the current frequency from the given channel. The same
+* Retrieve the current frequency from the given channel. As for
-* applies as for set_frequency (): check the flag.
+* gst_tuner_set_frequency(), the #GstTunerChannel must support frequency
-*
+* operations, as indicated by the GST_TUNER_CHANNEL_FREQUENCY flag.
-* Returns: the current frequency, or 0 on error.
+*
+* Returns: The current frequency, or 0 on error.
 */
 #ifdef __SYMBIAN32__
 EXPORT_C
 #endif
 return 0;
 }
 /**
-* gst_tuner_get_signal_strength:
+* gst_tuner_signal_strength:
 * @tuner: the #GstTuner (a #GstElement) that owns the given channel.
 * @channel: the #GstTunerChannel to get the signal strength from.
 *
-* get the strength of the signal on this channel. Note that this
+* Get the strength of the signal on this channel. Note that this
-* requires the current channel to be a "tuning" channel, e.g. a
+* requires the current channel to be a "tuning" channel, i.e. a
 * channel on which frequency can be set. This can be checked using
 * GST_TUNER_CHANNEL_HAS_FLAG (), and the appropriate flag to check
 * for is GST_TUNER_CHANNEL_FREQUENCY.
 *
-* Returns: signal strength, or 0 on error.
+* The valid range of the signal strength is indicated in the
-*/
+* min_signal and max_signal properties of the #GstTunerChannel.
-#ifdef __SYMBIAN32__
+*
-EXPORT_C
+* Returns: Signal strength, or 0 on error.
-#endif
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 gint
 gst_tuner_signal_strength (GstTuner * tuner, GstTunerChannel * channel)
 {
 GstTunerClass *klass;
 return klass->signal_strength (tuner, channel);
 }
 return 0;
 }
-#ifdef __SYMBIAN32__
-EXPORT_C
+/**
-#endif
+* gst_tuner_find_norm_by_name:
+* @tuner: A #GstTuner instance
+* @norm: A string containing the name of a #GstTunerNorm
+*
+* Look up a #GstTunerNorm by name.
+*
+* Returns: A #GstTunerNorm, or NULL if no norm with the provided name
+* is available.
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 GstTunerNorm *
 gst_tuner_find_norm_by_name (GstTuner * tuner, gchar * norm)
 {
 GList *walk;
 return GST_TUNER_NORM (walk->data);
 walk = g_list_next (walk);
 }
 return NULL;
 }
-#ifdef __SYMBIAN32__
-EXPORT_C
+/**
-#endif
+* gst_tuner_find_channel_by_name:
+* @tuner: A #GstTuner instance
+* @channel: A string containing the name of a #GstTunerChannel
+*
+* Look up a #GstTunerChannel by name.
+*
+* Returns: A #GstTunerChannel, or NULL if no channel with the provided name
+* is available.
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 GstTunerChannel *
 gst_tuner_find_channel_by_name (GstTuner * tuner, gchar * channel)
 {
 GList *walk;
 return GST_TUNER_CHANNEL (walk->data);
 walk = g_list_next (walk);
 }
 return NULL;
 }
-#ifdef __SYMBIAN32__
-EXPORT_C
+/**
-#endif
+* gst_tuner_channel_changed:
+* @tuner: A #GstTuner instance
+* @channel: A #GstTunerChannel instance
+*
+* Called by elements implementing the #GstTuner interface when the
+* current channel changes. Fires the #GstTuner::channel-changed signal.
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 void
 gst_tuner_channel_changed (GstTuner * tuner, GstTunerChannel * channel)
 {
 g_return_if_fail (GST_IS_TUNER (tuner));
 g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
 g_signal_emit (G_OBJECT (tuner),
 gst_tuner_signals[CHANNEL_CHANGED], 0, channel);
 }
-#ifdef __SYMBIAN32__
-EXPORT_C
+/**
-#endif
+* gst_tuner_norm_changed:
+* @tuner: A #GstTuner instance
+* @norm: A #GstTunerNorm instance
+*
+* Called by elements implementing the #GstTuner interface when the
+* current norm changes. Fires the #GstTuner::norm-changed signal.
+*
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 void
 gst_tuner_norm_changed (GstTuner * tuner, GstTunerNorm * norm)
 {
 g_return_if_fail (GST_IS_TUNER (tuner));
 g_return_if_fail (GST_IS_TUNER_NORM (norm));
 g_signal_emit (G_OBJECT (tuner), gst_tuner_signals[NORM_CHANGED], 0, norm);
 }
-#ifdef __SYMBIAN32__
-EXPORT_C
+/**
-#endif
+* gst_tuner_frequency_changed:
+* @tuner: A #GstTuner instance
+* @channel: The current #GstTunerChannel
+* @frequency: The new frequency setting
+*
+* Called by elements implementing the #GstTuner interface when the
+* configured frequency changes. Fires the #GstTuner::frequency-changed
+* signal on the tuner, and the #GstTunerChannel::frequency-changed signal
+* on the channel.
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 void
 gst_tuner_frequency_changed (GstTuner * tuner,
 GstTunerChannel * channel, gulong frequency)
 {
 g_signal_emit (G_OBJECT (tuner),
 gst_tuner_signals[FREQUENCY_CHANGED], 0, channel, frequency);
 g_signal_emit_by_name (G_OBJECT (channel), "frequency_changed", frequency);
 }
-#ifdef __SYMBIAN32__
-EXPORT_C
+/**
-#endif
+* gst_tuner_signal_changed:
+* @tuner: A #GstTuner instance
+* @channel: The current #GstTunerChannel
+* @signal: The new signal strength
+*
+* Called by elements implementing the #GstTuner interface when the
+* incoming signal strength changes. Fires the #GstTuner::signal-changed
+* signal on the tuner and the #GstTunerChannel::signal-changed signal on
+* the channel.
+*/
+#ifdef __SYMBIAN32__
+EXPORT_C
+#endif
 void
 gst_tuner_signal_changed (GstTuner * tuner,
 GstTunerChannel * channel, gint signal)
 {

changeset 16	8e837d1bf446
parent 0	0e761a78d257
child 30	7e817e7e631c