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 * GstPad:
  72     gst_pad_get_caps() does not return writable caps anymore and an explicit
  73     gst_caps_make_writable() needs to be performed. This was the functionality
  74     of gst_pad_get_caps_reffed(), which is removed now.
  75
  76     A similar change was done for gst_pad_peer_get_caps() and
  77     gst_pad_peer_get_caps_reffed()
  78
  79     gst_pad_set_bufferalloc_function(), gst_pad_alloc_buffer() and
  80     gst_pad_alloc_buffer_and_set_caps() are removed. Use the ALLOCATION query
  81     now to obtain a reference to a bufferpool object that can be used to
  82     allocate buffers.
  83
  84     removed sched_private, it should not be used, use g_object_set_qdata() or
  85     use element_private.
  86
  87     Removed GST_PAD_CAPS() use gst_pad_get_current_caps() to get a handle to the
  88     currently configured caps.
  89
  90     GstPadGetCapsFunction, gst_pad_get_caps(), gst_pad_peer_get_caps(),
  91     gst_pad_proxy_getcaps() now takes a GstCaps* parameter to inform
  92     the other side about the possible caps and preferences.
  93
  94     gst_pad_get_pad_template_caps() and gst_pad_get_pad_template()
  95     return a new reference of the caps or template now and the return
  96     value needs to be unreffed after usage.
  97
  98     gst_pad_set_caps() now pushes a CAPS event for backward compatibility.
  99     Consider sending the CAPS event yourself. It is not possible anymore to set
 100     NULL caps.
 101
 102     gst_pad_set_checkgetrange_function() and gst_pad_check_pull_range() are
 103     gone, use the SCHEDULING query now.
 104
 105     gst_pad_set_blocked(), gst_pad_set_blocked_async(),
 106     gst_pad_set_blocked_async_full() are removed, use the gst_pad_add_probe()
 107     method with the GST_PROBE_TYPE_BLOCK to get the same result as the async
 108     blocking version. There is no more sync version of blocking, this is in
 109     general dangerous and can be implemented using the callbacks if needed.
 110
 111     gst_pad_add_data_probe(), gst_pad_add_data_probe_full(),
 112     gst_pad_remove_data_probe(), gst_pad_add_event_probe(),
 113     gst_pad_add_event_probe_full(), gst_pad_remove_event_probe(),
 114     gst_pad_add_buffer_probe(), gst_pad_add_buffer_probe_full(),
 115     gst_pad_remove_buffer_probe() are removed. Use gst_pad_add_probe() and
 116     gst_pad_remove_probe() for equivalent functionality.
 117
 118     The have-data signal was removed from pads, it was never supposed to be used
 119     without calling the _add_.*_probe() methods.
 120
 121     The request-link signal was removed. It was never used.
 122
 123     gst_pad_get_negotiated_caps() -> get_pad_get_current_caps()
 124
 125 * GstPadTemplate
 126     gst_pad_template_get_caps() returns a new reference of the caps
 127     and the return value needs to be unreffed after usage.
 128
 129     gst_pad_template_new() does not take ownership of the caps anymore.
 130
 131     GstPadTemplate is now created with a floating ref and
 132     gst_element_class_add_pad_template() takes ownership of this floating ref.
 133
 134     GstPadTemplate instances are considered immutable and must not be
 135     changed.
 136
 137 * GstMiniObject
 138     A miniobject is now a simple refcounted structure holding the information
 139     common to buffers, events, messages, queries and caps.
 140
 141     There is no more GST_TYPE_MINIOBJECT as the type for subclasses.
 142     G_TYPE_BOXED can be used as the type of all GstMiniObject based types such
 143     as buffers, events, messages, caps, etc. Signals, for example, would use the
 144     boxed type if the argument include GstMiniObject derived types.
 145
 146     gst_mini_object_new() is removed. You would allocate memory with the the
 147     methods specific for the derived type.
 148
 149     GstParamSpecMiniObject is removed, use boxed param spec now with the GType
 150     of the specific GstMiniObject derived type. Also
 151     gst_param_spec_mini_object().
 152
 153     gst_param_spec_mini_object() -> g_param_spec_boxed()
 154
 155     The specific gst_value_*_mini_object() methods are removed, used the generic
 156     boxed methods instead.
 157
 158     gst_value_set_mini_object() -> g_value_set_boxed()
 159     gst_value_take_mini_object() -> g_value_take_boxed()
 160     gst_value_take_get_object() -> g_value_get_boxed()
 161     gst_value_take_dup_object() -> g_value_dup_boxed()
 162
 163     GST_VALUE_HOLDS_MINI_OBJECT() was removed, use G_VALUE_HOLDS_BOXED() or
 164     type-specific GST_VALUE_HOLDS_{BUFFER,CAPS,etc.}() instead.
 165
 166     The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
 167     memory in buffers as READONLY. Marking memory READONLY can now be done
 168     with the GstMemory API. Writability of miniobjects is now only done by using
 169     the refcount.
 170
 171 * GstBuffer
 172     A GstBuffer is now a simple boxed type this means that subclassing is not
 173     possible anymore.
 174
 175     To add data to the buffer you would now use gst_buffer_take_memory() with
 176     a GstMemory object containing the data. Multiple memory blocks can added to
 177     a GstBuffer that can then be retrieved with gst_buffer_peek_memory().
 178
 179     GST_BUFFER_DATA(), GST_BUFFER_MALLOCDATA(), GST_BUFFER_FREE_FUNC() and
 180     GST_BUFFER_SIZE() are gone, along with the fields in GstBuffer. Use the
 181     memory API to get access to the buffer data. GST_BUFFER_SIZE() can be
 182     replaced with gst_buffer_get_size() but if also access to the data is
 183     required, gst_buffer_map() can return both the size and data in one go.
 184
 185     The most common way to access all the data in a buffer is by using
 186     gst_buffer_map() and gst_buffer_unmap(). These calls require you to specify
 187     the access mode required to the data and will automatically merge and return
 188     a writable copy of the data.
 189
 190     The buffer must be writable (gst_buffer_is_writable()) in order to modify
 191     the fields, metadata or buffer memory. gst_buffer_make_writable() will not
 192     automatically make a writable copy of the memory but will instead increase
 193     the refcount of the memory. The _map() and _peek_memory() methods will
 194     automatically create writable copies when needed.
 195
 196     gst_buffer_make_metadata_writable() is gone, you can replace this safely
 197     with gst_buffer_make_writable().
 198
 199     gst_buffer_create_sub() is gone and can be safely replaced with
 200     gst_buffer_copy_region().
 201
 202     Changing the size of the buffer data can be done with gst_buffer_resize(),
 203     which will also update the metadata fields correctly. gst_buffer_set_size()
 204     is #defined to a special case of gst_buffer_resize() with a 0 offset.
 205
 206     gst_buffer_try_new_and_alloc() is replaced with gst_buffer_new_and_alloc(),
 207     which now returns NULL when memory allocation fails.
 208
 209     GST_BUFFER_CAPS() is gone, caps are not set on buffers anymore but are set
 210     on the pads where the buffer is pushed on. Likewise GST_BUFFER_COPY_CAPS is
 211     not needed anymore. gst_buffer_get/set_caps() are gone too.
 212
 213 * GstBufferList
 214     The GstBufferList object is much simplified because most of the
 215     functionality in the groups is now part of the GstMemory in buffers.
 216
 217     The object is reduced to encapsulating an array of buffers that you can send
 218     with the regular gst_pad_push_list. The iterator is not needed anymore
 219     because you can simply use gst_buffer_list_len() and gst_buffer_list_get()
 220     to iterate the array.
 221
 222     For dealing with the groups, it's now needed to add the memory blocks to
 223     GstBuffer and use the normal buffer API to get and merge the groups.
 224
 225 * GstStructure
 226
 227     The GArray of the structure fields are moved to private part and are not
 228     accessible from the application anymore. Use the methods to retrieve and
 229     modify fields from the array.
 230
 231 * GstEvent
 232     GST_EVENT_SRC is removed. Don't use this anymore.
 233
 234     gst_event_new_qos_full() -> gst_event_new_qos()
 235     gst_event_parse_qos_full() -> gst_event_parse_qos()
 236
 237     The GstStructure is removed from the public API, use the getters to get
 238     a handle to a GstStructure.
 239
 240     GST_EVENT_NEWSEGMENT -> GST_EVENT_SEGMENT
 241
 242     gst_event_new_new_segment () -> gst_event_new_segment() and it takes a
 243     GstSegment structure as an argument.
 244     gst_event_parse_new_segment() -> gst_event_parse_segment() to retrieve the
 245     GstSegment structure from the event.
 246     gst_event_copy_segment() to fill a GstSegment structure.
 247
 248 * GstQuery
 249     Boxed types derived from GstMiniObject.
 250
 251     The GstStructure is removed from the public API, use the getters to get
 252     a handle to a GstStructure.
 253
 254     gst_query_new_application() -> gst_query_new_custom()
 255
 256     gst_query_parse_formats_length() -> gst_query_parse_n_formats()
 257     gst_query_parse_formats_nth() -> gst_query_parse_nth_format()
 258
 259     Some query utility functionsno longer use an inout parameter for the
 260     destination/query format:
 261
 262       - gst_pad_query_position()
 263       - gst_pad_query_duration()
 264       - gst_pad_query_convert()
 265       - gst_pad_query_peer_position()
 266       - gst_pad_query_peer_duration()
 267       - gst_pad_query_peer_convert()
 268       - gst_element_query_position()
 269       - gst_element_query_duration()
 270       - gst_element_query_convert()
 271
 272 * GstBufferList
 273     Is now a boxed type derived from GstMiniObject.
 274
 275 * GstMessage
 276     Is now a boxed type derived from GstMiniObject
 277
 278     The GstStructure is removed from the public API, use the getters to get
 279     a handle to a GstStructure.
 280
 281 * GstCaps
 282     Is now a boxed type derived from GstMiniObject.
 283
 284 * GstSegment
 285     abs_rate was removed from the public fields, it can be trivially calculated
 286     from the rate field.
 287
 288     accum was renamed to base. last_stop was renamed to position.
 289
 290     The segment info now contains all the information needed to convert buffer
 291     timestamps to running_time and stream_time. There is no more segment
 292     accumulation, the GstSegment is completely self contained.
 293
 294     gst_segment_set_duration() and gst_segment_set_last_stop() are removed,
 295     simply modify the structure members duration and position respectively.
 296
 297     gst_segment_set_newsegment() is removed, it was used to accumulate segments
 298     and is not needed anymore, use gst_segment_copy_into() or modify the segment
 299     values directly.
 300
 301     gst_segment_set_seek() -> gst_segment_do_seek(). Updates the segment values
 302     with seek parameters.
 303
 304 * GstPluginFeature
 305     GST_PLUGIN_FEATURE_NAME() was removed, use GST_OBJECT_NAME() instead.
 306
 307 * GstTypeFind
 308     gst_type_find_peek() returns a const guint8 * now.
 309
 310 * GstAdapter
 311     gst_adapter_peek() is removed, use gst_adapter_map() and gst_adapter_unmap()
 312     to get access to raw data from the adapter.
 313
 314     Arguments renamed from guint to gsize.
 315
 316 * GstBitReader, GstByteReader, GstByteWriter
 317     gst_*_reader_new_from_buffer(), gst_*_reader_init_from_buffer() removed, get
 318     access to the buffer data with _map() and then use the _new() functions.
 319
 320     gst_byte_reader_new_from_buffer() and gst_byte_reader_init_from_buffer()
 321     removed, get access to the buffer data and then use the _new() functions.
 322
 323 * GstCollectPads
 324     gst_collect_pads_read() removed, use _read_buffer() or _take_buffer() and
 325     then use the memory API to get to the memory.
 326
 327 * GstBaseSrc, GstBaseTransform, GstBaseSink
 328     GstBaseSrc::get_caps(), GstBaseTransform::transform_caps() and
 329     GstBaseSink::get_caps() now take a filter GstCaps* parameter to
 330     filter the caps and allow better negotiation decisions.
 331
 332 * GstBaseTransform
 333     GstBaseTransform::transform_caps() now gets the complete caps passed
 334     instead of getting it passed structure by structure.
 335
 336     GstBaseTransform::event() was renamed to sink_event(). The old function
 337     uses the return value to determine if the event should be forwarded or not.
 338     The new function has a default implementation that always forwards the event
 339     and the return value is simply returned as a result from the event handler.
 340     The semantics of the sink_event are thus the same as those for the src_event
 341     function.
 342
 343 * GstImplementsInterface
 344     has been removed. Interfaces need to be updated to either have
 345     is_ready/usable/available() methods, or have GError arguments
 346     to their methods so we can return an appropriate error if a
 347     particular interface isn't supported for a particular device.
 348
 349 * GstIterator
 350     uses a GValue based API now that is similar to the 0.10 API but
 351     allows bindings to properly use GstIterator and prevents complex
 352     return value ownership issues.