2 * Copyright (C) 2003 Ronald Bultje <rbultje@ronald.bitfreak.net>
4 * tuner.c: tuner design virtual class function wrappers
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
27 #include "interfaces-marshal.h"
33 * @short_description: Interface for elements providing tuner operations
37 * The GstTuner interface is provided by elements that have the ability to
38 * tune into multiple input signals, for example TV or radio capture cards.
40 * The interpretation of 'tuning into' an input stream depends on the element
41 * implementing the interface. For v4lsrc, it might imply selection of an
42 * input source and/or frequency to be configured on a TV card. Another
43 * GstTuner implementation might be to allow selection of an active input pad
44 * from multiple input pads.
46 * That said, the GstTuner interface functions are biased toward the
47 * TV capture scenario.
49 * The general parameters provided are for configuration are:
51 * <listitem>Selection of a current #GstTunerChannel. The current channel
52 * represents the input source (e.g. Composite, S-Video etc for TV capture).
54 * <listitem>The #GstTunerNorm for the channel. The norm chooses the
55 * interpretation of the incoming signal for the current channel. For example,
56 * PAL or NTSC, or more specific variants there-of.
58 * <listitem>Channel frequency. If the current channel has the ability to tune
59 * between multiple frequencies (if it has the GST_TUNER_CHANNEL_FREQUENCY flag)
60 * then the frequency can be changed/retrieved via the
61 * gst_tuner_set_frequency() and gst_tuner_get_frequency() methods.
66 * Where applicable, the signal strength can be retrieved and/or monitored
81 static void gst_tuner_class_init (GstTunerClass * klass);
83 static guint gst_tuner_signals[LAST_SIGNAL] = { 0 };
86 gst_tuner_get_type (void)
88 static GType gst_tuner_type = 0;
90 if (!gst_tuner_type) {
91 static const GTypeInfo gst_tuner_info = {
92 sizeof (GstTunerClass),
93 (GBaseInitFunc) gst_tuner_class_init,
103 gst_tuner_type = g_type_register_static (G_TYPE_INTERFACE,
104 "GstTuner", &gst_tuner_info, 0);
105 g_type_interface_add_prerequisite (gst_tuner_type,
106 GST_TYPE_IMPLEMENTS_INTERFACE);
109 return gst_tuner_type;
113 gst_tuner_class_init (GstTunerClass * klass)
115 static gboolean initialized = FALSE;
119 * GstTuner::norm-changed:
120 * @tuner: The element providing the GstTuner interface
121 * @norm: The new configured norm.
123 * Reports that the current #GstTunerNorm has changed.
125 gst_tuner_signals[NORM_CHANGED] =
126 g_signal_new ("norm-changed",
127 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
128 G_STRUCT_OFFSET (GstTunerClass, norm_changed),
130 g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_TUNER_NORM);
132 * GstTuner::channel-changed:
133 * @tuner: The element providing the GstTuner interface
134 * @channel: The new configured channel.
136 * Reports that the current #GstTunerChannel has changed.
138 gst_tuner_signals[CHANNEL_CHANGED] =
139 g_signal_new ("channel-changed",
140 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
141 G_STRUCT_OFFSET (GstTunerClass, channel_changed),
143 g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
144 GST_TYPE_TUNER_CHANNEL);
146 * GstTuner::frequency-changed:
147 * @tuner: The element providing the GstTuner interface
148 * @frequency: The new frequency (an unsigned long)
150 * Reports that the current frequency has changed.
152 gst_tuner_signals[FREQUENCY_CHANGED] =
153 g_signal_new ("frequency-changed",
154 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
155 G_STRUCT_OFFSET (GstTunerClass, frequency_changed),
157 gst_interfaces_marshal_VOID__OBJECT_ULONG, G_TYPE_NONE, 2,
158 GST_TYPE_TUNER_CHANNEL, G_TYPE_ULONG);
160 * GstTuner::signal-changed:
161 * @tuner: The element providing the GstTuner interface
162 * @channel: The current #GstTunerChannel
163 * @signal: The new signal strength (an integer)
165 * Reports that the signal strength has changed.
167 * See Also: gst_tuner_signal_strength()
169 gst_tuner_signals[SIGNAL_CHANGED] =
170 g_signal_new ("signal-changed",
171 GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
172 G_STRUCT_OFFSET (GstTunerClass, signal_changed),
174 gst_interfaces_marshal_VOID__OBJECT_INT, G_TYPE_NONE, 2,
175 GST_TYPE_TUNER_CHANNEL, G_TYPE_INT);
180 /* default virtual functions */
181 klass->list_channels = NULL;
182 klass->set_channel = NULL;
183 klass->get_channel = NULL;
185 klass->list_norms = NULL;
186 klass->set_norm = NULL;
187 klass->get_norm = NULL;
189 klass->set_frequency = NULL;
190 klass->get_frequency = NULL;
191 klass->signal_strength = NULL;
195 * gst_tuner_list_channels:
196 * @tuner: the #GstTuner (a #GstElement) to get the channels from.
198 * Retrieve a #GList of #GstTunerChannels available
199 * (e.g. 'composite', 's-video', ...) from the given tuner object.
201 * Returns: A list of channels available on this tuner. The list is
202 * owned by the GstTuner and must not be freed.
205 gst_tuner_list_channels (GstTuner * tuner)
207 GstTunerClass *klass;
209 g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
211 klass = GST_TUNER_GET_CLASS (tuner);
212 if (klass->list_channels) {
213 return klass->list_channels (tuner);
220 * gst_tuner_set_channel:
221 * @tuner: the #GstTuner (a #GstElement) that owns the channel.
222 * @channel: the channel to tune to.
224 * Tunes the object to the given channel, which should be one of the
225 * channels returned by gst_tuner_list_channels().
229 gst_tuner_set_channel (GstTuner * tuner, GstTunerChannel * channel)
231 GstTunerClass *klass;
233 g_return_if_fail (GST_IS_TUNER (tuner));
235 klass = GST_TUNER_GET_CLASS (tuner);
236 if (klass->set_channel) {
237 klass->set_channel (tuner, channel);
242 * gst_tuner_get_channel:
243 * @tuner: the #GstTuner (a #GstElement) to get the current channel from.
245 * Retrieve the current channel from the tuner.
247 * Returns: the current channel of the tuner object.
251 gst_tuner_get_channel (GstTuner * tuner)
253 GstTunerClass *klass;
255 g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
257 klass = GST_TUNER_GET_CLASS (tuner);
258 if (klass->get_channel) {
259 return klass->get_channel (tuner);
266 * gst_tuner_list_norms:
267 * @tuner: the #GstTuner (*a #GstElement) to get the list of norms from.
269 * Retrieve a GList of available #GstTunerNorm settings for the currently
270 * tuned channel on the given tuner object.
272 * Returns: A list of norms available on the current channel for this
273 * tuner object. The list is owned by the GstTuner and must not
278 gst_tuner_list_norms (GstTuner * tuner)
280 GstTunerClass *klass;
282 g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
284 klass = GST_TUNER_GET_CLASS (tuner);
285 if (klass->list_norms) {
286 return klass->list_norms (tuner);
293 * gst_tuner_set_norm:
294 * @tuner: the #GstTuner (a #GstElement) to set the norm on.
295 * @norm: the norm to use for the current channel.
297 * Changes the video norm on this tuner to the given norm, which should be
298 * one of the norms returned by gst_tuner_list_norms().
302 gst_tuner_set_norm (GstTuner * tuner, GstTunerNorm * norm)
304 GstTunerClass *klass;
306 g_return_if_fail (GST_IS_TUNER (tuner));
308 klass = GST_TUNER_GET_CLASS (tuner);
309 if (klass->set_norm) {
310 klass->set_norm (tuner, norm);
315 * gst_tuner_get_norm:
316 * @tuner: the #GstTuner (a #GstElement) to get the current norm from.
318 * Get the current video norm from the given tuner object for the
319 * currently selected channel.
321 * Returns: the current norm.
325 gst_tuner_get_norm (GstTuner * tuner)
327 GstTunerClass *klass;
329 g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
331 klass = GST_TUNER_GET_CLASS (tuner);
332 if (klass->get_norm) {
333 return klass->get_norm (tuner);
340 * gst_tuner_set_frequency:
341 * @tuner: The #GstTuner (a #GstElement) that owns the given channel.
342 * @channel: The #GstTunerChannel to set the frequency on.
343 * @frequency: The frequency to tune in to.
345 * Sets a tuning frequency on the given tuner/channel. Note that this
346 * requires the given channel to be a "tuning" channel, which can be
347 * checked using GST_TUNER_CHANNEL_HAS_FLAG (), with the proper flag
348 * being GST_TUNER_CHANNEL_FREQUENCY.
350 * The frequency is in Hz, with minimum steps indicated by the
351 * frequency_multiplicator provided in the #GstTunerChannel. The
352 * valid range is provided in the min_frequency and max_frequency properties
353 * of the #GstTunerChannel.
357 gst_tuner_set_frequency (GstTuner * tuner,
358 GstTunerChannel * channel, gulong frequency)
360 GstTunerClass *klass;
362 g_return_if_fail (GST_IS_TUNER (tuner));
363 g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
364 g_return_if_fail (GST_TUNER_CHANNEL_HAS_FLAG (channel,
365 GST_TUNER_CHANNEL_FREQUENCY));
367 klass = GST_TUNER_GET_CLASS (tuner);
368 if (klass->set_frequency) {
369 klass->set_frequency (tuner, channel, frequency);
374 * gst_tuner_get_frequency:
375 * @tuner: The #GstTuner (a #GstElement) that owns the given channel.
376 * @channel: The #GstTunerChannel to retrieve the frequency from.
378 * Retrieve the current frequency from the given channel. As for
379 * gst_tuner_set_frequency(), the #GstTunerChannel must support frequency
380 * operations, as indicated by the GST_TUNER_CHANNEL_FREQUENCY flag.
382 * Returns: The current frequency, or 0 on error.
386 gst_tuner_get_frequency (GstTuner * tuner, GstTunerChannel * channel)
388 GstTunerClass *klass;
390 g_return_val_if_fail (GST_IS_TUNER (tuner), 0);
391 g_return_val_if_fail (GST_IS_TUNER_CHANNEL (channel), 0);
392 g_return_val_if_fail (GST_TUNER_CHANNEL_HAS_FLAG (channel,
393 GST_TUNER_CHANNEL_FREQUENCY), 0);
395 klass = GST_TUNER_GET_CLASS (tuner);
397 if (klass->get_frequency) {
398 return klass->get_frequency (tuner, channel);
405 * gst_tuner_signal_strength:
406 * @tuner: the #GstTuner (a #GstElement) that owns the given channel.
407 * @channel: the #GstTunerChannel to get the signal strength from.
409 * Get the strength of the signal on this channel. Note that this
410 * requires the current channel to be a "tuning" channel, i.e. a
411 * channel on which frequency can be set. This can be checked using
412 * GST_TUNER_CHANNEL_HAS_FLAG (), and the appropriate flag to check
413 * for is GST_TUNER_CHANNEL_FREQUENCY.
415 * The valid range of the signal strength is indicated in the
416 * min_signal and max_signal properties of the #GstTunerChannel.
418 * Returns: Signal strength, or 0 on error.
421 gst_tuner_signal_strength (GstTuner * tuner, GstTunerChannel * channel)
423 GstTunerClass *klass;
425 g_return_val_if_fail (GST_IS_TUNER (tuner), 0);
426 g_return_val_if_fail (GST_IS_TUNER_CHANNEL (channel), 0);
427 g_return_val_if_fail (GST_TUNER_CHANNEL_HAS_FLAG (channel,
428 GST_TUNER_CHANNEL_FREQUENCY), 0);
430 klass = GST_TUNER_GET_CLASS (tuner);
431 if (klass->signal_strength) {
432 return klass->signal_strength (tuner, channel);
439 * gst_tuner_find_norm_by_name:
440 * @tuner: A #GstTuner instance
441 * @norm: A string containing the name of a #GstTunerNorm
443 * Look up a #GstTunerNorm by name.
445 * Returns: A #GstTunerNorm, or NULL if no norm with the provided name
449 gst_tuner_find_norm_by_name (GstTuner * tuner, gchar * norm)
453 g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
454 g_return_val_if_fail (norm != NULL, NULL);
456 walk = (GList *) gst_tuner_list_norms (tuner);
458 if (strcmp (GST_TUNER_NORM (walk->data)->label, norm) == 0)
459 return GST_TUNER_NORM (walk->data);
460 walk = g_list_next (walk);
466 * gst_tuner_find_channel_by_name:
467 * @tuner: A #GstTuner instance
468 * @channel: A string containing the name of a #GstTunerChannel
470 * Look up a #GstTunerChannel by name.
472 * Returns: A #GstTunerChannel, or NULL if no channel with the provided name
476 gst_tuner_find_channel_by_name (GstTuner * tuner, gchar * channel)
480 g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
481 g_return_val_if_fail (channel != NULL, NULL);
483 walk = (GList *) gst_tuner_list_channels (tuner);
485 if (strcmp (GST_TUNER_CHANNEL (walk->data)->label, channel) == 0)
486 return GST_TUNER_CHANNEL (walk->data);
487 walk = g_list_next (walk);
493 * gst_tuner_channel_changed:
494 * @tuner: A #GstTuner instance
495 * @channel: A #GstTunerChannel instance
497 * Called by elements implementing the #GstTuner interface when the
498 * current channel changes. Fires the #GstTuner::channel-changed signal.
501 gst_tuner_channel_changed (GstTuner * tuner, GstTunerChannel * channel)
503 g_return_if_fail (GST_IS_TUNER (tuner));
504 g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
506 g_signal_emit (G_OBJECT (tuner),
507 gst_tuner_signals[CHANNEL_CHANGED], 0, channel);
511 * gst_tuner_norm_changed:
512 * @tuner: A #GstTuner instance
513 * @norm: A #GstTunerNorm instance
515 * Called by elements implementing the #GstTuner interface when the
516 * current norm changes. Fires the #GstTuner::norm-changed signal.
520 gst_tuner_norm_changed (GstTuner * tuner, GstTunerNorm * norm)
522 g_return_if_fail (GST_IS_TUNER (tuner));
523 g_return_if_fail (GST_IS_TUNER_NORM (norm));
525 g_signal_emit (G_OBJECT (tuner), gst_tuner_signals[NORM_CHANGED], 0, norm);
529 * gst_tuner_frequency_changed:
530 * @tuner: A #GstTuner instance
531 * @channel: The current #GstTunerChannel
532 * @frequency: The new frequency setting
534 * Called by elements implementing the #GstTuner interface when the
535 * configured frequency changes. Fires the #GstTuner::frequency-changed
536 * signal on the tuner, and the #GstTunerChannel::frequency-changed signal
540 gst_tuner_frequency_changed (GstTuner * tuner,
541 GstTunerChannel * channel, gulong frequency)
543 g_return_if_fail (GST_IS_TUNER (tuner));
544 g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
546 g_signal_emit (G_OBJECT (tuner),
547 gst_tuner_signals[FREQUENCY_CHANGED], 0, channel, frequency);
549 g_signal_emit_by_name (G_OBJECT (channel), "frequency_changed", frequency);
553 * gst_tuner_signal_changed:
554 * @tuner: A #GstTuner instance
555 * @channel: The current #GstTunerChannel
556 * @signal: The new signal strength
558 * Called by elements implementing the #GstTuner interface when the
559 * incoming signal strength changes. Fires the #GstTuner::signal-changed
560 * signal on the tuner and the #GstTunerChannel::signal-changed signal on
564 gst_tuner_signal_changed (GstTuner * tuner,
565 GstTunerChannel * channel, gint signal)
567 g_return_if_fail (GST_IS_TUNER (tuner));
568 g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
570 g_signal_emit (G_OBJECT (tuner),
571 gst_tuner_signals[SIGNAL_CHANGED], 0, channel, signal);
573 g_signal_emit_by_name (G_OBJECT (channel), "signal_changed", signal);