diff options
Diffstat (limited to 'wcap/README')
-rw-r--r-- | wcap/README | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/wcap/README b/wcap/README new file mode 100644 index 00000000..0994a1bb --- /dev/null +++ b/wcap/README @@ -0,0 +1,99 @@ +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 +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 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. |