40824fe7842a1722d92a51914b137dc3bd326694
[platform/upstream/gstreamer.git] / docs / random / porting-to-0.11.txt
1 The 0.11 porting guide
2 ----------------------
3
4 * All deprecated methods were removed. Recompile against 0.10 with
5   DISABLE_DEPRECATED and fix issues before attempting to port to 0.11.
6
7 * GST_BOILERPLATE is gone, use G_DEFINE_TYPE instead.
8
9 * various methods take a gsize instead of a guint when talking about memory
10   sizes.
11
12 * multifdsink, tcpclientsink, tcpclientsrc, tcpserversrc the protocol property
13   is removed, use gdppay and gdpdepay.
14
15 * Presets and plugins moved to $XDG_DATA_HOME/gstreamer-0.11/ root
16   directory. Registry moved to $XDG_CACHE_HOME/gstreamer-0.11/.
17   XDG_CACHE_HOME usually points to $HOME/.cache and XDG_DATA_HOME
18   usually is $HOME/.local/share/.
19
20 * GstObject:
21     GST_OBJECT_DISPOSING flag removed
22     GST_OBJECT_IS_DISPOSING removed
23     GST_OBJECT_FLOATING flag remove, GstObject is now GInitiallyUnowned
24     GST_OBJECT_IS_FLOATING removed, use g_object_is_floating()
25
26     GST_CLASS_GET_LOCK, GST_CLASS_LOCK, GST_CLASS_TRYLOCK, GST_CLASS_UNLOCK,
27     used to be a workaround for thread-unsafe glib < 2.8
28
29     gst_object_ref_sink() has gpointer as result to make it more like the
30     GObject version.
31
32     gst_object_sink() removed, use gst_object_ref_sink() instead.
33
34     gst_class_signal_connect() removed, was only used for XML
35
36     parent-set and parent-unset signals removed. Use notify:parent. Currently
37     still disabled because of deep notify locking issues.
38
39 * GstElement:
40     GstElementDetails is removed and replaced with more generic metadata.
41
42     gst_element_class_set_details_simple() -> gst_element_class_set_metadata()
43     gst_element_class_set_documentation_uri -> gst_element_class_add_metadata
44     gst_element_class_set_icon_name -> gst_element_class_add_metadata
45     also gst_element_class_get_metadata()
46
47     gst_element_factory_get_longname -> gst_element_factory_get_metadata
48     gst_element_factory_get_klass -> gst_element_factory_get_metadata
49     gst_element_factory_get_description -> gst_element_factory_get_metadata
50     gst_element_factory_get_author -> gst_element_factory_get_metadata
51     gst_element_factory_get_documentation_uri -> gst_element_factory_get_metadata
52     gst_element_factory_get_icon_name -> gst_element_factory_get_metadata
53
54     gstelementmetadata.h contains the keys for all standard metadata.
55
56     gst_element_factory_can_{src,sink}_caps() => gst_element_factory_can_{src,sink}_{any,all}_caps()
57
58     Element metadata and pad templates are inherited from parent classes and
59     should be added in class_init instead of base_init.
60
61     gst_element_class_add_pad_template() takes ownership of the template
62
63     Elements that change the duration must post DURATION messages on the
64     bus when the duration changes in PAUSED or PLAYING.
65
66     gst_element_lost_state_full() -> gst_element_lost_state()
67     gst_element_lost_state() -> gst_element_lost_state(, TRUE)
68
69     request_new_pad_full() -> request_new_pad()
70
71     gst_element_found_tags() and gst_element_found_tags_for_pad() are gone, just
72     push the tag event.
73
74 * GstPad:
75     gst_pad_get_caps() does not return writable caps anymore and an explicit
76     gst_caps_make_writable() needs to be performed. This was the functionality
77     of gst_pad_get_caps_reffed(), which is removed now.
78
79     A similar change was done for gst_pad_peer_get_caps() and
80     gst_pad_peer_get_caps_reffed()
81
82     gst_pad_set_bufferalloc_function(), gst_pad_alloc_buffer() and
83     gst_pad_alloc_buffer_and_set_caps() are removed. Use the ALLOCATION query
84     now when negotiating formats to obtain a reference to a bufferpool object
85     that can be used to allocate buffers using gst_buffer_pool_acquire_buffer().
86
87     removed sched_private, it should not be used, use g_object_set_qdata() or
88     use element_private.
89
90     Removed GST_PAD_CAPS() use gst_pad_get_current_caps() to get a handle to the
91     currently configured caps.
92
93     GstPadGetCapsFunction, gst_pad_get_caps(), gst_pad_peer_get_caps(),
94     gst_pad_proxy_getcaps() now takes a GstCaps* parameter to inform
95     the other side about the possible caps and preferences.
96
97     gst_pad_get_pad_template_caps() and gst_pad_get_pad_template()
98     return a new reference of the caps or template now and the return
99     value needs to be unreffed after usage.
100
101     gst_pad_set_caps() now pushes a CAPS event for backward compatibility.
102     Consider sending the CAPS event yourself. It is not possible anymore to set
103     NULL caps.
104
105     gst_pad_set_checkgetrange_function() and gst_pad_check_pull_range() are
106     gone, use the SCHEDULING query now.
107
108     gst_pad_set_blocked(), gst_pad_set_blocked_async(),
109     gst_pad_set_blocked_async_full() are removed, use the gst_pad_add_probe()
110     method with the GST_PAD_PROBE_TYPE_BLOCK to get the same result as the async
111     blocking version. There is no more sync version of blocking, this is in
112     general dangerous and can be implemented using the callbacks if needed.
113
114     gst_pad_add_data_probe(), gst_pad_add_data_probe_full(),
115     gst_pad_remove_data_probe(), gst_pad_add_event_probe(),
116     gst_pad_add_event_probe_full(), gst_pad_remove_event_probe(),
117     gst_pad_add_buffer_probe(), gst_pad_add_buffer_probe_full(),
118     gst_pad_remove_buffer_probe() are removed. Use gst_pad_add_probe() and
119     gst_pad_remove_probe() for equivalent functionality.
120
121     The have-data signal was removed from pads, it was never supposed to be used
122     without calling the _add_.*_probe() methods.
123
124     The request-link signal was removed. It was never used.
125
126     gst_pad_get_negotiated_caps() -> get_pad_get_current_caps()
127
128     GST_FLOW_UNEXPECTED -> GST_FLOW_EOS
129
130     GstActivateMode -> GstPadActivateMode, GST_ACTIVATE_* -> GST_PAD_ACTIVATE_*
131
132     The GstPadAcceptCapsFunction was removed and replaced with a
133     GST_QUERY_ACCEPT_CAPS query.
134
135     The GstPadFixateCapsFunction was removed. It has no replacement, you can
136     simply do the fixation in the element or use a vmethod from the base class
137     if appropriate.
138
139 * GstPadTemplate
140     gst_pad_template_get_caps() returns a new reference of the caps
141     and the return value needs to be unreffed after usage.
142
143     gst_pad_template_new() does not take ownership of the caps anymore.
144
145     GstPadTemplate is now created with a floating ref and
146     gst_element_class_add_pad_template() takes ownership of this floating ref.
147
148     GstPadTemplate instances are considered immutable and must not be
149     changed.
150
151 * GstMiniObject
152     A miniobject is now a simple refcounted structure holding the information
153     common to buffers, events, messages, queries and caps.
154
155     There is no more GST_TYPE_MINIOBJECT as the type for subclasses.
156     G_TYPE_BOXED can be used as the type of all GstMiniObject based types such
157     as buffers, events, messages, caps, etc. Signals, for example, would use the
158     boxed type if the argument include GstMiniObject derived types.
159
160     gst_mini_object_new() is removed. You would allocate memory with the the
161     methods specific for the derived type.
162
163     GstParamSpecMiniObject is removed, use boxed param spec now with the GType
164     of the specific GstMiniObject derived type. Also
165     gst_param_spec_mini_object().
166
167     gst_param_spec_mini_object() -> g_param_spec_boxed()
168
169     The specific gst_value_*_mini_object() methods are removed, used the generic
170     boxed methods instead.
171
172     gst_value_set_mini_object() -> g_value_set_boxed()
173     gst_value_take_mini_object() -> g_value_take_boxed()
174     gst_value_take_get_object() -> g_value_get_boxed()
175     gst_value_take_dup_object() -> g_value_dup_boxed()
176
177     GST_VALUE_HOLDS_MINI_OBJECT() was removed, use G_VALUE_HOLDS_BOXED() or
178     type-specific GST_VALUE_HOLDS_{BUFFER,CAPS,etc.}() instead.
179
180     The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
181     memory in buffers as READONLY. Marking memory READONLY can now be done
182     with the GstMemory API. Writability of miniobjects is now only done by using
183     the refcount.
184
185 * GstBuffer
186     A GstBuffer is now a simple boxed type this means that subclassing is not
187     possible anymore. 
188
189     To add data to the buffer you would now use gst_buffer_take_memory() with
190     a GstMemory object containing the data. Multiple memory blocks can added to
191     a GstBuffer that can then be retrieved with gst_buffer_peek_memory().
192
193     GST_BUFFER_DATA(), GST_BUFFER_MALLOCDATA(), GST_BUFFER_FREE_FUNC() and
194     GST_BUFFER_SIZE() are gone, along with the fields in GstBuffer. Use the
195     memory API to get access to the buffer data. GST_BUFFER_SIZE() can be
196     replaced with gst_buffer_get_size() but if also access to the data is
197     required, gst_buffer_map() can return both the size and data in one go.
198
199     The most common way to access all the data in a buffer is by using
200     gst_buffer_map() and gst_buffer_unmap(). These calls require you to specify
201     the access mode required to the data and will automatically merge and return
202     a writable copy of the data.
203
204     The buffer must be writable (gst_buffer_is_writable()) in order to modify
205     the fields, metadata or buffer memory. gst_buffer_make_writable() will not
206     automatically make a writable copy of the memory but will instead increase
207     the refcount of the memory. The _map() and _peek_memory() methods will
208     automatically create writable copies when needed.
209     
210     gst_buffer_make_metadata_writable() is gone, you can replace this safely
211     with gst_buffer_make_writable().
212     
213     gst_buffer_copy_metadata() is gone, use gst_buffer_copy_into() instead and
214     mind use GST_BUFFER_COPY_METADATA instead of the former GST_BUFFER_COPY_ALL.
215
216     gst_buffer_create_sub() is gone and can be safely replaced with
217     gst_buffer_copy_region(). 
218
219     Changing the size of the buffer data can be done with gst_buffer_resize(),
220     which will also update the metadata fields correctly. gst_buffer_set_size()
221     is #defined to a special case of gst_buffer_resize() with a 0 offset.
222
223     gst_buffer_try_new_and_alloc() is replaced with gst_buffer_new_and_alloc(),
224     which now returns NULL when memory allocation fails.
225
226     GST_BUFFER_CAPS() is gone, caps are not set on buffers anymore but are set
227     on the pads where the buffer is pushed on. Likewise GST_BUFFER_COPY_CAPS is
228     not needed anymore. gst_buffer_get/set_caps() are gone too.
229
230     GST_BUFFER_TIMESTAMP is gone, use GST_BUFFER_PTS or GST_BUFFER_DTS instead.
231     Likewise GST_BUFFER_TIMESTAMP_IS_VALID() was changed to
232     GST_BUFFER_PTS_IS_VALID and GST_BUFFER_DTS_IS_VALID
233
234 * GstBufferList
235     The GstBufferList object is much simplified because most of the
236     functionality in the groups is now part of the GstMemory in buffers.
237     
238     The object is reduced to encapsulating an array of buffers that you can send
239     with the regular gst_pad_push_list. The iterator is not needed anymore
240     because you can simply use gst_buffer_list_length() and gst_buffer_list_get()
241     to iterate the array.
242
243     For dealing with the groups, it's now needed to add the memory blocks to
244     GstBuffer and use the normal buffer API to get and merge the groups.
245
246     gst_buffer_list_sized_new() -> gst_buffer_list_new_sized()
247     gst_buffer_list_len() -> gst_buffer_list_length()
248
249 * GstStructure
250
251     The GArray of the structure fields are moved to private part and are not
252     accessible from the application anymore. Use the methods to retrieve and
253     modify fields from the array.
254
255     gst_structure_empty_new() -> gst_structure_new_empty()
256     gst_structure_id_empty_new() -> gst_structure_new_id_empty()
257     gst_structure_id_new() -> gst_structure_new_id()
258
259 * GstEvent
260     Boxed types derived from GstMiniObject.
261
262     GST_EVENT_SRC is removed. Don't use this anymore.
263
264     gst_event_new_qos_full() -> gst_event_new_qos()
265     gst_event_parse_qos_full() -> gst_event_parse_qos()
266
267     The GstStructure is removed from the public API, use the getters to get
268     a handle to a GstStructure.
269
270     GST_EVENT_NEWSEGMENT -> GST_EVENT_SEGMENT
271
272     gst_event_new_new_segment () -> gst_event_new_segment() and it takes a
273     GstSegment structure as an argument.
274     gst_event_parse_new_segment() -> gst_event_parse_segment() to retrieve the
275     GstSegment structure from the event.
276     gst_event_copy_segment() to fill a GstSegment structure.
277
278 * GstQuery
279     Boxed types derived from GstMiniObject.
280
281     The GstStructure is removed from the public API, use the getters to get
282     a handle to a GstStructure.
283
284     gst_query_new_application() -> gst_query_new_custom()
285
286     gst_query_parse_formats_length() -> gst_query_parse_n_formats()
287     gst_query_parse_formats_nth() -> gst_query_parse_nth_format()
288
289     Some query utility functions no longer use an inout parameter for the
290     destination/query format:
291
292       - gst_pad_query_position()
293       - gst_pad_query_duration()
294       - gst_pad_query_convert()
295       - gst_pad_query_peer_position()
296       - gst_pad_query_peer_duration()
297       - gst_pad_query_peer_convert()
298       - gst_element_query_position()
299       - gst_element_query_duration()
300       - gst_element_query_convert()
301
302     gst_element_get_query_types() and gst_pad_get_query_types() with associated
303     functions were removed.
304
305 * GstBufferList
306     Is now a boxed type derived from GstMiniObject.
307
308 * GstMessage
309     Is now a boxed type derived from GstMiniObject
310
311     The GstStructure is removed from the public API, use the getters to get
312     a handle to a GstStructure.
313
314 * GstCaps
315     Is now a boxed type derived from GstMiniObject. 
316
317 * GstSegment
318     abs_rate was removed from the public fields, it can be trivially calculated
319     from the rate field.
320
321     accum was renamed to base. last_stop was renamed to position.
322
323     The segment info now contains all the information needed to convert buffer
324     timestamps to running_time and stream_time. There is no more segment
325     accumulation, the GstSegment is completely self contained.
326
327     gst_segment_set_duration() and gst_segment_set_last_stop() are removed,
328     simply modify the structure members duration and position respectively.
329
330     gst_segment_set_newsegment() is removed, it was used to accumulate segments
331     and is not needed anymore, use gst_segment_copy_into() or modify the segment
332     values directly.
333
334     gst_segment_set_seek() -> gst_segment_do_seek(). Updates the segment values
335     with seek parameters.
336
337 * GstPluginFeature
338     GST_PLUGIN_FEATURE_NAME() was removed, use GST_OBJECT_NAME() instead.
339
340 * GstTypeFind
341     gst_type_find_peek() returns a const guint8 * now.
342
343 * GstTask
344
345     gst_task_create() -> gst_task_new()
346
347 * GstAdapter
348     gst_adapter_peek() is removed, use gst_adapter_map() and gst_adapter_unmap()
349     to get access to raw data from the adapter.
350
351     Arguments changed from guint to gsize.
352
353     gst_adapter_prev_timestamp() is removed and should be replaced with
354     gst_adapter_prev_pts() and gst_adapter_prev_dts().
355
356 * GstBitReader, GstByteReader, GstByteWriter
357     gst_*_reader_new_from_buffer(), gst_*_reader_init_from_buffer() removed, get
358     access to the buffer data with _map() and then use the _new() functions.
359
360     gst_byte_reader_new_from_buffer() and gst_byte_reader_init_from_buffer()
361     removed, get access to the buffer data and then use the _new() functions.
362
363 * GstCollectPads
364     gst_collect_pads_read() removed, use _read_buffer() or _take_buffer() and
365     then use the memory API to get to the memory.
366
367 * GstBaseSrc, GstBaseTransform, GstBaseSink
368     GstBaseSrc::get_caps(), GstBaseTransform::transform_caps() and
369     GstBaseSink::get_caps() now take a filter GstCaps* parameter to
370     filter the caps and allow better negotiation decisions.
371  
372 * GstBaseTransform
373     GstBaseTransform::transform_caps() now gets the complete caps passed
374     instead of getting it passed structure by structure.
375
376     GstBaseTransform::event() was renamed to sink_event(). The old function
377     uses the return value to determine if the event should be forwarded or not.
378     The new function has a default implementation that always forwards the event
379     and the return value is simply returned as a result from the event handler.
380     The semantics of the sink_event are thus the same as those for the src_event
381     function.
382
383 * GstImplementsInterface
384     has been removed. Interfaces need to be updated to either have
385     is_ready/usable/available() methods, or have GError arguments
386     to their methods so we can return an appropriate error if a
387     particular interface isn't supported for a particular device.
388
389 * GstIterator
390     uses a GValue based API now that is similar to the 0.10 API but
391     allows bindings to properly use GstIterator and prevents complex
392     return value ownership issues.
393
394 * GstTagList
395     is now an opaque object instead of being typedefed to a GstStructure. Cast
396     to GstStructure or use gst_structure_* API on it at your own peril (it may
397     still work for now, but might be changed in future).
398
399     gst_tag_list_new() has been renamed to gst_tag_list_new_empty().
400     gst_tag_list_new_full*() have been renamed to gst_tag_list_new*().
401