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