gsttuner

gsttuner — Interface for elements providing tuner operations

Functions

Signals

void channel-changed Run Last
void frequency-changed Run Last
void norm-changed Run Last
void signal-changed Run Last

Types and Values

Object Hierarchy

    GInterface
    ╰── GstTuner

Prerequisites

GstTuner requires GstImplementsInterface and GstElement.

Includes

#include <gst/interfaces/tuner.h>

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.

Functions

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.

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

tuner

A GstTuner instance

 

channel

The current GstTunerChannel

 

signal

The new signal strength

 

Types and Values

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.

Members

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

 

Signal Details

The “channel-changed” signal

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

Reports that the current GstTunerChannel has changed.

Parameters

tuner

The element providing the GstTuner interface

 

channel

The new configured channel.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “frequency-changed” signal

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

Reports that the current frequency has changed.

Parameters

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.

 

Flags: Run Last


The “norm-changed” signal

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

Reports that the current GstTunerNorm has changed.

Parameters

tuner

The element providing the GstTuner interface

 

norm

The new configured norm.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “signal-changed” signal

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

Reports that the signal strength has changed.

See Also: gst_tuner_signal_strength()

Parameters

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.

 

Flags: Run Last