docs/random/company/gstdata

   1 STATUS: GstData is not implemented as a class for speed reasons.
   2 ----------------------------------------------------------------
   3
   4 NB: This document does not represent the current state of CVS but my current plans on how to implement this.
   5
   6 Basics
   7 ======
   8
   9 Hierarchy
  10 ---------
  11 GstData
  12   GstInstream
  13     GstBuffer
  14     GstEventNewMedia
  15     GstEventDiscontinuous
  16     GstEventEOS
  17     GstEventLength
  18   GstOutOfStream
  19     GstEventLock
  20     GstEventUnLock
  21     GstEventSeek
  22     GstEventFlush
  23     GstEventEmpty
  24
  25
  26 GstData
  27 =======
  28
  29 typedef GstData * (*GstDataCopyFunction) (GstData *data);
  30 typedef void (*GstDataFreeFunction) (GstData *data);
  31
  32 struct _GstData
  33 {
  34   /* is a */
  35   GstDataClass *        klass;
  36
  37   /* refcounting */
  38 #ifdef HAVE_ATOMIC_H
  39   atomic_t              refcount;
  40 #else
  41   gint                  refcount;
  42   GMutex *              reflock;
  43 #endif
  44
  45   /* flags */
  46   guint                 flags;
  47 };
  48
  49 struct _GstDataClass
  50 {
  51   GstDataType           type;
  52
  53   GstDataCopyFunction   copy;
  54   GstDataFreeFunction   free;
  55 };
  56
  57 Inheritance
  58 -----------
  59 A GstData descandant GstMyData, would look like this:
  60 struct _GstMyData {
  61   GstData parent;
  62   /* more stuff specific to GstMyData */
  63 }
  64
  65 You can even enhance the class struct, if you want to. This works just like inheritance in GLib.
  66
  67 If it can be a parent class, it should implement these three functions publically:
  68 void gst_my_data_init (GstMyData *data) {
  69   /* call the parent's init function, eg: */
  70   gst_data_init (GST_DATA (data));
  71   /* initialize your data now */
  72 }
  73 void gst_my_data_dispose (GstMyData *data) {
  74   /* free every data, that needs to be freed */
  75   /* call the parent's dispose function, eg: */
  76   gst_data_dispose (GST_DATA (data));
  77   /* do NOT free the data */
  78 }
  79 GstData *gst_my_data_do_copy (GstMyData *to, GstMyData *from) {
  80   /* call the parent's copy function, eg: */
  81   gst_data_do_copy (GST_DATA (to), GST_DATA (from));
  82   /* copy relevant stuff from your struct now */
  83   /* note: the copy function must return a writable object, you may not set GST_DATA_READONLY here */
  84 }
  85
  86 If GstMyData should be instantiable, you should do this:
  87 Get a class struct, something like this:
  88 static GstDataClass my_data_class = { GST_TYPE_MY_DATA,
  89       gst_my_data_copy_func,
  90       gst_my_data_free_func };
  91 FIXME: At the moment all types need to be specified in a big enum in gstdata.h.
  92        We might want to change that when we support event plugins.
  93 The two functions above should look something like this:
  94 GstData *gst_my_data_copy_func (GstData *from) {
  95   /* allocate memory */
  96   GstMyData *copy = g_new (GstMyData, 1);
  97   /* copy relevant variables or initialize them */
  98   gst_my_data_copy (copy, GST_MY_DATA (from));
  99
 100   return copy;
 101 }
 102 void gst_my_data_free_func (GstData *data) {
 103   /* first dispose all data */
 104   gst_my_data_dispose (GST_MY_DATA (data));
 105   /* now free the struct */
 106   g_free (data);
 107 }
 108
 109 Now you just need a function that can be called from the real world:
 110 GstMyData *gst_my_data_new (void) {
 111   /* allocate memory */
 112   GstMyData *my_data = g_new (GstMyData, 1);
 113   /* initialize the variables */
 114   gst_my_data_init (my_data);
 115   /* set the right type */
 116   GST_DATA (my_data)->type = &my_data_class;
 117
 118   return my_data;
 119 }
 120
 121 summary of inheritance:
 122 - define structs like GObject inheritance
 123 - inheritance works by calling the functions of the parent when creating/copying/freeing an object
 124 - type recognition is done by the type field in the class struct
 125 - memory allocation is specific to the struct.
 126
 127 Refcounting
 128 -----------
 129 GstData provides threadsafe refcounting. If you create a new object - either by copying or explicit creation -  the refcount is initialized to 1.
 130 This reference is owned by the creator of the object.
 131 If the reference count reaches 0, the object is freed. The free function of the class is called for that purpose.
 132 In accordance with GLib, that uses g_object_(un)ref for everything, gst_data_(un)ref is used and no wrapper macros are created.
 133
 134 MT safety
 135 ---------
 136 Manipulating data inside an object is not threadsafe unless otherwise noted.
 137 If an object has a reference count of 1 it is assumed that the reference holder is the only user of that object and he may modify it the way he likes.
 138 If the reference count is greater than 1, the object may not be modified. If you need to modify it, you have to copy the object and use that copy instead.
 139 NB: Object creation and refcounting are threadsafe - or must be implemented that way.
 140
 141 Flags
 142 -----
 143 Flags work and can be used like the GstObject flags.
 144 GstData defines only one flag: GST_DATA_READONLY. If this flag is set, you are not allowed to modify the contents of a struct, even if the refcount is 1.
 145
 146 GBoxed
 147 ------
 148
 149
 150 GstInstream
 151 ===========
 152
 153 GstInstream is the base class for events and buffers that are passed inside the stream.
 154 It enhances the GstData struct by
 155 guint64         offset[GST_OFFSET_TYPES];
 156 This field describes the offset in the current stream in various different ways:
 157 GST_OFFSET_BYTES:  The number of bytes from the beginning of the stream.
 158 GST_OFFSET_TIME:   The timestamp in microseconds. The beginning of the stream equals timestamp 0. In buffers the timestamp should match the beginning of the data.
 159 GST_OFFSET_FRAMES: This type is specific to the stream and should be defined there. (video will probably use it for frame numbers, audio to count samples)
 160 If an offset can't be specified, it is set to GST_OFFSET_INVALID, which equals (guint64) -1. The byte offset always has to be specified. It is an error if it is invalid.
 161 A plugin playing data from an "infinite" source (eg a shoutcast stream from the internet) it should start with byteoffset 0.
 162
 163
 164 GstBuffer
 165 =========
 166
 167 The buffer enhances the GstInstream struct by including a data and a size field.
 168
 169 Memory allocation
 170 -----------------
 171 Memory is allocated via a special memchunk implementation, that is threadsafe. The default implementation uses a mutex and GMemChunks.
 172 FIXME: This is not true, we use g_malloc/g_free for now.
 173
 174 GstBufferClass
 175 --------------
 176 GstBufferClasses (note the plural) replace bufferpools. The default class uses g_free/g_malloc for storing data. However, you are free to write your own if
 177 you need buffers that store data in another way.
 178 Note however that the copy function needs to supply a writable copy of your buffer.
 179
 180 Subbuffers
 181 ----------
 182 Subbuffers have been replaced by a special kind of GstBufferClass.
 183
 184
 185 Instream events
 186 ===============
 187
 188 GstEventNewMedia
 189 ----------------
 190 Signals the start of a new stream. This must be send before any buffer of a new stream can be send.
 191 FIXME: The "must be send" can only be enforced if all elements are event aware. And this is necessary if we don't want to get parts of stream 1 inside stream 2.
 192
 193 GstEventDiscontinuous
 194 ---------------------
 195 This must be send between buffers, that don't have continuous data. This is necessary for example after seeking or when data is dropped for speed.
 196
 197 GstEventEOS
 198 -----------
 199 Signals the end of a stream. Must be send after all data is finished. If you want to start a new stream, don't send this event, send a GstEventNewMedia instead.
 200 After having processed this event, elements in the pipeline switch their state to paused.
 201
 202 GstEventLength
 203 --------------
 204 Specifies the length of the stream.
 205 FIXME: Write more, when sure how to do this.
 206
 207 Upstream events
 208 ===============
 209 These will be discussed in a seperate doc.
 210
 211
 212