Old src/share/demo/java2d/J2DBench/README

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