diff --git a/ChangeLog b/ChangeLog index 05c176221d..85816bbc34 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2004-01-25 Ronald Bultje + + * 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 * ext/divx/gstdivxdec.c: (gst_divxdec_init), diff --git a/gst-libs/gst/mixer/mixer.c b/gst-libs/gst/mixer/mixer.c index 7412ca288f..b0a9465d52 100644 --- a/gst-libs/gst/mixer/mixer.c +++ b/gst-libs/gst/mixer/mixer.c @@ -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, diff --git a/gst-libs/gst/propertyprobe/propertyprobe.c b/gst-libs/gst/propertyprobe/propertyprobe.c index a8de4a9ab0..ea242430f8 100644 --- a/gst-libs/gst/propertyprobe/propertyprobe.c +++ b/gst-libs/gst/propertyprobe/propertyprobe.c @@ -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) diff --git a/gst-libs/gst/tuner/tuner.c b/gst-libs/gst/tuner/tuner.c index cc41402c5c..471fc5d2ed 100644 --- a/gst-libs/gst/tuner/tuner.c +++ b/gst-libs/gst/tuner/tuner.c @@ -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; diff --git a/gst-libs/gst/tuner/tuner.h b/gst-libs/gst/tuner/tuner.h index de02051a8a..11a27cc4ee 100644 --- a/gst-libs/gst/tuner/tuner.h +++ b/gst-libs/gst/tuner/tuner.h @@ -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 */