Commit d7a5d173 authored by Wim Taymans's avatar Wim Taymans

Documentation updates

Original commit message from CVS:
Documentation updates
Added dump to identity
Fix some warnings in gstelement
parent d30487f9
......@@ -374,12 +374,11 @@ cothread_getcurrent (void)
}
/**
* cothread_set_data:
* cothread_set_private:
* @thread: the cothread state
* @key: a key for the data
* @data: the data
*
* adds data to a cothread
* set private data for the cothread.
*/
void
cothread_set_private (cothread_state *thread, gpointer data)
......@@ -387,6 +386,14 @@ cothread_set_private (cothread_state *thread, gpointer data)
thread->priv = data;
}
/**
* cothread_context_set_data:
* @thread: the cothread state
* @key: a key for the data
* @data: the data
*
* adds data to a cothread
*/
void
cothread_context_set_data (cothread_state *thread, gchar *key, gpointer data)
{
......@@ -396,13 +403,12 @@ cothread_context_set_data (cothread_state *thread, gchar *key, gpointer data)
}
/**
* cothread_get_data:
* cothread_get_private:
* @thread: the cothread state
* @key: a key for the data
*
* get data from the cothread
* get the private data from the cothread
*
* Returns: the data assiciated with the key
* Returns: the private data of the cothread
*/
gpointer
cothread_get_private (cothread_state *thread)
......@@ -410,6 +416,15 @@ cothread_get_private (cothread_state *thread)
return thread->priv;
}
/**
* cothread_context_get_data:
* @thread: the cothread state
* @key: a key for the data
*
* get data from the cothread
*
* Returns: the data associated with the key
*/
gpointer
cothread_context_get_data (cothread_state * thread, gchar * key)
{
......
......@@ -266,8 +266,7 @@ gst_fakesink_chain (GstPad *pad, GstBuffer *buf)
g_signal_emit (G_OBJECT (fakesink), gst_fakesink_signals[SIGNAL_HANDOFF], 0, buf, pad);
if (fakesink->dump)
{
if (fakesink->dump) {
gst_util_dump_mem (GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (buf));
}
......
......@@ -51,6 +51,7 @@ enum {
ARG_DROP_PROBABILITY,
ARG_SILENT,
ARG_LAST_MESSAGE,
ARG_DUMP,
};
......@@ -116,6 +117,9 @@ gst_identity_class_init (GstIdentityClass *klass)
g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_LAST_MESSAGE,
g_param_spec_string ("last-message", "last-message", "last-message",
NULL, G_PARAM_READABLE));
g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_DUMP,
g_param_spec_boolean("dump","Dump","Dump buffer contents",
FALSE, G_PARAM_READWRITE));
gst_identity_signals[SIGNAL_HANDOFF] =
g_signal_new ("handoff", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
......@@ -174,6 +178,7 @@ gst_identity_init (GstIdentity *identity)
identity->error_after = -1;
identity->drop_probability = 0.0;
identity->silent = FALSE;
identity->dump = FALSE;
}
static void
......@@ -206,6 +211,9 @@ gst_identity_chain (GstPad *pad, GstBuffer *buf)
return;
}
}
if (identity->dump) {
gst_util_dump_mem (GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (buf));
}
for (i = identity->duplicate; i; i--) {
if (!identity->silent)
......@@ -275,6 +283,9 @@ gst_identity_set_property (GObject *object, guint prop_id, const GValue *value,
case ARG_DUPLICATE:
identity->duplicate = g_value_get_uint (value);
break;
case ARG_DUMP:
identity->dump = g_value_get_boolean (value);
break;
case ARG_ERROR_AFTER:
identity->error_after = g_value_get_uint (value);
break;
......@@ -313,6 +324,9 @@ static void gst_identity_get_property(GObject *object, guint prop_id, GValue *va
case ARG_SILENT:
g_value_set_boolean (value, identity->silent);
break;
case ARG_DUMP:
g_value_set_boolean (value, identity->dump);
break;
case ARG_LAST_MESSAGE:
g_value_set_string (value, identity->last_message);
break;
......
......@@ -63,6 +63,7 @@ struct _GstIdentity {
gfloat drop_probability;
guint sleep_time;
gboolean silent;
gboolean dump;
gchar *last_message;
};
......
......@@ -26,7 +26,6 @@
#include "gstevent.h"
#include "gstbin.h"
#include "gstxml.h"
#include "gstsystemclock.h"
#include "gstscheduler.h"
......@@ -152,6 +151,14 @@ gst_bin_new (const gchar * name)
return gst_elementfactory_make ("bin", name);
}
/**
* gst_bin_get_clock:
* @bin: the bin to get the clock of
*
* Get the current clock of the bin
*
* Returns: the clock of the bin
*/
GstClock*
gst_bin_get_clock (GstBin *bin)
{
......@@ -164,6 +171,14 @@ gst_bin_get_clock (GstBin *bin)
return NULL;
}
/**
* gst_bin_use_clock:
* @bin: the bin to set the clock for
* @clock: the clock to use.
*
* Force the bin to use the given clock. Use NULL to
* force it to use no clock at all.
*/
void
gst_bin_use_clock (GstBin *bin, GstClock *clock)
{
......@@ -174,6 +189,12 @@ gst_bin_use_clock (GstBin *bin, GstClock *clock)
gst_scheduler_use_clock (GST_ELEMENT_SCHED (bin), clock);
}
/**
* gst_bin_auto_clock:
* @bin: the bin to autoclock
*
* Let the bin select a clock automatically.
*/
void
gst_bin_auto_clock (GstBin *bin)
{
......@@ -273,14 +294,13 @@ gst_bin_unset_element_sched (GstElement *element, GstScheduler *sched)
/**
* gst_element_connect_elements_many:
* gst_bin_add_many:
* @bin: the bin to add the elements to
* @element_1: the first element to add to the bin
* @...: NULL-terminated list of elements to add to the bin
*
* Add a list of elements to a bin. Uses #gst_bin_add.
**/
/* API FIXME: this should be called gst_element_connect_many, and connect_elements
* should just be connect */
*/
void
gst_bin_add_many (GstBin *bin, GstElement *element_1, ...)
{
......
......@@ -697,6 +697,17 @@ gst_caps_intersect (GstCaps *caps1, GstCaps *caps2)
return result;
}
/**
* gst_caps_normalize:
* @caps: a capabilty
*
* Make the normalisation of the caps. This will return a new caps
* that is equivalent to the input caps with the exception that all
* lists are unrolled. This function is useful when you want to iterate
* the caps.
*
* Returns: The normalisation of the caps.
*/
GstCaps*
gst_caps_normalize (GstCaps *caps)
{
......
......@@ -138,6 +138,9 @@ gst_clock_class_init (GstClockClass *klass)
parent_class = g_type_class_ref (GST_TYPE_OBJECT);
if (!g_thread_supported ())
g_thread_init (NULL);
_gst_clock_entries_chunk = g_mem_chunk_new ("GstClockEntries",
sizeof (GstClockEntry), sizeof (GstClockEntry) * 32,
G_ALLOC_AND_FREE);
......@@ -159,6 +162,14 @@ gst_clock_init (GstClock *clock)
clock->active_cond = g_cond_new ();
}
/**
* gst_clock_async_supported
* @clock: The clock to query
*
* Check if this clock can support async notification.
*
* Returns: TRUE if async notification is supported.
*/
gboolean
gst_clock_async_supported (GstClock *clock)
{
......@@ -167,7 +178,45 @@ gst_clock_async_supported (GstClock *clock)
return clock->async_supported;
}
/**
* gst_clock_set_speed
* @clock: The clock to modify
* @speed: The speed to set on the clock
*
* Set the speed on the given clock. 1.0 is the default
* speed.
*/
void
gst_clock_set_speed (GstClock *clock, gdouble speed)
{
g_return_if_fail (GST_IS_CLOCK (clock));
clock->speed = speed;
}
/**
* gst_clock_get_speed
* @clock: The clock to query
*
* Get the speed of the given clock.
*
* Returns: the speed of the clock.
*/
gdouble
gst_clock_get_speed (GstClock *clock)
{
g_return_val_if_fail (GST_IS_CLOCK (clock), 0.0);
return clock->speed;
}
/**
* gst_clock_reset
* @clock: The clock to reset
*
* Reset the clock to time 0.
*/
void
gst_clock_reset (GstClock *clock)
{
......@@ -186,6 +235,14 @@ gst_clock_reset (GstClock *clock)
GST_UNLOCK (clock);
}
/**
* gst_clock_activate
* @clock: The clock to activate
* @active: flag indication activate or deactivate
*
* Activates or deactivates the clock based on the activate paramater.
* As soon as the clock is activated, the time will start ticking.
*/
void
gst_clock_activate (GstClock *clock, gboolean active)
{
......@@ -213,6 +270,14 @@ gst_clock_activate (GstClock *clock, gboolean active)
g_mutex_unlock (clock->active_mutex);
}
/**
* gst_clock_is_active
* @clock: The clock to query
*
* Checks if the given clock is active.
*
* Returns: TRUE if the clock is active.
*/
gboolean
gst_clock_is_active (GstClock *clock)
{
......@@ -221,6 +286,15 @@ gst_clock_is_active (GstClock *clock)
return clock->active;
}
/**
* gst_clock_get_time
* @clock: The clock to query
*
* Get the current time of the given clock. The time is always
* monotonically increasing.
*
* Returns: the time of the clock.
*/
GstClockTime
gst_clock_get_time (GstClock *clock)
{
......@@ -270,6 +344,15 @@ gst_clock_wait_async_func (GstClock *clock, GstClockTime time,
return entry;
}
/**
* gst_clock_wait
* @clock: The clock to wait on
* @time: The time to wait for
*
* Wait and block till the clock reaches the specified time.
*
* Returns: result of the operation.
*/
GstClockReturn
gst_clock_wait (GstClock *clock, GstClockTime time)
{
......@@ -284,6 +367,19 @@ gst_clock_wait (GstClock *clock, GstClockTime time)
return res;
}
/**
* gst_clock_wait_async
* @clock: The clock to wait on
* @time: The time to wait for
* @func: The callback function
* @user_data: User data passed in the calback
*
* Register a callback on the given clock that will be triggered
* when the clock has reached the given time. A ClockID is returned
* that can be used to cancel the request.
*
* Returns: the clock id or NULL when async notification is not supported.
*/
GstClockID
gst_clock_wait_async (GstClock *clock, GstClockTime time,
GstClockCallback func, gpointer user_data)
......@@ -296,6 +392,52 @@ gst_clock_wait_async (GstClock *clock, GstClockTime time,
return NULL;
}
/**
* gst_clock_cancel_wait_async
* @clock: The clock to cancel the request on
* @id: The id to cancel
*
* Cancel an outstanding async notification request with the given ID.
*/
void
gst_clock_cancel_wait_async (GstClock *clock, GstClockID id)
{
g_warning ("not supported");
}
/**
* gst_clock_notify_async
* @clock: The clock to wait on
* @interval: The interval between notifications
* @func: The callback function
* @user_data: User data passed in the calback
*
* Register a callback on the given clock that will be periodically
* triggered with the specified interval. A ClockID is returned
* that can be used to cancel the request.
*
* Returns: the clock id or NULL when async notification is not supported.
*/
GstClockID
gst_clock_notify_async (GstClock *clock, GstClockTime interval,
GstClockCallback func, gpointer user_data)
{
g_warning ("not supported");
}
/**
* gst_clock_remove_notify_async
* @clock: The clock to cancel the request on
* @id: The id to cancel
*
* Cancel an outstanding async notification request with the given ID.
*/
void
gst_clock_remove_notify_async (GstClock *clock, GstClockID id)
{
g_warning ("not supported");
}
static void
gst_clock_unlock_func (GstClock *clock, GstClockTime time, GstClockID id, gpointer user_data)
{
......@@ -306,6 +448,15 @@ gst_clock_unlock_func (GstClock *clock, GstClockTime time, GstClockID id, gpoint
GST_CLOCK_ENTRY_UNLOCK (entry);
}
/**
* gst_clock_wait_id
* @clock: The clock to wait on
* @id: The clock id to wait on
*
* Wait and block on the clockid obtained with gst_clock_wait_async.
*
* Returns: result of the operation.
*/
GstClockReturn
gst_clock_wait_id (GstClock *clock, GstClockID id)
{
......@@ -341,6 +492,14 @@ gst_clock_wait_id (GstClock *clock, GstClockID id)
return res;
}
/**
* gst_clock_get_next_id
* @clock: The clock to query
*
* Get the clockid of the next event.
*
* Returns: a clockid or NULL is no event is pending.
*/
GstClockID
gst_clock_get_next_id (GstClock *clock)
{
......@@ -354,6 +513,14 @@ gst_clock_get_next_id (GstClock *clock)
return (GstClockID *) entry;
}
/**
* gst_clock_id_get_time
* @id: The clockid to query
*
* Get the time of the clock ID
*
* Returns: the time of the given clock id
*/
GstClockTime
gst_clock_id_get_time (GstClockID id)
{
......@@ -372,6 +539,13 @@ gst_clock_free_entry (GstClock *clock, GstClockEntry *entry)
g_mutex_unlock (_gst_clock_entries_chunk_lock);
}
/**
* gst_clock_unlock_id
* @clock: The clock that own the id
* @id: The clockid to unlock
*
* Unlock the ClockID.
*/
void
gst_clock_unlock_id (GstClock *clock, GstClockID id)
{
......@@ -383,6 +557,13 @@ gst_clock_unlock_id (GstClock *clock, GstClockID id)
gst_clock_free_entry (clock, entry);
}
/**
* gst_clock_set_resolution
* @clock: The clock set the resolution on
* @resolution: The resolution to set
*
* Set the accuracy of the clock.
*/
void
gst_clock_set_resolution (GstClock *clock, guint64 resolution)
{
......@@ -392,6 +573,14 @@ gst_clock_set_resolution (GstClock *clock, guint64 resolution)
CLASS (clock)->set_resolution (clock, resolution);
}
/**
* gst_clock_get_resolution
* @clock: The clock get the resolution of
*
* Get the accuracy of the clock.
*
* Returns: the resolution of the clock in microseconds.
*/
guint64
gst_clock_get_resolution (GstClock *clock)
{
......
......@@ -90,7 +90,7 @@ struct _GstClockClass {
GType gst_clock_get_type (void);
void gst_clock_set_speed (GstClock *clock, gdouble speed);
void gst_clock_get_speed (GstClock *clock, gdouble speed);
gdouble gst_clock_get_speed (GstClock *clock);
void gst_clock_activate (GstClock *clock, gboolean active);
gboolean gst_clock_is_active (GstClock *clock);
......
......@@ -288,6 +288,8 @@ gst_element_set_clock (GstElement *element, GstClock *clock)
* @element: GstElement to get the clock of
*
* Get the clock of the element
*
* Returns: the clock of the element.
*/
GstClock*
gst_element_get_clock (GstElement *element)
......@@ -308,6 +310,8 @@ gst_element_get_clock (GstElement *element)
* @time: the time to wait for
*
* Wait for a specific time on the clock
*
* Returns: the result of the wait operation
*/
GstClockReturn
gst_element_clock_wait (GstElement *element, GstClock *clock, GstClockTime time)
......@@ -717,7 +721,8 @@ gst_element_request_pad_by_name (GstElement *element, const gchar *name)
gboolean templ_found = FALSE;
GList *list;
gint n;
gchar *str, *data, *endptr;
const gchar *data;
gchar *str, *endptr;
g_return_val_if_fail (element != NULL, NULL);
g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
......@@ -867,7 +872,7 @@ gst_element_get_compatible_pad (GstElement *element, GstPad *pad)
+ It will use request pads if possible. But both pads will not be requested.
* If multiple connections are possible, only one is established.
*
* Return: TRUE if the elements could be connected.
* Returns: TRUE if the elements could be connected.
*/
gboolean
gst_element_connect_elements_filtered (GstElement *src, GstElement *dest,
......@@ -960,7 +965,7 @@ gst_element_connect_elements_filtered (GstElement *src, GstElement *dest,
* Chain together a series of elements. Uses #gst_element_connect_elements.
*
* Returns: TRUE on success, FALSE otherwise.
**/
*/
/* API FIXME: this should be called gst_element_connect_many, and connect_elements
* should just be connect */
gboolean
......@@ -998,7 +1003,7 @@ gst_element_connect_elements_many (GstElement *element_1, GstElement *element_2,
* connected yet. If multiple connections are possible, only one is
* established.
*
* Return: TRUE if the elements could be connected.
* Returns: TRUE if the elements could be connected.
*/
gboolean
gst_element_connect_elements (GstElement *src, GstElement *dest)
......@@ -1019,7 +1024,7 @@ gst_element_connect_elements (GstElement *src, GstElement *dest)
* child of the parent of the other element. If they have different
* parents, the connection fails.
*
* Return: TRUE if the pads could be connected.
* Returns: TRUE if the pads could be connected.
*/
gboolean
gst_element_connect_filtered (GstElement *src, const gchar *srcpadname,
......@@ -1063,7 +1068,7 @@ gst_element_connect_filtered (GstElement *src, const gchar *srcpadname,
* child of the parent of the other element. If they have different
* parents, the connection fails.
*
* Return: TRUE if the pads could be connected.
* Returns: TRUE if the pads could be connected.
*/
gboolean
gst_element_connect (GstElement *src, const gchar *srcpadname,
......
......@@ -146,7 +146,7 @@ gboolean gst_object_check_uniqueness (GList *list, const gchar *name);
#ifndef GST_DISABLE_LOADSAVE_REGISTRY
xmlNodePtr gst_object_save_thyself (GstObject *object, xmlNodePtr parent);
void gst_object_restore_thyself (GstObject *object, xmlNodePtr parent);
void gst_object_restore_thyself (GstObject *object, xmlNodePtr self);
#else
#pragma GCC poison gst_object_save_thyself
#pragma GCC poison gst_object_restore_thyself
......
......@@ -1261,8 +1261,9 @@ gst_pad_perform_negotiate (GstPad *srcpad, GstPad *sinkpad)
/**
* gst_pad_try_reconnect_filtered:
* @pad: the pad to reconnect
* @caps: the capabilities to use in the reconnectiong
* @srcpad: the source"pad to reconnect
* @sinkpad: the sink pad to reconnect
* @filtercaps: the capabilities to use in the reconnectiong
*
* Try to reconnect this pad and its peer with the specified caps
*
......@@ -1287,8 +1288,9 @@ gst_pad_try_reconnect_filtered (GstPad *srcpad, GstPad *sinkpad, GstCaps *filter
/**
* gst_pad_reconnect_filtered:
* @pad: the pad to reconnect
* @caps: the capabilities to use in the reconnectiong
* @srcpad: the source"pad to reconnect
* @sinkpad: the sink pad to reconnect
* @filtercaps: the capabilities to use in the reconnectiong
*
* Try to reconnect this pad and its peer with the specified caps.
*
......@@ -1499,11 +1501,12 @@ gst_pad_get_allowed_caps (GstPad *pad)
}
/**
* gst_pad_recac_allowed_caps:
* gst_pad_recalc_allowed_caps:
* @pad: the pad to recaculate the caps of
*
* Attempt to reconnect the pad to its peer through its filter, set with gst_pad_[re]connect_filtered.
* FIXME: no one calls this function. why is it here?
* Attempt to reconnect the pad to its peer through its filter,
* set with gst_pad_[re]connect_filtered. This function is useful when a
* plugin has new capabilities on a pad and wants to notify the peer.
*
* Returns: TRUE on success, FALSE otherwise.
*/
......@@ -2257,21 +2260,22 @@ static GstPad *ghost_pad_parent_class = NULL;
/* static guint gst_ghost_pad_signals[LAST_SIGNAL] = { 0 }; */
GType
gst_ghost_pad_get_type(void) {
gst_ghost_pad_get_type (void)
{
if (!_gst_ghost_pad_type) {
static const GTypeInfo pad_info = {
sizeof(GstGhostPadClass),
sizeof (GstGhostPadClass),
NULL,
NULL,
(GClassInitFunc)gst_ghost_pad_class_init,
(GClassInitFunc) gst_ghost_pad_class_init,