gstreamer/HACKING

268 lines
11 KiB
Text
Raw Normal View History

THE GOAL
--------
What we are trying to achieve:
satisfy:
patching of CVS checkout using our patch files placed in our CVS
passing of
make
make distcheck
non-srcdir build (ie, mkdir build; cd build; ../configure; make)
THE SETUP
---------
There is a "mirror" root CVS module that contains "ffmpeg".
This directory contains a vendor-branch checkout of upstream FFmpeg CVS
of a given day.
On head, the following things have been commited on top of this:
* patches/, which is a directory with a set of patches, and a series file
listing the order, as generated by quilt
* .pc/, which is a tree of files that quilt uses to keep control of its state.
It contains a list of applied patches, and one directory per patch,
containing a tree of hardlinked files that were added to the patchset, and
a .pc file listing all files part of the patchset.
* the result of having all these patches commited (ie, quilt push -a) to the
ffmpeg tree.
Both the actually patched CVS ffmpeg code as well as the .pc dir need to be
commited to CVS so the state of quilt wrt. the source is in sync.
THE WARNING
-----------
***
NEVER EVER commit stuff in gst-libs/ext/ffmpeg UNLESS your quilt stack is
completely applied !
This means, ALWAYS make sure quilt push -a has been run without problems.
What's more, if you want to be on the safe side, make sure that you can
unapply and reapply without problems, by running quilt pop -a then
quilt push -a.
The ONLY exception to this is when you're working on a branch to update
the upstream source you're working with.
***
THE WAY
-------
- If you want to hack on our copy of the FFmpeg code, there are some basic
rules you need to respect:
- you need to use quilt. If you don't use quilt, you can't hack on it.
- we separate patches based on the functionality they patch, and whether
or not we want to send stuff upstream. Make sure you work in the right
patch. use "quilt applied" to check which patches are applied.
- before starting to hack, run cvs diff. There should be NO diffs, and
NO files listed with question mark. If there are, somebody before you
probably made a mistake. To manage the state correctly, it is vital that
none of the files are unknown to CVS.
- if you want to add a file to a patchset, you need to:
- be in the right patchset
- quilt add (file)
- cvs add .pc/(patchsetname)/(file)
- cvs commit .pc/(patchsetname) (to update the state of quilt in cvs)
- edit the file
- cvs add the file if it doesn't exist yet
- quilt refresh
- quilt push -a (This one is IMPORTANT, otherwise you'll have a huge diff)
- cvs commit
- if you want to add a patchset, you need to:
- go over the procedure with thomas to check it's correct
- decide where in the stack to put it. ask for help if you don't know.
- go there in the patch stack (use quilt pop/push)
- quilt new (patchsetname).patch (don't forget .patch !)
- quilt add (files)
- cvs add .pc/(patchsetname) the whole tree
- cvs commit .pc/(patchsetname)
- quilt refresh
- quilt push -a
- cvs commit
- cvs diff (to check if any of the files are unknown to CVS; if they are,
you need to add them to CVS)
THE UPSTREAM
------------
At some points you want to update the upstream snapshot code to a newer date.
This is easy if you follow the steps outlined here, but make sure to follow
them correctly !
- find a good CVS snapshot date for upstream, one that is known to work.
You're going to save yourself quite a bit of trouble if you verify this
first !
- check it out to a local directory:
cvs -z9 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg export -D '2004-04-11 23:00 GMT' ffmpeg
- compile it and test it, make sure it works
- in gst-ffmpeg/gst-libs/ext/ffmpeg:
- Pre-flight checks:
- first make sure you don't have local changes, all files are either in
CVS or in .cvsignore patch, the whole quilt stack is applied, and stuff
works.
- do a quilt pop -a and quilt push -a to verify everything is ok.
- Branch and rollback:
- tag HEAD with the branch root point:
cvs tag BRANCH-UPDATE-CVS-2004-04-11-23-00-ROOT
- branch:
cvs tag -b BRANCH-UPDATE-CVS-2004-04-11-23-00
- FIXME: lock cvs HEAD
- update local copy to branch:
cvs update -r BRANCH-UPDATE-CVS-2004-04-11-23-00
- peel off all patches:
quilt pop -a
- commit this
cvs commit
- check
cvs diff
you should only have ? for files that are generated somehow (binaries,
build files, ...)
you get warnings about cvs not finding files to diff that are in .pc
or generated by your patches
- if you want, you can now compare this state of CVS (which should
be last upstream CVS combined with your local unapplied quilt state)
- remember to NOT do cvs update from here on, since you popped your quilt
state all your added files that are also in CVS are not locally present.
- sync with upstream:
- in a temp dir, redo the export:
cd ..
mkdir tmp
cd tmp
cvs -z9 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg export -D '2004-04-11 23:00 GMT' ffmpeg
- rsync it over the old ffmpeg tree
rsync -arv ffmpeg ..
- go back and commit this new snapshot
cd ../ffmpeg
cvs commit
- check if any new files got added that you should add to cvs
cvs diff
This will list a lot of local files missing, from your quilt state,
which you shouldn't worry about. Just inspect all the ?'s and add
files to cvs that belong to upstream and should be in cvs.
- if everything's ok and commited, tag the state:
cvs tag UPSTREAM-CVS-2004-04-11-23-00
- reapply and fix quilt patches one by one
- try applying one
quilt push
- if that didn't work, inspect the patch and figure out how to fix it:
- if the patch got applied upstream completely, quilt push will tell
you the patch looks like a reverse patch. In that case you can
remove the patch from your patches file (patches/series), and
remove the .pc/$(patchname) and patches/$(patchname).patch files from
cvs.
- if the patch conflicts somehow, you can force application with
quilt push -f
and then resolve all the rejects, and fix the patch completely.
Then refresh quilt state with
quilt refresh
- when the patch is succesfully removed or reworked, commit current state
to CVS, then check again if nothing is missing using cvs diff, and
resolve problems/apply missing files from your quilt state/...
- after reapplying your complete quilt state, test locally if the complete
gst-ffmpeg module now works. Compile and test. Resolve all problems
(upstream errors, missing symbols, missing files, ...) until you have
a working module. commit again.
- merge to head:
- update locally back to head
cvs update -A
- FIXME: unlock cvs HEAD
- merge from your branch
cvs update -j BRANCH-UPDATE-CVS-2004-04-11-23-00
- commit
cvs commit
- check for diffs
cvs diff
- tag merge point
cvs tag BRANCH-UPDATE-CVS-2004-04-11-23-00-MERGE
- add upstream date to "THE RECORDS" below
- get a drink
THE PLUGIN
----------
HACKING: Add some basic documentation on how our wrapping works. Original commit message from CVS: * HACKING: Add some basic documentation on how our wrapping works. * TODO: Add a list of things that could be worked on or that need doing. * configure.ac: Update snapshot. * ext/ffmpeg/Makefile.am: Changne .la links. See below (autotools patch). * ext/ffmpeg/gstffmpeg.c: (plugin_init): Enable demuxers. See below (gstffmpegdemux.c). * ext/ffmpeg/gstffmpegcodecmap.c: (gst_ffmpeg_formatid_to_caps): Realmedia caused a crash - fix that. * ext/ffmpeg/gstffmpegdemux.c: (gst_ffmpegdemux_averror), (gst_ffmpegdemux_base_init), (gst_ffmpegdemux_init), (gst_ffmpegdemux_close), (gst_ffmpegdemux_dispose), (gst_ffmpegdemux_stream_from_pad), (gst_ffmpegdemux_src_event_mask), (gst_ffmpegdemux_src_event), (gst_ffmpegdemux_src_format_list), (gst_ffmpegdemux_src_query_list), (gst_ffmpegdemux_src_query), (gst_ffmpegdemux_src_convert), (gst_ffmpegdemux_add), (gst_ffmpegdemux_open), (gst_ffmpegdemux_loop), (gst_ffmpegdemux_change_state), (gst_ffmpegdemux_register): Right. OK, so I fixed up the demuxing and have it basically-working, and the best way to get some more people to test it is to actually enable it. I'm not sure if we want this for 0.8.0, but we can at least give it a try. I've tested avi, matroska and mpeg, all appear to work. The cool thing is that this gives us instant support for several exotic formats that we'd never care about ourselves. Again, this needs more testing for it to still be enabled in 0.8.0, but I want to give it a try... * ext/ffmpeg/gstffmpegmux.c: (gst_ffmpegmux_base_init), (gst_ffmpegmux_init), (gst_ffmpegmux_request_new_pad), (gst_ffmpegmux_connect), (gst_ffmpegmux_loop), (gst_ffmpegmux_register): Add some fixups that I use locally. Make it work in the case of MPEG encoding, but the muxer is still not in shape to be enabled. * ext/ffmpeg/gstffmpegprotocol.c: (gst_ffmpegdata_open), (gst_ffmpegdata_read), (gst_ffmpegdata_write), (gst_ffmpegdata_seek), (gst_ffmpegdata_close): Some small fixups that crept into it while it was disabled for the last few years. Basically works. * gst-libs/ext/ffmpeg/Makefile.am: Instead of having our local-autotoolized version, I patch the ffmpeg source to be fully autotoolized. That means a simple SUBDIRS here is now enough. * gst-libs/ext/ffmpeg/Tag: Version update. * gst-libs/ext/ffmpeg/patch/autotools.diff: Autotoolize ffmpeg. Needs to be sent to ffmpeg-devel@... * gst-libs/ext/ffmpeg/patch/disableinstalllibs.diff: Don't install their libs. * gst-libs/ext/ffmpeg/patch/disablemmx.diff: Don't use MMX. It cannot ocmpile using PIC. * gst-libs/ext/ffmpeg/patch/disabletools.diff: Don't compile/install their tools, we don't use them. * gst-libs/ext/ffmpeg/patch/functions.diff: Prevent symbol conflicts. * gst-libs/ext/ffmpeg/patch/matroska.diff: Add a matroska demuxer. Needs to be sent to ffmpeg-devel@...
2004-03-01 04:59:17 +00:00
Some notes on how ffmpeg wrapping inside GStreamer currently works:
* gstffmpeg{dec,enc,demux,mux}.c are wrappers for specific element types from
their ffmpeg counterpart. If you want to wrap a new type of element in
wrapper file.
* gstffmpegcolorspace.c is a wrapper for one specific function in ffmpeg:
colorspace conversion. This works different from the previously mentioned
ones, and we'll come to that in the next item. If you want to wrap one
specific function, then that, too, belongs in a new wrapper file.
* the important difference between all those is that the colorspace element
contains one element, so there is a 1<->1 mapping. This makes for a fairly
basic element implementation. gstffmpegcolorspace.c, therefore, doesn't
differ much from other colorspace elements. The ffmpeg element types,
however, define a whole *list* of elements (in GStreamer, each decoder etc.
needs to be its own element). We use a set of tricks for that to keep
coding simple: codec mapping and dynamic type creation.
* ffmpeg uses CODEC_ID_* enumerations for their codecs. GStreamer uses caps,
which consists of a mimetype and a defined set of properties. In ffmpeg,
these properties live in a AVCodecContext struct, which contains anything
that could configure any codec (which makes it rather messy, but ohwell).
To convert from one to the other, we use codec mapping, which is done in
gstffmpegcodecmap.[ch]. This is the most important file in the whole
ffmpeg wrapping process! It contains functions to go from a codec type
(video or audio - used as the output format for decoding or the input
format for encoding), a codec id (to identify each format) or a format id
(a string identifying a file format - usually the file format extension)
to a GstCaps, and the other way around.
* to define multiple elements in one source file (which all behave similarly),
we dynamically create types for each plugin and let all of them operate on
the same struct (GstFFMpegDec, GstFFMpegEnc, ...). The functions in
gstffmpeg{dec,enc,demux,mux}.c called gst_ffmpeg*_register() do this.
The magic is as follows: for each codec or format, ffmpeg has a single
AVCodec or AV{Input,Output}Format, which are packed together in a list of
supported codecs/formats. We simply walk through the list, for each of
those, we check whether gstffmpegcodecmap.c knows about this single one.
If it does, we get the GstCaps for each pad template that belongs to it,
and register a type for all of those together. We also leave this inside
a caching struct, that will later be used by the base_init() function to
fill in information about this specific codec in the class struct of this
element (pad templates and codec/format information). Since the actual
codec information is the only thing that really makes each codec/format
different (they all behave the same through the ffmpeg API), we don't
really need to do anything else that is codec-specific, so all other
functions are rather simple.
* one particular thing that needs mention is how gstffmpeg{mux,demux}.c and
gstffmpegprotocol.c interoperate. ffmpeg uses URLProtocols for data input
and output. Now, of course, we want to use the *GStreamer* way of doing
input and output (filesrc, ...) rather than the ffmpeg way. Therefore, we
wrap up a GstPad as a URLProtocol and register this with ffmpeg. This is
what gstffmpegprotocol.c does. The URL is called gstreamer://%p, where %p
is the address of a GstPad. gstffmpeg{mux,demux}.c then open a file called
gstreamer://%p, with %p being their source/sink pad, respectively. This
way, we use GStreamer for data input/output through the ffmpeg API. It's
rather ugly, but it has worked quite well so far.
* there's lots of things that still need doing. See the TODO file for more
information.
THE RECORDS
-----------
- list of snapshots used:
CVS-2004-04-11-23-00
THE REMINDERS
-------------
* the initial ffmpeg checkout was imported using:
- get CVS ffmpeg
cvs -z3 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg co -D '2004-03-09 06:00 GMT' ffmpeg