diff options
Diffstat (limited to 'doc/libmpeg2.txt')
| -rw-r--r-- | doc/libmpeg2.txt | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/doc/libmpeg2.txt b/doc/libmpeg2.txt new file mode 100644 index 0000000..de380fb --- /dev/null +++ b/doc/libmpeg2.txt @@ -0,0 +1,266 @@ +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 + |