yuv4mpeg.h

Motion JPEG编解码器源代码

/*
 *  yuv4mpeg.h:  Functions for reading and writing "new" YUV4MPEG2 streams.
 *
 *               Stream format is described at the end of this file.
 *
 *
 *  Copyright (C) 2004 Matthew J. Marjanovic <[e-mail]>
 *
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License
 *  as published by the Free Software Foundation; either version 2
 *  of the License, or (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */

#ifndef __YUV4MPEG_H__
#define __YUV4MPEG_H__

#include <stdlib.h>
#include <mjpeg_types.h>
#ifndef _WIN32
#include <unistd.h>
#endif
#include <mjpeg_logging.h>


/************************************************************************
 *  error codes returned by y4m_* functions
 ************************************************************************/
#define Y4M_OK          0
#define Y4M_ERR_RANGE   1  /* argument or tag value out of range */
#define Y4M_ERR_SYSTEM  2  /* failed system call, check errno */
#define Y4M_ERR_HEADER  3  /* illegal/malformed header */
#define Y4M_ERR_BADTAG  4  /* illegal tag character */
#define Y4M_ERR_MAGIC   5  /* bad header magic */
#define Y4M_ERR_EOF     6  /* end-of-file (clean) */
#define Y4M_ERR_XXTAGS  7  /* too many xtags */
#define Y4M_ERR_BADEOF  8  /* unexpected end-of-file */
#define Y4M_ERR_FEATURE 9  /* stream requires features beyond allowed level */


/* generic 'unknown' value for integer parameters (e.g. interlace, height) */
#define Y4M_UNKNOWN -1

/************************************************************************
 * values for the "interlace" parameter [y4m_*_interlace()]
 ************************************************************************/
#define Y4M_ILACE_NONE          0   /* non-interlaced, progressive frame */
#define Y4M_ILACE_TOP_FIRST     1   /* interlaced, top-field first       */
#define Y4M_ILACE_BOTTOM_FIRST  2   /* interlaced, bottom-field first    */
#define Y4M_ILACE_MIXED         3   /* mixed, "refer to frame header"    */

/************************************************************************
 * values for the "chroma" parameter [y4m_*_chroma()]
 ************************************************************************/
#define Y4M_CHROMA_420JPEG     0  /* 4:2:0, H/V centered, for JPEG/MPEG-1 */
#define Y4M_CHROMA_420MPEG2    1  /* 4:2:0, H cosited, for MPEG-2         */
#define Y4M_CHROMA_420PALDV    2  /* 4:2:0, alternating Cb/Cr, for PAL-DV */
#define Y4M_CHROMA_444         3  /* 4:4:4, no subsampling, phew.         */
#define Y4M_CHROMA_422         4  /* 4:2:2, H cosited                     */
#define Y4M_CHROMA_411         5  /* 4:1:1, H cosited                     */
#define Y4M_CHROMA_MONO        6  /* luma plane only                      */
#define Y4M_CHROMA_444ALPHA    7  /* 4:4:4 with an alpha channel          */

/************************************************************************
 * values for sampling parameters [y4m_*_spatial(), y4m_*_temporal()]
 ************************************************************************/
#define Y4M_SAMPLING_PROGRESSIVE 0
#define Y4M_SAMPLING_INTERLACED  1

/************************************************************************
 * values for "presentation" parameter [y4m_*_presentation()]
 ************************************************************************/
#define Y4M_PRESENT_TOP_FIRST         0  /* top-field-first                 */
#define Y4M_PRESENT_TOP_FIRST_RPT     1  /* top-first, repeat top           */
#define Y4M_PRESENT_BOTTOM_FIRST      2  /* bottom-field-first              */
#define Y4M_PRESENT_BOTTOM_FIRST_RPT  3  /* bottom-first, repeat bottom     */
#define Y4M_PRESENT_PROG_SINGLE       4  /* single progressive frame        */
#define Y4M_PRESENT_PROG_DOUBLE       5  /* progressive frame, repeat once  */
#define Y4M_PRESENT_PROG_TRIPLE       6  /* progressive frame, repeat twice */

#define Y4M_MAX_NUM_PLANES 4

/************************************************************************
 *  'ratio' datatype, for rational numbers
 *                                     (see 'ratio' functions down below)
 ************************************************************************/
typedef struct _y4m_ratio {
  int n;  /* numerator   */
  int d;  /* denominator */
} y4m_ratio_t;


/************************************************************************
 *  useful standard framerates (as ratios)
 ************************************************************************/
extern const y4m_ratio_t y4m_fps_UNKNOWN;
extern const y4m_ratio_t y4m_fps_NTSC_FILM;  /* 24000/1001 film (in NTSC)  */
extern const y4m_ratio_t y4m_fps_FILM;       /* 24fps film                 */
extern const y4m_ratio_t y4m_fps_PAL;        /* 25fps PAL                  */
extern const y4m_ratio_t y4m_fps_NTSC;       /* 30000/1001 NTSC            */
extern const y4m_ratio_t y4m_fps_30;         /* 30fps                      */
extern const y4m_ratio_t y4m_fps_PAL_FIELD;  /* 50fps PAL field rate       */
extern const y4m_ratio_t y4m_fps_NTSC_FIELD; /* 60000/1001 NTSC field rate */
extern const y4m_ratio_t y4m_fps_60;         /* 60fps                      */

