gst_plugins_base/gst-libs/gst/interfaces/tuner.c
branchRCL_3
changeset 30 7e817e7e631c
parent 29 567bb019e3e3
equal deleted inserted replaced
29:567bb019e3e3 30:7e817e7e631c
    29 #include <string.h>
    29 #include <string.h>
    30 
    30 
    31 /**
    31 /**
    32  * SECTION:gsttuner
    32  * SECTION:gsttuner
    33  * @short_description: Interface for elements providing tuner operations
    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/
       
    61 #ifdef __SYMBIAN32__
       
    62 EXPORT_C
       
    63 #endif
       
    64 retrieved via the
       
    65  * gst_tuner_set_frequency() and gst_tuner_get_frequency() methods.
       
    66  * </listitem>
       
    67  * </itemizedlist>
       
    68  * </para>
       
    69  * <para>
       
    70  * Where applicable, the signal strength can be retrieved and/or monitored
       
    71  * via a signal.
       
    72  * </para>
       
    73  * </refsect2>
       
    74  */
    34  */
    75 
    35 
    76 enum
    36 enum
    77 {
    37 {
    78   NORM_CHANGED,
    38   NORM_CHANGED,
   121 gst_tuner_class_init (GstTunerClass * klass)
    81 gst_tuner_class_init (GstTunerClass * klass)
   122 {
    82 {
   123   static gboolean initialized = FALSE;
    83   static gboolean initialized = FALSE;
   124 
    84 
   125   if (!initialized) {
    85   if (!initialized) {
   126     /**
       
   127      * GstTuner::norm-changed:
       
   128      * @tuner: The element providing the GstTuner interface
       
   129      * @norm: The new configured norm.
       
   130      *
       
   131      * Reports that the current #GstTunerNorm has changed.
       
   132      */
       
   133     gst_tuner_signals[NORM_CHANGED] =
    86     gst_tuner_signals[NORM_CHANGED] =
   134         g_signal_new ("norm-changed",
    87         g_signal_new ("norm-changed",
   135         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
    88         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
   136         G_STRUCT_OFFSET (GstTunerClass, norm_changed),
    89         G_STRUCT_OFFSET (GstTunerClass, norm_changed),
   137         NULL, NULL,
    90         NULL, NULL,
   138         g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_TUNER_NORM);
    91         g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_TUNER_NORM);
   139     /**
       
   140      * GstTuner::channel-changed:
       
   141      * @tuner: The element providing the GstTuner interface
       
   142      * @channel: The new configured channel.
       
   143      *
       
   144      * Reports that the current #GstTunerChannel has changed.
       
   145      */
       
   146     gst_tuner_signals[CHANNEL_CHANGED] =
    92     gst_tuner_signals[CHANNEL_CHANGED] =
   147         g_signal_new ("channel-changed",
    93         g_signal_new ("channel-changed",
   148         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
    94         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
   149         G_STRUCT_OFFSET (GstTunerClass, channel_changed),
    95         G_STRUCT_OFFSET (GstTunerClass, channel_changed),
   150         NULL, NULL,
    96         NULL, NULL,
   151         g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
    97         g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1,
   152         GST_TYPE_TUNER_CHANNEL);
    98         GST_TYPE_TUNER_CHANNEL);
   153     /**
       
   154      * GstTuner::frequency-changed:
       
   155      * @tuner: The element providing the GstTuner interface
       
   156      * @frequency: The new frequency (an unsigned long)
       
   157      *
       
   158      * Reports that the current frequency has changed.
       
   159      */
       
   160     gst_tuner_signals[FREQUENCY_CHANGED] =
    99     gst_tuner_signals[FREQUENCY_CHANGED] =
   161         g_signal_new ("frequency-changed",
   100         g_signal_new ("frequency-changed",
   162         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
   101         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
   163         G_STRUCT_OFFSET (GstTunerClass, frequency_changed),
   102         G_STRUCT_OFFSET (GstTunerClass, frequency_changed),
   164         NULL, NULL,
   103         NULL, NULL,
   165         gst_interfaces_marshal_VOID__OBJECT_ULONG, G_TYPE_NONE, 2,
   104         gst_interfaces_marshal_VOID__OBJECT_ULONG, G_TYPE_NONE, 2,
   166         GST_TYPE_TUNER_CHANNEL, G_TYPE_ULONG);
   105         GST_TYPE_TUNER_CHANNEL, G_TYPE_ULONG);
   167     /**
       
   168      * GstTuner::signal-changed:
       
   169      * @tuner: The element providing the GstTuner interface
       
   170      * @channel: The current #GstTunerChannel
       
   171      * @signal: The new signal strength (an integer)
       
   172      *
       
   173      * Reports that the signal strength has changed.
       
   174      *
       
   175      * See Also: gst_tuner_signal_strength()
       
   176      */
       
   177     gst_tuner_signals[SIGNAL_CHANGED] =
   106     gst_tuner_signals[SIGNAL_CHANGED] =
   178         g_signal_new ("signal-changed",
   107         g_signal_new ("signal-changed",
   179         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
   108         GST_TYPE_TUNER, G_SIGNAL_RUN_LAST,
   180         G_STRUCT_OFFSET (GstTunerClass, signal_changed),
   109         G_STRUCT_OFFSET (GstTunerClass, signal_changed),
   181         NULL, NULL,
   110         NULL, NULL,
   201 
   130 
   202 /**
   131 /**
   203  * gst_tuner_list_channels:
   132  * gst_tuner_list_channels:
   204  * @tuner: the #GstTuner (a #GstElement) to get the channels from.
   133  * @tuner: the #GstTuner (a #GstElement) to get the channels from.
   205  *
   134  *
   206  * Retrieve a #GList of #GstTunerChannels available
   135  * Retrieve a list of channels (e.g. 'composite', 's-video', ...)
   207  * (e.g. 'composite', 's-video', ...) from the given tuner object.
   136  * from the given tuner object.
   208  *
   137  *
   209  * Returns: A list of channels available on this tuner. The list is
   138  * Returns: a list of channels available on this tuner.
   210  *          owned by the GstTuner and must not be freed.
   139  */
   211  */
   140 #ifdef __SYMBIAN32__
   212 #ifdef __SYMBIAN32__
   141 EXPORT_C
   213 EXPORT_C
   142 #endif
   214 #endif
   143 
   215 
   144 
   216 const GList *
   145 const GList *
   217 gst_tuner_list_channels (GstTuner * tuner)
   146 gst_tuner_list_channels (GstTuner * tuner)
   218 {
   147 {
   219   GstTunerClass *klass;
   148   GstTunerClass *klass;
   252     klass->set_channel (tuner, channel);
   181     klass->set_channel (tuner, channel);
   253   }
   182   }
   254 }
   183 }
   255 
   184 
   256 /**
   185 /**
   257  * gst_tuner_get_channel:
   186  * gst_Tuner_get_channel:
   258  * @tuner: the #GstTuner (a #GstElement) to get the current channel from.
   187  * @tuner: the #GstTuner (a #GstElement) to get the current channel from.
   259  *
   188  *
   260  * Retrieve the current channel from the tuner.
   189  * Retrieve the current channel from the tuner.
   261  *
   190  *
   262  * Returns: the current channel of the tuner object.
   191  * Returns: the current channel of the tuner object.
   280 
   209 
   281   return NULL;
   210   return NULL;
   282 }
   211 }
   283 
   212 
   284 /**
   213 /**
   285  * gst_tuner_list_norms:
   214  * gst_tuner_get_norms_list:
   286  * @tuner: the #GstTuner (*a #GstElement) to get the list of norms from.
   215  * @tuner: the #GstTuner (*a #GstElement) to get the list of norms from.
   287  *
   216  *
   288  * Retrieve a GList of available #GstTunerNorm settings for the currently
   217  * Retrieve a list of available norms on the currently tuned channel
   289  * tuned channel on the given tuner object.
   218  * from the given tuner object.
   290  *
   219  *
   291  * Returns: A list of norms available on the current channel for this
   220  * Returns: A list of norms available on the current channel for this
   292  *          tuner object. The list is owned by the GstTuner and must not
   221  *          tuner object.
   293  *          be freed.
       
   294  */
   222  */
   295 #ifdef __SYMBIAN32__
   223 #ifdef __SYMBIAN32__
   296 EXPORT_C
   224 EXPORT_C
   297 #endif
   225 #endif
   298 
   226 
   366   return NULL;
   294   return NULL;
   367 }
   295 }
   368 
   296 
   369 /**
   297 /**
   370  * gst_tuner_set_frequency:
   298  * gst_tuner_set_frequency:
   371  * @tuner: The #Gsttuner (a #GstElement) that owns the given channel.
   299  * @tuner: the #Gsttuner (a #GstElement) that owns the given channel.
   372  * @channel: The #GstTunerChannel to set the frequency on.
   300  * @channel: the #GstTunerChannel to set the frequency on.
   373  * @frequency: The frequency to tune in to.
   301  * @frequency: the frequency to tune in to.
   374  *
   302  *
   375  * Sets a tuning frequency on the given tuner/channel. Note that this
   303  * Sets a tuning frequency on the given tuner/channel. Note that this
   376  * requires the given channel to be a "tuning" channel, which can be
   304  * requires the given channel to be a "tuning" channel, which can be
   377  * checked using GST_TUNER_CHANNEL_HAS_FLAG (), with the proper flag
   305  * checked using GST_TUNER_CHANNEL_HAS_FLAG (), with the proper flag
   378  * being GST_TUNER_CHANNEL_FREQUENCY.
   306  * being GST_TUNER_CHANNEL_FREQUENCY.
   379  *
   307  */
   380  * The frequency is in Hz, with minimum steps indicated by the 
   308 #ifdef __SYMBIAN32__
   381  * frequency_multiplicator provided in the #GstTunerChannel. The
   309 EXPORT_C
   382  * valid range is provided in the min_frequency and max_frequency properties
   310 #endif
   383  * of the #GstTunerChannel.
   311 
   384  */
       
   385 #ifdef __SYMBIAN32__
       
   386 EXPORT_C
       
   387 #endif
       
   388 
   312 
   389 void
   313 void
   390 gst_tuner_set_frequency (GstTuner * tuner,
   314 gst_tuner_set_frequency (GstTuner * tuner,
   391     GstTunerChannel * channel, gulong frequency)
   315     GstTunerChannel * channel, gulong frequency)
   392 {
   316 {
   403   }
   327   }
   404 }
   328 }
   405 
   329 
   406 /**
   330 /**
   407  * gst_tuner_get_frequency:
   331  * gst_tuner_get_frequency:
   408  * @tuner: The #GstTuner (a #GstElement) that owns the given channel.
   332  * @tuner: the #GstTuner (a #GstElement) that owns the given channel.
   409  * @channel: The #GstTunerChannel to retrieve the frequency from.
   333  * @channel: the #GstTunerChannel to retrieve the frequency from.
   410  *
   334  *
   411  * Retrieve the current frequency from the given channel. As for
   335  * Retrieve the current frequency from the given channel. The same
   412  * gst_tuner_set_frequency(), the #GstTunerChannel must support frequency
   336  * applies as for set_frequency (): check the flag.
   413  * operations, as indicated by the GST_TUNER_CHANNEL_FREQUENCY flag.
   337  *
   414  *
   338  * Returns: the current frequency, or 0 on error.
   415  * Returns: The current frequency, or 0 on error.
       
   416  */
   339  */
   417 #ifdef __SYMBIAN32__
   340 #ifdef __SYMBIAN32__
   418 EXPORT_C
   341 EXPORT_C
   419 #endif
   342 #endif
   420 
   343 
   437 
   360 
   438   return 0;
   361   return 0;
   439 }
   362 }
   440 
   363 
   441 /**
   364 /**
   442  * gst_tuner_signal_strength:
   365  * gst_tuner_get_signal_strength:
   443  * @tuner: the #GstTuner (a #GstElement) that owns the given channel.
   366  * @tuner: the #GstTuner (a #GstElement) that owns the given channel.
   444  * @channel: the #GstTunerChannel to get the signal strength from.
   367  * @channel: the #GstTunerChannel to get the signal strength from.
   445  *
   368  *
   446  * Get the strength of the signal on this channel. Note that this
   369  * get the strength of the signal on this channel. Note that this
   447  * requires the current channel to be a "tuning" channel, i.e. a
   370  * requires the current channel to be a "tuning" channel, e.g. a
   448  * channel on which frequency can be set. This can be checked using
   371  * channel on which frequency can be set. This can be checked using
   449  * GST_TUNER_CHANNEL_HAS_FLAG (), and the appropriate flag to check
   372  * GST_TUNER_CHANNEL_HAS_FLAG (), and the appropriate flag to check
   450  * for is GST_TUNER_CHANNEL_FREQUENCY.
   373  * for is GST_TUNER_CHANNEL_FREQUENCY.
   451  *
   374  *
   452  * The valid range of the signal strength is indicated in the 
   375  * Returns: signal strength, or 0 on error.
   453  * min_signal and max_signal properties of the #GstTunerChannel.
   376  */
   454  *
   377 #ifdef __SYMBIAN32__
   455  * Returns: Signal strength, or 0 on error.
   378 EXPORT_C
   456  */
   379 #endif
   457 #ifdef __SYMBIAN32__
   380 
   458 EXPORT_C
       
   459 #endif
       
   460 
   381 
   461 gint
   382 gint
   462 gst_tuner_signal_strength (GstTuner * tuner, GstTunerChannel * channel)
   383 gst_tuner_signal_strength (GstTuner * tuner, GstTunerChannel * channel)
   463 {
   384 {
   464   GstTunerClass *klass;
   385   GstTunerClass *klass;
   473     return klass->signal_strength (tuner, channel);
   394     return klass->signal_strength (tuner, channel);
   474   }
   395   }
   475 
   396 
   476   return 0;
   397   return 0;
   477 }
   398 }
   478 
   399 #ifdef __SYMBIAN32__
   479 /**
   400 EXPORT_C
   480  * gst_tuner_find_norm_by_name:
   401 #endif
   481  * @tuner: A #GstTuner instance
   402 
   482  * @norm: A string containing the name of a #GstTunerNorm
       
   483  * 
       
   484  * Look up a #GstTunerNorm by name.
       
   485  *
       
   486  * Returns: A #GstTunerNorm, or NULL if no norm with the provided name
       
   487  * is available.
       
   488  */
       
   489 #ifdef __SYMBIAN32__
       
   490 EXPORT_C
       
   491 #endif
       
   492 
   403 
   493 GstTunerNorm *
   404 GstTunerNorm *
   494 gst_tuner_find_norm_by_name (GstTuner * tuner, gchar * norm)
   405 gst_tuner_find_norm_by_name (GstTuner * tuner, gchar * norm)
   495 {
   406 {
   496   GList *walk;
   407   GList *walk;
   504       return GST_TUNER_NORM (walk->data);
   415       return GST_TUNER_NORM (walk->data);
   505     walk = g_list_next (walk);
   416     walk = g_list_next (walk);
   506   }
   417   }
   507   return NULL;
   418   return NULL;
   508 }
   419 }
   509 
   420 #ifdef __SYMBIAN32__
   510 /**
   421 EXPORT_C
   511  * gst_tuner_find_channel_by_name:
   422 #endif
   512  * @tuner: A #GstTuner instance
   423 
   513  * @channel: A string containing the name of a #GstTunerChannel
       
   514  * 
       
   515  * Look up a #GstTunerChannel by name.
       
   516  *
       
   517  * Returns: A #GstTunerChannel, or NULL if no channel with the provided name
       
   518  * is available.
       
   519  */
       
   520 #ifdef __SYMBIAN32__
       
   521 EXPORT_C
       
   522 #endif
       
   523 
   424 
   524 GstTunerChannel *
   425 GstTunerChannel *
   525 gst_tuner_find_channel_by_name (GstTuner * tuner, gchar * channel)
   426 gst_tuner_find_channel_by_name (GstTuner * tuner, gchar * channel)
   526 {
   427 {
   527   GList *walk;
   428   GList *walk;
   535       return GST_TUNER_CHANNEL (walk->data);
   436       return GST_TUNER_CHANNEL (walk->data);
   536     walk = g_list_next (walk);
   437     walk = g_list_next (walk);
   537   }
   438   }
   538   return NULL;
   439   return NULL;
   539 }
   440 }
   540 
   441 #ifdef __SYMBIAN32__
   541 /**
   442 EXPORT_C
   542  * gst_tuner_channel_changed:
   443 #endif
   543  * @tuner: A #GstTuner instance
   444 
   544  * @channel: A #GstTunerChannel instance
       
   545  *
       
   546  * Called by elements implementing the #GstTuner interface when the
       
   547  * current channel changes. Fires the #GstTuner::channel-changed signal.
       
   548  */
       
   549 #ifdef __SYMBIAN32__
       
   550 EXPORT_C
       
   551 #endif
       
   552 
   445 
   553 void
   446 void
   554 gst_tuner_channel_changed (GstTuner * tuner, GstTunerChannel * channel)
   447 gst_tuner_channel_changed (GstTuner * tuner, GstTunerChannel * channel)
   555 {
   448 {
   556   g_return_if_fail (GST_IS_TUNER (tuner));
   449   g_return_if_fail (GST_IS_TUNER (tuner));
   557   g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
   450   g_return_if_fail (GST_IS_TUNER_CHANNEL (channel));
   558 
   451 
   559   g_signal_emit (G_OBJECT (tuner),
   452   g_signal_emit (G_OBJECT (tuner),
   560       gst_tuner_signals[CHANNEL_CHANGED], 0, channel);
   453       gst_tuner_signals[CHANNEL_CHANGED], 0, channel);
   561 }
   454 }
   562 
   455 #ifdef __SYMBIAN32__
   563 /**
   456 EXPORT_C
   564  * gst_tuner_norm_changed:
   457 #endif
   565  * @tuner: A #GstTuner instance
   458 
   566  * @norm: A #GstTunerNorm instance
       
   567  *
       
   568  * Called by elements implementing the #GstTuner interface when the
       
   569  * current norm changes. Fires the #GstTuner::norm-changed signal.
       
   570  * 
       
   571  */
       
   572 #ifdef __SYMBIAN32__
       
   573 EXPORT_C
       
   574 #endif
       
   575 
   459 
   576 void
   460 void
   577 gst_tuner_norm_changed (GstTuner * tuner, GstTunerNorm * norm)
   461 gst_tuner_norm_changed (GstTuner * tuner, GstTunerNorm * norm)
   578 {
   462 {
   579   g_return_if_fail (GST_IS_TUNER (tuner));
   463   g_return_if_fail (GST_IS_TUNER (tuner));
   580   g_return_if_fail (GST_IS_TUNER_NORM (norm));
   464   g_return_if_fail (GST_IS_TUNER_NORM (norm));
   581 
   465 
   582   g_signal_emit (G_OBJECT (tuner), gst_tuner_signals[NORM_CHANGED], 0, norm);
   466   g_signal_emit (G_OBJECT (tuner), gst_tuner_signals[NORM_CHANGED], 0, norm);
   583 }
   467 }
   584 
   468 #ifdef __SYMBIAN32__
   585 /**
   469 EXPORT_C
   586  * gst_tuner_frequency_changed:
   470 #endif
   587  * @tuner: A #GstTuner instance
   471 
   588  * @channel: The current #GstTunerChannel
       
   589  * @frequency: The new frequency setting
       
   590  *
       
   591  * Called by elements implementing the #GstTuner interface when the
       
   592  * configured frequency changes. Fires the #GstTuner::frequency-changed
       
   593  * signal on the tuner, and the #GstTunerChannel::frequency-changed signal
       
   594  * on the channel.
       
   595  */
       
   596 #ifdef __SYMBIAN32__
       
   597 EXPORT_C
       
   598 #endif
       
   599 
   472 
   600 void
   473 void
   601 gst_tuner_frequency_changed (GstTuner * tuner,
   474 gst_tuner_frequency_changed (GstTuner * tuner,
   602     GstTunerChannel * channel, gulong frequency)
   475     GstTunerChannel * channel, gulong frequency)
   603 {
   476 {
   607   g_signal_emit (G_OBJECT (tuner),
   480   g_signal_emit (G_OBJECT (tuner),
   608       gst_tuner_signals[FREQUENCY_CHANGED], 0, channel, frequency);
   481       gst_tuner_signals[FREQUENCY_CHANGED], 0, channel, frequency);
   609 
   482 
   610   g_signal_emit_by_name (G_OBJECT (channel), "frequency_changed", frequency);
   483   g_signal_emit_by_name (G_OBJECT (channel), "frequency_changed", frequency);
   611 }
   484 }
   612 
   485 #ifdef __SYMBIAN32__
   613 /**
   486 EXPORT_C
   614  * gst_tuner_signal_changed:
   487 #endif
   615  * @tuner: A #GstTuner instance
   488 
   616  * @channel: The current #GstTunerChannel
       
   617  * @signal: The new signal strength
       
   618  *
       
   619  * Called by elements implementing the #GstTuner interface when the
       
   620  * incoming signal strength changes. Fires the #GstTuner::signal-changed
       
   621  * signal on the tuner and the #GstTunerChannel::signal-changed signal on 
       
   622  * the channel.
       
   623  */
       
   624 #ifdef __SYMBIAN32__
       
   625 EXPORT_C
       
   626 #endif
       
   627 
   489 
   628 void
   490 void
   629 gst_tuner_signal_changed (GstTuner * tuner,
   491 gst_tuner_signal_changed (GstTuner * tuner,
   630     GstTunerChannel * channel, gint signal)
   492     GstTunerChannel * channel, gint signal)
   631 {
   493 {