Animation Script Reference - Utility Programs Reference Manual 1 op

The animation script language provides a simple syntax for describing an animation flow. An animation script comprises a single list of a flow’s requests encoded in the form of statements. Statements are terminated by semi-colons, and may be padded with space or tab characters, split across file lines,

combined with other statements on a single line, or surrounded by blank lines. However, it is conventional in scripts to place each statement on its own line, aligned to the left-most character of the line.

The format of each statement is the same, and includes the following information:

• simulation time when the request was issued

• execution ID of simulation event that was executing when the request was issued

• request name keyword

A typical request statement is displayed below. Note that the time, event, and request argument fields are not explicitly labeled within the statement itself; thus the formats of the statement and its associated request are usually needed to decipher the data contents of a statement.

Figure 1-33 Example Animation Script Statement

Each request supported by the animation script language is documented by its own entry later in this section. A request entry presents the syntax format of the request, including the request’s name and argument list, but not the simulation time, event ID, or terminator fields of a request statement. An entry also provides a description of each request argument. An example entry appears on the next page.

23.222142 3183 viewer_open 2 rtstats 100 100 600 400 ;

simulation time

event ID request name

Detailed information on the functionality and purpose of animation script requests is not provided in their entries. For these details, refer to the Animation Package chapter of the Simulation Kernel manual. Functionality information is provided for animation script requests that do not have an exact Kernel Procedure equivalent.

Figure 1-34 Example Animation Request Entry

In general, for every animation script request type, there is an equivalent Anim package Kernel Procedure (labeled in request entries as the KP Analog). However, there are some special cases in which there is not an exact equivalency, such as:

• Anim KPs that just provide a local service to simulation processes or

procedures without issuing any requests (this case includes op_anim_ime_gen_pos(), op_anim_lprobe_anvid(), and op_anim_macro_close()).

• Anim KPs that implement a graphical operation by issuing multiple separate

requests (this case includes op_anim_ime_nmod_draw(), which issues the ime_nmod_load and ime_mod_draw requests to load and draw a model).

• Anim KPs with a variable number of arguments that issue an initial request

followed by a series of argument-setting requests and a termination request (this case includes op_anim_igp_macro_draw(),

op_anim_igp_macro_redraw(), and op_anim_ime_nobj_update(), which request syntax format

equivalent Anim package

Kernel Procedure request argument data

viewer_open<anvid> <name> <x> <y> <w> <h>

Argument Type Description

<anvid> Anvid viewer ID

<name> string viewer name

<x> integer X coordinate of viewer upper-left corner <y> integer Y coordinate of viewer upper-left corner

<w> integer width of viewer

<h> integer height of viewer

respectively issue the initial requests igp_macro_draw, igp_macro_redraw, and ime_nobj_update; the initial requests are followed by a series of arg_int, arg_dbl, or arg_str requests that set integer, double, or string arguments, and then by the arg_eol list termination request).

• Anim KPs that issue a different request depending on the type of data passed to their arguments (this case include op_anim_mgp_reg_set(), which issues the mgp_reg_set_int, mgp_reg_set_dbl, and mgp_reg_set_str requests). The arguments of animation script requests are all literal constants encoded in ASCII (i.e., there are no variable or macro capabilities in the script language). Argument data types are defined for distinct categories of information, as documented in the table below. Note that these data types are similar in many instances to the corresponding C data types used to declare the arguments of Anim package KPs; however, the script language supports specialized data types and associated assignment syntax to make specification of arguments convenient.

Table 1-6 Animation Request Argument Data Types Data Type Example Value Description

Internal C Storage Class

integer 5 general integer

value int or short double 6.73 general floating-point value double string word "several words"

general text value; spaces can be included if string is surrounded by double-quotes

char []

Anvid 44 viewer ID (integer) int

Anmid 32 macro ID (integer) int

Andid 12 drawing ID

(integer)

int

keyword xor_reset single-word value,

from an

enumerated set of words

char or short

keyword list { retain_on, setup_on } brace-enclosed, comma-separated list of keywords char or short End of Table 1-6

Keywords are defined for many predefined enumerated values, such as request options. These keywords are concise because they rely on the

animation-specific nature of scripts, in contrast to the much more verbose Anim package symbolic constants used in simulation processes and procedures. Most of the enumerated keyword values are listed in the argument description section of request entries.

The common request argument <props> (graphical properties) has many enumerated values, and these keywords are listed only on the next page. <props> arguments are declared as keyword lists, and they accept a brace-enclosed list of graphical property keywords. Graphical property

keywords are categorized into property classes. In general, graphical properties from different classes are independent and can be combined, but graphical properties from the same class will produce unexpected results if combined. Table 1-7 Accepted Keywords for <props> Argument (Part 1 of 2)

Property Class Keywords

horizontal alignment alignh_centeralignh_leftalignh_right vertical alignment alignv_bottomalignv_centeralignv_top color names / RGB

