op_anim_igp_macro_draw()
摘要
带有一组寄存器赋值列表调用宏,在指定的查看器内产生绘图。
语法
op_anim_igp_macro _draw (anvid, props, anmid, [ regid, regval, ]… OPC_EOL)
| 参数 | 类型 | 说明 |
|---|---|---|
anvid |
Anvid |
查看器 ID [该值是引用某个查看器的数字标识符。宏将在该查看器窗口的上下文中被调用。] |
props |
int |
图形属性标志 [该值是动画图形属性标志 OPC_ANIM_COLOR_*、OPC_ANIM_PIXOP_*、OPC_ANIM_BGCOLOR_*、OPC_ANIM_STYLE_*、OPC_ANIM_ALIGNH_*、OPC_ANIM_ALIGNV_*、OPC_ANIM_FONT_* 和 OPC_ANIM_RETAIN 按位 OR 组合。更多信息见“Animation“ 第 3 页。] |
anmid |
Anmid |
宏 ID [该值是引用待调用宏的数字标识符。] |
regid |
int |
绘图寄存器 ID [该值是数字代码,标识待赋值的特定宏寄存器。] |
regval |
void* |
用于赋给宏寄存器的值 |
返回类型
Andid
宏调用的绘图 ID
[保留绘图会被分配 ID,以便之后可以被擦除(参见参考部分)。要使绘图被保留,必须传入图形属性标志 OPC_ANIM_RETAIN。非保留绘图会被分配 ID 常量 OPC_ANIM_ID_NIL。]
示例
/* 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);
详情
此 KP 的参数包含一个包含零个或多个寄存器赋值的列表。每个寄存器赋值由一对相邻的参数(regid 和 regval)表示,列表以符号常量 OPC_EOL(“End-Of-List”)结尾。名为 A-Z 的 26 个宏寄存器由预定义的符号常量标识,这些常量列于“Animation Macro Register Identifier Symbolic Constants—Integer Values“ 第 8 页。由于宏寄存器可以保存 integer、double 或字符串(char*)值,regval 参数接受这些类型中的任意一种。regval 参数声明为 void*,但其实际类型必须与对应寄存器 ID 的类型匹配。
宏绘图只受 retain 图形属性的影响。设置了 retain 图形属性(OPC_ANIM_RETAIN)的宏绘图,将在关联的查看器窗口每次重绘时重新绘制;默认情况下,它们会直接消失。宏作为整体被保留;宏内的 op_anim_mgp… 请求没有独立的保留控制,也不接受 retain 图形属性。
如果 retain 图形属性未启用,或者由于缺少自定义动画探针、或存在当前未激活的自定义动画探针而导致 KP 执行被禁用,此 KP 将返回由符号常量 OPC_ANIM_ID_NIL 标识的特殊值。
除了参考部分列出的查看器 ID 来源之外,符号常量 OPC_ANIM_ANVID_PBSPEC 也可用作替代查看器 ID,表示真正的查看器 ID 应从处于激活状态的无标签自定义动画探针获取。
用途
提供了一种调用称为宏的参数化动画请求序列的机制。宏将动画请求封装起来,使其可以作为单一单元来处理。此 KP 便捷地支持从单个函数调用执行多个动画请求。不过,把 op_anim_igp… 内核过程放入一个 C 函数也能做到这一点。宏提供的更重要的服务是:
- 通过调用 op_anim_igp_drawing_erase() 擦除宏所有请求的能力
- 通过调用 op_anim_igp_macro_redraw() 更新宏绘图所选寄存器值的能力
- 通过调用 op_anim_mme_nobj_pos() 在宏内获取并使用模型对象位置的能力
错误
- 程序中止:segmentation violation(由于
regid或regval参数的数据类型不正确) - 可恢复错误:Animation macro register ID (
<regid>) is invalid. Unable to continue animation flow.(由于某个regid参数的值无效) - 诊断错误:Animation viewer ID (
<anvid>) is out-of-range.(由于anvid参数的值无效) - 诊断错误:Animation macro ID (
<anmid>) is out-of-range.(由于anmid参数的值无效)
参考
- 使用内核过程 op_anim_macro_create() 创建宏,并使用
op_anim_mgp…内核过程定义它 - 使用内核过程 op_anim_igp_macro_redraw() 以新的寄存器赋值重绘宏
- 使用内核过程 op_anim_igp_drawing_erase() 擦除并释放由本内核过程创建的保留宏绘图
- 使用内核过程 op_anim_viewer_open() 或 op_anim_viewer_open_std() 获取新创建动画查看器的 ID(或与此前已打开的查看器会合),或使用内核过程 op_anim_lprobe_anvid() 获取由带标签的自定义动画探针打开的查看器的 ID