README

caskbench - The Cairo and Skia Benchmark
========================================

This benchmark is designed to do synthetic performance testing of
the cairo and skia drawing libraries.

Our principle goal is to identify problem areas in either of the drawing
libraries for performance work to be done.  To this end, we enable large
scale randomized testing of a broad range of drawing features, but
document the parameters so that particular problem cases can easily be
run in isolation for performance work.

This test suite strives to provide a flexible performance testing
toolbox useful for a range of test cases from low level performance
optimization work to high level benchmarking of devices.


== Building ==

Prerequisites include popt and gles3.  To install these on Ubuntu 13.04:

 $ sudo apt-get install libpopt-dev libgles2-mesa-dev

You will also need Skia and a GL-enabled version of libcairo installed.
These aren't packaged for Ubuntu currently, so you'll need to build from
source.

To build this testsuite, use these commands:

 $ cmake .
 $ make

The build system looks for the skia library in /usr/lib and
/usr/local/lib, and header files in /usr/include/skia and
/usr/local/include/skia.

A number of configuration settings can be overridden through cmake.  To
see a list of the options available for caskbench run:

 $ cmake -L

or, for more advanced cmake settings:

 $ cmake --help

For example, to build caskbench with only Cairo and no Skia at all, do:

 $ cmake . -DENABLE_SKIA=OFF


== Usage ==

Caskbench builds to a single executable which you can run directly
(using the software renderer):

  $ ./src/caskbench

  cairo-bubbles        64     PASS  10  115.60
  skia-bubbles         64     PASS  10  311.93  62.94%
  ...

The testing will alternate between cairo and skia versions of each test.
The second column indicates the test size, the fourth column is the
number of iterations.  If the third column shows anything other than a
pass, something's seriously wrong.  The fifth column is the fps value.
The last column calculates the percent difference that skia is faster
than cairo on average.

For hardware acceleration, specify the surface type to use (e.g. glx or
egl) via the -t parameter.

  $ ./src/caskbench -t egl

You can learn the available surface types via --list-surfaces:

  $ ./src/caskbench --list-surfaces

  image
  egl

The --iterations and --size parameters can be used to increase the
intensity of the testing.

  $ ./src/caskbench -t egl --iterations 100 --size 42

Run it with the '-?' flag to see usage directions with explanations of
all available options.

Caskbench is tested with the following skia branches:
 1. https://github.com/Samsung/skia/tree/dev/m34_1847
 2. https://github.com/Samsung/skia/tree/dev/m36_1985
 3. https://github.com/Samsung/skia/tree/upstream/m34_1847
 4. https://github.com/Samsung/skia/tree/upstream/m36_1985
 5. https://github.com/Samsung/skia/tree/henry