gst/gstcontext.c

   1 /* GStreamer
   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>
   5  *
   6  * gstcontext.h: Header for GstContext subsystem
   7  *
   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.
  12  *
  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.
  17  *
  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.
  22  */
  23
  24 /**
  25  * SECTION:gstcontext
  26  * @title: GstContext
  27  * @short_description: Lightweight objects to represent element contexts
  28  * @see_also: #GstMiniObject, #GstElement
  29  *
  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.
  33  *
  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.
  38  *
  39  * When an element needs a context it will do the following actions in this
  40  * order until one step succeeds:
  41  * 1. Check if the element already has a context
  42  * 2. Query downstream with GST_QUERY_CONTEXT for the context
  43  * 3. Query upstream with GST_QUERY_CONTEXT for the context
  44  * 4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required
  45  *    context types and afterwards check if a usable context was set now
  46  * 5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message
  47  *    on the bus.
  48  *
  49  * Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously
  50  * known context on the element that asks for it if possible. Otherwise the
  51  * application should provide one if it can.
  52  *
  53  * #GstContext<!-- -->s can be persistent.
  54  * A persistent #GstContext is kept in elements when they reach
  55  * %GST_STATE_NULL, non-persistent ones will be removed.
  56  * Also, a non-persistent context won't override a previous persistent
  57  * context set to an element.
  58  *
  59  * Since: 1.2
  60  */
  61
  62 #include "gst_private.h"
  63 #include <string.h>
  64 #include "gstcontext.h"
  65 #include "gstquark.h"
  66
  67 struct _GstContext
  68 {
  69   GstMiniObject mini_object;
  70
  71   gchar *context_type;
  72   GstStructure *structure;
  73   gboolean persistent;
  74 };
  75
  76 #define GST_CONTEXT_STRUCTURE(c)  (((GstContext *)(c))->structure)
  77
  78 GType _gst_context_type = 0;
  79 GST_DEFINE_MINI_OBJECT_TYPE (GstContext, gst_context);
  80
  81 void
  82 _priv_gst_context_initialize (void)
  83 {
  84   GST_CAT_INFO (GST_CAT_GST_INIT, "init contexts");
  85
  86   /* the GstMiniObject types need to be class_ref'd once before it can be
  87    * done from multiple threads;
  88    * see http://bugzilla.gnome.org/show_bug.cgi?id=304551 */
  89   gst_context_get_type ();
  90
  91   _gst_context_type = gst_context_get_type ();
  92 }
  93
  94 static void
  95 _gst_context_free (GstContext * context)
  96 {
  97   GstStructure *structure;
  98
  99   g_return_if_fail (context != NULL);
 100
 101   GST_CAT_LOG (GST_CAT_CONTEXT, "finalize context %p: %" GST_PTR_FORMAT,
 102       context, GST_CONTEXT_STRUCTURE (context));
 103
 104   structure = GST_CONTEXT_STRUCTURE (context);
 105   if (structure) {
 106     gst_structure_set_parent_refcount (structure, NULL);
 107     gst_structure_free (structure);
 108   }
 109   g_free (context->context_type);
 110
 111 #ifdef USE_POISONING
 112   memset (context, 0xff, sizeof (GstContext));
 113 #endif
 114
 115   g_slice_free1 (sizeof (GstContext), context);
 116 }
 117
 118 static void gst_context_init (GstContext * context);
 119
 120 static GstContext *
 121 _gst_context_copy (GstContext * context)
 122 {
 123   GstContext *copy;
 124   GstStructure *structure;
 125
 126   GST_CAT_LOG (GST_CAT_CONTEXT, "copy context %p: %" GST_PTR_FORMAT, context,
 127       GST_CONTEXT_STRUCTURE (context));
 128
 129   copy = g_slice_new0 (GstContext);
 130
 131   gst_context_init (copy);
 132
 133   copy->context_type = g_strdup (context->context_type);
 134
 135   structure = GST_CONTEXT_STRUCTURE (context);
 136   GST_CONTEXT_STRUCTURE (copy) = gst_structure_copy (structure);
 137   gst_structure_set_parent_refcount (GST_CONTEXT_STRUCTURE (copy),
 138       &copy->mini_object.refcount);
 139
 140   copy->persistent = context->persistent;
 141
 142   return GST_CONTEXT_CAST (copy);
 143 }
 144
 145 static void
 146 gst_context_init (GstContext * context)
 147 {
 148   gst_mini_object_init (GST_MINI_OBJECT_CAST (context), 0, _gst_context_type,
 149       (GstMiniObjectCopyFunction) _gst_context_copy, NULL,
 150       (GstMiniObjectFreeFunction) _gst_context_free);
 151 }
 152
 153 /**
 154  * gst_context_new:
 155  * @context_type: Context type
 156  * @persistent: Persistent context
 157  *
 158  * Create a new context.
 159  *
 160  * Returns: (transfer full): The new context.
 161  *
 162  * Since: 1.2
 163  */
 164 GstContext *
 165 gst_context_new (const gchar * context_type, gboolean persistent)
 166 {
 167   GstContext *context;
 168   GstStructure *structure;
 169
 170   g_return_val_if_fail (context_type != NULL, NULL);
 171
 172   context = g_slice_new0 (GstContext);
 173
 174   GST_CAT_LOG (GST_CAT_CONTEXT, "creating new context %p", context);
 175
 176   structure = gst_structure_new_id_empty (GST_QUARK (CONTEXT));
 177   gst_structure_set_parent_refcount (structure, &context->mini_object.refcount);
 178   gst_context_init (context);
 179
 180   context->context_type = g_strdup (context_type);
 181   GST_CONTEXT_STRUCTURE (context) = structure;
 182   context->persistent = persistent;
 183
 184   return context;
 185 }
 186
 187 /**
 188  * gst_context_get_context_type:
 189  * @context: The #GstContext.
 190  *
 191  * Get the type of @context.
 192  *
 193  * Returns: The type of the context.
 194  *
 195  * Since: 1.2
 196  */
 197 const gchar *
 198 gst_context_get_context_type (const GstContext * context)
 199 {
 200   g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
 201
 202   return context->context_type;
 203 }
 204
 205 /**
 206  * gst_context_has_context_type:
 207  * @context: The #GstContext.
 208  * @context_type: Context type to check.
 209  *
 210  * Checks if @context has @context_type.
 211  *
 212  * Returns: %TRUE if @context has @context_type.
 213  *
 214  * Since: 1.2
 215  */
 216 gboolean
 217 gst_context_has_context_type (const GstContext * context,
 218     const gchar * context_type)
 219 {
 220   g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
 221   g_return_val_if_fail (context_type != NULL, FALSE);
 222
 223   return strcmp (context->context_type, context_type) == 0;
 224 }
 225
 226 /**
 227  * gst_context_get_structure:
 228  * @context: The #GstContext.
 229  *
 230  * Access the structure of the context.
 231  *
 232  * Returns: (transfer none): The structure of the context. The structure is
 233  * still owned by the context, which means that you should not modify it,
 234  * free it and that the pointer becomes invalid when you free the context.
 235  *
 236  * Since: 1.2
 237  */
 238 const GstStructure *
 239 gst_context_get_structure (const GstContext * context)
 240 {
 241   g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
 242
 243   return GST_CONTEXT_STRUCTURE (context);
 244 }
 245
 246 /**
 247  * gst_context_writable_structure:
 248  * @context: The #GstContext.
 249  *
 250  * Get a writable version of the structure.
 251  *
 252  * Returns: The structure of the context. The structure is still
 253  * owned by the context, which means that you should not free it and
 254  * that the pointer becomes invalid when you free the context.
 255  * This function checks if @context is writable.
 256  *
 257  * Since: 1.2
 258  */
 259 GstStructure *
 260 gst_context_writable_structure (GstContext * context)
 261 {
 262   g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
 263   g_return_val_if_fail (gst_context_is_writable (context), NULL);
 264
 265   return GST_CONTEXT_STRUCTURE (context);
 266 }
 267
 268 /**
 269  * gst_context_is_persistent:
 270  * @context: The #GstContext.
 271  *
 272  * Check if @context is persistent.
 273  *
 274  * Returns: %TRUE if the context is persistent.
 275  *
 276  * Since: 1.2
 277  */
 278 gboolean
 279 gst_context_is_persistent (const GstContext * context)
 280 {
 281   g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
 282
 283   return context->persistent;
 284 }