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 = (GstBufferList *)
  71         gst_mini_object_ref (GST_MINI_OBJECT_CAST (sample->buffer_list));
  72
  73   return copy;
  74 }
  75
  76 static void
  77 _gst_sample_free (GstSample * sample)
  78 {
  79   GST_LOG ("free %p", sample);
  80
  81   if (sample->buffer)
  82     gst_buffer_unref (sample->buffer);
  83   if (sample->caps)
  84     gst_caps_unref (sample->caps);
  85   if (sample->info) {
  86     gst_structure_set_parent_refcount (sample->info, NULL);
  87     gst_structure_free (sample->info);
  88   }
  89   if (sample->buffer_list)
  90     gst_mini_object_unref (GST_MINI_OBJECT_CAST (sample->buffer_list));
  91
  92   g_slice_free1 (sizeof (GstSample), sample);
  93 }
  94
  95 /**
  96  * gst_sample_new:
  97  * @buffer: (transfer none) (allow-none): a #GstBuffer, or %NULL
  98  * @caps: (transfer none) (allow-none): a #GstCaps, or %NULL
  99  * @segment: (transfer none) (allow-none): a #GstSegment, or %NULL
 100  * @info: (transfer full) (allow-none): a #GstStructure, or %NULL
 101  *
 102  * Create a new #GstSample with the provided details.
 103  *
 104  * Free-function: gst_sample_unref
 105  *
 106  * Returns: (transfer full): the new #GstSample. gst_sample_unref()
 107  *     after usage.
 108  */
 109 GstSample *
 110 gst_sample_new (GstBuffer * buffer, GstCaps * caps, const GstSegment * segment,
 111     GstStructure * info)
 112 {
 113   GstSample *sample;
 114
 115   sample = g_slice_new0 (GstSample);
 116
 117   GST_LOG ("new %p", sample);
 118
 119   gst_mini_object_init (GST_MINI_OBJECT_CAST (sample), 0, _gst_sample_type,
 120       (GstMiniObjectCopyFunction) _gst_sample_copy, NULL,
 121       (GstMiniObjectFreeFunction) _gst_sample_free);
 122
 123   sample->buffer = buffer ? gst_buffer_ref (buffer) : NULL;
 124   sample->caps = caps ? gst_caps_ref (caps) : NULL;
 125
 126   /* FIXME 2.0: initialize with GST_FORMAT_UNDEFINED by default */
 127   if (segment)
 128     gst_segment_copy_into (segment, &sample->segment);
 129   else
 130     gst_segment_init (&sample->segment, GST_FORMAT_TIME);
 131
 132   if (info) {
 133     if (!gst_structure_set_parent_refcount (info,
 134             &sample->mini_object.refcount))
 135       goto had_parent;
 136
 137     sample->info = info;
 138   }
 139   return sample;
 140
 141   /* ERRORS */
 142 had_parent:
 143   {
 144     gst_sample_unref (sample);
 145     g_warning ("structure is already owned by another object");
 146     return NULL;
 147   }
 148 }
 149
 150 /**
 151  * gst_sample_get_buffer:
 152  * @sample: a #GstSample
 153  *
 154  * Get the buffer associated with @sample
 155  *
 156  * Returns: (transfer none) (nullable): the buffer of @sample or %NULL
 157  *  when there is no buffer. The buffer remains valid as long as
 158  *  @sample is valid.  If you need to hold on to it for longer than
 159  *  that, take a ref to the buffer with gst_buffer_ref().
 160  */
 161 GstBuffer *
 162 gst_sample_get_buffer (GstSample * sample)
 163 {
 164   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 165
 166   return sample->buffer;
 167 }
 168
 169 /**
 170  * gst_sample_get_caps:
 171  * @sample: a #GstSample
 172  *
 173  * Get the caps associated with @sample
 174  *
 175  * Returns: (transfer none) (nullable): the caps of @sample or %NULL
 176  *  when there is no caps. The caps remain valid as long as @sample is
 177  *  valid.  If you need to hold on to the caps for longer than that,
 178  *  take a ref to the caps with gst_caps_ref().
 179  */
 180 GstCaps *
 181 gst_sample_get_caps (GstSample * sample)
 182 {
 183   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 184
 185   return sample->caps;
 186 }
 187
 188 /**
 189  * gst_sample_get_segment:
 190  * @sample: a #GstSample
 191  *
 192  * Get the segment associated with @sample
 193  *
 194  * Returns: (transfer none): the segment of @sample.
 195  *  The segment remains valid as long as @sample is valid.
 196  */
 197 GstSegment *
 198 gst_sample_get_segment (GstSample * sample)
 199 {
 200   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 201
 202   return &sample->segment;
 203 }
 204
 205 /**
 206  * gst_sample_get_info:
 207  * @sample: a #GstSample
 208  *
 209  * Get extra information associated with @sample.
 210  *
 211  * Returns: (transfer none) (nullable): the extra info of @sample.
 212  *  The info remains valid as long as @sample is valid.
 213  */
 214 const GstStructure *
 215 gst_sample_get_info (GstSample * sample)
 216 {
 217   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 218
 219   return sample->info;
 220 }
 221
 222 /**
 223  * gst_sample_get_buffer_list:
 224  * @sample: a #GstSample
 225  *
 226  * Get the buffer list associated with @sample
 227  *
 228  * Returns: (transfer none) (nullable): the buffer list of @sample or %NULL
 229  *  when there is no buffer list. The buffer list remains valid as long as
 230  *  @sample is valid.  If you need to hold on to it for longer than
 231  *  that, take a ref to the buffer list with gst_mini_object_ref ().
 232  *
 233  * Since: 1.6
 234  */
 235 GstBufferList *
 236 gst_sample_get_buffer_list (GstSample * sample)
 237 {
 238   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 239
 240   return sample->buffer_list;
 241 }
 242
 243 /**
 244  * gst_sample_set_buffer_list:
 245  * @sample: a #GstSample
 246  * @buffer_list: a #GstBufferList
 247  *
 248  * Set the buffer list associated with @sample. @sample must be writable.
 249  *
 250  * Since: 1.6
 251  */
 252 void
 253 gst_sample_set_buffer_list (GstSample * sample, GstBufferList * buffer_list)
 254 {
 255   GstBufferList *old = NULL;
 256   g_return_if_fail (GST_IS_SAMPLE (sample));
 257   g_return_if_fail (gst_sample_is_writable (sample));
 258
 259   old = sample->buffer_list;
 260   sample->buffer_list = buffer_list ? (GstBufferList *)
 261       gst_mini_object_ref (GST_MINI_OBJECT_CAST (buffer_list)) : NULL;
 262
 263   if (old)
 264     gst_mini_object_unref (GST_MINI_OBJECT_CAST (old));
 265 }
 266
 267 /**
 268  * gst_sample_set_buffer:
 269  * @sample: A #GstSample
 270  * @buffer: (transfer none): A #GstBuffer
 271  *
 272  * Set the buffer associated with @sample. @sample must be writable.
 273  *
 274  * Since: 1.16
 275  */
 276 void
 277 gst_sample_set_buffer (GstSample * sample, GstBuffer * buffer)
 278 {
 279   g_return_if_fail (GST_IS_SAMPLE (sample));
 280   g_return_if_fail (gst_sample_is_writable (sample));
 281
 282   gst_buffer_replace (&sample->buffer, buffer);
 283 }
 284
 285 /**
 286  * gst_sample_set_caps:
 287  * @sample: A #GstSample
 288  * @caps: (transfer none): A #GstCaps
 289  *
 290  * Set the caps associated with @sample. @sample must be writable.
 291  *
 292  * Since: 1.16
 293  */
 294 void
 295 gst_sample_set_caps (GstSample * sample, GstCaps * caps)
 296 {
 297   g_return_if_fail (GST_IS_SAMPLE (sample));
 298   g_return_if_fail (gst_sample_is_writable (sample));
 299
 300   gst_caps_replace (&sample->caps, caps);
 301 }
 302
 303 /**
 304  * gst_sample_set_segment:
 305  * @sample: A #GstSample
 306  * @segment: (transfer none): A #GstSegment
 307  *
 308  * Set the segment associated with @sample. @sample must be writable.
 309  *
 310  * Since: 1.16
 311  */
 312 void
 313 gst_sample_set_segment (GstSample * sample, const GstSegment * segment)
 314 {
 315   g_return_if_fail (GST_IS_SAMPLE (sample));
 316   g_return_if_fail (gst_sample_is_writable (sample));
 317
 318   /* FIXME 2.0: initialize with GST_FORMAT_UNDEFINED by default */
 319   if (segment)
 320     gst_segment_copy_into (segment, &sample->segment);
 321   else
 322     gst_segment_init (&sample->segment, GST_FORMAT_TIME);
 323 }
 324
 325 /**
 326  * gst_sample_set_info:
 327  * @sample: A #GstSample
 328  * @info: (transfer full): A #GstStructure
 329  *
 330  * Set the info structure associated with @sample. @sample must be writable,
 331  * and @info must not have a parent set already.
 332  *
 333  * Since: 1.16
 334  */
 335 gboolean
 336 gst_sample_set_info (GstSample * sample, GstStructure * info)
 337 {
 338   g_return_val_if_fail (GST_IS_SAMPLE (sample), FALSE);
 339   g_return_val_if_fail (gst_sample_is_writable (sample), FALSE);
 340
 341   if (info) {
 342     if (!gst_structure_set_parent_refcount (info,
 343             &sample->mini_object.refcount))
 344       goto had_parent;
 345   }
 346
 347   if (sample->info) {
 348     gst_structure_set_parent_refcount (sample->info, NULL);
 349     gst_structure_free (sample->info);
 350   }
 351
 352   sample->info = info;
 353
 354   return TRUE;
 355
 356 had_parent:
 357   g_warning ("structure is already owned by another object");
 358   return FALSE;
 359 }