(the keyword prefix  may be one of the following: color for foreground color, or bgcolor for background color) _rgb000_rgb001_rgb002_rgb003 _rgb010_rgb011_rgb012_rgb013 _rgb020_rgb021_rgb022_rgb023 _rgb030_rgb031_rgb032_rgb033 _rgb100_rgb101_rgb102_rgb103 _rgb110_rgb111_rgb112_rgb113 _rgb120_rgb121_rgb122_rgb123 _rgb130_rgb131_rgb132_rgb133 _rgb200_rgb201_rgb202_rgb203 _rgb210_rgb211_rgb212_rgb213 _rgb220_rgb221_rgb222_rgb223 _rgb230_rgb231_rgb232_rgb233 _rgb300_rgb301_rgb302_rgb303 _rgb310_rgb311_rgb312_rgb313 _rgb320_rgb321_rgb322_rgb323 _rgb330_rgb331_rgb332_rgb333 color names / standard

(the keyword prefix  may be one of the following: color for foreground color, or bgcolor for background color) _beige_black_blue_brick _brown_corn_cyan_fuchsia _green_magenta_maroon_olive _orange_orchid_peach_pink _plum_purple_red_tan _sienna_steel_tan_violet _white_yellow

text fonts font_open_10font_open_12font_open_14

An example <props> value is shown below; it sets the graphical properties of text drawn by an igp_text_draw request to be 18 point, green, and with alignment based on the top edge:

Figure 1-35 Example Text Graphical Property Value

One other common request argument is declared as a keyword list: the <arg_vals> argument of mgp and mme macro-based requests. This type of argument expects a fixed-size list of keywords that represent the source of values for the other requests arguments. A value source may be: (a) a specified macro drawing register (identified by a keyword of the form “reg_<C>”, where <C> is a single character); (b) a literal value specified later in the request statement (identified by the keyword “constant”). Thus the <arg_vals> argument configures a particular format for the mgp and mme requests, by specifying the number of additional arguments to be expected after <arg_vals>. The size of the <arg_vals> list is determined by the number of arguments supported by a request; this number appears in the request entry declarations of <arg_vals>. An example value for <arg_vals> appears below.

Figure 1-36 Example of Value Source Specification in Macro Request

pixel operators pixop_andpixop_dstpixop_eqvpixop_nand pixop_ndstpixop_nodstpixop_norpixop_nosrc pixop_nsrcpixop_odstpixop_onepixop_or pixop_osrcpixop_osrcpixop_xorpixop_zero macro setup flag setup_offsetup_on

drawing styles style_dashesstyle_dotsstyle_patternstyle_solid drawing retention flag retain_offretain_on

End of Table 1-7

Table 1-7 Accepted Keywords for <props> Argument (Part 2 of 2) Property Class Keywords

{ font_open_18, color_green, alignv_top }

0.51 39 mgp_circle_draw 23 { reg_p, reg_x, reg_y, constant } 21;

The mechanism for specifying attribute sources via <arg_vals> presents a complication for optional arguments that are only present when another argument includes a particular value. This situation is limited to the optional <pat_name> argument of the mgp_bg_fill, mgp_circle_fill, and mgp_rect_fill requests, which normally should only be included if the <props> argument includes the style_pattern property keyword. The following special

considerations affect these requests:

• the number of items in the <arg_vals> list is always the same (i.e., a keyword in this list applies to the <pat_name> argument, whether or not <pat_name> is assigned a value from the request statement)

• if the <props> argument is specified by a literal value in the request statement, and it includes the style_pattern property keyword, and the

<arg_vals> argument specifies that the

<

pat_name> argument expects a

literal value, then <pat_name> should appear in the request statement • if the <props> argument is specified by a reference to a macro drawing

register, and the <arg_vals> argument specifies that the <pat_name> argument expects a literal value, then <pat_name> should appear in the request statement

• excluding the above cases, <pat_name> should not appear in the request statement

Animation Script Requests

arg_int <anvid> <arg_id> <value>

Argument Type Description

<anvid> Anvid viewer ID

<arg_id> integer argument ID

[This numeric identifier specifies the target of the argument assignment performed by this request. If this request is issued in the context of an igp_macro_draw or igp_macro_redraw request, <arg_id> specifies the target register of a macro (the ID range [0-25] specifies the register range [A-Z]); if this request is being issued in the context of an ime_nobj_update request, <arg_id> specifies the target object attribute (the only object attribute assignable as an integer is “color”, as specified by an ID of 0).]

<value> integer argument value

[When assigning an object’s color, the range of accepted values is [0-63].]

KP Analog: None

arg_dbl <anvid> <arg_id> <value>

Argument Type Description

<anvid> Anvid viewer ID

<arg_id> integer argument ID

