path: root/doc/libmpeg2.txt

The documentation is currently a mess. Sorry about that, hope to write
something better for the 0.4.1 release.


For people migrating code from 0.3.x to 0.4.0, the biggest thing to
note is that mpeg2_parse now returns a new state STATE_BUFFER when it
needs more data. Version 0.3.x used to return a -1 constant for this -
please update your code to replace that -1 with STATE_BUFFER. Otherwise
0.3.x code should mostly work with 0.4.0, hopefully.


For people new to libmpeg2, it's best to start by looking at
doc/sample1 and doc/sample2, which decode an mpeg2 elementary stream
and output their individual pictures as yuv frames (sample1) or rgb
frames (sample2). The main loop calls mpeg2_parse() which does some
work and then returns a state indicating what it just did -
STATE_BUFFER if it reached the end of the buffer and it needs a new
one, STATE_SEQUENCE if it just parsed a sequence header, STATE_PICTURE
if it just parsed a picture header, STATE_SLICE if it just decoded the
slice information associated with a picture (now is a good time to
save that decoded picture), etc...


To make more complex buffer management (basically allocate your own
buffers instead of letting the lib do it for you), look at
sample3/sample4 (giving your buffers to the lib at init time but
letting the lib chose a buffer for each picture) or sample5/sample6
(giving a new buffer to the lib for each picture).


Color conversion has been moved to a new helper library, libmpeg2convert.
The details of the mpeg2_convert_t type might change in the future,
but what won't change is that you should just take one of the
mpeg2_convert_t symbols exported from libmpeg2convert, and pass it to
the mpeg2_convert() function, and voila, you now get your output
buffers in the desired format. For example if you want rgb 32-bit
samples, you just call mpeg2_convert (mpeg2dec, mpeg2convert_rgb32, NULL)
and that's it.


There is a new mpeg2_stride function too. By default libmpeg2 choses
the smallest stride that will work for a given picture size, if you
want a larger stride you can set it (after the sequence header has
been decoded) by calling mpeg2_stride.


There is also a new function mpeg2_reset which should hopefully do the
right thing after skipping to a new position in the mpeg2 stream. If
full_reset is zero the lib starts decoding at the next picture, if
it's one the lib starts looking for the next sequence header.


The mpeg2_pts function is gone, because people complained about not
being to pass a 33-bit PTS thru it. So instead it's been replaced with
mpeg2_tag_picture(), which is identical except that it allows you to
pass two 32-bit values. You can use them to form a combined 64-bit
time stamp, or two 32-bit PTS/DTS stamps, or whatever you please -
libmpeg2 never uses these values, it just passes them around, hence
the name "tag". The semantics are what you want for a PTS function
though, i.e. the tags get associated to the next picture that starts
after the tag was set, where the start of a picture is defined as the
first byte of its picture start code.


That's all I can think of - sorry for the lack of proper
documentation, I'll try to help this before the 0.4.1 release.






I - simplest example

explanation of sequence_t, picture_t fields

II - w/ color conversion

III - pts

IV - app that preallocates buffers

V - app that does its own buffer management





Quick-and-dirty documentation for libmpeg2 0.3.1
Kees Cook <mpeg2@outflux.net>
2003-04-25



Basic Usage Pseudocode
----------------------

        if (you need a certain acceleration)
                mpeg2_accel(desired_acceleration);
        handle=mpeg2_init();
        info=mpeg2_info(handle);
        while (data_available) {
                state=mpeg2_parse(handle);
                switch (state) {
                case STATE_BUFFER:
                        read some data
                        mpeg2_buffer(handle,data_start,data_end);
                        break;
                case STATE_SLICE:
                case STATE_END:
                        display the frame described in "info"
                        break;
                case STATE_INVALID:
                        abort
                        break;
                }
        }
        mpeg2_close(handle);


Basic Usage Explained
---------------------

libmpeg2 uses an opaque pointer which is the active "handle" to the mpeg2
decoder.  To get this handle (of type "mpeg2dec_t"), call "mpeg2_init()".

