op_anim_igp_icon_draw()
Abstract
Draws an icon at a specified location.
Syntax
op_anim_igp_icon_draw (anvid, props, ic_name, x, y)
| Argument | Type | Description |
|---|---|---|
anvid |
Anvid |
viewer ID [This value is a numeric identifier which references a viewer. The icon will be displayed in the viewer’s window.] |
props |
int |
graphical property flags [This value is the bitwise OR combination of the Animation Graphical Properties flags OPC_ANIM_COLOR_*, OPC_ANIM_PIXOP_*, OPC_ANIM_BGCOLOR_*, OPC_ANIM_STYLE_*, OPC_ANIM_ALIGNH_*, OPC_ANIM_ALIGNV_*, OPC_ANIM_FONT_*, and OPC_ANIM_RETAIN. For more information, see “Animation“ on page 3.] |
ic_name |
char* |
icon name [This value is the name of an icon which must be contained in one of the three icon databases loaded by the op_vuanim program: sys_icon_db, op_vuanim_icon_db, or user_icon_db]. |
x |
int |
x coordinate of icon upper-left corner, measured in pixels from the origin of the viewer window (upper-left corner) |
y |
int |
y coordinate of icon upper-left corner, measured in pixels from the origin of the viewer window (upper-left corner) |
Return Type
Andid
drawing ID of icon
[Retained drawings are issued IDs so they can later be erased (see Reference section). For a drawing to be retained, the graphical property flag OPC_ANIM_RETAIN must be passed. Non-retained drawings are issued the ID constant OPC_ANIM_ID_NIL.]
Example
/** Mobile node position update interrupt: animate node’s new position. **/
/* Force calculation of new node position. */
op_ima_obj_pos_get (node_objid, &lat, &lon, &alt, &x, &y, &z);
/* Obtain new position of node in subnet coordinates. */
op_ima_obj_attr_get (node_objid, "x position", &sn_x);
op_ima_obj_attr_get (node_objid, "y position", &sn_y);
/* Convert node position from model coordinates to animation viewer coordinates. */
op_anim_ime_gen_pos (vid, sn_x, sn_y, &v_x, &v_y);
/* Erase node’s icon at previous position. */
op_anim_igp_drawing_erase (vid, node_did, OPC_ANIM_ERASE_MODE_XOR);
/* Redraw node’s icon at new position. */
node_did = op_anim_igp_icon_draw (vid, OPC_ANIM_RETAIN | OPC_ANIM_PIXOP_XOR,
"field_svc", v_x, v_y);
Details
Icon drawings are affected by the pixop and retain graphical properties. If the pixop graphical property is set to a value other than the default (OPC_ANIM_PIXOP_SRC), portions of the icon which are drawn over non-black viewer pixels may be displayed in colors which are different from those specified in the Color Palette Editor (see “Icon Database Editor“ on page 615 for more information).
Note: The pixop value OPC_ANIM_PIXOP_XOR should be used when the icon drawing will later be erased.
Icon drawings with the retain graphical property set (OPC_ANIM_RETAIN) will be redrawn whenever the associated viewer window is redrawn; by default, they will simply disappear.
You can create icons and add them to an icon database by using the Icon Database Editor. See “Icon Database Editor“ on page 615 for more information. Icons as large as 100 pixels on a side can be designed. However, the larger the icon, the longer it takes to draw (large icons which are updated frequently can cause choppy animations on low-performance workstations).
The special value identified by the symbolic constant OPC_ANIM_ID_NIL is returned by this KP if the retain graphical property is not enabled, or if KP execution is disabled due to the lack of a custom animation probe, or the presence of a custom animation probe which is not currently active.
In addition to the sources of viewer IDs listed in the Reference section, the symbolic constant OPC_ANIM_ANVID_PBSPEC can be used as a substitute viewer ID, indicating that the real viewer ID should be obtained from an active unlabeled custom animation probe.
Purpose
Provides a mechanism to draw an icon as part of an animation. The icon can serve as a component in a completely customized display, or it can be added to a model diagram as an indicator of some dynamic event or status. Note that changing the icon of an object within a model diagram is performed via op_anim_ime_nobj_update(). Icon drawings are useful for depicting static model objects such as nodes or modules in alternative diagrams, or for depicting the condition and status of specific model objects or the simulation as a whole. The Example for this function illustrates how to depict a mobile node as a moving icon, instead of updating the position attribute of the node in a model diagram.
Errors
- Program Abort: segmentation violation (due to a badly formed string for the
ic_nameargument) - Diagnostic Error: Animation viewer ID (
<anvid>) is out-of-range. (due to an invalid value for theanvidargument) - Diagnostic Error: Invalid property component (
<prop_comp>) for graphical primitive. (due to an inapplicable or invalid value for thepropsargument) - Diagnostic Error: Kernel procedure argument (
<arg_name>) has out-of-range value (<value>). (due to a value for the argumentsxorythat exceeds the range of a short integer)
Reference
- Use the KP op_anim_ime_nobj_update() to change the icon of an object displayed in a model diagram
- Use the KP op_anim_mgp_icon_draw() to draw an icon within the context of a macro
- Use the KP op_anim_igp_drawing_erase() to erase and deallocate a retained icon created by this KP
- Use the KPs op_anim_viewer_open() or op_anim_viewer_open_std() to obtain the ID of a newly created animation viewer (or rendezvous with a previously opened viewer), or the KP op_anim_lprobe_anvid() to obtain the ID of a viewer opened by a labeled custom animation probe