gst/gstsample.c

   1 /* GStreamer
   2  * Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.com>
   3  *
   4  * gstsample.c: media sample
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22 /**
  23  * SECTION:gstsample
  24  * @title: GstSample
  25  * @short_description: A media sample
  26  * @see_also: #GstBuffer, #GstCaps, #GstSegment
  27  *
  28  * A #GstSample is a small object containing data, a type, timing and
  29  * extra arbitrary information.
  30  */
  31 #include "gst_private.h"
  32
  33 #include "gstsample.h"
  34
  35 GST_DEBUG_CATEGORY_STATIC (gst_sample_debug);
  36 #define GST_CAT_DEFAULT gst_sample_debug
  37
  38 struct _GstSample
  39 {
  40   GstMiniObject mini_object;
  41
  42   GstBuffer *buffer;
  43   GstCaps *caps;
  44   GstSegment segment;
  45   GstStructure *info;
  46   GstBufferList *buffer_list;
  47 };
  48
  49 GType _gst_sample_type = 0;
  50
  51 GST_DEFINE_MINI_OBJECT_TYPE (GstSample, gst_sample);
  52
  53 void
  54 _priv_gst_sample_initialize (void)
  55 {
  56   _gst_sample_type = gst_sample_get_type ();
  57
  58   GST_DEBUG_CATEGORY_INIT (gst_sample_debug, "sample", 0, "GstSample debug");
  59 }
  60
  61 static GstSample *
  62 _gst_sample_copy (GstSample * sample)
  63 {
  64   GstSample *copy;
  65
  66   copy = gst_sample_new (sample->buffer, sample->caps, &sample->segment,
  67       (sample->info) ? gst_structure_copy (sample->info) : NULL);
  68
  69   if (sample->buffer_list) {
  70     copy->buffer_list = gst_buffer_list_ref (sample->buffer_list);
  71     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (copy->buffer_list),
  72         GST_MINI_OBJECT_CAST (copy));
  73   }
  74
  75   return copy;
  76 }
  77
  78 static void
  79 _gst_sample_free (GstSample * sample)
  80 {
  81   GST_LOG ("free %p", sample);
  82
  83   if (sample->buffer) {
  84     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (sample->buffer),
  85         GST_MINI_OBJECT_CAST (sample));
  86     gst_buffer_unref (sample->buffer);
  87   }
  88
  89   if (sample->caps) {
  90     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (sample->caps),
  91         GST_MINI_OBJECT_CAST (sample));
  92     gst_caps_unref (sample->caps);
  93   }
  94
  95   if (sample->info) {
  96     gst_structure_set_parent_refcount (sample->info, NULL);
  97     gst_structure_free (sample->info);
  98   }
  99   if (sample->buffer_list) {
 100     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (sample->buffer_list),
 101         GST_MINI_OBJECT_CAST (sample));
 102     gst_buffer_list_unref (sample->buffer_list);
 103   }
 104 #ifdef USE_POISONING
 105   memset (sample, 0xff, sizeof (GstSample));
 106 #endif
 107
 108   g_slice_free1 (sizeof (GstSample), sample);
 109 }
 110
 111 /**
 112  * gst_sample_new:
 113  * @buffer: (transfer none) (allow-none): a #GstBuffer, or %NULL
 114  * @caps: (transfer none) (allow-none): a #GstCaps, or %NULL
 115  * @segment: (transfer none) (allow-none): a #GstSegment, or %NULL
 116  * @info: (transfer full) (allow-none): a #GstStructure, or %NULL
 117  *
 118  * Create a new #GstSample with the provided details.
 119  *
 120  * Free-function: gst_sample_unref
 121  *
 122  * Returns: (transfer full): the new #GstSample. gst_sample_unref()
 123  *     after usage.
 124  */
 125 GstSample *
 126 gst_sample_new (GstBuffer * buffer, GstCaps * caps, const GstSegment * segment,
 127     GstStructure * info)
 128 {
 129   GstSample *sample;
 130
 131   sample = g_slice_new0 (GstSample);
 132
 133   GST_LOG ("new %p", sample);
 134
 135   gst_mini_object_init (GST_MINI_OBJECT_CAST (sample), 0, _gst_sample_type,
 136       (GstMiniObjectCopyFunction) _gst_sample_copy, NULL,
 137       (GstMiniObjectFreeFunction) _gst_sample_free);
 138
 139   if (buffer) {
 140     sample->buffer = gst_buffer_ref (buffer);
 141     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->buffer),
 142         GST_MINI_OBJECT_CAST (sample));
 143   }
 144
 145   if (caps) {
 146     sample->caps = gst_caps_ref (caps);
 147     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->caps),
 148         GST_MINI_OBJECT_CAST (sample));
 149   }
 150
 151   /* FIXME 2.0: initialize with GST_FORMAT_UNDEFINED by default */
 152   if (segment)
 153     gst_segment_copy_into (segment, &sample->segment);
 154   else
 155     gst_segment_init (&sample->segment, GST_FORMAT_TIME);
 156
 157   if (info) {
 158     if (!gst_structure_set_parent_refcount (info,
 159             &sample->mini_object.refcount))
 160       goto had_parent;
 161
 162     sample->info = info;
 163   }
 164   return sample;
 165
 166   /* ERRORS */
 167 had_parent:
 168   {
 169     gst_sample_unref (sample);
 170     g_warning ("structure is already owned by another object");
 171     return NULL;
 172   }
 173 }
 174
 175 /**
 176  * gst_sample_get_buffer:
 177  * @sample: a #GstSample
 178  *
 179  * Get the buffer associated with @sample
 180  *
 181  * Returns: (transfer none) (nullable): the buffer of @sample or %NULL
 182  *  when there is no buffer. The buffer remains valid as long as
 183  *  @sample is valid.  If you need to hold on to it for longer than
 184  *  that, take a ref to the buffer with gst_buffer_ref().
 185  */
 186 GstBuffer *
 187 gst_sample_get_buffer (GstSample * sample)
 188 {
 189   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 190
 191   return sample->buffer;
 192 }
 193
 194 /**
 195  * gst_sample_get_caps:
 196  * @sample: a #GstSample
 197  *
 198  * Get the caps associated with @sample
 199  *
 200  * Returns: (transfer none) (nullable): the caps of @sample or %NULL
 201  *  when there is no caps. The caps remain valid as long as @sample is
 202  *  valid.  If you need to hold on to the caps for longer than that,
 203  *  take a ref to the caps with gst_caps_ref().
 204  */
 205 GstCaps *
 206 gst_sample_get_caps (GstSample * sample)
 207 {
 208   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 209
 210   return sample->caps;
 211 }
 212
 213 /**
 214  * gst_sample_get_segment:
 215  * @sample: a #GstSample
 216  *
 217  * Get the segment associated with @sample
 218  *
 219  * Returns: (transfer none): the segment of @sample.
 220  *  The segment remains valid as long as @sample is valid.
 221  */
 222 GstSegment *
 223 gst_sample_get_segment (GstSample * sample)
 224 {
 225   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 226
 227   return &sample->segment;
 228 }
 229
 230 /**
 231  * gst_sample_get_info:
 232  * @sample: a #GstSample
 233  *
 234  * Get extra information associated with @sample.
 235  *
 236  * Returns: (transfer none) (nullable): the extra info of @sample.
 237  *  The info remains valid as long as @sample is valid.
 238  */
 239 const GstStructure *
 240 gst_sample_get_info (GstSample * sample)
 241 {
 242   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 243
 244   return sample->info;
 245 }
 246
 247 /**
 248  * gst_sample_get_buffer_list:
 249  * @sample: a #GstSample
 250  *
 251  * Get the buffer list associated with @sample
 252  *
 253  * Returns: (transfer none) (nullable): the buffer list of @sample or %NULL
 254  *  when there is no buffer list. The buffer list remains valid as long as
 255  *  @sample is valid.  If you need to hold on to it for longer than
 256  *  that, take a ref to the buffer list with gst_mini_object_ref ().
 257  *
 258  * Since: 1.6
 259  */
 260 GstBufferList *
 261 gst_sample_get_buffer_list (GstSample * sample)
 262 {
 263   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 264
 265   return sample->buffer_list;
 266 }
 267
 268 /**
 269  * gst_sample_set_buffer_list:
 270  * @sample: a #GstSample
 271  * @buffer_list: a #GstBufferList
 272  *
 273  * Set the buffer list associated with @sample. @sample must be writable.
 274  *
 275  * Since: 1.6
 276  */
 277 void
 278 gst_sample_set_buffer_list (GstSample * sample, GstBufferList * buffer_list)
 279 {
 280   GstBufferList *old = NULL;
 281   g_return_if_fail (GST_IS_SAMPLE (sample));
 282   g_return_if_fail (gst_sample_is_writable (sample));
 283
 284   old = sample->buffer_list;
 285
 286   if (old == buffer_list)
 287     return;
 288
 289   if (buffer_list) {
 290     sample->buffer_list = gst_buffer_list_ref (buffer_list);
 291     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->buffer_list),
 292         GST_MINI_OBJECT_CAST (sample));
 293   } else {
 294     sample->buffer_list = NULL;
 295   }
 296
 297   if (old) {
 298     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (old),
 299         GST_MINI_OBJECT_CAST (sample));
 300     gst_buffer_list_unref (old);
 301   }
 302 }
 303
 304 /**
 305  * gst_sample_set_buffer:
 306  * @sample: A #GstSample
 307  * @buffer: (transfer none): A #GstBuffer
 308  *
 309  * Set the buffer associated with @sample. @sample must be writable.
 310  *
 311  * Since: 1.16
 312  */
 313 void
 314 gst_sample_set_buffer (GstSample * sample, GstBuffer * buffer)
 315 {
 316   GstBuffer *old = NULL;
 317
 318   g_return_if_fail (GST_IS_SAMPLE (sample));
 319   g_return_if_fail (gst_sample_is_writable (sample));
 320
 321   old = sample->buffer;
 322
 323   if (old == buffer)
 324     return;
 325
 326   if (buffer) {
 327     sample->buffer = gst_buffer_ref (buffer);
 328     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->buffer),
 329         GST_MINI_OBJECT_CAST (sample));
 330   } else {
 331     sample->buffer = NULL;
 332   }
 333
 334   if (old) {
 335     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (old),
 336         GST_MINI_OBJECT_CAST (sample));
 337     gst_buffer_unref (old);
 338   }
 339 }
 340
 341 /**
 342  * gst_sample_set_caps:
 343  * @sample: A #GstSample
 344  * @caps: (transfer none): A #GstCaps
 345  *
 346  * Set the caps associated with @sample. @sample must be writable.
 347  *
 348  * Since: 1.16
 349  */
 350 void
 351 gst_sample_set_caps (GstSample * sample, GstCaps * caps)
 352 {
 353   GstCaps *old = NULL;
 354
 355   g_return_if_fail (GST_IS_SAMPLE (sample));
 356   g_return_if_fail (gst_sample_is_writable (sample));
 357
 358   old = sample->caps;
 359
 360   if (old == caps)
 361     return;
 362
 363   if (caps) {
 364     sample->caps = gst_caps_ref (caps);
 365     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->caps),
 366         GST_MINI_OBJECT_CAST (sample));
 367   } else {
 368     sample->caps = NULL;
 369   }
 370
 371   if (old) {
 372     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (old),
 373         GST_MINI_OBJECT_CAST (sample));
 374     gst_caps_unref (old);
 375   }
 376 }
 377
 378 /**
 379  * gst_sample_set_segment:
 380  * @sample: A #GstSample
 381  * @segment: (transfer none): A #GstSegment
 382  *
 383  * Set the segment associated with @sample. @sample must be writable.
 384  *
 385  * Since: 1.16
 386  */
 387 void
 388 gst_sample_set_segment (GstSample * sample, const GstSegment * segment)
 389 {
 390   g_return_if_fail (GST_IS_SAMPLE (sample));
 391   g_return_if_fail (gst_sample_is_writable (sample));
 392
 393   /* FIXME 2.0: initialize with GST_FORMAT_UNDEFINED by default */
 394   if (segment)
 395     gst_segment_copy_into (segment, &sample->segment);
 396   else
 397     gst_segment_init (&sample->segment, GST_FORMAT_TIME);
 398 }
 399
 400 /**
 401  * gst_sample_set_info:
 402  * @sample: A #GstSample
 403  * @info: (transfer full): A #GstStructure
 404  *
 405  * Set the info structure associated with @sample. @sample must be writable,
 406  * and @info must not have a parent set already.
 407  *
 408  * Since: 1.16
 409  */
 410 gboolean
 411 gst_sample_set_info (GstSample * sample, GstStructure * info)
 412 {
 413   g_return_val_if_fail (GST_IS_SAMPLE (sample), FALSE);
 414   g_return_val_if_fail (gst_sample_is_writable (sample), FALSE);
 415
 416   if (info) {
 417     if (!gst_structure_set_parent_refcount (info,
 418             &sample->mini_object.refcount))
 419       goto had_parent;
 420   }
 421
 422   if (sample->info) {
 423     gst_structure_set_parent_refcount (sample->info, NULL);
 424     gst_structure_free (sample->info);
 425   }
 426
 427   sample->info = info;
 428
 429   return TRUE;
 430
 431 had_parent:
 432   g_warning ("structure is already owned by another object");
 433   return FALSE;
 434 }