[gst-devel] Notes on the 0.9 API

[Torsten Schoenfeld]

On Sun, 2005-11-20 at 23:04 +0100, Andy Wingo wrote:

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

Well, I hope I'm still on time.

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

Ah, ok.  That makes sense.  I can't think of a better solution for this,
and I don't think it's all that hackish, either.

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

I'm not sure.  Threads and perl (the interpreter, not the language)
don't really like each other, but sometimes the problems can be worked
around.

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

As long as there's a way to know when a callback is never going to be
called again, everything's fine.  Problems arise when a) there's no
destruction notification, b) the callback outlives the current function
call, and c) the involved object is no GObject (no qdata).  In every
other case I can think of, the issue is solvable.

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

Hrm.  I thought it always creates a GstPipeline.  Can't think of a
better name right now.

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

http://bugzilla.gnome.org/show_bug.cgi?id=322069

> > * 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 :)

Nah, it's not that important.  Just wanted to be sure you guys are aware
of it.

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

After further inspection, changing this really seems to be more trouble
than it's worth.  The original name is okay.

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

Here are the ones I spotted while going through the main headers
(gnome/include/gstreamer-0.9/gst/*.h):

gst_event_new_newsegment
gst_event_parse_newsegment
gst_event_new_buffersize
gst_event_parse_buffersize
gst_ghost_pad_new_notarget
gst_pad_set_bufferalloc_function
gst_pad_set_activatepull_function
gst_pad_set_activatepush_function
gst_pad_set_getrange_function
gst_pad_set_checkgetrange_function
gst_pad_set_getcaps_function
gst_pad_set_acceptcaps_function
gst_pad_set_fixatecaps_function
gst_pad_set_setcaps_function
gst_pad_proxy_getcaps
gst_pad_proxy_setcaps

All the nagging aside, I think you did a good job with the new API.
It's already a lot saner than in 0.8.

-- 
Bye,
-Torsten