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
  46     gst_element_factory_get_longname -> gst_element_factory_get_metadata
  47     gst_element_factory_get_klass -> gst_element_factory_get_metadata
  48     gst_element_factory_get_description -> gst_element_factory_get_metadata
  49     gst_element_factory_get_author -> gst_element_factory_get_metadata
  50     gst_element_factory_get_documentation_uri -> gst_element_factory_get_metadata
  51     gst_element_factory_get_icon_name -> gst_element_factory_get_metadata
  52
  53     gstelementmetadata.h contains the keys for all standard metadata.
  54
  55     Element metadata and pad templates are inherited from parent classes and
  56     should be added in class_init instead of base_init.
  57
  58     gst_element_class_add_pad_template() takes ownership of the template
  59
  60     Elements that change the duration must post DURATION messages on the
  61     bus when the duration changes in PAUSED or PLAYING.
  62
  63     gst_element_lost_state_full() -> gst_element_lost_state()
  64     gst_element_lost_state() -> gst_element_lost_state(, TRUE)
  65
  66     request_new_pad_full() -> request_new_pad()
  67
  68 * GstPad:
  69     gst_pad_get_caps() does not return writable caps anymore and an explicit
  70     gst_caps_make_writable() needs to be performed. This was the functionality
  71     of gst_pad_get_caps_reffed(), which is removed now.
  72
  73     A similar change was done for gst_pad_peer_get_caps() and
  74     gst_pad_peer_get_caps_reffed()
  75
  76     gst_pad_set_bufferalloc_function(), gst_pad_alloc_buffer() and
  77     gst_pad_alloc_buffer_and_set_caps() are removed. Use the ALLOCATION query
  78     now to obtain a reference to a bufferpool object that can be used to
  79     allocate buffers.
  80
  81     removed sched_private, it should not be used, use g_object_set_qdata() or
  82     use element_private.
  83
  84     Removed GST_PAD_CAPS() use gst_pad_get_current_caps() to get a handle to the
  85     currently configured caps.
  86
  87     GstPadGetCapsFunction, gst_pad_get_caps(), gst_pad_peer_get_caps(),
  88     gst_pad_proxy_getcaps() now takes a GstCaps* parameter to inform
  89     the other side about the possible caps and preferences.
  90
  91     gst_pad_get_pad_template_caps() and gst_pad_get_pad_template()
  92     return a new reference of the caps or template now and the return
  93     value needs to be unreffed after usage.
  94
  95 * GstPadTemplate
  96     gst_pad_template_get_caps() returns a new reference of the caps
  97     and the return value needs to be unreffed after usage.
  98
  99     gst_pad_template_new() does not take ownership of the caps anymore.
 100
 101     GstPadTemplate is now created with a floating ref and
 102     gst_element_class_add_pad_template() takes ownership of this floating ref.
 103
 104 * GstMiniObject
 105     A miniobject is now a simple refcounted structure holding the information
 106     common to buffers, events, messages, queries and caps.
 107
 108     There is no more GST_TYPE_MINIOBJECT as the type for subclasses.
 109     G_TYPE_BOXED can be used as the type of all GstMiniObject based types such
 110     as buffers, events, messages, caps, etc. Signals, for example, would use the
 111     boxed type if the argument include GstMiniObject derived types.
 112
 113     gst_mini_object_new() is removed. You would allocate memory with the the
 114     methods specific for the derived type.
 115
 116     GstParamSpecMiniObject is removed, use boxed param spec now with the GType
 117     of the specific GstMiniObject derived type. Also
 118     gst_param_spec_mini_object().
 119
 120     gst_param_spec_mini_object() -> g_param_spec_boxed()
 121
 122     The specific gst_value_*_mini_object() methods are removed, used the generic
 123     boxed methods instead.
 124
 125     gst_value_set_mini_object() -> g_value_set_boxed()
 126     gst_value_take_mini_object() -> g_value_take_boxed()
 127     gst_value_take_get_object() -> g_value_get_boxed()
 128     gst_value_take_dup_object() -> g_value_dup_boxed()
 129
 130     The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
 131     memory in buffers as READONLY. Marking memory READONLY can now be done
 132     with the GstMemory API. Writability of miniobjects is now only done by using
 133     the refcount.
 134
 135 * GstBuffer
 136     A GstBuffer is now a simple boxed type this means that subclassing is not
 137     possible anymore.
 138
 139     To add data to the buffer you would now use gst_buffer_take_memory() with
 140     a GstMemory object containing the data. Multiple memory blocks can added to
 141     a GstBuffer that can then be retrieved with gst_buffer_peek_memory().
 142
 143     GST_BUFFER_DATA(), GST_BUFFER_MALLOCDATA(), GST_BUFFER_FREE_FUNC() and
 144     GST_BUFFER_SIZE() are gone, along with the fields in GstBuffer. Use the
 145     memory API to get access to the buffer data. GST_BUFFER_SIZE() can be
 146     replaced with gst_buffer_get_size() but if also access to the data is
 147     required, gst_buffer_map() can return both the size and data in one go.
 148
 149     The most common way to access all the data in a buffer is by using
 150     gst_buffer_map() and gst_buffer_unmap(). These calls require you to specify
 151     the access mode required to the data and will automatically merge and return
 152     a writable copy of the data.
 153
 154     The buffer must be writable (gst_buffer_is_writable()) in order to modify
 155     the fields, metadata or buffer memory. gst_buffer_make_writable() will not
 156     automatically make a writable copy of the memory but will instead increase
 157     the refcount of the memory. The _map() and _peek_memory() methods will
 158     automatically create writable copies when needed.
 159
 160     gst_buffer_make_metadata_writable() is gone, you can replace this safely
 161     with gst_buffer_make_writable().
 162
 163     gst_buffer_create_sub() is gone and can be safely replaced with
 164     gst_buffer_copy_region().
 165
 166     Changing the size of the buffer data can be done with gst_buffer_resize(),
 167     which will also update the metadata fields correctly. gst_buffer_set_size()
 168     is #defined to a special case of gst_buffer_resize() with a 0 offset.
 169
 170     gst_buffer_try_new_and_alloc() is replaced with gst_buffer_new_and_alloc(),
 171     which now returns NULL when memory allocation fails.
 172
 173     GST_BUFFER_CAPS() is gone, caps are not set on buffers anymore but are set
 174     on the pads where the buffer is pushed on. Likewise GST_BUFFER_COPY_CAPS is
 175     not needed anymore. gst_buffer_get/set_caps() are gone too.
 176
 177 * GstBufferList
 178     The GstBufferList object is much simplified because most of the
 179     functionality in the groups is now part of the GstMemory in buffers.
 180
 181     The object is reduced to encapsulating an array of buffers that you can send
 182     with the regular gst_pad_push_list. The iterator is not needed anymore
 183     because you can simply use gst_buffer_list_len() and gst_buffer_list_get()
 184     to iterate the array.
 185
 186     For dealing with the groups, it's now needed to add the memory blocks to
 187     GstBuffer and use the normal buffer API to get and merge the groups.
 188
 189 * GstEvent
 190     GST_EVENT_SRC is removed. Don't use this anymore.
 191
 192     gst_event_new_new_segment_full() -> gst_event_new_new_segment()
 193     gst_event_parse_new_segment_full() -> gst_event_parse_new_segment()
 194
 195     gst_event_new_qos_full() -> gst_event_new_qos()
 196     gst_event_parse_qos_full() -> gst_event_parse_qos()
 197
 198     The GstStructure is removed from the public API, use the getters to get
 199     a handle to a GstStructure.
 200
 201 * GstQuery
 202     Boxed types derived from GstMiniObject.
 203
 204     The GstStructure is removed from the public API, use the getters to get
 205     a handle to a GstStructure.
 206
 207 * GstBufferList
 208     Is now a boxed type derived from GstMiniObject.
 209
 210 * GstMessage
 211     Is now a boxed type derived from GstMiniObject
 212
 213     The GstStructure is removed from the public API, use the getters to get
 214     a handle to a GstStructure.
 215
 216 * GstCaps
 217     Is now a boxed type derived from GstMiniObject.
 218
 219 * GstSegment
 220     abs_rate was removed from the public fields, it can be trivially calculated
 221     from the rate field.
 222
 223 * GstTypeFind
 224     gst_type_find_peek() returns a const guin8 * now.
 225
 226 * GstAdapter
 227     gst_adapter_peek() is removed, use gst_adapter_map() and gst_adapter_unmap()
 228     to get access to raw data from the adapter.
 229
 230     Arguments renamed from guint to gsize.
 231
 232 * GstBitReader, GstByteReader, GstByteWriter
 233     gst_*_reader_new_from_buffer(), gst_*_reader_init_from_buffer() removed, get
 234     access to the buffer data with _map() and then use the _new() functions.
 235
 236     gst_byte_reader_new_from_buffer() and gst_byte_reader_init_from_buffer()
 237     removed, get access to the buffer data and then use the _new() functions.
 238
 239 * GstCollectPads
 240     gst_collect_pads_read() removed, use _read_buffer() or _take_buffer() and
 241     then use the memory API to get to the memory.
 242
 243 * GstBaseSrc, GstBaseTransform, GstBaseSink
 244     GstBaseSrc::get_caps(), GstBaseTransform::transform_caps() and
 245     GstBaseSink::get_caps() now take a filter GstCaps* parameter to
 246     filter the caps and allow better negotiation decisions.
 247
 248