[gst-devel] Roundup 1. libraries

[Wim Taymans]

Since Erik is back, here is the first part of the roundup.

The libraries:

I noticed that some codecs needed the same functionality over
and over again. for example a getbits implementation is needed
for many MPEG audio and video decoders. Instead of including them
over and over again into the source directory, I made some general
libraries to handle the common cases. So far I have 6 libraries
that can be found in the libs directory:

getbits: 
--------
This is a general getbits implementation currently used
by the MPEG audio decoder mpg123, the MPEG video decoders: mpeg_play
and mpeg2play, the MPEG1 and MPEG2 system parser, the MPEG1 multiplexer
and the ac3decoder. I tried to convert all the plugins to the new
getbits library.

The getbits API is designed to allow an inline as well as a function 
based implementation. currently all plugins use the inline method as
this is currently the fastest method.

The API goes like this:


#define GST_GETBITS_INLINE

define this before including the header if you want an inlined getbits
implementation. (default behaviour for now). 

#include <libs/getbits/gstgetbits.h>

then you define:

gst_getbits_t gb;

gst_getbits_init(&gb); /* to initialize the  struct */
gst_getbits_newbuf(&gb, buffer, bufferlength); /* to set the source */

gst_getbitsN(&gb);        /* will return N bits from the stream */
gst_getbitsn(&gb, N);     /* the same but for variable number of bits */

also:

gst_showbitsN(&gb);      /* get N bits but do not advance the stream */
gst_showbitsn(&gb, N);

gst_flushbits32(&gb);     /* advance the stream by 32 bits */
gst_flushbits(&gb, N);   /* should be gst_flushbitsn(gb, N) */

gst_backbits24(&gb);     /* move back 24 bits */
gst_backbitsn(&gb, N);   /* back N bits */

gst_getbits_bufferpos(&gb);
gst_getbits_bytesleft(&gb);
gst_getbits_bitsleft(&gb);
gst_getbits_bitoffset(&gb);  /* various functions to query the buffer position
*/

The flushbits and backbits implementation only has a high speed implementation
for 24 and 32 bits because I only needed those ones.

defining GETBITS_DEBUG_ENABLED or GETBITS_OVERRUN_ENABLED can help debugging
plugin errors by outputting lots of info.

the very scary inlined implementation can be found in gstgetbits_inl.h :-).
Thank god we have if(){}else{} statements in regular code.

putbits
-------

No inlined implemenation yet but with an API very much like the getbits 
implementation. so:

#include <libs/putbits/gstputbits.h>
gst_putbits_t pb;

gst_putbits_init(&pb);

gst_putbits_new_buffer(&pb, buffer, len);
gst_putbits_new_empty_buffer(&pb, len); /* if you're too lazy to do the
                                           malloc yourself */

gst_putbitsn(&pb, value, bits); 
gst_putbitsN(&pb, value);

gst_putbits_align(&pb);
gst_putbits_bitcount(&pb); /* to query how many bits are handled */

currently used in the MPEG1/2 encoder and MPEG audio encoder.

riff
----

various functions to work with riff files. currently used in the avi
encoder/decoder. The wav parser is not yet updated.

API:

#include <libs/riff/gstriff.h>

riff parsing goes like this:

  GstRiff *gst_riff_parser_new(GstRiffCallback function, gpointer data);

you create a new GstRiff parser by suplying a callback function and some
user data.

next you suply the data to be parsed with:

  gst_riff_next_buffer(GstRiff *riff, GstBuffer *buffer, gulong off);

The riff parser will parse the data and will call the callback function
when a complete chunk has been decoded.

The callback function is defined like:

  typedef void (*GstRiffCallback) (GstRiffChunk *chunk, gpointer data);

so in your function you will be able to query the type of chunk that was
found and the data in that chunk. gstriff.h also has all the headers to
easily parse the chunk data. For an example, check the avi parser.

The callback mechanism proved to be extremely effective to parse this
braindead format. The avi parser is greatly simplified and does not need
to wory about the recursive nature of AVI files. I have however not tried
to do any seeking in AVI files as index parsing is not implemented and
involves a seek to the end of the AVI file.

riff encoding goes like:

  GstRiff *gst_riff_encoder_new(guint32 type);

with type: GST_RIFF_RIFF_WAVE of GST_RIFF_RIFF_AVI

next thing to do is to fill up the gst_riff_avih struct and call:

  gint gst_riff_encoder_avih(GstRiff *riff, gst_riff_avih *head, gulong size);

to fill the buffer. The library will take care of adding the right LIST tags
and calculating the total size etc...

You can also add strf and strh structs to the encoder.
The last thing you will have to do is add chunks to the encoder.

You can get the current buffer you created with:

  GstBuffer* gst_riff_encoder_get_buffer(GstRiff *riff);

or with

  GstBuffer* gst_riff_encoder_get_and_reset_buffer(GstRiff *riff);

to discard the currently allocated memory in the encoder.

Pretty weird stuff but quite effective. Look at the avi encoder.
Currently no index is kept or the headers are not very well updated.

videoscale
----------

Provides an easy method of scaling a video buffer. Currently three
interpollation methods are available. NEAREST, BILINEAR and BICUBIC
interpollation.

API:

  GstVideoScale *gst_videoscale_new(gint sw, gint sh, gint dw, gint dh, 
                            gint format, GstVideoScaleMethod)

to request a new videoscaler. This scaler will scale an image of format
<format> of sw x sh to sd x sh pixels using the given interpolation method.

then you call 

  scaler->scale(scaler, guchar *src, guchar *dest);

to scale the data in the source buffer into the destination buffer.

Currently only YUV can be scaled using BILINEAR or BICUBIC interpolation.
RGB canonly be scaled with no interpolation. 

The NEAREST scaling method is implemented in fast assembly.

call 

  gst_videoscale_destroy(scaler); 

to cleanup any allocated memory.

the scaler is currently used in the videosink and the videoscale plugin.

winloader
---------

provides the windows functions to open and access windows codecs.

The needed include files can be found in the include directory.

Currently used in the avi decoder to playback DivX ;-) avi files.

colorspace
----------

provides access to several color conversion routines. Has a similar
API to the video scaler.

The include file defines the colorspaces available in gstreamer.

Currently used in the videosink.

-- 
Liar, n.:
	A lawyer with a roving commission.
		-- Ambrose Bierce, "The Devil's Dictionary"