NAME

MPIV0 - MPIV0 digital video file format

DESCRIPTION

The MPIV0 format provides a quick and easy way to write files containing streams of digital video data without having to learn the intricacies of a more sophisticated file format. This page describes the MPIV0 format and gives a quick guide to some software for reading MPIV0 files.

The MPIV0 file format is analogous to the pnm raw-pixel formats. An MPIV0 file consists of an ASCII header followed by some raw pixels. The header has the following format

• the ascii characters 'MPIV0'
• white space
• ascii string giving x size of images
• white space
• ascii string giving y size of images
• white space
• ascii string giving format index
• end-of-line

Characters in the header from a '#' to the next end of line are treated as comments. There can be no comments after the format index. The raw pixels for each image frame in the file follow immediately after the header.

The format index is an integer that indicates the pixel format in the file. It is interpreted as follows

Format Index	Pixel Type
0	RGB24
1	RGB15
2	RGB8
3	BW8

Below is a description of the formats:

RGB24

bytes in the file rotate through R G B R G B ... giving the RGB values for pixels.

RGB15

bytes contain a series of 16-bit words, lo byte first, where bits in the word contain 5-bit rgb values as follows

XRRRRRGGGGGBBBBB

RGB8

bytes contain a series of bytes, where bits in the byte contain 2- and 3-bit rgb values as follows

RRRGGGBB

BW8

bytes contain a series of gray values

Pixels are in row-major order for all formats.

There is some C code in a tar'ed directory written to make it easy to read MPIV0 files. They are in the file mpiv0.c and mpiv0.h. Here's a summary:

#include 
#include "mpiv0.h"

...

FILE *mpiv0_open( char *name, int *xsize, int *ysize,
		    MPIV0_FormatIndex *format );

char *name

name of MPIV0 file to read

int *xsize

pointer to location to write x size of images in file

int *ysize

pointer to location to write y size of images in file

MPIV0_FormatIndex *format

pointer to location to write file format index

Returns

returns file pointer to opened MPIV0 file if successful, NULL pointer otherwise.

int mpiv0_read( FILE *fp, int xsize, int ysize, MPIV0_FormatIndex format,
	       unsigned char **r, unsigned char **g, unsigned char **b );

FILE *fp

file pointer for MPIV0 file opened with mpiv0_open()

int xsize

x size of images

int ysize

y size of images

MPIV0_FormatIndex format

format index

unsigned char **r

pointer to location to write pointer to red pixel array

unsigned char **g

pointer to location to write pointer to green pixel array

unsigned char **b

pointer to location to write pointer to blue pixel array

Returns

number of frames read, i.e., 1 if successful, 0 if failure.

Note: If format == BW8 then *r, *g, and *b will point to the same array.

There is an example of how to use these two function in the program mpivtopnm.c in the tar'ed directory. In summary, use them the following way:

#include 
#include "MPIV0.h"

...

{
  FILE *fp;
  int xsize, ysize;
  MPIV0_FormatIndex format;
  unsigned char *r, *g, *b;

  if ( (fp = MPIV0_open( "name", &xsize, &ysize, &format ) == NULL ) {
   /* failed to open */
   ...
  }

  while ( MPIV0_read( fp, xsize, ysize, format &r, &g, &b ) == 1 ) {
    /* process r, g, and b */
    ...

    if ( format == BW8 )
      free( r );
    else {
      free( r );
      free( g );
      free( b );
    }
  }
}

Don't forget to free r, b, and b before processing the next frame. mpiv0_read allocates new memory for them each time it is called so you'll get a major memory leak if you forget this.

SEE ALSO

mpdvr, mpdvr, mpivmpeg, mpivsgi, and how-to examples.

BUGS

Web page design by Jeffrey E. Boyd