/************************************************************************
 *  useful standard sample (pixel) aspect ratios (W:H)
 ************************************************************************/
extern const y4m_ratio_t y4m_sar_UNKNOWN; 
extern const y4m_ratio_t y4m_sar_SQUARE;        /* square pixels */
extern const y4m_ratio_t y4m_sar_NTSC_CCIR601;  /* 525-line (NTSC) Rec.601 */
extern const y4m_ratio_t y4m_sar_NTSC_16_9;     /* 16:9 NTSC/Rec.601       */
extern const y4m_ratio_t y4m_sar_NTSC_SVCD_4_3; /* NTSC SVCD 4:3           */
extern const y4m_ratio_t y4m_sar_NTSC_SVCD_16_9;/* NTSC SVCD 16:9          */
extern const y4m_ratio_t y4m_sar_PAL_CCIR601;   /* 625-line (PAL) Rec.601  */
extern const y4m_ratio_t y4m_sar_PAL_16_9;      /* 16:9 PAL/Rec.601        */
extern const y4m_ratio_t y4m_sar_PAL_SVCD_4_3;  /* PAL SVCD 4:3            */
extern const y4m_ratio_t y4m_sar_PAL_SVCD_16_9; /* PAL SVCD 16:9           */
extern const y4m_ratio_t y4m_sar_SQR_ANA16_9;   /* anamorphic 16:9 sampled */
                                            /* from 4:3 with square pixels */

/************************************************************************
 *  useful standard display aspect ratios (W:H)
 ************************************************************************/
extern const y4m_ratio_t y4m_dar_UNKNOWN; 
extern const y4m_ratio_t y4m_dar_4_3;     /* standard TV   */
extern const y4m_ratio_t y4m_dar_16_9;    /* widescreen TV */
extern const y4m_ratio_t y4m_dar_221_100; /* word-to-your-mother TV */


#define Y4M_MAX_XTAGS 32        /* maximum number of xtags in list       */
#define Y4M_MAX_XTAG_SIZE 32    /* max length of an xtag (including 'X') */

typedef struct _y4m_xtag_list y4m_xtag_list_t;
typedef struct _y4m_stream_info y4m_stream_info_t;
typedef struct _y4m_frame_info y4m_frame_info_t;


#ifdef __cplusplus
#define BEGIN_CDECLS extern "C" {
#define END_CDECLS   }
#else
#define BEGIN_CDECLS 
#define END_CDECLS   
#endif

BEGIN_CDECLS

/************************************************************************
 *  'ratio' functions
 ************************************************************************/

/* 'normalize' a ratio (remove common factors) */
void y4m_ratio_reduce(y4m_ratio_t *r);

/* parse "nnn:ddd" into a ratio (returns Y4M_OK or Y4M_ERR_RANGE) */
int y4m_parse_ratio(y4m_ratio_t *r, const char *s);

/* quick test of two ratios for equality (i.e. identical components) */
#define Y4M_RATIO_EQL(a,b) ( ((a).n == (b).n) && ((a).d == (b).d) )

/* quick conversion of a ratio to a double (no divide-by-zero check!) */
#define Y4M_RATIO_DBL(r) ((double)(r).n / (double)(r).d)

/*************************************************************************
 *
 * Guess the true SAR (sample aspect ratio) from a list of commonly 
 * encountered values, given the "suggested" display aspect ratio (DAR),
 * and the true frame width and height.
 *
 * Returns y4m_sar_UNKNOWN if no match is found.
 *
 *************************************************************************/
y4m_ratio_t y4m_guess_sar(int width, int height, y4m_ratio_t dar);


/*************************************************************************
 *
 * Chroma Subsampling Mode information
 *
 *  x_ratio, y_ratio  -  subsampling of chroma planes
 *  x_offset, y_offset - offset of chroma sample grid,
 *                        relative to luma (0,0) sample
 *
 *************************************************************************/

y4m_ratio_t y4m_chroma_ss_x_ratio(int chroma_mode);
y4m_ratio_t y4m_chroma_ss_y_ratio(int chroma_mode);
#if 0
y4m_ratio_t y4m_chroma_ss_x_offset(int chroma_mode, int field, int plane);
y4m_ratio_t y4m_chroma_ss_y_offset(int chroma_mode, int field, int plane);
#endif

/* Given a string containing a (case-insensitive) chroma-tag keyword,
   return appropriate chroma mode (or Y4M_UNKNOWN) */
int y4m_chroma_parse_keyword(const char *s);

/* Given a Y4M_CHROMA_* mode, return appropriate chroma-tag keyword,
   or NULL if there is none. */
const char *y4m_chroma_keyword(int chroma_mode);

/* Given a Y4M_CHROMA_* mode, return appropriate chroma mode description,
   or NULL if there is none. */
