pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)NAME
pfNewStats, pfGetStatsClassType, pfStatsClass, pfGetStatsClass,
pfStatsClassMode, pfGetStatsClassMode, pfOpenStats, pfCloseStats,
pfGetOpenStats, pfCollectGfxPipeStats, pfGetStatsNumGfxPipeTimestamp,
pfStatsAttr, pfGetStatsAttr, pfStatsHwAttr, pfGetStatsHwAttr,
pfEnableStatsHw, pfDisableStatsHw, pfGetStatsHwEnable, pfCopyStats,
pfResetStats, pfClearStats, pfStatsCountGSet, pfAccumulateStats,
pfAverageStats, pfQueryStats, pfMQueryStats, pfGetCurStats,
pfGfxPipeTimestamp, pfGetStatsGfxPipeTimestampStatus - Maintain
statistics on OpenGL Performer operations and system usage
FUNCTION SPECIFICATION
#include <Performer/pr.h>
#include <Performer/prstats.h>
pfStats * pfNewStats(void *arena);
pfType * pfGetStatsClassType(void);
uint pfStatsClass(pfStats *stats, uint enmask, int val);
uint pfGetStatsClass(pfStats *stats, uint enmask);
uint pfStatsClassMode(pfStats *stats, int class, uint mask,
int val);
uint pfGetStatsClassMode(pfStats *stats, int class);
uint pfOpenStats(pfStats *stats, uint enmask);
uint pfCloseStats(uint enmask);
uint pfGetOpenStats(pfStats *stats, uint enmask);
uint pfCollectGfxPipeStats(pfStats* stats, uint enmask);
int pfGetStatsNumGfxPipeTimestamp(pfStats* stats);
void pfStatsAttr(pfStats *fstats, int attr, float val);
float pfGetStatsAttr(pfStats *fstats, int attr);
void pfStatsHwAttr(int attr, float val);
float pfGetStatsHwAttr(int attr);
void pfEnableStatsHw(uint which);
void pfDisableStatsHw(uint which);
Page 1
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
uint pfGetStatsHwEnable(uint which);
void pfCopyStats(pfStats *dst, pfStats *src, uint which);
void pfResetStats(pfStats *stats);
void pfClearStats(pfStats *stats, uint which);
void pfStatsCountGSet(pfStats *stats, pfGeoSet *gset);
void pfAccumulateStats(pfStats *dst, pfStats *src, uint which);
void pfAverageStats(pfStats *dst, pfStats *src, uint which,
int num);
int pfQueryStats(pfStats *stats, uint which, void *dst,
int size);
int pfMQueryStats(pfStats *stats, uint *which, void *dst,
int size);
pfStats * pfGetCurStats(void);
void pfGfxPipeTimestamp(uint flag);
int pfGetStatsGfxPipeTimestampStatus(pfStats* stats, uint stamp);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfStats is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfStats. Casting an object of
class pfStats to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfStats can also be used with these functions
designed for objects of class pfMemory.
Page 2
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
DESCRIPTION
These functions are used to collect, manipulate, print, and query
statistics on state operations, geometry, and graphics and system
operations.
pfNewStats creates and returns a handle to a pfStats. arena specifies a
malloc arena out of which the pfStats is allocated or NULL for allocation
off the process heap. pfStats can be deleted with pfDelete.
pfGetStatsClassType returns the pfType* for the class pfStats. The
pfType* returned by pfGetStatsClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfStats. Because
OpenGL Performer allows subclassing of built-in types, when decisions are
made based on the type of an object, it is usually better to use
pfIsOfType to test if an object is of a type derived from a Performer
type rather than to test for strict equality of the pfType*'s.
pfResetStats takes a pointer to a statistics structure, stats, and will
reset that entire statistics structure to its initial state.
pfClearStats takes a pointer to a statistics structure, stats, and a
bitmask which specifying the statistics that are to be cleared to zeroes.
pfCopyStats takes pointers to statistics structures, dst and src, and a
bitmask which specifying the statistics that are to be copied from src to
dst. This function is provided to enable more control over the default
pfObject function pfCopy. Note that only statistics data is copied and
not any enable/disable settings or modes.
Since some statistics can be expensive to gather, and so might possibly
influence other statistics, statistics are divided into different classes
based on the tasks that they monitor and one may select the specific
statistics classes of interest with pfStatsClass.
Statistics classes also have different modes of collection so that
Page 3
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
performance-expensive modes of a particular statistics class many be
disabled with pfStatsClassMode. The statistics class enables may be used
for directing operations on statistics structures, including statistics
collection, specified via pfOpenStats, and also for printing, copying,
clearing, accumulation, and averaging.
Class enables and disables are specified with bitmasks. Each statistics
class has an enable token: a PFSTATS_EN* token that can be OR-ed with
other statistics enable tokens and the result passed in to enable and
disable statistics operations.
Statistics classes that require special hardware support have token names
that start with PFSTATSHW_. These tokens are used as class enable tokens
in the usual statistics routines, and also to enable and disable the
hardware statistics gathering via pfEnableStatsHw and pfDisableStatsHw.
Statistics classes also have modes that select different elements of a
class for collection. These modes are set through pfStatsClassMode.
Each statistics class starts with a default mode setting.
The following tables provide details of the statistics class structure.
The first table lists the statistics classes, their naming tokens, and
their enable tokens for forming bitmasks.
Statistics Class Table
_______________________________________________________________________
Class PFSTATS_ Token PFSTATS_EN token
_______________________________________________________________________
Graphics Rendered PFSTATS_GFX PFSTATS_ENGFX
Pixel Fill PFSTATSHW_GFXPIPE_FILL PFSTATSHW_ENGFXPIPE_FILL
CPU PFSTATSHW_CPU PFSTATSHW_ENCPU
GfxPipe PFSTATSHW_GFXPIPE_TIMES PFSTATSHW_ENGFXPIPE_TIMES
_______________________________________________________________________
|
|
This second table defines the statistics classes and their naming token
and enable tokens for forming bitmasks.
Statistics Mode Table
___________________________________________________________________________
Class PFSTATS_ Token Modes
___________________________________________________________________________
Graphics PFSTATS_GFX PFSTATS_GFX_GEOM
Rendered PFSTATS_GFX_TSTRIP_LENGTHS
PFSTATS_GFX_ATTR_COUNTS
PFSTATS_GFX_STATE
PFSTATS_GFX_XFORM
PFSTATS_GFX_CULL_SIDEKICK
Pixel Fill PFSTATSHW_GFXPIPE_FILL PFSTATSHW_GFXPIPE_FILL_DEPTHCMP
PFSTATSHW_GFXPIPE_FILL_TRANSPARENT
|
|
Page 4
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
CPU PFSTATSHW_CPU PFSTATSHW_CPU_SYS
PFSTATSHW_CPU_IND
GfxPipe PFSTATSHW_GFXPIPE_TIMES PFSTATSHW_GFXPIPE_TIMES_TOTAL
PFSTATSHW_GFXPIPE_TIMES_AUTO_COLLECT
___________________________________________________________________________
|
|
The individual stats classes and modes are discussed in more detail in
the explanation of the statistics routines.
pfStatsClass takes a pointer to a statistics structure, stats, and will
set the classes specified in the bitmask, enmask, according to the val,
which must be set to one of the following:
PFSTATS_ON Enables the specified classes.
PFSTATS_OFF Disables the specified classes.
PFSTATS_DEFAULT Resets the specified classes to default
values.
PFSTATS_SET Sets the entire class enable mask to
enmask.
All stats collection can be set at once to on, off, or the default by
using PFSTATS_ALL for the bitmask and the appropriate value for the
enable flag. For example, the following example disables all stats
classes with their current class mode settings.
pfStatsClass(stats, PFSTATS_ALL, PFSTATS_OFF);
pfGetStatsClass takes a pointer to a stats structure, stats, and the
statistics classes of interest specified in the bitmask, enmask. If any
of the statistics classes specified in enmask are enabled, then
pfGetStatsClass will return the bitmask of those classes, and otherwise,
will return zero. If classes of an open pfStats structure are disabled,
then collection of those classes stop immediately and those classes are
considered closed.
pfStatsClassMode takes a pointer to a stats structure, stats, the name of
the class to set, class, a mask of the modes to set, mask, and the value
for the modes, val. The class modes offer further control over the
statistics that are to be accumulated for a given class. For each
statistics class, a set of modes is enabled by default. Some modes of a
statistics class may be somewhat expensive, and therefore they are not
enabled by default. val must be one of:
Page 5
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
PFSTATS_ON Enable the modes specified in mask.
PFSTATS_OFF Disable the modes specified in mask.
PFSTATS_DEFAULT Set modes specified in mask to default
values.
PFSTATS_SET Set class mode mask to the specified mask.
As a convenience, all classes may have all of their modes set to on, off,
or their default values by specifying a class of PFSTATS_CLASSES, and a
mask of PFSTATS_ALL. These defaults may differ between machines and may
change in the future; so, code should not assume the current defaults but
query the mode values for a given class where needed. No statistics for
a given mode are accumulated unless the corresponding class has been
enabled with pfStatsClass. If modes of an open pfStats structure are
disabled, then collection of those modes stop immediately.
Graphics Statistics Modes
PFSTATS_GFX_GEOM
This counts geometry that is drawn via pfDrawGSet. Statistics
include the number of pfGeoSets drawn, and the numbers of
pfGeoSets that have each binding of each attribute, colors,
normals, texture coordinates. The number of each type of
pfGeoSet primitive is counted, as well as the number of base
primitives drawn: total triangles, lines, and points.
Statistics are also kept on the number of triangle strips drawn
and the number of the total triangles that were actually in a
triangle strip. This mode is enabled by default.
PFSTATS_GFX_TSTRIP_LENGTHS
The number of triangles in strips whose length in terms of
triangle count is shorter than PFSTATS_TSTRIP_LENGTHS_MAX is
recorded. Triangles in strips whose triangle count is greater
than or equal to PFSTATS_TSTRIP_LENGTHS_MAX are all counted
together. Quads are counted as strips of length two and
independent triangles are counted as strips of length one. An
average triangle strip length (that uses all of the actual
lengths) is also maintained. Keeping these triangle strip
statistics is expensive for the drawing operation and so this
mode is not enabled by default, but must be enabled with
pfStatsClassMode.
PFSTATS_GFX_ATTR_COUNTS
The number of each of the different types of geometry
attributes (colors, normals, and texture coordinates) that are
drawn is counted. Keeping attribute statistics is expensive
for the drawing operation and so this mode is not enabled by
default, but must be enabled with pfStatsClassMode.
Page 6
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
PFSTATS_GFX_STATE
This mode enables the counting of calls to state changes, as
well as the number of actual state changes themselves. Such
state changes include the immediate mode routines such as
pfAntialias, and the application of the state structures, such
as pfApplyTex. Also counted is the number of pfGeoStates
encountered and the number of state stack operations, such as
pfLoadGState, pfApplyGState, pfPushState, and pfPopState. This
mode is enabled by default.
PFSTATS_GFX_XFORM
This mode enables the counting of calls to transformations,
such as pfTranslate, pfScale, and pfRotate, and graphics matrix
stack operations, such as pfLoadMatrix, etc. the number of
actual state changes themselves, as well as the number of
pfGeoStates encountered. This mode is enabled by default.
PFSTATS_GFX_CULL_SIDEKICK
This mode enables counting OpenGL primitives removed by a
CULL_SIDEKICK process.
Graphics Pipe Fill Statistics
These modes enable the accumulation of fill depth-complexity statistics
and require the corresponding hardware statistics to be enabled:
pfEnableStatsHw(PFSTATSHW_GFXPIPE_FILL_DEPTHCMP);
PFSTATSHW_GFXPIPE_FILL_DCPAINT
This mode causes pfCloseStats to paint the screen according to
the number of times each pixel is touched. This mode is
enabled by default.
PFSTATSHW_GFXPIPE_FILL_DCCOUNT
This mode causes pfCloseStats to read back the framebuffer for
the calculation of fill depth-complexity statistics. This mode
is enabled by default.
PFSTATSHW_GFXPIPE_FILL_DEPTHCMP
By default, only actual pixel writes are counted with depth
complexity stats. This mode enables counting of Z compares as
well. This mode is not enabled by default.
PFSTATSHW_GFXPIPE_FILL_TRANSP
This mode enables counting of fully transparent pixels. This
mode is not enabled by default.
CPU Statistics
The CPU statistics keep track of system usage and requires that the
Page 7
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
corresponding hardware statistics be enabled:
pfEnableStatsHw(PFSTATSHW_ENCPU);
The percentage of time CPUs spend idle, busy, in user code, and waiting
on the Graphics Pipeline, or on the swapping of memory is calculated.
Counted is the number of context switches (process and graphics), the
number of system calls, the number of times the graphics FIFO is found to
be full, the number of times a CPU went to sleep waiting on a full
graphics FIFO, the number of graphics pipeline IOCTLs issued (by the
system), and the number of swapbuffers seen. All of these statistics are
computed over an elapsed period of time, and using an elapsed interval of
at least one second is recommended.
PFSTATSHW_CPU_SYS
This mode enables computation of the above CPU statistics for
the entire system. This includes statistics on system usage,
cpu-graphics interactions, and memory. CPU usage statistics
are summed over all CPUs. This mode is enabled by default.
PFSTATSHW_CPU_IND
This mode enables tracking of CPU statistics for each
individual CPU and is much more expensive than using just the
summed statistics. It is not enabled by default.
pfGetStatsClassMode takes a pointer to a stats structure, stats, and the
name of the class to query, class. The return value is the mode of
class.
pfOpenStats takes a pointer to a stats structure, stats, and a bitmask
specifying the statistics classes that are to be opened for collection in
enmask. This statistics structure will become the one and only
statistics structure open for collection. The return value will be the
bitmask for all currently open statistics classes. If another pfStats
structure is already open, then this call to pfOpenStats will be ignored
and the return value will be 0. When statistics classes that use
statistics hardware are open for collection, pfOpenStats will access that
hardware for initialization. Therefore, for graphics pipe statistics, it
is imperative that the statistics hardware only be enabled for the
drawing process. Furthermore, only one process at a time should use
statistics hardware since it is a shared global resource. Finally, for
statistics that are actually accumulated in statistics hardware, it is
best to let some time elapse before the statistics are collected (in
pfCloseStats). Refer the examples at the end of this manual page.
pfCloseStats takes a bitmask which specifying the classes whose collected
statistics are to be accumulated into the current pfStats structure.
Further collection of these statistics are then disabled and they will
have to be re-opened with pfOpenStats for further collection. A pfStats
structure is considered to be open until all opened statistics classes
have been closed with pfCloseStats. The return value for pfCloseStats is
Page 8
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
the bitmask of the remaining open classes. If stats has no open classes,
a value of 0 will be returned. When statistics classes that use
statistics hardware are open for collection, pfCloseStats will access
that hardware to collect the specified statistics. Therefore, for
graphics pipe statistics, it is imperative that the statistics hardware
only be enabled for the drawing process. Furthermore, only one processes
should be using statistics hardware at a time since it is a shared global
resource.
pfGetOpenStats takes a pointer to a stats structure, stats, a bitmask
enmask specifying the statistics classes that are being queried. If any
of the statistics classes specified in enmask are open for collection,
then the bitmask of those statistics classes is returned, and otherwise,
zero.
pfGetCurStats returns the currently open statistics structure, or NULL if
there is no statistics structure open for accumulation.
pfGfxPipeTimestamp allows the specification of a PFSTATSHW_TIMETAMP_
token for the currently open pfStats structure with
PFSTATSHW_GFXPIPE_TIMES enabled. These tokens may be one of the following
and must be issued once per collection period and in increasing order.
PFSTATSHW_TIMESTAMP_START
signal start of drawing.
PFSTATSHW_TIMESTAMP_END
signal end of drawing.
PFSTATSHW_TIMESTAMP_FRAME_END
signals end of frame and is automatically followed by a
PFSTATSHW_TIMESTAMP_FINISH to flush graphics pipeline.
PFSTATSHW_TIMESTAMP_FINISH
will flush the graphics pipeline to ensure that all drawing is
including in the timing.
The PFSTATSHW_TIMESTAMP_OPEN and PFSTATSHW_TIMESTAMP_CLOSE may be issued
only by OpenGL Performer and these are issued automatically when
PFSTATSHW_GFXPIPE_TIMES statistics are opened and closed.
pfGetStatsGfxPipeTimestampStatus may be used to find out if a given
timestamp for the specified pfStats structure has completed its trip
through the graphics pipeline (and has resulting data ready for
collection).
pfCollectGfxPipeStats may be used to collect graphics pipeline
statistics for a structure after the statistics for that structure have
been closed. Graphics pipeline statistics must be gathered in the same
order that the timestamps are issued. If separate collection of graphics
pipeline statistics are to be done, the pfStatsClassMode of
PFSTATSHW_GFXPIPE_TIMES_AUTO_COLLECT (which is on by default) must be
turned off.
Page 9
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
pfStatsAttr takes a pointer to a stats structure, stats, the name of the
attribute to set, attr, and the attribute value, val. Currently, there
are no pfStats attributes. pfGetStatsAttr takes a pointer to a stats
structure, stats, and the name of the attribute to query, attr. The
return value is that of attribute attr.
pfEnableStatsHw takes a bitmask which specifying the hardware statistics
that should be enabled. These bitmasks are the statistics class enable
bitmasks that have start with PFSTATSHW_*. Statistics hardware must be
enabled for the corresponding classes of statistics to be accumulated.
Having statistics hardware enabled will have some cost to performance;
however, in most cases, it pays to leave this hardware enabled if
corresponding statistics classes are being frequently enabled and
disabled. When statistics classes that use statistics hardware are open
for collection, pfOpenStats and pfCloseStats will access that hardware.
For graphics pipe statistics, it is therefore imperative that the
statistics hardware only be enabled for a process that is connected to
the graphics pipeline. Furthermore, only one processes should be using
statistics hardware at a time since it is a shared global resource.
Graphics Statistics Hardware Enables
PFSTATSHW_ENGFXPIPE_TIMES
Enables the tracking of timestamps in the graphics pipeline.
This produces very accurate measurements of elapsed drawing
times with minimal impact. Timestamps are issued automatically
when statistics are opened and closed, and additional stamps
may be issued with pfGfxPipeTimestamp.
PFSTATSHW_ENGFXPIPE_FILL
Enables hardware to support tracking of depth complexity
statistics. When this mode is enabled, the framebuffer keeps
track of the number of times each pixel is touched. This may
require a framebuffer reconfiguration which can be quite
expensive, and which may not be possible in GLX windows.
PFSTATSHW_ENCPU
This mode enable gathering of CPU statistics by the system.
This mode should only be enabled by one process at a time.
pfDisableStatsHw takes a bitmask which specifying the hardware statistics
that should be disabled.
pfGetStatsHwEnable takes a bitmask which specifying the hardware
statistics that are being queried. If any of the hardware statistics
classes specified in which have their corresponding hardware enabled,
then the bitmask of those statistics classes is returned, and otherwise,
zero is returned.
pfStatsHwAttr takes the name of the attribute to set, attr, and the
attribute value, val. There is currently one stats hardware attribute:
PFSTATSHW_FILL_DCBITS. Its value must be an integer value in the range
Page 10
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
of 1 to 4. The default value is 3. This attribute sets the maximum
number of stencil bits used for tracking fill depth complexity. See the
GL manual page for stensize(3g) for more information on stencil
bitplanes.
pfGetStatsHwAttr Returns the value of attribute attr.
Collected statistics can be printed to stderr or a file with pfPrint, and
can be queried at run-time with pfQueryStats for a single-value query,
and pfMQueryStats for getting back a collection of statistics.
pfQueryStats takes a pointer to a statistics structure, stats, a query
token in which, and a destination buffer dst. The size of the expected
return data is specified by size and if non-zero, will prevent
pfQueryStats from writing beyond a buffer that is too small. The return
value is the number of bytes written to the destination buffer. There
are tokens for getting back all of the statistics, entire sub-structures,
and individual values. The exposed query structure types and query
tokens are all defined in <Performer/prstats.h>. Every structure and
field is commented with its corresponding query token. For example, the
exposed structure type pfStatsValues can be used to hold the entire
contents of a pfStats structure and has corresponding query token
PFSTATSVAL_ALL.
typedef struct pfStatsValues
{ /* to get back all stats: PFSTATSVAL_ALL */
/* PFSTATS_GFX class: PFSTATSVAL_GFX */
pfStatsValGeom geom; /* PFSTATSVAL_GFX_GEOM */
pfStatsValModes modeChanges; /* PFSTATSVAL_GFX_MODECHANGES */
pfStatsValModes modeCalls; /* PFSTATSVAL_GFX_MODECALLS */
pfStatsValState state; /* PFSTATSVAL_GFX_STATE */
pfStatsValXforms xform; /* PFSTATSVAL_GFX_XFORM */
/* PFSTATSHW_GFXPIPE_FILL class: PFSTATSVAL_GFXPIPE_FILL */
pfStatsValFill fill; /* PFSTATSVAL_GFXPIPE_FILL */
/* the PFSTATSHW_CPU class: PFSTATSVAL_CPU */
pfStatsValCPU cpu; /* PFSTATSVAL_CPU */
} pfStatsValues;
The following example will return all of the contents of a pfStats
structure into the contents of a structure of the exposed type
pfStatsValues.
pfStats *stats;
pfStatsValues *val;
pfQueryStats(stats, PFSTATSVAL_ALL, (float *) val, sizeof(pfStatsValues));
pfMQueryStats takes a pointer to a statistics structure, stats, a pointer
to the start of an array of query tokens in which, and a destination
Page 11
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
buffer dst. The array which must be terminated with the token
PFSTATSVAL_NULL. The size of the expected return data is specified by
size and if non-zero, will prevent pfMQueryStats from writing beyond a
buffer that is too small. The return value is the number of bytes
written to the destination buffer.
pfStatsCountGSet takes a pointer to a statistics structure, stats, and a
pointer to a pfGeoSet, gset, whose geometry statistics are to be
accumulated into stats.
pfAccumulateStats takes pointers to statistics structures, dst and src,
and a bitmask which specifying the statistics that are to be accumulated
from src to dst.
pfAverageStats takes pointers to statistics structures, dst and src, and
a bitmask which, and an integer num. The statistics classes specified by
which will be taken from src, averaged by dviding by num, and the result
placed in dst.
For a class of statistics to be collected, the following must be true:
1. A statistics structure must be created.
2. The corresponding statistics class must be enabled with
pfStatsClass. No statistics classes are enabled by default.
3. The corresponding statistics class mode must be enabled with
pfStatsClassMode. However, each statistics class has a popular
set of statistics modes enabled by default.
4. Any relevant hardware must be enabled via pfEnableStatsHw.
5. The statistics class must be opened for collection with
pfOpenStats.
EXAMPLES
This example creates a statistics structure and enabling the graphics
statistics class with the triangle-strip statistics enabled.
pfStats *stats = NULL;
stats = pfNewStats(NULL);
pfStatsClass(stats, PFSTATS_ENGFX, PFSTATS_ON);
pfStatsClassMode(stats, PFSTATS_GFX, PFSTATS_GFX_TSTRIP_LENGTHS, PFSTATS_ON);
This is an example of collecting CPU statistics over an elapsed period of
time.
Page 12
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)
pfStats *stats = NULL;
double lastTime = 0;
stats = pfNewStats(NULL);
/* enable the CPU stats class - using the default summed CPU statistics */
pfStatsClass(stats, PFSTATSHW_ENCPU, PFSTATS_ON);
/* enable CPU stats hardware */
pfEnableStatsHw(PFSTATSHW_ENCPU);
:
/* snap CPU stats every 2 seconds */
if (pfGetTime() - lastTime > 2.0)
{
if (pfGetOpenStats(stats, PFSTATSHW_ENCPU))
{
/*
* final snap of CPU stats is done here and difference
* between this and the initial snap is calculated.
*/
pfCloseStats(PFSTATSHW_ENCPU);
}
else
{
/* initial snap of CPU stats is done here */
pfOpenStats(stats, PFSTATSHW_ENCPU);
}
}
This example shows the enabling and disabling of fill statistics.
pfStats *stats = NULL;
stats = pfNewStats(NULL);
/* enable fill statistics collection */
pfStatsClass(stats, PFSTATSHW_ENGFXPIPE_FILL, PFSTATS_ON);
/* enable fill stats hardware - put framebuffer in correct configuration */
pfEnableStatsHW(PFSTATSHW_ENGFXPIPE_FILL);
/* open fill statistics collection and initialize hardware */
pfOpenStats(stats, PFSTATSHW_ENGFXPIPE_FILL);
/* draw geometry */
:
/*
* paint window by number of times each pixel was touched in the
* previous drawing and read back the framebuffer and
* examine the counts
*/
pfCloseStats(PFSTATSHW_ENGFXPIPE_FILL);
Page 13
pfStats(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfStats(3pf)NOTES
Fill stats are currently calculated by using stencil tests and therefore
require stencil bitplanes to be allocated. Furthermore, the
PFSTATSHW_GFXPIPE_FILL_TRANSP mode currently disables modes that reject
fully transparent pixels, such as pfAlphaFunc, which will alter what
pixels get written into the zbuffer and therefore should be used in
conjunction with PFSTATSHW_GFXPIPE_FILL_DEPTHCMP.
The pfStats routines, structures, and constants are defined in the
<Performer/prstats.h> header file.
BUGS
None
SEE ALSO
pfDelete, pfPrint
Page 14
