docs/random/porting-to-1.0.txt

   1 GStreamer 0.10 to 1.0 porting guide
   2 -----------------------------------
   3
   4 PREFACE
   5
   6 * All deprecated methods were removed. Recompile against 0.10 with
   7   DISABLE_DEPRECATED and fix issues before attempting to port to 1.0.
   8
   9 * API changes are usually easy to spot, because the compiler will
  10   generate a warning, at least if number of arguments or types differ
  11
  12 * Other changes are a bit more subtle. See checklist at the bottom
  13   for some "soft" changes which the compiler will not warn about.
  14
  15 * python developers may find https://wiki.ubuntu.com/Novacut/GStreamer1.0
  16   useful
  17
  18 * application developers may first want to have a look at the list of changes
  19   affecting applications in the Application Development Manual:
  20   http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/chapter-porting-1.0.html
  21
  22
  23 CHANGES
  24
  25 * GST_BOILERPLATE is gone, use G_DEFINE_TYPE instead (note that the variable
  26   that used to be called parent_class is then called gst_foo_bar_parent_class)
  27
  28 * various methods take a gsize instead of a guint when talking about memory
  29   sizes.
  30
  31 * multifdsink, tcpclientsink, tcpclientsrc, tcpserversrc the protocol property
  32   is removed, use gdppay and gdpdepay.
  33
  34 * Presets and plugins moved to $XDG_DATA_HOME/gstreamer-1.0/ root
  35   directory. Registry moved to $XDG_CACHE_HOME/gstreamer-1.0/.
  36   XDG_CACHE_HOME usually points to $HOME/.cache and XDG_DATA_HOME
  37   usually is $HOME/.local/share/.
  38
  39 * GstObject:
  40     GST_OBJECT_DISPOSING flag removed
  41     GST_OBJECT_IS_DISPOSING removed
  42     GST_OBJECT_FLOATING flag remove, GstObject is now GInitiallyUnowned
  43     GST_OBJECT_IS_FLOATING removed, use g_object_is_floating()
  44
  45     GST_CLASS_GET_LOCK, GST_CLASS_LOCK, GST_CLASS_TRYLOCK, GST_CLASS_UNLOCK,
  46     used to be a workaround for thread-unsafe glib < 2.8
  47
  48     gst_object_ref_sink() has gpointer as result to make it more like the
  49     GObject version.
  50
  51     gst_object_sink() removed, use gst_object_ref_sink() instead.
  52
  53     gst_class_signal_connect() removed, was only used for XML
  54
  55     parent-set and parent-unset signals removed. Use notify:parent. Currently
  56     still disabled because of deep notify locking issues.
  57
  58 * GstElement:
  59     GstElementDetails is removed and replaced with more generic metadata.
  60
  61     gst_element_class_set_details_simple() -> gst_element_class_set_metadata()
  62     gst_element_class_set_documentation_uri -> gst_element_class_add_metadata
  63     gst_element_class_set_icon_name -> gst_element_class_add_metadata
  64     also gst_element_class_get_metadata()
  65
  66     gst_element_factory_get_longname -> gst_element_factory_get_metadata
  67     gst_element_factory_get_klass -> gst_element_factory_get_metadata
  68     gst_element_factory_get_description -> gst_element_factory_get_metadata
  69     gst_element_factory_get_author -> gst_element_factory_get_metadata
  70     gst_element_factory_get_documentation_uri -> gst_element_factory_get_metadata
  71     gst_element_factory_get_icon_name -> gst_element_factory_get_metadata
  72
  73     gstelementmetadata.h contains the keys for all standard metadata.
  74
  75     gst_element_factory_can_{src,sink}_caps() => gst_element_factory_can_{src,sink}_{any,all}_caps()
  76
  77     Element metadata and pad templates are inherited from parent classes and
  78     should be added in class_init instead of base_init.
  79
  80     gst_element_class_add_pad_template() takes ownership of the template
  81
  82     gst_element_class_add_static_pad_template (element_class, &src_template)
  83       => gst_element_class_add_pad_template (element_class,
  84              gst_static_pad_template_get (&src_template));
  85
  86     Elements that change the duration must post DURATION messages on the
  87     bus when the duration changes in PAUSED or PLAYING.
  88
  89     gst_element_lost_state_full() -> gst_element_lost_state()
  90     gst_element_lost_state() -> gst_element_lost_state(, TRUE)
  91
  92     request_new_pad_full() -> request_new_pad()
  93
  94     gst_element_found_tags() and gst_element_found_tags_for_pad() are gone, just
  95     push the tag event.
  96
  97 * GstPad:
  98     gst_pad_get_caps() was replaced by gst_pad_query_caps(), it
  99     does not return writable caps anymore and an explicit
 100     gst_caps_make_writable() needs to be performed. This was the functionality
 101     of gst_pad_get_caps_reffed(), which is removed now.
 102
 103     A similar change was done for gst_pad_peer_get_caps() and
 104     gst_pad_peer_get_caps_reffed()
 105
 106     gst_pad_set_bufferalloc_function(), gst_pad_alloc_buffer() and
 107     gst_pad_alloc_buffer_and_set_caps() are removed. Use the ALLOCATION query
 108     now when negotiating formats to obtain a reference to a bufferpool object
 109     that can be used to allocate buffers using gst_buffer_pool_acquire_buffer().
 110
 111     gst_pad_set_setcaps_function() => GST_EVENT_CAPS in event handler
 112
 113     gst_pad_set_getcaps_function() => GST_QUERY_CAPS in query handler
 114
 115     gst_pad_set_acceptcaps_function() => GST_QUERY_ACCEPT_CAPS in query handler
 116
 117     removed sched_private, it should not be used, use g_object_set_qdata() or
 118     use element_private.
 119
 120     Removed GST_PAD_CAPS() use gst_pad_get_current_caps() to get a handle to the
 121     currently configured caps.
 122
 123     gst_pad_get_pad_template_caps() and gst_pad_get_pad_template()
 124     return a new reference of the caps or template now and the return
 125     value needs to be unreffed after usage.
 126
 127     gst_pad_set_caps() now pushes a CAPS event for backward compatibility.
 128     Consider sending the CAPS event yourself. It is not possible anymore to set
 129     NULL caps.
 130
 131     gst_pad_set_checkgetrange_function() and gst_pad_check_pull_range() are
 132     gone, use the SCHEDULING query now.
 133
 134     gst_pad_set_blocked(), gst_pad_set_blocked_async(),
 135     gst_pad_set_blocked_async_full() are removed, use the gst_pad_add_probe()
 136     method with the GST_PAD_PROBE_TYPE_BLOCK to get the same result as the async
 137     blocking version. There is no more sync version of blocking, this is in
 138     general dangerous and can be implemented using the callbacks if needed.
 139
 140     gst_pad_add_data_probe(), gst_pad_add_data_probe_full(),
 141     gst_pad_remove_data_probe(), gst_pad_add_event_probe(),
 142     gst_pad_add_event_probe_full(), gst_pad_remove_event_probe(),
 143     gst_pad_add_buffer_probe(), gst_pad_add_buffer_probe_full(),
 144     gst_pad_remove_buffer_probe() are removed. Use gst_pad_add_probe() and
 145     gst_pad_remove_probe() for equivalent functionality.
 146
 147     The have-data signal was removed from pads, it was never supposed to be used
 148     without calling the _add_.*_probe() methods.
 149
 150     The request-link signal was removed. It was never used.
 151
 152     gst_pad_get_negotiated_caps() -> gst_pad_get_current_caps()
 153
 154     GST_FLOW_UNEXPECTED -> GST_FLOW_EOS
 155
 156     GST_FLOW_WRONG_STATE -> GST_FLOW_FLUSHING
 157
 158     GstActivateMode -> GstPadMode, GST_ACTIVATE_* -> GST_PAD_MODE_*
 159     gst_pad_activate_{pull,push}() -> gst_pad_activate_mode()
 160
 161     The GstPadAcceptCapsFunction was removed and replaced with a
 162     GST_QUERY_ACCEPT_CAPS query.
 163
 164     The GstPadFixateCapsFunction was removed. It has no replacement, you can
 165     simply do the fixation in the element or use a vmethod from the base class
 166     if appropriate.
 167
 168     The GstPadGetCapsFunction was removed and replaced with a GST_QUERY_CAPS
 169     query. The query takes a GstCaps* parameter to inform the other side about
 170     the possible caps and preferences.
 171
 172     gst_pad_proxy_getcaps() -> gst_pad_proxy_query_caps()
 173     gst_pad_get_caps() -> gst_pad_query_caps()
 174     gst_pad_peer_get_caps() -> gst_pad_peer_query_caps()
 175     gst_pad_accept_caps() -> gst_pad_query_accept_caps()
 176     gst_pad_peer_accept_caps() -> gst_pad_peer_query_accept_caps()
 177     gst_pad_query_peer_*() -> gst_pad_peer_query_*()
 178
 179     GstPadFlags: GST_PAD_* -> GST_PAD_FLAG_*
 180
 181 * GstPadTemplate
 182     gst_pad_template_get_caps() returns a new reference of the caps
 183     and the return value needs to be unreffed after usage.
 184
 185     gst_pad_template_new() does not take ownership of the caps anymore.
 186
 187     GstPadTemplate is now created with a floating ref and
 188     gst_element_class_add_pad_template() takes ownership of this floating ref.
 189
 190     GstPadTemplate instances are considered immutable and must not be
 191     changed.
 192
 193 * GstMiniObject
 194     A miniobject is now a simple refcounted structure holding the information
 195     common to buffers, events, messages, queries and caps.
 196
 197     There is no more GST_TYPE_MINIOBJECT as the type for subclasses.
 198     G_TYPE_BOXED can be used as the type of all GstMiniObject based types such
 199     as buffers, events, messages, caps, etc. Signals, for example, would use the
 200     boxed type if the argument include GstMiniObject derived types.
 201
 202     gst_mini_object_new() is removed. You would allocate memory with the
 203     methods specific for the derived type.
 204
 205     GstParamSpecMiniObject is removed, use boxed param spec now with the GType
 206     of the specific GstMiniObject derived type. Also
 207     gst_param_spec_mini_object().
 208
 209     gst_param_spec_mini_object() -> g_param_spec_boxed()
 210
 211     The specific gst_value_*_mini_object() methods are removed, used the generic
 212     boxed methods instead.
 213
 214     gst_value_set_mini_object() -> g_value_set_boxed()
 215     gst_value_take_mini_object() -> g_value_take_boxed()
 216     gst_value_take_get_object() -> g_value_get_boxed()
 217     gst_value_take_dup_object() -> g_value_dup_boxed()
 218
 219     GST_VALUE_HOLDS_MINI_OBJECT() was removed, use G_VALUE_HOLDS_BOXED() or
 220     type-specific GST_VALUE_HOLDS_{BUFFER,CAPS,etc.}() instead.
 221
 222     The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
 223     memory in buffers as READONLY. Marking memory READONLY can now be done
 224     with the GstMemory API. Writability of miniobjects is now either done
 225     by using the refcount or by using exclusive locking.
 226
 227 * GstBuffer
 228     A GstBuffer is now a simple boxed type this means that subclassing is not
 229     possible anymore.
 230
 231     To add data to the buffer you would now use gst_buffer_insert_memory() with
 232     a GstMemory object containing the data. Multiple memory blocks can added to
 233     a GstBuffer that can then be retrieved with gst_buffer_peek_memory().
 234
 235     GST_BUFFER_DATA(), GST_BUFFER_MALLOCDATA(), GST_BUFFER_FREE_FUNC() and
 236     GST_BUFFER_SIZE() are gone, along with the fields in GstBuffer.
 237
 238     The most common way to access all the data in a buffer is by using
 239     gst_buffer_map() and gst_buffer_unmap(). These calls require you to specify
 240     the access mode required to the data and will automatically merge and return
 241     a writable copy of the data.
 242
 243     GST_BUFFER_SIZE() can be replaced with gst_buffer_get_size() but if also
 244     access to the data is required, gst_buffer_map() can return both the size
 245     and data in one go.
 246
 247     The buffer must be writable (gst_buffer_is_writable()) in order to modify
 248     the fields, metadata or buffer memory. gst_buffer_make_writable() will not
 249     automatically make a writable copy of the memory but will instead increase
 250     the refcount of the memory. The _map() and _peek_memory() methods will
 251     automatically create writable copies when needed.
 252
 253     gst_buffer_make_metadata_writable() is gone, you can replace this safely
 254     with gst_buffer_make_writable().
 255
 256     gst_buffer_copy_metadata() is gone, use gst_buffer_copy_into() instead and
 257     mind use GST_BUFFER_COPY_METADATA instead of the former GST_BUFFER_COPY_ALL.
 258
 259     gst_buffer_create_sub() is gone and can be safely replaced with
 260     gst_buffer_copy_region().
 261
 262     Changing the size of the buffer data can be done with gst_buffer_resize(),
 263     which will also update the metadata fields correctly. gst_buffer_set_size()
 264     is #defined to a special case of gst_buffer_resize() with a 0 offset.
 265
 266     gst_buffer_try_new_and_alloc() is replaced with gst_buffer_new_and_alloc(),
 267     which now returns NULL when memory allocation fails.
 268
 269     GST_BUFFER_CAPS() is gone, caps are not set on buffers anymore but are set
 270     on the pads where the buffer is pushed on. Likewise GST_BUFFER_COPY_CAPS is
 271     not needed anymore. gst_buffer_get/set_caps() are gone too.
 272
 273     GST_BUFFER_TIMESTAMP is gone, use GST_BUFFER_PTS or GST_BUFFER_DTS instead.
 274     Likewise GST_BUFFER_TIMESTAMP_IS_VALID() was changed to
 275     GST_BUFFER_PTS_IS_VALID and GST_BUFFER_DTS_IS_VALID
 276
 277     gst_buffer_join() was renamed to gst_buffer_append() and the memory is not
 278     directly merged but appended.
 279
 280     gst_buffer_merge() was removed, it is the same as gst_buffer_join() but
 281     without taking ownership of the arguments. Caller code should ref themselves
 282     when needed. Note that the extra refs might force slower paths in
 283     gst_buffer_join().
 284
 285     gst_buffer_is_span() and gst_buffer_span() are removed, use
 286     gst_buffer_merge() and gst_buffer_resize() for the same effect. Merging and
 287     spanning is delayed until the buffer is mapped and in some cases no merging
 288     of memory is needed at all when the element can deal with individual memory
 289     chunks.
 290
 291 * GstBufferList
 292     The GstBufferList object is much simplified because most of the
 293     functionality in the groups is now part of the GstMemory in buffers.
 294
 295     The object is reduced to encapsulating an array of buffers that you can send
 296     with the regular gst_pad_push_list. The iterator is not needed anymore
 297     because you can simply use gst_buffer_list_length() and gst_buffer_list_get()
 298     to iterate the array.
 299
 300     For dealing with the groups, it's now needed to add the memory blocks to
 301     GstBuffer and use the normal buffer API to get and merge the groups.
 302
 303     gst_buffer_list_sized_new() -> gst_buffer_list_new_sized()
 304     gst_buffer_list_len() -> gst_buffer_list_length()
 305
 306 * GstStructure
 307
 308     The GArray of the structure fields are moved to private part and are not
 309     accessible from the application anymore. Use the methods to retrieve and
 310     modify fields from the array.
 311
 312     gst_structure_empty_new() -> gst_structure_new_empty()
 313     gst_structure_id_empty_new() -> gst_structure_new_id_empty()
 314     gst_structure_id_new() -> gst_structure_new_id()
 315
 316 * GstEvent
 317     Boxed types derived from GstMiniObject.
 318
 319     GST_EVENT_SRC is removed. Don't use this anymore.
 320
 321     gst_event_new_qos_full() -> gst_event_new_qos()
 322     gst_event_parse_qos_full() -> gst_event_parse_qos()
 323
 324     The GstStructure is removed from the public API, use the getters to get
 325     a handle to a GstStructure.
 326
 327     GST_EVENT_NEWSEGMENT -> GST_EVENT_SEGMENT
 328
 329     gst_event_new_new_segment () -> gst_event_new_segment() and it takes a
 330     GstSegment structure as an argument.
 331     gst_event_parse_new_segment() -> gst_event_parse_segment() to retrieve the
 332     GstSegment structure from the event.
 333     gst_event_copy_segment() to fill a GstSegment structure.
 334
 335     gst_event_new_flush_stop() now takes a boolean, which in most cases should
 336     be TRUE
 337
 338 * GstQuery
 339     Boxed types derived from GstMiniObject.
 340
 341     The GstStructure is removed from the public API, use the getters to get
 342     a handle to a GstStructure.
 343
 344     gst_query_new_application() -> gst_query_new_custom()
 345
 346     gst_query_parse_formats_length() -> gst_query_parse_n_formats()
 347     gst_query_parse_formats_nth() -> gst_query_parse_nth_format()
 348
 349     Some query utility functions no longer use an inout parameter for the
 350     destination/query format:
 351
 352       - gst_pad_query_position()
 353       - gst_pad_query_duration()
 354       - gst_pad_query_convert()
 355       - gst_pad_query_peer_position()
 356       - gst_pad_query_peer_duration()
 357       - gst_pad_query_peer_convert()
 358       - gst_element_query_position()
 359       - gst_element_query_duration()
 360       - gst_element_query_convert()
 361
 362     gst_element_get_query_types() and gst_pad_get_query_types() with associated
 363     functions were removed.
 364
 365 * GstBufferList
 366     Is now a boxed type derived from GstMiniObject.
 367
 368 * GstMessage
 369     Is now a boxed type derived from GstMiniObject
 370
 371     The GstStructure is removed from the public API, use the getters to get
 372     a handle to a GstStructure.
 373
 374     GST_MESSAGE_DURATION -> GST_MESSAGE_DURATION_CHANGED
 375
 376     gst_message_parse_duration() was removed (not needed any longer, do
 377     a duration query to query the updated duration)
 378
 379 * GstCaps
 380     Is now a boxed type derived from GstMiniObject.
 381
 382     GST_VIDEO_CAPS_xxx -> GST_VIDEO_CAPS_MAKE(xxx)
 383
 384     Some caps functions now take ownership of the input argument, for
 385     efficiency reasons (to avoid unnecessary copies to make them writable):
 386
 387       gst_caps_normalize (caps)          =>   caps = gst_caps_normalize (caps)
 388       gst_caps_do_simplify (caps)        =>   caps = gst_caps_simplify (caps)
 389       gst_caps_merge (caps,caps2)        =>   caps = gst_caps_merge (caps,caps2)
 390       gst_caps_merge_structure (caps,st) =>   caps = gst_caps_merge_structure (caps,st)
 391       gst_caps_truncate (caps)           =>   caps = gst_caps_truncate (caps)
 392
 393     The compiler should warn about unused return values from these functions,
 394     which may help find the places that need to be updated.
 395
 396     Removed functions:
 397
 398       gst_caps_union() -> gst_caps_merge():  Be careful because _merge takes
 399                  ownership of the arguments.
 400
 401 * GstClock
 402     gst_clock_id_wait_async_full() was renamed to gst_clock_id_wait_async() and
 403     the old gst_clock_id_wait_async() function was removed.
 404
 405 * GstSegment
 406     abs_rate was removed from the public fields, it can be trivially calculated
 407     from the rate field.
 408
 409     Also segment accumulation was removed from the segment event. This means
 410     that now the source/demuxer/parser needs to add the elapsed time of the
 411     previous segment themselves (this must be added to segment->base). If this
 412     is not done, looped playback won't work.
 413
 414     accum was renamed to base. last_stop was renamed to position.
 415
 416     The segment info now contains all the information needed to convert buffer
 417     timestamps to running_time and stream_time. There is no more segment
 418     accumulation, the GstSegment is completely self contained.
 419
 420     gst_segment_set_duration() and gst_segment_set_last_stop() are removed,
 421     simply modify the structure members duration and position respectively.
 422
 423     gst_segment_set_newsegment() is removed, it was used to accumulate segments
 424     and is not needed anymore, use gst_segment_copy_into() or modify the segment
 425     values directly.
 426
 427     gst_segment_set_seek() -> gst_segment_do_seek(). Updates the segment values
 428     with seek parameters.
 429
 430 * GstPluginFeature
 431     GST_PLUGIN_FEATURE_NAME() was removed, use GST_OBJECT_NAME() instead.
 432
 433 * GstTypeFind
 434     gst_type_find_peek() returns a const guint8 * now.
 435
 436 * GstTask
 437     gst_task_create() -> gst_task_new()
 438
 439 * GstAudio
 440     GstBaseAudioSink -> GstAudioBaseSink
 441     GstBaseAudioSrc -> GstAudioBaseSrc
 442     ...
 443
 444 * GstAdapter
 445     gst_adapter_peek() is removed, use gst_adapter_map() and gst_adapter_unmap()
 446     to get access to raw data from the adapter.
 447
 448     Arguments changed from guint to gsize.
 449
 450     gst_adapter_prev_timestamp() is removed and should be replaced with
 451     gst_adapter_prev_pts() and gst_adapter_prev_dts().
 452
 453 * GstBitReader, GstByteReader, GstByteWriter
 454     gst_*_reader_new_from_buffer(), gst_*_reader_init_from_buffer() removed, get
 455     access to the buffer data with _map() and then use the _new() functions.
 456
 457     gst_byte_reader_new_from_buffer() and gst_byte_reader_init_from_buffer()
 458     removed, get access to the buffer data and then use the _new() functions.
 459
 460 * GstCollectPads
 461     gst_collect_pads_read() removed, use _read_buffer() or _take_buffer() and
 462     then use the memory API to get to the memory.
 463
 464 * GstBaseSrc, GstBaseTransform, GstBaseSink
 465     GstBaseSrc::get_caps(), GstBaseTransform::transform_caps() and
 466     GstBaseSink::get_caps() now take a filter GstCaps* parameter to
 467     filter the caps and allow better negotiation decisions.
 468
 469 * GstBaseSrc
 470     When overriding GstBaseTransform::fixate() one should chain up to the parent
 471     implementation.
 472
 473 * GstBaseTransform
 474     GstBaseTransform::transform_caps() now gets the complete caps passed
 475     instead of getting it passed structure by structure.
 476
 477     GstBaseTransform::event() was renamed to sink_event(). The old function
 478     uses the return value to determine if the event should be forwarded or not.
 479     The new function has a default implementation that always forwards the event
 480     and the return value is simply returned as a result from the event handler.
 481     The semantics of the sink_event are thus the same as those for the src_event
 482     function.
 483
 484 * GstImplementsInterface
 485     has been removed. Interfaces need to be updated to either have
 486     is_ready/usable/available() methods, or have GError arguments
 487     to their methods so we can return an appropriate error if a
 488     particular interface isn't supported for a particular device.
 489
 490 * GstIterator
 491     uses a GValue based API now that is similar to the 0.10 API but
 492     allows bindings to properly use GstIterator and prevents complex
 493     return value ownership issues.
 494
 495 * GstNavigationInterface
 496     Now part of the video library in gst-plugins-base, and the interfaces
 497     library no longer exists.
 498
 499 * GstMixerInterface / GstTunerInterface
 500     Removed - no replacement?
 501
 502 * GstXOverlay interface
 503     Renamed to GstVideoOverlay, and now part of the video library in
 504     gst-plugins-base, as the interfaces library no longer exists.
 505
 506 * GstPropertyProbe interface
 507     Removed - no replacement in 1.0.x and 1.2.x, but since 1.4 there is
 508     a more featureful replacement for device discovery and feature querying,
 509     provided by GstDeviceMonitor, GstDevice, and friends. See the
 510     "GStreamer Device Discovery and Device Probing" documentation at
 511     http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-device-probing.html
 512
 513 * GstURIHandler
 514     gst_uri_handler_get_uri() and the get_uri vfunc now return a copy of
 515     the URI string
 516
 517     gst_uri_handler_set_uri() and the set_uri vfunc now take an additional
 518     GError argument so the handler can notify the caller why it didn't
 519     accept a particular URI.
 520
 521     gst_uri_handler_set_uri() now checks if the protocol of the URI passed
 522     is one of the protocols advertised by the uri handler, so set_uri vfunc
 523     implementations no longer need to check that as well.
 524
 525 * GstTagList
 526     is now an opaque mini object instead of being typedefed to a GstStructure.
 527
 528     While it was previously okay (and in some cases required because of
 529     missing taglist API) to cast a GstTagList to a GstStructure or use
 530     gst_structure_* API on taglists, you can no longer do that. Doing so will
 531     cause crashes.
 532
 533     Also, tag lists are refcounted now, and can therefore not be freely
 534     modified any longer. Make sure to call
 535
 536       taglist = gst_tag_list_make_writable (taglist);
 537
 538     before adding, removing or changing tags in the taglist.
 539
 540     gst_tag_list_new() has been renamed to gst_tag_list_new_empty().
 541     gst_tag_list_new_full*() have been renamed to gst_tag_list_new*().
 542     gst_tag_list_free() has been replaced by gst_tag_list_unref().
 543
 544     GST_TAG_IMAGE, GST_TAG_PREVIEW_IMAGE, GST_TAG_ATTACHMENT: many tags that
 545     used to be of type GstBuffer are now of type GstSample (which is basically
 546     a struct containing a buffer alongside caps and some other info).
 547
 548     gst_tag_list_get_buffer() => gst_tag_list_get_sample()
 549
 550     gst_is_tag_list() => GST_IS_TAG_LIST ()
 551
 552 * GstController:
 553     has now been merged into GstObject. It does not exists as a individual
 554     object anymore. In addition core contains a GstControlSource base class and
 555     the GstControlBinding. The actual control sources are in the controller
 556     library as before. The 2nd big change is that control sources generate
 557     a sequence of gdouble values and those are mapped to the property type and
 558     value range by GstControlBindings.
 559
 560     For plugins the effect is that gst_controller_init() is gone and
 561     gst_object_sync_values() is taking a GstObject * instead of GObject *.
 562
 563     For applications the effect is larger. The whole gst_controller_* API is
 564     gone and now available in simplified form under gst_object_*. ControlSources
 565     are now attached via GstControlBinding to properties. There are no GValue
 566     arguments used anymore when programming control sources.
 567
 568     A simple way to attach a ControlSource to a property is:
 569     gst_object_add_control_binding (object,
 570       gst_direct_control_binding_new (object, property_name, control_source));
 571
 572     gst_controller_set_property_disabled ->
 573       gst_object_set_control_binding_disabled
 574
 575     gst_object_get_value_arrays has been removed. Loop over the controlled
 576     properties fetch the value array. Also GstValueArray is gone. The fields of
 577     GstValueArray are now passed directly to gst_object_get_value_array as
 578     arguments.
 579
 580     GstInterpolationControlSource has been split. There is a new
 581     GstTimedValueControlSource baseclass and 2 sub classes:
 582     GstInterpolationControlSource and GstTriggerControlSource. The API for setting
 583     and getting the timestamps is in GstTimedValueControlSource.
 584
 585     gst_interpolation_control_source_set_interpolation_mode() has been removed.
 586     Set the "mode" gobject property on the control-source instead. The possible
 587     enum values have been renamed from GST_INTERPOLATE_XXX to
 588     GST_INTERPOLATION_MODE_XXX.
 589
 590 * GstRegistry
 591
 592     gst_registry_get_default() -> gst_registry_get()
 593     gst_default_registry_*(...) -> gst_registry_*(gst_registry_get(), ...)
 594
 595 * GstValue
 596
 597     GST_TYPE_DATE -> G_TYPE_DATE
 598     GST_VALUE_HOLDS_DATE(value) -> G_VALUE_HOLDS(value,G_TYPE_DATE)
 599     gst_value_set_date() -> g_value_set_boxed()
 600     gst_value_get_date() -> g_value_get_boxed()
 601
 602 * GError/GstGError
 603
 604     GstGError -> GError
 605     GST_TYPE_G_ERROR / gst_g_error_get_type() -> G_TYPE_ERROR
 606
 607 * GstVideo
 608
 609     GstXOverlay interface -> renamed to GstVideoOverlay, and now part of
 610     the video library in gst-plugins-base, as the interfaces library
 611     no longer exists.
 612
 613     gst_video_format_parse_caps() -> use gst_video_info_from_caps() and
 614         then GstVideoInfo.
 615
 616 * GstChildProxy
 617
 618     gst_child_proxy_lookup() can no longer be called on GObjects that
 619     do not implement the GstChildProxy interface. Use
 620       g_object_class_find_property (G_OBJECT_GET_CLASS (obj), "foo")
 621     instead for non-childproxy objects.
 622
 623 * "codec-data" and "streamheader" field in GstCaps (not implemented yet!)
 624
 625     codec-data and stream headers are no longer in GstCaps, but sent as
 626     part of a STREAM CONFIG event (which should be sent after the initial
 627     CAPS event if needed).
 628
 629 =============================================================================
 630   Porting checklist - "soft" API changes
 631 =============================================================================
 632
 633  * the "ffmpegcolorspace" element has been replaced by "videoconvert"
 634
 635  * "playbin2" has been renamed to "playbin", with similar API
 636
 637  * "decodebin2" has been renamed to "decodebin", with similar API. Note
 638    that there is no longer a "new-decoded-pad" signal, just use GstElement's
 639    "pad-added" signal instead (but don't forget to remove the 'gboolean last'
 640    argument from your old signal callback function signature).
 641
 642  * the names of some "formatted" pad templates has been changed from e.g.
 643    "src%d" to "src%u" or "src_%u" or similar, since we don't want to see
 644    negative numbers in pad names. This mostly affects applications that
 645    create request pads from elements.
 646
 647  * some elements that used to have a single dynamic source pad have a
 648    static source pad now. Example: wavparse, id3demux, iceydemux, apedemux.
 649    (This does not affect applications using decodebin or playbin).
 650
 651  * the name of the GstXOverlay "prepare-xwindow-id" message has changed
 652    to "prepare-window-handle" (and GstXOverlay has been renamed to
 653    GstVideoOverlay). Code that checks for the string directly should be
 654    changed to use gst_is_video_overlay_prepare_window_handle_message(message)
 655    instead.
 656
 657  * playbin now proxies the GstVideoOverlay (former GstXOverlay) interface,
 658    so most applications can just remove the sync bus handler where they
 659    would set the window ID, and instead just set the window ID on playbin
 660    from the application thread before starting playback.
 661
 662  * playbin also proxies the GstColorBalance and GstNavigation interfaces,
 663    so applications that use this don't need to go fishing for elements
 664    that may implement those any more, but can just use them unconditionally.
 665
 666  * level sendy the per channel values as a GValueArray instead of a GstValueList
 667    see gst-plugins-good/test/examples/level/level-example.c
 668
 669  * media type / caps changes:
 670
 671       audio/x-raw-int   -> audio/x-raw
 672       audio/x-raw-float -> audio/x-raw
 673
 674       video/x-raw-rgb   -> video/x-raw
 675       video/x-raw-yuv   -> video/x-raw
 676       video/x-raw-bayer -> video/x-bayer
 677
 678       video/x-dvd-subpicture -> subpicture/x-dvd
 679
 680       application/ogg  -> audio/ogg or video/ogg (or application/ogg)
 681
 682       video/x-matroska -> audio/x-matroska or video/x-matroska or video/x-matroska-3d
 683
 684       video/webm -> audio/webm or video/webm
 685
 686       text/plain          -> text/x-raw, format=utf8
 687       text/x-pango-markup -> text/x-raw, format=pango-markup
 688
 689  * element name changes/replacements:
 690
 691       playbin2   -> playbin
 692       decodebin2 -> decodebin
 693       camerabin2 -> camerabin
 694
 695       ffmpegcolorspace -> videoconvert
 696
 697       mp3parse         -> mpegaudioparse
 698       legacyh264parse  -> h264parse (note: properties gone, use downstream caps)
 699       lame             -> lamemp3enc
 700       jp2k{enc,dec}    -> openjpeg{enc,dec}
 701
 702       ffenc_*   -> avenc_*
 703       ffdec_*   -> avdec_*
 704       ffdemux_* -> avdemux_*
 705       ffmux_*   -> avmux_*
 706
 707  * property type changes (very nasty for code using the C g_object_set/get API)
 708
 709       - playbin2::connection-speed:
 710         changed from a plain unsigned integer to an unsigned 64-bit integer
 711
 712  * property default value changes
 713
 714       - souphttpsrc now by default asks the server to send icecast metadata
 715         if available (from internet radio streams usually). This has
 716         implications for hand-rolled pipelines, which may require an icydemux
 717         element now to parse that metadata (without that the data might be
 718         garbled). Since 1.0.7 the "iradio-mode" property has been re-added
 719         to allow users to switch off the default behaviour of requesting
 720         icecast metadata.
 721       - fakesink, identity and fakesrc's "silent" property default value
 722         changed from FALSE to TRUE. This means that "gst-launch-1.0 -v" will
 723         not show messages from any of these elements unless you explicitly
 724         request them with "silent=false". This change was made for efficiency
 725         reasons.
 726
 727  * decoders now require parsers in front of them
 728
 729       - in 1.0 many decoders require parsers in front of them in many
 730         situation. This is to simplify decoders and move a lot of the
 731         "intelligence" into the parser. This makes it easier to write
 732         decoders and minimises behavioural differences between different
 733         decoders (both for the same format and different formats). So e.g.
 734
 735           filesrc ! flacdec ! audioconvert ! pulsesink
 736
 737         now becomes
 738
 739           filesrc ! flacparse ! flacdec ! audioconvert ! pulsesink
 740
 741         but better just use
 742
 743           filesrc ! decodebin ! audioconvert ! pulsesink
 744
 745         or even
 746
 747           playbin uri=file:///path/to/foo.flac audio-sink=pulsesink
 748
 749  * non-time-based sources do not provide presentation timestamps anymore
 750
 751       - Sources based on BYTEs instead of TIME (like filesrc or souphttpsrc)
 752         do not provide PTS anymore. In the 0.10 API they provided a PTS with
 753         value 0 for the first buffer. This was needed for legacy operation but
 754         has been removed in the 1.0 API. These sources will usually still put
 755         a 0 DTS (decoding timestamp) on the first buffer even if PTS is unset.
 756
 757 =============================================================================
 758   Troubleshooting
 759 =============================================================================
 760
 761  * GLib-GObject-WARNING **: cannot register existing type `GstObject'
 762
 763    If you get this warning, this usually means your plugin or application
 764    is linked against both libgstreamer-1.0.so and libgstreamer-0.10.so.
 765    Make sure you have changed all -0.10 references in your configure.ac,
 766    pkg-config invocations or Makefile.am/Makefile to -1.0.
 767
 768    While both versions can co-exist without problems on the same system, it
 769    is not possible to use both versions at the same time in a single running
 770    process. In most cases this would also not be the desired behaviour.
 771