[gst-devel] Notes on the 0.9 API

[Torsten Schoenfeld]

Aloha,

here are some notes I made while porting the Perl bindings over to the
0.9 API.  Most of these points are no big issues and some are simple
questions of taste, but a few deserve some attention, I think.

* gst_element_link_pads_filtered and gst_element_link_filtered: Should
the filter caps be const?

* Why "GstBufferFlag" instead of "GstBufferFlags"?  It seems to be
convention to use the plural for GFlags.

* GstMiniObject is quite a pain for language bindings because some of
the functionality that's usually provided by the GObject wrappers has to
be duplicated (for example: memory and inheritance management, callback
handling).  I'm not complaining, though.  I understand that
GstMiniObject was consciously designed to be efficient, and that GObject
just isn't fast enough.  I just thought I'd mention it anyway.

* Why is GstMessageType a GFlags?  Can messages be of more than one
type?
* If messages can have more than one type, why do the _parse_ methods
check for equality (==) instead of "includedness" (&)?

* gstchildproxy.h doesn't get included by default.
* gst_child_proxy_[sg]et is badly named.  Since GstChildProxy is an
interface, these methods map to $thing->[sg]et in OO-ish language
bindings -- thus colliding with g_object_[sg]et.  Something like that is
okay if the interface provides the basic functionality of the object
implementing it.  Example: gtk_tree_model_get also maps to $thing->get,
but if you call the "get" method on a tree model, it's pretty likely
that you actually want gtk_tree_model_get instead of g_object_get.
Fetching data is more common than fetching object properties.  This
doesn't hold for gst_child_proxy_[sg]et though, IMO.  For the Perl
bindings, I renamed the methods to "[sg]et_child_property".

* Why GST_EVENT_CUSTOM_UP instead of GST_EVENT_CUSTOM_US?

* There's no destruction notification for the callback given to
gst_pad_start_task.  This is probably true for more callbacks too, but I
haven't looked into wrapping most of them yet.

* gst_parse_launch is a misnomer.  The name *kinda* makes sense if you
think of it as "parse the gst-launch syntax", but most people probably
interpret "launch" as a verb -- and two verbs in a method don't sound
well.  Actually, gst_parse_launch looks like a normal pipeline
constructor to me -- so why not name it gst_pipeline_new_from_string or
similar?

* gst_registry_* don't appear in the online API docs, but they do seem
to have gtk-doc comments.

* GstTagSetter's methods are not well named.  This is similar to the
GstChildIndex issue above.  Names like "merge" and "add" just don't say
enough of what they actually do.  I renamed them to "merge_tags",
"add_tags", etc.  I think this was discussed on IRC already, and I seem
to remember that people agreed that these methods should be renamed.

* gst_type_find_factory_get_caps: Why are the returned caps not const?

* What are GstObject, GstElement, GstPad and GstBuffer methods doing in
gstutils.h?  Why aren't they listed in the corresponding header?  I
think the subjective "utility" of a method should not determine where
it's listed.  If it has a gst_xxx_ prefix, it should be in gstxxx.h.

* Why is it "GST_TYPE_LIST" and not "GST_TYPE_VALUE_LIST"?

* There's no consistent word separation scheme.  Most of the API follows
what seems to be the standard: separate words by "_".  But sometimes
there's no separation at all, which looks pretty weird.

-- 
Bye,
-Torsten