op_anim_igp_macro_redraw()
Abstract
Reinvokes the macro associated with an existing drawing, providing a list of new register assignments. The previously created drawing is referenced by its drawing ID, and is typically erased before its associated macro is redrawn.
Syntax
op_anim_igp_macro_redraw (anvid, andid, mode, [ regid, regval, ]… OPC_EOL)
| Argument | Type | Description |
|---|---|---|
anvid |
Anvid |
viewer ID [This value is a numeric identifier which references a viewer. The specified drawing’s associated macro will be re-invoked in the context of the viewer’s window.] |
andid |
Andid |
drawing ID of previously drawn macro |
mode |
int |
erase mode [This is a numeric code which identifies the technique used for erasure of the macro drawing’s previous on-screen appearance. The erase mode symbolic constants are listed in the Details section.] |
regid |
int |
drawing register ID [This value is a numeric code which identifies a specific macro register to be assigned.] |
regval |
void* |
value for assignment to macro register |
Return Type
void
no return value
Example
/* Determine type of interrupt. */
itype = op_intrpt_type ();
/* Process queue statistic interrupt. */
if (itype == OPC_INTRPT_STAT)
{
/* Map queue level into color value. */
queue_size = op_stat_local_read (op_intrpt_stat ());
if (queue_size < 5)
color = OPC_ANIM_COLOR_BLUE;
else if (queue_size < 10)
color = OPC_ANIM_COLOR_PURPLE;
else color = OPC_ANIM_COLOR_PINK;
/* Redraw queue status indicator with new color. */
op_anim_igp_macro_redraw (vid, did, OPC_ANIM_ERASE_MODE_XOR,
OPC_ANIM_REG_C_INT, color, OPC_EOL);
}
Details
The arguments to this KP include a list of zero or more register assignments. Each register assignment is represented by a pair of adjacent arguments (regid and regval), and the list is terminated by the symbolic constant OPC_EOL (“End-Of-List”). The 26 macro registers named A-Z are identified by predefined symbolic constants listed under “Animation Macro Register Identifier Symbolic Constants—Integer Values“ on page 8. Since macro registers can hold integer, double, or string (char*) values, the regval arguments are declared as void*, but can be any of these three data types.
Before a macro is redrawn with the new register assignments, its existing drawing is erased. The mode of drawing erasure is set by the mode argument, which can take one of three symbolic constant values. The XOR mode (exclusive-OR; specified by OPC_ANIM_ERASE_MODE_XOR) erases the macro drawing by re-invoking it with the old register values. The redraw mode (specified by OPC_ANIM_ERASE_MODE_REDRAW) erases the macro drawing by redrawing the viewer, and then re-invokes the macro. The disabled erase mode (specified by OPC_ANIM_ERASE_MODE_NONE) is not useful for this KP. More information on erase modes appears in the Details section of the KP op_anim_igp_drawing_erase().
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 reinvoke a previously drawn macro with new parameters (register assignments). This is roughly equivalent to erasing the previous macro drawing via the KP op_anim_igp_drawing_erase() and then reinvoking the macro via the KP op_anim_igp_macro_draw(). However, the redraw KP provides the convenience of a single call format and only requires the specification of register assignments that have changed. A typical strategy involving animation macros: a macro that has several parameters is only drawn with all register assignments at the start of a simulation, and thereafter, it is redrawn with only one or two register assignments as conditions change. Macros which include the KP op_anim_mme_nobj_pos() require special design for proper redraw; see the op_anim_mme_nobj_pos() KP for information on this topic.
Errors
- Program Abort: segmentation violation (due to incorrect data types for the
regidorregvalarguments) - Recoverable Error: Animation macro register ID (
<regid>) is invalid. Unable to continue animation flow. (due to an invalid value for aregidargument) - 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 the KP op_anim_macro_create() to create a macro, and
op_anim_mgp…KPs to define it - Use the KP op_anim_igp_macro_draw() to initially draw a macro
- Use the KP op_anim_igp_drawing_erase() to erase and deallocate a retained macro drawing
- 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