[gst-devel] Docs/RFC: GstData

[Benjamin Otte]

On Thu, 18 Apr 2002, David I. Lehn wrote:

> * Benjamin Otte <in7y118 at public.uni-hamburg.de> [20020416 20:11]:
> > Hierarchy
> > ---------
> > GstData
> >   GstInstream
> >     GstBuffer
> >     GstEventNewMedia
> ...
> >   GstOutOfStream
> >     GstEventLock
> ...
>
> Hmm.  GstInstream and GstOutOfStream seem rather awkward names.   I'll
> second the idea that they might not be needed.  What's the difference in
> the code between those two classes?  Is there any code in them at all?
> You could do something like the following:
>
> GstData
>   GstEvent
>     GstBuffer
>     GstEventEOS
>     GstEvent...
>     ... the rest ...
>
> and then just add a method to GstEvent:
>
>   gboolean gst_event_is_inline(GstEvent *);
>
> and let subclasses override it (or set a flag if we're lazy since these
> are not real objects anyway) to specify if they are inline (instream) or
> out of band (OutOfStream).  (or whatever naming would be)
>
When trying to find some events that are useful instream and outofstream,
I couldn't come up wth any. I would even like to seperate names between
those two, calling the out of stream stuff events and the instream stuff
status messages or something.
Just to give an example: If you want to request a new stream (out of
stream event), you would need to specify which stream you wanted and
probvably if you wanted to flush data before this.
An instream event just marks the beginning of a stream, nothing more.
As for the difference in code:
GstInstream has the offset property which is useless in out of stream
events. GstOutOfStream currently does nothing but might get a "priority"
field, for example.

> > GstData
> > =======
> >
> > typedef GstData * (*GstDataCopyFunction) (GstData *data);
> > typedef void (*GstDataFreeFunction) (GstData *data);
> >
> > struct _GstData
> > {
> >   /* inheritance */
> >   GstDataClass *	klass;
>
> Eh?  This doesn't really inherit from a class, it is an instance of a
> class.  Maybe use /* isa */.
>
Sounds good. Will fix.

> > struct _GstDataClass
> > {
> >   GstDataType		type;
> >
> >   GstDataCopyFunction	copy;
> >   GstDataFreeFunction	free;
> > };
> >
>
> What is GstDataType?  Is that going to be related to the GType system?
> It would be nice to also make sure all these pseudo-classes are
> registered as boxed types too.
>
It's not going to be related to GType. It's used to identify the struct
you use.
Tou have the possibility to use different class structs for the same data
type.
Ypou might for example have buffers Of GstDefaultBufferClass,
GstSubBufferClass, GstXVideoBufferClass and so on. These classes would all
be of type GST_TYPE_BUFFER.

Maybe the name "class" is a bit misleading. I used it for lack of a better
word...

> > If it can be a parent class, it should implement these three functions
> > publically:
> > void gst_my_data_init (GstData *data) {
> >   /* call the parent's init function, eg: */
> >   gst_data_init (data);
> >   /* initialize your data now */
> > }
>
> I think methods should use their own class with this sort of style:
>
> void gst_mt_data_init (GstMyData *data) {
>    gst_data_init (GST_DATA (data));
>    ...
> }
>
> similar in your other code.
>
>
> > If GstMyData should be instantiable, you should do this:
> > Get a class struct, something like this:
> > static GstDataClass my_data_class = { GST_TYPE_MY_DATA,
> >       gst_my_data_copy_func,
> >       gst_my_data_free_func };
> > FIXME: At the moment all types need to be specified in a big enum in
> > gstdata.h.
> >        We might want to change that when we support event plugins.
> > The two functions above should look something like this:
> > GstData *gst_my_data_copy_func (GstData *from) {
> >   /* allocate memory */
> >   GstMyData *copy = g_new (GstData, 1);
> >   /* copy relevant variables or initialize them */
> >   gst_my_data_copy (copy, from);
> >
> >   return copy;
> > }
>
> do you mean g_new (GstMyData, 1)?
>
Yes, typo.

> >   /* initialize the variables */
> >   gst_my_data_init (GST_DATA (my_data));
>
> again, I think methods can use their own types:
>   gst_my_data_init (GstMyData *data) {}
> so we can simplify call to:
>   gst_my_data_init (my_data);
>
> so then this casting makes more sense:
>
> >   /* set the right type */
> >   GST_DATA (my_data)->type = &my_data_class;
> >
> >   return my_data;
> > }
> ...
Right. Will fix.

