mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-24 10:41:04 +00:00
63294c0655
Original commit message from CVS: Moved from gst-plugins/ext/mplex/. See that directory for older changelogs.
473 lines
18 KiB
C
473 lines
18 KiB
C
/*
|
|
* yuv4mpeg.h: Functions for reading and writing "new" YUV4MPEG2 streams.
|
|
*
|
|
* Stream format is described at the end of this file.
|
|
*
|
|
*
|
|
* Copyright (C) 2001 Matthew J. Marjanovic <maddog@mir.com>
|
|
*
|
|
*
|
|
* 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>
|
|
#include <unistd.h>
|
|
#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 */
|
|
|
|
|
|
/* generic 'unknown' value for integer parameters (e.g. interlace, height) */
|
|
#define Y4M_UNKNOWN -1
|
|
|
|
|
|
|
|
/************************************************************************
|
|
* '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 */
|
|
|
|
|
|
/************************************************************************
|
|
* '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.
|
|
************************************************************************/
|
|
#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 {
|
|
int count;
|
|
char *tags[Y4M_MAX_XTAGS];
|
|
} y4m_xtag_list_t;
|
|
|
|
|
|
|
|
/************************************************************************
|
|
* '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.
|
|
************************************************************************/
|
|
typedef struct _y4m_stream_info {
|
|
/* values from header */
|
|
int width;
|
|
int height;
|
|
int interlace; /* see Y4M_ILACE_* definitions below */
|
|
y4m_ratio_t framerate; /* frames-per-second; 0:0 == unknown */
|
|
y4m_ratio_t sampleaspect; /* pixel width/height; 0:0 == unknown */
|
|
/* computed/derivative values */
|
|
int framelength; /* bytes of data per frame (not including header) */
|
|
/* mystical X tags */
|
|
y4m_xtag_list_t x_tags;
|
|
} y4m_stream_info_t;
|
|
|
|
/* possible options for the interlace parameter */
|
|
#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 */
|
|
|
|
|
|
/************************************************************************
|
|
* '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.
|
|
************************************************************************/
|
|
typedef struct _y4m_frame_info {
|
|
/* mystical X tags */
|
|
y4m_xtag_list_t x_tags;
|
|
} y4m_frame_info_t;
|
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#else
|
|
#endif
|
|
|
|
|
|
/************************************************************************
|
|
* '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);
|
|
|
|
|
|
|
|
/************************************************************************
|
|
* '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);
|
|
|
|
/* 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 */
|
|
void y4m_si_set_width(y4m_stream_info_t *si, int width);
|
|
int y4m_si_get_width(const y4m_stream_info_t *si);
|
|
void y4m_si_set_height(y4m_stream_info_t *si, int height);
|
|
int y4m_si_get_height(const y4m_stream_info_t *si);
|
|
void y4m_si_set_interlace(y4m_stream_info_t *si, int interlace);
|
|
int y4m_si_get_interlace(const y4m_stream_info_t *si);
|
|
void y4m_si_set_framerate(y4m_stream_info_t *si, y4m_ratio_t framerate);
|
|
y4m_ratio_t y4m_si_get_framerate(const y4m_stream_info_t *si);
|
|
void y4m_si_set_sampleaspect(y4m_stream_info_t *si, y4m_ratio_t sar);
|
|
y4m_ratio_t y4m_si_get_sampleaspect(const y4m_stream_info_t *si);
|
|
int y4m_si_get_framelength(const y4m_stream_info_t *si);
|
|
|
|
/* 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);
|
|
|
|
/* 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);
|
|
|
|
/* 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 */
|
|
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)
|
|
*
|
|
************************************************************************/
|
|
|
|
/* read a frame header from file descriptor fd */
|
|
int y4m_read_frame_header(int fd, y4m_frame_info_t *i);
|
|
|
|
/* write a frame header to file descriptor fd */
|
|
int y4m_write_frame_header(int fd, const y4m_frame_info_t *i);
|
|
|
|
/* read a complete frame (header + data)
|
|
o yuv[3] points to three buffers, one each for Y, U, V planes */
|
|
int y4m_read_frame(int fd, const y4m_stream_info_t *si,
|
|
y4m_frame_info_t *fi, uint8_t * const yuv[3]);
|
|
|
|
/* write a complete frame (header + data)
|
|
o yuv[3] points to three buffers, one each for Y, U, V planes */
|
|
int y4m_write_frame(int fd, const y4m_stream_info_t *si,
|
|
const y4m_frame_info_t *fi, uint8_t * const yuv[3]);
|
|
|
|
|
|
/* read a complete frame (header + data), but de-interleave fields
|
|
into two separate buffers
|
|
o upper_field[3] same as yuv[3] above, but for upper field
|
|
o lower_field[3] same as yuv[3] above, but for lower field
|
|
*/
|
|
int y4m_read_fields(int fd, const y4m_stream_info_t *si,
|
|
y4m_frame_info_t *fi,
|
|
uint8_t * const upper_field[3],
|
|
uint8_t * const lower_field[3]);
|
|
|
|
/* write a complete frame (header + data), but interleave fields
|
|
from two separate buffers
|
|
o upper_field[3] same as yuv[3] above, but for upper field
|
|
o lower_field[3] same as yuv[3] above, but for lower field
|
|
*/
|
|
int y4m_write_fields(int fd, const y4m_stream_info_t *si,
|
|
const y4m_frame_info_t *fi,
|
|
uint8_t * const upper_field[3],
|
|
uint8_t * const lower_field[3]);
|
|
|
|
|
|
|
|
/************************************************************************
|
|
* 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);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
/************************************************************************
|
|
************************************************************************
|
|
|
|
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 " (note the space after the '2')
|
|
o unlimited number of ' ' separated TAGGED-FIELDs
|
|
o '\n' line terminator
|
|
|
|
FRAME-HEADER consists of
|
|
o string "FRAME " (note the space after the 'E')
|
|
o unlimited number of ' ' separated TAGGED-FIELDs
|
|
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 generic 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
|
|
I - [char] interlacing: p - progressive (none)
|
|
t - top-field-first
|
|
b - bottom-field-first
|
|
? - 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:
|
|
X - character string 'metadata' (unparsed, but passed around)
|
|
|
|
************************************************************************
|
|
************************************************************************/
|
|
|
|
#endif /* __YUV4MPEG_H__ */
|
|
|
|
|