git.maemo.org Git - mafwsubrenderer/blob - gst-plugins-base-subtitles0.10/gst-libs/gst/interfaces/tuner.c

   1 /* GStreamer Tuner
   2  * Copyright (C) 2003 Ronald Bultje <rbultje@ronald.bitfreak.net>
   3  *
   4  * tuner.c: tuner design virtual class function wrappers
   5  *
   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.
  10  *
  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.
  15  *
  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.
  20  */
  21
  22 #ifdef HAVE_CONFIG_H
  23 #include "config.h"
  24 #endif
  25
  26 #include "tuner.h"
  27 #include "interfaces-marshal.h"
  28
  29 #include <string.h>
  30
  31 /**
  32  * SECTION:gsttuner
  33  * @short_description: Interface for elements providing tuner operations
  34  *
  35  * <refsect2>
  36  * <para>
  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.
  39  * </para><para>
  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.
  45  * </para><para>
  46  * That said, the GstTuner interface functions are biased toward the
  47  * TV capture scenario.
  48  * </para><para>
  49  * The general parameters provided are for configuration are:
  50  * <itemizedlist>
  51  * <listitem>Selection of a current #GstTunerChannel. The current channel
  52  * represents the input source (e.g. Composite, S-Video etc for TV capture).
  53  * </listitem>
  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.
  57  * </listitem>
  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.
  62  * </listitem>
  63  * </itemizedlist>
  64  * </para>
  65  * <para>
  66  * Where applicable, the signal strength can be retrieved and/or monitored
  67  * via a signal.
  68  * </para>
  69  * </refsect2>
  70  */
  71
  72 enum
  73 {
  74   NORM_CHANGED,
  75   CHANNEL_CHANGED,
  76   FREQUENCY_CHANGED,
  77   SIGNAL_CHANGED,
  78   LAST_SIGNAL
  79 };
  80
  81 static void gst_tuner_class_init (GstTunerClass * klass);
  82
  83 static guint gst_tuner_signals[LAST_SIGNAL] = { 0 };
  84
  85 GType
  86 gst_tuner_get_type (void)
  87 {
  88   static GType gst_tuner_type = 0;
  89
  90   if (!gst_tuner_type) {
  91     static const GTypeInfo gst_tuner_info = {
  92       sizeof (GstTunerClass),
  93       (GBaseInitFunc) gst_tuner_class_init,
  94       NULL,
  95       NULL,
  96       NULL,
  97       NULL,
  98       0,
  99       0,
 100       NULL,
 101     };
 102
 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);
 107   }
 108
 109   return gst_tuner_type;
 110 }
 111
 112 static void
 113 gst_tuner_class_init (GstTunerClass * klass)
 114 {
 115   static gboolean initialized = FALSE;
 116
 117   if (!initialized) {
 118     /**
 119      * GstTuner::norm-changed:
 120      * @tuner: The element providing the GstTuner interface
 121      * @norm: The new configured norm.
 122      *
 123      * Reports that the current #GstTunerNorm has changed.
 124      */
 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),
 129         NULL, NULL,
 130         g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_TUNER_NORM);
 131     /**
 132      * GstTuner::channel-changed:
 133      * @tuner: The element providing the GstTuner interface
 134      * @channel: The new configured channel.
 135      *
 136      * Reports that the current #GstTunerChannel has changed.
 137      */
 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),
 142         NULL, NULL,
 143         g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
 144         GST_TYPE_TUNER_CHANNEL);
 145     /**
 146      * GstTuner::frequency-changed:
 147      * @tuner: The element providing the GstTuner interface
 148      * @frequency: The new frequency (an unsigned long)
 149      *
 150      * Reports that the current frequency has changed.
 151      */
 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),
 156         NULL, NULL,
 157         gst_interfaces_marshal_VOID__OBJECT_ULONG, G_TYPE_NONE, 2,
 158         GST_TYPE_TUNER_CHANNEL, G_TYPE_ULONG);
 159     /**
 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)
 164      *
 165      * Reports that the signal strength has changed.
 166      *
 167      * See Also: gst_tuner_signal_strength()
 168      */
 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),
 173         NULL, NULL,
 174         gst_interfaces_marshal_VOID__OBJECT_INT, G_TYPE_NONE, 2,
 175         GST_TYPE_TUNER_CHANNEL, G_TYPE_INT);
 176
 177     initialized = TRUE;
 178   }
 179
 180   /* default virtual functions */
 181   klass->list_channels = NULL;
 182   klass->set_channel = NULL;
 183   klass->get_channel = NULL;
 184
 185   klass->list_norms = NULL;
 186   klass->set_norm = NULL;
 187   klass->get_norm = NULL;
 188
 189   klass->set_frequency = NULL;
 190   klass->get_frequency = NULL;
 191   klass->signal_strength = NULL;
 192 }
 193
 194 /**
 195  * gst_tuner_list_channels:
 196  * @tuner: the #GstTuner (a #GstElement) to get the channels from.
 197  *
 198  * Retrieve a #GList of #GstTunerChannels available
 199  * (e.g. 'composite', 's-video', ...) from the given tuner object.
 200  *
 201  * Returns: A list of channels available on this tuner. The list is
 202  *          owned by the GstTuner and must not be freed.
 203  */
 204 const GList *
 205 gst_tuner_list_channels (GstTuner * tuner)
 206 {
 207   GstTunerClass *klass;
 208
 209   g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
 210
 211   klass = GST_TUNER_GET_CLASS (tuner);
 212   if (klass->list_channels) {
 213     return klass->list_channels (tuner);
 214   }
 215
 216   return NULL;
 217 }
 218
 219 /**
 220  * gst_tuner_set_channel:
 221  * @tuner: the #GstTuner (a #GstElement) that owns the channel.
 222  * @channel: the channel to tune to.
 223  *
 224  * Tunes the object to the given channel, which should be one of the
 225  * channels returned by gst_tuner_list_channels().
 226  */
 227
 228 void
 229 gst_tuner_set_channel (GstTuner * tuner, GstTunerChannel * channel)
 230 {
 231   GstTunerClass *klass;
 232
 233   g_return_if_fail (GST_IS_TUNER (tuner));
 234
 235   klass = GST_TUNER_GET_CLASS (tuner);
 236   if (klass->set_channel) {
 237     klass->set_channel (tuner, channel);
 238   }
 239 }
 240
 241 /**
 242  * gst_tuner_get_channel:
 243  * @tuner: the #GstTuner (a #GstElement) to get the current channel from.
 244  *
 245  * Retrieve the current channel from the tuner.
 246  *
 247  * Returns: the current channel of the tuner object.
 248  */
 249
 250 GstTunerChannel *
 251 gst_tuner_get_channel (GstTuner * tuner)
 252 {
 253   GstTunerClass *klass;
 254
 255   g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
 256
 257   klass = GST_TUNER_GET_CLASS (tuner);
 258   if (klass->get_channel) {
 259     return klass->get_channel (tuner);
 260   }
 261
 262   return NULL;
 263 }
 264
 265 /**
 266  * gst_tuner_list_norms:
 267  * @tuner: the #GstTuner (*a #GstElement) to get the list of norms from.
 268  *
 269  * Retrieve a GList of available #GstTunerNorm settings for the currently
 270  * tuned channel on the given tuner object.
 271  *
 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
 274  *          be freed.
 275  */
 276
 277 const GList *
 278 gst_tuner_list_norms (GstTuner * tuner)
 279 {
 280   GstTunerClass *klass;
 281
 282   g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
 283
 284   klass = GST_TUNER_GET_CLASS (tuner);
 285   if (klass->list_norms) {
 286     return klass->list_norms (tuner);
 287   }
 288
 289   return NULL;
 290 }
 291
 292 /**
 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.
 296  *
 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().
 299  */
 300
 301 void
 302 gst_tuner_set_norm (GstTuner * tuner, GstTunerNorm * norm)
 303 {
 304   GstTunerClass *klass;
 305
 306   g_return_if_fail (GST_IS_TUNER (tuner));
 307
 308   klass = GST_TUNER_GET_CLASS (tuner);
 309   if (klass->set_norm) {
 310     klass->set_norm (tuner, norm);
 311   }
 312 }
 313
 314 /**
 315  * gst_tuner_get_norm:
 316  * @tuner: the #GstTuner (a #GstElement) to get the current norm from.
 317  *
 318  * Get the current video norm from the given tuner object for the
 319  * currently selected channel.
 320  *
 321  * Returns: the current norm.
 322  */
 323
 324 GstTunerNorm *
 325 gst_tuner_get_norm (GstTuner * tuner)
 326 {
 327   GstTunerClass *klass;
 328
 329   g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
 330
 331   klass = GST_TUNER_GET_CLASS (tuner);
 332   if (klass->get_norm) {
 333     return klass->get_norm (tuner);
 334   }
 335
 336   return NULL;
 337 }
 338
 339 /**
 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.
 344  *
 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.
 349  *
 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.
 354  */
 355
 356 void
 357 gst_tuner_set_frequency (GstTuner * tuner,
 358     GstTunerChannel * channel, gulong frequency)
 359 {
 360   GstTunerClass *klass;
 361
 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));
 366
 367   klass = GST_TUNER_GET_CLASS (tuner);
 368   if (klass->set_frequency) {
 369     klass->set_frequency (tuner, channel, frequency);
 370   }
 371 }
 372
 373 /**
 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.
 377  *
 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.
 381  *
 382  * Returns: The current frequency, or 0 on error.
 383  */
 384
 385 gulong
 386 gst_tuner_get_frequency (GstTuner * tuner, GstTunerChannel * channel)
 387 {
 388   GstTunerClass *klass;
 389
 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);
 394
 395   klass = GST_TUNER_GET_CLASS (tuner);
 396
 397   if (klass->get_frequency) {
 398     return klass->get_frequency (tuner, channel);
 399   }
 400
 401   return 0;
 402 }
 403
 404 /**
 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.
 408  *
 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.
 414  *
 415  * The valid range of the signal strength is indicated in the
 416  * min_signal and max_signal properties of the #GstTunerChannel.
 417  *
 418  * Returns: Signal strength, or 0 on error.
 419  */
 420 gint
 421 gst_tuner_signal_strength (GstTuner * tuner, GstTunerChannel * channel)
 422 {
 423   GstTunerClass *klass;
 424
 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);
 429
 430   klass = GST_TUNER_GET_CLASS (tuner);
 431   if (klass->signal_strength) {
 432     return klass->signal_strength (tuner, channel);
 433   }
 434
 435   return 0;
 436 }
 437
 438 /**
 439  * gst_tuner_find_norm_by_name:
 440  * @tuner: A #GstTuner instance
 441  * @norm: A string containing the name of a #GstTunerNorm
 442  *
 443  * Look up a #GstTunerNorm by name.
 444  *
 445  * Returns: A #GstTunerNorm, or NULL if no norm with the provided name
 446  * is available.
 447  */
 448 GstTunerNorm *
 449 gst_tuner_find_norm_by_name (GstTuner * tuner, gchar * norm)
 450 {
 451   GList *walk;
 452
 453   g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
 454   g_return_val_if_fail (norm != NULL, NULL);
 455
 456   walk = (GList *) gst_tuner_list_norms (tuner);
 457   while (walk) {
 458     if (strcmp (GST_TUNER_NORM (walk->data)->label, norm) == 0)
 459       return GST_TUNER_NORM (walk->data);
 460     walk = g_list_next (walk);
 461   }
 462   return NULL;
 463 }
 464
 465 /**
 466  * gst_tuner_find_channel_by_name:
 467  * @tuner: A #GstTuner instance
 468  * @channel: A string containing the name of a #GstTunerChannel
 469  *
 470  * Look up a #GstTunerChannel by name.
 471  *
 472  * Returns: A #GstTunerChannel, or NULL if no channel with the provided name
 473  * is available.
 474  */
 475 GstTunerChannel *
 476 gst_tuner_find_channel_by_name (GstTuner * tuner, gchar * channel)
 477 {
 478   GList *walk;
 479
 480   g_return_val_if_fail (GST_IS_TUNER (tuner), NULL);
 481   g_return_val_if_fail (channel != NULL, NULL);
 482
 483   walk = (GList *) gst_tuner_list_channels (tuner);
 484   while (walk) {
 485     if (strcmp (GST_TUNER_CHANNEL (walk->data)->label, channel) == 0)
 486       return GST_TUNER_CHANNEL (walk->data);
 487     walk = g_list_next (walk);
 488   }
 489   return NULL;
 490 }
 491
 492 /**
 493  * gst_tuner_channel_changed:
 494  * @tuner: A #GstTuner instance
 495  * @channel: A #GstTunerChannel instance
 496  *
 497  * Called by elements implementing the #GstTuner interface when the
 498  * current channel changes. Fires the #GstTuner::channel-changed signal.
 499  */
 500 void
 501 gst_tuner_channel_changed (GstTuner * tuner, GstTunerChannel * channel)
 502 {
 503   g_return_if_fail (GST_IS_TUNER (tuner));
 504   g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
 505
 506   g_signal_emit (G_OBJECT (tuner),
 507       gst_tuner_signals[CHANNEL_CHANGED], 0, channel);
 508 }
 509
 510 /**
 511  * gst_tuner_norm_changed:
 512  * @tuner: A #GstTuner instance
 513  * @norm: A #GstTunerNorm instance
 514  *
 515  * Called by elements implementing the #GstTuner interface when the
 516  * current norm changes. Fires the #GstTuner::norm-changed signal.
 517  *
 518  */
 519 void
 520 gst_tuner_norm_changed (GstTuner * tuner, GstTunerNorm * norm)
 521 {
 522   g_return_if_fail (GST_IS_TUNER (tuner));
 523   g_return_if_fail (GST_IS_TUNER_NORM (norm));
 524
 525   g_signal_emit (G_OBJECT (tuner), gst_tuner_signals[NORM_CHANGED], 0, norm);
 526 }
 527
 528 /**
 529  * gst_tuner_frequency_changed:
 530  * @tuner: A #GstTuner instance
 531  * @channel: The current #GstTunerChannel
 532  * @frequency: The new frequency setting
 533  *
 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
 537  * on the channel.
 538  */
 539 void
 540 gst_tuner_frequency_changed (GstTuner * tuner,
 541     GstTunerChannel * channel, gulong frequency)
 542 {
 543   g_return_if_fail (GST_IS_TUNER (tuner));
 544   g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
 545
 546   g_signal_emit (G_OBJECT (tuner),
 547       gst_tuner_signals[FREQUENCY_CHANGED], 0, channel, frequency);
 548
 549   g_signal_emit_by_name (G_OBJECT (channel), "frequency_changed", frequency);
 550 }
 551
 552 /**
 553  * gst_tuner_signal_changed:
 554  * @tuner: A #GstTuner instance
 555  * @channel: The current #GstTunerChannel
 556  * @signal: The new signal strength
 557  *
 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
 561  * the channel.
 562  */
 563 void
 564 gst_tuner_signal_changed (GstTuner * tuner,
 565     GstTunerChannel * channel, gint signal)
 566 {
 567   g_return_if_fail (GST_IS_TUNER (tuner));
 568   g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
 569
 570   g_signal_emit (G_OBJECT (tuner),
 571       gst_tuner_signals[SIGNAL_CHANGED], 0, channel, signal);
 572
 573   g_signal_emit_by_name (G_OBJECT (channel), "signal_changed", signal);
 574 }