README
1-----------------------------------------------------------------------
2Introduction
3-----------------------------------------------------------------------
4
5J2DBench is a suite of benchmarks with a GUI front end that lets you
6analyze the performance of many Java2D graphical operations. You can
7easily modify the test options, and save them for later runs using
8GUI, or load them in batch mode to allow quick testing on different
9builds. It also provides logging of the result, to make the
10comparison of the collected data easier.
11
12J2DAnalyzer is J2DBench a results analyzer/comparator which can
13compare the results generated by the J2DBench runs.
14
15XMLHTMLReporter is an additional tool which can create an html report
16from the results files generated by the J2DBench runs.
17
18-----------------------------------------------------------------------
19Minimum requirements
20-----------------------------------------------------------------------
21
22The benchmark requires at least jdk1.4 to compile and run. Note that
23source/target is set to 1.6 in the makefile and build.xml, because of
24support in jdk 9 compiler.
25
26-----------------------------------------------------------------------
27How To Compile
28-----------------------------------------------------------------------
29
30#> cd J2DBench
31
32The benchmark can be compiled by using either ant:
33
34#> ant
35
36or gnumake (assuming there's 'javac' in the path):
37
38#> gnumake
39
40The jar files will be generated into J2DBench/dist directory.
41
42Note that the workspace also contains Netbeans 4.0 project file:
43 J2DBench/nbproject/project.xml
44allowing it to be easily imported into Netbeans.
45
46-----------------------------------------------------------------------
47How To Run J2DBench, J2DAnalyzer, XMLHTMLReporter
48-----------------------------------------------------------------------
49
50#> ant run
51 or
52#> java -jar dist/J2DBench.jar
53
54To get help page for each of the tools, run:
55#> java -jar dist/J2DBench.jar -help
56#> java -jar dist/J2DAnalyzer.jar -help
57#> java -cp dist/J2DAnalyzer.jar j2dbench.report.XMLHTMLReporter -help
58
59-----------------------------------------------------------------------
60Using J2DBench GUI to Create Options File
61-----------------------------------------------------------------------
62
63There are global options, options specific to a group of benchmarks,
64and benchmark-specific options.
65
66Global options affect all groups of benchmarks, group options only
67affect benchmarks in particular group, and benchmark-specific ones are
68relevant to a single benchmark.
69
70Examples of important global options:
71 Calibration:
72 if the "Fixed Number of reps" is set to 0, J2DBench will calibrate
73 each individual benchmark, meaning that it will determine how many
74 repetitions each benchmark can perform in "Target Test Time", and
75 use this number of repetitions for each Test Run.
76
77 If "Fixed Number of reps" is non-0, each benchmark will be run for
78 specified number of repetitions. The use of Calibration mode is
79 preferable because the time per operation can vary widely among
80 the various tests.
81
82 Output Destinations:
83 where the benchmarks will render to.
84 All selected benchmarks will be repeated for each selected
85 destination.
86
87Example of benchmark group options:
88TextBenchmarks/TextOptions/Graphics
89 Text AntiAlias:
90 whether to use text antialiasing for text benchmarks
91
92Example of a benchmark option:
93Graphics Benchmarks/Imaging Benchmarks:
94 Image Rendering Sources (for Imaging Benchmarks only):
95 the source image types used for testing
96
97Example of a benchmark:
98Graphics Benchmarks/Imaging Benchmarks/Image Rendering Tests:
99 drawImage(img, tx, obs):
100 test the Graphics2D's
101 drawImage(Image image, AffineTransform tx, ImageObserver obs)
102 operation.
103
104General note: you can chose multiple options in some cases by holding
105Shift or Ctrl key.
106
107-----------------------------------------------------------------------
108Use Scenario
109-----------------------------------------------------------------------
110
111Suppose you want to compare rendering performance of the default
112and opengl pipelines.
113
114Start J2DBench (assuming the current dir is J2DBench's top dir)
115#> java -jar dist/J2DBench.jar
116
117You can either create and save the option file by selecting desired
118tests and their attributes, or use one of the provided option files in
119options/ directory (for example, default.opt, which is used below).
120
121Note that it's very easy to create an option file which would take an
122extremely long time to execute the tests, so be be careful when
123choosing the options and benchmarks to run.
124
125After the options file is created, start J2DBench in batch mode to run
126the benchmarks for the default pipeline:
127#> java -jar dist/J2DBench.jar -batch -loadopts options/default.opt \
128 -saveres default.res -title "Rendering - Default ppl" \
129 -desc "Rendering tests with the default pipeline"
130
131This command will run the benchmarks defined in options/default.opt
132file and save the result in default.res file.
133
134(You can also run selected tests directly from the GUI mode by hitting
135"Run Tests" in the J2DBench dialog)
136
137Now run the benchmark with opengl pipeline:
138#> java -Dsun.java2d.opengl=True -jar dist/J2DBench.jar -batch \
139 -loadopts options/default.opt \
140 -saveres opengl.res -title "Rendering - OpenGL" \
141 -desc "Rendering tests with OpenGL pipeline"
142
143Now let's analyze the results using J2DAnalyzer:
144#> java -jar dist/J2DAnalyzer.jar default.res opengl.res
145
146Note that you can compare more than two sets of results, see
147J2DAnalyzer's help page.
148
149You can also generate html pages from the results files using
150j2dbench.report.XMLHTMLReporter class in J2DAnalyzer.jar. Suppose
151generated pages are to be stored in html_results directory.
152
153First, make sure html_results/testcases directory exists:
154#> mkdir -p html_results/testcases
155
156Then generate the report:
157#> java -cp J2DAnalyzer.jar j2dbench.report.XMLHTMLReporter \
158 -r html_results -b default.res -t opengl.res
159
160The html report will be generated in html_results/ directory.
161The index page:
162 html_results/Summary_Report.html
163