eventView(1pf)

NAME
     eventView, evpp, evanalyzer, evhist, evgraph, evmerge - OpenGL Performer
     real-time event generator/viewer.

SYNOPSIS
     evpp [ options ] infile.def

     evanalyzer infile.timefile

     evhist infile.timefile event_name_1 [s|e event_name_2 s|e]

     evgraph infile.timefile event_name info_name

     evmerge infile1.timefile infile2.timefile

DESCRIPTION
     This page describes tools for adding and viewing real-time events in a
     Performer program. In describes the following programs:

          evpp -
               An Event Pre-Processor. This program takes a description of
               user events and generates a C program adding the new events
               into an application programs.

          evanalyzer -
               A viewing program for captured events.

          evhist -
               A display program for generating histograms of event durations.
               Usually activated from within evanalyzer.

          evgraph -
               A display program for plotting functions of event information
               slots.

          evmerge -
               A utility program for merging event files.



   evpp - Event Pre-Processor.
     evpp is a pre-processor for adding user-events to an OpenGL Performer
     program. It takes an text file describing a set of new event types. It
     produces a C source file and a C include file. Compiling and linking the
     new C source file in your program enables recording the newly generated
     events.

     Here's an example of an evpp input file:

          file "out.timefile";
          max_events 10000;
          c_file "myEvents.c";
          h_file "myEvents.h";

          active true;

          conditional_sampling true;

          malloc "pfSharedMalloc";

          group "my_APP"     0x000001;
          group "my_Cull_CB" 0x000002;

          group "my_APP"
                  {
                  event "my_pfFrame";
                  event "my_pfSync";
                  };

          group "my_Cull_CB"
                  {
                          event "my_Cull_Group_CB"
                                  {
                                          size 5;
                                  };

                          event "my_Cull_DCS_CB"
                                  {
                                          size 5;
                                  };
                  };

          event "myCB"
                  {
                          info "myInfo"
                          {
                                  type int;
                                  name "myInfoName";
                          };
                  }




     The above file defines two groups of events. Each group contains two
     events.  In the second group (my_Cull_CB), each event is an array of five
     events. This is useful for generating the same event types from different
     processes. In this case, each CULL process will generate events on
     callbacks to pfGroups and pfDCS.  The above file also defines an event
     called myCB which doesn't belong to any group. This event contains a
     single information slot of type integer on it.
     The file directive specifies the output file name. If the character ?  is
     used instead of a file name, the generated macros EVENT_WRITE and
     EVENT_WRITE_ALL will require a file name as a parameter.

     The max_events directive specifies the maximum number of events that will
     be allocated and captured.

     The c_file and h_file directives specify the file names for the source
     code files that evpp generates.

     The active directive may be true or false. It determines whether evpp
     will generate empty macros. This is useful when trying to avoid
     generating any macros without changing any application source code.

     The conditional_sampling directive can be true or false. If false, events
     will be captured regardless of the call to EVENT_SAMPLE_ON.

     The malloc directive allows defining an alternative memory allocation for
     internal eventView use. If using anything other than "pfSharedMalloc" as
     the malloc value, the application must supply a function receiving an int
     and returning a void* pointer to newly allocated memory. pfSharedMalloc
     is a built in function that allocates memory off the Performer shared
     arena.

     When defining a group of events, one must first define a group mask. The
     group directive accept a group name and a mask. Masks may overlap. This
     is useful for defining hierarchies of groups.

     An event directive is used for defining single events. They may be inside
     or outside the definition of a group. And event should have a name, and
     may have a size and information slots. In the example above, an event of
     size 5 is effectively an array of five independent events. This is useful
     for creating per-pipe events.



   evpp command line options
          -h   Print usage string.

          -c   Compile generated files. This option can make Makefiles
               simpler.

          -n   Set all the events in the input file to inactive. The macros
               generated for all events will be empty. This flag use useful
               when trying to disable the instrumentation of a source file
               without removing the macros.



   evanalyzer - a graphic event display
     evanalyzer generates a graphic display of captures events. Each line in
     its display contains events of a single type. The horizontal axis of the
     display denotes the time.

     An event starts at a vertical bar from the bottom of the event line to
     its middle, continues horizontally and ends as a vertical bar from the
     middle of the event line to its top.


     evanalyzer keyboard/mouse controls

          Up/Down arrows -
               Change the zoom factor of the display.

          Right/Left arrows -
               Shift display window across the captured data.

          Left Mouse Button -
               Pick an event start/end. Clicking on one event start/end and
               releasing on another, prints the time difference between the
               two on the top of the display.

          Middle Mouse Button -
               Drag the event display window across the captured data.

          Right Mouse Button -
               If the mouse is on an event line and the event has information
               fields, allow toggling their display.  If the mouse is not on
               an event line, toggle events displayed or groups displayed.

          h key -
               Bring up a histogram program (evhist) and run it on the
               currently selected event.

          f key -
               If the event line under the mouse has information slots, ask to
               pick a slot.  Bring up a function plot program (evgraph) and
               run it on the selected information slot on the current event.
               ESC - Exits evanalyzer.


     evhist keyboard controls.

     Moving the mouse across the window prints how many samples are on the
     histogram bar under the mouse and what time value it represents.


          Up/Down arrows -
               Change the resolution of the histogram.

          Right/Left arrows -
               Change the percentage of samples on both extremes of the
               histogram that we ignore (Displayed as garbage on the top of
               the display).
          ESC -
               Exits evhist.


   evgraph - plot event info.
     evgraph is a display program for plotting the information slot of a given
     event type. It is usually activated by evanalyzer.

     evgraph keyboard/mouse controls


          Up/Down arrows -
               Change the resolution of the plot.

          Right/Left arrows -
               Translate plot horizontally.

          Middle mouse button -
               Drag plot horizontally.


NOTES
     EventView was originally written by Ran Yakir from BVR Systems.


SEE ALSO
     pfInitializeEvents, pfResetEvents, pfEventSampleOn, pfEventSampleOff,
     pfWriteEvents