[cairo-commit] [cairo-www] src/FAQ.mdwn
ickle at freedesktop.org
Sun Nov 16 13:38:51 PST 2008
src/FAQ.mdwn | 33 +++++++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)
Author: Chris Wilson <chris at chris-wilson.co.uk>
Date: Sun Nov 16 21:34:55 2008 +0000
[FAQ] Add a howto trace entry.
Answer the question "My application's slower than I think it should be.
What can I do to help the cairo community find the problem?"
diff --git a/src/FAQ.mdwn b/src/FAQ.mdwn
index 35d6b60..666ff2a 100644
@@ -342,3 +342,36 @@ aligned with integer positions on the device-pixel grid. And the
easiest way to do that is to use an identity transformation,
(`cairo_identity_matrix`), and construct the path by calling
`cairo_rectangle` with integer values.
+<h2 id="profiling">My application's slower than I think it should be.
+What can I do to help the cairo community find the problem?</h2>
+The first step in analysing any problem is constructing a reproducible
+test case. Cairo provides a cairo-trace utility (currently only available
+from the git development tree, but is planned for inclusion with Cairo 1.10).
+This utility records all Cairo calls made by an application and allows you,
+and everyone else in the community, to replay the exact same sequence. This
+trace can be reviewed by others and they may be able to suggest alternative
+methods of achieving the same results. Or it may provide the developers with
+a useful benchmark for improving Cairo.
+<h3>How to generate a trace:</h3>
+After installing Cairo from git, a 1.9 snapshot or a later release the cairo-trace utility will be available.
+ $ cairo-trace
+ usage: cairo-trace [--no-file|--verbose] command
+ cairo-trace will generate a log of all calls made by command to
+ cairo. This log will be stored in a file in the local directory
+ called command.$pid.trace.
+ Whatever else happens is driven by its argument:
+ --flush - Flush the output trace after every call.
+ --verbose - Show the trace on stdout.
+ --no-file - Disable the creation of an output file.
+ --no-callers - Do not lookup the caller address/symbol/line whilst tracing.
+That is performing
+ $ cairo-trace /path/to/my/app arg1 arg2 ... argn
+will generate an output file called ./app.$pid.trace.
More information about the cairo-commit