caps: remove gst_caps_union()
[platform/upstream/gstreamer.git] / docs / random / porting-to-0.11.txt
index bfab504..0181bcd 100644 (file)
@@ -60,6 +60,10 @@ The 0.11 porting guide
 
     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.
 
@@ -68,8 +72,12 @@ The 0.11 porting guide
 
     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() does not return writable caps anymore and an explicit
+    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.
 
@@ -78,8 +86,8 @@ The 0.11 porting guide
 
     gst_pad_set_bufferalloc_function(), gst_pad_alloc_buffer() and
     gst_pad_alloc_buffer_and_set_caps() are removed. Use the ALLOCATION query
-    now to obtain a reference to a bufferpool object that can be used to
-    allocate buffers.
+    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.
@@ -104,7 +112,7 @@ The 0.11 porting guide
 
     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_PROBE_TYPE_BLOCK to get the same result as the async
+    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.
 
@@ -124,6 +132,27 @@ The 0.11 porting guide
 
     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.
+
+    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.
@@ -197,6 +226,9 @@ The 0.11 porting guide
     
     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(). 
@@ -212,25 +244,38 @@ The 0.11 porting guide
     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
+
 * 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_len() and gst_buffer_list_get()
+    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()
@@ -258,7 +303,7 @@ The 0.11 porting guide
     gst_query_parse_formats_length() -> gst_query_parse_n_formats()
     gst_query_parse_formats_nth() -> gst_query_parse_nth_format()
 
-    Some query utility functionsno longer use an inout parameter for the
+    Some query utility functions no longer use an inout parameter for the
     destination/query format:
 
       - gst_pad_query_position()
@@ -271,6 +316,9 @@ The 0.11 porting guide
       - 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.
 
@@ -281,7 +329,26 @@ The 0.11 porting guide
     a handle to a GstStructure.
 
 * GstCaps
-    Is now a boxed type derived from GstMiniObject. 
+    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
@@ -309,11 +376,17 @@ The 0.11 porting guide
 * 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 renamed from guint to gsize.
+    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
@@ -352,3 +425,84 @@ The 0.11 porting guide
     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 object instead of being typedefed to a GstStructure. Cast
+    to GstStructure or use gst_structure_* API on it at your own peril (it may
+    still work for now, but might be changed in future).
+
+    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*().
+
+* 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).