home *** CD-ROM | disk | FTP | other *** search
/ Chip 2005 June / ccd0605.iso / LINUX / gopchop-1.1.7.tar.tar / gopchop-1.1.7.tar / gopchop-1.1.7 / docs / libmpeg2.txt < prev    next >
Text File  |  2003-04-26  |  6KB  |  178 lines
  1. Quick-and-dirty documentation for libmpeg2 0.3.1
  2. Kees Cook <mpeg2@outflux.net>
  3. 2003-04-25
  4.  
  5.  
  6.  
  7. Basic Usage Pseudocode
  8. ----------------------
  9.  
  10.         if (you need a certain acceleration)
  11.                 mpeg2_accel(desired_acceleration);
  12.         handle=mpeg2_init();
  13.         info=mpeg2_info(handle);
  14.         while (data_available) {
  15.                 state=mpeg2_parse(handle);
  16.                 switch (state) {
  17.                 case -1:
  18.                         read some data
  19.                         mpeg2_buffer(handle,data_start,data_end);
  20.                         break;
  21.                 case STATE_SLICE:
  22.                 case STATE_END:
  23.                         display the frame described in "info"
  24.                         break;
  25.                 case STATE_INVALID:
  26.                         abort
  27.                         break;
  28.                 }
  29.         }
  30.         mpeg2_close(handle);
  31.  
  32.  
  33. Basic Usage Explained
  34. ---------------------
  35.  
  36. libmpeg2 uses an opaque pointer which is the active "handle" to the mpeg2
  37. decoder.  To get this handle (of type "mpeg2dec_t"), call "mpeg2_init()".
  38.  
  39. Data is loaded into the decoder with "mpeg2_buffer" whenever "mpeg2_parse"
  40. is ready for more data (return state is -1).  Pictures are available whenever
  41. "mpeg2_parse"'s return state is STATE_SLICE or STATE_END.
  42.  
  43.         This means the *previous* picture is available, right?  In other
  44.         words, when STATE_SLICE is seen, that means that the *previous*
  45.         picture is all done.  Same thing for STATE_END.  So if you want to
  46.         see one frame at a time (without starting to fill the mpeg2 decoder
  47.         with more data not from that picture) we'd have to inject something
  48.         to make it report STATE_END?
  49.  
  50.  
  51.  
  52. Basic Function Reference
  53. ------------------------
  54.  
  55. mpeg2dec_t * mpeg2_init()
  56.         Initializes a memory space for mpeg2 decoding.  This memory must
  57.         be freed with a call to "mpeg2_close" when finished.
  58.  
  59.         Returns NULL on error (when system is out of memory)
  60.  
  61.                 - Doesn't check if chunk_buffer is NULL?
  62.  
  63.  
  64. uint32_t mpeg2_accel(uint32_t accel)
  65.         Sets the CPU acceleration type to be used for all decoders for the
  66.         life of the program.  YOU CAN SAFELY IGNORE THIS FUNCTION.
  67.        
  68.         By default, a call to mpeg2_accel is not needed, since the best
  69.         available acceleration will be auto-detected.  To override the
  70.         default, this function must be called before any calls to
  71.         "mpeg2_init".  See mpeg2.h for a list of the available accelerations
  72.         (prefix "MPEG2_ACCEL_...").
  73.         
  74.         After a call to mpeg2_init, mpeg2_accel can be called to find out
  75.         what the selected acceleration list is.  Once the accelerations have
  76.         been selected (through explicitly requesting one, or through
  77.         auto-detection) the "accel" parameter will be ignored.
  78.  
  79.         Returns selected acceleration list.  If the requested acceleration
  80.         is not available, the function will auto-detect the best available
  81.         accelerations and return that instead.
  82.         
  83.                 - Cannot be undone!  This should maybe be a part of
  84.                   the mpeg2 structure somehow?
  85.  
  86.  
  87. const mpeg2_info_t * mpeg2_info(mpeg2dec_t * handle)
  88.         Gets structure for the mpeg2 decoder's "mpeg2_info_t" structure.
  89.         This will let you do something (like display!) the decoded pictures
  90.         with the mpeg2_info_t structure members:
  91.  
  92.         display_fbuf:
  93.                 memory area containing the rendered picture information.
  94.                 If this is NULL, no frame is available.
  95.  
  96.         display_fbuf->buf:
  97.                 YUV coded pixel data for the picture.
  98.  
  99.         display_picture:
  100.                 data structure describing the current picture.
  101.                 see mpeg2.h for more details.
  102.  
  103.         sequence:
  104.                 data structure describing the entire current picture sequence:
  105.  
  106.                 width:  picture width in pixels.
  107.                 height: picture height in pixels.
  108.  
  109.                 see mpeg2.h for more details.
  110.  
  111.         user_data:
  112.                 handy place to attach things needed by your program.  Must
  113.                 be detached before calling "mpeg2_close".
  114.  
  115.         there are more...check mpeg2.h
  116.  
  117.  
  118.  
  119.  
  120. int mpeg2_parse(mpeg2dec_t * handle)
  121.         Parses available data and returns state of the decoder:
  122.  
  123.         -1:
  124.                 ready for more data.  decoder has finished reading
  125.                 the buffer sent with mpeg2_buffer.
  126.  
  127.         STATE_SEQUENCE:
  128.                 A sequence header has been found.
  129.  
  130.         STATE_SEQUENCE_REPEATED:
  131.                 A repeated sequence header has been found and processed.
  132.  
  133.         STATE_GOP:
  134.                 A GOP has been found.
  135.  
  136.         STATE_PICTURE:
  137.                 A picture header has been found.
  138.         STATE_PICTURE_2ND:
  139.                 A second field picture header has been found.
  140.  
  141.         STATE_SLICE_1ST:
  142.                 First slice of a multi-field picture has been found.
  143.         STATE_SLICE:
  144.                 Final slice (multi-field or not) of a picture has been found.
  145.                 Good time to update the display.
  146.         STATE_END:
  147.                 End of the stream?  Good time to update the display.
  148.  
  149.         STATE_INVALID:
  150.                 Filled the internal buffers without finding any start codes.
  151.                 Cannot continue: mpeg2_close must be called next.
  152.  
  153.  
  154. void mpeg2_buffer(mpeg2dec_t * handle, uint8_t * start, uint8_t * end)
  155.         Makes data between "start" and "end" available for processing.
  156.         If a subsequent call to "mpeg2_parse" doesn't find anything useful
  157.         (returns -1) then this data will be copied into the mpeg2 decoder's
  158.         private data area.  This process repeats until something useful is
  159.         found with mpeg2_parse (returns something other than -1), or the
  160.         buffer fills up.
  161.  
  162.  
  163. void mpeg2_close(mpeg2dec_t * handle)
  164.         Cleans up the memory associated with the mpeg2 decoder handle.
  165.  
  166.         - does not check for NULL frees! (via mpeg2_free)
  167.  
  168.  
  169. Advanced Function Reference
  170. ---------------------------
  171.  
  172. mpeg2_convert
  173. mpeg2_set_buf
  174. mpeg2_custom_fbuf
  175. mpeg2_init_fbuf
  176. mpeg2_slice
  177.  
  178.