testing.xml

<?xml version='1.0' encoding='iso-8859-1'?>

<sect1 id="testing">
	<title id="testing.title">Debugging and benchmarking</title>
	
	<sect2 id="breakpoint-modules">
		<title>How do you put a breakpoint in the dynamically loaded modules?</title>
		
		<para>
		You need xfree86-gdb, which is a version of gdb modified
		to understand the module binary format that XFree86 uses
		in addition to the standard elf/coff binary formats. 
		</para>
		
		<example>
			<title>Using xfree86-gdb</title>
			
			<para>
			Use 
<programlisting>
modules mach64_drv.o mach64_dri.o
</programlisting>
			after starting the debugger to load symbols, etc.
			</para>
		</example>
	
		<para>
		xfree86-gdb is freely available from <ulink url="http://www.dawa.demon.co.uk/xfree-gdb/">here</ulink>.
		</para>
	</sect2>

	<sect2 id="benchmarking-ut">
		<title>How do I do benchmarking with Unreal Tournament?</title>
        
		<para>
		Start a practice level. Type <userinput>timedemo 1</userinput> in 
		the console or in alternative select the "TimeDemo Statistic" menu 
		entry under the "Tools" section.
		</para>
		
		<para>
		You should see two numbers in white text on the right side of the 
		screen showing the average framerate (Avg) and the number of frame 
		rates in the last second (Last Sec). If this doesn't work
		check whether the stats get reported in your <filename>
		~/.loki/ut/System/UnrealTournament.log</filename> file.
		</para>
		
	</sect2>

	<sect2 id="accel-detect">
		<title>
		Is there any way for us to detect which features are implemented with hardware 
		support for a given driver?
		</title>
		
		<para>
		OpenGL doesn't have such a query. This is a potential problem with any OpenGL 
		implementation.  The real question one wants answered is 
		<quote>is this feature or GL state combination
		fast enough for my needs?</quote>.  Whether a feature is implemented in
		hardware or software isn't always consistent with that question.
		</para>
		
		<para>
		You might consider implementing a benchmark function to test the speed
		during start-up and making a decision depending on the result.  The info could 
		be cached in a file keyed by <envar>GL_RENDERER</envar>.
		</para>
		
		<para>
		Check <ulink url="http://www.berkelium.com/OpenGL/isfast.html">isfast</ulink>
		</para>
	</sect2>

	<sect2>
		<title>Which OpenGL benchmarking program can I use to test and compare various facets of the performance of graphics cards?</title>
	
		<glosslist>
			<glossentry>
				<glossterm>Games</glossterm>
				<glossdef>
						<para>
						You can use OpenGL games such as Quake 3, Unreal Tournament, etc.
						</para>
				</glossdef>
			</glossentry>
	
			<glossentry>
				<glossterm>SPECviewperf</glossterm>
				<glossdef>
						<para>
						<ulink url="http://www.specbench.org/gpc/opc.static/opcview.htm">SPECviewperf</ulink> 
						is a portable OpenGL performance benchmark program written in C providing 
						a vast amount of flexibility in benchmarking OpenGL performance.
						</para>
				</glossdef>
			</glossentry>
		
			<glossentry>
				<glossterm>SPECglperf</glossterm>
				<glossdef>
						<para>
						<ulink url="http://www.specbench.org/gpc/opc.static/glperf.htm">SPECglperf</ulink> 
						is an executable toolkit that measures the performance of 
						OpenGL 2D and 3D graphics operations. These operations are low-level 
						primitives (points, lines, triangles, pixels, etc.) rather than entire models.
						</para>
				</glossdef>
			</glossentry>
		
			<glossentry>
				<glossterm>gleam</glossterm>
				<glossdef>
						<para>
						<ulink url="http://glean.sourceforge.net">glean</ulink> is a suite of tools 
						for evaluating the quality of an 
						OpenGL implementation and diagnosing any problems that are 
						discovered. It also has the ability to compare two OpenGL 
						implementations and highlight the differences between them.
						</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm>machtest</glossterm>
				<glossdef>
					<para>
					<ulink url="http://wwwvis.informatik.uni-stuttgart.de/machtest/intro.html">machtest</ulink>
					is a thorough benchmark for graphics cards.
					It has literary thousands of command line options, is easily extensible and it can produce machine readable output. 
					</para>
				</glossdef>
			</glossentry>
		
			<glossentry>
				<glossterm>Mesa demos</glossterm>
				<glossdef>
						<para>
						</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm>Nate Robins' OpenGL Tutors</glossterm>
				<glossdef>
						<para>
						<ulink url="http://www.xmission.com/~nate/tutors.html">Nate Robins' OpenGL Tutors</ulink> 
						are a set of tutorial programs that demonstrate basic OpenGL functionality by allowing the 
						user to modify the parameters of a function and see the effect on the scene. 
						</para>
				</glossdef>
			</glossentry>
			
		</glosslist>
	</sect2>
	
	<sect2>
		<title>What environment variables affect libGL behavior?</title>
		
		<glosslist>
			<glossentry>
				<glossterm><envar>LIBGL_DEBUG</envar></glossterm>
				
				<glossdef>
					<para>
					If defined debug information will be printed to <varname>stderr</varname>.
					If set to <userinput>verbose</userinput> additional information will be printed.
					</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm><envar>LIBGL_DRIVERS_PATH</envar></glossterm>
				
				<glossdef>
					<para>
					Path were to search for 3D DRI drivers.
					See also <link linkend="ed-driver-where">here</link>.
					</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm><envar>LIBGL_MULTIHEAD</envar></glossterm>
				
				<glossdef>
					<para>
					Define to specify the presence of more than one display.
					</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm><envar>LIBGL_ALWAYS_INDIRECT</envar></glossterm>
				
				<glossdef>
					<para>
					Assures that no direct rendering will take place.
					See also <link linkend="indirect-difference">here</link>.
					</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm><envar>LIBGL_DRI_AUTOFULLSCREEN</envar></glossterm>
				
				<glossdef>
					<para>
					If set to 
						<userinput>enable</userinput>, 
						<userinput>1</userinput>, 
						<userinput>on</userinput>, 
						<userinput>true</userinput>, 
						<userinput>t</userinput>, 
						<userinput>yes</userinput> or 
						<userinput>y</userinput>
					the driver it will check for the potential to enter an automatic full-screen mode.
					</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm><envar>LIBGL_SOFTWARE_RENDERING</envar></glossterm>
				
				<glossdef>
					<para>
					If set it will force software rendering.
					</para>
				</glossdef>
			</glossentry>

			<glossentry>
				<glossterm><envar>LIBGL_NO_MULTITEXTURE</envar></glossterm>
				
				<glossdef>
					<para>
					If set it will disable the <function>GL_ARB_multitexture</function> extension.
					</para>
				</glossdef>
			</glossentry>
			
			<glossentry>
				<glossterm><envar>LIBGL_PERFORMANCE_BOXES</envar></glossterm>
				
				<glossdef>
					<para>
					If set the r128 driver, when built with <varname>ENABLE_PERF_BOXES</varname> will draw performance boxes.
					</para>
				</glossdef>
			</glossentry>
			
		</glosslist>
	</sect2>

	<sect2>
		<title>How should I report bugs?</title>
		
		<para>
		Please submit bugs to the <ulink url="mailto:dri-devel@lists.sourceforge.net">dri-devel mailing list</ulink>.
		It's best if you can create a small example that shows what you think is the problem.
		</para>
		
		<para>
		For those who really want to be Open Source heroes -- you can create a test
		for the bug under <ulink url="http://glean.sourceforge.net">glean</ulink>. The intention
		would be to run glean quite often, so any functionality you can verify
		there, is much less likely to reappear in a broken form at some random
		time in the future.
		</para>
	</sect2>
</sect1>