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