*** empty log message ***
[dyninst.git] / visi / docs / README
1 directions to incorporate a visualization  (an example is in xtext.C)
2 -----------------------------------------
3 in main():
4 ---------
5 (1) call visiInit()
6
7 (2) register callback routines associated with certain Paradyn events
8     by calling RegistrationCallback():  these are routines written by the
9     visualization writer to be called by the visi_callback routine when 
10     the specified event occurs.  
11     the event types (type msgTag) are defined in ../src/visiTypes.h
12     
13     Callback routines should take one integer parameter.  This parameter
14     is only used for the DATAVALUES event, where it is the bucket number
15     of the next full set of data across all the valid metrics/resources
16     of the datagrid.    
17
18     Most of the work involved in integrating the visualization has to 
19     do with writing these callback routines.  In most cases this will
20     involve changing a callback routine in the X application that initially
21     read data from a file descriptor, to get data from the interface's
22     data structures:  in most cases this involves invoking dataGrid method
23     functions.  An example of a change to an existing call back routine
24     is the function "fd_input" in xtext.C.  
25
26     dataGrid method functions are defined in ~paradyn/core/visi/src/datagrid.h
27     visualization interface routines and global variables are in 
28       ~paradyn/core/visi/src/visualization.[Ch]
29
30 (3) optional: call StartVisi(argc,argv) with the args to main():  each 
31     visualization is started with two command line arguments--a metric 
32     list and a resource list.  For visualizations that do not invoke
33     the upcalls provided by the visi interface this is the only opportunity 
34     to start data collection.
35
36   Steps 3a and 3b: for handling upcalls to Paradyn side:
37   ------------------------------------------------------
38 (3a) create a widget associated with the upcall
39 (3b) use XtAddCallback to register your handler routine for events assoc.
40      with this widget
41
42 (4) register the paradyn file descriptor (returned by VisiInit) and 
43     the paradyn callback routine "visi_callback" with the appropriate
44     add application routine.  (ie. for Xt use XtAddApp)
45
46 (5) call Xt main loop
47
48
49 Getting values out of the datagrid
50 ----------------------------------
51 Information about metrics, resources, and data values can be obtained
52 by calling the visi_DataGrid method functions in ~paradyn/visi/h/datagrid.h
53
54 Data values can be retrieved in one of two ways:
55  1) datagrid[metricNum][resourceNum][bucketNum] returns a single bucket value
56  2) datagrid[metricNum][resourceNum].Value() returns a pointer to an array of
57     bucket values
58
59
60 Adding aditional information to a datagrid cell
61 -----------------------------------------------
62 Each datagrid cell has a void * public member (userdata) that can be used 
63 to add any additional information to a datagrid cell.   
64
65
66 Interface test programs  (in paradyn/core/visi/test )
67 -----------------------
68 Sample visi interface client server programs, and examples of integrating
69 the interface routines into an existing visualization.