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