yuv4mpeg.h

Motion JPEG编解码器源代码

/* access or set frame_info fields (level 1) */
int y4m_fi_get_presentation(const y4m_frame_info_t *fi);
int y4m_fi_get_temporal(const y4m_frame_info_t *fi);
int y4m_fi_get_spatial(const y4m_frame_info_t *fi);

void y4m_fi_set_presentation(y4m_frame_info_t *fi, int pres);
void y4m_fi_set_temporal(y4m_frame_info_t *fi, int sampling);
void y4m_fi_set_spatial(y4m_frame_info_t *fi, int sampling);


/* access frame_info xtag_list */
y4m_xtag_list_t *y4m_fi_xtags(y4m_frame_info_t *fi);



/************************************************************************
 *  blocking read and write functions
 *
 *  o guaranteed to transfer entire payload (or fail)
 *  o return values:
 *                         0 (zero)   complete success
 *          -(# of remaining bytes)   error (and errno left set)
 *          +(# of remaining bytes)   EOF (for y4m_read only)
 *
 ************************************************************************/

/* read len bytes from fd into buf */
ssize_t y4m_read(int fd, void *buf, size_t len);

/* write len bytes from fd into buf */
ssize_t y4m_write(int fd, const void *buf, size_t len);



/************************************************************************
 *  stream header processing functions
 *  
 *  o return values:
 *                   Y4M_OK - success
 *                Y4M_ERR_* - error (see y4m_strerr() for descriptions)
 *
 ************************************************************************/

/* parse a string of stream header tags */
int y4m_parse_stream_tags(char *s, y4m_stream_info_t *i);

/* read a stream header from file descriptor fd
   (the current contents of stream_info are erased first) */
int y4m_read_stream_header(int fd, y4m_stream_info_t *i);

/* write a stream header to file descriptor fd */
int y4m_write_stream_header(int fd, const y4m_stream_info_t *i);



/************************************************************************
 *  frame processing functions
 *  
 *  o return values:
 *                   Y4M_OK - success
 *                Y4M_ERR_* - error (see y4m_strerr() for descriptions)
 *
 ************************************************************************/

/* write a frame header to file descriptor fd */
int y4m_write_frame_header(int fd,
			   const y4m_stream_info_t *si,
			   const y4m_frame_info_t *fi);

/* write a complete frame (header + data)
   o planes[] points to 1-4 buffers, one each for image plane */
int y4m_write_frame(int fd, const y4m_stream_info_t *si, 
		    const y4m_frame_info_t *fi, uint8_t * const *planes);


/* write a complete frame (header + data), but interleave fields
    from two separate buffers
   o upper_field[] same as planes[] above, but for upper field only
   o lower_field[] same as planes[] above, but for lower field only
*/
int y4m_write_fields(int fd, const y4m_stream_info_t *si, 
		     const y4m_frame_info_t *fi,
		     uint8_t * const *upper_field, 
		     uint8_t * const *lower_field);


/* read a frame header from file descriptor fd 
   (the current contents of frame_info are erased first) */
int y4m_read_frame_header(int fd,
			  const y4m_stream_info_t *si,
			  y4m_frame_info_t *fi);

/* read frame data [to be called after y4m_read_frame_header()]
   o planes[] points to 1-4 buffers, one each for image plane */
int y4m_read_frame_data(int fd, const y4m_stream_info_t *si, 
                        y4m_frame_info_t *fi, uint8_t * const *planes);

/* read frame data, but de-interleave fields into two separate buffers
    [to be called after y4m_read_frame_header()]
   o upper_field[] same as planes[] above, but for upper field only
   o lower_field[] same as planes[] above, but for lower field only
*/
int y4m_read_fields_data(int fd, const y4m_stream_info_t *si, 
                         y4m_frame_info_t *fi,
                         uint8_t * const *upper_field, 
                         uint8_t * const *lower_field);

/* read a complete frame (header + data)
   o planes[] points to 1-4 buffers, one each for image plane */
int y4m_read_frame(int fd, const y4m_stream_info_t *si, 
		   y4m_frame_info_t *fi, uint8_t * const *planes);

/* read a complete frame (header + data), but de-interleave fields
    into two separate buffers
   o upper_field[] same as planes[] above, but for upper field only
   o lower_field[] same as planes[] above, but for lower field only
*/
int y4m_read_fields(int fd, const y4m_stream_info_t *si, 
		    y4m_frame_info_t *fi,
		    uint8_t * const *upper_field, 
		    uint8_t * const *lower_field);


/************************************************************************
 *  miscellaneous functions
 ************************************************************************/

/* convenient dump of stream header info via mjpeg_log facility
 *  - each logged/printed line is prefixed by 'prefix'
 */
void y4m_log_stream_info(log_level_t level, const char *prefix,
			 const y4m_stream_info_t *i);

/* convert a Y4M_ERR_* error code into mildly explanatory string */
const char *y4m_strerr(int err);

/* set 'allow_unknown_tag' flag for library...
    o yn = 0 :  unknown header tags will produce a parsing error
    o yn = 1 :  unknown header tags/values will produce a warning, but
                 are otherwise passed along via the xtags list
    o yn = -1:  don't change, just return current setting

   return value:  previous setting of flag
*/
int y4m_allow_unknown_tags(int yn);


/* set level of "accepted extensions" for the library...
    o level = 0:  default - conform to original YUV4MPEG2 spec; yield errors
                   when reading or writing a stream which exceeds it.
    o level = 1:  allow reading/writing streams which contain non-420jpeg
                   chroma and/or mixed-mode interlacing
    o level = -1: don't change, just return current setting

   return value:  previous setting of level
 */
