Commit 7c1c3a17 authored by Ronald S. Bultje's avatar Ronald S. Bultje
Browse files

gst-libs/gst/: Add gtk-doc style comments. Also fix a function name.

Original commit message from CVS:
2004-01-25  Ronald Bultje  <rbultje@ronald.bitfreak.net>

* gst-libs/gst/mixer/mixer.c:
* gst-libs/gst/propertyprobe/propertyprobe.c:
* gst-libs/gst/tuner/tuner.c: (gst_tuner_find_norm_by_name),
(gst_tuner_find_channel_by_name):
* gst-libs/gst/tuner/tuner.h:
Add gtk-doc style comments. Also fix a function name.
parent f0e41ec9
2004-01-25 Ronald Bultje <rbultje@ronald.bitfreak.net>
* gst-libs/gst/mixer/mixer.c:
* gst-libs/gst/propertyprobe/propertyprobe.c:
* gst-libs/gst/tuner/tuner.c: (gst_tuner_find_norm_by_name),
(gst_tuner_find_channel_by_name):
* gst-libs/gst/tuner/tuner.h:
Add gtk-doc style comments. Also fix a function name.
2004-01-25 Ronald Bultje <rbultje@ronald.bitfreak.net>
* ext/divx/gstdivxdec.c: (gst_divxdec_init),
......
......@@ -106,6 +106,18 @@ gst_mixer_class_init (GstMixerClass *klass)
klass->set_record = NULL;
}
/**
*agst_mixer_list_tracks:
* @mixer: the #GstMixer (a #GstElement) to get the tracks from.
*
* Returns a list of avialable tracks for this mixer/element. Note
* that it is allowed for sink (output) elements to only provide
* the output tracks in this list. Likewise, for sources (inputs),
* it is allowed to only provide input elements in this list.
*
* Returns: A #GList consisting of zero or more #GstMixerTracks.
*/
const GList *
gst_mixer_list_tracks (GstMixer *mixer)
{
......@@ -118,6 +130,21 @@ gst_mixer_list_tracks (GstMixer *mixer)
return NULL;
}
/**
* gst_mixer_set_volume:
* @mixer: The #GstMixer (a #GstElement) that owns the track.
* @track: The #GstMixerTrack to set the volume on.
* @volumes: an array of integers (of size track->num_channels)
* that gives the wanted volume for each channel in
* this track.
*
* Sets the volume on each channel in a track. Short note about
* naming: a track is defined as one separate stream owned by
* the mixer/element, such as 'Line-in' or 'Microphone'. A
* channel is said to be a mono-stream inside this track. A
* stereo track thus contains two channels.
*/
void
gst_mixer_set_volume (GstMixer *mixer,
GstMixerTrack *track,
......@@ -130,6 +157,17 @@ gst_mixer_set_volume (GstMixer *mixer,
}
}
/*
* gst_mixer_get_volume:
* @mixer: the #GstMixer (a #GstElement) that owns the track
* @track: the GstMixerTrack to get the volume from.
* @volumes: a pre-allocated array of integers (of size
* track->num_channels) to store the current volume
* of each channel in the given track in.
*
* Get the current volume(s) on the given track.
*/
void
gst_mixer_get_volume (GstMixer *mixer,
GstMixerTrack *track,
......@@ -148,6 +186,17 @@ gst_mixer_get_volume (GstMixer *mixer,
}
}
/**
* gst_mixer_set_mute:
* @mixer: the #GstMixer (a #GstElement) that owns the track.
* @track: the #GstMixerTrack to operate on.
* @mute: a boolean value indicating whether to turn on or off
* muting.
*
* Mutes or unmutes the given channel. To find out whether a
* track is currently muted, use GST_MIXER_TRACK_HAS_FLAG ().
*/
void
gst_mixer_set_mute (GstMixer *mixer,
GstMixerTrack *track,
......@@ -160,6 +209,19 @@ gst_mixer_set_mute (GstMixer *mixer,
}
}
/**
* gst_mixer_set_record:
* @mixer: The #GstMixer (a #GstElement) that owns the track.
* @track: the #GstMixerTrack to operate on.
* @record: a boolean value that indicates whether to turn on
* or off recording.
*
* Enables or disables recording on the given track. Note that
* this is only possible on input tracks, not on output tracks
* (see GST_MIXER_TRACK_HAS_FLAG () and the GST_MIXER_TRACK_INPUT
* flag).
*/
void
gst_mixer_set_record (GstMixer *mixer,
GstMixerTrack *track,
......
......@@ -82,6 +82,16 @@ gst_property_probe_iface_init (GstPropertyProbeInterface *iface)
iface->get_values = NULL;
}
/**
* gst_property_probe_get_properties:
* @probe: the #GstPropertyProbe to get the properties for.
*
* Get a list of properties for which probing is supported.
*
* Returns the list of properties for which probing is supported
* by this element.
*/
const GList *
gst_property_probe_get_properties (GstPropertyProbe *probe)
{
......@@ -133,6 +143,18 @@ gst_property_probe_probe_property (GstPropertyProbe *probe,
iface->probe_property (probe, pspec->param_id, pspec);
}
/**
* gst_property_probe_probe_property_name:
* @probe: the #GstPropertyProbe to check.
* @name: name of the property to return.
*
* Returns the #GParamSpec for the given property. It's similar to
* g_object_class_find_property (), except that this function only
* takes "probe'able" properties into account.
*
* Returns: the #GParamSpec that belongs to the given property.
*/
void
gst_property_probe_probe_property_name (GstPropertyProbe *probe,
const gchar *name)
......@@ -151,6 +173,20 @@ gst_property_probe_probe_property_name (GstPropertyProbe *probe,
gst_property_probe_probe_property (probe, pspec);
}
/**
* gst_property_probe_needs_probe:
* @probe: the #GstPropertyProbe object to which the given property belongs.
* @pspec: a #GParamSpec that identifies the property to check.
*
* Checks whether a property needs a probe. This might be because
* the property wasn't initialized before, or because host setup
* changed. This might be, for example, because a new device was
* added, and thus device probing needs to be refreshed to display
* the new device.
*
* Returns: TRUE if the property needs a new probe, FALSE if not.
*/
gboolean
gst_property_probe_needs_probe (GstPropertyProbe *probe,
const GParamSpec *pspec)
......@@ -168,6 +204,16 @@ gst_property_probe_needs_probe (GstPropertyProbe *probe,
return FALSE;
}
/**
* gst_property_probe_needs_probe_name:
* @probe: the #GstPropertyProbe object to which the given property belongs.
* @name: the name of the property to check.
*
* Same as gst_property_probe_needs_probe ().
*
* Returns: TRUE if the property needs a new probe, FALSE if not.
*/
gboolean
gst_property_probe_needs_probe_name (GstPropertyProbe *probe,
const gchar *name)
......@@ -185,6 +231,17 @@ gst_property_probe_needs_probe_name (GstPropertyProbe *probe,
return gst_property_probe_needs_probe (probe, pspec);
}
/**
* gst_property_probe_get_values:
* @probe: the #GstPropertyProbe object.
* @pspec: the #GParamSpec property identifier.
*
* Gets the possible (probed) values for the given property,
* requires the property to have been probed before.
*
* Returns: A list of valid values for the given property.
*/
GValueArray *
gst_property_probe_get_values (GstPropertyProbe *probe,
......@@ -203,6 +260,16 @@ gst_property_probe_get_values (GstPropertyProbe *probe,
return NULL;
}
/**
* gst_property_probe_get_values_name:
* @probe: the #GstPropertyProbe object.
* @name: the name of the property to get values for.
*
* Same as gst_property_probe_get_values ().
*
* Returns: A list of valid values for the given property.
*/
GValueArray *
gst_property_probe_get_values_name (GstPropertyProbe *probe,
const gchar *name)
......@@ -221,6 +288,17 @@ gst_property_probe_get_values_name (GstPropertyProbe *probe,
return gst_property_probe_get_values (probe, pspec);
}
/**
* gst_property_probe_probe_and_get_values:
* @probe: the #GstPropertyProbe object.
* @pspec: The #GParamSpec property identifier.
*
* Check whether the given property requires a new probe. If so,
* fo the probe. After that, retrieve a value list. Meant as a
* utility function that wraps the above functions.
*
* Return: the list of valid values for this property.
*/
GValueArray *
gst_property_probe_probe_and_get_values (GstPropertyProbe *probe,
......@@ -239,6 +317,16 @@ gst_property_probe_probe_and_get_values (GstPropertyProbe *probe,
return gst_property_probe_get_values (probe, pspec);
}
/**
* gst_property_probe_probe_and_get_values_name:
* @probe: the #GstPropertyProbe object.
* @name: the name of the property to get values for.
*
* Same as gst_property_probe_probe_and_get_values ().
*
* Return: the list of valid values for this property.
*/
GValueArray *
gst_property_probe_probe_and_get_values_name (GstPropertyProbe *probe,
const gchar *name)
......
......@@ -120,6 +120,16 @@ gst_tuner_class_init (GstTunerClass *klass)
klass->signal_strength = NULL;
}
/**
* gst_tuner_list_channels:
* @tuner: the #GstTuner (a #GstElement) to get the channels from.
*
* Retrieve a list of channels (e.g. 'composite', 's-video', ...)
* from the given tuner object.
*
* Returns: a list of channels available on this tuner.
*/
const GList *
gst_tuner_list_channels (GstTuner *tuner)
{
......@@ -132,6 +142,14 @@ gst_tuner_list_channels (GstTuner *tuner)
return NULL;
}
/**
* gst_tuner_set_channel:
* @tuner: the #GstTuner (a #GstElement) that owns the channel.
* @channel: the channel to tune to.
*
* Tunes the object to the given channel.
*/
void
gst_tuner_set_channel (GstTuner *tuner,
GstTunerChannel *channel)
......@@ -143,6 +161,15 @@ gst_tuner_set_channel (GstTuner *tuner,
}
}
/**
* gst_Tuner_get_channel:
* @tuner: the #GstTuner (a #GstElement) to get the current channel from.
*
* Retrieve the current channel from the tuner.
*
* Returns: the current channel of the tuner object.
*/
GstTunerChannel *
gst_tuner_get_channel (GstTuner *tuner)
{
......@@ -155,6 +182,17 @@ gst_tuner_get_channel (GstTuner *tuner)
return NULL;
}
/**
* gst_tuner_get_norms_list:
* @tuner: the #GstTuner (*a #GstElement) to get the list of norms from.
*
* Retrieve a list of available norms on the currently tuned channel
* from the given tuner object.
*
* Returns: A list of norms available on the current channel for this
* tuner object.
*/
const GList *
gst_tuner_list_norms (GstTuner *tuner)
{
......@@ -167,6 +205,14 @@ gst_tuner_list_norms (GstTuner *tuner)
return NULL;
}
/**
* gst_tuner_set_norm:
* @tuner: the #GstTuner (a #GstElement) to set the norm on.
* @norm: the norm to use for the current channel.
*
* Changes the video norm on this tuner to the given norm.
*/
void
gst_tuner_set_norm (GstTuner *tuner,
GstTunerNorm *norm)
......@@ -178,6 +224,16 @@ gst_tuner_set_norm (GstTuner *tuner,
}
}
/**
* gst_tuner_get_norm:
* @tuner: the #GstTuner (a #GstElement) to get the current norm from.
*
* Get the current video norm from the given tuner object for the
* currently selected channel.
*
* Returns: the current norm.
*/
GstTunerNorm *
gst_tuner_get_norm (GstTuner *tuner)
{
......@@ -190,6 +246,18 @@ gst_tuner_get_norm (GstTuner *tuner)
return NULL;
}
/**
* gst_tuner_set_frequency:
* @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.
*
* 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.
*/
void
gst_tuner_set_frequency (GstTuner *tuner,
GstTunerChannel *channel,
......@@ -205,6 +273,17 @@ gst_tuner_set_frequency (GstTuner *tuner,
}
}
/**
* gst_tuner_get_frequency:
* @tuner: the #GstTuner (a #GstElement) that owns the given channel.
* @channel: the #GstTunerChannel to retrieve the frequency from.
*
* Retrieve the current frequency from the given channel. The same
* applies as for set_frequency (): check the flag.
*
* Returns: the current frequency, or 0 on error.
*/
gulong
gst_tuner_get_frequency (GstTuner *tuner,
GstTunerChannel *channel)
......@@ -221,6 +300,20 @@ gst_tuner_get_frequency (GstTuner *tuner,
return 0;
}
/**
* gst_tuner_get_signal_strength:
* @tuner: the #GstTuner (a #GstElement) that owns the given channel.
* @channel: the #GstTunerChannel to get the signal strength from.
*
* get the strength of the signal on this channel. Note that this
* requires the current channel to be a "tuning" channel, e.g. 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.
*
* Returns: signal strength, or 0 on error.
*/
gint
gst_tuner_signal_strength (GstTuner *tuner,
GstTunerChannel *channel)
......@@ -238,7 +331,8 @@ gst_tuner_signal_strength (GstTuner *tuner,
}
GstTunerNorm *
gst_tuner_find_norm_by_name (GstTuner *tuner, gchar *norm)
gst_tuner_find_norm_by_name (GstTuner *tuner,
gchar *norm)
{
GList *walk;
......@@ -255,7 +349,8 @@ gst_tuner_find_norm_by_name (GstTuner *tuner, gchar *norm)
}
GstTunerChannel *
gst_v4l2_find_channel_by_name (GstTuner *tuner, gchar *channel)
gst_tuner_find_channel_by_name (GstTuner *tuner,
gchar *channel)
{
GList *walk;
......
......@@ -106,7 +106,7 @@ gint gst_tuner_signal_strength (GstTuner *tuner,
/* helper functions */
GstTunerNorm * gst_tuner_find_norm_by_name (GstTuner *tuner,
gchar *norm);
GstTunerChannel * gst_tuner_find_channel_by_name(GstTuner *tuner,
GstTunerChannel *gst_tuner_find_channel_by_name (GstTuner *tuner,
gchar *channel);
/* trigger signals */
......
......@@ -106,6 +106,18 @@ gst_mixer_class_init (GstMixerClass *klass)
klass->set_record = NULL;
}
/**
*agst_mixer_list_tracks:
* @mixer: the #GstMixer (a #GstElement) to get the tracks from.
*
* Returns a list of avialable tracks for this mixer/element. Note
* that it is allowed for sink (output) elements to only provide
* the output tracks in this list. Likewise, for sources (inputs),
* it is allowed to only provide input elements in this list.
*
* Returns: A #GList consisting of zero or more #GstMixerTracks.
*/
const GList *
gst_mixer_list_tracks (GstMixer *mixer)
{
......@@ -118,6 +130,21 @@ gst_mixer_list_tracks (GstMixer *mixer)
return NULL;
}
/**
* gst_mixer_set_volume:
* @mixer: The #GstMixer (a #GstElement) that owns the track.
* @track: The #GstMixerTrack to set the volume on.
* @volumes: an array of integers (of size track->num_channels)
* that gives the wanted volume for each channel in
* this track.
*
* Sets the volume on each channel in a track. Short note about
* naming: a track is defined as one separate stream owned by
* the mixer/element, such as 'Line-in' or 'Microphone'. A
* channel is said to be a mono-stream inside this track. A
* stereo track thus contains two channels.
*/
void
gst_mixer_set_volume (GstMixer *mixer,
GstMixerTrack *track,
......@@ -130,6 +157,17 @@ gst_mixer_set_volume (GstMixer *mixer,
}
}
/*
* gst_mixer_get_volume:
* @mixer: the #GstMixer (a #GstElement) that owns the track
* @track: the GstMixerTrack to get the volume from.
* @volumes: a pre-allocated array of integers (of size
* track->num_channels) to store the current volume
* of each channel in the given track in.
*
* Get the current volume(s) on the given track.
*/
void
gst_mixer_get_volume (GstMixer *mixer,
GstMixerTrack *track,
......@@ -148,6 +186,17 @@ gst_mixer_get_volume (GstMixer *mixer,
}
}
/**
* gst_mixer_set_mute:
* @mixer: the #GstMixer (a #GstElement) that owns the track.
* @track: the #GstMixerTrack to operate on.
* @mute: a boolean value indicating whether to turn on or off
* muting.
*
* Mutes or unmutes the given channel. To find out whether a
* track is currently muted, use GST_MIXER_TRACK_HAS_FLAG ().
*/
void
gst_mixer_set_mute (GstMixer *mixer,
GstMixerTrack *track,
......@@ -160,6 +209,19 @@ gst_mixer_set_mute (GstMixer *mixer,
}
}
/**
* gst_mixer_set_record:
* @mixer: The #GstMixer (a #GstElement) that owns the track.
* @track: the #GstMixerTrack to operate on.
* @record: a boolean value that indicates whether to turn on
* or off recording.
*
* Enables or disables recording on the given track. Note that
* this is only possible on input tracks, not on output tracks
* (see GST_MIXER_TRACK_HAS_FLAG () and the GST_MIXER_TRACK_INPUT
* flag).
*/
void
gst_mixer_set_record (GstMixer *mixer,
GstMixerTrack *track,
......
......@@ -82,6 +82,16 @@ gst_property_probe_iface_init (GstPropertyProbeInterface *iface)
iface->get_values = NULL;
}
/**
* gst_property_probe_get_properties:
* @probe: the #GstPropertyProbe to get the properties for.
*
* Get a list of properties for which probing is supported.
*
* Returns the list of properties for which probing is supported
* by this element.
*/
const GList *
gst_property_probe_get_properties (GstPropertyProbe *probe)
{
......@@ -133,6 +143,18 @@ gst_property_probe_probe_property (GstPropertyProbe *probe,
iface->probe_property (probe, pspec->param_id, pspec);
}
/**
* gst_property_probe_probe_property_name:
* @probe: the #GstPropertyProbe to check.
* @name: name of the property to return.
*
* Returns the #GParamSpec for the given property. It's similar to
* g_object_class_find_property (), except that this function only
* takes "probe'able" properties into account.
*
* Returns: the #GParamSpec that belongs to the given property.
*/
void
gst_property_probe_probe_property_name (GstPropertyProbe *probe,
const gchar *name)
......@@ -151,6 +173,20 @@ gst_property_probe_probe_property_name (GstPropertyProbe *probe,
gst_property_probe_probe_property (probe, pspec);
}
/**
* gst_property_probe_needs_probe:
* @probe: the #GstPropertyProbe object to which the given property belongs.
* @pspec: a #GParamSpec that identifies the property to check.
*
* Checks whether a property needs a probe. This might be because
* the property wasn't initialized before, or because host setup
* changed. This might be, for example, because a new device was
* added, and thus device probing needs to be refreshed to display
* the new device.
*
* Returns: TRUE if the property needs a new probe, FALSE if not.
*/
gboolean
gst_property_probe_needs_probe (GstPropertyProbe *probe,
const GParamSpec *pspec)
......@@ -168,6 +204,16 @@ gst_property_probe_needs_probe (GstPropertyProbe *probe,
return FALSE;
}
/**
* gst_property_probe_needs_probe_name:
* @probe: the #GstPropertyProbe object to which the given property belongs.
* @name: the name of the property to check.
*
* Same as gst_property_probe_needs_probe ().
*
* Returns: TRUE if the property needs a new probe, FALSE if not.
*/
gboolean
gst_property_probe_needs_probe_name (GstPropertyProbe *probe,
const gchar *name)
......@@ -185,6 +231,17 @@ gst_property_probe_needs_probe_name (GstPropertyProbe *probe,
return gst_property_probe_needs_probe (probe, pspec);
}
/**
* gst_property_probe_get_values:
* @probe: the #GstPropertyProbe object.
* @pspec: the #GParamSpec property identifier.
*
* Gets the possible (probed) values for the given property,
* requires the property to have been probed before.
*
* Returns: A list of valid values for the given property.
*/
GValueArray *
gst_property_probe_get_values (GstPropertyProbe *probe,
......@@ -203,6 +260,16 @@ gst_property_probe_get_values (GstPropertyProbe *probe,
return NULL;
}
/**
* gst_property_probe_get_values_name:
* @probe: the #GstPropertyProbe object.
* @name: the name of the property to get values for.
*
* Same as gst_property_probe_get_values ().
*
* Returns: A list of valid values for the given property.
*/
GValueArray *
gst_property_probe_get_values_name (GstPropertyProbe *probe,
const gchar *name)
......@@ -221,6 +288,17 @@ gst_property_probe_get_values_name (GstPropertyProbe *probe,
return gst_property_probe_get_values (probe, pspec);
}
/**
* gst_property_probe_probe_and_get_values:
* @probe: the #GstPropertyProbe object.
* @pspec: The #GParamSpec property identifier.
*
* Check whether the given property requires a new probe. If so,
* fo the probe. After that, retrieve a value list. Meant as a