pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
NAMEpfFrameStats - Specify pfFrameStats modes and get collected values.
FUNCTION SPECIFICATION
#include <Performer/pf/pfFrameStats.h>
pfFrameStats::pfFrameStats();
static pfType* pfFrameStats::getClassType(void);
void pfFrameStats::draw(pfChannel *chan);
void pfFrameStats::copy(uint dSel, pfFrameStats *src,
uint sSel, uint classes);
uint pfFrameStats::getOpen(pfFrameStats *fstats, uint emask);
uint pfFrameStats::open(pfFrameStats *fstats, uint enmask);
uint pfFrameStats::close(uint enmask);
void pfFrameStats::countNode(int class, uint mode,
pfNode * node);
uint pfFrameStats::setClass(uint enmask, int val);
uint pfFrameStats::getClass(uint enmask);
uint pfFrameStats::setClassMode(int class, uint mask,
int val);
uint pfFrameStats::getClassMode(int class);
void pfFrameStats::setAttr(int attr, float val);
float pfFrameStats::getAttr(int attr);
void pfFrameStats::copy(pfFrameStats *src, uint dSel,
uint sSel, uint classes);
void pfFrameStats::reset(void);
void pfFrameStats::clear(uint which);
void pfFrameStats::count(pfGeoSet * gset);
void pfFrameStats::accumulate(pfFrameStats* src, uint which);
void pfFrameStats::average(pfFrameStats* src, uint which,
int num);
Page 1
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
int pfFrameStats::query(uint which, float *dst, int size);
int pfFrameStats::mQuery(uint *which, float *dst, int size);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfFrameStats is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfFrameStats. This is also true
for ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfFrameStats can also be used with these
functions designed for objects of class pfMemory.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
The pfFrameStats utilities provide for the collection of statistics about
all parts of OpenGL Performer processing of a scene for a given frame.
These statistics can be kept automatically on every pfChannel, or users
may accumulate and store their own statistics. Routines for operating
on, displaying, and printing statistics are also provided.
The frame statistics for a channel are fetched by first getting the
Page 2
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
pointer to the channel's statistics structure with pfChannel::getFStats,
and then enabling the desired statistics classes. When a channel is
automatically accumulating frame statistics, it enables the necessary
statistics hardware and statistics accumulation in the correct processes.
The resulting collected statistics can then be displayed in a channel,
queried, or printed. These statistics may be accumulated and averaged
over a specified number of frames or seconds. The pfFrameStats
declarations are contained in pfstats.h. The class of process frame
timing statistics for each of the OpenGL Performer processes of
application, cull and draw, is enabled by default.
Many pfFrameStats member functions are borrowed (but not inherited) from
the pfStats class:
accumulate
average
clear
close
copy
getOpen
setAttr
setClass
setClassMode
getClassMode
count
getAttr
getClass
mQuery
open
query
reset
These functions accept identical parameters to their counterparts in
pfStats. Refer to the pfStats man page for detailed descriptions of
these routines.
pfFrameStats::getClassType returns the pfType* for the class
pfFrameStats. The pfType* returned by pfFrameStats::getClassType is the
same as the pfType* returned by invoking the virtual function getType on
any instance of class pfFrameStats. 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 the member function isOfType
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.
The pfFrameStats structure stores accumulated statistics in several
buffers. The following is a list of the frame statistics buffers:
PFFSTATS_BUF_PREV Statistics for previous completed
frame
Page 3
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
PFFSTATS_BUF_CUR Buffer for current statistics
collection
PFFSTATS_BUF_CUM Statistics accumulated since last
update
PFFSTATS_BUF_AVG Statistics averaged over previous
update period
These different buffers can be queried with pfFrameStats::query and
printed with pfMemory::print. The desired PFFSTATS_BUF_* token is simply
bitwise OR-ed with the desired statistics value token.
The following table of additional frame statistics classes, their naming
token, and their enable token for forming bitmasks. Notice that
pfFrameStats tokens start with PFFSTATS*.
Frame Statistics Class Table
___________________________________________________________
Class PFSTATS_* Token PFSTATS_EN* token
___________________________________________________________
Process frame times PFFSTATS_PFTIMES PFFSTATS_ENPFTIMES
Database PFFSTATS_DB PFFSTATS_ENDB
Cull PFFSTATS_CULL PFFSTATS_ENCULL
|
|
This table lists the frame statistics modes and tokens.
Frame Statistics Class Mode Table
_______________________________________________________________
Class PFSTATS_ Token Modes
_______________________________________________________________
Process frame times PFFSTATS_PFTIMES PFFSTATS_PFTIMES_BASIC
PFFSTATS_PFTIMES_HIST
Database PFFSTATS_DB PFFSTATS_DB_VIS
PFFSTATS_DB_EVAL
Cull PFFSTATS_CULL PFFSTATS_CULL_TRAV
|
|
new pfFrameStats creates and returns a handle to a pfFrameStats.
pfFrameStats are always allocated from shared memory and cannot be
created statically, on the stack or in arrays. pfFrameStats should be
deleted using pfDelete rather than the delete operator. A pfFrameStats
structure contains pfStats statistics as well as additional statistics
classes and support for tracking frame related tasks.
Only the additional support for pfFrameStats above and beyond that of new
pfStats is discussed here.
pfFrameStats::draw displays the pfFrameStats structure fstats in the
Page 4
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
channel specified by chan. This is useful for displaying the statistics
in a special channel separate from the main scene channel.
pfChannel::drawStats may be called from OpenGL Performer's application,
cull, or draw processes and must be called each frame a statistics
display is desired. See pfChannel::drawStats for a detailed explanation
of the channel statistics display.
pfFrameStats::setClass takes a pointer to a statistics structure, fstats,
and will set the classes specified in the bitmask, enmask, according to
the val, which is one of the following:
PFSTATS_ON Enables the specified classes.
PFSTATS_OFF Disables the specified classes.
PFSTATS_DEFAULT Sets the specified classes to their
default values.
PFSTATS_SET Sets the 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 function call will enable all
frame statistics, as well as basic statistics classes, with their current
class mode settings.
fstats->setClass(PFSTATS_ALL, PFSTATS_ON);
Only statistics classes that are enabled with pfFStatsClass are able to
be printed with pfMemory::print, collected, copied, accumulated,
averaged, and queried.
pfFrameStats::getClass takes the statistics classes of interest specified
in the bitmask, enmask. The frame statistics classes are enabled through
pfFrameStats::setClass and the frame statistics class bitmasks may be
combined with the basic statistics classes. If any of the statistics
classes specified in enmask are enabled, then pfFrameStats::getClass will
return the bitmask of those classes, and will otherwise return zero.
pfFrameStats::setClassMode takes the name of the class to set, class, a
mask of class modes, mask, and the value for those modes, val. The
pfFrameStats classes include all of the pfStats classes. If class is
PFSTATS_CLASSES, then all pfFrameStats classes will have their modes set
according to mask and val. Each statistics class has its own mode tokens
that may be used for mask. mask may also be one of PFSTATS_ALL or 0x0.
val is one of the statistics value tokens: PFSTATS_ON, PFSTATS_OFF,
PFSTATS_SET, or PFSTATS_DEFAULT. See the pfStats man page for more
general information on pfStats statistics classes and value tokens under
pfStats::setClassMode. The following describes the additional classes
for frame statistics and their corresponding modes.
Page 5
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
Process Frame Times Modes:
PFFSTATS_PFTIMES_BASIC
This mode enables a running average of the time for each OpenGL
Performer process of application, cull, and draw to complete
the tasks for a single frame. This mode is enabled by default.
PFFSTATS_PFTIMES_HIST
In this mode, a history of time stamps is maintained for
different tasks within each of the OpenGL Performer processes:
application processes, cull processes, draw processes, and
intersection processes. Examples of time stamps include when
each process starts and ends processing a frame, and that
processes application frame number for that frame. There are
special additional time stamps for each kind of process. For
application processes there are time stamps to mark when the
application process starts and finishes cleaning the scene in
pfSync, a time stamp when the application process wakes up to
sync to the next frame boundary (done when the application
process is running with phase set to PFPHASE_LOCK or
PFPHASE_FLOAT), and a time stamp to mark when the application
process returns after setting off a forked CULL or ISECT
process. The time stamps for each process are defined in the
pfFStatsValPFTimes* data type and queried by providing the
corresponding PFFSTATSVAL_PFTIMES_HIST_* tokens to
pfFrameStats::query.
Database Statistics Modes:
PFFSTATS_DB_VIS
This mode enables tracking of how many pfNodes of each
different type are visible and drawn in a given frame. This
mode is enabled by default. These statistics are queried by
providing the desired PFFSTATSVAL_VISIBLE* token to
pfFrameStats::query.
PFFSTATS_DB_EVAL
This mode enables tracking of how many pfNodes of each
different type have special evaluations in a given frame. Node
types that require special evaluation steps include
pfBillboard, pfSCS, pfDCS, pfLayer, pfLightPoint,
pfLightSource, pfPartition, and pfSequence. There are also
query tokens to query what processes the evaluation step for a
given node type is done in. This mode is enabled by default.
These statistics are queried by providing the desired
PFFSTATSVAL_EVALUATED* token to pfFrameStats::query.
Cull Statistics Modes:
PFFSTATS_CULL_TRAV
There is only one cull frame statistics mode and it tracks
culling traversal statistics: how many pfGeoSets and pfNodes of
Page 6
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
each type are traversed in the cull operation, how many pfNodes
are trivially in or out of the viewing frustum, and how many
must pass through a bounding sphere or bounding box test. These
statistics are queried by providing one of the
PFFSTATSVAL_CULLTRAV tokens to pfFrameStats::query. There are
also statistics on the test results of the cull traversal,
queried with the PFFSTATSVAL_CULLTEST* tokens.
pfFrameStats::getClassMode takes the name of the class to query, class.
The return value is the mode of class.
pfFrameStats::setAttr takes the name of the attribute to set, attr, and
the attribute value, val. Frame statistics provide additional attributes
beyond the basic pfStats attributes. These attributes are only relevant
when automatic statistics collection is being done by a parent channel.
These attributes are:
PFFSTATS_UPDATE_FRAMES
The number of frames over which statistics should be averaged.
The default value is 2. If val is 0, statistics accumulation
and averaging is disabled and only the CUR and PREV statistics
for enabled classes will be maintained. This is recommended
for applications that are not using the averaged statistics and
require a high, fixed frame rate.
PFFSTATS_UPDATE_SECS
The number of seconds, over which statistics should be
averaged. The default uses the number of frames. As with
PFFSTATS_UPDATE_FRAMES, if val is 0, statistics accumulation
and averaging is disabled and only the CUR and PREV statistics
for enabled classes will be maintained.
PFFSTATS_PFTIMES_HIST_FRAMES
For the Process Frame Times Statistics, PFFSTATS_PFTIMES, the
number of frames of time-stamp history to keep. The default
value is 4.
pfFrameStats::getAttr takes the name of the attribute to query, attr.
The return value is that of attribute attr.
pfFrameStats::query: which is a PFSTATSVAL_* or PFFSTATSVAL_* token that
specifies the value or values to query in which, and dst destination
buffer that is a pointer to a float, a pfStatsVal* or pfFStatsVal*
structure. The size of the expected return data is specified by size and
if non-zero, will prevent pfFrameStats::query from writing beyond a
buffer that is too small. The return value is the number of bytes
written to the destination buffer. A single PFFSTATS_BUF_* token should
be bitwise OR-ed into the which flag to select a frame stats buffer:
PREV, CUR, AVG, or CUM. If no frame statistics buffer is selected, then
the query accesses the PREV buffer by default. If multiple stats buffers
are selected, no results will be written and a warning message will be
printed. In a running application, one should query frame statistics in
Page 7
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
the application process and query the PREV and AVG statistics buffers.
The pfFrameStats query structures and tokens are all defined in
pfstats.h. Frame statistics queries may be mixed with standard
statistics queries. There are tokens for getting back all of the
statistics, entire sub-structures, and individual values.
pfFrameStats::mQuery takes a pointer to the start of a PFSTATSVAL_NULL-
terminated array of query tokens in which, and a destination buffer dst.
The size of the expected return data is specified by size and if non-
zero, will prevent pfFrameStats::query from writing beyond a buffer that
is too small. The return value is the number of bytes written to the
destination buffer. If at any point in the query, an error is
encountered, the query will return and not finish the rest of the
requests.
pfFrameStats::copy: The dSel and sSel arguments explicitly specify the
statistics buffers for both source and destination pfFrameStats
structures. A value of 0 is defaulted to the value PFFSTATS_BUF_CUR.
The classes argument is a _EN* statistics class enable bitmask. Any
buffer select token included with the class bitmask is ignored.
pfFrameStats::countNode will count node in the specified stats class for
the specified mode of the pfFrameStats. Only one class and mode may be
specified, and children of node are not traversed.
pfFrameStats::count works as documented for the pfStats statistics
structure. It accumulates the statistics into the CUR statistics buffer.
The pfFrameStats::clear, pfFrameStats::accumulate, pfFrameStats::average
routines work as documented for the basic pfStats statistics structure.
However, for operating on a pfFrameStats structure, these routines need
to know which pfFrameStats buffer to access. A pfFrameStats buffer is
selected by OR-ing in a _BUF_ token with the statistics class enable.
The same pfFrameStats buffer is used for both source and destination
pfFrameStats structures. If no pfFrameStats buffer is selected with a
_BUF_ token, a default value of PFFSTATS_BUF_CUR is used for calls to
pfFrameStats::clear and pfFrameStats::accumulate, and a default value of
PFFSTATS_BUF_CUM is used for calls to pfFrameStats::average.
EXAMPLES
For a class of statistics to be collected, the following must be true:
1. A pfFrameStats structure must be fetched from the channel of
interest, or created.
2. The corresponding statistics class must be enabled with
pfFrameStats::setClass. No statistics classes are enabled by
default.
Page 8
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
3. The corresponding statistics class mode must be enabled with
pfFrameStats::setClassMode However, each statistics class does
have a reasonable set of statistics modes enabled by default.
Here a pfFrameStats structure is obtained by the channel of interest and
then database, cull, and graphics statistics are enabled.
pfFrameStats *fstats = NULL;
fstats = chan->getFStats();
fstats->setClass(PFSTATS_ENGFX | PFFSTATS_ENDB | PFFSTATS_ENCULL, PFSTATS_ON);
This example shows how to enable and display just the frame times and the
number of triangles per frame. This is a very efficient configuration.
pfFrameStats *fstats = NULL;
fstats = chan->getFStats();
/* first, turn off the frame history stats */
fstats->setClassMode(PFFSTATS_PFTIMES, PFFSTATS_PFTIMES_HIST, PFSTATS_OFF);
/* Only enable the geometry counts in the graphics stats */
fstats->setClassMode(PFSTATS_GFX, PFSTATS_GFX_GEOM, PFSTATS_SET);
/* disable the display of the verbose graphics stats
* and just have the total tris number at the top of your display.
*/
chan->setStatsMode(PFCSTATS_DRAW, PFFSTATS_ENPFTIMES);
The following is an example of querying a few specific statistics. Note
that if the corresponding stats class and mode is not enabled then the
query will simply return 0 for that value.
uint qtmp[5];
float ftmp[5];
pfFrameStats *fstats = NULL;
fstats = chan->getFStats();
qtmp[0] = PFFSTATS_BUF_AVG | PFSTATSVAL_GFX_GEOM_TRIS;
qtmp[1] = PFFSTATS_BUF_AVG | PFFSTATSVAL_PFTIMES_PROC_TOTAL;
qtmp[2] = PFFSTATS_BUF_AVG | PFSTATSVAL_CPU_SYS_BUSY;
qtmp[3] = NULL;
fstats->mQuery(qtmp, ftmp, sizeof(ftmp));
fprintf(stderr, "Query num tris: %.0f\n", ftmp[0]);
fprintf(stderr, "Query frame time: %.0f msecs\n", ftmp[1]*1000.0f);
fprintf(stderr, "Query sys busy: %.0f%%\n", ftmp[2]);
Page 9
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
This example shows using a very inexpensive pfFrameStats mode to track
frame rates and frames that missed the goal frame rate.
/* enable only the most minimal stats - tracking of process frame times */
pfFrameStats *fstats = chan->getFStats();
fstats->setClass(PFFSTATS_ENPFTIMES, PFSTATS_SET);
fstats->setClassMode(PFFSTATS_PFTIMES, PFFSTATS_PFTIMES_BASIC, PFSTATS_SET);
/* turn off accumulation and averaging of stats */
fstats->setAttr(PFFSTATS_UPDATE_FRAMES, 0.0f);
#define STAMPS 0
#define TIMES 1
#define MISSES 2
static uint query[] = {
PFFSTATS_BUF_PREV | PFFSTATSVAL_PFTIMES_APPSTAMP,
PFFSTATS_BUF_PREV | PFFSTATSVAL_PFTIMES_PROC,
PFFSTATS_BUF_PREV | PFFSTATSVAL_PFTIMES_MISSES, NULL
};
static pfFStatsValProc dst[3];
int i;
if (!FrameStats)
initFrameStats();
/* get the prev frame times and corresponding app frame stamps */
fstats->mQuery(query, dst, sizeof(dst));
/* record the collected data here */
NOTES
pfFrameStats::draw does not actually draw the diagram but sets a flag so
that the diagram is drawn just before OpenGL Performer swaps buffers.
The CPU statistics from the pfStats class PFSTATSHW_CPU are obtained from
IRIX process accounting data at the start and end of the update period.
They are then copied into the CUR and AVG buffers.
pfFrameStats::open and pfFrameStats::close cannot be executed on a
pfFrameStats structure. All actual frame statistics collection is done
only by individual pfChannels. Frame statistics can be copied and
accumulated into additional pfFrameStats structures.
The pfDrawChanStats manual page gives some pointers on how to interpret
the statistics to help in tuning your database. Refer to the OpenGL
Performer Programming Guide for more detailed information.
Page 10
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C++ Reference Pages
BUGS
Calls to pfFrameStats::query with the query tokens PFFSTATSVAL_NUMFRAMES
or PFFSTATSVAL_NUMISECTFRAMES return values formatted as floats, even
though the corresponding fields in the pfFrameStatsValues structure are
of type type int.
The checking of size in and pfFrameStats::mQuery is not yet implemented.
SEE ALSO
pfChannel, pfStats, pfDelete
Page 11