const char *y4m_chroma_description(int chroma_mode);



/************************************************************************
 *  'xtag' functions
 *
 * o Before using an xtag_list (but after the structure/memory has been
 *    allocated), you must initialize it via y4m_init_xtag_list().
 * o After using an xtag_list (but before the structure is released),
 *    call y4m_fini_xtag_list() to free internal memory.
 *
 ************************************************************************/

/* initialize an xtag_list structure */
void y4m_init_xtag_list(y4m_xtag_list_t *xtags);

/* finalize an xtag_list structure */
void y4m_fini_xtag_list(y4m_xtag_list_t *xtags);

/* make one xtag_list into a copy of another */
void y4m_copy_xtag_list(y4m_xtag_list_t *dest, const y4m_xtag_list_t *src);

/* return number of tags in an xtag_list */
int y4m_xtag_count(const y4m_xtag_list_t *xtags);

/* access n'th tag in an xtag_list */
const char *y4m_xtag_get(const y4m_xtag_list_t *xtags, int n);

/* append a new tag to an xtag_list
    returns:          Y4M_OK - success
              Y4M_ERR_XXTAGS - list is already full */
int y4m_xtag_add(y4m_xtag_list_t *xtags, const char *tag);

/* remove a tag from an xtag_list 
    returns:         Y4M_OK - success
              Y4M_ERR_RANGE - n is out of range */
int y4m_xtag_remove(y4m_xtag_list_t *xtags, int n);

/* remove all tags from an xtag_list 
    returns:   Y4M_OK - success       */
int y4m_xtag_clearlist(y4m_xtag_list_t *xtags);

/* append copies of tags from src list to dest list
    returns:          Y4M_OK - success
              Y4M_ERR_XXTAGS - operation would overfill dest list */
int y4m_xtag_addlist(y4m_xtag_list_t *dest, const y4m_xtag_list_t *src);



/************************************************************************
 *  '*_info' functions
 *
 * o Before using a *_info structure (but after the structure/memory has
 *    been allocated), you must initialize it via y4m_init_*_info().
 * o After using a *_info structure (but before the structure is released),
 *    call y4m_fini_*_info() to free internal memory.
 * o Use the 'set' and 'get' accessors to modify or access the fields in
 *    the structures; don't touch the structure directly.  (Ok, so there
 *    is no really convenient C syntax to prevent you from doing this,
 *    but we are all responsible programmers here, so just don't do it!)
 *
 ************************************************************************/

/* initialize a stream_info structure */
void y4m_init_stream_info(y4m_stream_info_t *i);

/* finalize a stream_info structure */
void y4m_fini_stream_info(y4m_stream_info_t *i);

/* reset stream_info back to default/unknown values */
void y4m_clear_stream_info(y4m_stream_info_t *info);

/* make one stream_info into a copy of another */
void y4m_copy_stream_info(y4m_stream_info_t *dest,
			  const y4m_stream_info_t *src);

/* access or set stream_info fields */
/*      level 0                   */
int y4m_si_get_width(const y4m_stream_info_t *si);
int y4m_si_get_height(const y4m_stream_info_t *si);
int y4m_si_get_interlace(const y4m_stream_info_t *si);
y4m_ratio_t y4m_si_get_framerate(const y4m_stream_info_t *si);
y4m_ratio_t y4m_si_get_sampleaspect(const y4m_stream_info_t *si);
void y4m_si_set_width(y4m_stream_info_t *si, int width);
void y4m_si_set_height(y4m_stream_info_t *si, int height);
void y4m_si_set_interlace(y4m_stream_info_t *si, int interlace);
void y4m_si_set_framerate(y4m_stream_info_t *si, y4m_ratio_t framerate);
void y4m_si_set_sampleaspect(y4m_stream_info_t *si, y4m_ratio_t sar);
/*      level 1                   */
void y4m_si_set_chroma(y4m_stream_info_t *si, int chroma_mode);
int y4m_si_get_chroma(const y4m_stream_info_t *si);

/* derived quantities (no setter) */
/*      level 0                   */
int y4m_si_get_framelength(const y4m_stream_info_t *si);
/*      level 1                   */
int y4m_si_get_plane_count(const y4m_stream_info_t *si);
int y4m_si_get_plane_width(const y4m_stream_info_t *si, int plane);
int y4m_si_get_plane_height(const y4m_stream_info_t *si, int plane);
int y4m_si_get_plane_length(const y4m_stream_info_t *si, int plane);


/* access stream_info xtag_list */
y4m_xtag_list_t *y4m_si_xtags(y4m_stream_info_t *si);


/* initialize a frame_info structure */
void y4m_init_frame_info(y4m_frame_info_t *i);

/* finalize a frame_info structure */
void y4m_fini_frame_info(y4m_frame_info_t *i);

/* reset frame_info back to default/unknown values */
void y4m_clear_frame_info(y4m_frame_info_t *info);

/* make one frame_info into a copy of another */
void y4m_copy_frame_info(y4m_frame_info_t *dest,
			 const y4m_frame_info_t *src);