pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewFStats, pfGetFStatsClassType, pfDrawFStats, pfCopyFStats,
pfGetOpenFStats, pfOpenFStats, pfCloseFStats, pfFStatsCountNode,
pfFStatsClass, pfGetFStatsClass, pfFStatsClassMode, pfGetFStatsClassMode,
pfFStatsAttr, pfGetFStatsAttr, pfResetFStats, pfClearFStats,
pfFStatsCountGSet, pfAccumulateFStats, pfAverageFStats, pfQueryFStats,
pfMQueryFStats - Specify pfFrameStats modes and get collected values.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
#include <Performer/pfstats.h>
pfFrameStats * pfNewFStats(void);
pfType* pfGetFStatsClassType(void);
void pfDrawFStats(pfFrameStats *fstats, pfChannel *chan);
void pfCopyFStats(pfFrameStats *dst, pfFrameStats *src,
uint dSel, uint sSel, uint classes);
uint pfGetOpenFStats(pfFrameStats *fstats, uint emask);
uint pfOpenFStats(pfFrameStats *fstats, uint enmask);
uint pfCloseFStats(uint enmask);
void pfFStatsCountNode(pfFrameStats *fstats, int class,
uint mode, pfNode * node);
uint pfFStatsClass(pfFrameStats *fstats, uint enmask,
int val);
uint pfGetFStatsClass(pfFrameStats *fstats, uint enmask);
uint pfFStatsClassMode(pfFrameStats *fstats, int class,
uint mask, int val);
uint pfGetFStatsClassMode(pfFrameStats *fstats, int class);
void pfFStatsAttr(pfFrameStats *fstats, int attr, float val);
float pfGetFStatsAttr(pfFrameStats *fstats, int attr);
void pfResetFStats(pfFrameStats *fstats);
void pfClearFStats(pfFrameStats *fstats, uint which);
void pfFStatsCountGSet(pfFrameStats * fstats,
pfGeoSet * gset);
Page 1
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void pfAccumulateFStats(pfFrameStats* dst, pfFrameStats* src,
uint which);
void pfAverageFStats(pfFrameStats* dst, pfFrameStats* src,
uint which, int num);
int pfQueryFStats(pfFrameStats *fstats, uint which,
float *dst, int size);
int pfMQueryFStats(pfFrameStats *fstats, 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. Casting an object of
class pfFrameStats 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 pfDeleteGLHandle(pfObject *obj);
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.
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);
Page 2
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
void * pfGetArena(void *ptr);
PARAMETERS
fstats identifies a pfFrameStats.
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
pointer to the channel's statistics structure with pfGetChanFStats, 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 routines are borrowed from pfStats. These routines
have the identical function as the pfStats routines but operate on a
pfFrameStats rather than a pfStats. The routine correspondence is listed
in the following table.
pfFrameStats routine pfStats routine
__________________________________________
pfAccumulateFStats pfAccumulateStats
pfAverageFStats pfAverageStats
pfClearFStats pfClearStats
pfCloseFStats pfCloseStats
pfFStatsAttr pfStatsAttr
pfFStatsClass pfStatsClass
pfFStatsClassMode pfStatsClassMode
pfGetFStatsClassMode pfGetStatsClassMode
pfFStatsCountGSet pfStatsCountGSet
pfGetFStatsAttr pfGetStatsAttr
pfGetFStatsClass pfGetStatsClass
pfOpenFStats pfOpenStats
pfCloseFStats pfCloseStats
pfGetOpenFStats pfGetOpenStats
pfMQueryFStats pfMQueryStats
pfOpenFStats pfOpenStats
pfGetOpenFStats pfGetOpenStats
pfQueryFStats pfQueryStats
pfResetFStats pfResetStats
|
Page 3
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
___________________________________________
|
Refer to the pfStats man page for detailed descriptions of these
routines.
pfGetFStatsClassType returns the pfType* for the class pfFrameStats. The
pfType* returned by pfGetFStatsClassType is the same as the pfType*
returned by invoking pfGetType 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 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.
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
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 pfQueryFStats and printed
with pfPrint. 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
|
|
Page 4
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
________________________________________________________________
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
|
|
pfNewFStats creates and returns a handle to a pfFrameStats. pfFrameStats
are always allocated from shared memory and can be deleted using
pfDelete. 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
pfNewStats is discussed here. There are also examples showing different
basic operations with pfFrameStats at the end of this man page.
pfDrawFStats displays the pfFrameStats structure fstats in the channel
specified by chan. This is useful for displaying the statistics in a
special channel separate from the main scene channel. pfDrawChanStats
may be called from OpenGL Performer's application, cull, or draw
processes and must be called each frame a statistics display is desired.
See pfDrawChanStats for a detailed explanation of the channel statistics
display.
pfFStatsClass 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.
pfFStatsClass(fstats, PFSTATS_ALL, PFSTATS_ON);
Only statistics classes that are enabled with pfFStatsClass are able to
be printed with pfPrint, collected, copied, accumulated, averaged, and
Page 5
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
queried.
pfGetFStatsClass takes a pointer to a statistics structure, fstats, and
the statistics classes of interest specified in the bitmask, enmask. The
frame statistics classes are enabled through pfFStatsClass 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 pfGetFStatsClass will return the bitmask of those classes,
and will otherwise return zero.
pfFStatsClassMode takes a pointer to a pfFrameStats structure, fstats,
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 pfStatsClassMode. The
following describes the additional classes for frame statistics and their
corresponding modes.
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
pfQueryFStats.
Database Statistics Modes:
Page 6
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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
pfQueryFStats.
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 pfQueryFStats.
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
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 pfQueryFStats. There are also
statistics on the test results of the cull traversal, queried
with the PFFSTATSVAL_CULLTEST* tokens.
pfGetFStatsClassMode takes a pointer to a statistics structure, fstats,
and the name of the class to query, class. The return value is the mode
of class.
pfFStatsAttr takes a pointer to a statistics structure, fstats, 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
Page 7
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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.
pfGetFStatsAttr takes a pointer to a statistics structure, fstats, and
the name of the attribute to query, attr. The return value is that of
attribute attr.
pfQueryFStats takes a pointer to a statistics structure, fstats. 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
pfQueryFStats 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 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.
pfMQueryFStats takes a pointer to a statistics structure, fstats, 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
pfMQueryFStats 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.
pfCopyFStats: 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.
pfFStatsCountNode will count node in the specified stats class for the
specified mode of the pfFrameStats structure fstats. Only one class and
mode may be specified, and children of node are not traversed.
pfFStatsCountGSet works as documented for the pfStats statistics
Page 8
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
structure. It accumulates the statistics into the CUR statistics buffer.
The pfClearFStats, pfAccumulateFStats, pfAverageFStats routines all take
pointers to a pfFrameStats structure, fstats, and 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 pfClearFStats and
pfAccumulateFStats, and a default value of PFFSTATS_BUF_CUM is used for
calls to pfAverageFStats.
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
pfFStatsClass. No statistics classes are enabled by default.
3. The corresponding statistics class mode must be enabled with
pfFStatsClassMode However, each statistics class does have a
reasonable set of statistics modes enabled by default.
Here a pfFrameStats structure is obtained for the channel of interest and
then database, cull, and graphics statistics are enabled.
pfFrameStats *fstats = NULL;
fstats = pfGetChanFStats(chan);
pfFStatsClass(stats, 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 = pfGetChanFStats(chan);
/* first, turn off the frame history stats */
pfFStatsClassMode(fstats, PFFSTATS_PFTIMES, PFFSTATS_PFTIMES_HIST, PFSTATS_OFF);
/* Only enable the geometry counts in the graphics stats */
pfFStatsClassMode(fstats, 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.
*/
pfChanFStatsMode(chan, PFCSTATS_DRAW, PFFSTATS_ENPFTIMES);
Page 9
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
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 = pfGetChanFStats(chan);
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;
pfMQueryFStats(fstats, 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]);
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 = pfGetChanFStats(chan);
pfFStatsClass(fstats, PFFSTATS_ENPFTIMES, PFSTATS_SET);
pfFStatsClassMode(fstats, PFFSTATS_PFTIMES, PFFSTATS_PFTIMES_BASIC, PFSTATS_SET);
/* turn off accumulation and averaging of stats */
pfFStatsAttr(fstats, 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 */
pfMQueryFStats(fstats, query, dst, sizeof(dst));
Page 10
pfFrameStats(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
/* record the collected data here */
NOTESpfDrawFStats 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.
pfOpenFStats and pfCloseFStats 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.
BUGS
Calls to pfQueryFStats 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 pfMQueryFStats is not yet implemented.
SEE ALSO
pfChanStatsMode, pfDrawChanStats, pfGetChanFStats, pfStats, pfDelete
Page 11
