Quick-and-dirty documentation for libmpeg2 0.3.1 Kees Cook 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 -1: 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 -1). 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: -1: 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 -1) 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 -1), 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