1.) HOW TO RUN ONE TEST STAND-ALONE
2.) HOW TO RUN THE WHOLE THING
3.) HOW TO GENERATE GRAPHS
4.) GENERAL ADVICE


1.) HOW TO RUN ONE TEST STAND-ALONE:

	cd tests
	./test-clutk-perf 0 10 50 5 single blur `pkg-config --modversion clutk-0.3` ./gpu ./ogl 1 1

The usage-template of test-clutk-perf looks like this:

	test-clutk-perf <iteration>
			<number>
			<size>
			<seconds>
			single|composed
			animated|static
			blur|glow|shadow
			<mod-version>
			<gpu>
			<ogl-version>
			<current>
			<all>

<iteration> is an unsigned integer value needed for the gnuplot-scripts and is
only of importance to the run-perf-tests.sh script. If you run test-clutk-perf
just stand-alone you can leave this at 0.

<number> is an unsigned integer value telling how many actors (single of
composed, more on that further down) should be created. There is an upper limit
of 100 at the moment.

<size> is an unsigned integer value for specifying the size in pixels (width and
height) of an actor. There is an upper limit of 300 at the moment.

<seconds> is an unsigned integer value denoting the duration in seconds how long
a test should run. Note: Clicking the close-widget on a window opened by
test-clutk-perf has no effect!

single|composed is a string flag (use either "single" or "composed") instructing
to use single actors or a composed actors (vbox with three image-actors). This
is meant to test effects applied to a parent also affecting its children. The
three children of the parent will have a different effect applied to them
(shifted by one).

animated|static is a string flag (use either "animated" or "static") which will
animate (or not animate) certain properties of the selected effect. Only
performance-relevant properties are animated (e.g. "size", "factor" but not some
"offset-x" or so).

blur|glow|shadow is a string flag (use "blur", "glow" or "shadow") to control
the shader effect to be applied to the actor. If the actor type is "composed"
then this controls only the effect of the parent actor/container.

<mod-version> is a string informing about the library version of clutk used.
This is meant to be passed on to the gnuplot-scripts later. Most of the time use
something like `pkg-config --modversion clutk-0.3`.

<gpu> is a string informing about the found OpenGL-renderer the test is running
on. It is displayed in the on-screen label of the test-clutk-perf window.

<ogl-version> is a string informing about the version of the found
OpenGL-implementation the test is running on. It is being display in the
on-screen label of the test-clutk-perf window.

<current> is an unsigned integer indicating which test (in a row of many) this
is. Only useful for the scripts like run-perf-tests.sh running a whole batch of
tests.

<all> is an unsigned integer indicating how many tests are intended to run. Only
useful for the scripts like run-perf-tests.sh running a whole batch of tests.



2.) HOW TO RUN THE WHOLE THING:

	cd tests
	./run-perf-tests.sh 2 5 `pkg-config --modversion clutk-0.3`

The usage-template of run-perf-tests.sh looks like this:

	run-perf-tests.sh <index>
			  <seconds>
			  <mod_version>

<index> unsigned integer value indicating the iteration of a test-run. This is
needed by the gnuplot-scripts. Pay close attention to this. If you're unsure
what number to put there look at the last line of any log-*.csv file. The
running iteration number at the beginning shows you the last value you used. For
a new run take that number, increase it by one and use that for the new run.

<seconds> unsigned integer value determining the duration of one single test. It
should be at least 5 seconds.

<mod_version> string informing about the used clutk version. This will be used
as the tick-mark label on the x-axis by gnuplot.

It is adviced that you don't run the run-perf-tests.sh under compiz, metacity or
any full desktop-environment. To keep the gathered data as "pure" as possible
you should log out of your current desktop-session and switch to a VT. Login on
a VT (usually by hitting Ctrl-Alt-F1) and do:

	sudo stop gdm (will stop gdm and X11)
	X & (will start plain X11 without anything)

Switch back to the VT (Ctrl-Alt-F1) where you're logged in and do:

	DISPLAY=:0.0 gnome-terminal &

Switch back to the X11 session (usually by hitting Ctrl-Alt-F7) and use the just
opened gnome-terminal to cd to your clutk directory:

Issue the commands:

	cd tests
	./run-perf-tests.sh 0 5 `pkg-config --modversion clutk-0.3`

and wait and watch all the glory happening :)

This will run 360 different tests and take 30 minutes (or just 6 minutes if you
only let each test run for 1 second). Note: You should let each test run for at
least 5 seconds, thus the time to resolve and load libraries, open/load shader
text-files, compile them etc. does not weight in too much.

Next time you run the script (after you compiled a newer and hopefully improved
version of clutk) do:

	./run-perf-tests.sh 1 5 `pkg-config --modversion clutk-0.3`

Note the increased iteration (1 instead of 0). This is needed for the
gnuplot-scripts. You'll see your log-*.csv files (in clutk/tests) now containing
two lines with performance-data. Pay close attention to this! Otherwise 
gnuplot-scripts will not work.



3.) HOW TO GENERATE GRAPHS:

(still needs to be written)



4.) GENERAL ADVICE:

I suggest to keep the log-*.csv files under separate version control. Especially
in the beginning you will want to mess around with the run-perf-tests.sh script.
For example, each time you interrupt the script you'll mess up the consistnecy
of the data. For each test a single log-file is maintained and used for a
performance graph.
