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