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  * @short_description: Lightweight objects to represent element contexts
  27  * @see_also: #GstMiniObject, #GstElement
  28  *
  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.
  32  *
  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.
  37  *
  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
  46  *    on the bus.
  47  *
  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.
  51  *
  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.
  57  *
  58  * Since: 1.2
  59  */
  60
  61 #include "gst_private.h"
  62 #include <string.h>
  63 #include "gstcontext.h"
  64 #include "gstquark.h"
  65
  66 struct _GstContext
  67 {
  68   GstMiniObject mini_object;
  69
  70   gchar *context_type;
  71   GstStructure *structure;
  72   gboolean persistent;
  73 };
  74
  75 #define GST_CONTEXT_STRUCTURE(c)  (((GstContext *)(c))->structure)
  76
  77 GType _gst_context_type = 0;
  78 GST_DEFINE_MINI_OBJECT_TYPE (GstContext, gst_context);
  79
  80 void
  81 _priv_gst_context_initialize (void)
  82 {
  83   GST_CAT_INFO (GST_CAT_GST_INIT, "init contexts");
  84
  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 ();
  89
  90   _gst_context_type = gst_context_get_type ();
  91 }
  92
  93 static void
  94 _gst_context_free (GstContext * context)
  95 {
  96   GstStructure *structure;
  97
  98   g_return_if_fail (context != NULL);
  99
 100   GST_CAT_LOG (GST_CAT_CONTEXT, "finalize context %p: %" GST_PTR_FORMAT,
 101       context, GST_CONTEXT_STRUCTURE (context));
 102
 103   structure = GST_CONTEXT_STRUCTURE (context);
 104   if (structure) {
 105     gst_structure_set_parent_refcount (structure, NULL);
 106     gst_structure_free (structure);
 107   }
 108   g_free (context->context_type);
 109
 110   g_slice_free1 (sizeof (GstContext), context);
 111 }
 112
 113 static void gst_context_init (GstContext * context);
 114
 115 static GstContext *
 116 _gst_context_copy (GstContext * context)
 117 {
 118   GstContext *copy;
 119   GstStructure *structure;
 120
 121   GST_CAT_LOG (GST_CAT_CONTEXT, "copy context %p: %" GST_PTR_FORMAT, context,
 122       GST_CONTEXT_STRUCTURE (context));
 123
 124   copy = g_slice_new0 (GstContext);
 125
 126   gst_context_init (copy);
 127
 128   copy->context_type = g_strdup (context->context_type);
 129
 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       &copy->mini_object.refcount);
 134
 135   copy->persistent = context->persistent;
 136
 137   return GST_CONTEXT_CAST (copy);
 138 }
 139
 140 static void
 141 gst_context_init (GstContext * context)
 142 {
 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);
 146 }
 147
 148 /**
 149  * gst_context_new:
 150  * @context_type: Context type
 151  * @persistent: Persistent context
 152  *
 153  * Create a new context.
 154  *
 155  * Returns: (transfer full): The new context.
 156  *
 157  * Since: 1.2
 158  */
 159 GstContext *
 160 gst_context_new (const gchar * context_type, gboolean persistent)
 161 {
 162   GstContext *context;
 163   GstStructure *structure;
 164
 165   g_return_val_if_fail (context_type != NULL, NULL);
 166
 167   context = g_slice_new0 (GstContext);
 168
 169   GST_CAT_LOG (GST_CAT_CONTEXT, "creating new context %p", context);
 170
 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);
 174
 175   context->context_type = g_strdup (context_type);
 176   GST_CONTEXT_STRUCTURE (context) = structure;
 177   context->persistent = persistent;
 178
 179   return context;
 180 }
 181
 182 /**
 183  * gst_context_get_context_type:
 184  * @context: The #GstContext.
 185  *
 186  * Get the type of @context.
 187  *
 188  * Returns: The type of the context.
 189  *
 190  * Since: 1.2
 191  */
 192 const gchar *
 193 gst_context_get_context_type (const GstContext * context)
 194 {
 195   g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
 196
 197   return context->context_type;
 198 }
 199
 200 /**
 201  * gst_context_has_context_type:
 202  * @context: The #GstContext.
 203  * @context_type: Context type to check.
 204  *
 205  * Checks if @context has @context_type.
 206  *
 207  * Returns: %TRUE if @context has @context_type.
 208  *
 209  * Since: 1.2
 210  */
 211 gboolean
 212 gst_context_has_context_type (const GstContext * context,
 213     const gchar * context_type)
 214 {
 215   g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
 216   g_return_val_if_fail (context_type != NULL, FALSE);
 217
 218   return strcmp (context->context_type, context_type) == 0;
 219 }
 220
 221 /**
 222  * gst_context_get_structure:
 223  * @context: The #GstContext.
 224  *
 225  * Access the structure of the context.
 226  *
 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.
 230  *
 231  * Since: 1.2
 232  */
 233 const GstStructure *
 234 gst_context_get_structure (const GstContext * context)
 235 {
 236   g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
 237
 238   return GST_CONTEXT_STRUCTURE (context);
 239 }
 240
 241 /**
 242  * gst_context_writable_structure:
 243  * @context: The #GstContext.
 244  *
 245  * Get a writable version of the structure.
 246  *
 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.
 251  *
 252  * Since: 1.2
 253  */
 254 GstStructure *
 255 gst_context_writable_structure (GstContext * context)
 256 {
 257   g_return_val_if_fail (GST_IS_CONTEXT (context), NULL);
 258   g_return_val_if_fail (gst_context_is_writable (context), NULL);
 259
 260   return GST_CONTEXT_STRUCTURE (context);
 261 }
 262
 263 /**
 264  * gst_context_is_persistent:
 265  * @context: The #GstContext.
 266  *
 267  * Check if @context is persistent.
 268  *
 269  * Returns: %TRUE if the context is persistent.
 270  *
 271  * Since: 1.2
 272  */
 273 gboolean
 274 gst_context_is_persistent (const GstContext * context)
 275 {
 276   g_return_val_if_fail (GST_IS_CONTEXT (context), FALSE);
 277
 278   return context->persistent;
 279 }