[MPlayer-G2-dev] Re: Question for Arpi :)

[Arpi]

Hi,

>     So I'm confused with API too. It's why I want _really_ exact API
> description. Then there will no way to say "that may be true but may be
> not". If we have good defined API then we'll avoid headaches in the
> future - then with any changes in function it's behavior will never
> change due to strong API. :)

The video decoder/filter api is not yet final. There are a few
unused fields/flags, and some unclear states.

But for ppl wanting to port their filter ASAP, i hacke dtogether a quick
text of differences from g1:

Video decoder/filter API changes since G1:
==========================================

NOTE: first you should read g1's DOCS/tech/libmpcodecs.txt !

Differences in video decoding:
==============================
video decoders don't get the demuxed fraem as parameter (data/len) to
the decode() function, instead they should request from the demuxer by
using ds_get_packet (or other ds reading functions).
This change was required to allow non-1:1 demux-packet -> video frame
correspondence. For example, libmpeg2 want raw mpeg packets instead of
the ES-demuxed frames. Also, field-based mpeg2 could be handled in
decoders, by reading 2 ds packet and output 1 frame.
Also, decoders can skip demuxer reading, for example when outputting
buffered (from previous packets) frames.

There is an other difference: decoders may (optional!) alter the
timestamps and/or duration got from demuxer.
It's required for formats when timestamp is encoded in the video packet
(instead of the packet header in container), or when you don't have
1:1 mapping between demuxer packets and frames (see above).

Differences in video filters:
=============================
By default, everything works the same way as in G1, except that put_image
won't call next filter's put_image directly, but return the dmpi.
So, instead of 'return vf_next_put_image(vf,dmpi);' you have to write
'return dmpi;' now. And, isntead of 'return 0;' you write 'return NULL;'.

Additionally, filters also have a 'drop' parameter, to allow frame
dropping at filters. By default you can ignore this flag, your put_image()
won't be called when drop!=0.

Let's see the non-default case now:
Your filters may set 2 special flags to control frame dropping:

// filter wants process_image() to be called with mpi=NULL for dropped frames
#define VFCAP_NOTIFY_DROPPED_FRAMES 0x2000

// filter wants to see all frames, even if we want to drop them...
// (so you can't drop frame above this filter)
#define VFCAP_WANTS_DROPPED_FRAMES 0x4000

As you can see, the 'drop' flag has effect only with VFCAP_WANTS_DROPPED_FRAMES.
These flags will allow filters to be notified about dropped frames, it's
required for pattern-matching (like inverse telecine) filters and temporal
postprocessing filters.

Non-1:1 frame mapping in filters:
In G2, you can write filters outputting more frames than inputting, ie.
increasing frame-rate. (Outputting less frames than input was possible
in g1 too, by returning no frame (0 in g1, NULL in g2)).

For this, you have to implement get_pending_image().
When available, this function will be called first, to check if any
buffered/queued frame is available. If it returns NULL, the previous
filter (up to the decoder) will be called, and then put_image() will
receive the new input frame.



A'rpi / Astral & ESP-team

--
Developer of MPlayer G2, the Movie Framework for all - http://www.MPlayerHQ.hu