gsttuner

gsttuner — Interface for elements providing tuner operations

Synopsis

#include <gst/interfaces/tuner.h>

                    GstTuner;
struct              GstTunerClass;
const GList *       gst_tuner_list_channels             (GstTuner *tuner);
GstTunerChannel *   gst_tuner_get_channel               (GstTuner *tuner);
void                gst_tuner_set_channel               (GstTuner *tuner,
                                                         GstTunerChannel *channel);
const GList *       gst_tuner_list_norms                (GstTuner *tuner);
GstTunerNorm *      gst_tuner_get_norm                  (GstTuner *tuner);
void                gst_tuner_set_norm                  (GstTuner *tuner,
                                                         GstTunerNorm *norm);
gulong              gst_tuner_get_frequency             (GstTuner *tuner,
                                                         GstTunerChannel *channel);
void                gst_tuner_set_frequency             (GstTuner *tuner,
                                                         GstTunerChannel *channel,
                                                         gulong frequency);
gint                gst_tuner_signal_strength           (GstTuner *tuner,
                                                         GstTunerChannel *channel);
GstTunerNorm *      gst_tuner_find_norm_by_name         (GstTuner *tuner,
                                                         gchar *norm);
GstTunerChannel *   gst_tuner_find_channel_by_name      (GstTuner *tuner,
                                                         gchar *channel);
void                gst_tuner_channel_changed           (GstTuner *tuner,
                                                         GstTunerChannel *channel);
void                gst_tuner_norm_changed              (GstTuner *tuner,
                                                         GstTunerNorm *norm);
void                gst_tuner_frequency_changed         (GstTuner *tuner,
                                                         GstTunerChannel *channel,
                                                         gulong frequency);
void                gst_tuner_signal_changed            (GstTuner *tuner,
                                                         GstTunerChannel *channel,
                                                         gint signal);

Object Hierarchy

  GInterface
   +----GstTuner

Prerequisites

GstTuner requires GstImplementsInterface and GstElement.

Signals

  "channel-changed"                                : Run Last
  "frequency-changed"                              : Run Last
  "norm-changed"                                   : Run Last
  "signal-changed"                                 : Run Last

Description

The GstTuner interface is provided by elements that have the ability to tune into multiple input signals, for example TV or radio capture cards.

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.

That said, the GstTuner interface functions are biased toward the TV capture scenario.

The general parameters provided are for configuration are:

  • Selection of a current GstTunerChannel. The current channel represents the input source (e.g. Composite, S-Video etc for TV capture).
  • 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.
  • 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/retrieved via the gst_tuner_set_frequency() and gst_tuner_get_frequency() methods.

Where applicable, the signal strength can be retrieved and/or monitored via a signal.

Details

GstTuner

typedef struct _GstTuner GstTuner;

struct GstTunerClass

struct GstTunerClass {
  GTypeInterface klass;

  /* virtual functions */
  const GList * (* list_channels)   (GstTuner        *tuner);
  void          (* set_channel)     (GstTuner        *tuner,
                                     GstTunerChannel *channel);
  GstTunerChannel *
                (* get_channel)     (GstTuner        *tuner);

  const GList * (* list_norms)      (GstTuner        *tuner);
  void          (* set_norm)        (GstTuner        *tuner,
                                     GstTunerNorm    *norm);
  GstTunerNorm *(* get_norm)        (GstTuner        *tuner);

  void          (* set_frequency)   (GstTuner        *tuner,
                                     GstTunerChannel *channel,
                                     gulong           frequency);
  gulong        (* get_frequency)   (GstTuner        *tuner,
                                     GstTunerChannel *channel);
  gint          (* signal_strength) (GstTuner        *tuner,
                                     GstTunerChannel *channel);

  /* signals */
  void (*channel_changed)   (GstTuner        *tuner,
                             GstTunerChannel *channel);
  void (*norm_changed)      (GstTuner        *tuner,
                             GstTunerNorm    *norm);
  void (*frequency_changed) (GstTuner        *tuner,
                             GstTunerChannel *channel,
                             gulong           frequency);
  void (*signal_changed)    (GstTuner        *tuner,
                             GstTunerChannel *channel,
                             gint             signal);
};

