op_anim_igp_drawing_erase()
Abstract
Erases and deallocates a retained drawing from a viewer.
Syntax
op_anim_igp_drawing_erase (anvid, andid, mode)
| Argument | Type | Description |
|---|---|---|
anvid |
Anvid |
viewer ID [This value is a numeric identifier which references a viewer. The specified drawing will be erased from the viewer’s window.] |
andid |
Andid |
drawing ID to be erased [This value is a numeric identifier which references a retained drawing which was created using one of the op_anim_igp… KPs.] |
mode |
int |
erase mode [This value is a numeric code which identifies the technique used for erasure of the specified drawing’s on-screen appearance. The erase mode symbolic constants are listed under “Animation Drawing Erase Mode Symbolic Constants“ on page 7, as well as in the Details section.] |
Return Type
void
no return value
Example
/* Received a packet forwarding interrupt; determine which packet has been identified. */
iciptr = op_intrpt_ici ();
op_ici_attr_get (iciptr, "pk_id", &pk_id);
/* Loop through queue contents, looking for the identified packet. */
for (i = 0, q_size = op_subq_stat (0, OPC_QSTAT_PKSIZE); i < q_size; i++)
{
/* Peek at packet, and test ID. */
pkptr = op_subq_pk_access (0, i);
if (op_pk_id (pkptr) == pk_id)
{
/* Remove & forward packet. */
op_subq_pk_remove (0, i);
op_pk_send (pkptr, OUT_STRM);
/* Erase drawing of packet in animation. */
op_ici_attr_get (iciptr, "pk_did", &pk_did);
op_anim_igp_drawing_erase (vid, pk_did, OPC_ANIM_ERASE_MODE_XOR);
break;
}
}
Details
This operation provides two independent services:
- erasing a retained drawing from a viewer
- deallocating the memory associated with the retained drawing so that it will not be redrawn when the viewer is redrawn.
The mode of drawing erasure is set by the mode argument. The most common mode erases a drawing by re-displaying it using the XOR (exclusive-OR) pixop graphical property; this mode is specified by the symbolic constant OPC_ANIM_ERASE_MODE_XOR. Provided that the drawing was originally displayed using this pixop, and that the drawing has not been subsequently overlapped by other non-XOR pixop graphical figures, this technique will perfectly excise the drawing from the viewer, leaving behind no graphical side-effects.
To display retained drawings using the XOR pixop, specify the graphical property flag OPC_ANIM_PIXOP_XOR. The redraw mode (specified by the symbolic constant OPC_ANIM_ERASE_MODE_REDRAW) does not directly erase a drawing; instead, it deallocates the drawing first and then redraws the whole viewer. This has the net effect of erasing a drawing, and has the advantage over the XOR mode that it can erase drawings displayed in any pixop. However, it also has the side-effect of erasing any non-retained graphical figures, and can produce sluggish and choppy animations if used frequently.
There is also a disabled erase mode (specified by the symbolic constant OPC_ANIM_ERASE_MODE_NONE) that does not erase a drawing, but just deallocates it. This mode depends on a subsequent viewer redraw for the erasure to take effect. In addition to the sources of viewer IDs listed in the Reference section below, 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 erase retained drawings which no longer should be displayed in a dynamic animation. The capability to retain a drawing provides user flexibility in op_vuanim (i.e., viewers can be moved, resized, or circulated, and retained drawings will be redisplayed). The capability to erase a drawing supports the non-monotonic updating of viewers, permitting dynamic animations which track the state of a simulation. Typical applications of drawing erasure include moving nodes, dynamic status indicators (symbols and text which are only displayed when certain conditions hold), and lines depicting dynamic connectivity.
Errors
- Diagnostic Error: Animation viewer ID (
<anvid>) is out-of-range. (due to an invalid value for theanvidargument) - Diagnostic Error: Animation drawing ID (
<andid>) is out-of-range. (due to an invalid value for theandidargument)
Reference
- use any of the
op_anim_igp…KPs to create drawings which can later be erased by this KP - Use the KP op_anim_viewer_redraw() to effect the erasure of drawings which have been deallocated using this KP and the
OPC_ANIM_ERASE_MODE_NONE-specified mode - 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