int y4m_accept_extensions(int level);


END_CDECLS


/************************************************************************
 ************************************************************************

  Description of the (new!, forever?) YUV4MPEG2 stream format:

  STREAM consists of
    o one '\n' terminated STREAM-HEADER
    o unlimited number of FRAMEs

  FRAME consists of
    o one '\n' terminated FRAME-HEADER
    o "length" octets of planar YCrCb 4:2:0 image data
        (if frame is interlaced, then the two fields are interleaved)


  STREAM-HEADER consists of
     o string "YUV4MPEG2"
     o unlimited number TAGGED-FIELDs, each preceded by ' ' separator
     o '\n' line terminator

  FRAME-HEADER consists of
     o string "FRAME"
     o unlimited number of TAGGED-FIELDs, each preceded by ' ' separator
     o '\n' line terminator


  TAGGED-FIELD consists of
     o single ascii character tag
     o VALUE (which does not contain whitespace)

  VALUE consists of
     o integer (base 10 ascii representation)
  or o RATIO
  or o single ascii character
  or o non-whitespace ascii string

  RATIO consists of
     o numerator (integer)
     o ':' (a colon)
     o denominator (integer)


  The currently supported tags for the STREAM-HEADER:
     W - [integer] frame width, pixels, should be > 0
     H - [integer] frame height, pixels, should be > 0
     C - [string]  chroma-subsampling/data format
           420jpeg   (default)
           420mpeg2
           420paldv
           411
           422
           444       - non-subsampled Y'CbCr
	   444alpha  - Y'CbCr with alpha channel (with Y' black/white point)
           mono      - Y' plane only
     I - [char] interlacing:  p - progressive (none)
                              t - top-field-first
                              b - bottom-field-first
                              m - mixed -- see 'I' tag in frame header
                              ? - unknown
     F - [ratio] frame-rate, 0:0 == unknown
     A - [ratio] sample (pixel) aspect ratio, 0:0 == unknown
     X - [character string] 'metadata' (unparsed, but passed around)

  The currently supported tags for the FRAME-HEADER:
     Ixyz - framing/sampling (required if-and-only-if stream is "Im")
          x:  t - top-field-first
              T - top-field-first and repeat
	      b - bottom-field-first
              B - bottom-field-first and repeat
              1 - single progressive frame
              2 - double progressive frame (repeat)
              3 - triple progressive frame (repeat twice)

          y:  p - progressive:  fields sampled at same time
              i - interlaced:   fields sampled at different times

          z:  p - progressive:  subsampling over whole frame
              i - interlaced:   each field subsampled independently
              ? - unknown (allowed only for non-4:2:0 subsampling)           
       
     X - character string 'metadata' (unparsed, but passed around)

 ************************************************************************
 ************************************************************************/


/*

   THAT'S ALL FOLKS!

   Thank you for reading the source code.  We hope you have thoroughly
   enjoyed the experience.

*/





#ifdef INTERNAL_Y4M_LIBCODE_STUFF_QPX
#define Y4MPRIVATIZE(identifier) identifier
#else
#define Y4MPRIVATIZE(identifier) PRIVATE##identifier
#endif

/* 
 * Actual structure definitions of structures which you shouldn't touch.
 *
 */

/************************************************************************
 *  'xtag_list' --- list of unparsed and/or meta/X header tags
 *
 *     Do not touch this structure directly!
 *
 *     Use the y4m_xtag_*() functions (see below).
 *     You must initialize/finalize this structure before/after use.
 ************************************************************************/
struct _y4m_xtag_list {
  int Y4MPRIVATIZE(count);
  char *Y4MPRIVATIZE(tags)[Y4M_MAX_XTAGS];
};


/************************************************************************
 *  'stream_info' --- stream header information
 *
 *     Do not touch this structure directly!
 *
 *     Use the y4m_si_*() functions (see below).
 *     You must initialize/finalize this structure before/after use.
 ************************************************************************/
struct _y4m_stream_info {
  /* values from header/setters */
  int Y4MPRIVATIZE(width);
  int Y4MPRIVATIZE(height);
  int Y4MPRIVATIZE(interlace);            /* see Y4M_ILACE_* definitions  */
  y4m_ratio_t Y4MPRIVATIZE(framerate);    /* see Y4M_FPS_* definitions    */
  y4m_ratio_t Y4MPRIVATIZE(sampleaspect); /* see Y4M_SAR_* definitions    */
  int Y4MPRIVATIZE(chroma);               /* see Y4M_CHROMA_* definitions */

  /* mystical X tags */
  y4m_xtag_list_t Y4MPRIVATIZE(x_tags);
};


/************************************************************************
 *  'frame_info' --- frame header information
 *
 *     Do not touch this structure directly!
 *
 *     Use the y4m_fi_*() functions (see below).
 *     You must initialize/finalize this structure before/after use.
 ************************************************************************/

struct _y4m_frame_info {
  int Y4MPRIVATIZE(spatial);      /* see Y4M_SAMPLING_* definitions */
  int Y4MPRIVATIZE(temporal);     /* see Y4M_SAMPLING_* definitions */
  int Y4MPRIVATIZE(presentation); /* see Y4M_PRESENT_* definitions  */
  /* mystical X tags */
  y4m_xtag_list_t Y4MPRIVATIZE(x_tags);
};


#undef Y4MPRIVATIZE


#endif /* __YUV4MPEG_H__ */