Debian Codegraph @

docs/random/company/gstdata

raw
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 publicly:
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 separate doc.
210
211
212