1STATUS: GstData is not implemented as a class for speed reasons. 2---------------------------------------------------------------- 3 4NB: This document does not represent the current state of CVS but my current plans on how to implement this. 5 6Basics 7====== 8 9Hierarchy 10--------- 11GstData 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 26GstData 27======= 28 29typedef GstData * (*GstDataCopyFunction) (GstData *data); 30typedef void (*GstDataFreeFunction) (GstData *data); 31 32struct _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 49struct _GstDataClass 50{ 51 GstDataType type; 52 53 GstDataCopyFunction copy; 54 GstDataFreeFunction free; 55}; 56 57Inheritance 58----------- 59A GstData descandant GstMyData, would look like this: 60struct _GstMyData { 61 GstData parent; 62 /* more stuff specific to GstMyData */ 63} 64 65You can even enhance the class struct, if you want to. This works just like inheritance in GLib. 66 67If it can be a parent class, it should implement these three functions publicly: 68void 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} 73void 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} 79GstData *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 86If GstMyData should be instantiable, you should do this: 87Get a class struct, something like this: 88static GstDataClass my_data_class = { GST_TYPE_MY_DATA, 89 gst_my_data_copy_func, 90 gst_my_data_free_func }; 91FIXME: 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. 93The two functions above should look something like this: 94GstData *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} 102void 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 109Now you just need a function that can be called from the real world: 110GstMyData *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 121summary 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 127Refcounting 128----------- 129GstData provides threadsafe refcounting. If you create a new object - either by copying or explicit creation - the refcount is initialized to 1. 130This reference is owned by the creator of the object. 131If the reference count reaches 0, the object is freed. The free function of the class is called for that purpose. 132In accordance with GLib, that uses g_object_(un)ref for everything, gst_data_(un)ref is used and no wrapper macros are created. 133 134MT safety 135--------- 136Manipulating data inside an object is not threadsafe unless otherwise noted. 137If 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. 138If 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. 139NB: Object creation and refcounting are threadsafe - or must be implemented that way. 140 141Flags 142----- 143Flags work and can be used like the GstObject flags. 144GstData 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 146GBoxed 147------ 148 149 150GstInstream 151=========== 152 153GstInstream is the base class for events and buffers that are passed inside the stream. 154It enhances the GstData struct by 155guint64 offset[GST_OFFSET_TYPES]; 156This field describes the offset in the current stream in various different ways: 157GST_OFFSET_BYTES: The number of bytes from the beginning of the stream. 158GST_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. 159GST_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) 160If 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. 161A plugin playing data from an "infinite" source (eg a shoutcast stream from the internet) it should start with byteoffset 0. 162 163 164GstBuffer 165========= 166 167The buffer enhances the GstInstream struct by including a data and a size field. 168 169Memory allocation 170----------------- 171Memory is allocated via a special memchunk implementation, that is threadsafe. The default implementation uses a mutex and GMemChunks. 172FIXME: This is not true, we use g_malloc/g_free for now. 173 174GstBufferClass 175-------------- 176GstBufferClasses (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 177you need buffers that store data in another way. 178Note however that the copy function needs to supply a writable copy of your buffer. 179 180Subbuffers 181---------- 182Subbuffers have been replaced by a special kind of GstBufferClass. 183 184 185Instream events 186=============== 187 188GstEventNewMedia 189---------------- 190Signals the start of a new stream. This must be send before any buffer of a new stream can be send. 191FIXME: 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 193GstEventDiscontinuous 194--------------------- 195This 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 197GstEventEOS 198----------- 199Signals 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. 200After having processed this event, elements in the pipeline switch their state to paused. 201 202GstEventLength 203-------------- 204Specifies the length of the stream. 205FIXME: Write more, when sure how to do this. 206 207Upstream events 208=============== 209These will be discussed in a separate doc. 210 211 212 213