op_anim_lprobe_anvid()
Abstract
Returns the ID of a viewer associated with a labeled probe, as specified by its label text. The viewer of each defined labeled probe is opened by the first invocation of this KP which references the probe label.
Syntax
op_anim_lprobe_anvid (label)
| Argument | Type | Description |
|---|---|---|
label |
char* |
custom animation probe label [This value is a string which is compared to the label attribute of all custom animation probes defined for the surrounding module. If a match is found, the animation viewer ID associated with the probe is returned.] |
Return Type
Anvid
viewer ID of labeled probe
[If no probe has been defined with the specified label, the value represented by the symbolic constant OPC_ANIM_ANVID_NONE will be returned. If no animation flow is active at all, then the value represented by the symbolic constant OPC_ANIM_ID_NIL will be returned. These values can be detected and used to suppress execution of subsequent animation KPs, as shown in the Example section.]
Example
/* Obtain the ID of a viewer opened by a probe labeled "switch I/O"; */
/* if the probe has not been set, none of the dependent animation statements */
/* will be executed. */
vid = op_anim_lprobe_anvid ("switch I/O");
if (vid != OPC_ANIM_ANVID_NONE)
{
/* Draw background color. */
op_anim_igp_bg_fill (vid, OPC_ANIM_RETAIN | OPC_ANIM_COLOR_STEEL, " ");
/* Load and draw node model. */
op_anim_ime_nmod_draw (vid, OPC_ANIM_MODTYPE_NODE, "hyper_switch", " ",
OPC_ANIM_MOD_OPTION_NONE, OPC_ANIM_DEFPROPS);
/* Draw title string at top of viewer window. */
op_anim_igp_text_draw (vid, OPC_ANIM_COLOR_YELLOW | OPC_ANIM_FONT_OPEN_10 |
OPC_ANIM_ALIGNH_CENTER, 200, 50, "Switch I/O Diagram");
}
Details
This KP is one of several distinct techniques for obtaining the ID of an animation viewer for use by Anim package KPs; it obtains the ID of a viewer opened by a labeled custom animation probe. The use of labeled probe viewers offers the following characteristics:
- A single animation viewer can be shared by multiple process models (possibly distributed throughout a network model) with no required inter-process communication or coordination except for their common expectation of a specific probe label.
- The position, size, and name of the animation viewer are attributes of the labeled probe set in the Probe Editor, which supports convenient alteration without modifying the simulation.
- Multiple animation KPs which taken together form a specific dynamic view of simulation events can be “logically grouped” under a particular probe label, permitting convenient enabling/disabling of all KPs in the group (for instance, all animation KPs which are used to illustrate packet processing within a switch can obtain their viewer ID from a probe labeled “switch_proc”—if such a probe is not defined, the associated diagram will appear).
Animation requests directed to labeled probe viewers are disabled when a probe with the specified label does not exist; op_anim_lprobe_anvid() returns a special value (identified by the symbolic constant OPC_ANIM_ANVID_NONE) in such cases. The disabling can be done transparently by simply passing the “null” viewer ID to an Anim KP (which will detect the value and disable the request without producing an error) or by explicit detection which potentially avoids execution of blocks of code and increases performance when the specified labeled probe is not defined (as in the Example code).
Purpose
Provides a mechanism for obtaining access to a viewer opened by a custom animation probe which is restricted to a particular label. Animation KPs which depict a particular aspect of a simulation, or which display events within a particular protocol stack layer, can be passed the output of this KP, allowing convenient control over request masking and viewer parameters from the Probe Editor. Note that the animation viewer associated with a labeled probe is not necessarily opened at the beginning of a simulation’s animation flow, but rather when this KP is first invoked with the probe’s label.
Errors
- Program Abort: segmentation violation (due to a badly formed string for the
labelargument)
Reference
- Use the KPs op_anim_viewer_open() or op_anim_viewer_open_std() to create an animation viewer and obtain its ID, or to rendezvous with an existing viewer created by any method (a custom open, automatic probe, or custom probes)
- Use the KP op_anim_viewer_close() to close a viewer which is no longer needed (closing a labeled probe’s viewer will cause an error in the anim. flow if subsequent Anim KPs reference the viewer)
- Use the
op_anim_igp…KPs to display graphical primitives in an opened viewer - Use the
op_anim_ime…KPs to display or modify model elements in an opened viewer