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.
26 * @short_description: Lightweight objects to represent element contexts
27 * @see_also: #GstMiniObject, #GstElement
29 * #GstContext is a container object used to store contexts like a device
30 * context, a display server connection and similar concepts that should
31 * be shared between multiple elements.
33 * Applications can set a context on a complete pipeline by using
34 * gst_element_set_context(), which will then be propagated to all
35 * child elements. Elements can handle these in #GstElementClass.set_context()
36 * and merge them with the context information they already have.
38 * When an element needs a context it will do the following actions in this
39 * order until one step succeeds:
40 * 1. Check if the element already has a context
41 * 2. Query downstream with GST_QUERY_CONTEXT for the context
42 * 3. Query upstream with GST_QUERY_CONTEXT for the context
43 * 4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required
44 * context types and afterwards check if a usable context was set now
45 * 5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message
48 * Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously
49 * known context on the element that asks for it if possible. Otherwise the
50 * application should provide one if it can.
52 * #GstContext<!-- -->s can be persistent.
53 * A persistent #GstContext is kept in elements when they reach
54 * %GST_STATE_NULL, non-persistent ones will be removed.
55 * Also, a non-persistent context won't override a previous persistent
56 * context set to an element.
61 #include "gst_private.h"
63 #include "gstcontext.h"
68 GstMiniObject mini_object;
71 GstStructure *structure;
75 #define GST_CONTEXT_STRUCTURE(c) (((GstContext *)(c))->structure)
77 GType _gst_context_type = 0;
78 GST_DEFINE_MINI_OBJECT_TYPE (GstContext, gst_context);
81 _priv_gst_context_initialize (void)
83 GST_CAT_INFO (GST_CAT_GST_INIT, "init contexts");
85 /* the GstMiniObject types need to be class_ref'd once before it can be
86 * done from multiple threads;
87 * see http://bugzilla.gnome.org/show_bug.cgi?id=304551 */
88 gst_context_get_type ();
90 _gst_context_type = gst_context_get_type ();
94 _gst_context_free (GstContext * context)
96 GstStructure *structure;
98 g_return_if_fail (context != NULL);
100 GST_CAT_LOG (GST_CAT_CONTEXT, "finalize context %p: %" GST_PTR_FORMAT,
101 context, GST_CONTEXT_STRUCTURE (context));
103 structure = GST_CONTEXT_STRUCTURE (context);
105 gst_structure_set_parent_refcount (structure, NULL);
106 gst_structure_free (structure);
108 g_free (context->context_type);
110 g_slice_free1 (sizeof (GstContext), context);
113 static void gst_context_init (GstContext * context);
116 _gst_context_copy (GstContext * context)
119 GstStructure *structure;
121 GST_CAT_LOG (GST_CAT_CONTEXT, "copy context %p: %" GST_PTR_FORMAT, context,
122 GST_CONTEXT_STRUCTURE (context));
124 copy = g_slice_new0 (GstContext);
126 gst_context_init (copy);
128 copy->context_type = g_strdup (context->context_type);
130 structure = GST_CONTEXT_STRUCTURE (context);
131 GST_CONTEXT_STRUCTURE (copy) = gst_structure_copy (structure);
132 gst_structure_set_parent_refcount (GST_CONTEXT_STRUCTURE (copy),
133 ©->mini_object.refcount);
135 copy->persistent = context->persistent;
137 return GST_CONTEXT_CAST (copy);
141 gst_context_init (GstContext * context)
143 gst_mini_object_init (GST_MINI_OBJECT_CAST (context), 0, _gst_context_type,
144 (GstMiniObjectCopyFunction) _gst_context_copy, NULL,
145 (GstMiniObjectFreeFunction) _gst_context_free);
150 * @context_type: Context type
151 * @persistent: Persistent context
153 * Create a new context.
155 * Returns: (transfer full): The new context.
160 gst_context_new (const gchar * context_type, gboolean persistent)
163 GstStructure *structure;
165 g_return_val_if_fail (context_type != NULL, NULL);
167 context = g_slice_new0 (GstContext);
169 GST_CAT_LOG (GST_CAT_CONTEXT, "creating new context %p", context);
171 structure = gst_structure_new_id_empty (GST_QUARK (CONTEXT));
172 gst_structure_set_parent_refcount (structure, &context->mini_object.refcount);
173 gst_context_init (context);
175 context->context_type = g_strdup (context_type);
176 GST_CONTEXT_STRUCTURE (context) = structure;
177 context->persistent = persistent;
183 * gst_context_get_context_type:
184 * @context: The #GstContext.
186 * Get the type of @context.
188 * Returns: The type of the context.
193 gst_context_get_context_type (const GstContext * context)
195 g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
197 return context->context_type;
201 * gst_context_has_context_type:
202 * @context: The #GstContext.
203 * @context_type: Context type to check.
205 * Checks if @context has @context_type.
207 * Returns: %TRUE if @context has @context_type.
212 gst_context_has_context_type (const GstContext * context,
213 const gchar * context_type)
215 g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
216 g_return_val_if_fail (context_type != NULL, FALSE);
218 return strcmp (context->context_type, context_type) == 0;
222 * gst_context_get_structure:
223 * @context: The #GstContext.
225 * Access the structure of the context.
227 * Returns: (transfer none): The structure of the context. The structure is
228 * still owned by the context, which means that you should not modify it,
229 * free it and that the pointer becomes invalid when you free the context.
234 gst_context_get_structure (const GstContext * context)
236 g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
238 return GST_CONTEXT_STRUCTURE (context);
242 * gst_context_writable_structure:
243 * @context: The #GstContext.
245 * Get a writable version of the structure.
247 * Returns: The structure of the context. The structure is still
248 * owned by the context, which means that you should not free it and
249 * that the pointer becomes invalid when you free the context.
250 * This function checks if @context is writable.
255 gst_context_writable_structure (GstContext * context)
257 g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
258 g_return_val_if_fail (gst_context_is_writable (context), NULL);
260 return GST_CONTEXT_STRUCTURE (context);
264 * gst_context_is_persistent:
265 * @context: The #GstContext.
267 * Check if @context is persistent.
269 * Returns: %TRUE if the context is persistent.
274 gst_context_is_persistent (const GstContext * context)
276 g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
278 return context->persistent;