> > MT safety
> > ---------
> > Manipulating data inside an object is not threadsafe unless otherwise
> > noted.
> > If an object has a reference count of 1 it is assumed that the reference
> > holder is the only user of that object and he may modify it the way he
> > likes.
> > If the reference count is greater than 1, the object may not be modified.
> > If you need to modify it, you have to copy the object and use that copy
> > instead.
> > NB: Object creation and refcounting are threadsafe - or must be
> > implemented that way.
> >
>
> Are there locks for this?  How do know if someone has called _ref() on
> your object between checking the refcount and accessing the object data?
>



> > GBoxed
> > ------
>
> yeah, do setup boxed types.  things like python bindings will need it to
> pass around thes structs anyway.  better to have it in core than
> repeated in other binding packages too.
>
Will do. It will probably just be one boxed type for GstData, because you
just need to call data->klass->free with any type.
I still fail to see what GBoxed is good for. Do you have some links
describing what this is used for?
Glib/Gtk+ use it just for GValues and I think we're fine with pointers
there.

> > GstInstream
> > ===========
> >
> > GstInstream is the base class for events and buffers that are passed
> > inside the stream.
> > It enhances the GstData struct by
> > guint64		offset[GST_OFFSET_TYPES];
> > This field describes the offset in the current stream in various different
> > ways:
> > GST_OFFSET_BYTES:  The number of bytes from the beginning of the stream.
> > GST_OFFSET_TIME:   The timestamp in microseconds. The beginning of the
> > stream equals timestamp 0. In buffers the timestamp should match the
> > beginning of the data.
> > GST_OFFSET_FRAMES: This type is specific to the stream and should be
> > defined there. (video will probably use it for frame numbers, audio to
> > count samples)
> > If an offset can't be specified, it is set to GST_OFFSET_INVALID, which
> > equals (guint64) -1. The byte offset always has to be specified. It is an
> > error if it is invalid.
> > A plugin playing data from an "infinite" source (eg a shoutcast stream
> > from the internet) it should start with byteoffset 0.
> >
>
> At first look this seems a bit complex and messy.  Maybe it's the best
> way though... I dunno.  Are those fields likely to be all filled for
> common cases?   Or, for instance, would a filesrc set the bytes, a
> demuxer set the time, and a decoder set the frame as data flows along a
> pipeline?
>
> What if an app need some other type of tag?  Like fields or some other
> block number or whatever.  Maybe plan for arbitrary tagged data by
> making these fields opaque and use accessor functions to get/set them.
>
> _INVALID seems more like an error condition than lack-of-value.  Perhaps
> _NONE or _UNKNOWN or _UNSET or something.
>
> I'm not sure about the guint64 array either.  I'll make another post
> to start time handling discussion.
>
>
> > GstEventNewMedia
> > ----------------
> > Signals the start of a new stream. This must be send before any buffer of
> > a new stream can be send.
>
> Why not call it GstEventNewStream?
> (I'd suggest BOS to match EOS but that would be confusing <g>)
>
I don't know the exact reason anymore, but it had something to do with
"you can get new media inside the same stream".

> > GstEventLength
> > --------------
> > Specifies the length of the stream.
> > FIXME: Write more, when sure how to do this.
> >
>
> How is this used?  My first thought is that apps should just query a
> size parameter in the source element.  Doesn't seem the sort of thing
> that need to travel in the stream.  But maybe there's a good use...
>
There actually is a good use: Have you ever tried to get the length of an
mp3 or avi by looking at the file size?

> I hope I didn't tear up your work too much. ;)
>
No, you did exactly what I was hoping somebody would do for two days now.
I call it "valuable feedback" :)