From f11cf32c3f7f571009b29925cb5fbc11013e6088 Mon Sep 17 00:00:00 2001 From: Jan Schmidt Date: Fri, 9 May 2008 21:42:26 +0000 Subject: [PATCH] Document the GstTuner and GstColorBalance interfaces, and some other random API functions that needed it. 70% symbol ... Original commit message from CVS: * docs/libs/gst-plugins-base-libs-sections.txt: * gst-libs/gst/interfaces/colorbalance.c: * gst-libs/gst/interfaces/colorbalance.h: * gst-libs/gst/interfaces/colorbalancechannel.c: * gst-libs/gst/interfaces/colorbalancechannel.h: * gst-libs/gst/interfaces/tuner.c: * gst-libs/gst/interfaces/tunerchannel.c: * gst-libs/gst/interfaces/tunerchannel.h: * gst-libs/gst/interfaces/tunernorm.c: * gst-libs/gst/interfaces/tunernorm.h: * gst-libs/gst/video/video.c: * gst-libs/gst/video/video.h: Document the GstTuner and GstColorBalance interfaces, and some other random API functions that needed it. 70% symbol coverage, woo. --- ChangeLog | 17 ++ docs/libs/gst-plugins-base-libs-sections.txt | 2 - gst-libs/gst/interfaces/colorbalance.c | 65 +++++++ gst-libs/gst/interfaces/colorbalance.h | 12 ++ gst-libs/gst/interfaces/colorbalancechannel.c | 18 ++ gst-libs/gst/interfaces/colorbalancechannel.h | 11 +- gst-libs/gst/interfaces/tuner.c | 179 +++++++++++++++--- gst-libs/gst/interfaces/tunerchannel.c | 34 ++++ gst-libs/gst/interfaces/tunerchannel.h | 38 +++- gst-libs/gst/interfaces/tunernorm.c | 13 ++ gst-libs/gst/interfaces/tunernorm.h | 7 + gst-libs/gst/video/video.c | 45 ++++- gst-libs/gst/video/video.h | 2 +- 13 files changed, 406 insertions(+), 37 deletions(-) diff --git a/ChangeLog b/ChangeLog index 09a24cfb73..eb30509385 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +2008-05-09 Jan Schmidt + + * docs/libs/gst-plugins-base-libs-sections.txt: + * gst-libs/gst/interfaces/colorbalance.c: + * gst-libs/gst/interfaces/colorbalance.h: + * gst-libs/gst/interfaces/colorbalancechannel.c: + * gst-libs/gst/interfaces/colorbalancechannel.h: + * gst-libs/gst/interfaces/tuner.c: + * gst-libs/gst/interfaces/tunerchannel.c: + * gst-libs/gst/interfaces/tunerchannel.h: + * gst-libs/gst/interfaces/tunernorm.c: + * gst-libs/gst/interfaces/tunernorm.h: + * gst-libs/gst/video/video.c: + * gst-libs/gst/video/video.h: + Document the GstTuner and GstColorBalance interfaces, and some + other random API functions that needed it. 70% symbol coverage, woo. + 2008-05-09 Wim Taymans * gst-libs/gst/audio/gstaudiosink.c: (gst_audioringbuffer_acquire): diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt index d5affab21f..48a984dcbe 100644 --- a/docs/libs/gst-plugins-base-libs-sections.txt +++ b/docs/libs/gst-plugins-base-libs-sections.txt @@ -1484,7 +1484,6 @@ gst_video_format_is_yuv gst_video_format_to_fourcc gst_video_format_from_fourcc gst_video_format_parse_caps -gst_video_format_from_rgb32_masks gst_video_parse_caps_framerate gst_video_parse_caps_pixel_aspect_ratio @@ -1542,7 +1541,6 @@ dngettext gettext gettext_noop ngettext -rfc822_binary textdomain SHA_BLOCKSIZE SHA_BYTE diff --git a/gst-libs/gst/interfaces/colorbalance.c b/gst-libs/gst/interfaces/colorbalance.c index 5b09bb8e59..1982f785e3 100644 --- a/gst-libs/gst/interfaces/colorbalance.c +++ b/gst-libs/gst/interfaces/colorbalance.c @@ -30,6 +30,15 @@ /** * SECTION:gstcolorbalance * @short_description: Interface for adjusting color balance settings + * + * + * This interface is implemented by elements which can perform some color + * balance operation on video frames they process. For example, modifying + * the brightness, contrast, hue or saturation. + * + * Example elements are 'xvimagesink' and 'colorbalance' + * + * */ enum @@ -75,6 +84,14 @@ gst_color_balance_class_init (GstColorBalanceClass * klass) static gboolean initialized = FALSE; if (!initialized) { + /** + * GstColorBalance::value-changed: + * @colorbalance: The GstColorBalance instance + * @channel: The #GstColorBalanceChannel + * @value: The new value + * + * Fired when the value of the indicated channel has changed. + */ gst_color_balance_signals[VALUE_CHANGED] = g_signal_new ("value-changed", GST_TYPE_COLOR_BALANCE, G_SIGNAL_RUN_LAST, @@ -94,6 +111,16 @@ gst_color_balance_class_init (GstColorBalanceClass * klass) klass->get_value = NULL; } +/** + * gst_color_balance_list_channels: + * @balance: A #GstColorBalance instance + * + * Retrieve a list of the available channels. + * + * Returns: A GList containing pointers to #GstColorBalanceChannel objects. + * The list is owned by the #GstColorBalance instance and must not + * be freed. + */ const GList * gst_color_balance_list_channels (GstColorBalance * balance) { @@ -106,6 +133,19 @@ gst_color_balance_list_channels (GstColorBalance * balance) return NULL; } +/** + * gst_color_balance_set_value: + * @balance: A #GstColorBalance instance + * @channel: A #GstColorBalanceChannel instance + * @value: The new value for the channel. + * + * Sets the current value of the channel to the passed value, which must + * be between min_value and max_value. + * + * See Also: The #GstColorBalanceChannel::min_value and + * #GstColorBalanceChannel::max_value members of the + * #GstColorBalanceChannel object. + */ void gst_color_balance_set_value (GstColorBalance * balance, GstColorBalanceChannel * channel, gint value) @@ -117,6 +157,20 @@ gst_color_balance_set_value (GstColorBalance * balance, } } +/** + * gst_color_balance_get_value: + * @balance: A #GstColorBalance instance + * @channel: A #GstColorBalanceChannel instance + * + * Retrieve the current value of the indicated channel, between min_value + * and max_value. + * + * See Also: The #GstColorBalanceChannel::min_value and + * #GstColorBalanceChannel::max_value members of the + * #GstColorBalanceChannel object. + * + * Returns: The current value of the channel. + */ gint gst_color_balance_get_value (GstColorBalance * balance, GstColorBalanceChannel * channel) @@ -130,6 +184,17 @@ gst_color_balance_get_value (GstColorBalance * balance, return channel->min_value; } +/** + * gst_color_balance_value_changed: + * @balance: A #GstColorBalance instance + * @channel: A #GstColorBalanceChannel whose value has changed + * @value: The new value of the channel + * + * A helper function called by implementations of the GstColorBalance + * interface. It fires the #GstColorBalance::value-changed signal on the + * instance, and the #GstColorBalanceChannel::value-changed signal on the + * channel object. + */ void gst_color_balance_value_changed (GstColorBalance * balance, GstColorBalanceChannel * channel, gint value) diff --git a/gst-libs/gst/interfaces/colorbalance.h b/gst-libs/gst/interfaces/colorbalance.h index 970cc5917c..44fbc67e7e 100644 --- a/gst-libs/gst/interfaces/colorbalance.h +++ b/gst-libs/gst/interfaces/colorbalance.h @@ -47,6 +47,18 @@ G_BEGIN_DECLS typedef struct _GstColorBalance GstColorBalance; +/** + * GstColorBalanceType: + * @GST_COLOR_BALANCE_HARDWARE: Color balance is implemented with dedicated + * hardware. + * @GST_COLOR_BALANCE_SOFTWARE: Color balance is implemented via software + * processing. + * + * An enumeration indicating whether an element implements color balancing + * operations in software or in dedicated hardware. In general, dedicated + * hardware implementations (such as those provided by xvimagesink) are + * preferred. + */ typedef enum { GST_COLOR_BALANCE_HARDWARE, diff --git a/gst-libs/gst/interfaces/colorbalancechannel.c b/gst-libs/gst/interfaces/colorbalancechannel.c index e99fe00386..ae22fba845 100644 --- a/gst-libs/gst/interfaces/colorbalancechannel.c +++ b/gst-libs/gst/interfaces/colorbalancechannel.c @@ -25,6 +25,17 @@ #include "colorbalancechannel.h" +/** + * SECTION:gstcolorbalancechannel + * @short_description: Object representing a channel from the #GstColorBalance + * interface. + * + * The #GstColorBalanceChannel object represents a parameter + * for modifying the color balance implemented by an element providing the + * #GstColorBalance interface. For example, Hue or Saturation. + * + */ + enum { /* FILL ME */ @@ -74,6 +85,13 @@ gst_color_balance_channel_class_init (GstColorBalanceChannelClass * klass) parent_class = g_type_class_peek_parent (klass); + /** + * GstColorBalanceChannel::value-changed: + * @channel: The #GstColorBalanceChannel + * @value: The new value + * + * Fired when the value of the indicated channel has changed. + */ signals[SIGNAL_VALUE_CHANGED] = g_signal_new ("value-changed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, diff --git a/gst-libs/gst/interfaces/colorbalancechannel.h b/gst-libs/gst/interfaces/colorbalancechannel.h index 174a442f5c..dfb0d9d0b2 100644 --- a/gst-libs/gst/interfaces/colorbalancechannel.h +++ b/gst-libs/gst/interfaces/colorbalancechannel.h @@ -39,12 +39,19 @@ G_BEGIN_DECLS #define GST_IS_COLOR_BALANCE_CHANNEL_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_COLOR_BALANCE_CHANNEL)) +/** + * GstColorBalanceChannel: + * @label: A string containing a descriptive name for this channel + * @min_value: The minimum valid value for this channel. + * @max_value: The maximum valid value for this channel. + */ typedef struct _GstColorBalanceChannel { GObject parent; + /*< public >*/ gchar *label; - gint min_value, - max_value; + gint min_value; + gint max_value; } GstColorBalanceChannel; typedef struct _GstColorBalanceChannelClass { diff --git a/gst-libs/gst/interfaces/tuner.c b/gst-libs/gst/interfaces/tuner.c index 89f874b610..dbefde1faa 100644 --- a/gst-libs/gst/interfaces/tuner.c +++ b/gst-libs/gst/interfaces/tuner.c @@ -31,6 +31,42 @@ /** * SECTION:gsttuner * @short_description: Interface for elements providing tuner operations + * + * + * + * 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. + * + * */ enum @@ -79,12 +115,26 @@ gst_tuner_class_init (GstTunerClass * klass) static gboolean initialized = FALSE; if (!initialized) { + /** + * GstTuner::norm-changed: + * @tuner: The element providing the GstTuner interface + * @norm: The new configured norm. + * + * Reports that the current #GstTunerNorm has changed. + */ gst_tuner_signals[NORM_CHANGED] = g_signal_new ("norm-changed", GST_TYPE_TUNER, G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstTunerClass, norm_changed), NULL, NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_TUNER_NORM); + /** + * GstTuner::channel-changed: + * @tuner: The element providing the GstTuner interface + * @channel: The new configured channel. + * + * Reports that the current #GstTunerChannel has changed. + */ gst_tuner_signals[CHANNEL_CHANGED] = g_signal_new ("channel-changed", GST_TYPE_TUNER, G_SIGNAL_RUN_LAST, @@ -92,6 +142,13 @@ gst_tuner_class_init (GstTunerClass * klass) NULL, NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_TUNER_CHANNEL); + /** + * GstTuner::frequency-changed: + * @tuner: The element providing the GstTuner interface + * @frequency: The new frequency (an unsigned long) + * + * Reports that the current frequency has changed. + */ gst_tuner_signals[FREQUENCY_CHANGED] = g_signal_new ("frequency-changed", GST_TYPE_TUNER, G_SIGNAL_RUN_LAST, @@ -99,6 +156,16 @@ gst_tuner_class_init (GstTunerClass * klass) NULL, NULL, gst_interfaces_marshal_VOID__OBJECT_ULONG, G_TYPE_NONE, 2, GST_TYPE_TUNER_CHANNEL, G_TYPE_ULONG); + /** + * GstTuner::signal-changed: + * @tuner: The element providing the GstTuner interface + * @channel: The current #GstTunerChannel + * @signal: The new signal strength (an integer) + * + * Reports that the signal strength has changed. + * + * See Also: gst_tuner_signal_strength() + */ gst_tuner_signals[SIGNAL_CHANGED] = g_signal_new ("signal-changed", GST_TYPE_TUNER, G_SIGNAL_RUN_LAST, @@ -128,12 +195,12 @@ gst_tuner_class_init (GstTunerClass * klass) * 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. + * Retrieve a #GList of #GstTunerChannels available + * (e.g. 'composite', 's-video', ...) from the given tuner object. * - * Returns: a list of channels available on this tuner. + * Returns: A list of channels available on this tuner. The list is + * owned by the GstTuner and must not be freed. */ - const GList * gst_tuner_list_channels (GstTuner * tuner) { @@ -171,7 +238,7 @@ gst_tuner_set_channel (GstTuner * tuner, GstTunerChannel * channel) } /** - * gst_Tuner_get_channel: + * gst_tuner_get_channel: * @tuner: the #GstTuner (a #GstElement) to get the current channel from. * * Retrieve the current channel from the tuner. @@ -195,14 +262,15 @@ gst_tuner_get_channel (GstTuner * tuner) } /** - * gst_tuner_get_norms_list: + * gst_tuner_list_norms: * @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. + * Retrieve a GList of available #GstTunerNorm settings for the currently + * tuned channel on the given tuner object. * * Returns: A list of norms available on the current channel for this - * tuner object. + * tuner object. The list is owned by the GstTuner and must not + * be freed. */ const GList * @@ -268,14 +336,19 @@ gst_tuner_get_norm (GstTuner * tuner) /** * 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. + * @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. + * + * 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. */ void @@ -297,13 +370,14 @@ 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. + * @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. + * 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. * - * Returns: the current frequency, or 0 on error. + * Returns: The current frequency, or 0 on error. */ gulong @@ -326,19 +400,21 @@ gst_tuner_get_frequency (GstTuner * tuner, GstTunerChannel * channel) } /** - * gst_tuner_get_signal_strength: + * gst_tuner_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 + * 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. * - * Returns: signal strength, or 0 on error. + * The valid range of the signal strength is indicated in the + * min_signal and max_signal properties of the #GstTunerChannel. + * + * Returns: Signal strength, or 0 on error. */ - gint gst_tuner_signal_strength (GstTuner * tuner, GstTunerChannel * channel) { @@ -357,6 +433,16 @@ gst_tuner_signal_strength (GstTuner * tuner, GstTunerChannel * channel) return 0; } +/** + * gst_tuner_find_norm_by_name: + * @tuner: A #GstTuner instance + * @norm: A string containing the name of a #GstTunerNorm + * + * Look up a #GstTunerNorm by name. + * + * Returns: A #GstTunerNorm, or NULL if no norm with the provided name + * is available. + */ GstTunerNorm * gst_tuner_find_norm_by_name (GstTuner * tuner, gchar * norm) { @@ -374,6 +460,16 @@ gst_tuner_find_norm_by_name (GstTuner * tuner, gchar * norm) return NULL; } +/** + * gst_tuner_find_channel_by_name: + * @tuner: A #GstTuner instance + * @channel: A string containing the name of a #GstTunerChannel + * + * Look up a #GstTunerChannel by name. + * + * Returns: A #GstTunerChannel, or NULL if no channel with the provided name + * is available. + */ GstTunerChannel * gst_tuner_find_channel_by_name (GstTuner * tuner, gchar * channel) { @@ -391,6 +487,14 @@ gst_tuner_find_channel_by_name (GstTuner * tuner, gchar * channel) return NULL; } +/** + * gst_tuner_channel_changed: + * @tuner: A #GstTuner instance + * @channel: A #GstTunerChannel instance + * + * Called by elements implementing the #GstTuner interface when the + * current channel changes. Fires the #GstTuner::channel-changed signal. + */ void gst_tuner_channel_changed (GstTuner * tuner, GstTunerChannel * channel) { @@ -401,6 +505,15 @@ gst_tuner_channel_changed (GstTuner * tuner, GstTunerChannel * channel) gst_tuner_signals[CHANNEL_CHANGED], 0, channel); } +/** + * gst_tuner_norm_changed: + * @tuner: A #GstTuner instance + * @norm: A #GstTunerNorm instance + * + * Called by elements implementing the #GstTuner interface when the + * current norm changes. Fires the #GstTuner::norm-changed signal. + * + */ void gst_tuner_norm_changed (GstTuner * tuner, GstTunerNorm * norm) { @@ -410,6 +523,17 @@ gst_tuner_norm_changed (GstTuner * tuner, GstTunerNorm * norm) g_signal_emit (G_OBJECT (tuner), gst_tuner_signals[NORM_CHANGED], 0, norm); } +/** + * gst_tuner_frequency_changed: + * @tuner: A #GstTuner instance + * @channel: The current #GstTunerChannel + * @frequency: The new frequency setting + * + * Called by elements implementing the #GstTuner interface when the + * configured frequency changes. Fires the #GstTuner::frequency-changed + * signal on the tuner, and the #GstTunerChannel::frequency-changed signal + * on the channel. + */ void gst_tuner_frequency_changed (GstTuner * tuner, GstTunerChannel * channel, gulong frequency) @@ -423,6 +547,17 @@ gst_tuner_frequency_changed (GstTuner * tuner, g_signal_emit_by_name (G_OBJECT (channel), "frequency_changed", frequency); } +/** + * gst_tuner_signal_changed: + * @tuner: A #GstTuner instance + * @channel: The current #GstTunerChannel + * @signal: The new signal strength + * + * Called by elements implementing the #GstTuner interface when the + * incoming signal strength changes. Fires the #GstTuner::signal-changed + * signal on the tuner and the #GstTunerChannel::signal-changed signal on + * the channel. + */ void gst_tuner_signal_changed (GstTuner * tuner, GstTunerChannel * channel, gint signal) diff --git a/gst-libs/gst/interfaces/tunerchannel.c b/gst-libs/gst/interfaces/tunerchannel.c index ff6b0bc876..ac2b74e819 100644 --- a/gst-libs/gst/interfaces/tunerchannel.c +++ b/gst-libs/gst/interfaces/tunerchannel.c @@ -25,6 +25,24 @@ #include "tunerchannel.h" +/** + * SECTION:gsttunerchannel + * @short_description: A channel from an element implementing the #GstTuner + * interface. + * + * + * The #GstTunerChannel object is provided by an element implementing + * the #GstTuner interface. + * + * + * GstTunerChannel provides a name and flags to determine the type and + * capabilities of the channel. If the GST_TUNER_CHANNEL_FREQUENCY flag is + * set, then the channel also information about the minimum and maximum + * frequency, and range of the reported signal strength. + * + * + */ + enum { /* FILL ME */ @@ -74,12 +92,28 @@ gst_tuner_channel_class_init (GstTunerChannelClass * klass) parent_class = g_type_class_peek_parent (klass); + /** + * GstTunerChannel::frequency-changed: + * @tunerchannel: The #GstTunerChannel + * @frequency: The new frequency (an unsigned long) + * + * Reports that the current frequency has changed. + */ signals[SIGNAL_FREQUENCY_CHANGED] = g_signal_new ("frequency-changed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstTunerChannelClass, frequency_changed), NULL, NULL, g_cclosure_marshal_VOID__ULONG, G_TYPE_NONE, 1, G_TYPE_ULONG); + /** + * GstTunerChannel::signal-changed: + * @tunerchannel: The #GstTunerChannel + * @signal: The new signal strength (an integer) + * + * Reports that the signal strength has changed. + * + * See Also: gst_tuner_signal_strength() + */ signals[SIGNAL_SIGNAL_CHANGED] = g_signal_new ("signal-changed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, diff --git a/gst-libs/gst/interfaces/tunerchannel.h b/gst-libs/gst/interfaces/tunerchannel.h index 49f6075b6e..7028f0fadc 100644 --- a/gst-libs/gst/interfaces/tunerchannel.h +++ b/gst-libs/gst/interfaces/tunerchannel.h @@ -39,6 +39,17 @@ G_BEGIN_DECLS #define GST_IS_TUNER_CHANNEL_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_TUNER_CHANNEL)) +/** + * GstTunerChannelFlags: + * @GST_TUNER_CHANNEL_INPUT: The channel is for input + * @GST_TUNER_CHANNEL_OUTPUT: The channel is for output + * @GST_TUNER_CHANNEL_FREQUENCY: The channel has a frequency setting + * and signal strength. + * @GST_TUNER_CHANNEL_AUDIO: The channel carries audio. + * + * An enumeration for flags indicating the available capabilities + * of a #GstTunerChannel. + */ typedef enum { GST_TUNER_CHANNEL_INPUT = (1<<0), GST_TUNER_CHANNEL_OUTPUT = (1<<1), @@ -46,24 +57,43 @@ typedef enum { GST_TUNER_CHANNEL_AUDIO = (1<<3) } GstTunerChannelFlags; +/** + * GST_TUNER_CHANNEL_HAS_FLAG: + * @channel: A #GstTunerChannel + * @flag: The flag to check for + * + * Macro to check if the given flag is set on a channel + */ #define GST_TUNER_CHANNEL_HAS_FLAG(channel, flag) \ ((channel)->flags & flag) +/** + * GstTunerChannel: + * @label: A string containing a descriptive name for this channel + * @flags: A set of #GstTunerChannelFlags for this channel + * @freq_multiplicator: The step size (in Hz) for the frequency setting. + * @min_frequency: Minimum valid frequency setting (in Hz). + * @max_frequency: Maximum valid frequency setting (in Hz). + * @min_signal: Minimum reported signal strength value. + * @max_signal: Maximum reported signal strength value. + */ typedef struct _GstTunerChannel { GObject parent; + /*< public >*/ gchar *label; GstTunerChannelFlags flags; gfloat freq_multiplicator; - gulong min_frequency, - max_frequency; - gint min_signal, - max_signal; + gulong min_frequency; + gulong max_frequency; + gint min_signal; + gint max_signal; } GstTunerChannel; typedef struct _GstTunerChannelClass { GObjectClass parent; + /*< private >*/ /* signals */ void (*frequency_changed) (GstTunerChannel *channel, gulong frequency); diff --git a/gst-libs/gst/interfaces/tunernorm.c b/gst-libs/gst/interfaces/tunernorm.c index 9e10cf26c7..47260b0ed1 100644 --- a/gst-libs/gst/interfaces/tunernorm.c +++ b/gst-libs/gst/interfaces/tunernorm.c @@ -25,6 +25,19 @@ #include "tunernorm.h" +/** + * SECTION:gsttunernorm + * @short_description: Encapsulates information about the data format(s) + * for a #GstTunerChannel. + * + * + * The #GstTunerNorm object is created by an element implementing the + * #GstTuner interface and encapsulates the selection of a capture/output format + * for a selected #GstTunerChannel. + * + * + */ + enum { /* FILL ME */ diff --git a/gst-libs/gst/interfaces/tunernorm.h b/gst-libs/gst/interfaces/tunernorm.h index 66e4c62026..f306f1a9be 100644 --- a/gst-libs/gst/interfaces/tunernorm.h +++ b/gst-libs/gst/interfaces/tunernorm.h @@ -37,9 +37,16 @@ G_BEGIN_DECLS #define GST_IS_TUNER_NORM_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_TUNER_NORM)) +/** + * GstTunerNorm: + * @label: A string containing a descriptive name for the norm + * @framerate: A GValue containing the framerate associated with this norm, + * if any. (May be unset). + */ typedef struct _GstTunerNorm { GObject parent; + /*< public >*/ gchar *label; GValue framerate; } GstTunerNorm; diff --git a/gst-libs/gst/video/video.c b/gst-libs/gst/video/video.c index 8f6a716e4c..3be9d40e32 100644 --- a/gst-libs/gst/video/video.c +++ b/gst-libs/gst/video/video.c @@ -45,7 +45,19 @@ static GstVideoFormat gst_video_format_from_rgb24_masks (int red_mask, int green_mask, int blue_mask); -/* This is simply a convenience function, nothing more or less */ +/** + * gst_video_frame_rate: + * @pad: pointer to a #GstPad + * + * A convenience function to retrieve a GValue holding the framerate + * from the caps on a pad. + * + * The pad needs to have negotiated caps containing a framerate property. + * + * Returns: NULL if the pad has no configured caps or the configured caps + * do not contain a framerate. + * + */ const GValue * gst_video_frame_rate (GstPad * pad) { @@ -84,6 +96,20 @@ gst_video_frame_rate (GstPad * pad) return fps; } +/** + * gst_video_get_size: + * @pad: pointer to a #GstPad + * @width: pointer to integer to hold pixel width of the video frames (output) + * @height: pointer to integer to hold pixel height of the video frames (output) + * + * Inspect the caps of the provided pad and retrieve the width and height of + * the video frames it is configured for. + * + * The pad needs to have negotiated caps containing width and height properties. + * + * Returns: TRUE if the width and height could be retrieved. + * + */ gboolean gst_video_get_size (GstPad * pad, gint * width, gint * height) { @@ -290,9 +316,9 @@ gst_video_format_parse_caps (GstCaps * caps, GstVideoFormat * format, /** * gst_video_parse_caps_framerate: - * @caps: - * @fps_n: pointer to numerator of frame rate (output) - * @fps_d: pointer to denominator of frame rate (output) + * @caps: pointer to a #GstCaps instance + * @fps_n: pointer to integer to hold numerator of frame rate (output) + * @fps_d: pointer to integer to hold denominator of frame rate (output) * * Extracts the frame rate from @caps and places the values in the locations * pointed to by @fps_n and @fps_d. Returns TRUE if the values could be @@ -320,7 +346,7 @@ gst_video_parse_caps_framerate (GstCaps * caps, int *fps_n, int *fps_d) /** * gst_video_parse_caps_pixel_aspect_ratio: - * @caps: + * @caps: pointer to a #GstCaps instance * @par_n: pointer to numerator of pixel aspect ratio (output) * @par_d: pointer to denominator of pixel aspect ratio (output) * @@ -530,7 +556,7 @@ gst_video_format_to_fourcc (GstVideoFormat format) } } -/** +/* * gst_video_format_from_rgb32_masks: * @red_mask: red bit mask * @green_mask: green bit mask @@ -607,6 +633,8 @@ gst_video_format_from_rgb24_masks (int red_mask, int green_mask, int blue_mask) * gst_video_format_is_rgb: * @format: a #GstVideoFormat * + * Determine whether the video format is an RGB format. + * * Since: 0.10.16 * * Returns: TRUE if @format represents RGB video @@ -643,6 +671,8 @@ gst_video_format_is_rgb (GstVideoFormat format) * gst_video_format_is_yuv: * @format: a #GstVideoFormat * + * Determine whether the video format is a YUV format. + * * Since: 0.10.16 * * Returns: TRUE if @format represents YUV video @@ -678,6 +708,9 @@ gst_video_format_is_yuv (GstVideoFormat format) /** * gst_video_format_has_alpha: * @format: a #GstVideoFormat + * + * Returns TRUE or FALSE depending on if the video format provides an + * alpha channel. * * Since: 0.10.16 * diff --git a/gst-libs/gst/video/video.h b/gst-libs/gst/video/video.h index 1c4b55f322..ef185b5226 100644 --- a/gst-libs/gst/video/video.h +++ b/gst-libs/gst/video/video.h @@ -27,7 +27,7 @@ G_BEGIN_DECLS /** * GstVideoFormat: - * @GST_VIDEO_FORMAT_UNKNOWN, + * @GST_VIDEO_FORMAT_UNKNOWN: Unknown or unset video format id * @GST_VIDEO_FORMAT_I420: planar 4:2:0 YUV * @GST_VIDEO_FORMAT_YV12: planar 4:2:0 YVU (like I420 but UV planes swapped) * @GST_VIDEO_FORMAT_YUY2: packed 4:2:2 YUV (Y0-U0-Y1-V0 Y2-U2-Y3-V2 Y4 ...)