weston/wcap/README

WCAP Tools

WCAP is the video capture format used by Weston (Weston CAPture).
It's a simple, lossless format, that encodes the difference between
frames as run-length ecoded rectangles.  It's a variable framerate
format, that only records new frames along with a timestamp when
something actually changes.

Recording in Weston is started by pressing MOD+R and stopped by
pressing MOD+R again.  Currently this leaves a capture.wcap file in
the cwd of the weston process.  The file format is documented below
and Weston comes with two tools to convert the wcap file into
something more usable:

 - wcap-snapshot; a simple tool that will extract a given frame from
   the capture as a png.  This will produce a lossless screenshot,
   which is useful if you're trying to screenshot a brief glitch or
   something like that that's hard to capture with the screenshot tool.

   wcap-snapshot takes a wcap file as its first argument.  Without
   anything else, it will show the screen size and number of frames in
   the file.  With an integer second argument, it will extract that
   frame as a png:

	[krh@minato weston]$ wcap-snapshot capture.wcap 
	wcap file: size 1024x640, 176 frames
	[krh@minato weston]$ wcap-snapshot capture.wcap 20
	wrote wcap-frame-20.png
	wcap file: size 1024x640, 176 frames

 - wcap-decode; this is a copy of the vpxenc tool from the libvpx
   repository, with wcap input file support added.  The tool can
   encode a wcap file into a webm video (http://www.webmproject.org/).
   The command line arguments are identical to what the vpxenc tool
   takes and wcap-decode will print them if run without any arguments.

   The minimal command line requires a webm output file and a wcap
   input file:

	[krh@minato weston]$ wcap-decode -o foo.webm capture.wcap  

   but it's possible to select target bitrate and output framerate and
   it's typically useful to pass -t 4 to let the tool use multiple
   threads:

	[krh@minato weston]$ wcap-decode --target-bitrate=1024 \
		--best -t 4 -o foo.webm capture.wcap  --fps=10/1


WCAP File format

The file format has a small header and then just consists of the
indivial frames.  The header is

	uint32_t	magic
	uint32_t	format
	uint32_t	width
	uint32_t	height

all CPU endian 32 bit words.  The magic number is

	#define WCAP_HEADER_MAGIC	0x57434150

and makes it easy to recognize a wcap file and verify that it's the
right endian.  There are four supported pixel formats:

	#define WCAP_FORMAT_XRGB8888	0x34325258
	#define WCAP_FORMAT_XBGR8888	0x34324258
	#define WCAP_FORMAT_RGBX8888	0x34325852
	#define WCAP_FORMAT_BGRX8888	0x34325842

Each frame has a header:

	uint32_t	msecs
	uint32_t	nrects

which specifies a timestamp in ms and the number of rectangles that
changed since previous frame.  The timestamps are typically just a raw
system timestamp and the first frame doesn't start from 0ms.

A frame consists of a list of rectangles, each of which represents the
component-wise different between the previous frame and the current
using a run-length encoding.  The initial frame is decoded against a
previous frame of all 0x00000000 pixels.  Each rectangle starts out
with

	int32_t		x1
	int32_t		y1
	int32_t		x2
	int32_t		y2

followed by (x2 - x1) * (y2 - y1) pixels, run-length encoded.  The
run-length encoding uses the 'X' channel in the pixel format to encode
the length of the run.  That is for WCAP_FORMAT_XRGB8888, for example,
the length of the run is in the upper 8 bits.  For X values 0-0xdf,
the length is X + 1, for X above or equal to 0xe0, the run length is 1
<< (X - 0xe0 + 7).  That is, a pixel value of 0xe3000100, means that
the next 1024 pixels differ by RGB(0x00, 0x01, 0x00) from the previous
pixels.