pfEventView(3pf) OpenGL Performer 3.2.2 libpf Reference Pages
NAME
pfInitializeEvents, pfEventSampleOn, pfEventSampleOff, pfWriteEvents,
pfResetEvents - Accumulate internal Performer timing events.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
void pfInitializeEvents(void);
void pfEventSampleOn(void);
void pfEventSampleOff(void);
void pfWriteEvents(char *filename);
void pfResetEvents(void);
DESCRIPTION
OpenGL Performer is instrumented to generate internal timing events and
write them into a file upon application program request. Each event has a
start time a nd an end time. Together they bind the execution of
important parts of a Performer frame in the various Perforfmer processes.
The captured event durations are similar to the durations presented in
pfFrameStats. However, EventView events can be written to a file and
analyzed offline - after the execution of a Performer program completes.
In addition, an application program can design its private set of events
and can merge them into the same output file as the Performer internal
events.
OpenGL Performer supplies an analysis program called evanalyzer for
generating a graphic display of the captured events.
pfInitializeEvents initializes the internal Performer event capture
mechanism. An application must call this function before calling pfConfig
in order to initialize the event-capture data structures. All other event
capture functions should be called after pfInitializeEvents.
pfEventSampleOn starts event capturing. Immediately after this function
is called, all Performer generated timing events will be logged for
future saving into a file. Performer will log a limited number of events
(currently 10000 events). No events will be logged after this limit is
reached.
pfEventSampleOff stops event capturing. No events will be logged after
this call.
pfWriteEvents writes out the currently logged events into a disk file
filename. The written events can be later viewed using evanalyzer.
pfResetEvents resets the list of captured events.
Page 1
pfEventView(3pf) OpenGL Performer 3.2.2 libpf Reference Pages
Sample use of pfEventView:
The simplest case.
The simplest way to use pfEventView is to use only Performer-internal
events. In this case, an application program may look like:
main()
{
pfInit();
// Initialize event capture.
pfInitializeEvents();
pfConfig();
// Create window & scene graph.
....
// Start event capture
pfEventSampleOn();
for (i = 0 ; i < numFrames ; i ++)
{
pfSync();
pfFrame();
}
// Stop event capture.
pfEventSampleOff();
// Write to file.
pfWriteEvents("events.timefile");
}
After the program completes, one can analyze the generated events using
the command: evanalyzer events.timefile.
Sample use of pfEventView:
A more complex case.
In a more complex case, an application has some private events that it
wishes to add to the captured event file. We achieve this in two stages:
Stage I:
We define application private events in a file. The following example
defines a single event named myDrawCB and assigns a single information
slot of type integer for this event.
Page 2
pfEventView(3pf) OpenGL Performer 3.2.2 libpf Reference Pages
file "myEvents.timefile";
max_events 10000;
c_file "myEvents.c";
h_file "myEvents.h";
active true;
conditional_sampling true;
malloc "pfSharedMalloc";
event "myDrawCB"
{
info "CB_Info"
{
name "Something" ;
type int ;
};
};
Running evpp on above file creates the two files myEvents.c and
myEvents.h. The application should compile and link with the newly
generated file myEvents.c. The file myEvents.h contains macros that the
application uses for controling event capture.
Stage II:
In the application code below, we generate an event of type myDrawCB in a
DRAW callback of some node in the scene graph. Every time we generate an
event, we assign a value to its information slot:
int pre_draw_cb(pfTraverser *trav, void *userData)
{
int someValue;
// Mark the start of private event MyDrawCB.
EVENT_START_MYDRAWCB;
// Assign value to the information field of this event.
EVENT_MYDRAWCB_INFO_CB_Info (someValue);
... Run callback code.
// Mark the end of private event MyDrawCB.
EVENT_END_MYDRAWCB;
}
main()
{
pfGeode *geode;
Page 3
pfEventView(3pf) OpenGL Performer 3.2.2 libpf Reference Pages
pfInit();
// Initialize Performer-internal event capture.
pfInitializeEvents();
// Initialize application-private event capture.
EVENT_INIT;
pfConfig();
// Create window & scene graph.
....
// Setup DRAW callback on a node.
pfNodeTravFuncs(geode, PFTRAV_DRAW, pre_draw_cb, NULL);
// Start event capture on all initialized event sets (Performer-internal
// and application-private).
EVENT_SAMPLE_ALL_ON;
for (i = 0 ; i < numFrames ; i ++)
{
pfSync();
pfFrame();
}
// Stop event capture on all initialized event sets..
EVENT_SAMPLE_ALL_OFF;
// Write all captured events from all initialized sets to a file.
// Since we named a file in the evpp input file,
// we need not specify it here.
EVENT_WRITE_ALL;
}
As in the first example, after the program completes, one can analyze the
generated events using the command: evanalyzer myEvents.timefile. This
time the file contains Performer-internal and application-private
(myDrawCB) events. Clicking the right-hand mouse button on the line
marked myDrawCB can toggle the display of the information field on this
event.
Note that we didn't have to start/stop sampling of Performer-internal
events. The macros EVENT_SAMPLE_ALL_ON and EVENT_SAMPLE_ALL_OFF start
and stop sampling for all currently initialized event sets.
The manual page for evpp contains more information about generating
application-private event types.
Page 4
pfEventView(3pf) OpenGL Performer 3.2.2 libpf Reference Pages
NOTES
EventView was originally written by Ran Yakir from BVR Systems.
SEE ALSO
evpp, evhist, evanalyzer
Page 5