Data is loaded into the decoder with "mpeg2_buffer" whenever
"mpeg2_parse" is ready for more data (return state is STATE_BUFFER).
Pictures are available whenever "mpeg2_parse"'s return state is
STATE_SLICE or STATE_END.

        This means the *previous* picture is available, right?  In other
        words, when STATE_SLICE is seen, that means that the *previous*
        picture is all done.  Same thing for STATE_END.  So if you want to
        see one frame at a time (without starting to fill the mpeg2 decoder
        with more data not from that picture) we'd have to inject something
        to make it report STATE_END?



Basic Function Reference
------------------------

mpeg2dec_t * mpeg2_init()
        Initializes a memory space for mpeg2 decoding.  This memory must
        be freed with a call to "mpeg2_close" when finished.

        Returns NULL on error (when system is out of memory)

                - Doesn't check if chunk_buffer is NULL?


uint32_t mpeg2_accel(uint32_t accel)
        Sets the CPU acceleration type to be used for all decoders for the
        life of the program.  YOU CAN SAFELY IGNORE THIS FUNCTION.
       
        By default, a call to mpeg2_accel is not needed, since the best
        available acceleration will be auto-detected.  To override the
        default, this function must be called before any calls to
        "mpeg2_init".  See mpeg2.h for a list of the available accelerations
        (prefix "MPEG2_ACCEL_...").
        
        After a call to mpeg2_init, mpeg2_accel can be called to find out
        what the selected acceleration list is.  Once the accelerations have
        been selected (through explicitly requesting one, or through
        auto-detection) the "accel" parameter will be ignored.

        Returns selected acceleration list.  If the requested acceleration
        is not available, the function will auto-detect the best available
        accelerations and return that instead.
        
                - Cannot be undone!  This should maybe be a part of
                  the mpeg2 structure somehow?


const mpeg2_info_t * mpeg2_info(mpeg2dec_t * handle)
        Gets structure for the mpeg2 decoder's "mpeg2_info_t" structure.
        This will let you do something (like display!) the decoded pictures
        with the mpeg2_info_t structure members:

        display_fbuf:
                memory area containing the rendered picture information.
                If this is NULL, no frame is available.

        display_fbuf->buf:
                YUV coded pixel data for the picture.

        display_picture:
                data structure describing the current picture.
                see mpeg2.h for more details.

        sequence:
                data structure describing the entire current picture sequence:

                width:  picture width in pixels.
                height: picture height in pixels.

                see mpeg2.h for more details.

        user_data:
                handy place to attach things needed by your program.  Must
                be detached before calling "mpeg2_close".

        there are more...check mpeg2.h




int mpeg2_parse(mpeg2dec_t * handle)
        Parses available data and returns state of the decoder:

        STATE_BUFFER:
                ready for more data.  decoder has finished reading
                the buffer sent with mpeg2_buffer.

        STATE_SEQUENCE:
                A sequence header has been found.

        STATE_SEQUENCE_REPEATED:
                A repeated sequence header has been found and processed.

        STATE_GOP:
                A GOP has been found.

        STATE_PICTURE:
                A picture header has been found.
        STATE_PICTURE_2ND:
                A second field picture header has been found.

        STATE_SLICE_1ST:
                First slice of a multi-field picture has been found.
        STATE_SLICE:
                Final slice (multi-field or not) of a picture has been found.
                Good time to update the display.
        STATE_END:
                End of the stream?  Good time to update the display.

        STATE_INVALID:
                Filled the internal buffers without finding any start codes.
                Cannot continue: mpeg2_close must be called next.


void mpeg2_buffer(mpeg2dec_t * handle, uint8_t * start, uint8_t * end)
        Makes data between "start" and "end" available for processing.
        If a subsequent call to "mpeg2_parse" doesn't find anything useful
        (returns STATE_BUFFER) then this data will be copied into the mpeg2
        decoder's private data area.  This process repeats until something
        useful is found with mpeg2_parse (returns something other than
        STATE_BUFFER), or the buffer fills up.


void mpeg2_close(mpeg2dec_t * handle)
        Cleans up the memory associated with the mpeg2 decoder handle.

        - does not check for NULL frees! (via mpeg2_free)


Advanced Function Reference
---------------------------

mpeg2_convert
mpeg2_set_buf
mpeg2_custom_fbuf
mpeg2_init_fbuf
mpeg2_slice