a couple of notes for the 0.11 porting guide
[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     gst_element_class_add_static_pad_template (element_class, &src_template)
64       => gst_element_class_add_pad_template (element_class,
65              gst_static_pad_template_get (&src_template));
66
67     Elements that change the duration must post DURATION messages on the
68     bus when the duration changes in PAUSED or PLAYING.
69
70     gst_element_lost_state_full() -> gst_element_lost_state()
71     gst_element_lost_state() -> gst_element_lost_state(, TRUE)
72
73     request_new_pad_full() -> request_new_pad()
74
75     gst_element_found_tags() and gst_element_found_tags_for_pad() are gone, just
76     push the tag event.
77
78 * GstPad:
79     gst_pad_get_caps() was replaced by gst_pad_query_caps(), it
80     does not return writable caps anymore and an explicit
81     gst_caps_make_writable() needs to be performed. This was the functionality
82     of gst_pad_get_caps_reffed(), which is removed now.
83
84     A similar change was done for gst_pad_peer_get_caps() and
85     gst_pad_peer_get_caps_reffed()
86
87     gst_pad_set_bufferalloc_function(), gst_pad_alloc_buffer() and
88     gst_pad_alloc_buffer_and_set_caps() are removed. Use the ALLOCATION query
89     now when negotiating formats to obtain a reference to a bufferpool object
90     that can be used to allocate buffers using gst_buffer_pool_acquire_buffer().
91
92     removed sched_private, it should not be used, use g_object_set_qdata() or
93     use element_private.
94
95     Removed GST_PAD_CAPS() use gst_pad_get_current_caps() to get a handle to the
96     currently configured caps.
97
98     gst_pad_get_pad_template_caps() and gst_pad_get_pad_template()
99     return a new reference of the caps or template now and the return
100     value needs to be unreffed after usage.
101
102     gst_pad_set_caps() now pushes a CAPS event for backward compatibility.
103     Consider sending the CAPS event yourself. It is not possible anymore to set
104     NULL caps.
105
106     gst_pad_set_checkgetrange_function() and gst_pad_check_pull_range() are
107     gone, use the SCHEDULING query now.
108
109     gst_pad_set_blocked(), gst_pad_set_blocked_async(),
110     gst_pad_set_blocked_async_full() are removed, use the gst_pad_add_probe()
111     method with the GST_PAD_PROBE_TYPE_BLOCK to get the same result as the async
112     blocking version. There is no more sync version of blocking, this is in
113     general dangerous and can be implemented using the callbacks if needed.
114
115     gst_pad_add_data_probe(), gst_pad_add_data_probe_full(),
116     gst_pad_remove_data_probe(), gst_pad_add_event_probe(),
117     gst_pad_add_event_probe_full(), gst_pad_remove_event_probe(),
118     gst_pad_add_buffer_probe(), gst_pad_add_buffer_probe_full(),
119     gst_pad_remove_buffer_probe() are removed. Use gst_pad_add_probe() and
120     gst_pad_remove_probe() for equivalent functionality.
121
122     The have-data signal was removed from pads, it was never supposed to be used
123     without calling the _add_.*_probe() methods.
124
125     The request-link signal was removed. It was never used.
126
127     gst_pad_get_negotiated_caps() -> get_pad_get_current_caps()
128
129     GST_FLOW_UNEXPECTED -> GST_FLOW_EOS
130
131     GstActivateMode -> GstPadMode, GST_ACTIVATE_* -> GST_PAD_MODE_*
132
133     The GstPadAcceptCapsFunction was removed and replaced with a
134     GST_QUERY_ACCEPT_CAPS query.
135
136     The GstPadFixateCapsFunction was removed. It has no replacement, you can
137     simply do the fixation in the element or use a vmethod from the base class
138     if appropriate.
139
140     The GstPadGetCapsFunction was removed and replaced with a GST_QUERY_CAPS
141     query. The query takes a GstCaps* parameter to inform the other side about
142     the possible caps and preferences.  
143
144     gst_pad_proxy_getcaps() -> gst_pad_proxy_query_caps()
145     gst_pad_get_caps() -> gst_pad_query_caps()
146     gst_pad_peer_get_caps() -> gst_pad_peer_query_caps()
147     gst_pad_accept_caps() -> gst_pad_query_accept_caps()
148     gst_pad_peer_accept_caps() -> gst_pad_peer_query_accept_caps()
149     gst_pad_query_peer_*() -> gst_pad_peer_query_*()
150
151     GstPadFlags: GST_PAD_* -> GST_PAD_FLAG_*
152
153 * GstPadTemplate
154     gst_pad_template_get_caps() returns a new reference of the caps
155     and the return value needs to be unreffed after usage.
156
157     gst_pad_template_new() does not take ownership of the caps anymore.
158
159     GstPadTemplate is now created with a floating ref and
160     gst_element_class_add_pad_template() takes ownership of this floating ref.
161
162     GstPadTemplate instances are considered immutable and must not be
163     changed.
164
165 * GstMiniObject
166     A miniobject is now a simple refcounted structure holding the information
167     common to buffers, events, messages, queries and caps.
168
169     There is no more GST_TYPE_MINIOBJECT as the type for subclasses.
170     G_TYPE_BOXED can be used as the type of all GstMiniObject based types such
171     as buffers, events, messages, caps, etc. Signals, for example, would use the
172     boxed type if the argument include GstMiniObject derived types.
173
174     gst_mini_object_new() is removed. You would allocate memory with the the
175     methods specific for the derived type.
176
177     GstParamSpecMiniObject is removed, use boxed param spec now with the GType
178     of the specific GstMiniObject derived type. Also
179     gst_param_spec_mini_object().
180
181     gst_param_spec_mini_object() -> g_param_spec_boxed()
182
183     The specific gst_value_*_mini_object() methods are removed, used the generic
184     boxed methods instead.
185
186     gst_value_set_mini_object() -> g_value_set_boxed()
187     gst_value_take_mini_object() -> g_value_take_boxed()
188     gst_value_take_get_object() -> g_value_get_boxed()
189     gst_value_take_dup_object() -> g_value_dup_boxed()
190
191     GST_VALUE_HOLDS_MINI_OBJECT() was removed, use G_VALUE_HOLDS_BOXED() or
192     type-specific GST_VALUE_HOLDS_{BUFFER,CAPS,etc.}() instead.
193
194     The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
195     memory in buffers as READONLY. Marking memory READONLY can now be done
196     with the GstMemory API. Writability of miniobjects is now only done by using
197     the refcount.
198
199 * GstBuffer
200     A GstBuffer is now a simple boxed type this means that subclassing is not
201     possible anymore. 
202
203     To add data to the buffer you would now use gst_buffer_insert_memory() with
204     a GstMemory object containing the data. Multiple memory blocks can added to
205     a GstBuffer that can then be retrieved with gst_buffer_peek_memory().
206
207     GST_BUFFER_DATA(), GST_BUFFER_MALLOCDATA(), GST_BUFFER_FREE_FUNC() and
208     GST_BUFFER_SIZE() are gone, along with the fields in GstBuffer. Use the
209     memory API to get access to the buffer data. GST_BUFFER_SIZE() can be
210     replaced with gst_buffer_get_size() but if also access to the data is
211     required, gst_buffer_map() can return both the size and data in one go.
212
213     The most common way to access all the data in a buffer is by using
214     gst_buffer_map() and gst_buffer_unmap(). These calls require you to specify
215     the access mode required to the data and will automatically merge and return
216     a writable copy of the data.
217
218     The buffer must be writable (gst_buffer_is_writable()) in order to modify
219     the fields, metadata or buffer memory. gst_buffer_make_writable() will not
220     automatically make a writable copy of the memory but will instead increase
221     the refcount of the memory. The _map() and _peek_memory() methods will
222     automatically create writable copies when needed.
223     
224     gst_buffer_make_metadata_writable() is gone, you can replace this safely
225     with gst_buffer_make_writable().
226     
227     gst_buffer_copy_metadata() is gone, use gst_buffer_copy_into() instead and
228     mind use GST_BUFFER_COPY_METADATA instead of the former GST_BUFFER_COPY_ALL.
229
230     gst_buffer_create_sub() is gone and can be safely replaced with
231     gst_buffer_copy_region(). 
232
233     Changing the size of the buffer data can be done with gst_buffer_resize(),
234     which will also update the metadata fields correctly. gst_buffer_set_size()
235     is #defined to a special case of gst_buffer_resize() with a 0 offset.
236
237     gst_buffer_try_new_and_alloc() is replaced with gst_buffer_new_and_alloc(),
238     which now returns NULL when memory allocation fails.
239
240     GST_BUFFER_CAPS() is gone, caps are not set on buffers anymore but are set
241     on the pads where the buffer is pushed on. Likewise GST_BUFFER_COPY_CAPS is
242     not needed anymore. gst_buffer_get/set_caps() are gone too.
243
244     GST_BUFFER_TIMESTAMP is gone, use GST_BUFFER_PTS or GST_BUFFER_DTS instead.
245     Likewise GST_BUFFER_TIMESTAMP_IS_VALID() was changed to
246     GST_BUFFER_PTS_IS_VALID and GST_BUFFER_DTS_IS_VALID
247
248     gst_buffer_join() was renamed to gst_buffer_append() and the memory is not
249     directly merged but appended.
250
251     gst_buffer_merge() was removed, it is the same as gst_buffer_join() but
252     without taking ownership of the arguments. Caller code should ref themselves
253     when needed. Note that the extra refs might force slower paths in
254     gst_buffer_join().
255
256     gst_buffer_is_span() and gst_buffer_span() are removed, use
257     gst_buffer_merge() and gst_buffer_resize() for the same effect. Merging and
258     spanning is delayed until the buffer is mapped and in some cases no merging
259     of memory is needed at all when the element can deal with individual memory
260     chunks.
261
262 * GstBufferList
263     The GstBufferList object is much simplified because most of the
264     functionality in the groups is now part of the GstMemory in buffers.
265     
266     The object is reduced to encapsulating an array of buffers that you can send
267     with the regular gst_pad_push_list. The iterator is not needed anymore
268     because you can simply use gst_buffer_list_length() and gst_buffer_list_get()
269     to iterate the array.
270
271     For dealing with the groups, it's now needed to add the memory blocks to
272     GstBuffer and use the normal buffer API to get and merge the groups.
273
274     gst_buffer_list_sized_new() -> gst_buffer_list_new_sized()
275     gst_buffer_list_len() -> gst_buffer_list_length()
276
277 * GstStructure
278
279     The GArray of the structure fields are moved to private part and are not
280     accessible from the application anymore. Use the methods to retrieve and
281     modify fields from the array.
282
283     gst_structure_empty_new() -> gst_structure_new_empty()
284     gst_structure_id_empty_new() -> gst_structure_new_id_empty()
285     gst_structure_id_new() -> gst_structure_new_id()
286
287 * GstEvent
288     Boxed types derived from GstMiniObject.
289
290     GST_EVENT_SRC is removed. Don't use this anymore.
291
292     gst_event_new_qos_full() -> gst_event_new_qos()
293     gst_event_parse_qos_full() -> gst_event_parse_qos()
294
295     The GstStructure is removed from the public API, use the getters to get
296     a handle to a GstStructure.
297
298     GST_EVENT_NEWSEGMENT -> GST_EVENT_SEGMENT
299
300     gst_event_new_new_segment () -> gst_event_new_segment() and it takes a
301     GstSegment structure as an argument.
302     gst_event_parse_new_segment() -> gst_event_parse_segment() to retrieve the
303     GstSegment structure from the event.
304     gst_event_copy_segment() to fill a GstSegment structure.
305
306 * GstQuery
307     Boxed types derived from GstMiniObject.
308
309     The GstStructure is removed from the public API, use the getters to get
310     a handle to a GstStructure.
311
312     gst_query_new_application() -> gst_query_new_custom()
313
314     gst_query_parse_formats_length() -> gst_query_parse_n_formats()
315     gst_query_parse_formats_nth() -> gst_query_parse_nth_format()
316
317     Some query utility functions no longer use an inout parameter for the
318     destination/query format:
319
320       - gst_pad_query_position()
321       - gst_pad_query_duration()
322       - gst_pad_query_convert()
323       - gst_pad_query_peer_position()
324       - gst_pad_query_peer_duration()
325       - gst_pad_query_peer_convert()
326       - gst_element_query_position()
327       - gst_element_query_duration()
328       - gst_element_query_convert()
329
330     gst_element_get_query_types() and gst_pad_get_query_types() with associated
331     functions were removed.
332
333 * GstBufferList
334     Is now a boxed type derived from GstMiniObject.
335
336 * GstMessage
337     Is now a boxed type derived from GstMiniObject
338
339     The GstStructure is removed from the public API, use the getters to get
340     a handle to a GstStructure.
341
342 * GstCaps
343     Is now a boxed type derived from GstMiniObject.
344
345     GST_VIDEO_CAPS_xxx -> GST_VIDEO_CAPS_MAKE(xxx)
346
347     Some caps functions now take ownership of the input argument, for
348     efficiency reasons (to avoid unnecessary copies to make them writable):
349
350       gst_caps_normalize (caps)          =>   caps = gst_caps_normalize (caps)
351       gst_caps_do_simplify (caps)        =>   caps = gst_caps_simplify (caps)
352       gst_caps_merge (caps,caps2)        =>   caps = gst_caps_merge (caps,caps2)
353       gst_caps_merge_structure (caps,st) =>   caps = gst_caps_merge_structure (caps,st)
354       gst_caps_truncate (caps)           =>   caps = gst_caps_truncate (caps)
355
356     The compiler should warn about unused return values from these functions,
357     which may help find the places that need to be updated.
358
359     Removed functions:
360
361       gst_caps_union() -> gst_caps_merge():  Be careful because _merge takes
362                  ownership of the arguments.
363
364 * GstClock
365     gst_clock_id_wait_async_full() was renamed to gst_clock_id_wait_async() and
366     the old gst_clock_id_wait_async() function was removed.
367
368 * GstSegment
369     abs_rate was removed from the public fields, it can be trivially calculated
370     from the rate field.
371
372     accum was renamed to base. last_stop was renamed to position.
373
374     The segment info now contains all the information needed to convert buffer
375     timestamps to running_time and stream_time. There is no more segment
376     accumulation, the GstSegment is completely self contained.
377
378     gst_segment_set_duration() and gst_segment_set_last_stop() are removed,
379     simply modify the structure members duration and position respectively.
380
381     gst_segment_set_newsegment() is removed, it was used to accumulate segments
382     and is not needed anymore, use gst_segment_copy_into() or modify the segment
383     values directly.
384
385     gst_segment_set_seek() -> gst_segment_do_seek(). Updates the segment values
386     with seek parameters.
387
388 * GstPluginFeature
389     GST_PLUGIN_FEATURE_NAME() was removed, use GST_OBJECT_NAME() instead.
390
391 * GstTypeFind
392     gst_type_find_peek() returns a const guint8 * now.
393
394 * GstTask
395     gst_task_create() -> gst_task_new()
396
397 * GstAdapter
398     gst_adapter_peek() is removed, use gst_adapter_map() and gst_adapter_unmap()
399     to get access to raw data from the adapter.
400
401     Arguments changed from guint to gsize.
402
403     gst_adapter_prev_timestamp() is removed and should be replaced with
404     gst_adapter_prev_pts() and gst_adapter_prev_dts().
405
406 * GstBitReader, GstByteReader, GstByteWriter
407     gst_*_reader_new_from_buffer(), gst_*_reader_init_from_buffer() removed, get
408     access to the buffer data with _map() and then use the _new() functions.
409
410     gst_byte_reader_new_from_buffer() and gst_byte_reader_init_from_buffer()
411     removed, get access to the buffer data and then use the _new() functions.
412
413 * GstCollectPads
414     gst_collect_pads_read() removed, use _read_buffer() or _take_buffer() and
415     then use the memory API to get to the memory.
416
417 * GstBaseSrc, GstBaseTransform, GstBaseSink
418     GstBaseSrc::get_caps(), GstBaseTransform::transform_caps() and
419     GstBaseSink::get_caps() now take a filter GstCaps* parameter to
420     filter the caps and allow better negotiation decisions.
421  
422 * GstBaseTransform
423     GstBaseTransform::transform_caps() now gets the complete caps passed
424     instead of getting it passed structure by structure.
425
426     GstBaseTransform::event() was renamed to sink_event(). The old function
427     uses the return value to determine if the event should be forwarded or not.
428     The new function has a default implementation that always forwards the event
429     and the return value is simply returned as a result from the event handler.
430     The semantics of the sink_event are thus the same as those for the src_event
431     function.
432
433 * GstImplementsInterface
434     has been removed. Interfaces need to be updated to either have
435     is_ready/usable/available() methods, or have GError arguments
436     to their methods so we can return an appropriate error if a
437     particular interface isn't supported for a particular device.
438
439 * GstIterator
440     uses a GValue based API now that is similar to the 0.10 API but
441     allows bindings to properly use GstIterator and prevents complex
442     return value ownership issues.
443
444 * GstNavigationInterface
445     Now part of the video library in gst-plugins-base, and the interfaces library no
446     longer exists.
447
448 * GstMixerInterface / GstTunerInterface
449     Removed - no replacement?
450
451 * GstURIHandler
452     gst_uri_handler_get_uri() and the get_uri vfunc now return a copy of
453     the URI string
454
455     gst_uri_handler_set_uri() and the set_uri vfunc now take an additional
456     GError argument so the handler can notify the caller why it didn't
457     accept a particular URI.
458
459     gst_uri_handler_set_uri() now checks if the protocol of the URI passed
460     is one of the protocols advertised by the uri handler, so set_uri vfunc
461     implementations no longer need to check that as well.
462
463 * GstTagList
464     is now an opaque mini object instead of being typedefed to a GstStructure.
465
466     While it was previously okay (and in some cases required because of
467     missing taglist API) to cast a GstTagList to a GstStructure or use
468     gst_structure_* API on taglists, you can no longer do that. Doing so will
469     cause crashes.
470
471     Also, tag lists are refcounted now, and can therefore not be freely
472     modified any longer. Make sure to call
473
474       taglist = gst_tag_list_make_writable (taglist);
475
476     before adding, removing or changing tags in the taglist.
477
478     gst_tag_list_new() has been renamed to gst_tag_list_new_empty().
479     gst_tag_list_new_full*() have been renamed to gst_tag_list_new*().
480     gst_tag_list_free() has been replaced by gst_tag_list_unref().
481
482 * GstController:
483     has now been merged into GstObject. It does not exists as a individual
484     object anymore. In addition core contains a GstControlSource base class and
485     the GstControlBinding. The actual control sources are in the controller
486     library as before. The 2nd big change is that control sources generate
487     a sequence of gdouble values and those are mapped to the property type and
488     value range by GstControlBindings.
489     
490     For plugins the effect is that gst_controller_init() is gone and
491     gst_object_sync_values() is taking a GstObject * instead of GObject *.
492     
493     For applications the effect is larger. The whole gst_controller_* API is
494     gone and now available in simplified form under gst_object_*. ControlSources
495     are now attached via GstControlBinding to properties. There are no GValue
496     arguments used anymore when programming control sources.
497
498     gst_controller_new* -> gst_object_set_control_source
499     gst_controller_add_properties -> gst_object_set_control_source
500     gst_controller_set_control_source -> gst_object_set_control_source
501     gst_controller_get_control_source -> gst_object_get_control_source
502
503     gst_controller_set_property_disabled -> gst_object_set_controlled_property_disabled
504
505     gst_object_get_value_arrays has been removed. Loop over the controlled
506     properties fetch the value array. Also GstValueArray is gone. The fields of
507     GstValueArray are now passed directly to gst_object_get_value_array as
508     arguments.
509     
510     GstInterpolationControlSource has been split. There is a new 
511     GstTimedValueControlSource baseclass and 2 sub classes: 
512     GstInterpolationControlSource and GstTriggerControlSource. The API for setting
513     and getting the timestamps is in GstTimedValueControlSource.
514     
515     gst_interpolation_control_source_set_interpolation_mode() has been removed.
516     Set the "mode" gobject property on the control-source instead. The possible
517     enum values have been renamed from GST_INTERPOLATE_XXX to
518     GST_INTERPOLATION_MODE_XXX.
519
520 * GstRegistry
521
522     gst_registry_get_default() -> gst_registry_get()
523     gst_default_registry_*(...) -> gst_registry_*(gst_registry_get(), ...)
524
525 * GstValue
526
527     GST_TYPE_DATE -> G_TYPE_DATE
528     GST_VALUE_HOLDS_DATE(value) -> G_VALUE_HOLDS(value,G_TYPE_DATE)
529     gst_value_set_date() -> g_value_set_boxed()
530     gst_value_get_date() -> g_value_get_boxed()
531
532 * GError/GstGError
533
534     GstGError -> GError
535     GST_TYPE_G_ERROR / gst_g_error_get_type() -> G_TYPE_ERROR
536
537 * "codec-data" and "streamheader" field in GstCaps
538
539     codec-data and stream headers are no longer in GstCaps, but sent as
540     part of a STREAM CONFIG event (which should be sent after the initial
541     CAPS event if needed).