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  * @short_description: A media sample
  25  * @see_also: #GstBuffer, #GstCaps, #GstSegment
  26  *
  27  * A #GstSample is a small object containing data, a type, timing and
  28  * extra arbitrary information.
  29  *
  30  * Last reviewed on 2012-03-29 (0.11.3)
  31  */
  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 };
  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   return copy;
  70 }
  71
  72 static void
  73 _gst_sample_free (GstSample * sample)
  74 {
  75   GST_LOG ("free %p", sample);
  76
  77   if (sample->buffer)
  78     gst_buffer_unref (sample->buffer);
  79   if (sample->caps)
  80     gst_caps_unref (sample->caps);
  81   if (sample->info) {
  82     gst_structure_set_parent_refcount (sample->info, NULL);
  83     gst_structure_free (sample->info);
  84   }
  85   g_slice_free1 (sizeof (GstSample), sample);
  86 }
  87
  88 /**
  89  * gst_sample_new:
  90  * @buffer: (transfer none) (allow-none): a #GstBuffer, or NULL
  91  * @caps: (transfer none) (allow-none): a #GstCaps, or NULL
  92  * @segment: (transfer none) (allow-none): a #GstSegment, or NULL
  93  * @info: (transfer full) (allow-none): a #GstStructure, or NULL
  94  *
  95  * Create a new #GstSample with the provided details.
  96  *
  97  * Free-function: gst_sample_unref
  98  *
  99  * Returns: (transfer full): the new #GstSample. gst_sample_unref()
 100  *     after usage.
 101  */
 102 GstSample *
 103 gst_sample_new (GstBuffer * buffer, GstCaps * caps, const GstSegment * segment,
 104     GstStructure * info)
 105 {
 106   GstSample *sample;
 107
 108   sample = g_slice_new0 (GstSample);
 109
 110   GST_LOG ("new %p", sample);
 111
 112   gst_mini_object_init (GST_MINI_OBJECT_CAST (sample), 0, _gst_sample_type,
 113       (GstMiniObjectCopyFunction) _gst_sample_copy, NULL,
 114       (GstMiniObjectFreeFunction) _gst_sample_free);
 115
 116   sample->buffer = buffer ? gst_buffer_ref (buffer) : NULL;
 117   sample->caps = caps ? gst_caps_ref (caps) : NULL;
 118
 119   if (segment)
 120     gst_segment_copy_into (segment, &sample->segment);
 121   else
 122     gst_segment_init (&sample->segment, GST_FORMAT_TIME);
 123
 124   if (info) {
 125     if (!gst_structure_set_parent_refcount (info,
 126             &sample->mini_object.refcount))
 127       goto had_parent;
 128
 129     sample->info = info;
 130   }
 131   return sample;
 132
 133   /* ERRORS */
 134 had_parent:
 135   {
 136     gst_sample_unref (sample);
 137     g_warning ("structure is already owned by another object");
 138     return NULL;
 139   }
 140 }
 141
 142 /**
 143  * gst_sample_get_buffer:
 144  * @sample: a #GstSample
 145  *
 146  * Get the buffer associated with @sample
 147  *
 148  * Returns: (transfer none): the buffer of @sample or NULL when there
 149  *  is no buffer. The buffer remains valid as long as @sample is valid.
 150  *  If you need to hold on to it for longer than that, take a ref to
 151  *  the buffer with gst_buffer_ref().
 152  */
 153 GstBuffer *
 154 gst_sample_get_buffer (GstSample * sample)
 155 {
 156   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 157
 158   return sample->buffer;
 159 }
 160
 161 /**
 162  * gst_sample_get_caps:
 163  * @sample: a #GstSample
 164  *
 165  * Get the caps associated with @sample
 166  *
 167  * Returns: (transfer none): the caps of @sample or NULL when there
 168  *  is no caps. The caps remain valid as long as @sample is valid.
 169  *  If you need to hold on to the caps for longer than that, take a ref to
 170  *  the caps with gst_caps_ref().
 171  */
 172 GstCaps *
 173 gst_sample_get_caps (GstSample * sample)
 174 {
 175   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 176
 177   return sample->caps;
 178 }
 179
 180 /**
 181  * gst_sample_get_segment:
 182  * @sample: a #GstSample
 183  *
 184  * Get the segment associated with @sample
 185  *
 186  * Returns: (transfer none): the segment of @sample.
 187  *  The segment remains valid as long as @sample is valid.
 188  */
 189 GstSegment *
 190 gst_sample_get_segment (GstSample * sample)
 191 {
 192   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 193
 194   return &sample->segment;
 195 }
 196
 197 /**
 198  * gst_sample_get_info:
 199  * @sample: a #GstSample
 200  *
 201  * Get extra information associated with @sample.
 202  *
 203  * Returns: (transfer none): the extra info of @sample.
 204  *  The info remains valid as long as @sample is valid.
 205  */
 206 const GstStructure *
 207 gst_sample_get_info (GstSample * sample)
 208 {
 209   g_return_val_if_fail (GST_IS_SAMPLE (sample), NULL);
 210
 211   return sample->info;
 212 }