libmpdemux/yuv4mpeg.h

   1 /*
   2  *  yuv4mpeg.h:  Functions for reading and writing "new" YUV4MPEG2 streams.
   3  *
   4  *               Stream format is described at the end of this file.
   5  *
   6  *
   7  *  Copyright (C) 2001 Matthew J. Marjanovic <maddog@mir.com>
   8  *
   9  *  This file is part of the MJPEG Tools package (mjpeg.sourceforge.net).
  10  *  Ported to mplayer by Rik Snel <rsnel@cube.dyndns.org>
  11  *
  12  *  This program is free software; you can redistribute it and/or
  13  *  modify it under the terms of the GNU General Public License
  14  *  as published by the Free Software Foundation; either version 2
  15  *  of the License, or (at your option) any later version.
  16  *
  17  *  This program is distributed in the hope that it will be useful,
  18  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  *  GNU General Public License for more details.
  21  *
  22  *  You should have received a copy of the GNU General Public License
  23  *  along with this program; if not, write to the Free Software
  24  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  25  */
  26
  27 #ifndef MPLAYER_YUV4MPEG_H
  28 #define MPLAYER_YUV4MPEG_H
  29
  30 #include <stdlib.h>
  31 //#include "mp_msg.h"
  32 #include "stream/stream.h"
  33
  34
  35
  36 /************************************************************************
  37  *  error codes returned by y4m_* functions
  38  ************************************************************************/
  39 #define Y4M_OK          0
  40 #define Y4M_ERR_RANGE   1
  41 #define Y4M_ERR_SYSTEM  2
  42 #define Y4M_ERR_HEADER  3
  43 #define Y4M_ERR_BADTAG  4
  44 #define Y4M_ERR_MAGIC   5
  45 #define Y4M_ERR_EOF     6
  46 #define Y4M_ERR_XXTAGS  7
  47
  48
  49 /* generic 'unknown' value for integer parameters (e.g. interlace, height) */
  50 #define Y4M_UNKNOWN -1
  51
  52
  53
  54 /************************************************************************
  55  *  'ratio' datatype, for rational numbers
  56  *                                     (see 'ratio' functions down below)
  57  ************************************************************************/
  58 typedef struct y4m_ratio {
  59   int n;  /* numerator   */
  60   int d;  /* denominator */
  61 } y4m_ratio_t;
  62
  63
  64 /************************************************************************
  65  *  useful standard framerates (as ratios)
  66  ************************************************************************/
  67 extern const y4m_ratio_t y4m_fps_UNKNOWN;
  68 extern const y4m_ratio_t y4m_fps_NTSC_FILM;  /* 24000/1001 film (in NTSC)  */
  69 extern const y4m_ratio_t y4m_fps_FILM;       /* 24fps film                 */
  70 extern const y4m_ratio_t y4m_fps_PAL;        /* 25fps PAL                  */
  71 extern const y4m_ratio_t y4m_fps_NTSC;       /* 30000/1001 NTSC            */
  72 extern const y4m_ratio_t y4m_fps_30;         /* 30fps                      */
  73 extern const y4m_ratio_t y4m_fps_PAL_FIELD;  /* 50fps PAL field rate       */
  74 extern const y4m_ratio_t y4m_fps_NTSC_FIELD; /* 60000/1001 NTSC field rate */
  75 extern const y4m_ratio_t y4m_fps_60;         /* 60fps                      */
  76
  77 /************************************************************************
  78  *  useful standard sample (pixel) aspect ratios
  79  ************************************************************************/
  80 extern const y4m_ratio_t y4m_sar_UNKNOWN;
  81 extern const y4m_ratio_t y4m_sar_SQUARE;        /* square pixels */
  82 extern const y4m_ratio_t y4m_sar_NTSC_CCIR601;  /* 525-line (NTSC) Rec.601 */
  83 extern const y4m_ratio_t y4m_sar_NTSC_16_9;     /* 16:9 NTSC/Rec.601       */
  84 extern const y4m_ratio_t y4m_sar_NTSC_SVCD_4_3; /* NTSC SVCD 4:3           */
  85 extern const y4m_ratio_t y4m_sar_NTSC_SVCD_16_9;/* NTSC SVCD 16:9          */
  86 extern const y4m_ratio_t y4m_sar_PAL_CCIR601;   /* 625-line (PAL) Rec.601  */
  87 extern const y4m_ratio_t y4m_sar_PAL_16_9;      /* 16:9 PAL/Rec.601        */
  88 extern const y4m_ratio_t y4m_sar_PAL_SVCD_4_3;  /* PAL SVCD 4:3            */
  89 extern const y4m_ratio_t y4m_sar_PAL_SVCD_16_9; /* PAL SVCD 16:9           */
  90
  91
  92 /************************************************************************
  93  *  'xtag_list' --- list of unparsed and/or meta/X header tags
  94  *
  95  *     Do not touch this structure directly!
  96  *
  97  *     Use the y4m_xtag_*() functions (see below).
  98  *     You must initialize/finalize this structure before/after use.
  99  ************************************************************************/
 100 #define Y4M_MAX_XTAGS 32        /* maximum number of xtags in list       */
 101 #define Y4M_MAX_XTAG_SIZE 32    /* max length of an xtag (including 'X') */
 102 typedef struct y4m_xtag_list {
 103   int count;
 104   char *tags[Y4M_MAX_XTAGS];
 105 } y4m_xtag_list_t;
 106
 107
 108
 109 /************************************************************************
 110  *  'stream_info' --- stream header information
 111  *
 112  *     Do not touch this structure directly!
 113  *
 114  *     Use the y4m_si_*() functions (see below).
 115  *     You must initialize/finalize this structure before/after use.
 116  ************************************************************************/
 117 typedef struct y4m_stream_info {
 118   /* values from header */
 119   int width;
 120   int height;
 121   int interlace;            /* see Y4M_ILACE_* definitions below   */
 122   y4m_ratio_t framerate;    /* frames-per-second;   0:0 == unknown */
 123   y4m_ratio_t sampleaspect; /* pixel width/height;  0:0 == unknown */
 124   /* computed/derivative values */
 125   int framelength;    /* bytes of data per frame (not including header) */
 126   /* mystical X tags */
 127   y4m_xtag_list_t x_tags;
 128 } y4m_stream_info_t;
 129
 130 /* possible options for the interlace parameter */
 131 #define Y4M_ILACE_NONE          0   /* non-interlaced, progressive frame */
 132 #define Y4M_ILACE_TOP_FIRST     1   /* interlaced, top-field first       */
 133 #define Y4M_ILACE_BOTTOM_FIRST  2   /* interlaced, bottom-field first    */
 134
 135
 136 /************************************************************************
 137  *  'frame_info' --- frame header information
 138  *
 139  *     Do not touch this structure directly!
 140  *
 141  *     Use the y4m_fi_*() functions (see below).
 142  *     You must initialize/finalize this structure before/after use.
 143  ************************************************************************/
 144 typedef struct y4m_frame_info {
 145   /* mystical X tags */
 146   y4m_xtag_list_t x_tags;
 147 } y4m_frame_info_t;
 148
 149
 150
 151 #ifdef __cplusplus
 152 extern "C" {
 153 #else
 154 #endif
 155
 156
 157 /************************************************************************
 158  *  'ratio' functions
 159  ************************************************************************/
 160
 161 /* 'normalize' a ratio (remove common factors) */
 162 void y4m_ratio_reduce(y4m_ratio_t *r);
 163
 164 /* parse "nnn:ddd" into a ratio (returns Y4M_OK or Y4M_ERR_RANGE) */
 165 int y4m_parse_ratio(y4m_ratio_t *r, const char *s);
 166
 167 /* quick test of two ratios for equality (i.e. identical components) */
 168 #define Y4M_RATIO_EQL(a,b) ( ((a).n == (b).n) && ((a).d == (b).d) )
 169
 170 /* quick conversion of a ratio to a double (no divide-by-zero check!) */
 171 #define Y4M_RATIO_DBL(r) ((double)(r).n / (double)(r).d)
 172
 173
 174
 175 /************************************************************************
 176  *  'xtag' functions
 177  *
 178  * o Before using an xtag_list (but after the structure/memory has been
 179  *    allocated), you must initialize it via y4m_init_xtag_list().
 180  * o After using an xtag_list (but before the structure is released),
 181  *    call y4m_fini_xtag_list() to free internal memory.
 182  *
 183  ************************************************************************/
 184
 185 /* initialize an xtag_list structure */
 186 void y4m_init_xtag_list(y4m_xtag_list_t *xtags);
 187
 188 /* finalize an xtag_list structure */
 189 void y4m_fini_xtag_list(y4m_xtag_list_t *xtags);
 190
 191 /* make one xtag_list into a copy of another */
 192 void y4m_copy_xtag_list(y4m_xtag_list_t *dest, const y4m_xtag_list_t *src);
 193
 194 /* return number of tags in an xtag_list */
 195 int y4m_xtag_count(const y4m_xtag_list_t *xtags);
 196
 197 /* access n'th tag in an xtag_list */
 198 const char *y4m_xtag_get(const y4m_xtag_list_t *xtags, int n);
 199
 200 /* append a new tag to an xtag_list
 201     returns:          Y4M_OK - success
 202               Y4M_ERR_XXTAGS - list is already full */
 203 int y4m_xtag_add(y4m_xtag_list_t *xtags, const char *tag);
 204
 205 /* remove a tag from an xtag_list
 206     returns:         Y4M_OK - success
 207               Y4M_ERR_RANGE - n is out of range */
 208 int y4m_xtag_remove(y4m_xtag_list_t *xtags, int n);
 209
 210 /* remove all tags from an xtag_list
 211     returns:   Y4M_OK - success       */
 212 int y4m_xtag_clearlist(y4m_xtag_list_t *xtags);
 213
 214 /* append copies of tags from src list to dest list
 215     returns:          Y4M_OK - success
 216               Y4M_ERR_XXTAGS - operation would overfill dest list */
 217 int y4m_xtag_addlist(y4m_xtag_list_t *dest, const y4m_xtag_list_t *src);
 218
 219
 220
 221 /************************************************************************
 222  *  '*_info' functions
 223  *
 224  * o Before using a *_info structure (but after the structure/memory has
 225  *    been allocated), you must initialize it via y4m_init_*_info().
 226  * o After using a *_info structure (but before the structure is released),
 227  *    call y4m_fini_*_info() to free internal memory.
 228  * o Use the 'set' and 'get' accessors to modify or access the fields in
 229  *    the structures; don't touch the structure directly.  (Ok, so there
 230  *    is no really convenient C syntax to prevent you from doing this,
 231  *    but we are all responsible programmers here, so just don't do it!)
 232  *
 233  ************************************************************************/
 234
 235 /* initialize a stream_info structure */
 236 void y4m_init_stream_info(y4m_stream_info_t *i);
 237
 238 /* finalize a stream_info structure */
 239 void y4m_fini_stream_info(y4m_stream_info_t *i);
 240
 241 /* make one stream_info into a copy of another */
 242 void y4m_copy_stream_info(y4m_stream_info_t *dest, y4m_stream_info_t *src);
 243
 244 /* access or set stream_info fields */
 245 void y4m_si_set_width(y4m_stream_info_t *si, int width);
 246 int y4m_si_get_width(y4m_stream_info_t *si);
 247 void y4m_si_set_height(y4m_stream_info_t *si, int height);
 248 int y4m_si_get_height(y4m_stream_info_t *si);
 249 void y4m_si_set_interlace(y4m_stream_info_t *si, int interlace);
 250 int y4m_si_get_interlace(y4m_stream_info_t *si);
 251 void y4m_si_set_framerate(y4m_stream_info_t *si, y4m_ratio_t framerate);
 252 y4m_ratio_t y4m_si_get_framerate(y4m_stream_info_t *si);
 253 void y4m_si_set_sampleaspect(y4m_stream_info_t *si, y4m_ratio_t sar);
 254 y4m_ratio_t y4m_si_get_sampleaspect(y4m_stream_info_t *si);
 255 int y4m_si_get_framelength(y4m_stream_info_t *si);
 256
 257 /* access stream_info xtag_list */
 258 y4m_xtag_list_t *y4m_si_xtags(y4m_stream_info_t *si);
 259
 260
 261 /* initialize a frame_info structure */
 262 void y4m_init_frame_info(y4m_frame_info_t *i);
 263
 264 /* finalize a frame_info structure */
 265 void y4m_fini_frame_info(y4m_frame_info_t *i);
 266
 267 /* make one frame_info into a copy of another */
 268 void y4m_copy_frame_info(y4m_frame_info_t *dest, y4m_frame_info_t *src);
 269
 270 /* access frame_info xtag_list */
 271 y4m_xtag_list_t *y4m_fi_xtags(y4m_frame_info_t *fi);
 272
 273
 274
 275 /************************************************************************
 276  *  blocking read and write functions
 277  *
 278  *  o guaranteed to transfer entire payload (or fail)
 279  *  o return values:
 280  *                         0 (zero)   complete success
 281  *          -(# of remaining bytes)   error (and errno left set)
 282  *          +(# of remaining bytes)   EOF (for y4m_read only)
 283  *
 284  ************************************************************************/
 285
 286 /* read len bytes from fd into buf */
 287 ssize_t y4m_read(stream_t *s, char *buf, size_t len);
 288
 289 #if 0
 290 /* write len bytes from fd into buf */
 291 ssize_t y4m_write(int fd, char *buf, size_t len);
 292 #endif
 293
 294
 295 /************************************************************************
 296  *  stream header processing functions
 297  *
 298  *  o return values:
 299  *                   Y4M_OK - success
 300  *                Y4M_ERR_* - error (see y4m_strerr() for descriptions)
 301  *
 302  ************************************************************************/
 303
 304 /* parse a string of stream header tags */
 305 int y4m_parse_stream_tags(char *s, y4m_stream_info_t *i);
 306
 307 /* read a stream header from file descriptor fd */
 308 int y4m_read_stream_header(stream_t *s, y4m_stream_info_t *i);
 309
 310 #if 0
 311 /* write a stream header to file descriptor fd */
 312 int y4m_write_stream_header(int fd,  y4m_stream_info_t *i);
 313 #endif
 314
 315
 316 /************************************************************************
 317  *  frame processing functions
 318  *
 319  *  o return values:
 320  *                   Y4M_OK - success
 321  *                Y4M_ERR_* - error (see y4m_strerr() for descriptions)
 322  *
 323  ************************************************************************/
 324
 325 /* read a frame header from file descriptor fd */
 326 int y4m_read_frame_header(stream_t *s, y4m_frame_info_t *i);
 327
 328 #if 0
 329 /* write a frame header to file descriptor fd */
 330 int y4m_write_frame_header(int fd, y4m_frame_info_t *i);
 331 #endif
 332
 333 /* read a complete frame (header + data)
 334    o yuv[3] points to three buffers, one each for Y, U, V planes */
 335 int y4m_read_frame(stream_t *s, y4m_stream_info_t *si,
 336                    y4m_frame_info_t *fi, unsigned char *yuv[3]);
 337
 338 #if 0
 339 /* write a complete frame (header + data)
 340    o yuv[3] points to three buffers, one each for Y, U, V planes */
 341 int y4m_write_frame(int fd, y4m_stream_info_t *si,
 342                     y4m_frame_info_t *fi, unsigned char *yuv[3]);
 343 #endif
 344
 345 #if 0
 346 /* read a complete frame (header + data), but de-interleave fields
 347     into two separate buffers
 348    o upper_field[3] same as yuv[3] above, but for upper field
 349    o lower_field[3] same as yuv[3] above, but for lower field
 350 */
 351 int y4m_read_fields(int fd, y4m_stream_info_t *si, y4m_frame_info_t *fi,
 352                     unsigned char *upper_field[3],
 353                     unsigned char *lower_field[3]);
 354
 355 /* write a complete frame (header + data), but interleave fields
 356     from two separate buffers
 357    o upper_field[3] same as yuv[3] above, but for upper field
 358    o lower_field[3] same as yuv[3] above, but for lower field
 359 */
 360 int y4m_write_fields(int fd, y4m_stream_info_t *si, y4m_frame_info_t *fi,
 361                      unsigned char *upper_field[3],
 362                      unsigned char *lower_field[3]);
 363
 364 #endif
 365
 366 /************************************************************************
 367  *  miscellaneous functions
 368  ************************************************************************/
 369
 370 /* convenient dump of stream header info via mjpeg_log facility
 371  *  - each logged/printed line is prefixed by 'prefix'
 372  */
 373 void y4m_log_stream_info(const char *prefix, y4m_stream_info_t *i);
 374
 375 /* convert a Y4M_ERR_* error code into mildly explanatory string */
 376 const char *y4m_strerr(int err);
 377
 378 /* set 'allow_unknown_tag' flag for library...
 379     o yn = 0 :  unknown header tags will produce a parsing error
 380     o yn = 1 :  unknown header tags/values will produce a warning, but
 381                  are otherwise passed along via the xtags list
 382     o yn = -1:  don't change, just return current setting
 383
 384    return value:  previous setting of flag
 385 */
 386 int y4m_allow_unknown_tags(int yn);
 387
 388
 389 #ifdef __cplusplus
 390 }
 391 #endif
 392
 393 /************************************************************************
 394  ************************************************************************
 395
 396   Description of the (new!, forever?) YUV4MPEG2 stream format:
 397
 398   STREAM consists of
 399     o one '\n' terminated STREAM-HEADER
 400     o unlimited number of FRAMEs
 401
 402   FRAME consists of
 403     o one '\n' terminated FRAME-HEADER
 404     o "length" octets of planar YCrCb 4:2:0 image data
 405         (if frame is interlaced, then the two fields are interleaved)
 406
 407
 408   STREAM-HEADER consists of
 409      o string "YUV4MPEG2 "  (note the space after the '2')
 410      o unlimited number of ' ' separated TAGGED-FIELDs
 411      o '\n' line terminator
 412
 413   FRAME-HEADER consists of
 414      o string "FRAME "  (note the space after the 'E')
 415      o unlimited number of ' ' separated TAGGED-FIELDs
 416      o '\n' line terminator
 417
 418
 419   TAGGED-FIELD consists of
 420      o single ascii character tag
 421      o VALUE (which does not contain whitespace)
 422
 423   VALUE consists of
 424      o integer (base 10 ascii representation)
 425   or o RATIO
 426   or o single ascii character
 427   or o generic ascii string
 428
 429   RATIO consists of
 430      o numerator (integer)
 431      o ':' (a colon)
 432      o denominator (integer)
 433
 434
 435   The currently supported tags for the STREAM-HEADER:
 436      W - [integer] frame width, pixels, should be > 0
 437      H - [integer] frame height, pixels, should be > 0
 438      I - [char] interlacing:  p - progressive (none)
 439                             t - top-field-first
 440                             b - bottom-field-first
 441                             ? - unknown
 442      F - [ratio] frame-rate, 0:0 == unknown
 443      A - [ratio] sample (pixel) aspect ratio, 0:0 == unknown
 444      X - [character string] 'metadata' (unparsed, but passed around)
 445
 446   The currently supported tags for the FRAME-HEADER:
 447      X - character string 'metadata' (unparsed, but passed around)
 448
 449  ************************************************************************
 450  ************************************************************************/
 451
 452 #endif /* MPLAYER_YUV4MPEG_H */