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 -> GstPadMode, GST_ACTIVATE_* -> GST_PAD_MODE_*
 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     The GstPadGetCapsFunction was removed and replaced with a GST_QUERY_CAPS
 140     query.
 141
 142     gst_pad_proxy_getcaps() -> gst_pad_proxy_query_caps()
 143     gst_pad_get_caps() -> gst_pad_query_caps()
 144     gst_pad_peer_get_caps() -> gst_pad_peer_query_caps()
 145     gst_pad_accept_caps() -> gst_pad_query_accept_caps()
 146     gst_pad_peer_accept_caps() -> gst_pad_peer_query_accept_caps()
 147     gst_pad_query_peer_*() -> gst_pad_peer_query_*()
 148
 149     GstPadFlags: GST_PAD_* -> GST_PAD_FLAG_*
 150
 151 * GstPadTemplate
 152     gst_pad_template_get_caps() returns a new reference of the caps
 153     and the return value needs to be unreffed after usage.
 154
 155     gst_pad_template_new() does not take ownership of the caps anymore.
 156
 157     GstPadTemplate is now created with a floating ref and
 158     gst_element_class_add_pad_template() takes ownership of this floating ref.
 159
 160     GstPadTemplate instances are considered immutable and must not be
 161     changed.
 162
 163 * GstMiniObject
 164     A miniobject is now a simple refcounted structure holding the information
 165     common to buffers, events, messages, queries and caps.
 166
 167     There is no more GST_TYPE_MINIOBJECT as the type for subclasses.
 168     G_TYPE_BOXED can be used as the type of all GstMiniObject based types such
 169     as buffers, events, messages, caps, etc. Signals, for example, would use the
 170     boxed type if the argument include GstMiniObject derived types.
 171
 172     gst_mini_object_new() is removed. You would allocate memory with the the
 173     methods specific for the derived type.
 174
 175     GstParamSpecMiniObject is removed, use boxed param spec now with the GType
 176     of the specific GstMiniObject derived type. Also
 177     gst_param_spec_mini_object().
 178
 179     gst_param_spec_mini_object() -> g_param_spec_boxed()
 180
 181     The specific gst_value_*_mini_object() methods are removed, used the generic
 182     boxed methods instead.
 183
 184     gst_value_set_mini_object() -> g_value_set_boxed()
 185     gst_value_take_mini_object() -> g_value_take_boxed()
 186     gst_value_take_get_object() -> g_value_get_boxed()
 187     gst_value_take_dup_object() -> g_value_dup_boxed()
 188
 189     GST_VALUE_HOLDS_MINI_OBJECT() was removed, use G_VALUE_HOLDS_BOXED() or
 190     type-specific GST_VALUE_HOLDS_{BUFFER,CAPS,etc.}() instead.
 191
 192     The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
 193     memory in buffers as READONLY. Marking memory READONLY can now be done
 194     with the GstMemory API. Writability of miniobjects is now only done by using
 195     the refcount.
 196
 197 * GstBuffer
 198     A GstBuffer is now a simple boxed type this means that subclassing is not
 199     possible anymore.
 200
 201     To add data to the buffer you would now use gst_buffer_take_memory() with
 202     a GstMemory object containing the data. Multiple memory blocks can added to
 203     a GstBuffer that can then be retrieved with gst_buffer_peek_memory().
 204
 205     GST_BUFFER_DATA(), GST_BUFFER_MALLOCDATA(), GST_BUFFER_FREE_FUNC() and
 206     GST_BUFFER_SIZE() are gone, along with the fields in GstBuffer. Use the
 207     memory API to get access to the buffer data. GST_BUFFER_SIZE() can be
 208     replaced with gst_buffer_get_size() but if also access to the data is
 209     required, gst_buffer_map() can return both the size and data in one go.
 210
 211     The most common way to access all the data in a buffer is by using
 212     gst_buffer_map() and gst_buffer_unmap(). These calls require you to specify
 213     the access mode required to the data and will automatically merge and return
 214     a writable copy of the data.
 215
 216     The buffer must be writable (gst_buffer_is_writable()) in order to modify
 217     the fields, metadata or buffer memory. gst_buffer_make_writable() will not
 218     automatically make a writable copy of the memory but will instead increase
 219     the refcount of the memory. The _map() and _peek_memory() methods will
 220     automatically create writable copies when needed.
 221
 222     gst_buffer_make_metadata_writable() is gone, you can replace this safely
 223     with gst_buffer_make_writable().
 224
 225     gst_buffer_copy_metadata() is gone, use gst_buffer_copy_into() instead and
 226     mind use GST_BUFFER_COPY_METADATA instead of the former GST_BUFFER_COPY_ALL.
 227
 228     gst_buffer_create_sub() is gone and can be safely replaced with
 229     gst_buffer_copy_region().
 230
 231     Changing the size of the buffer data can be done with gst_buffer_resize(),
 232     which will also update the metadata fields correctly. gst_buffer_set_size()
 233     is #defined to a special case of gst_buffer_resize() with a 0 offset.
 234
 235     gst_buffer_try_new_and_alloc() is replaced with gst_buffer_new_and_alloc(),
 236     which now returns NULL when memory allocation fails.
 237
 238     GST_BUFFER_CAPS() is gone, caps are not set on buffers anymore but are set
 239     on the pads where the buffer is pushed on. Likewise GST_BUFFER_COPY_CAPS is
 240     not needed anymore. gst_buffer_get/set_caps() are gone too.
 241
 242     GST_BUFFER_TIMESTAMP is gone, use GST_BUFFER_PTS or GST_BUFFER_DTS instead.
 243     Likewise GST_BUFFER_TIMESTAMP_IS_VALID() was changed to
 244     GST_BUFFER_PTS_IS_VALID and GST_BUFFER_DTS_IS_VALID
 245
 246 * GstBufferList
 247     The GstBufferList object is much simplified because most of the
 248     functionality in the groups is now part of the GstMemory in buffers.
 249
 250     The object is reduced to encapsulating an array of buffers that you can send
 251     with the regular gst_pad_push_list. The iterator is not needed anymore
 252     because you can simply use gst_buffer_list_length() and gst_buffer_list_get()
 253     to iterate the array.
 254
 255     For dealing with the groups, it's now needed to add the memory blocks to
 256     GstBuffer and use the normal buffer API to get and merge the groups.
 257
 258     gst_buffer_list_sized_new() -> gst_buffer_list_new_sized()
 259     gst_buffer_list_len() -> gst_buffer_list_length()
 260
 261 * GstStructure
 262
 263     The GArray of the structure fields are moved to private part and are not
 264     accessible from the application anymore. Use the methods to retrieve and
 265     modify fields from the array.
 266
 267     gst_structure_empty_new() -> gst_structure_new_empty()
 268     gst_structure_id_empty_new() -> gst_structure_new_id_empty()
 269     gst_structure_id_new() -> gst_structure_new_id()
 270
 271 * GstEvent
 272     Boxed types derived from GstMiniObject.
 273
 274     GST_EVENT_SRC is removed. Don't use this anymore.
 275
 276     gst_event_new_qos_full() -> gst_event_new_qos()
 277     gst_event_parse_qos_full() -> gst_event_parse_qos()
 278
 279     The GstStructure is removed from the public API, use the getters to get
 280     a handle to a GstStructure.
 281
 282     GST_EVENT_NEWSEGMENT -> GST_EVENT_SEGMENT
 283
 284     gst_event_new_new_segment () -> gst_event_new_segment() and it takes a
 285     GstSegment structure as an argument.
 286     gst_event_parse_new_segment() -> gst_event_parse_segment() to retrieve the
 287     GstSegment structure from the event.
 288     gst_event_copy_segment() to fill a GstSegment structure.
 289
 290 * GstQuery
 291     Boxed types derived from GstMiniObject.
 292
 293     The GstStructure is removed from the public API, use the getters to get
 294     a handle to a GstStructure.
 295
 296     gst_query_new_application() -> gst_query_new_custom()
 297
 298     gst_query_parse_formats_length() -> gst_query_parse_n_formats()
 299     gst_query_parse_formats_nth() -> gst_query_parse_nth_format()
 300
 301     Some query utility functions no longer use an inout parameter for the
 302     destination/query format:
 303
 304       - gst_pad_query_position()
 305       - gst_pad_query_duration()
 306       - gst_pad_query_convert()
 307       - gst_pad_query_peer_position()
 308       - gst_pad_query_peer_duration()
 309       - gst_pad_query_peer_convert()
 310       - gst_element_query_position()
 311       - gst_element_query_duration()
 312       - gst_element_query_convert()
 313
 314     gst_element_get_query_types() and gst_pad_get_query_types() with associated
 315     functions were removed.
 316
 317 * GstBufferList
 318     Is now a boxed type derived from GstMiniObject.
 319
 320 * GstMessage
 321     Is now a boxed type derived from GstMiniObject
 322
 323     The GstStructure is removed from the public API, use the getters to get
 324     a handle to a GstStructure.
 325
 326 * GstCaps
 327     Is now a boxed type derived from GstMiniObject.
 328
 329     GST_VIDEO_CAPS_xxx -> GST_VIDEO_CAPS_MAKE(xxx)
 330
 331 * GstSegment
 332     abs_rate was removed from the public fields, it can be trivially calculated
 333     from the rate field.
 334
 335     accum was renamed to base. last_stop was renamed to position.
 336
 337     The segment info now contains all the information needed to convert buffer
 338     timestamps to running_time and stream_time. There is no more segment
 339     accumulation, the GstSegment is completely self contained.
 340
 341     gst_segment_set_duration() and gst_segment_set_last_stop() are removed,
 342     simply modify the structure members duration and position respectively.
 343
 344     gst_segment_set_newsegment() is removed, it was used to accumulate segments
 345     and is not needed anymore, use gst_segment_copy_into() or modify the segment
 346     values directly.
 347
 348     gst_segment_set_seek() -> gst_segment_do_seek(). Updates the segment values
 349     with seek parameters.
 350
 351 * GstPluginFeature
 352     GST_PLUGIN_FEATURE_NAME() was removed, use GST_OBJECT_NAME() instead.
 353
 354 * GstTypeFind
 355     gst_type_find_peek() returns a const guint8 * now.
 356
 357 * GstTask
 358     gst_task_create() -> gst_task_new()
 359
 360 * GstAdapter
 361     gst_adapter_peek() is removed, use gst_adapter_map() and gst_adapter_unmap()
 362     to get access to raw data from the adapter.
 363
 364     Arguments changed from guint to gsize.
 365
 366     gst_adapter_prev_timestamp() is removed and should be replaced with
 367     gst_adapter_prev_pts() and gst_adapter_prev_dts().
 368
 369 * GstBitReader, GstByteReader, GstByteWriter
 370     gst_*_reader_new_from_buffer(), gst_*_reader_init_from_buffer() removed, get
 371     access to the buffer data with _map() and then use the _new() functions.
 372
 373     gst_byte_reader_new_from_buffer() and gst_byte_reader_init_from_buffer()
 374     removed, get access to the buffer data and then use the _new() functions.
 375
 376 * GstCollectPads
 377     gst_collect_pads_read() removed, use _read_buffer() or _take_buffer() and
 378     then use the memory API to get to the memory.
 379
 380 * GstBaseSrc, GstBaseTransform, GstBaseSink
 381     GstBaseSrc::get_caps(), GstBaseTransform::transform_caps() and
 382     GstBaseSink::get_caps() now take a filter GstCaps* parameter to
 383     filter the caps and allow better negotiation decisions.
 384
 385 * GstBaseTransform
 386     GstBaseTransform::transform_caps() now gets the complete caps passed
 387     instead of getting it passed structure by structure.
 388
 389     GstBaseTransform::event() was renamed to sink_event(). The old function
 390     uses the return value to determine if the event should be forwarded or not.
 391     The new function has a default implementation that always forwards the event
 392     and the return value is simply returned as a result from the event handler.
 393     The semantics of the sink_event are thus the same as those for the src_event
 394     function.
 395
 396 * GstImplementsInterface
 397     has been removed. Interfaces need to be updated to either have
 398     is_ready/usable/available() methods, or have GError arguments
 399     to their methods so we can return an appropriate error if a
 400     particular interface isn't supported for a particular device.
 401
 402 * GstIterator
 403     uses a GValue based API now that is similar to the 0.10 API but
 404     allows bindings to properly use GstIterator and prevents complex
 405     return value ownership issues.
 406
 407 * GstURIHandler
 408     gst_uri_handler_get_uri() and the get_uri vfunc now return a copy of
 409     the URI string
 410
 411     gst_uri_handler_set_uri() and the set_uri vfunc now take an additional
 412     GError argument so the handler can notify the caller why it didn't
 413     accept a particular URI.
 414
 415     gst_uri_handler_set_uri() now checks if the protocol of the URI passed
 416     is one of the protocols advertised by the uri handler, so set_uri vfunc
 417     implementations no longer need to check that as well.
 418
 419 * GstTagList
 420     is now an opaque object instead of being typedefed to a GstStructure. Cast
 421     to GstStructure or use gst_structure_* API on it at your own peril (it may
 422     still work for now, but might be changed in future).
 423
 424     gst_tag_list_new() has been renamed to gst_tag_list_new_empty().
 425     gst_tag_list_new_full*() have been renamed to gst_tag_list_new*().
 426
 427 * GstController:
 428     has now been merged into GstObject. The control sources are in the
 429     controller library still.
 430
 431     For plugins the effect is that gst_controller_init() is gone and
 432     gst_object_sync_values() is taking a GstObject * instead of GObject *.
 433
 434     For applications the effect is larger. The whole gst_controller_* API is
 435     gone and now available in simplified form under gst_object_*. There is no
 436     more GstController object. Attach a control source to a property to control
 437     it and attach NULL to un-control it.
 438
 439     gst_controller_new* -> gst_object_set_control_source
 440     gst_controller_add_properties -> gst_object_set_control_source
 441     gst_controller_set_control_source -> gst_object_set_control_source
 442     gst_controller_get_control_source -> gst_object_get_control_source
 443
 444     gst_controller_set_property_disabled -> gst_object_set_controlled_property_disabled