weston/wcap
Pekka Paalanen b423edecbb meson: better error for wcap dep cairo
Add human-friendly error message.

Cairo is a hard dependency on the whole at least because tests seem to
require it, but this will help if someone adds an option to disable
building tests to get rid of Cairo.

Signed-off-by: Pekka Paalanen <pq@iki.fi>
2018-12-31 15:16:53 +02:00
..
.gitignore tests, wcap: update ignores 2012-05-31 13:53:57 -04:00
README wcap: fix a typo in README 2017-01-03 11:59:17 +00:00
main.c wcap: Prefer quote form of include for config.h 2015-06-15 13:04:19 -07:00
meson.build meson: better error for wcap dep cairo 2018-12-31 15:16:53 +02:00
wcap-decode.c wcap: Prevent fd leak in wcap_decoder_create() fail path 2017-03-31 01:41:45 +02:00
wcap-decode.h include stdint.h for int32_t/uint32_t 2016-07-26 16:26:08 -07:00

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 encoded 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 the wcap-decode tool to convert the wcap file
into something more usable:

 - Extract single or all frames as individual png files.  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-decode takes a number of options and a wcap file as its
   arguments.  Without anything else, it will show the screen size and
   number of frames in the file.  Pass --frame=<frame> to extract a
   single frame or pass --all to extract all frames as png files:

	[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

 - Decode and the wcap file and dump it as a YUV4MPEG2 stream on
   stdout.  This format is compatible with most video encoders and can
   be piped directly into a command line encoder such as vpxenc (part
   of libvpx, encodes to a webm file) or theora_encode (part of
   libtheora, encodes to a ogg theora file).

   Using vpxenc to encode a webm file would look something like this:

	[krh@minato weston]$ wcap-decode  --yuv4mpeg2 ../capture.wcap |
		vpxenc --target-bitrate=1024 --best -t 4 -o foo.webm  -

   where we select target bitrate, pass -t 4 to let vpxenc use
   multiple threads.  To encode to Ogg Theora a command line like this
   works:

	[krh@minato weston]$ wcap-decode ../capture.wcap  --yuv4mpeg2 |
		theora_encode - -o cap.ogv


WCAP File format

The file format has a small header and then just consists of the
individual 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 difference 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.