[This numeric identifier specifies the target of the argument assignment performed by this request. If this request is issued in the context of an igp_macro_draw or igp_macro_redraw request, <arg_id> specifies the target register of a macro (the ID range [0-25] specifies the register range [A-Z]); if this request is being issued in the context of an ime_nobj_update request, <arg_id> specifies the target object attribute (the only object attributes assignable as doubles are “x position” and “y position”, as specified by the IDs 2 and 3, respectively).]

<value> double argument value KP Analog: None

arg_str <anvid> <arg_id> <value>

Argument Type Description

<anvid> Anvid viewer ID

<arg_id> integer argument ID

[This numeric identifier specifies the target of the argument assignment performed by this request. If this request is issued in the context of an igp_macro_draw or igp_macro_redraw request, <arg_id> specifies the target register of a macro (the ID range [0-25] specifies the register range [A-Z]); if this request is being issued in the context of an ime_nobj_update request, <arg_id> specifies the target object attribute (the only object attribute assignable as a string is “icon name”, as specified by an ID of 1).]

<value> string argument value KP Analog: None

arg_eol <anvid>

Argument Type Description

<anvid> Anvid viewer ID

[This request terminates a series of arg_<type> requests, where <type> is either int, dbl, or str. Argument assignment requests follow requests that have a variable number of arguments:

igp_macro_draw, igp_macro_redraw, and ime_nobj_update.]

KP Analog: None

force

Argument Type Description no arguments KP Analog: op_anim_force()

flow_end

Argument Type Description no arguments KP Analog: op_anim_flow_end()

igp_bg_fill <anvid> <props> [<pat_name>] [<andid>]

Argument Type Description

<anvid> Anvid viewer ID

<props> keyword list

graphical property list

[<pat_name>] string pattern name

[This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.]

[<andid>] Andid drawing ID of request

[This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.]

igp_circle_draw <anvid> <props> <ctr_x> <ctr_y> <radius> [<andid>]

Argument Type Description

<anvid> Anvid viewer ID

<props> keyword list

graphical property list

<ctr_x> integer X coordinate of the circle’s center point <ctr_y> integer Y coordinate of the circle’s center point <radius> integer radius of the circle

[<andid>] Andid drawing ID of request

[This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.]

KP Analog: op_anim_igp_circle_draw()

igp_circle_fill <anvid> <props> [<pat_name>] <ctr_x> <ctr_y> <radius> [<andid>]

Argument Type Description

<anvid> Anvid viewer ID

<props> keyword list

graphical property list

[<pat_name>] string pattern name

[This argument is optional, and should only be included if the <props> argument includes the property flag style_pattern.]

<ctr_x> integer X coordinate of the circle’s center point <ctr_y> integer Y coordinate of the circle’s center point <radius> integer radius of the circle

[<andid>] Andid drawing ID of request

[This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.]

igp_drawing_erase <anvid> <andid> <mode>

Argument Type Description

<anvid> Anvid viewer ID

<andid> integer drawing ID [<mode> keyword erase mode

[Accepted erase mode keywords are: none, redraw, xor, and xor_reset.]

KP Analog: op_anim_igp_drawing_erase()

igp_icon_draw <anvid> <props> <ic_name> <x> <y> [<andid>]

Argument Type Description

<anvid> Anvid viewer ID

<props> keyword list

graphical property list

<ic_name> string icon name

<x> integer X coordinate of icon upper-left corner <y> integer Y coordinate of icon upper-left corner [<andid>] Andid drawing ID of request

[This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.]

igp_line_draw <anvid> <props> <x1> <y1> <x2> <y2> [<andid>]

Argument Type Description

<anvid> Anvid viewer ID

<props> keyword list

graphical property list

<x1> integer X coordinate of line’s first endpoint <y1> integer Y coordinate of line’s first endpoint <x2> integer X coordinate of line’s second endpoint <y2> integer Y coordinate of line’s second endpoint [<andid>] Andid drawing ID of request

[This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.]

KP Analog: op_anim_igp_line_draw()

igp_macro_draw <anvid> <props> <anmid> [<andid>]

Argument Type Description

<anvid> Anvid viewer ID

<props> keyword list

graphical property list

<anmid> Anmid macro ID

[<andid>] Andid drawing ID of request

[This numeric identifier is assigned to the drawing produced by this request. This argument is optional, and should only be included if the <props> argument includes the property flag retain_on.]

This request is followed by a series of one or more argument-setting requests of the types arg_int, arg_dbl, or arg_str; each of these requests specifies a macro register and its new value. The list of argument requests is terminated by a request of the type arg_eol. KP Analog: op_anim_igp_macro_draw()

igp_macro_redraw <anvid> <andid> <mode>

Argument Type Description

<anvid> Anvid viewer ID

<andid> Andid drawing ID of previously drawn macro

<mode> keyword erase mode

[Accepted erase mode keywords are: none,

redraw, xor, and xor_reset.]

igp_rect_draw <anvid> <props> <x> <y> <width> <height> [<andid>]

In document Utility Programs Reference Manual 1 op_vuanim Utility (Page 34-65)