1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<TITLE>GXSetGPMetric</TITLE> 9</HEAD> 10<BODY> 11<H1 align="left">GXSetGPMetric</H1> 12 13<H2>Syntax</H2> 14<dl><dd><pre class="construction"> 15#include <revolution/gx.h> 16 17void GXSetGPMetric( <A href="../Enumerated_Types/GXPerf0.html">GXPerf0</A> perf0, <A href="../Enumerated_Types/GXPerf1.html">GXPerf1</A> perf1 ); 18 19#define GXSetGP0Metric(perf0) GXSetGPMetric((perf0), GX_PERF1_NONE) 20#define GXSetGP1Metric(perf1) GXSetGPMetric(GX_PERF0_NONE, (perf1)) 21</pre></dd></dl> 22 23<H2>Arguments</H2> 24<TABLE class="arguments" border="1" > 25 <TBODY> 26 <TR> 27<TH>perf0</TH> 28<TD>Counter 0 for a performance metric.</TD> 29 </TR> 30 <TR> 31<TH>perf1</TH> 32<TD>Counter 1 for a performance metric.</TD> 33 </TR> 34 </TBODY> 35</TABLE> 36 37<H2>Return Values</H2> 38<P>None.</P> 39 40<H2>Description</H2> 41<P>The graphics processor (GP) can count many internal events that give detailed information on performance. This function sets two performance metrics, <SPAN class="argument">perf0</SPAN> and <SPAN class="argument">perf1</SPAN>. The first targets measured are <CODE>GX_PERF0_NONE</CODE> and <CODE>GX_PERF1_NONE</CODE>, and the first call to the <A href="GXReadGPMetric.html"><CODE>GXReadGPMetric</CODE></A> function returns zero as a count value.</P> 42<P>Because this function reads results from CPU-accessible registers in the GP, this command must not be used in a display list. Furthermore, in some cases the performance counters are triggered by sending tokens through the graphics FIFO to the GP. This implies that the function should only be used in immediate mode (when the graphics FIFO is connected simultaneously to the CPU and the GP). It may also be necessary to send a rendering synchronization token using the <A href="../Management/GXSetDrawSync.html"><CODE>GXSetDrawSync</CODE></A> function, or call the <A href="../Management/GXSetDrawDone.html"><CODE>GXSetDrawDone</CODE></A> function after the <A href="GXReadGPMetric.html"><CODE>GXReadGPMetric</CODE></A> function, to ensure that the state has actually been processed by the GP.</P> 43<DL><DD><CODE>GXSetGPMetric( GX_PERF0_VERTICES, GX_PERF1_TEXELS );<BR> GXClearGPMetric( );<BR> drawSphere();<BR> GXSetDrawSync(0xbabe);<BR> while (0xbabe != GXReadDrawSync())<BR> ;<BR> GXReadGPMetric(&verts, &texels);<BR> OSReport("vertices in sphere %d, texels %d\n", verts, texels);</CODE></DD></DL> 44<P>The <A href="GXReadGPMetric.html"><CODE>GXReadGPMetric</CODE></A> and <A href="GXClearGPMetric.html"><CODE>GXClearGPMetric</CODE></A> functions can be used in the callback associated with the render synchronization interrupt. See the <A href="../Management/GXSetDrawSyncCallback.html"><CODE>GXSetDrawSyncCallback</CODE></A> function. The <A href="GXSetGPMetric.html"><CODE>GXSetGPMetric</CODE></A> function should not be used in the render synchronization callback, because it will randomly insert tokens in the GP command stream.</P> 45<DL><DD><CODE>#define OBJECTS 3<BR> u32 count[OBJECTS][2]</CODE></BLOCKQUOTE> 46<BLOCKQUOTE><CODE>void myDrawSyncCallback( u16 token ) <BR> {<BR> GXReadGPMetric(&count[token-1][0], &count[token-1][1]);<BR> GXClearGPMetric();<BR> }</CODE></DD></DL> 47<DL><DD><CODE>void myDraw( void ) <BR> {<BR> GXSetDrawSyncCallback( myDrawSyncCallback );<BR> GXSetGPMetric( GX_PERF0_VERTICES, GX_PERF1_TEXELS );<BR> drawSphere();<BR> GXSetDrawSync(1);<BR> drawCube();<BR> GXSetDrawSync(2);<BR> drawCylinder();<BR> GXSetDrawSync(3);<BR> GXDrawDone();<BR> for (i = 0; i < OBJECTS; i++)<BR> OSReport("object %d: vertices %d, texels %d\n", i, count[i][0],<BR> count[i][1]);<BR> }</CODE></DD></DL> 48<P>Each performance counter has a unique set of events or ratios that it can count. In some cases the same metric can be counted using both counters. For example, there are <CODE>GX_PERF0_VERTICES</CODE> and <CODE>GX_PERF1_VERTICES</CODE>. Ratios (metric names ending in <CODE>_RATIO</CODE>) are multiplied by 1000 (1000 = all misses/clips, etc., 0 = no misses/clips, etc.).</P> 49 50<H3>Convenient Functions</H3> 51<P>The <A href="GXSetGPMetric.html"><CODE>GXSetGP0Metric</CODE></A>/<A href="GXReadGP0Metric.html"><CODE>GXReadGP0Metric</CODE></A> and <A href="GXSetGPMetric.html"><CODE>GXSetGP1Metric</CODE></A>/<A href="GXReadGP1Metric.html"><CODE>GXReadGP1Metric</CODE></A> functions can be used when you need to read only one counter. Be careful not to call the <A href="GXSetGPMetric.html"><CODE>GXSetGP0Metric</CODE></A>/<A href="GXReadGP0Metric.html"><CODE>GXReadGP0Metric</CODE></A> and <A href="GXSetGPMetric.html"><CODE>GXSetGP1Metric</CODE></A>/<A href="GXReadGP1Metric.html"><CODE>GXReadGP1Metric</CODE></A> functions simultaneously. Call the <A href="GXReadGPMetric.html"><CODE>GXReadGPMetric</CODE></A> function instead.</P> 52 53<H3>Counter 0 Details</H3> 54<H4>GX_PERF0_CLIP_VTX</H4> 55<P>Returns the number of vertices clipped by the GP.</P> 56 57<H4>GX_PERF0_CLIP_CLKS</H4> 58<P>Returns the number of GP clock cycles spent clipping.</P> 59 60<H4>GX_PERF0_XF_WAIT_IN<BR> GX_PERF0_XF_WAIT_OUT<BR> GX_PERF0_XF_XFRM_CLKS<BR> GX_PERF0_XF_LIT_CLKS<BR> GX_PERF0_XF_BOT_CLKS<BR> GX_PERF0_XF_REGLD_CLKS<BR> GX_PERF0_XF_REGRD_CLKS</H4> 61<P>The GP transform engine (XF) is a pipeline with an input stage, parallel transform, and lighting stages, and a 'bottom of pipe' processor which merges the results of lighting and texture coordinate generation. These performance counters measure how many cycles are spent in each stage of the XF.</P> 62<P><CODE>GX_PERF0_XF_WAIT_IN</CODE> measures how many cycles the XF spends waiting on input.<BR>If the XF is waiting for a large percentage of the total time, it may indicate that the CPU is not supplying data fast enough to keep the GP busy.</P> 63<P><CODE>GX_PERF0_XF_WAIT_OUT</CODE> measures how many cycles the XF spends waiting to send its output to the rest of the GP pipeline.<BR>If the XF cannot output, it may indicate that the GP is limited by the current fill-rate.</P> 64<P><CODE>GX_PERF0_XF_XFRM_CLKS</CODE> indicates the number of cycles during which the conversion engine is busy.<BR><CODE>GX_PERF0_XF_LIT_CLKS</CODE> indicates the number of cycles during which the lighting engine is busy.<BR><CODE>GX_PERF0_BOT_CLKS</CODE> indicates the number of cycles during which the bottom of the pipe is busy.</P> 65<P>The XF contains state registers that control its processing. These registers are normally set using various GX API functions.<BR><CODE>GX_PERF0_XF_REGLD_CLKS</CODE> measures how many cycles are spent loading XF registers and <CODE>GX_PERF0_XF_REGRD_CLKS</CODE> measures for how many cycles the XF reads the state registers.</P> 66 67<H4>GX_PERF0_TRIANGLES*</H4> 68<P>The triangle metrics allow for the counting of triangles under specific conditions or with specific attributes.<BR><CODE>GX_PERF0_TRIANGLES</CODE> counts all triangles. <BR><CODE>GX_PERF0_TRIANGLES_CULLED</CODE> counts triangles that failed the front/back-face culling test.<BR><CODE>GX_PERF0_TRIANGLES_PASSED</CODE> counts triangles that passed that test.<BR><CODE>GX_PERF0_TRIANGLES_SCISSORED</CODE> counts the scissored triangles.</P> 69<P>The <CODE>GX_PERF0_TRIANGLES_*TEX</CODE> metrics count triangles based on the number of texture coordinates supplied.<BR>The <CODE>GX_PERF0_TRIANGLES_*CLR</CODE> metrics count triangles based on the number of colors supplied.</P> 70 71<H4>GX_PERF0_QUAD*</H4> 72<P>The rectangle metrics allow you to count the number of rectangles (2x2 pixel units, or quads) the GP processed.<BR><em>Coverage</em> is used to indicate how many pixels in the quad are actually part of triangles being rasterized. For example, a coverage of 4 means all pixels in the quad intersect triangles.<BR>A coverage of 1 indicates that only 1 pixel in the quad intersects a triangle.</P> 73<P><CODE>GX_PERF0_QUAD_0CVG</CODE> indicates the number of quads with 0 coverage.<BR><CODE>GX_PERF0_QUAD_NON0CVG</CODE> counts the number of quads that have greater than zero coverage.<BR><CODE>GX_PERF0_QUAD_[1-4]CVG</CODE> counts the quads with a given coverage.</P> 74<P><CODE>GX_PERF0_AVG_QUAD_CNT</CODE> indicates the average quad count.</P> 75 76<H4>GX_PERF0_CLOCKS</H4> 77<P><CODE>GX_PERF0_CLOCKS</CODE> counts the number of GP clock cycles that have elapsed since the previous <A href="GXReadGP0Metric.html"><CODE>GXReadGP0Metric</CODE></A> function call.</P> 78 79<H4>GX_PERF0_NONE</H4> 80<P>This metric is used to disable counting on GP counter 0 and clears the current count.</P> 81 82<H3>Counter 1 Details</H3> 83<H4>GX_PERF1_TEXELS</H4> 84<P>This metric returns the number of texels processed by the GP.</P> 85 86<H4>GX_PERF1_TX_IDLE</H4> 87<P>Returns the number of clock cycles for which the texture unit (TX) is idle.</P> 88 89<H4>GX_PERF1_TX_REGS</H4> 90<P>Returns the number of GP clock cycles spent writing to state registers in the TX unit.</P> 91 92<H4>GX_PERF1_TX_MEMSTALL</H4> 93<P>Returns the number of GP clock cycles the TX unit is stalled while waiting for main memory.</P> 94 95<H4>GX_PERF1_TC_CHECK1_2<BR> GX_PERF1_TC_CHECK3_4<BR> GX_PERF1_TC_CHECK5_6<BR> GX_PERF1_TC_CHECK7_8<BR> GX_PERF1_TC_MISS</H4> 96<P>These metrics can be used to compute the texture cache (TC) miss rate. The <SPAN class="argument">TC_CHECK*</SPAN> arguments count how many texture cache lines are accessed for each pixel. In the worst case, for a mipmap, up to 8 cache lines may be accessed to produce one textured pixel. <CODE>GX_PERF1_TC_MISS</CODE> counts the number of accesses with the texture cache. </P> 97<P>To compute the cache miss rate, compute:</P> 98<DL><DD><CODE>GX_PERF1_TC_MISS / (GX_TC_PERF1_TC_CHECK1_2 + GX_PERF1_TC_CHECK3_4 + GX_PERF1_TC_CHECK_5_6 + GX_PERF1_TC_CHECK_7_8)</CODE></DD></DL> 99 100<H4>GX_PERF1_VC_ELEMQ_FULL<BR> GX_PERF1_VC_MISSQ<BR> GX_PERF1_VC_MEMREQ_FULL<BR> GX_PERF1_VC_STATUS7<BR> GX_PERF1_VC_MISSREP_FULL<BR> GX_PERF1_VC_STREAMBUF_LOW<BR> GX_PERF1_VC_ALL_STALLS</H4> 101<P>These metrics count different vertex cache stall conditions.</P> 102 103<H4>GX_PERF1_VERTICES</H4> 104<P>This metric returns the number of vertices processed by the GP.</P> 105 106<H4>GX_PERF1_FIFO_REQ</H4> 107<P>This metric counts the number of (32-byte) lines read from the GP FIFO.</P> 108 109<H4>GX_PERF1_CALL_REQ</H4> 110<P>This metric counts the number of (32-byte) lines read from called display lists (<CODE>GXCallDisplayList</CODE>).</P> 111 112<H4>GX_PERF1_VC_MISS_REQ</H4> 113<P>This metric counts the number of vertex cache miss requests. Each miss request is in the form of a 32-byte transfer from main memory.</P> 114 115<H4>GX_PERF1_CP_ALL_REQ</H4> 116<P>This metric counts all requests (32 bytes per request) from the GP command processor (CP).<BR>It should be equal to the sum of counts returned by <CODE>GX_PEF1_FIFO_REQ</CODE>, <CODE>GX_PERF1_CALL_REQ</CODE> and <CODE>GX_PERF1_VC_MISS_REQ</CODE>.</P> 117 118<H4>GX_PERF1_CLOCKS</H4> 119<P><CODE>GX_PERF1_CLOCKS</CODE> counts the number of GP clock cycles that have elapsed since the previous call to the <A href="GXReadGP1Metric.html"><CODE>GXReadGP1Metric</CODE></A> function.</P> 120 121<H4>GX_PERF1_NONE</H4> 122<P>This metric is used to disable counting on GP counter 1 and clears the current count.</P> 123 124<H2>See Also</H2> 125<P class="reference"> 126<A href="GXReadMemMetric.html">GXReadMemMetric</A>, 127<A href="GXClearMemMetric.html">GXClearMemMetric</A>, 128<A href="GXReadPixMetric.html">GXReadPixMetric</A>, 129<A href="GXClearPixMetric.html">GXClearPixMetric</A>, 130<A href="GXSetVCacheMetric.html">GXSetVCacheMetric</A>, 131<A href="GXReadVCacheMetric.html">GXReadVCacheMetric</A>, 132<A href="GXClearVCacheMetric.html">GXClearVCacheMetric</A> 133</P> 134 135<H2>Revision History</H2> 136<P> 1372006/03/01 Initial version.<br> 138</P> 139 140<hr><p>CONFIDENTIAL</p></body> 141</HTML>