2 * Copyright (C) 2013 Collabora Ltd.
3 * Author: Sebastian Dröge <sebastian.droege@collabora.co.uk>
4 * Copyright (C) 2013 Sebastian Dröge <slomo@circular-chaos.org>
6 * gstcontext.h: Header for GstContext subsystem
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
27 * @short_description: Lightweight objects to represent element contexts
28 * @see_also: #GstMiniObject, #GstElement
30 * #GstContext is a container object used to store contexts like a device
31 * context, a display server connection and similar concepts that should
32 * be shared between multiple elements.
34 * Applications can set a context on a complete pipeline by using
35 * gst_element_set_context(), which will then be propagated to all
36 * child elements. Elements can handle these in #GstElementClass::set_context
37 * and merge them with the context information they already have.
39 * When an element needs a context it will do the following actions in this
40 * order until one step succeeds:
42 * 1. Check if the element already has a context
43 * 2. Query downstream with %GST_QUERY_CONTEXT for the context
44 * 3. Query upstream with %GST_QUERY_CONTEXT for the context
45 * 4. Post a %GST_MESSAGE_NEED_CONTEXT message on the bus with the required
46 * context types and afterwards check if a usable context was set now
47 * 5. Create a context by itself and post a %GST_MESSAGE_HAVE_CONTEXT message
50 * Bins will catch %GST_MESSAGE_NEED_CONTEXT messages and will set any previously
51 * known context on the element that asks for it if possible. Otherwise the
52 * application should provide one if it can.
54 * #GstContext can be persistent.
55 * A persistent #GstContext is kept in elements when they reach
56 * %GST_STATE_NULL, non-persistent ones will be removed.
57 * Also, a non-persistent context won't override a previous persistent
58 * context set to an element.
63 #define GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
64 #include "gst_private.h"
66 #include "gstcontext.h"
71 GstMiniObject mini_object;
74 GstStructure *structure;
78 #define GST_CONTEXT_STRUCTURE(c) (((GstContext *)(c))->structure)
80 GType _gst_context_type = 0;
81 GST_DEFINE_MINI_OBJECT_TYPE (GstContext, gst_context);
84 _priv_gst_context_initialize (void)
86 GST_CAT_INFO (GST_CAT_GST_INIT, "init contexts");
88 /* the GstMiniObject types need to be class_ref'd once before it can be
89 * done from multiple threads;
90 * see http://bugzilla.gnome.org/show_bug.cgi?id=304551 */
91 gst_context_get_type ();
93 _gst_context_type = gst_context_get_type ();
97 _gst_context_free (GstContext * context)
99 GstStructure *structure;
101 g_return_if_fail (context != NULL);
103 GST_CAT_LOG (GST_CAT_CONTEXT, "finalize context %p: %" GST_PTR_FORMAT,
104 context, GST_CONTEXT_STRUCTURE (context));
106 structure = GST_CONTEXT_STRUCTURE (context);
108 gst_structure_set_parent_refcount (structure, NULL);
109 gst_structure_free (structure);
111 g_free (context->context_type);
114 memset (context, 0xff, sizeof (GstContext));
117 g_slice_free1 (sizeof (GstContext), context);
120 static void gst_context_init (GstContext * context);
123 _gst_context_copy (GstContext * context)
126 GstStructure *structure;
128 GST_CAT_LOG (GST_CAT_CONTEXT, "copy context %p: %" GST_PTR_FORMAT, context,
129 GST_CONTEXT_STRUCTURE (context));
131 copy = g_slice_new0 (GstContext);
133 gst_context_init (copy);
135 copy->context_type = g_strdup (context->context_type);
137 structure = GST_CONTEXT_STRUCTURE (context);
138 GST_CONTEXT_STRUCTURE (copy) = gst_structure_copy (structure);
139 gst_structure_set_parent_refcount (GST_CONTEXT_STRUCTURE (copy),
140 ©->mini_object.refcount);
142 copy->persistent = context->persistent;
144 return GST_CONTEXT_CAST (copy);
148 gst_context_init (GstContext * context)
150 gst_mini_object_init (GST_MINI_OBJECT_CAST (context), 0, _gst_context_type,
151 (GstMiniObjectCopyFunction) _gst_context_copy, NULL,
152 (GstMiniObjectFreeFunction) _gst_context_free);
157 * @context_type: Context type
158 * @persistent: Persistent context
160 * Creates a new context.
162 * Returns: (transfer full): The new context.
167 gst_context_new (const gchar * context_type, gboolean persistent)
170 GstStructure *structure;
172 g_return_val_if_fail (context_type != NULL, NULL);
174 context = g_slice_new0 (GstContext);
176 GST_CAT_LOG (GST_CAT_CONTEXT, "creating new context %p", context);
178 structure = gst_structure_new_id_empty (GST_QUARK (CONTEXT));
179 gst_structure_set_parent_refcount (structure, &context->mini_object.refcount);
180 gst_context_init (context);
182 context->context_type = g_strdup (context_type);
183 GST_CONTEXT_STRUCTURE (context) = structure;
184 context->persistent = persistent;
190 * gst_context_get_context_type:
191 * @context: The #GstContext.
193 * Gets the type of @context.
195 * Returns: The type of the context.
200 gst_context_get_context_type (const GstContext * context)
202 g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
204 return context->context_type;
208 * gst_context_has_context_type:
209 * @context: The #GstContext.
210 * @context_type: Context type to check.
212 * Checks if @context has @context_type.
214 * Returns: %TRUE if @context has @context_type.
219 gst_context_has_context_type (const GstContext * context,
220 const gchar * context_type)
222 g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
223 g_return_val_if_fail (context_type != NULL, FALSE);
225 return strcmp (context->context_type, context_type) == 0;
229 * gst_context_get_structure:
230 * @context: The #GstContext.
232 * Accesses the structure of the context.
234 * Returns: (transfer none): The structure of the context. The structure is
235 * still owned by the context, which means that you should not modify it,
236 * free it and that the pointer becomes invalid when you free the context.
241 gst_context_get_structure (const GstContext * context)
243 g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
245 return GST_CONTEXT_STRUCTURE (context);
249 * gst_context_writable_structure:
250 * @context: The #GstContext.
252 * Gets a writable version of the structure.
254 * Returns: The structure of the context. The structure is still
255 * owned by the context, which means that you should not free it and
256 * that the pointer becomes invalid when you free the context.
257 * This function checks if @context is writable.
262 gst_context_writable_structure (GstContext * context)
264 g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
265 g_return_val_if_fail (gst_context_is_writable (context), NULL);
267 return GST_CONTEXT_STRUCTURE (context);
271 * gst_context_is_persistent:
272 * @context: The #GstContext.
274 * Checks if @context is persistent.
276 * Returns: %TRUE if the context is persistent.
281 gst_context_is_persistent (const GstContext * context)
283 g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
285 return context->persistent;
290 * @context: the context to ref
292 * Convenience macro to increase the reference count of the context.
294 * Returns: @context (for convenience when doing assignments)
299 gst_context_ref (GstContext * context)
301 return (GstContext *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (context));
306 * @context: the context to unref
308 * Convenience macro to decrease the reference count of the context, possibly
314 gst_context_unref (GstContext * context)
316 gst_mini_object_unref (GST_MINI_OBJECT_CAST (context));
321 * @context: the context to copy
323 * Creates a copy of the context. Returns a copy of the context.
325 * Returns: (transfer full): a new copy of @context.
332 gst_context_copy (const GstContext * context)
335 GST_CONTEXT_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST
340 * gst_context_replace:
341 * @old_context: (inout) (transfer full): pointer to a pointer to a #GstContext
343 * @new_context: (allow-none) (transfer none): pointer to a #GstContext that will
344 * replace the context pointed to by @old_context.
346 * Modifies a pointer to a #GstContext to point to a different #GstContext. The
347 * modification is done atomically (so this is useful for ensuring thread safety
348 * in some cases), and the reference counts are updated appropriately (the old
349 * context is unreffed, the new one is reffed).
351 * Either @new_context or the #GstContext pointed to by @old_context may be %NULL.
353 * Returns: %TRUE if @new_context was different from @old_context
358 gst_context_replace (GstContext ** old_context, GstContext * new_context)
360 return gst_mini_object_replace ((GstMiniObject **) old_context,
361 (GstMiniObject *) new_context);