[gst-devel] Notes on the 0.9 API

[Andy Wingo]

Hi Torsten,

These are great comments. We're pushing the time for getting api changes
in, so a fast reply would be appreciated.

On Sun, 2005-11-20 at 22:24 +0100, Torsten Schoenfeld wrote:
> * gst_element_link_pads_filtered and gst_element_link_filtered: Should
> the filter caps be const?

Caps are refcounted like gstbuffer for example, they have a slightly
different memory management. See docs/design/part-MT-refcounting.txt.

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

You are right I think. Will fix tomorrow.

> * 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.

ACK. But it's better than what we used to have (crack events and
buffers) while not being huge.

> * Why is GstMessageType a GFlags?

So you can poll for GST_MESSAGE_EOS | GST_MESSAGE_ERROR for example, see
gst_bus_poll(). Also see ANY. This seems somehow hackish. Do you have
ideas on how to make this more consistent?

>   Can messages be of more than one
> type?

No.

> * 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".

You are right.

> * Why GST_EVENT_CUSTOM_UP instead of GST_EVENT_CUSTOM_US?

See http://bugzilla.gnome.org/show_bug.cgi?id=319392 -- I plan to redo
this tomorrow.

> * 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.

Can you really do this in perl? This will spawn an os-level thread to
call that function. That's pretty hardcore if you can do it.

Bindings-wise it's probably best to just set your callback as qdata on
the task object. That's the answer to this specific problem. Is there a
more general problem?

> * 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?

It is a confusing function yes. Um.... hm. Complication is that gstparse
is a module that can be configured out of the build. Also it doesn't
have to create a pipeline. Its function is to transform a
"pipeline" (which doesn't have to be a GstPipeline) from a string in
launch-syntax (that's a bad name i guess) to an element. Any other ideas
for the name? Will think about this too.

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

Will fix tomorrow.

> * 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.

File a specific bug (*soon*, and better with a patch) blocking #319388.

> * gst_type_find_factory_get_caps: Why are the returned caps not const?

same reason, you can ref them, and that changes the structure -> not
strictly 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.

The idea being those functions are non-orthogonal, a layer above. I
think everyone thinks it sucks. This will not change for 0.10 though,
except maybe for a comment in e.g. gstelement.h telling people also to
look at utils.h. If you want this in please send a patch :)

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

The value names are a bit confused, they all operate on gvalues anyway.
File a bug with more justification if you are interested in this,
otherwise it will probably slip by due to lack of resources.

> * 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.

We try hard to be consistent. Please let us know where we are not. Let
us know of functions with words that are together without "_".

Thanks for the comments,
-- 
Andy Wingo
http://wingolog.org/