Tuner interface.

GTypeInterface klass;

the parent interface

list_channels ()

list available channels

set_channel ()

set to a channel

get_channel ()

return the current channel

list_norms ()

list available norms

set_norm ()

set a norm

get_norm ()

return the current norm

set_frequency ()

set the frequency

get_frequency ()

return the current frequency

signal_strength ()

get the signal strength

channel_changed ()

default handler for channel changed notification

norm_changed ()

default handler for norm changed notification

frequency_changed ()

default handler for frequency changed notification

signal_changed ()

default handler for signal-strength changed notification

gst_tuner_list_channels ()

const GList *       gst_tuner_list_channels             (GstTuner *tuner);

Retrieve a GList of GstTunerChannels available (e.g. 'composite', 's-video', ...) from the given tuner object.

tuner :

the GstTuner (a GstElement) to get the channels from.

Returns :

A list of channels available on this tuner. The list is owned by the GstTuner and must not be freed.

gst_tuner_get_channel ()

GstTunerChannel *   gst_tuner_get_channel               (GstTuner *tuner);

Retrieve the current channel from the tuner.

tuner :

the GstTuner (a GstElement) to get the current channel from.

Returns :

the current channel of the tuner object.

gst_tuner_set_channel ()

void                gst_tuner_set_channel               (GstTuner *tuner,
                                                         GstTunerChannel *channel);

Tunes the object to the given channel, which should be one of the channels returned by gst_tuner_list_channels().

tuner :

the GstTuner (a GstElement) that owns the channel.

channel :

the channel to tune to.

gst_tuner_list_norms ()

const GList *       gst_tuner_list_norms                (GstTuner *tuner);

Retrieve a GList of available GstTunerNorm settings for the currently tuned channel on the given tuner object.

tuner :

the GstTuner (*a GstElement) to get the list of norms from.

Returns :

A list of norms available on the current channel for this tuner object. The list is owned by the GstTuner and must not be freed.

gst_tuner_get_norm ()

GstTunerNorm *      gst_tuner_get_norm                  (GstTuner *tuner);

Get the current video norm from the given tuner object for the currently selected channel.

tuner :

the GstTuner (a GstElement) to get the current norm from.

Returns :

the current norm.

gst_tuner_set_norm ()

void                gst_tuner_set_norm                  (GstTuner *tuner,
                                                         GstTunerNorm *norm);

Changes the video norm on this tuner to the given norm, which should be one of the norms returned by gst_tuner_list_norms().

tuner :

the GstTuner (a GstElement) to set the norm on.

norm :

the norm to use for the current channel.

gst_tuner_get_frequency ()

gulong              gst_tuner_get_frequency             (GstTuner *tuner,
                                                         GstTunerChannel *channel);

Retrieve the current frequency from the given channel. As for gst_tuner_set_frequency(), the GstTunerChannel must support frequency operations, as indicated by the GST_TUNER_CHANNEL_FREQUENCY flag.

tuner :

The GstTuner (a GstElement) that owns the given channel.

channel :

The GstTunerChannel to retrieve the frequency from.

Returns :

The current frequency, or 0 on error.

gst_tuner_set_frequency ()

void                gst_tuner_set_frequency             (GstTuner *tuner,
                                                         GstTunerChannel *channel,
                                                         gulong frequency);

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.

The frequency is in Hz, with minimum steps indicated by the frequency_multiplicator provided in the GstTunerChannel. The valid range is provided in the min_frequency and max_frequency properties of the GstTunerChannel.

tuner :

The GstTuner (a GstElement) that owns the given channel.

channel :

The GstTunerChannel to set the frequency on.

frequency :

The frequency to tune in to.

gst_tuner_signal_strength ()

gint                gst_tuner_signal_strength           (GstTuner *tuner,
                                                         GstTunerChannel *channel);

Get the strength of the signal on this channel. Note that this 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.

