wcap/README

   1 WCAP Tools
   2
   3 WCAP is the video capture format used by Weston (Weston CAPture).
   4 It's a simple, lossless format, that encodes the difference between
   5 frames as run-length ecoded rectangles.  It's a variable framerate
   6 format, that only records new frames along with a timestamp when
   7 something actually changes.
   8
   9 Recording in Weston is started by pressing MOD+R and stopped by
  10 pressing MOD+R again.  Currently this leaves a capture.wcap file in
  11 the cwd of the weston process.  The file format is documented below
  12 and Weston comes with two tools to convert the wcap file into
  13 something more usable:
  14
  15  - wcap-snapshot; a simple tool that will extract a given frame from
  16    the capture as a png.  This will produce a lossless screenshot,
  17    which is useful if you're trying to screenshot a brief glitch or
  18    something like that that's hard to capture with the screenshot tool.
  19
  20    wcap-snapshot takes a wcap file as its first argument.  Without
  21    anything else, it will show the screen size and number of frames in
  22    the file.  With an integer second argument, it will extract that
  23    frame as a png:
  24
  25         [krh@minato weston]$ wcap-snapshot capture.wcap
  26         wcap file: size 1024x640, 176 frames
  27         [krh@minato weston]$ wcap-snapshot capture.wcap 20
  28         wrote wcap-frame-20.png
  29         wcap file: size 1024x640, 176 frames
  30
  31  - wcap-decode; this is a copy of the vpxenc tool from the libvpx
  32    repository, with wcap input file support added.  The tool can
  33    encode a wcap file into a webm video (http://www.webmproject.org/).
  34    The command line arguments are identical to what the vpxenc tool
  35    takes and wcap-decode will print them if run without any arguments.
  36
  37    The minimal command line requires a webm output file and a wcap
  38    input file:
  39
  40         [krh@minato weston]$ wcap-decode -o foo.webm capture.wcap
  41
  42    but it's possible to select target bitrate and output framerate and
  43    it's typically useful to pass -t 4 to let the tool use multiple
  44    threads:
  45
  46         [krh@minato weston]$ wcap-decode --target-bitrate=1024 \
  47                 --best -t 4 -o foo.webm capture.wcap  --fps=10/1
  48
  49
  50 WCAP File format
  51
  52 The file format has a small header and then just consists of the
  53 indivial frames.  The header is
  54
  55         uint32_t        magic
  56         uint32_t        format
  57         uint32_t        width
  58         uint32_t        height
  59
  60 all CPU endian 32 bit words.  The magic number is
  61
  62         #define WCAP_HEADER_MAGIC       0x57434150
  63
  64 and makes it easy to recognize a wcap file and verify that it's the
  65 right endian.  There are four supported pixel formats:
  66
  67         #define WCAP_FORMAT_XRGB8888    0x34325258
  68         #define WCAP_FORMAT_XBGR8888    0x34324258
  69         #define WCAP_FORMAT_RGBX8888    0x34325852
  70         #define WCAP_FORMAT_BGRX8888    0x34325842
  71
  72 Each frame has a header:
  73
  74         uint32_t        msecs
  75         uint32_t        nrects
  76
  77 which specifies a timestamp in ms and the number of rectangles that
  78 changed since previous frame.  The timestamps are typically just a raw
  79 system timestamp and the first frame doesn't start from 0ms.
  80
  81 A frame consists of a list of rectangles, each of which represents the
  82 component-wise different between the previous frame and the current
  83 using a run-length encoding.  The initial frame is decoded against a
  84 previous frame of all 0x00000000 pixels.  Each rectangle starts out
  85 with
  86
  87         int32_t         x1
  88         int32_t         y1
  89         int32_t         x2
  90         int32_t         y2
  91
  92 followed by (x2 - x1) * (y2 - y1) pixels, run-length encoded.  The
  93 run-length encoding uses the 'X' channel in the pixel format to encode
  94 the length of the run.  That is for WCAP_FORMAT_XRGB8888, for example,
  95 the length of the run is in the upper 8 bits.  For X values 0-0xdf,
  96 the length is X + 1, for X above or equal to 0xe0, the run length is 1
  97 << (X - 0xe0 + 7).  That is, a pixel value of 0xe3000100, means that
  98 the next 1024 pixels differ by RGB(0x00, 0x01, 0x00) from the previous
  99 pixels.