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 #define GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
  32 #include "gst_private.h"
  33
  34 #include "gstsample.h"
  35
  36 GST_DEBUG_CATEGORY_STATIC (gst_sample_debug);
  37 #define GST_CAT_DEFAULT gst_sample_debug
  38
  39 struct _GstSample
  40 {
  41   GstMiniObject mini_object;
  42
  43   GstBuffer *buffer;
  44   GstCaps *caps;
  45   GstSegment segment;
  46   GstStructure *info;
  47   GstBufferList *buffer_list;
  48 };
  49
  50 GType _gst_sample_type = 0;
  51
  52 GST_DEFINE_MINI_OBJECT_TYPE (GstSample, gst_sample);
  53
  54 void
  55 _priv_gst_sample_initialize (void)
  56 {
  57   _gst_sample_type = gst_sample_get_type ();
  58
  59   GST_DEBUG_CATEGORY_INIT (gst_sample_debug, "sample", 0, "GstSample debug");
  60 }
  61
  62 static GstSample *
  63 _gst_sample_copy (GstSample * sample)
  64 {
  65   GstSample *copy;
  66
  67   copy = gst_sample_new (sample->buffer, sample->caps, &sample->segment,
  68       (sample->info) ? gst_structure_copy (sample->info) : NULL);
  69
  70   if (sample->buffer_list) {
  71     copy->buffer_list = gst_buffer_list_ref (sample->buffer_list);
  72     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (copy->buffer_list),
  73         GST_MINI_OBJECT_CAST (copy));
  74   }
  75
  76   return copy;
  77 }
  78
  79 static void
  80 _gst_sample_free (GstSample * sample)
  81 {
  82   GST_LOG ("free %p", sample);
  83
  84   if (sample->buffer) {
  85     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (sample->buffer),
  86         GST_MINI_OBJECT_CAST (sample));
  87     gst_buffer_unref (sample->buffer);
  88   }
  89
  90   if (sample->caps) {
  91     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (sample->caps),
  92         GST_MINI_OBJECT_CAST (sample));
  93     gst_caps_unref (sample->caps);
  94   }
  95
  96   if (sample->info) {
  97     gst_structure_set_parent_refcount (sample->info, NULL);
  98     gst_structure_free (sample->info);
  99   }
 100   if (sample->buffer_list) {
 101     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (sample->buffer_list),
 102         GST_MINI_OBJECT_CAST (sample));
 103     gst_buffer_list_unref (sample->buffer_list);
 104   }
 105 #ifdef USE_POISONING
 106   memset (sample, 0xff, sizeof (GstSample));
 107 #endif
 108
 109   g_slice_free1 (sizeof (GstSample), sample);
 110 }
 111
 112 /**
 113  * gst_sample_new:
 114  * @buffer: (transfer none) (allow-none): a #GstBuffer, or %NULL
 115  * @caps: (transfer none) (allow-none): a #GstCaps, or %NULL
 116  * @segment: (transfer none) (allow-none): a #GstSegment, or %NULL
 117  * @info: (transfer full) (allow-none): a #GstStructure, or %NULL
 118  *
 119  * Create a new #GstSample with the provided details.
 120  *
 121  * Free-function: gst_sample_unref
 122  *
 123  * Returns: (transfer full): the new #GstSample. gst_sample_unref()
 124  *     after usage.
 125  */
 126 GstSample *
 127 gst_sample_new (GstBuffer * buffer, GstCaps * caps, const GstSegment * segment,
 128     GstStructure * info)
 129 {
 130   GstSample *sample;
 131
 132   sample = g_slice_new0 (GstSample);
 133
 134   GST_LOG ("new %p", sample);
 135
 136   gst_mini_object_init (GST_MINI_OBJECT_CAST (sample), 0, _gst_sample_type,
 137       (GstMiniObjectCopyFunction) _gst_sample_copy, NULL,
 138       (GstMiniObjectFreeFunction) _gst_sample_free);
 139
 140   if (buffer) {
 141     sample->buffer = gst_buffer_ref (buffer);
 142     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->buffer),
 143         GST_MINI_OBJECT_CAST (sample));
 144   }
 145
 146   if (caps) {
 147     sample->caps = gst_caps_ref (caps);
 148     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->caps),
 149         GST_MINI_OBJECT_CAST (sample));
 150   }
 151
 152   /* FIXME 2.0: initialize with GST_FORMAT_UNDEFINED by default */
 153   if (segment)
 154     gst_segment_copy_into (segment, &sample->segment);
 155   else
 156     gst_segment_init (&sample->segment, GST_FORMAT_TIME);
 157
 158   if (info) {
 159     if (!gst_structure_set_parent_refcount (info,
 160             &sample->mini_object.refcount))
 161       goto had_parent;
 162
 163     sample->info = info;
 164   }
 165   return sample;
 166
 167   /* ERRORS */
 168 had_parent:
 169   {
 170     gst_sample_unref (sample);
 171     g_warning ("structure is already owned by another object");
 172     return NULL;
 173   }
 174 }
 175
 176 /**
 177  * gst_sample_get_buffer:
 178  * @sample: a #GstSample
 179  *
 180  * Get the buffer associated with @sample
 181  *
 182  * Returns: (transfer none) (nullable): the buffer of @sample or %NULL
 183  *  when there is no buffer. The buffer remains valid as long as
 184  *  @sample is valid.  If you need to hold on to it for longer than
 185  *  that, take a ref to the buffer with gst_buffer_ref().
 186  */
 187 GstBuffer *
 188 gst_sample_get_buffer (GstSample * sample)
 189 {
 190   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 191
 192   return sample->buffer;
 193 }
 194
 195 /**
 196  * gst_sample_get_caps:
 197  * @sample: a #GstSample
 198  *
 199  * Get the caps associated with @sample
 200  *
 201  * Returns: (transfer none) (nullable): the caps of @sample or %NULL
 202  *  when there is no caps. The caps remain valid as long as @sample is
 203  *  valid.  If you need to hold on to the caps for longer than that,
 204  *  take a ref to the caps with gst_caps_ref().
 205  */
 206 GstCaps *
 207 gst_sample_get_caps (GstSample * sample)
 208 {
 209   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 210
 211   return sample->caps;
 212 }
 213
 214 /**
 215  * gst_sample_get_segment:
 216  * @sample: a #GstSample
 217  *
 218  * Get the segment associated with @sample
 219  *
 220  * Returns: (transfer none): the segment of @sample.
 221  *  The segment remains valid as long as @sample is valid.
 222  */
 223 GstSegment *
 224 gst_sample_get_segment (GstSample * sample)
 225 {
 226   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 227
 228   return &sample->segment;
 229 }
 230
 231 /**
 232  * gst_sample_get_info:
 233  * @sample: a #GstSample
 234  *
 235  * Get extra information associated with @sample.
 236  *
 237  * Returns: (transfer none) (nullable): the extra info of @sample.
 238  *  The info remains valid as long as @sample is valid.
 239  */
 240 const GstStructure *
 241 gst_sample_get_info (GstSample * sample)
 242 {
 243   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 244
 245   return sample->info;
 246 }
 247
 248 /**
 249  * gst_sample_get_buffer_list:
 250  * @sample: a #GstSample
 251  *
 252  * Get the buffer list associated with @sample
 253  *
 254  * Returns: (transfer none) (nullable): the buffer list of @sample or %NULL
 255  *  when there is no buffer list. The buffer list remains valid as long as
 256  *  @sample is valid.  If you need to hold on to it for longer than
 257  *  that, take a ref to the buffer list with gst_mini_object_ref ().
 258  *
 259  * Since: 1.6
 260  */
 261 GstBufferList *
 262 gst_sample_get_buffer_list (GstSample * sample)
 263 {
 264   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 265
 266   return sample->buffer_list;
 267 }
 268
 269 /**
 270  * gst_sample_set_buffer_list:
 271  * @sample: a #GstSample
 272  * @buffer_list: a #GstBufferList
 273  *
 274  * Set the buffer list associated with @sample. @sample must be writable.
 275  *
 276  * Since: 1.6
 277  */
 278 void
 279 gst_sample_set_buffer_list (GstSample * sample, GstBufferList * buffer_list)
 280 {
 281   GstBufferList *old = NULL;
 282   g_return_if_fail (GST_IS_SAMPLE (sample));
 283   g_return_if_fail (gst_sample_is_writable (sample));
 284
 285   old = sample->buffer_list;
 286
 287   if (old == buffer_list)
 288     return;
 289
 290   if (buffer_list) {
 291     sample->buffer_list = gst_buffer_list_ref (buffer_list);
 292     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->buffer_list),
 293         GST_MINI_OBJECT_CAST (sample));
 294   } else {
 295     sample->buffer_list = NULL;
 296   }
 297
 298   if (old) {
 299     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (old),
 300         GST_MINI_OBJECT_CAST (sample));
 301     gst_buffer_list_unref (old);
 302   }
 303 }
 304
 305 /**
 306  * gst_sample_set_buffer:
 307  * @sample: A #GstSample
 308  * @buffer: (transfer none): A #GstBuffer
 309  *
 310  * Set the buffer associated with @sample. @sample must be writable.
 311  *
 312  * Since: 1.16
 313  */
 314 void
 315 gst_sample_set_buffer (GstSample * sample, GstBuffer * buffer)
 316 {
 317   GstBuffer *old = NULL;
 318
 319   g_return_if_fail (GST_IS_SAMPLE (sample));
 320   g_return_if_fail (gst_sample_is_writable (sample));
 321
 322   old = sample->buffer;
 323
 324   if (old == buffer)
 325     return;
 326
 327   if (buffer) {
 328     sample->buffer = gst_buffer_ref (buffer);
 329     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->buffer),
 330         GST_MINI_OBJECT_CAST (sample));
 331   } else {
 332     sample->buffer = NULL;
 333   }
 334
 335   if (old) {
 336     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (old),
 337         GST_MINI_OBJECT_CAST (sample));
 338     gst_buffer_unref (old);
 339   }
 340 }
 341
 342 /**
 343  * gst_sample_set_caps:
 344  * @sample: A #GstSample
 345  * @caps: (transfer none): A #GstCaps
 346  *
 347  * Set the caps associated with @sample. @sample must be writable.
 348  *
 349  * Since: 1.16
 350  */
 351 void
 352 gst_sample_set_caps (GstSample * sample, GstCaps * caps)
 353 {
 354   GstCaps *old = NULL;
 355
 356   g_return_if_fail (GST_IS_SAMPLE (sample));
 357   g_return_if_fail (gst_sample_is_writable (sample));
 358
 359   old = sample->caps;
 360
 361   if (old == caps)
 362     return;
 363
 364   if (caps) {
 365     sample->caps = gst_caps_ref (caps);
 366     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (sample->caps),
 367         GST_MINI_OBJECT_CAST (sample));
 368   } else {
 369     sample->caps = NULL;
 370   }
 371
 372   if (old) {
 373     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (old),
 374         GST_MINI_OBJECT_CAST (sample));
 375     gst_caps_unref (old);
 376   }
 377 }
 378
 379 /**
 380  * gst_sample_set_segment:
 381  * @sample: A #GstSample
 382  * @segment: (transfer none): A #GstSegment
 383  *
 384  * Set the segment associated with @sample. @sample must be writable.
 385  *
 386  * Since: 1.16
 387  */
 388 void
 389 gst_sample_set_segment (GstSample * sample, const GstSegment * segment)
 390 {
 391   g_return_if_fail (GST_IS_SAMPLE (sample));
 392   g_return_if_fail (gst_sample_is_writable (sample));
 393
 394   /* FIXME 2.0: initialize with GST_FORMAT_UNDEFINED by default */
 395   if (segment)
 396     gst_segment_copy_into (segment, &sample->segment);
 397   else
 398     gst_segment_init (&sample->segment, GST_FORMAT_TIME);
 399 }
 400
 401 /**
 402  * gst_sample_set_info:
 403  * @sample: A #GstSample
 404  * @info: (transfer full): A #GstStructure
 405  *
 406  * Set the info structure associated with @sample. @sample must be writable,
 407  * and @info must not have a parent set already.
 408  *
 409  * Since: 1.16
 410  */
 411 gboolean
 412 gst_sample_set_info (GstSample * sample, GstStructure * info)
 413 {
 414   g_return_val_if_fail (GST_IS_SAMPLE (sample), FALSE);
 415   g_return_val_if_fail (gst_sample_is_writable (sample), FALSE);
 416
 417   if (info) {
 418     if (!gst_structure_set_parent_refcount (info,
 419             &sample->mini_object.refcount))
 420       goto had_parent;
 421   }
 422
 423   if (sample->info) {
 424     gst_structure_set_parent_refcount (sample->info, NULL);
 425     gst_structure_free (sample->info);
 426   }
 427
 428   sample->info = info;
 429
 430   return TRUE;
 431
 432 had_parent:
 433   g_warning ("structure is already owned by another object");
 434   return FALSE;
 435 }
 436
 437 /**
 438  * gst_sample_ref: (skip)
 439  * @sample: a #GstSample
 440  *
 441  * Increases the refcount of the given sample by one.
 442  *
 443  * Returns: (transfer full): @sample
 444  */
 445 GstSample *
 446 gst_sample_ref (GstSample * sample)
 447 {
 448   return GST_SAMPLE_CAST (gst_mini_object_ref (GST_MINI_OBJECT_CAST (sample)));
 449 }
 450
 451 /**
 452  * gst_sample_unref: (skip)
 453  * @sample: (transfer full): a #GstSample
 454  *
 455  * Decreases the refcount of the sample. If the refcount reaches 0, the
 456  * sample will be freed.
 457  */
 458 void
 459 gst_sample_unref (GstSample * sample)
 460 {
 461   gst_mini_object_unref (GST_MINI_OBJECT_CAST (sample));
 462 }
 463
 464 /**
 465  * gst_sample_copy: (skip)
 466  * @buf: a #GstSample.
 467  *
 468  * Create a copy of the given sample. This will also make a newly allocated
 469  * copy of the data the source sample contains.
 470  *
 471  * Returns: (transfer full): a new copy of @buf.
 472  *
 473  * Since: 1.2
 474  */
 475 GstSample *
 476 gst_sample_copy (const GstSample * buf)
 477 {
 478   return
 479       GST_SAMPLE_CAST (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (buf)));
 480 }