The valid range of the signal strength is indicated in the min_signal and max_signal properties of the GstTunerChannel.

tuner :

the GstTuner (a GstElement) that owns the given channel.

channel :

the GstTunerChannel to get the signal strength from.

Returns :

Signal strength, or 0 on error.

gst_tuner_find_norm_by_name ()

GstTunerNorm *      gst_tuner_find_norm_by_name         (GstTuner *tuner,
                                                         gchar *norm);

Look up a GstTunerNorm by name.

tuner :

A GstTuner instance

norm :

A string containing the name of a GstTunerNorm

Returns :

A GstTunerNorm, or NULL if no norm with the provided name is available.

gst_tuner_find_channel_by_name ()

GstTunerChannel *   gst_tuner_find_channel_by_name      (GstTuner *tuner,
                                                         gchar *channel);

Look up a GstTunerChannel by name.

tuner :

A GstTuner instance

channel :

A string containing the name of a GstTunerChannel

Returns :

A GstTunerChannel, or NULL if no channel with the provided name is available.

gst_tuner_channel_changed ()

void                gst_tuner_channel_changed           (GstTuner *tuner,
                                                         GstTunerChannel *channel);

Called by elements implementing the GstTuner interface when the current channel changes. Fires the "channel-changed" signal.

tuner :

A GstTuner instance

channel :

A GstTunerChannel instance

gst_tuner_norm_changed ()

void                gst_tuner_norm_changed              (GstTuner *tuner,
                                                         GstTunerNorm *norm);

Called by elements implementing the GstTuner interface when the current norm changes. Fires the "norm-changed" signal.

tuner :

A GstTuner instance

norm :

A GstTunerNorm instance

gst_tuner_frequency_changed ()

void                gst_tuner_frequency_changed         (GstTuner *tuner,
                                                         GstTunerChannel *channel,
                                                         gulong frequency);

Called by elements implementing the GstTuner interface when the configured frequency changes. Fires the "frequency-changed" signal on the tuner, and the "frequency-changed" signal on the channel.

tuner :

A GstTuner instance

channel :

The current GstTunerChannel

frequency :

The new frequency setting

gst_tuner_signal_changed ()

void                gst_tuner_signal_changed            (GstTuner *tuner,
                                                         GstTunerChannel *channel,
                                                         gint signal);

Called by elements implementing the GstTuner interface when the incoming signal strength changes. Fires the "signal-changed" signal on the tuner and the "signal-changed" signal on the channel.

tuner :

A GstTuner instance

channel :

The current GstTunerChannel

signal :

The new signal strength

Signal Details

The "channel-changed" signal

void                user_function                      (GstTuner        *tuner,
                                                        GstTunerChannel *channel,
                                                        gpointer         user_data)      : Run Last

Reports that the current GstTunerChannel has changed.

tuner :

The element providing the GstTuner interface

channel :

The new configured channel.

user_data :

user data set when the signal handler was connected.

The "frequency-changed" signal

void                user_function                      (GstTuner        *tuner,
                                                        GstTunerChannel *frequency,
                                                        gulong           arg2,
                                                        gpointer         user_data)      : Run Last

Reports that the current frequency has changed.

tuner :

The element providing the GstTuner interface

frequency :

The new frequency (an unsigned long)

user_data :

user data set when the signal handler was connected.

The "norm-changed" signal

void                user_function                      (GstTuner     *tuner,
                                                        GstTunerNorm *norm,
                                                        gpointer      user_data)      : Run Last

Reports that the current GstTunerNorm has changed.

tuner :

The element providing the GstTuner interface

norm :

The new configured norm.

user_data :

user data set when the signal handler was connected.

The "signal-changed" signal

void                user_function                      (GstTuner        *tuner,
                                                        GstTunerChannel *channel,
                                                        gint             signal,
                                                        gpointer         user_data)      : Run Last

Reports that the signal strength has changed.

See Also: gst_tuner_signal_strength()

tuner :

The element providing the GstTuner interface

channel :

The current GstTunerChannel

signal :

The new signal strength (an integer)

user_data :

user data set when the signal handler was connected.