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) 2004 Matthew J. Marjanovic <maddog@mir.com> 8 * 9 * 10 * This program is free software; you can redistribute it and/or 11 * modify it under the terms of the GNU General Public License 12 * as published by the Free Software Foundation; either version 2 13 * of the License, or (at your option) any later version. 14 * 15 * This program is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public License 21 * along with this program; if not, write to the Free Software 22 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 23 */ 24 25 #ifndef __YUV4MPEG_H__ 26 #define __YUV4MPEG_H__ 27 28 #include <stdlib.h> 29 #include <mjpeg_types.h> 30 #ifndef _WIN32 31 #include <unistd.h> 32 #endif 33 #include <mjpeg_logging.h> 34 35 36 /************************************************************************ 37 * error codes returned by y4m_* functions 38 ************************************************************************/ 39 #define Y4M_OK 0 40 #define Y4M_ERR_RANGE 1 /* argument or tag value out of range */ 41 #define Y4M_ERR_SYSTEM 2 /* failed system call, check errno */ 42 #define Y4M_ERR_HEADER 3 /* illegal/malformed header */ 43 #define Y4M_ERR_BADTAG 4 /* illegal tag character */ 44 #define Y4M_ERR_MAGIC 5 /* bad header magic */ 45 #define Y4M_ERR_EOF 6 /* end-of-file (clean) */ 46 #define Y4M_ERR_XXTAGS 7 /* too many xtags */ 47 #define Y4M_ERR_BADEOF 8 /* unexpected end-of-file */ 48 #define Y4M_ERR_FEATURE 9 /* stream requires features beyond allowed level */ 49 50 51 /* generic 'unknown' value for integer parameters (e.g. interlace, height) */ 52 #define Y4M_UNKNOWN -1 53 54 /************************************************************************ 55 * values for the "interlace" parameter [y4m_*_interlace()] 56 ************************************************************************/ 57 #define Y4M_ILACE_NONE 0 /* non-interlaced, progressive frame */ 58 #define Y4M_ILACE_TOP_FIRST 1 /* interlaced, top-field first */ 59 #define Y4M_ILACE_BOTTOM_FIRST 2 /* interlaced, bottom-field first */ 60 #define Y4M_ILACE_MIXED 3 /* mixed, "refer to frame header" */ 61 62 /************************************************************************ 63 * values for the "chroma" parameter [y4m_*_chroma()] 64 ************************************************************************/ 65 #define Y4M_CHROMA_420JPEG 0 /* 4:2:0, H/V centered, for JPEG/MPEG-1 */ 66 #define Y4M_CHROMA_420MPEG2 1 /* 4:2:0, H cosited, for MPEG-2 */ 67 #define Y4M_CHROMA_420PALDV 2 /* 4:2:0, alternating Cb/Cr, for PAL-DV */ 68 #define Y4M_CHROMA_444 3 /* 4:4:4, no subsampling, phew. */ 69 #define Y4M_CHROMA_422 4 /* 4:2:2, H cosited */ 70 #define Y4M_CHROMA_411 5 /* 4:1:1, H cosited */ 71 #define Y4M_CHROMA_MONO 6 /* luma plane only */ 72 #define Y4M_CHROMA_444ALPHA 7 /* 4:4:4 with an alpha channel */ 73 74 /************************************************************************ 75 * values for sampling parameters [y4m_*_spatial(), y4m_*_temporal()] 76 ************************************************************************/ 77 #define Y4M_SAMPLING_PROGRESSIVE 0 78 #define Y4M_SAMPLING_INTERLACED 1 79 80 /************************************************************************ 81 * values for "presentation" parameter [y4m_*_presentation()] 82 ************************************************************************/ 83 #define Y4M_PRESENT_TOP_FIRST 0 /* top-field-first */ 84 #define Y4M_PRESENT_TOP_FIRST_RPT 1 /* top-first, repeat top */ 85 #define Y4M_PRESENT_BOTTOM_FIRST 2 /* bottom-field-first */ 86 #define Y4M_PRESENT_BOTTOM_FIRST_RPT 3 /* bottom-first, repeat bottom */ 87 #define Y4M_PRESENT_PROG_SINGLE 4 /* single progressive frame */ 88 #define Y4M_PRESENT_PROG_DOUBLE 5 /* progressive frame, repeat once */ 89 #define Y4M_PRESENT_PROG_TRIPLE 6 /* progressive frame, repeat twice */ 90 91 #define Y4M_MAX_NUM_PLANES 4 92 93 /************************************************************************ 94 * 'ratio' datatype, for rational numbers 95 * (see 'ratio' functions down below) 96 ************************************************************************/ 97 typedef struct _y4m_ratio { 98 int n; /* numerator */ 99 int d; /* denominator */ 100 } y4m_ratio_t; 101 102 103 /************************************************************************ 104 * useful standard framerates (as ratios) 105 ************************************************************************/ 106 extern const y4m_ratio_t y4m_fps_UNKNOWN; 107 extern const y4m_ratio_t y4m_fps_NTSC_FILM; /* 24000/1001 film (in NTSC) */ 108 extern const y4m_ratio_t y4m_fps_FILM; /* 24fps film */ 109 extern const y4m_ratio_t y4m_fps_PAL; /* 25fps PAL */ 110 extern const y4m_ratio_t y4m_fps_NTSC; /* 30000/1001 NTSC */ 111 extern const y4m_ratio_t y4m_fps_30; /* 30fps */ 112 extern const y4m_ratio_t y4m_fps_PAL_FIELD; /* 50fps PAL field rate */ 113 extern const y4m_ratio_t y4m_fps_NTSC_FIELD; /* 60000/1001 NTSC field rate */ 114 extern const y4m_ratio_t y4m_fps_60; /* 60fps */ 115 116 /************************************************************************ 117 * useful standard sample (pixel) aspect ratios (W:H) 118 ************************************************************************/ 119 extern const y4m_ratio_t y4m_sar_UNKNOWN; 120 extern const y4m_ratio_t y4m_sar_SQUARE; /* square pixels */ 121 extern const y4m_ratio_t y4m_sar_NTSC_CCIR601; /* 525-line (NTSC) Rec.601 */ 122 extern const y4m_ratio_t y4m_sar_NTSC_16_9; /* 16:9 NTSC/Rec.601 */ 123 extern const y4m_ratio_t y4m_sar_NTSC_SVCD_4_3; /* NTSC SVCD 4:3 */ 124 extern const y4m_ratio_t y4m_sar_NTSC_SVCD_16_9;/* NTSC SVCD 16:9 */ 125 extern const y4m_ratio_t y4m_sar_PAL_CCIR601; /* 625-line (PAL) Rec.601 */ 126 extern const y4m_ratio_t y4m_sar_PAL_16_9; /* 16:9 PAL/Rec.601 */ 127 extern const y4m_ratio_t y4m_sar_PAL_SVCD_4_3; /* PAL SVCD 4:3 */ 128 extern const y4m_ratio_t y4m_sar_PAL_SVCD_16_9; /* PAL SVCD 16:9 */ 129 extern const y4m_ratio_t y4m_sar_SQR_ANA16_9; /* anamorphic 16:9 sampled */ 130 /* from 4:3 with square pixels */ 131 132 /************************************************************************ 133 * useful standard display aspect ratios (W:H) 134 ************************************************************************/ 135 extern const y4m_ratio_t y4m_dar_UNKNOWN; 136 extern const y4m_ratio_t y4m_dar_4_3; /* standard TV */ 137 extern const y4m_ratio_t y4m_dar_16_9; /* widescreen TV */ 138 extern const y4m_ratio_t y4m_dar_221_100; /* word-to-your-mother TV */ 139 140 141 #define Y4M_MAX_XTAGS 32 /* maximum number of xtags in list */ 142 #define Y4M_MAX_XTAG_SIZE 32 /* max length of an xtag (including 'X') */ 143 144 typedef struct _y4m_xtag_list y4m_xtag_list_t; 145 typedef struct _y4m_stream_info y4m_stream_info_t; 146 typedef struct _y4m_frame_info y4m_frame_info_t; 147 148 149 #ifdef __cplusplus 150 #define BEGIN_CDECLS extern "C" { 151 #define END_CDECLS } 152 #else 153 #define BEGIN_CDECLS 154 #define END_CDECLS 155 #endif 156 157 BEGIN_CDECLS 158 159 /************************************************************************ 160 * 'ratio' functions 161 ************************************************************************/ 162 163 /* 'normalize' a ratio (remove common factors) */ 164 void y4m_ratio_reduce(y4m_ratio_t *r); 165 166 /* parse "nnn:ddd" into a ratio (returns Y4M_OK or Y4M_ERR_RANGE) */ 167 int y4m_parse_ratio(y4m_ratio_t *r, const char *s); 168 169 /* quick test of two ratios for equality (i.e. identical components) */ 170 #define Y4M_RATIO_EQL(a,b) ( ((a).n == (b).n) && ((a).d == (b).d) ) 171 172 /* quick conversion of a ratio to a double (no divide-by-zero check!) */ 173 #define Y4M_RATIO_DBL(r) ((double)(r).n / (double)(r).d) 174 175 /************************************************************************* 176 * 177 * Guess the true SAR (sample aspect ratio) from a list of commonly 178 * encountered values, given the "suggested" display aspect ratio (DAR), 179 * and the true frame width and height. 180 * 181 * Returns y4m_sar_UNKNOWN if no match is found. 182 * 183 *************************************************************************/ 184 y4m_ratio_t y4m_guess_sar(int width, int height, y4m_ratio_t dar); 185 186 187 /************************************************************************* 188 * 189 * Chroma Subsampling Mode information 190 * 191 * x_ratio, y_ratio - subsampling of chroma planes 192 * x_offset, y_offset - offset of chroma sample grid, 193 * relative to luma (0,0) sample 194 * 195 *************************************************************************/ 196 197 y4m_ratio_t y4m_chroma_ss_x_ratio(int chroma_mode); 198 y4m_ratio_t y4m_chroma_ss_y_ratio(int chroma_mode); 199 #if 0 200 y4m_ratio_t y4m_chroma_ss_x_offset(int chroma_mode, int field, int plane); 201 y4m_ratio_t y4m_chroma_ss_y_offset(int chroma_mode, int field, int plane); 202 #endif 203 204 /* Given a string containing a (case-insensitive) chroma-tag keyword, 205 return appropriate chroma mode (or Y4M_UNKNOWN) */ 206 int y4m_chroma_parse_keyword(const char *s); 207 208 /* Given a Y4M_CHROMA_* mode, return appropriate chroma-tag keyword, 209 or NULL if there is none. */ 210 const char *y4m_chroma_keyword(int chroma_mode); 211 212 /* Given a Y4M_CHROMA_* mode, return appropriate chroma mode description, 213 or NULL if there is none. */ 214 const char *y4m_chroma_description(int chroma_mode); 215 216 217 218 /************************************************************************ 219 * 'xtag' functions 220 * 221 * o Before using an xtag_list (but after the structure/memory has been 222 * allocated), you must initialize it via y4m_init_xtag_list(). 223 * o After using an xtag_list (but before the structure is released), 224 * call y4m_fini_xtag_list() to free internal memory. 225 * 226 ************************************************************************/ 227 228 /* initialize an xtag_list structure */ 229 void y4m_init_xtag_list(y4m_xtag_list_t *xtags); 230 231 /* finalize an xtag_list structure */ 232 void y4m_fini_xtag_list(y4m_xtag_list_t *xtags); 233 234 /* make one xtag_list into a copy of another */ 235 void y4m_copy_xtag_list(y4m_xtag_list_t *dest, const y4m_xtag_list_t *src); 236 237 /* return number of tags in an xtag_list */ 238 int y4m_xtag_count(const y4m_xtag_list_t *xtags); 239 240 /* access n'th tag in an xtag_list */ 241 const char *y4m_xtag_get(const y4m_xtag_list_t *xtags, int n); 242 243 /* append a new tag to an xtag_list 244 returns: Y4M_OK - success 245 Y4M_ERR_XXTAGS - list is already full */ 246 int y4m_xtag_add(y4m_xtag_list_t *xtags, const char *tag); 247 248 /* remove a tag from an xtag_list 249 returns: Y4M_OK - success 250 Y4M_ERR_RANGE - n is out of range */ 251 int y4m_xtag_remove(y4m_xtag_list_t *xtags, int n); 252 253 /* remove all tags from an xtag_list 254 returns: Y4M_OK - success */ 255 int y4m_xtag_clearlist(y4m_xtag_list_t *xtags); 256 257 /* append copies of tags from src list to dest list 258 returns: Y4M_OK - success 259 Y4M_ERR_XXTAGS - operation would overfill dest list */ 260 int y4m_xtag_addlist(y4m_xtag_list_t *dest, const y4m_xtag_list_t *src); 261 262 263 264 /************************************************************************ 265 * '*_info' functions 266 * 267 * o Before using a *_info structure (but after the structure/memory has 268 * been allocated), you must initialize it via y4m_init_*_info(). 269 * o After using a *_info structure (but before the structure is released), 270 * call y4m_fini_*_info() to free internal memory. 271 * o Use the 'set' and 'get' accessors to modify or access the fields in 272 * the structures; don't touch the structure directly. (Ok, so there 273 * is no really convenient C syntax to prevent you from doing this, 274 * but we are all responsible programmers here, so just don't do it!) 275 * 276 ************************************************************************/ 277 278 /* initialize a stream_info structure */ 279 void y4m_init_stream_info(y4m_stream_info_t *i); 280 281 /* finalize a stream_info structure */ 282 void y4m_fini_stream_info(y4m_stream_info_t *i); 283 284 /* reset stream_info back to default/unknown values */ 285 void y4m_clear_stream_info(y4m_stream_info_t *info); 286 287 /* make one stream_info into a copy of another */ 288 void y4m_copy_stream_info(y4m_stream_info_t *dest, 289 const y4m_stream_info_t *src); 290 291 /* access or set stream_info fields */ 292 /* level 0 */ 293 int y4m_si_get_width(const y4m_stream_info_t *si); 294 int y4m_si_get_height(const y4m_stream_info_t *si); 295 int y4m_si_get_interlace(const y4m_stream_info_t *si); 296 y4m_ratio_t y4m_si_get_framerate(const y4m_stream_info_t *si); 297 y4m_ratio_t y4m_si_get_sampleaspect(const y4m_stream_info_t *si); 298 void y4m_si_set_width(y4m_stream_info_t *si, int width); 299 void y4m_si_set_height(y4m_stream_info_t *si, int height); 300 void y4m_si_set_interlace(y4m_stream_info_t *si, int interlace); 301 void y4m_si_set_framerate(y4m_stream_info_t *si, y4m_ratio_t framerate); 302 void y4m_si_set_sampleaspect(y4m_stream_info_t *si, y4m_ratio_t sar); 303 /* level 1 */ 304 void y4m_si_set_chroma(y4m_stream_info_t *si, int chroma_mode); 305 int y4m_si_get_chroma(const y4m_stream_info_t *si); 306 307 /* derived quantities (no setter) */ 308 /* level 0 */ 309 int y4m_si_get_framelength(const y4m_stream_info_t *si); 310 /* level 1 */ 311 int y4m_si_get_plane_count(const y4m_stream_info_t *si); 312 int y4m_si_get_plane_width(const y4m_stream_info_t *si, int plane); 313 int y4m_si_get_plane_height(const y4m_stream_info_t *si, int plane); 314 int y4m_si_get_plane_length(const y4m_stream_info_t *si, int plane); 315 316 317 /* access stream_info xtag_list */ 318 y4m_xtag_list_t *y4m_si_xtags(y4m_stream_info_t *si); 319 320 321 /* initialize a frame_info structure */ 322 void y4m_init_frame_info(y4m_frame_info_t *i); 323 324 /* finalize a frame_info structure */ 325 void y4m_fini_frame_info(y4m_frame_info_t *i); 326 327 /* reset frame_info back to default/unknown values */ 328 void y4m_clear_frame_info(y4m_frame_info_t *info); 329 330 /* make one frame_info into a copy of another */ 331 void y4m_copy_frame_info(y4m_frame_info_t *dest, 332 const y4m_frame_info_t *src); 333 334 335 /* access or set frame_info fields (level 1) */ 336 int y4m_fi_get_presentation(const y4m_frame_info_t *fi); 337 int y4m_fi_get_temporal(const y4m_frame_info_t *fi); 338 int y4m_fi_get_spatial(const y4m_frame_info_t *fi); 339 340 void y4m_fi_set_presentation(y4m_frame_info_t *fi, int pres); 341 void y4m_fi_set_temporal(y4m_frame_info_t *fi, int sampling); 342 void y4m_fi_set_spatial(y4m_frame_info_t *fi, int sampling); 343 344 345 /* access frame_info xtag_list */ 346 y4m_xtag_list_t *y4m_fi_xtags(y4m_frame_info_t *fi); 347 348 349 /************************************************************************ 350 * blocking read and write functions 351 * 352 * o guaranteed to transfer entire payload (or fail) 353 * o return values: 354 * 0 (zero) complete success 355 * -(# of remaining bytes) error (and errno left set) 356 * +(# of remaining bytes) EOF (for y4m_read only) 357 * 358 ************************************************************************/ 359 360 /* read len bytes from fd into buf */ 361 ssize_t y4m_read(int fd, void *buf, size_t len); 362 363 /* write len bytes from fd into buf */ 364 ssize_t y4m_write(int fd, const void *buf, size_t len); 365 366 /************************************************************************ 367 * callback based read and write 368 * 369 * The structures y4m_cb_reader_t and y4m_cb_writer_t must be 370 * set up by the caller before and of the *_read_*_cb() or 371 * *_write_*_cb() functions are called. Te return values of 372 * the read() and write() members have the same meaning as for 373 * y4m_read() and y4m_write() 374 * 375 ************************************************************************/ 376 377 typedef struct y4m_cb_reader_s 378 { 379 void * data; 380 ssize_t (*read)(void * data, void *buf, size_t len); 381 } y4m_cb_reader_t; 382 383 typedef struct y4m_cb_writer_s 384 { 385 void * data; 386 ssize_t (*write)(void * data, const void *buf, size_t len); 387 } y4m_cb_writer_t; 388 389 /* read len bytes from fd into buf */ 390 ssize_t y4m_read_cb(y4m_cb_reader_t * fd, void *buf, size_t len); 391 392 /* write len bytes from fd into buf */ 393 ssize_t y4m_write_cb(y4m_cb_writer_t * fd, const void *buf, size_t len); 394 395 396 /************************************************************************ 397 * stream header processing functions 398 * 399 * o return values: 400 * Y4M_OK - success 401 * Y4M_ERR_* - error (see y4m_strerr() for descriptions) 402 * 403 ************************************************************************/ 404 405 /* parse a string of stream header tags */ 406 int y4m_parse_stream_tags(char *s, y4m_stream_info_t *i); 407 408 /* read a stream header from file descriptor fd 409 (the current contents of stream_info are erased first) */ 410 int y4m_read_stream_header(int fd, y4m_stream_info_t *i); 411 412 /* read a stream header with a callback reader 413 (the current contents of stream_info are erased first) */ 414 int y4m_read_stream_header_cb(y4m_cb_reader_t * fd, y4m_stream_info_t *i); 415 416 /* write a stream header to file descriptor fd */ 417 int y4m_write_stream_header(int fd, const y4m_stream_info_t *i); 418 419 /* write a stream header with a callback writer */ 420 int y4m_write_stream_header_cb(y4m_cb_writer_t * fd, const y4m_stream_info_t *i); 421 422 423 /************************************************************************ 424 * frame processing functions 425 * 426 * o return values: 427 * Y4M_OK - success 428 * Y4M_ERR_* - error (see y4m_strerr() for descriptions) 429 * 430 ************************************************************************/ 431 432 /* write a frame header to file descriptor fd */ 433 int y4m_write_frame_header(int fd, 434 const y4m_stream_info_t *si, 435 const y4m_frame_info_t *fi); 436 437 /* write a frame header with a callback writer fd */ 438 int y4m_write_frame_header_cb(y4m_cb_writer_t * fd, 439 const y4m_stream_info_t *si, 440 const y4m_frame_info_t *fi); 441 442 /* write a complete frame (header + data) to file descriptor fd 443 o planes[] points to 1-4 buffers, one each for image plane */ 444 int y4m_write_frame(int fd, const y4m_stream_info_t *si, 445 const y4m_frame_info_t *fi, uint8_t * const *planes); 446 447 /* write a complete frame (header + data) with a callback writer fd 448 o planes[] points to 1-4 buffers, one each for image plane */ 449 int y4m_write_frame_cb(y4m_cb_writer_t * fd, const y4m_stream_info_t *si, 450 const y4m_frame_info_t *fi, uint8_t * const *planes); 451 452 /* write a complete frame (header + data), to file descriptor fd 453 but interleave fields from two separate buffers 454 o upper_field[] same as planes[] above, but for upper field only 455 o lower_field[] same as planes[] above, but for lower field only 456 */ 457 int y4m_write_fields(int fd, const y4m_stream_info_t *si, 458 const y4m_frame_info_t *fi, 459 uint8_t * const *upper_field, 460 uint8_t * const *lower_field); 461 462 /* write a complete frame (header + data), with a callback writer fd 463 but interleave fields from two separate buffers 464 o upper_field[] same as planes[] above, but for upper field only 465 o lower_field[] same as planes[] above, but for lower field only 466 */ 467 int y4m_write_fields_cb(y4m_cb_writer_t * fd, const y4m_stream_info_t *si, 468 const y4m_frame_info_t *fi, 469 uint8_t * const *upper_field, 470 uint8_t * const *lower_field); 471 472 /* read a frame header from file descriptor fd 473 (the current contents of frame_info are erased first) */ 474 int y4m_read_frame_header(int fd, 475 const y4m_stream_info_t *si, 476 y4m_frame_info_t *fi); 477 478 /* read a frame header with callback reader fd 479 (the current contents of frame_info are erased first) */ 480 int y4m_read_frame_header_cb(y4m_cb_reader_t * fd, 481 const y4m_stream_info_t *si, 482 y4m_frame_info_t *fi); 483 484 /* read frame data from file descriptor fd 485 [to be called after y4m_read_frame_header()] 486 o planes[] points to 1-4 buffers, one each for image plane */ 487 int y4m_read_frame_data(int fd, const y4m_stream_info_t *si, 488 y4m_frame_info_t *fi, uint8_t * const *planes); 489 490 /* read frame data with callback reader fd 491 [to be called after y4m_read_frame_header_cb()] 492 o planes[] points to 1-4 buffers, one each for image plane */ 493 int y4m_read_frame_data_cb(y4m_cb_reader_t * fd, const y4m_stream_info_t *si, 494 y4m_frame_info_t *fi, uint8_t * const *planes); 495 496 /* read frame data from file descriptor fd, 497 but de-interleave fields into two separate buffers 498 [to be called after y4m_read_frame_header()] 499 o upper_field[] same as planes[] above, but for upper field only 500 o lower_field[] same as planes[] above, but for lower field only 501 */ 502 int y4m_read_fields_data(int fd, const y4m_stream_info_t *si, 503 y4m_frame_info_t *fi, 504 uint8_t * const *upper_field, 505 uint8_t * const *lower_field); 506 507 /* read frame data with callback reader fd, 508 but de-interleave fields into two separate buffers 509 [to be called after y4m_read_frame_header_cb()] 510 o upper_field[] same as planes[] above, but for upper field only 511 o lower_field[] same as planes[] above, but for lower field only 512 */ 513 int y4m_read_fields_data_cb(y4m_cb_reader_t * fd, 514 const y4m_stream_info_t *si, 515 y4m_frame_info_t *fi, 516 uint8_t * const *upper_field, 517 uint8_t * const *lower_field); 518 519 /* read a complete frame (header + data) from file descriptor fd, 520 o planes[] points to 1-4 buffers, one each for image plane */ 521 int y4m_read_frame(int fd, const y4m_stream_info_t *si, 522 y4m_frame_info_t *fi, uint8_t * const *planes); 523 524 /* read a complete frame (header + data) from callback reader fd, 525 o planes[] points to 1-4 buffers, one each for image plane */ 526 int y4m_read_frame_cb(y4m_cb_reader_t * fd, const y4m_stream_info_t *si, 527 y4m_frame_info_t *fi, uint8_t * const *planes); 528 529 /* read a complete frame (header + data) from file descriptor fd, 530 but de-interleave fields into two separate buffers 531 o upper_field[] same as planes[] above, but for upper field only 532 o lower_field[] same as planes[] above, but for lower field only 533 */ 534 int y4m_read_fields(int fd, const y4m_stream_info_t *si, 535 y4m_frame_info_t *fi, 536 uint8_t * const *upper_field, 537 uint8_t * const *lower_field); 538 539 /* read a complete frame (header + data) from callback_reader fd, 540 but de-interleave fields into two separate buffers 541 o upper_field[] same as planes[] above, but for upper field only 542 o lower_field[] same as planes[] above, but for lower field only 543 */ 544 int y4m_read_fields_cb(y4m_cb_reader_t * fd, const y4m_stream_info_t *si, 545 y4m_frame_info_t *fi, 546 uint8_t * const *upper_field, 547 uint8_t * const *lower_field); 548 549 /************************************************************************ 550 * miscellaneous functions 551 ************************************************************************/ 552 553 /* convenient dump of stream header info via mjpeg_log facility 554 * - each logged/printed line is prefixed by 'prefix' 555 */ 556 void y4m_log_stream_info(log_level_t level, const char *prefix, 557 const y4m_stream_info_t *i); 558 559 /* convert a Y4M_ERR_* error code into mildly explanatory string */ 560 const char *y4m_strerr(int err); 561 562 /* set 'allow_unknown_tag' flag for library... 563 o yn = 0 : unknown header tags will produce a parsing error 564 o yn = 1 : unknown header tags/values will produce a warning, but 565 are otherwise passed along via the xtags list 566 o yn = -1: don't change, just return current setting 567 568 return value: previous setting of flag 569 */ 570 int y4m_allow_unknown_tags(int yn); 571 572 573 /* set level of "accepted extensions" for the library... 574 o level = 0: default - conform to original YUV4MPEG2 spec; yield errors 575 when reading or writing a stream which exceeds it. 576 o level = 1: allow reading/writing streams which contain non-420jpeg 577 chroma and/or mixed-mode interlacing 578 o level = -1: don't change, just return current setting 579 580 return value: previous setting of level 581 */ 582 int y4m_accept_extensions(int level); 583 584 585 END_CDECLS 586 587 588 /************************************************************************ 589 ************************************************************************ 590 591 Description of the (new!, forever?) YUV4MPEG2 stream format: 592 593 STREAM consists of 594 o one '\n' terminated STREAM-HEADER 595 o unlimited number of FRAMEs 596 597 FRAME consists of 598 o one '\n' terminated FRAME-HEADER 599 o "length" octets of planar YCrCb 4:2:0 image data 600 (if frame is interlaced, then the two fields are interleaved) 601 602 603 STREAM-HEADER consists of 604 o string "YUV4MPEG2" 605 o unlimited number TAGGED-FIELDs, each preceded by ' ' separator 606 o '\n' line terminator 607 608 FRAME-HEADER consists of 609 o string "FRAME" 610 o unlimited number of TAGGED-FIELDs, each preceded by ' ' separator 611 o '\n' line terminator 612 613 614 TAGGED-FIELD consists of 615 o single ascii character tag 616 o VALUE (which does not contain whitespace) 617 618 VALUE consists of 619 o integer (base 10 ascii representation) 620 or o RATIO 621 or o single ascii character 622 or o non-whitespace ascii string 623 624 RATIO consists of 625 o numerator (integer) 626 o ':' (a colon) 627 o denominator (integer) 628 629 630 The currently supported tags for the STREAM-HEADER: 631 W - [integer] frame width, pixels, should be > 0 632 H - [integer] frame height, pixels, should be > 0 633 C - [string] chroma-subsampling/data format 634 420jpeg (default) 635 420mpeg2 636 420paldv 637 411 638 422 639 444 - non-subsampled Y'CbCr 640 444alpha - Y'CbCr with alpha channel (with Y' black/white point) 641 mono - Y' plane only 642 I - [char] interlacing: p - progressive (none) 643 t - top-field-first 644 b - bottom-field-first 645 m - mixed -- see 'I' tag in frame header 646 ? - unknown 647 F - [ratio] frame-rate, 0:0 == unknown 648 A - [ratio] sample (pixel) aspect ratio, 0:0 == unknown 649 X - [character string] 'metadata' (unparsed, but passed around) 650 651 The currently supported tags for the FRAME-HEADER: 652 Ixyz - framing/sampling (required if-and-only-if stream is "Im") 653 x: t - top-field-first 654 T - top-field-first and repeat 655 b - bottom-field-first 656 B - bottom-field-first and repeat 657 1 - single progressive frame 658 2 - double progressive frame (repeat) 659 3 - triple progressive frame (repeat twice) 660 661 y: p - progressive: fields sampled at same time 662 i - interlaced: fields sampled at different times 663 664 z: p - progressive: subsampling over whole frame 665 i - interlaced: each field subsampled independently 666 ? - unknown (allowed only for non-4:2:0 subsampling) 667 668 X - character string 'metadata' (unparsed, but passed around) 669 670 ************************************************************************ 671 ************************************************************************/ 672 673 674 /* 675 676 THAT'S ALL FOLKS! 677 678 Thank you for reading the source code. We hope you have thoroughly 679 enjoyed the experience. 680 681 */ 682 683 684 685 686 687 #ifdef INTERNAL_Y4M_LIBCODE_STUFF_QPX 688 #define Y4MPRIVATIZE(identifier) identifier 689 #else 690 #define Y4MPRIVATIZE(identifier) PRIVATE##identifier 691 #endif 692 693 /* 694 * Actual structure definitions of structures which you shouldn't touch. 695 * 696 */ 697 698 /************************************************************************ 699 * 'xtag_list' --- list of unparsed and/or meta/X header tags 700 * 701 * Do not touch this structure directly! 702 * 703 * Use the y4m_xtag_*() functions (see below). 704 * You must initialize/finalize this structure before/after use. 705 ************************************************************************/ 706 struct _y4m_xtag_list { 707 int Y4MPRIVATIZE(count); 708 char *Y4MPRIVATIZE(tags)[Y4M_MAX_XTAGS]; 709 }; 710 711 712 /************************************************************************ 713 * 'stream_info' --- stream header information 714 * 715 * Do not touch this structure directly! 716 * 717 * Use the y4m_si_*() functions (see below). 718 * You must initialize/finalize this structure before/after use. 719 ************************************************************************/ 720 struct _y4m_stream_info { 721 /* values from header/setters */ 722 int Y4MPRIVATIZE(width); 723 int Y4MPRIVATIZE(height); 724 int Y4MPRIVATIZE(interlace); /* see Y4M_ILACE_* definitions */ 725 y4m_ratio_t Y4MPRIVATIZE(framerate); /* see Y4M_FPS_* definitions */ 726 y4m_ratio_t Y4MPRIVATIZE(sampleaspect); /* see Y4M_SAR_* definitions */ 727 int Y4MPRIVATIZE(chroma); /* see Y4M_CHROMA_* definitions */ 728 729 /* mystical X tags */ 730 y4m_xtag_list_t Y4MPRIVATIZE(x_tags); 731 }; 732 733 734 /************************************************************************ 735 * 'frame_info' --- frame header information 736 * 737 * Do not touch this structure directly! 738 * 739 * Use the y4m_fi_*() functions (see below). 740 * You must initialize/finalize this structure before/after use. 741 ************************************************************************/ 742 743 struct _y4m_frame_info { 744 int Y4MPRIVATIZE(spatial); /* see Y4M_SAMPLING_* definitions */ 745 int Y4MPRIVATIZE(temporal); /* see Y4M_SAMPLING_* definitions */ 746 int Y4MPRIVATIZE(presentation); /* see Y4M_PRESENT_* definitions */ 747 /* mystical X tags */ 748 y4m_xtag_list_t Y4MPRIVATIZE(x_tags); 749 }; 750 751 752 #undef Y4MPRIVATIZE 753 754 755 #endif /* __YUV4MPEG_H__ */ 756 757 758