op_anim_mgp_line_draw()
Abstract
Adds a primitive that draws a line segment to the specified macro.
Syntax
op_anim_mgp_line_draw (anmid, props, x1, y1, x2, y2)
| Argument | Type | Description |
|---|---|---|
anmid |
Anmid |
macro ID [This value is a numeric identifier which references an open animation macro, created via the KP op_anim_macro_create().] |
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.] |
x1 |
int |
x coordinate of line’s first endpoint |
y1 |
int |
y coordinate of line’s first endpoint |
x2 |
int |
x coordinate of line’s second endpoint |
y2 |
int |
y coordinate of line’s second endpoint [The x1, x2, y1, and y2 coordinate values are measured in pixels from the origin of the viewer window (upper-left corner).] |
Return Type
void
no return value
Example
/* Create a macro which draws a line between two nodes. */
mid = op_anim_macro_create ("node dynconn");
/* Determine the positions of the nodes A & B; the position of A is */
/* stored in (M,N) and the position of B is stored in (O,P). */
op_anim_mme_nobj_pos (mid, OPC_ANIM_OBJTYPE_NODE, OPC_ANIM_REG_A_STR,
OPC_ANIM_REG_M_INT, OPC_ANIM_REG_N_INT, OPC_ANIM_VERTEX_ICON_CTR);
op_anim_mme_nobj_pos (mid, OPC_ANIM_OBJTYPE_NODE, OPC_ANIM_REG_B_STR,
OPC_ANIM_REG_O_INT, OPC_ANIM_REG_P_INT, OPC_ANIM_VERTEX_ICON_CTR);
/* Draw the line between the nodes. */
op_anim_mgp_line_draw (mid, OPC_ANIM_COLOR_GREEN,
OPC_ANIM_REG_M_INT, OPC_ANIM_REG_N_INT, OPC_ANIM_REG_O_INT, OPC_ANIM_REG_P_INT);
/* Execute the macro for source & destination nodes. */
op_anim_igp_macro_draw (vid, OPC_ANIM_RETAIN, mid,
OPC_ANIM_REG_A_STR, src_nd_name,
OPC_ANIM_REG_B_STR, dst_nd_name, OPC_EOL);
Details
The props, x1, y1, x2, and y2 arguments of this KP will accept macro register ID symbolic constants, as listed under “Animation Macro Register Identifier Symbolic Constants—Integer Values“ on page 8. If register IDs are supplied for these arguments, the actual values are taken from the specified registers at the time of macro invocation.
Line drawings are affected by the color, pixop, and style graphical properties. The color graphical property of the line can be assigned any of the 64 indexed color values (with the format OPC_ANIM_COLOR_RGB<rgb>) or the 25 named color values (the default color is black). If the pixop graphical property is set to a value other than the default (OPC_ANIM_PIXOP_SRC), portions of the line which are drawn over non-black viewer pixels may be displayed in a color other than that assigned (note that the pixop value OPC_ANIM_PIXOP_XOR should be used if the specified macro will be invoked with the retain property for later erasure). The style graphical property of a line can take on one of three values: solid lines can be specified by the symbolic constant OPC_ANIM_STYLE_SOLID (the default), dashed lines by OPC_ANIM_STYLE_DASHES, and dotted lines by OPC_ANIM_STYLE_DOTS.
Purpose
Provides a mechanism to draw a line segment in the context of a macro. The line segment 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. Line drawings are useful for depicting dynamic connections between model diagram components: examples include remote interrupts, packet deliveries, radio transmissions, and established circuits. Such applications can be performed by loading the positions of model objects into macro registers via the KP op_anim_mme_nobj_pos().
Errors
- Recoverable Error: Animation macro ID (
<anmid>) is [out-of-range] [unrecognized]. (former case due toanmidargument value that is invalid, latter case to destroyed macro) - Diagnostic Error: Invalid property component (
<prop_comp>) for graphical primitive. (due to an inapplicable or invalid literal value for thepropsargument) - Diagnostic Error: Kernel procedure argument (
<arg>) has out-of-range value (<val>). (due to a literal value for the argumentsx1,y1,x2, ory2that exceeds the range of a short)
Reference
- Use the KP op_anim_mgp_rect_draw() to draw a square or rectangle
- Use the KP op_anim_igp_line_draw() to draw a line in immediate mode
- Use the KP op_anim_macro_create() to create an empty macro
- Use the KP op_anim_macro_close() to indicate the completion of a macro definition
- Use the KP op_anim_igp_macro_draw() to invoke a macro within a viewer