llSetLinkTextureAnim

From Second Life Wiki
Jump to navigation Jump to search

Summary

Function: llSetLinkTextureAnim( integer link, integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate );

Animate the texture on the specified face/faces of the specified prim/prims by setting the texture scale and offset. Identical to llSetTextureAnim except able to modify any prim in the link set.

• integer link Link number (0: unlinked, 1: root prim, >1: child prims and seated avatars) or a LINK_* flag to effect
• integer mode mask of Mode flags
• integer face face number or ALL_SIDES
• integer sizex horizontal frames (ignored for ROTATE and SCALE)
• integer sizey vertical frames (ignored for ROTATE and SCALE)
• float start Start position/frame number (or radians for ROTATE)
• float length number of frames to display (or radians for ROTATE)
• float rate frames per second (must not be zero)

If face is ALL_SIDES then the function works on all sides. start supports negative indexes. Frames are numbered from left to right, top to bottom, starting at 0.
If rate is negative, it has the same effect as using the REVERSE flag.[2]

Specification

Index Positive Negative
First 0 -length
Last length - 1 -1

Indexes

  • Positive indexes count from the beginning, the first item being indexed as 0, the last as (length - 1).
  • Negative indexes count from the far end, the first item being indexed as -length, the last as -1.

Frames

Frames are sub-rectangles within the texture. A set of frames with 2 horizontal (sizex) and 3 vertical (sizey) means the overall texture is divided into 3 rows of 2 columns of images, each of which is a frame. llSetLinkTextureAnim will animate across these 6 starting with the top left image and going across and down, optionally repeating. If SMOOTH is set the frames slide smoothly from one to the next, if off, each frame is displayed in turn centered on the face.

Flag Description
LINK_ROOT 1 refers to the root prim in a multi-prim linked set[1]
LINK_SET -1 refers to all prims
LINK_ALL_OTHERS -2 refers to all other prims
Flag Description
LINK_ALL_CHILDREN -3 refers to all children, (everything but the root)
LINK_THIS -4 refers to the prim the script is in

Modes Description
ANIM_ON 0x01 Texture animation is on. This must be set to start the animation, cleared to stop it.
LOOP 0x02 Loop the texture animation.
REVERSE 0x04 Play animation in reverse direction.
PING_PONG 0x08 Play animation going forwards, then backwards.
SMOOTH 0x10 Slide in the X direction, instead of playing separate frames.
In both SCALE and ROTATE modes, causes smooth transitions.
ROTATE 0x20 Animate texture rotation.
Does not work with SCALE
SCALE 0x40 Animate the texture scale.
Does not work with ROTATE

Caveats

  • The function silently fails if its face value indicates a face that does not exist.
  • If start is out of bounds the script continues to execute without an error message.
  • You can only have one texture animation on a prim
    • Calling llSetLinkTextureAnim more than once on a prim will reset it.
    • Calling llSetLinkTextureAnim again with exact same values will not reset animation (a small difference in rate will suffice).
  • You cannot combine ROTATE and SCALE flags.
  • sizex & sizey are both limited to a range of 0 to 255
  • llSetLinkTextureAnim when on shows the texture with 1 repeat in X and Y and 0 rotation and offset.
  • Selecting and un-selecting a prim with animation will reset animation from beginning.

Important Issues

~ All Issues ~ Search JIRA for related Bugs
   Some persistent prim properties lost when duplicated
   Texture Animation is not copied (llSetTextureAnim)
   Texture animations ignore repeats per face

Examples

This slides a texture smoothly, along the horizontal U-axis, and loops it when it gets to the end.

<lsl>llSetLinkTextureAnim(LINK_THIS, ANIM_ON

Notes

Link Numbers

Each prim that makes up an object has an address, a link number. To access a specific prim in the object, the prim's link number must be known. In addition to prims having link numbers, avatars seated upon the object do as well.

  • If an object consists of only one prim, and there are no avatars seated upon it, the (root) prim's link number is zero.
  • However, if the object is made up of multiple prims or there is an avatar seated upon the object, the root prim's link number is one.

When an avatar sits on an object, it is added to the end of the link set and will have the largest link number. In addition to this, while an avatar is seated upon an object, the object is unable to link or unlink prims without unseating all avatars first.

Counting Prims & Avatars

There are two functions of interest when trying to find the number of prims and avatars on an object.

integer GetPrimCount() { //always returns only the number of prims
    if(llGetAttached())//Is it attached?
        return llGetNumberOfPrims();//returns avatars and prims but attachments can't be sat on.
    return llGetObjectPrimCount(llGetKey());//returns only prims but won't work on attachments.
}
See llGetNumberOfPrims for more about counting prims and avatars.

Errata

If a script located in a child prim erroneously attempts to access link 0, it will get or set the property of the linkset's root prim. This bug (BUG-5049) is preserved for broken legacy scripts. Texture animation is a property of the prim (i.e., you can remove the script that started the animation, and the prim will remember the settings anyway.) Note, though, that as of Jan 2009, texture animation is still one of the prim properties that are lost when using the rezzed in world copy method of shift-drag. Originally brought up in VWR-640, it got its own issue in SVC-3925

An online-tool for rough and ready conversion of moving gifs to animated textures is here: http://www.peregrinesalon.com/anim/ (link valid as of Jan 2009.)

See Also

Functions

•  llGetLinkNumber Returns the link number of the prim the script is in.
•  llSetTextureAnim Set texture animation for the prim the script is on.

Articles

•  Negative Index

Deep Notes

All Issues

~ Search JIRA for related Issues
   Some persistent prim properties lost when duplicated
   Texture Animation is not copied (llSetTextureAnim)
   Texture animations ignore repeats per face

Footnotes

  1. ^ LINK_ROOT does not work on single prim objects. Unless there is an avatar sitting on the object.
  2. ^ Though if rate is negative and the REVERSE flag is used, they cancel each other out.

Signature

function void llSetLinkTextureAnim( integer link, integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate );