#ifndef _VIDFILE_H_b7f81f7e_
#define _VIDFILE_H_b7f81f7e_

/*
 * A file is defined as an octet sequence.  It contains a header
 *  followed by frames.  All multi-octet values are given in network
 *  byte order (ie, MSB first).  The header consists of:
 *
 *	- 16 octets of magic number.  These identify the file as
 *	   instance of this format.  They are, in hex,
 *		56 39 02 59 7d 7d 00 98 88 16 a2 bb 3c 74 5a 6e
 *
 *	- Two octets, holding a value one less than the width (so that
 *	file values 0..65535 correspond to frame sizes 1..65536).
 *
 *	- Two octets, holding a value one less than the height (so that
 *	file values 0..65535 correspond to frame sizes 1..65536).
 *
 *	- One octet of length L, then L octets holding an octet string
 *	   identifying the video data format (see below).
 *
 *	- Zero or more feature blocks, each of which consists of
 *		- One octet of length L, then L bytes holding an octet
 *		   string identifying the feature.
 *		- Two octets of hint.  These can be ignored by programs
 *		   that understand this feature; the rest of this
 *		   description is addressed to programs that don't.
 *		   The first octet contains two flag bits:
 *			0x01	Essential.  If this bit is set, it's
 *				  not worth even trying to make sense
 *				  of the data; such attempts are
 *				  probably doomed to failure.
 *			0x02	Skip.  If this bit is set, take the
 *				  second octet's value, N, and compute
 *				  1<<N.  Then, ignore that many octets
 *				  at the beginning of each frame's
 *				  data; the frames should then make
 *				  sense.
 *			0xfc	MBZ
 *		- Four octets holding a length N, then N octets of
 *		   feature-specific data.
 *
 *	   When multiple features prepend data to frames, data they
 *	   prepend always appears in the same order in each frame (or
 *	   each applicable frame) as the information blocks appear in
 *	   the file.
 *
 *	- A 0x00 octet (which could be viewed as a zero-length feature
 *	   name, but without the usual feature-specific data following
 *	   it).
 *
 * The defined video data format strings (not including their length
 *  octets) are:
 *
 *	52 47 42 38 38 38 20 52 47 42
 *	(ASCII "RGB888 RGB")
 *		Each frame is a stream of pixels, in the usual
 *		fourth-quadrant order; each pixel is represented by
 *		three octets, giving the R, G, and B values for that
 *		pixel in that order.
 *
 *	59 27 43 62 43 72 34 32 32 20 59 27 43 62 59 27 43 72 20 30 2d 32 35 35
 *	(ASCII "Y'CbCr422 Y'CbY'Cr 0-255")
 *		It is an error to use this if width is odd.  Each frame
 *		is broken up into pairs of horizontally adjacent
 *		pixels, each pair having X coordinates 2k and 2k+1 for
 *		some k.  Then, these are represented as Y'CbCr values
 *		with chroma decimated by a horizontal factor of two
 *		(ie, 4:2:2 style, as suggested by the format string),
 *		giving two luma samples, one Cb sample, and one Cr
 *		sample.  These are then stored as four octets: first
 *		the first pixel's luma, then the Cb, then the other
 *		pixel's luma, then the Cr.  These are then streamed in
 *		the usual fourth-quadrant order to give the frame's
 *		representation.  Y', Cb, and Cr may range over the full
 *		0-255 range; there is no headroom or footroom.  Kr is
 *		0.299 and Kb is 0.114.
 *
 *	54 68 65 6f 72 61
 *	(ASCII "Theora")
 *		Each `frame' is a Theora data packet with a little
 *		additional framing information.  Specifically, each
 *		frame consists of 21 octets of header information:
 *
 *		- Four octets holding the octet count of the data
 *		- One octet of flag bits:
 *			- 0x01: BOS
 *			- 0x02: EOS
 *		- Eight octets holding the granule position
 *		- Eight octets holding the packet number
 *
 *		followed by as many octets as the header calls for.
 *
 *		On read, this uses the VFF_CHUNKED interface, with
 *		additional args to the header callback
 *			unsigned int flags;
 *			unsigned long long int granulepos;
 *			unsigned long long int packetno;
 *		flags are the flag octet from above, extended to
 *		unsigned int; granulepos and packetno are the other two
 *		pieces of header data.  There are no additional args to
 *		the chunk callback.
 *
 *		On write, a file opened with this format requires four
 *		additional args to write_vidfile_frame, before any
 *		features' arguments.  They are:
 *			unsigned int length;
 *			unsigned int flags;
 *			unsigned long long int granulepos;
 *			unsigned long long int packetno;
 *		length is the total frame length, the amount of data
 *		pointed to by framedata.  flags, granulepos, and
 *		packetno are as above for the read case.
 *
 *		The size passed on open is the frame size and thus
 *		width and height must be multiples of 16.
 *
 * Feature blocks defined:
 *
 *	74 69 6d 65 73 74 61 6d 70
 *	(ASCII "timestamp")
 *		Timestamps are included.  This prepends timestamps to
 *		some/all of the frames in the file.  The
 *		feature-specific data gives details.
 *
 *		The only currently defined form the feature-specific
 *		data may take is the four-octet block 75 73 65 63
 *		(ASCII "usec"), which indicates that each frame has 8
 *		octets of prepended data, giving the frame's timing in
 *		microseconds relative to an unspecified encoder-chosen
 *		base value.  When using this format, the block will
 *		normally have hint octets 0x02 0x03, but this is not
 *		required.
 *
 *		It is an error for this feature to appear more than
 *		once.
 */

/*
 * Video formats and the format strings they correspnod to (see above).
 */
typedef enum {
	  VF_FMT_RGB888_RGB = 1,	/* RGB888 RGB */
	  VF_FMT_YCbCr422_YCbYCr_0_255,	/* Y'CbCr422 Y'CbY'Cr 0-255 */
	  VF_FMT_THEORA,		/* Theora */
	  } VF_VIDFMT;

/*
 * Feature flag bits.
 */

/*
 * Timestamps are included.  This corresponds to the "timestamp"
 *  feature in the file format, with format "usec".
 *
 * No additional arguments on open-for-write.
 *
 * No additional arguments to the feature callback on open-for-read.
 *
 * One additional argument on frame write, that being an unsigned long
 *  long int giving the timestamp.
 *
 * One additional argument on frame read, that being an unsigned long
 *  long int * to receive the timestamp.
 *
 * No additional arguments on close-for-write.
 *
 * No additional arguments on close-for-read.
 */
#define VFF_TIMESTAMPS 0x00000001

/*
 * This flag is used only on read; it is an error to specify it when
 *  opening a file for write.
 *
 * This indicates that the amount of space occupied by each frame in
 *  the file is difficult to predict ahead of time.  This calls for a
 *  change to read_vidfile_frame's interface: the `frame data' argument
 *  to it becomes, instead, a pointer to a VF_CHUNKER object.
 *
 * When this is used, the application is alerted through the feature
 *  callback; that is, this is treated like a feature in that the
 *  feature callback is called (with no additional arguments) for it.
 */
#define VFF_CHUNKED 0x00000002
typedef struct vf_chunker VF_CHUNKER;
struct vf_chunker {
  /*
   * cookie is passed as the first argument to the other functions.
   */
  void *cookie;
  /*
   * Called with the total frame size in octets.  Depending on the
   *  particular format, there may be additional arguments.
   */
  void (*header)(
	void *,			/* cookie */
	int,			/* total size */
	... );			/* possible additional args */
  /*
   * Called for each chunk of data.  The arguments are the offset and
   *  length of the chunk, plus the data itself; depending on the
   *  particular format, there may be additional arguments.  In the
   *  absence of errors, all the chunk calls will exactly cover the
   *  octets of the data, but no promises about in what order.
   */
  void (*chunk)(
	void *,			/* cookie */
	int,			/* offset */
	int,			/* length */
	const void *,		/* data */
	...);			/* possible additional args */
  } ;

typedef struct vfw_handle VFW_HANDLE;
typedef struct vfr_handle VFR_HANDLE;

/*
 * Prepare to write a video file; in particular, generate its header.
 *
 * VFW_HANDLE *open_vidfile_write(
 *	void (*writefn)(void *, const void *, int), void *cookie,
 *	int width,
 *	int height,
 *	VF_VIDFMT fmt,
 *	unsigned int flags,
 *	... )
 *
 * writefn is a callback called to write data; it is passed the cookie
 *  and a buffer-and-length argument pair.  There is no error return,
 *  but the function is permitted to throw out.  If it throws out
 *  during open_vidfile_write, the open does not complete; if it throws
 *  out during later I/O, the only permitted further operation on the
 *  VFW_HANDLE is to close it.
 *
 * width and height are the size of each frame, in pixels, and must be
 *  in the range 1..65536.  fmt is one of the VF_FMT_* constants,
 *  describing the data's format.
 *
 * The flags argument indicates various optional features.  It consists
 *  of zero or more bits from the VFF_* defines.  Some of them may
 *  indicate the presence of optional arguments; when more than one
 *  flag with arguments is given, the arguments occur in order of
 *  increasing VFF_* value.
 *
 * If an error occurs during the open, writefn will be called with a
 *  negative value for the length and a buffer pointing to a string
 *  describing the error.  If writefn returns from this call,
 *  open_vidfile_write will return nil.
 *
 * Successful return value is an opaque handle, used with other calls.
 */
extern VFW_HANDLE *open_vidfile_write(
	void (*)(void *, const void *, int),	/* writefn */
	void *,					/* cookie */
	int, int,				/* width, height */
	VF_VIDFMT,				/* format */
	unsigned int,				/* flags */
	... );

/*
 * Write a frame.
 *
 * void write_vidfile_frame(
 *	VFW_HANDLE *handle,
 *	const void *framedata,
 *	... )
 *
 * framedata points to the frame data.  It is assumed to point to the
 *  correct amount of data in the correct format.
 *
 * Additional arguments may be permitted and/or required, depending on
 *  how the file was opened.
 */
extern void write_vidfile_frame(VFW_HANDLE *, const void *, ...);

/*
 * Close a vidfile being written.
 *
 * void close_vidfile_write(
 *	VFW_HANDLE *handle,
 *	... )
 *
 * Additional arguments may be permitted and/or required, depending on
 *  how the file was opened.
 */
extern void close_vidfile_write(VFW_HANDLE *, ...);

/*
 * Prepare to read a video file; in particular, parse its header.
 *
 * VFR_HANDLE *open_vidfile_read(
 *	void (*err)(void *, const char *),
 *	void *errcookie,
 *	int (*readfn)(void *, void *, int),
 *	void *readcookie,
 *	int *widthp,
 *	int *heightp,
 *	VF_VIDFMT *fmtp,
 *	void (*feature)(void *, unsigned int, ...),
 *	void *featurecookie );
 *
 * err is an error callback, called on error (with errcookie as its
 *  first argument and an error message as its second argument).  It
 *  must not throw out.  If it is called during open_vidfile_read, the
 *  open does not succeed; if it is called during later I/O, the only
 *  subsequently permitted operation on the VFR_HANDLE is to close it.
 *
 * readfn is a callback called to read data; it is passed readcookie
 *  and a buffer-and-length argument pair.  It returns the number of
 *  octets read, or a value < 1 on error; it must not throw out.
 *
 * widthp and heightp receive the size of each frame, in pixels; fmtp,
 *  one of the VF_FMT_* constants, describing the data's format.
 *
 * (*feature)() is called for each feature found in the file, with
 *  featurecookie as its first argument.  The second argument is the
 *  corresponding VFF_ bit, with additional arguments, if any,
 *  depending on the particular bit.  This function must not throw out.
 *  Unrecognized features with essential set produce errors;
 *  unrecognized features with essential clear are ignored as far as
 *  the API is concerned.
 *
 * Successful return value is an opaque handle, used with other calls.
 *
 * Note that, in contrast to readfn, feature is never called during
 *  later use of the VFR_HANDLE; the pointer need not remain valid
 *  after open_vidfile_read return.
 */
extern VFR_HANDLE *open_vidfile_read(
	void (*)(void *, const char *),		/* err */
	void *,					/* errcookie */
	int (*)(void *, void *, int),		/* readfn */
	void *,					/* readcookie */
	int *, int *,				/* widthp, heightp */
	VF_VIDFMT *,				/* formatp */
	void (*)(void *, unsigned int, ...),	/* feature */
	void *				);	/* featurecookie */

/*
 * Read a frame.
 *
 * void read_vidfile_frame(
 *	VFR_HANDLE *handle,
 *	void *framedata,
 *	... )
 *
 * framedata points to the frame data area.  It is assumed to point to
 *  the correct amount of data.
 *
 * Additional arguments may be permitted and/or required, depending on
 *  the features found when the file was opened.
 */
extern void read_vidfile_frame(VFR_HANDLE *, void *, ...);

/*
 * Close a vidfile being read.
 *
 * void close_vidfile_read(
 *	VFR_HANDLE *handle,
 *	... )
 *
 * Additional arguments may be permitted and/or required, depending on
 *  how the file was opened.
 */
extern void close_vidfile_read(VFR_HANDLE *, ...);

#endif