*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
*/
/**
* @name: the name of the argument to set
* @value: the string value to set
*
- * Convertes the string value to the type of the objects argument and
+ * Converts the string value to the type of the objects argument and
* sets the argument with it.
*
* Note that this function silently returns if @object has no property named
* Returns: A constantly incrementing 32-bit unsigned integer, which might
* overflow back to 0 at some point. Use gst_util_seqnum_compare() to make sure
* you handle wraparound correctly.
- *
- * Since: 0.10.22
*/
guint32
gst_util_seqnum_next (void)
*
* Returns: A negative number if @s1 is before @s2, 0 if they are equal, or a
* positive number if @s1 is after @s2.
- *
- * Since: 0.10.22
*/
gint32
gst_util_seqnum_compare (guint32 s1, guint32 s2)
#include "gstpad.h"
-static void
-string_append_indent (GString * str, gint count)
-{
- gint xx;
-
- for (xx = 0; xx < count; xx++)
- g_string_append_c (str, ' ');
-}
-
-/**
- * gst_print_pad_caps:
- * @buf: the buffer to print the caps in
- * @indent: initial indentation
- * @pad: (transfer none): the pad to print the caps from
- *
- * Write the pad capabilities in a human readable format into
- * the given GString.
- */
-void
-gst_print_pad_caps (GString * buf, gint indent, GstPad * pad)
-{
- GstCaps *caps;
-
- caps = gst_pad_get_current_caps (pad);
-
- if (!caps) {
- string_append_indent (buf, indent);
- g_string_printf (buf, "%s:%s has no capabilities",
- GST_DEBUG_PAD_NAME (pad));
- } else {
- char *s;
-
- s = gst_caps_to_string (caps);
- g_string_append (buf, s);
- g_free (s);
-
- gst_caps_unref (caps);
- }
-}
-
-/**
- * gst_print_element_args:
- * @buf: the buffer to print the args in
- * @indent: initial indentation
- * @element: (transfer none): the element to print the args of
- *
- * Print the element argument in a human readable format in the given
- * GString.
- */
-void
-gst_print_element_args (GString * buf, gint indent, GstElement * element)
-{
- guint width;
- GValue value = { 0, }; /* the important thing is that value.type = 0 */
- gchar *str = NULL;
- GParamSpec *spec, **specs, **walk;
-
- specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (element), NULL);
-
- width = 0;
- for (walk = specs; *walk; walk++) {
- spec = *walk;
- if (width < strlen (spec->name))
- width = strlen (spec->name);
- }
-
- for (walk = specs; *walk; walk++) {
- spec = *walk;
-
- if (spec->flags & G_PARAM_READABLE) {
- g_value_init (&value, spec->value_type);
- g_object_get_property (G_OBJECT (element), spec->name, &value);
- str = g_strdup_value_contents (&value);
- g_value_unset (&value);
- } else {
- str = g_strdup ("Parameter not readable.");
- }
-
- string_append_indent (buf, indent);
- g_string_append (buf, spec->name);
- string_append_indent (buf, 2 + width - strlen (spec->name));
- g_string_append (buf, str);
- g_string_append_c (buf, '\n');
-
- g_free (str);
- }
-
- g_free (specs);
-}
-
/**
* gst_element_create_all_pads:
* @element: (transfer none): a #GstElement to create pads for
* Retrieves a pad template from @element that is compatible with @compattempl.
* Pads from compatible templates can be linked together.
*
- * Returns: (transfer none): a compatible #GstPadTemplate, or NULL if none
+ * Returns: (transfer none): a compatible #GstPadTemplate, or %NULL if none
* was found. No unreferencing is necessary.
*/
GstPadTemplate *
* gst_element_get_compatible_pad:
* @element: (transfer none): a #GstElement in which the pad should be found.
* @pad: (transfer none): the #GstPad to find a compatible one for.
- * @caps: the #GstCaps to use as a filter.
+ * @caps: (allow-none): the #GstCaps to use as a filter.
*
* Looks for an unlinked pad to which the given pad can link. It is not
* guaranteed that linking the pads will work, though it should work in most
*
* Returns: (transfer none): a string with the name of the state
* result.
- *
- * Since: 0.10.11
*/
const gchar *
gst_element_state_change_return_get_name (GstStateChangeReturn state_ret)
* Checks if the factory can sink all possible capabilities.
*
* Returns: %TRUE if the caps are fully compatible.
- *
- * Since: 0.10.33
*/
gboolean
gst_element_factory_can_sink_all_caps (GstElementFactory * factory,
* Checks if the factory can src all possible capabilities.
*
* Returns: %TRUE if the caps are fully compatible.
- *
- * Since: 0.10.33
*/
gboolean
gst_element_factory_can_src_all_caps (GstElementFactory * factory,
* Checks if the factory can sink any possible capability.
*
* Returns: %TRUE if the caps have a common subset.
- *
- * Since: 0.10.33
*/
gboolean
gst_element_factory_can_sink_any_caps (GstElementFactory * factory,
* Checks if the factory can src any possible capability.
*
* Returns: %TRUE if the caps have a common subset.
- *
- * Since: 0.10.33
*/
gboolean
gst_element_factory_can_src_any_caps (GstElementFactory * factory,
* gst_element_link_pads_full:
* @src: a #GstElement containing the source pad.
* @srcpadname: (allow-none): the name of the #GstPad in source element
- * or NULL for any pad.
+ * or %NULL for any pad.
* @dest: (transfer none): the #GstElement containing the destination pad.
* @destpadname: (allow-none): the name of the #GstPad in destination element,
- * or NULL for any pad.
+ * or %NULL for any pad.
* @flags: the #GstPadLinkCheck to be performed when linking pads.
*
* Links the two named pads of the source and destination elements.
*
* This is a convenience function for gst_pad_link_full().
*
- * Returns: TRUE if the pads could be linked, FALSE otherwise.
- *
- * Since: 0.10.30
+ * Returns: %TRUE if the pads could be linked, %FALSE otherwise.
*/
gboolean
gst_element_link_pads_full (GstElement * src, const gchar * srcpadname,
* gst_element_link_pads:
* @src: a #GstElement containing the source pad.
* @srcpadname: (allow-none): the name of the #GstPad in source element
- * or NULL for any pad.
+ * or %NULL for any pad.
* @dest: (transfer none): the #GstElement containing the destination pad.
* @destpadname: (allow-none): the name of the #GstPad in destination element,
- * or NULL for any pad.
+ * or %NULL for any pad.
*
* Links the two named pads of the source and destination elements.
* Side effect is that if one of the pads has no parent, it becomes a
* child of the parent of the other element. If they have different
* parents, the link fails.
*
- * Returns: TRUE if the pads could be linked, FALSE otherwise.
+ * Returns: %TRUE if the pads could be linked, %FALSE otherwise.
*/
gboolean
gst_element_link_pads (GstElement * src, const gchar * srcpadname,
* gst_element_link_pads_filtered:
* @src: a #GstElement containing the source pad.
* @srcpadname: (allow-none): the name of the #GstPad in source element
- * or NULL for any pad.
+ * or %NULL for any pad.
* @dest: (transfer none): the #GstElement containing the destination pad.
* @destpadname: (allow-none): the name of the #GstPad in destination element
- * or NULL for any pad.
+ * or %NULL for any pad.
* @filter: (transfer none) (allow-none): the #GstCaps to filter the link,
- * or #NULL for no filter.
+ * or %NULL for no filter.
*
* Links the two named pads of the source and destination elements. Side effect
* is that if one of the pads has no parent, it becomes a child of the parent of
* the other element. If they have different parents, the link fails. If @caps
- * is not #NULL, makes sure that the caps of the link is a subset of @caps.
+ * is not %NULL, makes sure that the caps of the link is a subset of @caps.
*
- * Returns: TRUE if the pads could be linked, FALSE otherwise.
+ * Returns: %TRUE if the pads could be linked, %FALSE otherwise.
*/
gboolean
gst_element_link_pads_filtered (GstElement * src, const gchar * srcpadname,
* Make sure you have added your elements to a bin or pipeline with
* gst_bin_add() before trying to link them.
*
- * Returns: TRUE if the elements could be linked, FALSE otherwise.
+ * Returns: %TRUE if the elements could be linked, %FALSE otherwise.
*/
gboolean
gst_element_link (GstElement * src, GstElement * dest)
* gst_element_link_many:
* @element_1: (transfer none): the first #GstElement in the link chain.
* @element_2: (transfer none): the second #GstElement in the link chain.
- * @...: the NULL-terminated list of elements to link in order.
+ * @...: the %NULL-terminated list of elements to link in order.
*
* Chain together a series of elements. Uses gst_element_link().
* Make sure you have added your elements to a bin or pipeline with
* gst_bin_add() before trying to link them.
*
- * Returns: TRUE on success, FALSE otherwise.
+ * Returns: %TRUE on success, %FALSE otherwise.
*/
gboolean
gst_element_link_many (GstElement * element_1, GstElement * element_2, ...)
* @src: a #GstElement containing the source pad.
* @dest: (transfer none): the #GstElement containing the destination pad.
* @filter: (transfer none) (allow-none): the #GstCaps to filter the link,
- * or #NULL for no filter.
+ * or %NULL for no filter.
*
* Links @src to @dest using the given caps as filtercaps.
* The link must be from source to
* Make sure you have added your elements to a bin or pipeline with
* gst_bin_add() before trying to link them.
*
- * Returns: TRUE if the pads could be linked, FALSE otherwise.
+ * Returns: %TRUE if the pads could be linked, %FALSE otherwise.
*/
gboolean
gst_element_link_filtered (GstElement * src, GstElement * dest,
* gst_element_unlink_many:
* @element_1: (transfer none): the first #GstElement in the link chain.
* @element_2: (transfer none): the second #GstElement in the link chain.
- * @...: the NULL-terminated list of elements to unlink in order.
+ * @...: the %NULL-terminated list of elements to unlink in order.
*
* Unlinks a series of elements. Uses gst_element_unlink().
*/
* @element: a #GstElement to invoke the position query on.
* @format: the #GstFormat requested
* @cur: (out) (allow-none): a location in which to store the current
- * position, or NULL.
+ * position, or %NULL.
+ *
+ * Queries an element (usually top-level pipeline or playbin element) for the
+ * stream position in nanoseconds. This will be a value between 0 and the
+ * stream duration (if the stream duration is known). This query will usually
+ * only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING
+ * state). The application will receive an ASYNC_DONE message on the pipeline
+ * bus when that is the case.
*
- * Queries an element for the stream position. If one repeatedly calls this
- * function one can also create and reuse it in gst_element_query().
+ * If one repeatedly calls this function one can also create a query and reuse
+ * it in gst_element_query().
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_element_query_position (GstElement * element, GstFormat format,
* gst_element_query_duration:
* @element: a #GstElement to invoke the duration query on.
* @format: the #GstFormat requested
- * @duration: (out): A location in which to store the total duration, or NULL.
+ * @duration: (out) (allow-none): A location in which to store the total duration, or %NULL.
+ *
+ * Queries an element (usually top-level pipeline or playbin element) for the
+ * total stream duration in nanoseconds. This query will only work once the
+ * pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application
+ * will receive an ASYNC_DONE message on the pipeline bus when that is the case.
*
- * Queries an element for the total stream duration.
+ * If the duration changes for some reason, you will get a DURATION_CHANGED
+ * message on the pipeline bus, in which case you should re-query the duration
+ * using this function.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_element_query_duration (GstElement * element, GstFormat format,
*
* Queries an element to convert @src_val in @src_format to @dest_format.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_element_query_convert (GstElement * element, GstFormat src_format,
}
/**
- * gst_element_seek_simple
+ * gst_element_seek_simple:
* @element: a #GstElement to seek on
* @format: a #GstFormat to execute the seek in, such as #GST_FORMAT_TIME
* @seek_flags: seek options; playback applications will usually want to use
* PAUSED. If the element supports seek in READY, it will always return %TRUE when
* it receives the event in the READY state.
*
- * Returns: %TRUE if the seek operation succeeded (the seek might not always be
- * executed instantly though)
- *
- * Since: 0.10.7
+ * Returns: %TRUE if the seek operation succeeded. Flushing seeks will trigger a
+ * preroll, which will emit %GST_MESSAGE_ASYNC_DONE.
*/
gboolean
gst_element_seek_simple (GstElement * element, GstFormat format,
* @pad: the pad to use
*
* A helper function you can use that sets the FIXED_CAPS flag
- * This way the default getcaps function will always return the negotiated caps
+ * This way the default CAPS query will always return the negotiated caps
* or in case the pad is not negotiated, the padtemplate caps.
*
- * Use this function on a pad that, once gst_pad_set_caps() has been called
- * on it, cannot be renegotiated to something else.
+ * The negotiated caps are the caps of the last CAPS event that passed on the
+ * pad. Use this function on a pad that, once it negotiated to a CAPS, cannot
+ * be renegotiated to something else.
*/
void
gst_pad_use_fixed_caps (GstPad * pad)
* @pad: a pad
*
* Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or
- * its parent is not an element, return NULL.
+ * its parent is not an element, return %NULL.
*
* Returns: (transfer full): the parent of the pad. The caller has a
* reference on the parent, so unref when you're finished with it.
* gst_object_default_error:
* @source: the #GstObject that initiated the error.
* @error: (in): the GError.
- * @debug: (in) (allow-none): an additional debug information string, or NULL
+ * @debug: (in) (allow-none): an additional debug information string, or %NULL
*
* A default error function that uses g_printerr() to display the error message
* and the optional debug sting..
* @element_1: (transfer full): the #GstElement element to add to the bin
* @...: (transfer full): additional elements to add to the bin
*
- * Adds a NULL-terminated list of elements to a bin. This function is
+ * Adds a %NULL-terminated list of elements to a bin. This function is
* equivalent to calling gst_bin_add() for each member of the list. The return
* value of each gst_bin_add() is ignored.
*/
* gst_bin_remove_many:
* @bin: a #GstBin
* @element_1: (transfer none): the first #GstElement to remove from the bin
- * @...: (transfer none): NULL-terminated list of elements to remove from the bin
+ * @...: (transfer none): %NULL-terminated list of elements to remove from the bin
*
* Remove a list of elements from a bin. This function is equivalent
* to calling gst_bin_remove() with each member of the list.
* @pad: a #GstPad to proxy.
* @query: an ACCEPT_CAPS #GstQuery.
*
- * Calls gst_pad_accept_caps() for all internally linked pads of @pad and
+ * Checks if all internally linked pads of @pad accepts the caps in @query and
* returns the intersection of the results.
*
* This function is useful as a default accept caps query function for an element
* that can handle any stream format, but requires caps that are acceptable for
- * all oposite pads.
+ * all opposite pads.
*
- * Returns: TRUE if @query could be executed
+ * Returns: %TRUE if @query could be executed
*/
gboolean
gst_pad_proxy_query_accept_caps (GstPad * pad, GstQuery * query)
data.query = query;
/* value to hold the return, by default it holds TRUE */
+ /* FIXME: TRUE is wrong when there are no pads */
data.ret = TRUE;
gst_pad_forward (pad, (GstPadForwardFunction) query_accept_caps_func, &data);
gst_query_set_accept_caps_result (query, data.ret);
- return TRUE;
+ GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "proxying accept caps query: %d",
+ data.ret);
+
+ return data.ret;
}
typedef struct
* @pad: a #GstPad to proxy.
* @query: a CAPS #GstQuery.
*
- * Calls gst_pad_query_caps() for all internally linked pads fof @pad and returns
+ * Calls gst_pad_query_caps() for all internally linked pads of @pad and returns
* the intersection of the results.
*
* This function is useful as a default caps query function for an element
* that can handle any stream format, but requires all its pads to have
* the same caps. Two such elements are tee and adder.
*
- * Returns: TRUE if @query could be executed
+ * Returns: %TRUE if @query could be executed
*/
gboolean
gst_pad_proxy_query_caps (GstPad * pad, GstQuery * query)
{
- GstCaps *templ, *intersected;
+ GstCaps *filter, *templ, *result;
QueryCapsData data;
g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
GST_DEBUG_PAD_NAME (pad));
data.query = query;
- /* value to hold the return, by default it holds ANY */
- data.ret = gst_caps_new_any ();
+
+ /* value to hold the return, by default it holds the filter or ANY */
+ gst_query_parse_caps (query, &filter);
+ data.ret = filter ? gst_caps_ref (filter) : gst_caps_new_any ();
gst_pad_forward (pad, (GstPadForwardFunction) query_caps_func, &data);
templ = gst_pad_get_pad_template_caps (pad);
- intersected = gst_caps_intersect (data.ret, templ);
+ result = gst_caps_intersect (data.ret, templ);
gst_caps_unref (data.ret);
gst_caps_unref (templ);
- gst_query_set_caps_result (query, intersected);
- gst_caps_unref (intersected);
+ gst_query_set_caps_result (query, result);
+ gst_caps_unref (result);
+ /* FIXME: return something depending on the processing */
return TRUE;
}
* gst_pad_query_position:
* @pad: a #GstPad to invoke the position query on.
* @format: the #GstFormat requested
- * @cur: (out): A location in which to store the current position, or NULL.
+ * @cur: (out) (allow-none): A location in which to store the current position, or %NULL.
*
* Queries a pad for the stream position.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_pad_query_position (GstPad * pad, GstFormat format, gint64 * cur)
* Must be a sink pad.
* @format: the #GstFormat requested
* @cur: (out) (allow-none): a location in which to store the current
- * position, or NULL.
+ * position, or %NULL.
*
* Queries the peer of a given sink pad for the stream position.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_pad_peer_query_position (GstPad * pad, GstFormat format, gint64 * cur)
gboolean ret = FALSE;
g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
- g_return_val_if_fail (GST_PAD_IS_SINK (pad), FALSE);
g_return_val_if_fail (format != GST_FORMAT_UNDEFINED, FALSE);
query = gst_query_new_position (format);
* @pad: a #GstPad to invoke the duration query on.
* @format: the #GstFormat requested
* @duration: (out) (allow-none): a location in which to store the total
- * duration, or NULL.
+ * duration, or %NULL.
*
* Queries a pad for the total stream duration.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_pad_query_duration (GstPad * pad, GstFormat format, gint64 * duration)
* Must be a sink pad.
* @format: the #GstFormat requested
* @duration: (out) (allow-none): a location in which to store the total
- * duration, or NULL.
+ * duration, or %NULL.
*
* Queries the peer pad of a given sink pad for the total stream duration.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_pad_peer_query_duration (GstPad * pad, GstFormat format, gint64 * duration)
*
* Queries a pad to convert @src_val in @src_format to @dest_format.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_pad_query_convert (GstPad * pad, GstFormat src_format, gint64 src_val,
* Queries the peer pad of a given sink pad to convert @src_val in @src_format
* to @dest_format.
*
- * Returns: TRUE if the query could be performed.
+ * Returns: %TRUE if the query could be performed.
*/
gboolean
gst_pad_peer_query_convert (GstPad * pad, GstFormat src_format, gint64 src_val,
/**
* gst_pad_query_caps:
* @pad: a #GstPad to get the capabilities of.
- * @filter: (allow-none): suggested #GstCaps, or NULL
+ * @filter: (allow-none): suggested #GstCaps, or %NULL
*
* Gets the capabilities this pad can produce or consume.
- * Note that this method doesn't necessarily return the caps set by
- * gst_pad_set_caps() - use gst_pad_get_current_caps() for that instead.
+ * Note that this method doesn't necessarily return the caps set by sending a
+ * gst_event_new_caps() - use gst_pad_get_current_caps() for that instead.
* gst_pad_query_caps returns all possible caps a pad can operate with, using
* the pad's CAPS query function, If the query fails, this function will return
- * @filter, if not #NULL, otherwise ANY.
+ * @filter, if not %NULL, otherwise ANY.
*
* When called on sinkpads @filter contains the caps that
* upstream could produce in the order preferred by upstream. When
* called on srcpads @filter contains the caps accepted by
- * downstream in the preffered order. @filter might be %NULL but
+ * downstream in the preferred order. @filter might be %NULL but
* if it is not %NULL the returned caps will be a subset of @filter.
*
* Note that this function does not return writable #GstCaps, use
/**
* gst_pad_peer_query_caps:
* @pad: a #GstPad to get the capabilities of.
- * @filter: (allow-none): a #GstCaps filter, or NULL.
+ * @filter: (allow-none): a #GstCaps filter, or %NULL.
*
* Gets the capabilities of the peer connected to this pad. Similar to
* gst_pad_query_caps().
* When called on srcpads @filter contains the caps that
* upstream could produce in the order preferred by upstream. When
* called on sinkpads @filter contains the caps accepted by
- * downstream in the preffered order. @filter might be %NULL but
+ * downstream in the preferred order. @filter might be %NULL but
* if it is not %NULL the returned caps will be a subset of @filter.
*
- * Returns: the caps of the peer pad with incremented ref-count. This function
- * returns %NULL when there is no peer pad.
+ * Returns: the caps of the peer pad with incremented ref-count. When there is
+ * no peer pad, this function returns @filter or, when @filter is %NULL, ANY
+ * caps.
*/
GstCaps *
gst_pad_peer_query_caps (GstPad * pad, GstCaps * filter)
*
* Check if the given pad accepts the caps.
*
- * Returns: TRUE if the pad can accept the caps.
+ * Returns: %TRUE if the pad can accept the caps.
*/
gboolean
gst_pad_query_accept_caps (GstPad * pad, GstCaps * caps)
g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
g_return_val_if_fail (GST_IS_CAPS (caps), FALSE);
- GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "accept caps of %p", caps);
+ GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "accept caps of %"
+ GST_PTR_FORMAT, caps);
query = gst_query_new_accept_caps (caps);
if (gst_pad_query (pad, query)) {
* @caps: a #GstCaps to check on the pad
*
* Check if the peer of @pad accepts @caps. If @pad has no peer, this function
- * returns TRUE.
+ * returns %TRUE.
*
- * Returns: TRUE if the peer of @pad can accept the caps or @pad has no peer.
+ * Returns: %TRUE if the peer of @pad can accept the caps or @pad has no peer.
*/
gboolean
gst_pad_peer_query_accept_caps (GstPad * pad, GstCaps * caps)
*
* Recursively looks for elements with an unlinked pad of the given
* direction within the specified bin and returns an unlinked pad
- * if one is found, or NULL otherwise. If a pad is found, the caller
+ * if one is found, or %NULL otherwise. If a pad is found, the caller
* owns a reference to it and should use gst_object_unref() on the
* pad when it is not needed any longer.
*
- * Returns: (transfer full): unlinked pad of the given direction, or NULL.
- *
- * Since: 0.10.20
+ * Returns: (transfer full): unlinked pad of the given direction, %NULL.
*/
GstPad *
gst_bin_find_unlinked_pad (GstBin * bin, GstPadDirection direction)
* @bin_description: command line describing the bin
* @ghost_unlinked_pads: whether to automatically create ghost pads
* for unlinked source or sink pads within the bin
- * @err: where to store the error message in case of an error, or NULL
+ * @err: where to store the error message in case of an error, or %NULL
*
* This is a convenience wrapper around gst_parse_launch() to create a
* #GstBin from a gst-launch-style pipeline description. See
* and want them all ghosted, you will have to create the ghost pads
* yourself).
*
- * Returns: (transfer floating): a newly-created bin, or NULL if an error occurred.
- *
- * Since: 0.10.3
+ * Returns: (transfer floating) (type Gst.Bin): a newly-created bin,
+ * or %NULL if an error occurred.
*/
GstElement *
gst_parse_bin_from_description (const gchar * bin_description,
* @context: (transfer none) (allow-none): a parse context allocated with
* gst_parse_context_new(), or %NULL
* @flags: parsing options, or #GST_PARSE_FLAG_NONE
- * @err: where to store the error message in case of an error, or NULL
+ * @err: where to store the error message in case of an error, or %NULL
*
* This is a convenience wrapper around gst_parse_launch() to create a
* #GstBin from a gst-launch-style pipeline description. See
* and want them all ghosted, you will have to create the ghost pads
* yourself).
*
- * Returns: (transfer full): a newly-created bin, or NULL if an error occurred.
- *
- * Since: 0.10.20
+ * Returns: (transfer full) (type Gst.Element): a newly-created element, which
+ * is guaranteed to be a bin unless GST_FLAG_NO_SINGLE_ELEMENT_BINS was
+ * passed, or %NULL if an error occurred.
*/
GstElement *
gst_parse_bin_from_description_full (const gchar * bin_description,
{
#ifndef GST_DISABLE_PARSE
GstPad *pad = NULL;
+ GstElement *element;
GstBin *bin;
gchar *desc;
GST_DEBUG ("Making bin from description '%s'", bin_description);
/* parse the pipeline to a bin */
- desc = g_strdup_printf ("bin.( %s )", bin_description);
- bin = (GstBin *) gst_parse_launch_full (desc, context, flags, err);
- g_free (desc);
+ if (flags & GST_PARSE_FLAG_NO_SINGLE_ELEMENT_BINS) {
+ element = gst_parse_launch_full (bin_description, context, flags, err);
+ } else {
+ desc = g_strdup_printf ("bin.( %s )", bin_description);
+ element = gst_parse_launch_full (desc, context, flags, err);
+ g_free (desc);
+ }
- if (bin == NULL || (err && *err != NULL)) {
- if (bin)
- gst_object_unref (bin);
+ if (element == NULL || (err && *err != NULL)) {
+ if (element)
+ gst_object_unref (element);
return NULL;
}
+ if (GST_IS_BIN (element)) {
+ bin = GST_BIN (element);
+ } else {
+ return element;
+ }
+
/* find pads and ghost them if necessary */
if (ghost_unlinked_pads) {
if ((pad = gst_bin_find_unlinked_pad (bin, GST_PAD_SRC))) {
* The timestamp should not be interpreted in any other way.
*
* Returns: the timestamp
- *
- * Since: 0.10.16
*/
GstClockTime
gst_util_get_timestamp (void)
{
-#if defined (HAVE_POSIX_TIMERS) && defined(HAVE_MONOTONIC_CLOCK)
+#if defined (HAVE_POSIX_TIMERS) && defined(HAVE_MONOTONIC_CLOCK) &&\
+ defined (HAVE_CLOCK_GETTIME)
struct timespec now;
clock_gettime (CLOCK_MONOTONIC, &now);
* The complexity of this search function is O(log (num_elements)).
*
* Returns: (transfer none): The address of the found element or %NULL if nothing was found
- *
- * Since: 0.10.23
*/
gpointer
gst_util_array_binary_search (gpointer array, guint num_elements,
* and @b.
*
* Returns: Greatest common divisor of @a and @b
- *
- * Since: 0.10.26
*/
gint
gst_util_greatest_common_divisor (gint a, gint b)
* and @b.
*
* Returns: Greatest common divisor of @a and @b
- *
- * Since: 0.11.0
*/
gint64
gst_util_greatest_common_divisor_int64 (gint64 a, gint64 b)
* @dest: (out): pointer to a #gdouble for the result
*
* Transforms a fraction to a #gdouble.
- *
- * Since: 0.10.26
*/
void
gst_util_fraction_to_double (gint src_n, gint src_d, gdouble * dest)
*
* Transforms a #gdouble to a fraction and simplifies
* the result.
- *
- * Since: 0.10.26
*/
void
gst_util_double_to_fraction (gdouble src, gint * dest_n, gint * dest_d)
* the result in @res_n and @res_d.
*
* Returns: %FALSE on overflow, %TRUE otherwise.
- *
- * Since: 0.10.26
*/
gboolean
gst_util_fraction_multiply (gint a_n, gint a_d, gint b_n, gint b_d,
g_return_val_if_fail (a_d != 0, FALSE);
g_return_val_if_fail (b_d != 0, FALSE);
+ /* early out if either is 0, as its gcd would be 0 */
+ if (a_n == 0 || b_n == 0) {
+ *res_n = 0;
+ *res_d = 1;
+ return TRUE;
+ }
+
gcd = gst_util_greatest_common_divisor (a_n, a_d);
a_n /= gcd;
a_d /= gcd;
* the result in @res_n and @res_d.
*
* Returns: %FALSE on overflow, %TRUE otherwise.
- *
- * Since: 0.10.26
*/
gboolean
gst_util_fraction_add (gint a_n, gint a_d, gint b_n, gint b_d, gint * res_n,
* -1 if a < b, 0 if a = b and 1 if a > b.
*
* Returns: -1 if a < b; 0 if a = b; 1 if a > b.
- *
- * Since: 0.10.31
*/
gint
gst_util_fraction_compare (gint a_n, gint a_d, gint b_n, gint b_d)
/* Should not happen because a_d and b_d are not 0 */
g_return_val_if_reached (0);
}
+
+static gchar *
+gst_pad_create_stream_id_internal (GstPad * pad, GstElement * parent,
+ const gchar * stream_id)
+{
+ GstEvent *upstream_event;
+ gchar *upstream_stream_id = NULL, *new_stream_id;
+ GstPad *sinkpad;
+
+ g_return_val_if_fail (GST_IS_PAD (pad), NULL);
+ g_return_val_if_fail (GST_PAD_IS_SRC (pad), NULL);
+ g_return_val_if_fail (GST_IS_ELEMENT (parent), NULL);
+
+ g_return_val_if_fail (parent->numsinkpads <= 1, NULL);
+
+ /* If the element has multiple source pads it must
+ * provide a stream-id for every source pad, otherwise
+ * all source pads will have the same and are not
+ * distinguishable */
+ g_return_val_if_fail (parent->numsrcpads <= 1 || stream_id, NULL);
+
+ /* First try to get the upstream stream-start stream-id from the sinkpad.
+ * This will only work for non-source elements */
+ sinkpad = gst_element_get_static_pad (parent, "sink");
+ if (sinkpad) {
+ upstream_event =
+ gst_pad_get_sticky_event (sinkpad, GST_EVENT_STREAM_START, 0);
+ if (upstream_event) {
+ const gchar *tmp;
+
+ gst_event_parse_stream_start (upstream_event, &tmp);
+ if (tmp)
+ upstream_stream_id = g_strdup (tmp);
+ gst_event_unref (upstream_event);
+ }
+ gst_object_unref (sinkpad);
+ }
+
+ /* The only case where we don't have an upstream start-start event
+ * here is for source elements */
+ if (!upstream_stream_id) {
+ GstQuery *query;
+
+ /* Try to generate one from the URI query and
+ * if it fails take a random number instead */
+ query = gst_query_new_uri ();
+ if (gst_element_query (parent, query)) {
+ GChecksum *cs;
+ gchar *uri;
+
+ gst_query_parse_uri (query, &uri);
+
+ /* And then generate an SHA256 sum of the URI */
+ cs = g_checksum_new (G_CHECKSUM_SHA256);
+ g_checksum_update (cs, (const guchar *) uri, strlen (uri));
+ g_free (uri);
+ upstream_stream_id = g_strdup (g_checksum_get_string (cs));
+ g_checksum_free (cs);
+ } else {
+ /* Just get some random number if the URI query fails */
+ GST_FIXME_OBJECT (pad, "Creating random stream-id, consider "
+ "implementing a deterministic way of creating a stream-id");
+ upstream_stream_id =
+ g_strdup_printf ("%08x%08x%08x%08x", g_random_int (), g_random_int (),
+ g_random_int (), g_random_int ());
+ }
+
+ gst_query_unref (query);
+ }
+
+ if (stream_id) {
+ new_stream_id = g_strconcat (upstream_stream_id, "/", stream_id, NULL);
+ } else {
+ new_stream_id = g_strdup (upstream_stream_id);
+ }
+
+ g_free (upstream_stream_id);
+
+ return new_stream_id;
+}
+
+/**
+ * gst_pad_create_stream_id_printf_valist:
+ * @pad: A source #GstPad
+ * @parent: Parent #GstElement of @pad
+ * @stream_id: (allow-none): The stream-id
+ * @var_args: parameters for the @stream_id format string
+ *
+ * Creates a stream-id for the source #GstPad @pad by combining the
+ * upstream information with the optional @stream_id of the stream
+ * of @pad. @pad must have a parent #GstElement and which must have zero
+ * or one sinkpad. @stream_id can only be %NULL if the parent element
+ * of @pad has only a single source pad.
+ *
+ * This function generates an unique stream-id by getting the upstream
+ * stream-start event stream ID and appending @stream_id to it. If the
+ * element has no sinkpad it will generate an upstream stream-id by
+ * doing an URI query on the element and in the worst case just uses
+ * a random number. Source elements that don't implement the URI
+ * handler interface should ideally generate a unique, deterministic
+ * stream-id manually instead.
+ *
+ * Returns: A stream-id for @pad. g_free() after usage.
+ */
+gchar *
+gst_pad_create_stream_id_printf_valist (GstPad * pad, GstElement * parent,
+ const gchar * stream_id, va_list var_args)
+{
+ gchar *expanded = NULL, *new_stream_id;
+
+ if (stream_id)
+ expanded = g_strdup_vprintf (stream_id, var_args);
+
+ new_stream_id = gst_pad_create_stream_id_internal (pad, parent, expanded);
+
+ g_free (expanded);
+
+ return new_stream_id;
+}
+
+/**
+ * gst_pad_create_stream_id_printf:
+ * @pad: A source #GstPad
+ * @parent: Parent #GstElement of @pad
+ * @stream_id: (allow-none): The stream-id
+ * @...: parameters for the @stream_id format string
+ *
+ * Creates a stream-id for the source #GstPad @pad by combining the
+ * upstream information with the optional @stream_id of the stream
+ * of @pad. @pad must have a parent #GstElement and which must have zero
+ * or one sinkpad. @stream_id can only be %NULL if the parent element
+ * of @pad has only a single source pad.
+ *
+ * This function generates an unique stream-id by getting the upstream
+ * stream-start event stream ID and appending @stream_id to it. If the
+ * element has no sinkpad it will generate an upstream stream-id by
+ * doing an URI query on the element and in the worst case just uses
+ * a random number. Source elements that don't implement the URI
+ * handler interface should ideally generate a unique, deterministic
+ * stream-id manually instead.
+ *
+ * Returns: A stream-id for @pad. g_free() after usage.
+ */
+gchar *
+gst_pad_create_stream_id_printf (GstPad * pad, GstElement * parent,
+ const gchar * stream_id, ...)
+{
+ va_list var_args;
+ gchar *new_stream_id;
+
+ va_start (var_args, stream_id);
+ new_stream_id =
+ gst_pad_create_stream_id_printf_valist (pad, parent, stream_id, var_args);
+ va_end (var_args);
+
+ return new_stream_id;
+}
+
+/**
+ * gst_pad_create_stream_id:
+ * @pad: A source #GstPad
+ * @parent: Parent #GstElement of @pad
+ * @stream_id: (allow-none): The stream-id
+ *
+ * Creates a stream-id for the source #GstPad @pad by combining the
+ * upstream information with the optional @stream_id of the stream
+ * of @pad. @pad must have a parent #GstElement and which must have zero
+ * or one sinkpad. @stream_id can only be %NULL if the parent element
+ * of @pad has only a single source pad.
+ *
+ * This function generates an unique stream-id by getting the upstream
+ * stream-start event stream ID and appending @stream_id to it. If the
+ * element has no sinkpad it will generate an upstream stream-id by
+ * doing an URI query on the element and in the worst case just uses
+ * a random number. Source elements that don't implement the URI
+ * handler interface should ideally generate a unique, deterministic
+ * stream-id manually instead.
+ *
+ * Since stream IDs are sorted alphabetically, any numbers in the
+ * stream ID should be printed with a fixed number of characters,
+ * preceded by 0's, such as by using the format \%03u instead of \%u.
+ *
+ * Returns: A stream-id for @pad. g_free() after usage.
+ */
+gchar *
+gst_pad_create_stream_id (GstPad * pad, GstElement * parent,
+ const gchar * stream_id)
+{
+ return gst_pad_create_stream_id_internal (pad, parent, stream_id);
+}
+
+/**
+ * gst_pad_get_stream_id:
+ * @pad: A source #GstPad
+ *
+ * Returns the current stream-id for the @pad, or %NULL if none has been
+ * set yet, i.e. the pad has not received a stream-start event yet.
+ *
+ * This is a convenience wrapper around gst_pad_get_sticky_event() and
+ * gst_event_parse_stream_start().
+ *
+ * The returned stream-id string should be treated as an opaque string, its
+ * contents should not be interpreted.
+ *
+ * Returns: a newly-allocated copy of the stream-id for @pad, or %NULL.
+ * g_free() the returned string when no longer needed.
+ *
+ * Since: 1.2
+ */
+gchar *
+gst_pad_get_stream_id (GstPad * pad)
+{
+ const gchar *stream_id = NULL;
+ GstEvent *event;
+ gchar *ret = NULL;
+
+ g_return_val_if_fail (GST_IS_PAD (pad), NULL);
+
+ event = gst_pad_get_sticky_event (pad, GST_EVENT_STREAM_START, 0);
+ if (event != NULL) {
+ gst_event_parse_stream_start (event, &stream_id);
+ ret = g_strdup (stream_id);
+ gst_event_unref (event);
+ GST_LOG_OBJECT (pad, "pad has stream-id '%s'", ret);
+ } else {
+ GST_DEBUG_OBJECT (pad, "pad has not received a stream-start event yet");
+ }
+
+ return ret;
+}
+
+/**
+ * gst_util_group_id_next:
+ *
+ * Return a constantly incrementing group id.
+ *
+ * This function is used to generate a new group-id for the
+ * stream-start event.
+ *
+ * Returns: A constantly incrementing unsigned integer, which might
+ * overflow back to 0 at some point.
+ */
+guint
+gst_util_group_id_next (void)
+{
+ static gint counter = 0;
+ return g_atomic_int_add (&counter, 1);
+}