From c8e8981be86d87c25db6e5c42d07e94427f2b9ab Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Wed, 12 Jun 2002 22:26:36 +0000 Subject: [PATCH] Documentation updates Original commit message from CVS: Documentation updates Make spider forward bufferpools Remove some old registry code --- gst/autoplug/gstspideridentity.c | 15 ++-- gst/elements/gstfilesrc.c | 2 +- gst/gstcaps.h | 2 +- gst/gstclock.c | 17 +++++ gst/gstelement.c | 41 +++++++++-- gst/gstevent.c | 29 ++++++-- gst/gstevent.h | 4 +- gst/gstpad.c | 17 +++++ gst/gstparse.c | 5 +- gst/gstplugin.c | 18 +++++ gst/gstregistry.c | 117 +------------------------------ gst/gstregistry.h | 18 ----- gst/gstscheduler.c | 1 + plugins/elements/gstfilesrc.c | 2 +- 14 files changed, 132 insertions(+), 156 deletions(-) diff --git a/gst/autoplug/gstspideridentity.c b/gst/autoplug/gstspideridentity.c index 189c44a8dd..80e52cb841 100644 --- a/gst/autoplug/gstspideridentity.c +++ b/gst/autoplug/gstspideridentity.c @@ -128,17 +128,16 @@ gst_spider_identity_class_init (GstSpiderIdentityClass *klass) gstelement_class->change_state = GST_DEBUG_FUNCPTR(gst_spider_identity_change_state); gstelement_class->request_new_pad = GST_DEBUG_FUNCPTR(gst_spider_identity_request_new_pad); } -/* defined but not used + static GstBufferPool* gst_spider_identity_get_bufferpool (GstPad *pad) -{*/ - /* fix me */ -/* GstSpiderIdentity *spider_identity; +{ + GstSpiderIdentity *ident; - spider_identity = GST_SPIDER_IDENTITY (gst_pad_get_parent (pad)); + ident = GST_SPIDER_IDENTITY (gst_pad_get_parent (pad)); - return gst_pad_get_bufferpool (spider_identity->src); -}*/ + return gst_pad_get_bufferpool (ident->src); +} static void gst_spider_identity_init (GstSpiderIdentity *ident) @@ -148,6 +147,7 @@ gst_spider_identity_init (GstSpiderIdentity *ident) gst_element_add_pad (GST_ELEMENT (ident), ident->sink); gst_pad_set_connect_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_connect)); gst_pad_set_getcaps_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_getcaps)); + gst_pad_set_bufferpool_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_get_bufferpool)); /* src */ ident->src = gst_pad_new_from_template (GST_PAD_TEMPLATE_GET (spider_src_factory), "src"); gst_element_add_pad (GST_ELEMENT (ident), ident->src); @@ -288,6 +288,7 @@ gst_spider_identity_request_new_pad (GstElement *element, GstPadTemplate *templ gst_element_add_pad (GST_ELEMENT (ident), ident->sink); gst_pad_set_connect_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_connect)); gst_pad_set_getcaps_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_getcaps)); + gst_pad_set_bufferpool_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_get_bufferpool)); return ident->sink; case GST_PAD_SRC: /* src */ diff --git a/gst/elements/gstfilesrc.c b/gst/elements/gstfilesrc.c index 3fc7b50571..f06484ac31 100644 --- a/gst/elements/gstfilesrc.c +++ b/gst/elements/gstfilesrc.c @@ -453,7 +453,7 @@ gst_filesrc_get (GstPad *pad) src->seek_happened = FALSE; GST_DEBUG (GST_CAT_EVENT, "filesrc sending discont\n"); event = gst_event_new_discontinuous (FALSE, GST_FORMAT_BYTES, src->curoffset, NULL); - GST_EVENT_DISCONT_FLUSH (event) = src->need_flush; + GST_EVENT_DISCONT_NEW_MEDIA (event) = FALSE; src->need_flush = FALSE; return GST_BUFFER (event); } diff --git a/gst/gstcaps.h b/gst/gstcaps.h index ecdc5efdc8..ad4ccb7b07 100644 --- a/gst/gstcaps.h +++ b/gst/gstcaps.h @@ -97,7 +97,7 @@ void gst_caps_destroy (GstCaps *caps); void gst_caps_debug (GstCaps *caps, const gchar *label); GstCaps* gst_caps_copy (GstCaps *caps); -GstCaps* gst_caps_copy_first (GstCaps *caps); +GstCaps* gst_caps_copy_1 (GstCaps *caps); GstCaps* gst_caps_copy_on_write (GstCaps *caps); const gchar* gst_caps_get_name (GstCaps *caps); diff --git a/gst/gstclock.c b/gst/gstclock.c index 93ca644a78..dd12edbd0e 100644 --- a/gst/gstclock.c +++ b/gst/gstclock.c @@ -288,6 +288,17 @@ gst_clock_is_active (GstClock *clock) return clock->active; } +/** + * gst_clock_handle_discont + * @clock: a #GstClock to notify of the discontinuity + * @time: The new time + * + * Notifies the clock of a discontinuity in time. + * + * Returns: TRUE if the clock was updated. It is possible that + * the clock was not updated by this call because only the first + * discontinuitity in the pipeline is honoured. + */ gboolean gst_clock_handle_discont (GstClock *clock, guint64 time) { @@ -384,8 +395,12 @@ gst_clock_wait_async_func (GstClock *clock, GstClockTime time, * gst_clock_wait * @clock: a #GstClock to wait on * @time: The #GstClockTime to wait for + * @jitter: The jitter * * Wait and block till the clock reaches the specified time. + * The jitter value contains the difference between the requested time and + * the actual time, negative values indicate that the requested time + * was allready passed when this call was made. * * Returns: the #GstClockReturn result of the operation. */ @@ -489,8 +504,10 @@ gst_clock_unlock_func (GstClock *clock, GstClockTime time, GstClockID id, gpoint * gst_clock_wait_id * @clock: The clock to wait on * @id: The clock id to wait on + * @jitter: The jitter * * Wait and block on the clockid obtained with gst_clock_wait_async. + * The jitter value is described in gst_clock_wait(). * * Returns: result of the operation. */ diff --git a/gst/gstelement.c b/gst/gstelement.c index 471c0e111b..df4984b82d 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -584,6 +584,14 @@ gst_element_request_pad (GstElement *element, GstPadTemplate *templ, const gchar return newpad; } +/** + * gst_element_release_request_pad: + * @element: a #GstElement to release the request pad of + * @pad: The pad to release + * + * Make the element free the previously requested pad as obtained + * with gst_element_get_request_pad(). + */ void gst_element_release_request_pad (GstElement *element, GstPad *pad) { @@ -713,6 +721,7 @@ gst_element_get_clock (GstElement *element) * @element: a #GstElement * @clock: the #GstClock to use * @time: the #GstClockTime to wait for on the clock + * @jitter: The difference between requested time and actual time * * Waits for a specific time on the clock. * @@ -740,7 +749,7 @@ gst_element_clock_wait (GstElement *element, GstClock *clock, GstClockTime time, * gst_element_release_locks: * @element: an element * - * Instruct the element to release all the locks it is holding, ex + * Instruct the element to release all the locks it is holding, such as * blocking reads, waiting for the clock, ... * * Returns: TRUE if the locks could be released. @@ -1125,7 +1134,7 @@ gst_element_get_pad_template (GstElement *element, const guchar *name) /** * gst_element_get_compatible_pad_template: * @element: element to get padtemplate of - * @templ: a template to find a compatible template for + * @compattempl: a template to find a compatible template for * * Generate a padtemplate for this element compatible with the given * template, ie able to link to it. @@ -1649,6 +1658,17 @@ gst_element_send_event_default (GstElement *element, GstEvent *event) return res; } +/** + * gst_element_send_event: + * @element: The element to send the event to. + * @event: The event to send to the object. + * + * Sends an event to an element. If the element doesn't + * implement an event handler, the event will be forwarded + * to a random sinkpad. + * + * Returns: TRUE if the event was handled. + */ gboolean gst_element_send_event (GstElement *element, GstEvent *event) { @@ -1682,6 +1702,21 @@ gst_element_query_default (GstElement *element, GstPadQueryType type, return res; } +/** + * gst_element_query: + * @element: The element to perform the query on. + * @type: The query type + * @format: a pointer to hold the format of the result + * @value: a pointer to the value of the result + * + * Perform a query on the given element. If the format is set + * to GST_FORMAT_DEFAULT and this function returns TRUE, the + * format pointer will hold the default format. + * For element that don't implement a query handler, this function + * forwards the query to a random connected sinkpad of this element. + * + * Returns: TRUE if the query could be performed. + */ gboolean gst_element_query (GstElement *element, GstPadQueryType type, GstFormat *format, gint64 *value) @@ -1696,8 +1731,6 @@ gst_element_query (GstElement *element, GstPadQueryType type, return FALSE; } - - /** * gst_element_error: * @element: Element with the error diff --git a/gst/gstevent.c b/gst/gstevent.c index 89a4af6986..eb5cb4a4de 100644 --- a/gst/gstevent.c +++ b/gst/gstevent.c @@ -149,7 +149,6 @@ gst_event_free (GstEvent* event) * gst_event_new_seek: * @type: The type of the seek event * @offset: The offset of the seek - * @flush: A boolean indicating a flush has to be performed as well * * Allocate a new seek event with the given parameters. * @@ -167,15 +166,25 @@ gst_event_new_seek (GstSeekType type, gint64 offset) return event; } +/** + * gst_event_new_discontinuous: + * @new_media: A flag indicating a new media type starts + * @format1: The format of the discont value + * @...: more discont values and formats + * + * Allocate a new discontinuous event with the geven format/value pairs. + * + * Returns: A new discontinuous event. + */ GstEvent* -gst_event_new_discontinuous (gboolean flush, GstSeekType format1, ...) +gst_event_new_discontinuous (gboolean new_media, GstSeekType format1, ...) { va_list var_args; GstEvent *event; gint count = 0; event = gst_event_new (GST_EVENT_DISCONTINUOUS); - GST_EVENT_DISCONT_FLUSH (event) = flush; + GST_EVENT_DISCONT_NEW_MEDIA (event) = new_media; va_start (var_args, format1); @@ -195,8 +204,18 @@ gst_event_new_discontinuous (gboolean flush, GstSeekType format1, ...) return event; } +/** + * gst_event_discont_get_value: + * @event: The event to query + * @format: The format of the discont value + * @value: A pointer to the value + * + * Get the value for the given format in the dicont event. + * + * Returns: TRUE if the discont event caries the specified format/value pair. + */ gboolean -gst_event_discont_get_value (GstEvent *event, GstSeekType type, gint64 *value) +gst_event_discont_get_value (GstEvent *event, GstFormat format, gint64 *value) { gint i, n; @@ -206,7 +225,7 @@ gst_event_discont_get_value (GstEvent *event, GstSeekType type, gint64 *value) n = GST_EVENT_DISCONT_OFFSET_LEN (event); for (i = 0; i < n; i++) { - if (GST_EVENT_DISCONT_OFFSET(event,i).format == type) { + if (GST_EVENT_DISCONT_OFFSET(event,i).format == format) { *value = GST_EVENT_DISCONT_OFFSET(event,i).value; return TRUE; } diff --git a/gst/gstevent.h b/gst/gstevent.h index 475b8a185e..4f5e7323d3 100644 --- a/gst/gstevent.h +++ b/gst/gstevent.h @@ -89,7 +89,7 @@ typedef struct #define GST_EVENT_SEEK_OFFSET(event) (GST_EVENT(event)->event_data.seek.offset) #define GST_EVENT_SEEK_ACCURACY(event) (GST_EVENT(event)->event_data.seek.accuracy) -#define GST_EVENT_DISCONT_FLUSH(event) (GST_EVENT(event)->event_data.discont.flush) +#define GST_EVENT_DISCONT_NEW_MEDIA(event) (GST_EVENT(event)->event_data.discont.new_media) #define GST_EVENT_DISCONT_OFFSET(event,i) (GST_EVENT(event)->event_data.discont.offsets[i]) #define GST_EVENT_DISCONT_OFFSET_LEN(event) (GST_EVENT(event)->event_data.discont.noffsets) @@ -109,7 +109,7 @@ struct _GstEvent { struct { GstFormatValue offsets[8]; gint noffsets; - gboolean flush; + gboolean new_media; } discont; } event_data; }; diff --git a/gst/gstpad.c b/gst/gstpad.c index 9bfcb1c123..f6f56b9857 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -502,6 +502,23 @@ gst_pad_set_query_function (GstPad *pad, GstPadQueryFunction query) GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (query)); } +/** + * gst_pad_set_internal_connection_function: + * @pad: the pad to set the internal connection function for + * @intconn: the internal connection function + * + * Set the given internal connection function for the pad. + */ +void +gst_pad_set_internal_connection_function (GstPad *pad, GstPadIntConnFunction intconn) +{ + g_return_if_fail (pad != NULL); + g_return_if_fail (GST_IS_REAL_PAD (pad)); + + GST_RPAD_INTCONNFUNC(pad) = intconn; + GST_DEBUG (GST_CAT_PADS, "internal connection for %s:%s set to %s", + GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (intconn)); +} /** * gst_pad_set_connect_function: diff --git a/gst/gstparse.c b/gst/gstparse.c index bd16e1fdb0..835a0f1111 100644 --- a/gst/gstparse.c +++ b/gst/gstparse.c @@ -439,10 +439,12 @@ pipeline_from_graph (graph_t *g, GError **error) /** * gst_parse_launchv: * @argv: null-terminated array of arguments + * @error: pointer to GError * * Create a new pipeline based on command line syntax. * - * Returns: a new pipeline on success, NULL on failure + * Returns: a new pipeline on success, NULL on failure and error + * will contain the error message. */ GstBin * gst_parse_launchv (const gchar **argv, GError **error) @@ -511,6 +513,7 @@ void _gst_parse_unescape (gchar *str) /** * gst_parse_launch: * @pipeline_description: the command line describing the pipeline + * @error: the error message in case of a failure * * Create a new pipeline based on command line syntax. * diff --git a/gst/gstplugin.c b/gst/gstplugin.c index d73b6bf0d0..2ceac5f7f4 100644 --- a/gst/gstplugin.c +++ b/gst/gstplugin.c @@ -116,6 +116,14 @@ gst_plugin_register_func (GstPluginDesc *desc, GstPlugin *plugin, GModule *modul return plugin; } +/** + * gst_plugin_new: + * @filename: The filename of the plugin + * + * Creates a plugin from the given filename + * + * Returns: A new GstPlugin object + */ GstPlugin* gst_plugin_new (const gchar *filename) { @@ -331,6 +339,16 @@ gst_plugin_is_loaded (GstPlugin *plugin) return (plugin->module != NULL); } +/** + * gst_plugin_find_feature: + * @plugin: plugin to get the feature from + * @name: The name of the feature to find + * @type: The type of the feature to find + * + * Find a feature of the given name and type in the given plugin. + * + * Returns: a GstPluginFeature or NULL if the feature was not found. + */ GstPluginFeature* gst_plugin_find_feature (GstPlugin *plugin, const gchar *name, GType type) { diff --git a/gst/gstregistry.c b/gst/gstregistry.c index aaa1b6c466..7da950bb10 100644 --- a/gst/gstregistry.c +++ b/gst/gstregistry.c @@ -194,6 +194,7 @@ gst_registry_unload (GstRegistry *registry) /** * gst_registry_add_path: * @registry: the registry to add the path to + * @path: the path to add to the registry * * Add the given path to the registry. The syntax of the * path is specific to the registry. If the path has already been @@ -664,119 +665,3 @@ gst_registry_pool_get_prefered (GstRegistryFlags flags) return NULL; } - - -static gchar *gst_registry_option = NULL; - -/* save the registry specified as an option */ -void -gst_registry_option_set (const gchar *registry) -{ - gst_registry_option = g_strdup (registry); - return; -} - -/* decide if we're going to use the global registry or not - * - if root, use global - * - if not root : - * - if user can write to global, use global - * - else use local - */ -gboolean -gst_registry_use_global (void) -{ - /* struct stat reg_stat; */ - FILE *reg; - - if (getuid () == 0) return TRUE; /* root always uses global */ - - /* check if we can write to the global registry somehow */ - reg = fopen (GLOBAL_REGISTRY_FILE, "a"); - if (reg == NULL) { return FALSE; } - else - { - /* we can write to it, do so for kicks */ - fclose (reg); - } - - /* we can write to it, so now see if we can write in the dir as well */ - if (access (GLOBAL_REGISTRY_DIR, W_OK) == 0) return TRUE; - - return FALSE; -} - -/* get the data that tells us where we can write the registry - * Allocate, fill in the GstRegistryWrite struct according to - * current situation, and return it */ -GstRegistryWrite * -gst_registry_write_get () -{ - GstRegistryWrite *gst_reg = g_malloc (sizeof (GstRegistryWrite)); - - /* if a registry is specified on command line, use that one */ - if (gst_registry_option) - { - /* FIXME: maybe parse the dir from file ? */ - gst_reg->dir = NULL; - gst_reg->file = gst_registry_option; - /* we cannot use the temp dir since the move needs to be on same device */ - gst_reg->tmp_file = g_strdup_printf ("%s.tmp", gst_registry_option); - } - else if (g_getenv ("GST_REGISTRY")) - { - gst_reg->dir = NULL; - gst_reg->file = g_strdup (g_getenv ("GST_REGISTRY")); - gst_reg->tmp_file = g_strdup_printf ("%s.tmp", g_getenv ("GST_REGISTRY")); - } - else - { - if (gst_registry_use_global ()) - { - gst_reg->dir = g_strdup (GLOBAL_REGISTRY_DIR); - gst_reg->file = g_strdup (GLOBAL_REGISTRY_FILE); - gst_reg->tmp_file = g_strdup (GLOBAL_REGISTRY_FILE_TMP); - } - else - { - gchar *homedir = (gchar *) g_get_home_dir (); - - gst_reg->dir = g_strjoin ("/", homedir, LOCAL_REGISTRY_DIR, NULL); - gst_reg->file = g_strjoin ("/", homedir, LOCAL_REGISTRY_FILE, NULL); - gst_reg->tmp_file = g_strjoin ("/", homedir, LOCAL_REGISTRY_FILE_TMP, NULL); - } - } - return gst_reg; -} - -/* fill in the GstRegistryRead struct according to current situation */ -GstRegistryRead * -gst_registry_read_get () -{ - GstRegistryRead *gst_reg = g_new0 (GstRegistryRead, 1); - - /* if a registry is specified on command line, use that one */ - if (gst_registry_option) - { - /* FIXME: maybe parse the dir from file ? */ - gst_reg->local_reg = NULL; - gst_reg->global_reg = gst_registry_option; - } - else if (g_getenv ("GST_REGISTRY")) - { - gst_reg->local_reg = NULL; - gst_reg->global_reg = g_strdup (g_getenv ("GST_REGISTRY")); - } - else - { - gchar *homedir = (gchar *) g_get_home_dir (); - gst_reg->local_reg = g_strjoin ("/", homedir, LOCAL_REGISTRY_FILE, NULL); - if (g_file_test (gst_reg->local_reg, G_FILE_TEST_EXISTS) == FALSE) - { - /* it does not exist, so don't read from it */ - g_free (gst_reg->local_reg); - gst_reg->local_reg = NULL; - } - gst_reg->global_reg = g_strdup (GLOBAL_REGISTRY_FILE); - } - return gst_reg; -} diff --git a/gst/gstregistry.h b/gst/gstregistry.h index 126cc5423f..098dfbe4d7 100644 --- a/gst/gstregistry.h +++ b/gst/gstregistry.h @@ -45,24 +45,6 @@ G_BEGIN_DECLS -typedef struct _GstRegistryWrite GstRegistryWrite; -struct _GstRegistryWrite { - gchar *dir; - gchar *file; - gchar *tmp_file; -}; - -typedef struct _GstRegistryRead GstRegistryRead; -struct _GstRegistryRead { - gchar *global_reg; - gchar *local_reg; -}; - -GstRegistryWrite *gst_registry_write_get (void); -GstRegistryRead *gst_registry_read_get (void); -void gst_registry_option_set (const gchar *registry); - - typedef enum { GST_REGISTRY_OK = (0), GST_REGISTRY_LOAD_ERROR = (1 << 1), diff --git a/gst/gstscheduler.c b/gst/gstscheduler.c index 9a8cedc9f6..e61d9a2091 100644 --- a/gst/gstscheduler.c +++ b/gst/gstscheduler.c @@ -549,6 +549,7 @@ gst_scheduler_auto_clock (GstScheduler *sched) * @element: the element that wants to wait * @clock: the clock to use * @time: the time to wait for + * @jitter: the time difference between requested time and actual time * * Wait till the clock reaches a specific time * diff --git a/plugins/elements/gstfilesrc.c b/plugins/elements/gstfilesrc.c index 3fc7b50571..f06484ac31 100644 --- a/plugins/elements/gstfilesrc.c +++ b/plugins/elements/gstfilesrc.c @@ -453,7 +453,7 @@ gst_filesrc_get (GstPad *pad) src->seek_happened = FALSE; GST_DEBUG (GST_CAT_EVENT, "filesrc sending discont\n"); event = gst_event_new_discontinuous (FALSE, GST_FORMAT_BYTES, src->curoffset, NULL); - GST_EVENT_DISCONT_FLUSH (event) = src->need_flush; + GST_EVENT_DISCONT_NEW_MEDIA (event) = FALSE; src->need_flush = FALSE; return GST_BUFFER (event); }