diff options
| -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..b74333e4 --- /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 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. |