src/demo/share/java2d/J2DBench/README - platform/libcore - Git at Google

 -----------------------------------------------------------------------
 Introduction
 -----------------------------------------------------------------------

 J2DBench is a  suite of benchmarks with a GUI front  end that lets you
 analyze the  performance of many Java2D graphical  operations. You can
 easily modify  the test  options, and save  them for later  runs using
 GUI, or  load them in batch  mode to allow quick  testing on different
 builds.   It  also  provides  logging  of  the  result,  to  make  the
 comparison of the collected data easier.

 J2DAnalyzer  is  J2DBench  a  results  analyzer/comparator  which  can
 compare the results generated by the J2DBench runs.

 XMLHTMLReporter is an additional tool  which can create an html report
 from the results files generated by the J2DBench runs.

 -----------------------------------------------------------------------
 Minimum requirements
 -----------------------------------------------------------------------

 The benchmark requires at least jdk1.4 to compile and run. Note that
 source/target is set to 1.6 in the makefile and build.xml, because of
 support in jdk 9 compiler.

 -----------------------------------------------------------------------
 How To Compile
 -----------------------------------------------------------------------

 #> cd J2DBench

 The benchmark can be compiled by using either ant:

 #> ant

 or gnumake (assuming there's 'javac' in the path):

 #> gnumake

 The jar files will be generated into J2DBench/dist directory.

 Note that the workspace also contains Netbeans 4.0 project file:
   J2DBench/nbproject/project.xml
 allowing it to be easily imported into Netbeans.

 -----------------------------------------------------------------------
 How To Run J2DBench, J2DAnalyzer, XMLHTMLReporter
 -----------------------------------------------------------------------

 #> ant run
   or
 #> java -jar dist/J2DBench.jar

 To get help page for each of the tools, run:
 #> java -jar dist/J2DBench.jar -help
 #> java -jar dist/J2DAnalyzer.jar -help
 #> java -cp dist/J2DAnalyzer.jar j2dbench.report.XMLHTMLReporter -help

 -----------------------------------------------------------------------
 Using J2DBench GUI to Create Options File
 -----------------------------------------------------------------------

 There are global  options, options specific to a  group of benchmarks,
 and benchmark-specific options.

 Global  options affect all  groups of  benchmarks, group  options only
 affect benchmarks in particular group, and benchmark-specific ones are
 relevant to a single benchmark.

 Examples of important global options:
   Calibration:
     if the "Fixed Number of reps" is set to 0, J2DBench will calibrate
     each individual benchmark, meaning that it will determine how many
     repetitions each benchmark can perform in "Target Test Time", and
     use this number of repetitions for each Test Run.

     If "Fixed Number of reps" is non-0, each benchmark will be run for
     specified number  of repetitions.  The use of  Calibration mode is
     preferable because  the time per  operation can vary  widely among
     the various tests.

   Output Destinations:
     where the benchmarks will render to.
     All selected  benchmarks will be repeated for each selected
     destination.

 Example of benchmark group options:
 TextBenchmarks/TextOptions/Graphics
   Text AntiAlias:
     whether to use text antialiasing for text benchmarks

 Example of a benchmark option:
 Graphics Benchmarks/Imaging Benchmarks:
   Image Rendering Sources (for Imaging Benchmarks only):
     the source image types used for testing

 Example of a benchmark:
 Graphics Benchmarks/Imaging Benchmarks/Image Rendering Tests:
   drawImage(img, tx, obs):
     test the Graphics2D's
       drawImage(Image image, AffineTransform tx, ImageObserver obs)
     operation.

 General note: you can chose multiple options in some cases by holding
 Shift or Ctrl key.

 -----------------------------------------------------------------------
 Use Scenario
 -----------------------------------------------------------------------

 Suppose you want to compare rendering performance of the default
 and opengl pipelines.

 Start J2DBench (assuming the current dir is J2DBench's top dir)
 #> java -jar dist/J2DBench.jar

 You can  either create and save  the option file  by selecting desired
 tests and their attributes, or use one of the provided option files in
 options/ directory (for example, default.opt, which is used below).

 Note that it's very easy to  create an option file which would take an
 extremely  long time  to  execute the  tests,  so be  be careful  when
 choosing the options and benchmarks to run.

 After the options file is created, start J2DBench in batch mode to run
 the benchmarks for the default pipeline:
 #> java -jar dist/J2DBench.jar -batch -loadopts options/default.opt \
      -saveres default.res -title "Rendering - Default ppl" \
      -desc "Rendering tests with the default pipeline"

 This command  will run  the benchmarks defined  in options/default.opt
 file and save the result in default.res file.

 (You can also run selected tests directly from the GUI mode by hitting
 "Run Tests" in the J2DBench dialog)

 Now run the benchmark with opengl pipeline:
 #> java -Dsun.java2d.opengl=True -jar dist/J2DBench.jar -batch \
      -loadopts options/default.opt \
      -saveres opengl.res -title "Rendering - OpenGL" \
      -desc "Rendering tests with OpenGL pipeline"

 Now let's analyze the results using J2DAnalyzer:
 #> java -jar dist/J2DAnalyzer.jar default.res opengl.res

 Note that you can compare more than two sets of results, see
 J2DAnalyzer's help page.

 You can also generate html pages from the results files using
 j2dbench.report.XMLHTMLReporter class in J2DAnalyzer.jar.  Suppose
 generated pages are to be stored in html_results directory.

 First, make sure html_results/testcases directory exists:
 #> mkdir -p html_results/testcases

 Then generate the report:
 #> java -cp J2DAnalyzer.jar j2dbench.report.XMLHTMLReporter \
      -r html_results -b default.res -t opengl.res

 The html report will be generated in html_results/ directory.
 The index page:
   html_results/Summary_Report.html
	-----------------------------------------------------------------------
	Introduction
	-----------------------------------------------------------------------

	J2DBench is a suite of benchmarks with a GUI front end that lets you
	analyze the performance of many Java2D graphical operations. You can
	easily modify the test options, and save them for later runs using
	GUI, or load them in batch mode to allow quick testing on different
	builds. It also provides logging of the result, to make the
	comparison of the collected data easier.

	J2DAnalyzer is J2DBench a results analyzer/comparator which can
	compare the results generated by the J2DBench runs.

	XMLHTMLReporter is an additional tool which can create an html report
	from the results files generated by the J2DBench runs.

	-----------------------------------------------------------------------
	Minimum requirements
	-----------------------------------------------------------------------

	The benchmark requires at least jdk1.4 to compile and run. Note that
	source/target is set to 1.6 in the makefile and build.xml, because of
	support in jdk 9 compiler.

	-----------------------------------------------------------------------
	How To Compile
	-----------------------------------------------------------------------

	#> cd J2DBench

	The benchmark can be compiled by using either ant:

	#> ant

	or gnumake (assuming there's 'javac' in the path):

	#> gnumake

	The jar files will be generated into J2DBench/dist directory.

	Note that the workspace also contains Netbeans 4.0 project file:
	J2DBench/nbproject/project.xml
	allowing it to be easily imported into Netbeans.

	-----------------------------------------------------------------------
	How To Run J2DBench, J2DAnalyzer, XMLHTMLReporter
	-----------------------------------------------------------------------

	#> ant run
	or
	#> java -jar dist/J2DBench.jar

	To get help page for each of the tools, run:
	#> java -jar dist/J2DBench.jar -help
	#> java -jar dist/J2DAnalyzer.jar -help
	#> java -cp dist/J2DAnalyzer.jar j2dbench.report.XMLHTMLReporter -help

	-----------------------------------------------------------------------
	Using J2DBench GUI to Create Options File
	-----------------------------------------------------------------------

	There are global options, options specific to a group of benchmarks,
	and benchmark-specific options.

	Global options affect all groups of benchmarks, group options only
	affect benchmarks in particular group, and benchmark-specific ones are
	relevant to a single benchmark.

	Examples of important global options:
	Calibration:
	if the "Fixed Number of reps" is set to 0, J2DBench will calibrate
	each individual benchmark, meaning that it will determine how many
	repetitions each benchmark can perform in "Target Test Time", and
	use this number of repetitions for each Test Run.

	If "Fixed Number of reps" is non-0, each benchmark will be run for
	specified number of repetitions. The use of Calibration mode is
	preferable because the time per operation can vary widely among
	the various tests.

	Output Destinations:
	where the benchmarks will render to.
	All selected benchmarks will be repeated for each selected
	destination.

	Example of benchmark group options:
	TextBenchmarks/TextOptions/Graphics
	Text AntiAlias:
	whether to use text antialiasing for text benchmarks

	Example of a benchmark option:
	Graphics Benchmarks/Imaging Benchmarks:
	Image Rendering Sources (for Imaging Benchmarks only):
	the source image types used for testing

	Example of a benchmark:
	Graphics Benchmarks/Imaging Benchmarks/Image Rendering Tests:
	drawImage(img, tx, obs):
	test the Graphics2D's
	drawImage(Image image, AffineTransform tx, ImageObserver obs)
	operation.

	General note: you can chose multiple options in some cases by holding
	Shift or Ctrl key.

	-----------------------------------------------------------------------
	Use Scenario
	-----------------------------------------------------------------------

	Suppose you want to compare rendering performance of the default
	and opengl pipelines.

	Start J2DBench (assuming the current dir is J2DBench's top dir)
	#> java -jar dist/J2DBench.jar

	You can either create and save the option file by selecting desired
	tests and their attributes, or use one of the provided option files in
	options/ directory (for example, default.opt, which is used below).

	Note that it's very easy to create an option file which would take an
	extremely long time to execute the tests, so be be careful when
	choosing the options and benchmarks to run.

	After the options file is created, start J2DBench in batch mode to run
	the benchmarks for the default pipeline:
	#> java -jar dist/J2DBench.jar -batch -loadopts options/default.opt \
	-saveres default.res -title "Rendering - Default ppl" \
	-desc "Rendering tests with the default pipeline"

	This command will run the benchmarks defined in options/default.opt
	file and save the result in default.res file.

	(You can also run selected tests directly from the GUI mode by hitting
	"Run Tests" in the J2DBench dialog)

	Now run the benchmark with opengl pipeline:
	#> java -Dsun.java2d.opengl=True -jar dist/J2DBench.jar -batch \
	-loadopts options/default.opt \
	-saveres opengl.res -title "Rendering - OpenGL" \
	-desc "Rendering tests with OpenGL pipeline"

	Now let's analyze the results using J2DAnalyzer:
	#> java -jar dist/J2DAnalyzer.jar default.res opengl.res

	Note that you can compare more than two sets of results, see
	J2DAnalyzer's help page.

	You can also generate html pages from the results files using
	j2dbench.report.XMLHTMLReporter class in J2DAnalyzer.jar. Suppose
	generated pages are to be stored in html_results directory.

	First, make sure html_results/testcases directory exists:
	#> mkdir -p html_results/testcases

	Then generate the report:
	#> java -cp J2DAnalyzer.jar j2dbench.report.XMLHTMLReporter \
	-r html_results -b default.res -t opengl.res

	The html report will be generated in html_results/ directory.
	The index page:
	html_results/Summary_Report.html