jit.anim.drive

Animate a 3D transform

Description

Animates relative transforms over time with easing. The jit.anim.drive object works in conjunction with jit.anim.node and OpenGL objects to perform this function. Double clicking the object will open a ui mapping dictionary, allowing certain user interface actions to be mapped to animation messages.

Examples

Animate a 3D transform

Discussion

UI mapping of key and mouse input is facilitated by editing the ui-map dictionary. Key input is mapped alpha-numeric keys and arrow keys (using up, down, left and right instead of the key symbol). Mouse mapping looks for the following dictionary entries:
Horizontal: mouse_horizontal, mouse_h, mouse_x
Horizontal with button down: mouse_down_horizontal, mouse_down_h, mouse_down_x
Vertical: mouse_vertical, mouse_v, mouse_y
Vertical with button down: mouse_down_vertical, mouse_down_v, mouse_down_y
UI input can be mapped to move, turn and grow messages.

Attributes

active [int]

g/s(get)

Indicates if the object is currently animating.

automatic [int]

Enables automatic update messages (default = 1). Requires the targetname object to belong to a valid OpenGL context.

drawto [symbol]

Assign to the named drawing context, allowing for updates to be received automatically.

ease [float]

Set both easein and easeout attributes (default = 1.).

easefunc [symbol]

Determines how the easing is applied (default = linear).

Possible values:

'linear'
'quadratic'
'cubic'

easein [float]

Determines how long it will take (in seconds) for a specific animation message to go from it's current value to the new value (default = 1.). This attribute only affects the move, turn and grow animations.

easeout [float]

Determines how long it will take (in seconds) for a specific animation message to go from it's current value to 0 (default = 1.). This attribute only affects the move, turn and grow animations.

evalreport [int]

Enable/disable the evaluation parameter reporting out the dumpout (default = 0). The report is a 3 element list where each element represents the current evaluation parameters for the moveto, rotateto, and scaleto messages, in that order.

name [symbol]

Specifies the name of the instance (default = UID).

position [3 floats]

The current stored position in 3D space. This attribute is used for the moveto and springto messages (default = 0 0 0).

quat [4 floats]

The current orientation in 3D space, stored as a quaternion value. This attribute is used for the rotateto message (default = 0 0 0 1).

scale [3 floats]

The current stored scale in 3D space. This attribute is used for the scaleto message (default = 1 1 1).

speed [float]

The speed of animations in units per second. (default = 30.)

spring_damp [float]

The dampening amount applied to the spring equation used in the springto message (default = 0.1).

spring_mass [float]

The mass amount applied to the spring equation used in the springto message (default = 1.).

spring_stiff [float]

The stiffness amount applied to the spring equation used in the springto message (default = 0.2).

spring_thresh [float]

The threshold value to determine when the spring simulation is no longer active. Used in the springto message (default = 0.0001).

targetname [symbol]

The name of the target object that should be either an OpenGL object, or a jit.anim.node object.

ui_listen [int]

Cause UI mouse and keyboard messages to be received from context window (default = 0). Requires the targetname object to belong to a valid OpenGL context.

ui_map [symbol]

Name associated with the ui mapping dictionary (default = UID). If an existing dictionary is registered to that name, this dictionary will reference the registered dictionary.

ui_map_clone [symbol]

The name of a registered dictionary to clone as the UI mapping dictionary.

ui_priority [int]

UI priority value (default = 900). When multiple UI objects are listening to the same window, ui_priority determines the order objects receive input. Lower values test first.

Common Box Attributes

annotation [symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background [int] (default: 0)

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color [4 floats]

Sets the color for the object box outline.

fontface [int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic

Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname [symbol]

Sets the object's font.

fontsize [float]

Sets the object's font size (in points).

Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden [int] (default: 0)

Toggles whether an object is hidden when the patcher is locked.

hint [symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick [int] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation [int] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 0. 0. 0. 0.)

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect [4 floats]

g/s(set)

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size [2 floats]

g/s(set)

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor [float]

Sets the color for the object's text in RGBA format.

textjustification [int]

Text Justification

Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname [symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

Messages

bang

Causes the animation messages to be output, if currently animating.

anim_reset

Disable all animations

(mouse)

Mouse events

dictionary

Arguments

name [symbol]
The incoming dictionary is cloned and used to set the ui mapping.

grow

Arguments

x [float]
y [float]
z [float]
Scale the attached object along each axis by the amount provided. The axis arguments are multiplied by speed.

move

Arguments

x [float]
y [float]
z [float]
Move the attached object along the axis provided, relative to the space indicated by the objects's movemode attribute. The axis arguments are multiplied by speed.

moveto

Arguments

x [float]
y [float]
z [float]
duration [float]
Move the attached object to the specified position over the specified length of time (in seconds). Easing in and out is applied to the movement based on the easefunc attribute.

scaleto

Arguments

x [float]
y [float]
z [float]
duration [float]
Scale the attached object to the specified scale value over the specified length of time (in seconds). Easing in and out is applied to the scaling based on the easefunc attribute.

springto

Arguments

x [float]
y [float]
z [float]
Move the attached object to the specified position using a mass-spring simulation.

rotateto

Arguments

x [float]
y [float]
z [float]
w [float]
duration [float]
Rotate the attached object to the specified quaternion orientation over the specified length of time (in seconds). Easing in and out is applied to the rotation based on the easefunc attribute.

ui_dict

See the dictionary listing

ui_key

Arguments

key [symbol]
Send the specified key. If the key is in the ui mapping dictionary, the corresponding animation will be enabled.

ui_keyup

Arguments

key [symbol]
Send the specified keyup. If the key is in the ui mapping dictionary, the corresponding animation will be disabled.

ui_mouse

Arguments

screen-x [int]
screen-y [int]
mouse-down [int]
Send the mouse event. If the event is in the ui mapping dictionary, the corresponding animation will be enabled.

update_drive

See the bang listing

turn

Arguments

x [float]
y [float]
z [float]
Rotate the attached object along each axis by the amount provided, relative to the space indicated by the turnmode attribute. The axis arguments are multiplied by speed.

See Also

Name Description
jit.anim.node Perform hierarchical transformation
jit.anim.path Evaluate a path of 3D transform points
jit.gl.camera Set a rendering view