-The 0.11 porting guide
-----------------------
+This guide has been renamed to porting-to-1.0.txt.
-* All deprecated methods were removed. Recompile against 0.10 with
- DISABLE_DEPRECATED and fix issues before attempting to port to 0.11.
+The latest version can be found at:
-* GST_BOILERPLATE is gone, use G_DEFINE_TYPE instead.
-
-* various methods take a gsize instead of a guint when talking about memory
- sizes.
-
-* multifdsink, tcpclientsink, tcpclientsrc, tcpserversrc the protocol property
- is removed, use gdppay and gdpdepay.
-
-* Presets and plugins moved to $XDG_DATA_HOME/gstreamer-0.11/ root
- directory. Registry moved to $XDG_CACHE_HOME/gstreamer-0.11/.
- XDG_CACHE_HOME usually points to $HOME/.cache and XDG_DATA_HOME
- usually is $HOME/.local/share/.
-
-* GstObject:
- GST_OBJECT_DISPOSING flag removed
- GST_OBJECT_IS_DISPOSING removed
- GST_OBJECT_FLOATING flag remove, GstObject is now GInitiallyUnowned
- GST_OBJECT_IS_FLOATING removed, use g_object_is_floating()
-
- GST_CLASS_GET_LOCK, GST_CLASS_LOCK, GST_CLASS_TRYLOCK, GST_CLASS_UNLOCK,
- used to be a workaround for thread-unsafe glib < 2.8
-
- gst_object_ref_sink() has gpointer as result to make it more like the
- GObject version.
-
- gst_object_sink() removed, use gst_object_ref_sink() instead.
-
- gst_class_signal_connect() removed, was only used for XML
-
- parent-set and parent-unset signals removed. Use notify:parent. Currently
- still disabled because of deep notify locking issues.
-
-* GstElement:
- GstElementDetails is removed and replaced with more generic metadata.
-
- gst_element_class_set_details_simple() -> gst_element_class_set_metadata()
- gst_element_class_set_documentation_uri -> gst_element_class_add_metadata
- gst_element_class_set_icon_name -> gst_element_class_add_metadata
- also gst_element_class_get_metadata()
-
- gst_element_factory_get_longname -> gst_element_factory_get_metadata
- gst_element_factory_get_klass -> gst_element_factory_get_metadata
- gst_element_factory_get_description -> gst_element_factory_get_metadata
- gst_element_factory_get_author -> gst_element_factory_get_metadata
- gst_element_factory_get_documentation_uri -> gst_element_factory_get_metadata
- gst_element_factory_get_icon_name -> gst_element_factory_get_metadata
-
- gstelementmetadata.h contains the keys for all standard metadata.
-
- gst_element_factory_can_{src,sink}_caps() => gst_element_factory_can_{src,sink}_{any,all}_caps()
-
- Element metadata and pad templates are inherited from parent classes and
- should be added in class_init instead of base_init.
-
- gst_element_class_add_pad_template() takes ownership of the template
-
- gst_element_class_add_static_pad_template (element_class, &src_template)
- => gst_element_class_add_pad_template (element_class,
- gst_static_pad_template_get (&src_template));
-
- Elements that change the duration must post DURATION messages on the
- bus when the duration changes in PAUSED or PLAYING.
-
- gst_element_lost_state_full() -> gst_element_lost_state()
- gst_element_lost_state() -> gst_element_lost_state(, TRUE)
-
- request_new_pad_full() -> request_new_pad()
-
- gst_element_found_tags() and gst_element_found_tags_for_pad() are gone, just
- push the tag event.
-
-* GstPad:
- gst_pad_get_caps() was replaced by gst_pad_query_caps(), it
- does not return writable caps anymore and an explicit
- gst_caps_make_writable() needs to be performed. This was the functionality
- of gst_pad_get_caps_reffed(), which is removed now.
-
- A similar change was done for gst_pad_peer_get_caps() and
- gst_pad_peer_get_caps_reffed()
-
- gst_pad_set_bufferalloc_function(), gst_pad_alloc_buffer() and
- gst_pad_alloc_buffer_and_set_caps() are removed. Use the ALLOCATION query
- now when negotiating formats to obtain a reference to a bufferpool object
- that can be used to allocate buffers using gst_buffer_pool_acquire_buffer().
-
- removed sched_private, it should not be used, use g_object_set_qdata() or
- use element_private.
-
- Removed GST_PAD_CAPS() use gst_pad_get_current_caps() to get a handle to the
- currently configured caps.
-
- gst_pad_get_pad_template_caps() and gst_pad_get_pad_template()
- return a new reference of the caps or template now and the return
- value needs to be unreffed after usage.
-
- gst_pad_set_caps() now pushes a CAPS event for backward compatibility.
- Consider sending the CAPS event yourself. It is not possible anymore to set
- NULL caps.
-
- gst_pad_set_checkgetrange_function() and gst_pad_check_pull_range() are
- gone, use the SCHEDULING query now.
-
- gst_pad_set_blocked(), gst_pad_set_blocked_async(),
- gst_pad_set_blocked_async_full() are removed, use the gst_pad_add_probe()
- method with the GST_PAD_PROBE_TYPE_BLOCK to get the same result as the async
- blocking version. There is no more sync version of blocking, this is in
- general dangerous and can be implemented using the callbacks if needed.
-
- gst_pad_add_data_probe(), gst_pad_add_data_probe_full(),
- gst_pad_remove_data_probe(), gst_pad_add_event_probe(),
- gst_pad_add_event_probe_full(), gst_pad_remove_event_probe(),
- gst_pad_add_buffer_probe(), gst_pad_add_buffer_probe_full(),
- gst_pad_remove_buffer_probe() are removed. Use gst_pad_add_probe() and
- gst_pad_remove_probe() for equivalent functionality.
-
- The have-data signal was removed from pads, it was never supposed to be used
- without calling the _add_.*_probe() methods.
-
- The request-link signal was removed. It was never used.
-
- gst_pad_get_negotiated_caps() -> get_pad_get_current_caps()
-
- GST_FLOW_UNEXPECTED -> GST_FLOW_EOS
-
- GstActivateMode -> GstPadMode, GST_ACTIVATE_* -> GST_PAD_MODE_*
-
- The GstPadAcceptCapsFunction was removed and replaced with a
- GST_QUERY_ACCEPT_CAPS query.
-
- The GstPadFixateCapsFunction was removed. It has no replacement, you can
- simply do the fixation in the element or use a vmethod from the base class
- if appropriate.
-
- The GstPadGetCapsFunction was removed and replaced with a GST_QUERY_CAPS
- query. The query takes a GstCaps* parameter to inform the other side about
- the possible caps and preferences.
-
- gst_pad_proxy_getcaps() -> gst_pad_proxy_query_caps()
- gst_pad_get_caps() -> gst_pad_query_caps()
- gst_pad_peer_get_caps() -> gst_pad_peer_query_caps()
- gst_pad_accept_caps() -> gst_pad_query_accept_caps()
- gst_pad_peer_accept_caps() -> gst_pad_peer_query_accept_caps()
- gst_pad_query_peer_*() -> gst_pad_peer_query_*()
-
- GstPadFlags: GST_PAD_* -> GST_PAD_FLAG_*
-
-* GstPadTemplate
- gst_pad_template_get_caps() returns a new reference of the caps
- and the return value needs to be unreffed after usage.
-
- gst_pad_template_new() does not take ownership of the caps anymore.
-
- GstPadTemplate is now created with a floating ref and
- gst_element_class_add_pad_template() takes ownership of this floating ref.
-
- GstPadTemplate instances are considered immutable and must not be
- changed.
-
-* GstMiniObject
- A miniobject is now a simple refcounted structure holding the information
- common to buffers, events, messages, queries and caps.
-
- There is no more GST_TYPE_MINIOBJECT as the type for subclasses.
- G_TYPE_BOXED can be used as the type of all GstMiniObject based types such
- as buffers, events, messages, caps, etc. Signals, for example, would use the
- boxed type if the argument include GstMiniObject derived types.
-
- gst_mini_object_new() is removed. You would allocate memory with the the
- methods specific for the derived type.
-
- GstParamSpecMiniObject is removed, use boxed param spec now with the GType
- of the specific GstMiniObject derived type. Also
- gst_param_spec_mini_object().
-
- gst_param_spec_mini_object() -> g_param_spec_boxed()
-
- The specific gst_value_*_mini_object() methods are removed, used the generic
- boxed methods instead.
-
- gst_value_set_mini_object() -> g_value_set_boxed()
- gst_value_take_mini_object() -> g_value_take_boxed()
- gst_value_take_get_object() -> g_value_get_boxed()
- gst_value_take_dup_object() -> g_value_dup_boxed()
-
- GST_VALUE_HOLDS_MINI_OBJECT() was removed, use G_VALUE_HOLDS_BOXED() or
- type-specific GST_VALUE_HOLDS_{BUFFER,CAPS,etc.}() instead.
-
- The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
- memory in buffers as READONLY. Marking memory READONLY can now be done
- with the GstMemory API. Writability of miniobjects is now only done by using
- the refcount.
-
-* GstBuffer
- A GstBuffer is now a simple boxed type this means that subclassing is not
- possible anymore.
-
- To add data to the buffer you would now use gst_buffer_insert_memory() with
- a GstMemory object containing the data. Multiple memory blocks can added to
- a GstBuffer that can then be retrieved with gst_buffer_peek_memory().
-
- GST_BUFFER_DATA(), GST_BUFFER_MALLOCDATA(), GST_BUFFER_FREE_FUNC() and
- GST_BUFFER_SIZE() are gone, along with the fields in GstBuffer. Use the
- memory API to get access to the buffer data. GST_BUFFER_SIZE() can be
- replaced with gst_buffer_get_size() but if also access to the data is
- required, gst_buffer_map() can return both the size and data in one go.
-
- The most common way to access all the data in a buffer is by using
- gst_buffer_map() and gst_buffer_unmap(). These calls require you to specify
- the access mode required to the data and will automatically merge and return
- a writable copy of the data.
-
- The buffer must be writable (gst_buffer_is_writable()) in order to modify
- the fields, metadata or buffer memory. gst_buffer_make_writable() will not
- automatically make a writable copy of the memory but will instead increase
- the refcount of the memory. The _map() and _peek_memory() methods will
- automatically create writable copies when needed.
-
- gst_buffer_make_metadata_writable() is gone, you can replace this safely
- with gst_buffer_make_writable().
-
- gst_buffer_copy_metadata() is gone, use gst_buffer_copy_into() instead and
- mind use GST_BUFFER_COPY_METADATA instead of the former GST_BUFFER_COPY_ALL.
-
- gst_buffer_create_sub() is gone and can be safely replaced with
- gst_buffer_copy_region().
-
- Changing the size of the buffer data can be done with gst_buffer_resize(),
- which will also update the metadata fields correctly. gst_buffer_set_size()
- is #defined to a special case of gst_buffer_resize() with a 0 offset.
-
- gst_buffer_try_new_and_alloc() is replaced with gst_buffer_new_and_alloc(),
- which now returns NULL when memory allocation fails.
-
- GST_BUFFER_CAPS() is gone, caps are not set on buffers anymore but are set
- on the pads where the buffer is pushed on. Likewise GST_BUFFER_COPY_CAPS is
- not needed anymore. gst_buffer_get/set_caps() are gone too.
-
- GST_BUFFER_TIMESTAMP is gone, use GST_BUFFER_PTS or GST_BUFFER_DTS instead.
- Likewise GST_BUFFER_TIMESTAMP_IS_VALID() was changed to
- GST_BUFFER_PTS_IS_VALID and GST_BUFFER_DTS_IS_VALID
-
- gst_buffer_join() was renamed to gst_buffer_append() and the memory is not
- directly merged but appended.
-
- gst_buffer_merge() was removed, it is the same as gst_buffer_join() but
- without taking ownership of the arguments. Caller code should ref themselves
- when needed. Note that the extra refs might force slower paths in
- gst_buffer_join().
-
- gst_buffer_is_span() and gst_buffer_span() are removed, use
- gst_buffer_merge() and gst_buffer_resize() for the same effect. Merging and
- spanning is delayed until the buffer is mapped and in some cases no merging
- of memory is needed at all when the element can deal with individual memory
- chunks.
-
-* GstBufferList
- The GstBufferList object is much simplified because most of the
- functionality in the groups is now part of the GstMemory in buffers.
-
- The object is reduced to encapsulating an array of buffers that you can send
- with the regular gst_pad_push_list. The iterator is not needed anymore
- because you can simply use gst_buffer_list_length() and gst_buffer_list_get()
- to iterate the array.
-
- For dealing with the groups, it's now needed to add the memory blocks to
- GstBuffer and use the normal buffer API to get and merge the groups.
-
- gst_buffer_list_sized_new() -> gst_buffer_list_new_sized()
- gst_buffer_list_len() -> gst_buffer_list_length()
-
-* GstStructure
-
- The GArray of the structure fields are moved to private part and are not
- accessible from the application anymore. Use the methods to retrieve and
- modify fields from the array.
-
- gst_structure_empty_new() -> gst_structure_new_empty()
- gst_structure_id_empty_new() -> gst_structure_new_id_empty()
- gst_structure_id_new() -> gst_structure_new_id()
-
-* GstEvent
- Boxed types derived from GstMiniObject.
-
- GST_EVENT_SRC is removed. Don't use this anymore.
-
- gst_event_new_qos_full() -> gst_event_new_qos()
- gst_event_parse_qos_full() -> gst_event_parse_qos()
-
- The GstStructure is removed from the public API, use the getters to get
- a handle to a GstStructure.
-
- GST_EVENT_NEWSEGMENT -> GST_EVENT_SEGMENT
-
- gst_event_new_new_segment () -> gst_event_new_segment() and it takes a
- GstSegment structure as an argument.
- gst_event_parse_new_segment() -> gst_event_parse_segment() to retrieve the
- GstSegment structure from the event.
- gst_event_copy_segment() to fill a GstSegment structure.
-
-* GstQuery
- Boxed types derived from GstMiniObject.
-
- The GstStructure is removed from the public API, use the getters to get
- a handle to a GstStructure.
-
- gst_query_new_application() -> gst_query_new_custom()
-
- gst_query_parse_formats_length() -> gst_query_parse_n_formats()
- gst_query_parse_formats_nth() -> gst_query_parse_nth_format()
-
- Some query utility functions no longer use an inout parameter for the
- destination/query format:
-
- - gst_pad_query_position()
- - gst_pad_query_duration()
- - gst_pad_query_convert()
- - gst_pad_query_peer_position()
- - gst_pad_query_peer_duration()
- - gst_pad_query_peer_convert()
- - gst_element_query_position()
- - gst_element_query_duration()
- - gst_element_query_convert()
-
- gst_element_get_query_types() and gst_pad_get_query_types() with associated
- functions were removed.
-
-* GstBufferList
- Is now a boxed type derived from GstMiniObject.
-
-* GstMessage
- Is now a boxed type derived from GstMiniObject
-
- The GstStructure is removed from the public API, use the getters to get
- a handle to a GstStructure.
-
-* GstCaps
- Is now a boxed type derived from GstMiniObject.
-
- GST_VIDEO_CAPS_xxx -> GST_VIDEO_CAPS_MAKE(xxx)
-
- Some caps functions now take ownership of the input argument, for
- efficiency reasons (to avoid unnecessary copies to make them writable):
-
- gst_caps_normalize (caps) => caps = gst_caps_normalize (caps)
- gst_caps_do_simplify (caps) => caps = gst_caps_simplify (caps)
- gst_caps_merge (caps,caps2) => caps = gst_caps_merge (caps,caps2)
- gst_caps_merge_structure (caps,st) => caps = gst_caps_merge_structure (caps,st)
- gst_caps_truncate (caps) => caps = gst_caps_truncate (caps)
-
- The compiler should warn about unused return values from these functions,
- which may help find the places that need to be updated.
-
- Removed functions:
-
- gst_caps_union() -> gst_caps_merge(): Be careful because _merge takes
- ownership of the arguments.
-
-* GstSegment
- abs_rate was removed from the public fields, it can be trivially calculated
- from the rate field.
-
- accum was renamed to base. last_stop was renamed to position.
-
- The segment info now contains all the information needed to convert buffer
- timestamps to running_time and stream_time. There is no more segment
- accumulation, the GstSegment is completely self contained.
-
- gst_segment_set_duration() and gst_segment_set_last_stop() are removed,
- simply modify the structure members duration and position respectively.
-
- gst_segment_set_newsegment() is removed, it was used to accumulate segments
- and is not needed anymore, use gst_segment_copy_into() or modify the segment
- values directly.
-
- gst_segment_set_seek() -> gst_segment_do_seek(). Updates the segment values
- with seek parameters.
-
-* GstPluginFeature
- GST_PLUGIN_FEATURE_NAME() was removed, use GST_OBJECT_NAME() instead.
-
-* GstTypeFind
- gst_type_find_peek() returns a const guint8 * now.
-
-* GstTask
- gst_task_create() -> gst_task_new()
-
-* GstAdapter
- gst_adapter_peek() is removed, use gst_adapter_map() and gst_adapter_unmap()
- to get access to raw data from the adapter.
-
- Arguments changed from guint to gsize.
-
- gst_adapter_prev_timestamp() is removed and should be replaced with
- gst_adapter_prev_pts() and gst_adapter_prev_dts().
-
-* GstBitReader, GstByteReader, GstByteWriter
- gst_*_reader_new_from_buffer(), gst_*_reader_init_from_buffer() removed, get
- access to the buffer data with _map() and then use the _new() functions.
-
- gst_byte_reader_new_from_buffer() and gst_byte_reader_init_from_buffer()
- removed, get access to the buffer data and then use the _new() functions.
-
-* GstCollectPads
- gst_collect_pads_read() removed, use _read_buffer() or _take_buffer() and
- then use the memory API to get to the memory.
-
-* GstBaseSrc, GstBaseTransform, GstBaseSink
- GstBaseSrc::get_caps(), GstBaseTransform::transform_caps() and
- GstBaseSink::get_caps() now take a filter GstCaps* parameter to
- filter the caps and allow better negotiation decisions.
-
-* GstBaseTransform
- GstBaseTransform::transform_caps() now gets the complete caps passed
- instead of getting it passed structure by structure.
-
- GstBaseTransform::event() was renamed to sink_event(). The old function
- uses the return value to determine if the event should be forwarded or not.
- The new function has a default implementation that always forwards the event
- and the return value is simply returned as a result from the event handler.
- The semantics of the sink_event are thus the same as those for the src_event
- function.
-
-* GstImplementsInterface
- has been removed. Interfaces need to be updated to either have
- is_ready/usable/available() methods, or have GError arguments
- to their methods so we can return an appropriate error if a
- particular interface isn't supported for a particular device.
-
-* GstIterator
- uses a GValue based API now that is similar to the 0.10 API but
- allows bindings to properly use GstIterator and prevents complex
- return value ownership issues.
-
-* GstURIHandler
- gst_uri_handler_get_uri() and the get_uri vfunc now return a copy of
- the URI string
-
- gst_uri_handler_set_uri() and the set_uri vfunc now take an additional
- GError argument so the handler can notify the caller why it didn't
- accept a particular URI.
-
- gst_uri_handler_set_uri() now checks if the protocol of the URI passed
- is one of the protocols advertised by the uri handler, so set_uri vfunc
- implementations no longer need to check that as well.
-
-* GstTagList
- is now an opaque mini object instead of being typedefed to a GstStructure.
-
- While it was previously okay (and in some cases required because of
- missing taglist API) to cast a GstTagList to a GstStructure or use
- gst_structure_* API on taglists, you can no longer do that. Doing so will
- cause crashes.
-
- Also, tag lists are refcounted now, and can therefore not be freely
- modified any longer. Make sure to call
-
- taglist = gst_tag_list_make_writable (taglist);
-
- before adding, removing or changing tags in the taglist.
-
- gst_tag_list_new() has been renamed to gst_tag_list_new_empty().
- gst_tag_list_new_full*() have been renamed to gst_tag_list_new*().
- gst_tag_list_free() has been replaced by gst_tag_list_unref().
-
-* GstController:
- has now been merged into GstObject. It does not exists as a individual
- object anymore. In addition core contains a GstControlSource base class and
- the GstControlBinding. The actual control sources are in the controller
- library as before. The 2nd big change is that control sources generate
- a sequence of gdouble values and those are mapped to the property type and
- value range by GstControlBindings.
-
- For plugins the effect is that gst_controller_init() is gone and
- gst_object_sync_values() is taking a GstObject * instead of GObject *.
-
- For applications the effect is larger. The whole gst_controller_* API is
- gone and now available in simplified form under gst_object_*. ControlSources
- are now attached via GstControlBinding to properties. There are no GValue
- arguments used anymore when programming control sources.
-
- gst_controller_new* -> gst_object_set_control_source
- gst_controller_add_properties -> gst_object_set_control_source
- gst_controller_set_control_source -> gst_object_set_control_source
- gst_controller_get_control_source -> gst_object_get_control_source
-
- gst_controller_set_property_disabled -> gst_object_set_controlled_property_disabled
-
- gst_object_get_value_arrays has been removed. Loop over the controlled
- properties fetch the value array. Also GstValueArray is gone. The fields of
- GstValueArray are now passed directly to gst_object_get_value_array as
- arguments.
-
- GstInterpolationControlSource has been split. There is a new
- GstTimedValueControlSource baseclass and 2 sub classes:
- GstInterpolationControlSource and GstTriggerControlSource. The API for setting
- and getting the timestamps is in GstTimedValueControlSource.
-
- gst_interpolation_control_source_set_interpolation_mode() has been removed.
- Set the "mode" gobject property on the control-source instead. The possible
- enum values have been renamed from GST_INTERPOLATE_XXX to
- GST_INTERPOLATION_MODE_XXX.
-
-* GstRegistry
-
- gst_registry_get_default() -> gst_registry_get()
- gst_default_registry_*(...) -> gst_registry_*(gst_registry_get(), ...)
-
-* GstValue
-
- GST_TYPE_DATE -> G_TYPE_DATE
- GST_VALUE_HOLDS_DATE(value) -> G_VALUE_HOLDS(value,G_TYPE_DATE)
- gst_value_set_date() -> g_value_set_boxed()
- gst_value_get_date() -> g_value_get_boxed()
-
-* GError/GstGError
-
- GstGError -> GError
- GST_TYPE_G_ERROR / gst_g_error_get_type() -> G_TYPE_ERROR
-
-* "codec-data" and "streamheader" field in GstCaps
-
- codec-data and stream headers are no longer in GstCaps, but sent as
- part of a STREAM CONFIG event (which should be sent after the initial
- CAPS event if needed).
+http://cgit.freedesktop.org/gstreamer/gstreamer/tree/docs/random/porting-to-1.0.txt