vis_help.txt

simulator for ad hoc

        The "Show Transmission Range" option can be checked to display the
        power range of each node as a circle around it. If you do not wish
        to see the power range displayed, then just uncheck this option.

[C] Debug Menu:

  [1] The "Set Step Size..." option has been disabled for the time being since
      we could not yet find a satisfactory way to handle stepping. This
      functionality will be added soon.

  [2] The "View Stats..." option is used to display statistics collected at
      the end of the GloMoSim simulation. The statistics are located in a file
      called GLOMO.STAT. (see $glomo/doc/user.txt for more details about
      GLOMO.STAT) In order for GLOMO.STAT to be written to, the GloMoSim
      simulation must be run to completion since it is written to at the end
      of the simulation.  The GLOMO.STAT file will be placed in whichever
      directory that GloMoSim is run from. So if you run GloMoSim without the
      VT from the $glomo/bin/ directory, then it will be placed in that
      directory. But if you run it from the VT in the $glomo/java_gui/
      directory, then it will be placed in that directory instead.

      Once the stats window is open, the left panel will allow you to select
      which statistics you wish to view. Only those statistics which you set
      as YES in the CONFIG.IN file will be displayed on the left panel.
      For example, if you only set TCP-STATISTICS and ROUTING-STATISTICS to
      YES and set everything else to NO, then only those two stats will be
      available as options on the left menu. If you don't specify any statistics
      as YES in the CONFIG.IN file, then nothing will be displayed on the
      left panel. (see $glomo/doc/user.txt for more information about
      statistics collected at the end of the simulation from GloMoSim)
 
      In the future, when GloMoSim provides real time statistics during the
      execution instead of just at the end, the VT will be augmented to
      display these statistics. One way to implement this is to show statistics
      for a particular node when you click on it. For now, I just wrote a dummy
      function which displays the location of a node when you click on it. In
      the future, some useful statistics will be displayed instead. Also, global
      statistics will be displayed real time during the execution of GloMoSim
      on the right panel of the VT when GloMoSim eventually develops the ability
      to show global statistics.

[D] The Speed Up and Slow Down buttons can be used to speed up or slow down
    the simulation.
    The Zoom our and Zoom In buttons can be used to scale the cordinate.
    The Stop, Step and Run button can be used to pause, step and resume the 
    simulation

-----------------------------------------------------------------------
[4] Modifying GloMoSim to interact with the Visualization Tool
-----------------------------------------------------------------------

GloMoSim already contains code which allows it to interact with
the VT. However, the code is only written for the radio and channel
layers for the time being. If you wish to extend the functionality
of the code written in the radio and channel layers or if you wish
to have other layers of GloMoSim displayed by the VT, then you will
have to add the code yourself. Here is a brief description of the
interface between GloMoSim and the VT:

The way GloMoSim communicates with the VT is through standard output
(stdout). When GloMoSim wants something to be displayed by the VT,
it sends a formatted text message (basically a printf) to the VT
specifying what it wants the VT to display. You do not have to worry
about setting up the stdout link between GloMoSim and the VT - it is
already taken care of when you execute GloMoSim from the VT.
(ie: what you did in part c above)

The text message that GloMoSim sends to the VT needs to be in a
specific format for the VT to understand and execute it.
The programmer does not have to worry about what the format is.
Instead, a header file, "java_gui.h", contains prototypes of
functions you can call to display certain things in the VT.
When you call one of these functions from GloMoSim, it will send
the text message to the VT in the proper format.
Here is a current listing of the functions provided for communication
between GloMoSim and the VT (example uses of these functions can
be found in: main/channel.pc, main/mobility.pc, radio/radio_no.pc,
and radio/radio_has.pc):

[A] void JGUI_InitNode(long numGuiNodes, long id, long positionX,
                       long positionY, long txRange, JGUI_COLOR color);
    Purpose:
       This function is used for initializing nodes at the beginning
       of the simulation. The VT needs this information so that it
       can allocate storage for each node in memory. Since it is called
       only once for each node at the beginning of the simulation, you
       will never need to use this function with GloMoSim since it has
       already been included (in $glomo/main/mobility.pc).
    Parameters:
       numGuiNodes:   Number of nodes in the simulation
       id:            Numerical id of the node
       positionX:     Initial x coordinate of the node
       positionY:     Initial y coordinate of the node
       txRange:       Radio power range of the node
       color:         Color of the node displayed in the VT

[B] void JGUI_DrawLine(long srcId, long destId, unsigned char *simTime,
                       JGUI_COLOR color);
    Purpose:
       This function is used to draw a temporary line between two nodes
       which can represent the transmission of a packet between two nodes.
       After a brief period of time, the line is erased.
    Parameters:
       srcId:    Id of the transmitting node
       destId:   Id of the receiving node
       simTime:  Current time of the PARSEC simulation clock
       color:    Color of the line displayed in the VT

[C] void JGUI_DrawThickLine(long srcId, long destId, long thickness,
                            unsigned char *simTime, JGUI_COLOR color);
    Purpose:
       This function has the same functionality as JGUI_DrawLine except
       it allows you to specify a thickness for the line.
    Parameters:
       srcId, destId, simTime, color: same as for JGUI_DrawLine
       thickness:  The thickness of the line

[D] void JGUI_DrawLink(long srcId, long destId, unsigned char *simTime,
                       JGUI_COLOR color);
    Purpose:
       This function is similar to JGUI_DrawLine except that it is not
       automatically erased after a short period of time. To erase the
       line, call JGUI_EraseLink.
    Parameters:
       Same as for JGUI_DrawLine
        
[E] void JGUI_EraseLink(long srcId, long destId, unsigned char *simTime);
    Purpose:
       Erase the line drawn by JGUI_DrawLink
    Parameters:
       Same as for JGUI_DrawLine except it doesn't include the color
       variable since it is not necessary

[F] void JGUI_DrawBroadcast(long id, unsigned char *simTime,
                            JGUI_COLOR color);
    Purpose:
       This function is used to draw an expanding circle within a node's
       power range.
    Parameters:
       id:         Id of transmitting node
       simTime:    Current time of the PARSEC simulation clock
       color:      Color of the expanding circle displayed in the VT

[G] void JGUI_MoveNode(long id, long x, long y, unsigned char *simTime);
    Purpose:
       This function is used to move a node from one part of the screen
       to another. The user will never have to call this function because
       it is already included in the mobility file (main/mobility.pc) which
       is the only place where node movement takes place.
    Parameters:
       id:         Id of the node to be moved
       x:          New x coordinate of the node
       y:          New y coordinate of the node
       simTime:    Current time of the PARSEC simulation clock

The following is a list of enums that can be used for the JGUI_COLOR
parameters of the function prototypes listed above:

    typedef enum {
        JGUI_BLACK=0, JGUI_BLUE=1, JGUI_CYAN=2, JGUI_DARK_GRAY=3, JGUI_GRAY=4,
        JGUI_GREEN=5, JGUI_LIGHT_GRAY=6, JGUI_MAGENTA=7, JGUI_ORANGE=8,
        JGUI_PINK=9, JGUI_RED=10, JGUI_WHITE=11, JGUI_YELLOW=12
    } JGUI_COLOR;

The functions provided are pretty generic. Hopefully it will provide
enough power to display everything you want. If you have any suggestions
for other functions to add, please let me know ([e-mail]).