Difference between revisions of "LlSetTextureAnim"

From Second Life Wiki
Jump to navigation Jump to search
m (Replaced old <LSL> block with <source lang="lsl2">)
(19 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{Issues/SVC-3925}}{{Issues/SVC-1242}}{{Issues/VWR-4018}}{{LSL_Function/negative index|true|start}}{{LSL_Function/face|face}}{{LSL_Function
{{LSL_Function
|inject-2={{Issues/SVC-4897}}{{Issues/SVC-3925}}{{Issues/SVC-1242}}{{Issues/VWR-4018}}
|inject-3=
{{LSL_Function/face|face}}
{{LSL_Function/negative index|true|start}}
|func_id=211
|func_id=211
|func_sleep=0.0
|func_sleep=0.0
Line 5: Line 9:
|sort=SetTextureAnim
|sort=SetTextureAnim
|func=llSetTextureAnim
|func=llSetTextureAnim
|p1_type=integer|p1_name=mode|p1_desc=mask of Mode flags
|p1_type=integer|p1_subtype=bit_field|p1_name=mode|p1_desc=mask of Mode flags
|p2_type=integer|p2_name=face
|p2_type=integer|p2_name=face
|p3_type=integer|p3_name=sizex|p3_desc=horizontal frames (ignored for [[ROTATE]] and [[SCALE]])
|p3_type=integer|p3_name=sizex|p3_desc=horizontal frames (ignored for [[ROTATE]] and [[SCALE]])
Line 12: Line 16:
|p6_type=float|p6_name=length|p6_desc=number of frames to display (or radians for [[ROTATE]])
|p6_type=float|p6_name=length|p6_desc=number of frames to display (or radians for [[ROTATE]])
|p7_type=float|p7_name=rate|p7_desc=frames per second (must not be zero)
|p7_type=float|p7_name=rate|p7_desc=frames per second (must not be zero)
|func_footnote=Frames are numbered from left to right, top to bottom, starting at 0.<br/>If '''rate''' is negative, it has the same effect as using the [[REVERSE]] flag.{{Footnote|Though if '''rate''' is negative and the [[REVERSE]] flag is used, they cancel each other out.}}
|func_footnote=Frames are numbered from left to right, top to bottom, starting at 0.<br/>If {{LSLP|rate}} is negative, it has the same effect as using the [[REVERSE]] flag.{{Footnote|Though if {{LSLP|rate}} is negative and the [[REVERSE]] flag is used, they cancel each other out.|Though if 'rate' is negative and the [[REVERSE]] flag is used, they cancel each other out.}}
|func_desc=Animate the texture on the specified face/faces by setting the texture scale and offset.
|func_desc=Animate the texture on the specified face/faces by setting the texture scale and offset.
|return_text
|return_text
|spec=
|spec=
===Frames===
===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. llSetTextureAnim 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.
Frames are sub-rectangles within the texture. A set of frames with 2 horizontal ({{LSLP|sizex}}) and 3 vertical ({{LSLP|sizey}}) means the overall texture is divided into 3 rows of 2 columns of images, each of which is a frame. llSetTextureAnim 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 across each row but will "jump" from one row to the next, if off, each frame is displayed in turn centered on the face.
|caveats=*You can only have one texture animation on a prim
|caveats=*You can only have one texture animation on a prim
**Calling llSetTextureAnim more than once on a prim will reset it.
**Calling llSetTextureAnim more than once on a prim will reset the existing animation.
**Calling llSetTextureAnim again with exact same values will not reset animation (a small difference in rate will suffice).
*You cannot combine [[ROTATE]] and [[SCALE]] flags.
*You cannot combine [[ROTATE]] and [[SCALE]] flags.
*'''sizex''' & '''sizey''' are both limited to a range of 0 to 255
*{{LSLP|sizex}} & {{LSLP|sizey}} are both limited to a range of 0 to 255
*llSetTextureAnim when on shows the texture with 1 repeat in X and Y and 0 rotation and offset.
*llSetTextureAnim, 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.
|constants={{{!}} class="sortable collapsible" {{Prettytable|style=margin-top:0;}}
|constants={{{!}} class="sortable collapsible" {{Prettytable|style=margin-top:0;}}
{{!}}-{{Hl2}}
{{!}}-{{Hl2}}
Line 58: Line 64:
{{!}}}
{{!}}}
|examples=
|examples=
This slides a texture smoothly and loops it when it gets to the end.
This slides a texture smoothly, along the horizontal U-axis, and loops it when it gets to the end.  Note - the texture's rotation for each side affects the apparent motion.  So if the texture is rotated 90 degrees by use of the edit box, the texture may not flow in the direction expected.
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1, 1, 1);</lsl>
<source lang="lsl2">llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1.0, 1.0, 1.0);</source>


This slides a texture smoothly in the opposite direction
This slides a texture smoothly, along the horizontal U-axis, in the opposite direction
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1, 1, -1);</lsl>
<source lang="lsl2">llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1.0, 1.0, -1.0);</source>


This divides a texture into 64 "cells", 8 across, and 8 down, and flips through them, left to right, top to bottom. This is useful for cell animation.
This divides a texture into 64 "cells", 8 across, and 8 down, and flips through them, left to right, top to bottom. This is useful for cell animation.
<lsl>llSetTextureAnim( ANIM_ON | LOOP, ALL_SIDES, 8, 8, 0, 64, 6.4 );</lsl>
<source lang="lsl2">llSetTextureAnim( ANIM_ON | LOOP, ALL_SIDES, 8, 8, 0.0, 64.0, 6.4 );</source>


This rotates a texture counter-clockwise at 2 revolutions per second. Change the last value to -2*TWO_PI to rotate clockwise.
This rotates a texture counter-clockwise at 2 revolutions per second. Change the last value to -2*TWO_PI to rotate clockwise.
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | ROTATE | LOOP, ALL_SIDES,1,1,0, TWO_PI, 2*TWO_PI);</lsl>
<source lang="lsl2">llSetTextureAnim(ANIM_ON | SMOOTH | ROTATE | LOOP, ALL_SIDES,1,1,0, TWO_PI, 2*TWO_PI);</source>


This scales a texture larger and smaller.
This scales a texture larger and smaller.
<lsl>llSetTextureAnim(ANIM_ON | SMOOTH | SCALE | PING_PONG | LOOP, ALL_SIDES, 1, 1, 1, 3, 2);</lsl>
<source lang="lsl2">llSetTextureAnim(ANIM_ON | SMOOTH | SCALE | PING_PONG | LOOP, ALL_SIDES, 1, 1, 1.0, 3.0, 2.0);</source>


This turns off all texture animations
This turns off all texture animations
<lsl>llSetTextureAnim(FALSE, ALL_SIDES, 0, 0, 0.0, 0.0, 1.0);</lsl>
<source lang="lsl2">llSetTextureAnim(FALSE, ALL_SIDES, 0, 0, 0.0, 0.0, 1.0);</source>


This toggles a looping animation to make it stop at a specific frame.
This toggles a looping animation to make it stop at a specific frame.
<lsl>integer ON;
<source lang="lsl2">
integer textureIsBeingAnimated;
 
default
default
{
{
     touch_start(integer num)
     touch_start(integer num_detected)
     {
     {
          if (ON)
        if (textureIsBeingAnimated)
          {
            llSetTextureAnim(ANIM_ON | LOOP, ALL_SIDES, 1, 5, 0.0, 0.0, 1.0);
              llSetTextureAnim(ANIM_ON | LOOP, ALL_SIDES, 1, 5, 0, 0, 1);
        else
          }
            llSetTextureAnim(ANIM_ON | SMOOTH, ALL_SIDES, 1, 5, 5.0, 1.0, 1.0);
          else
 
          {
        // toggle back and forth between TRUE (1) and FALSE (0)
              llSetTextureAnim(ANIM_ON | SMOOTH, ALL_SIDES, 1, 5, 5, 1, 1);
        textureIsBeingAnimated = !textureIsBeingAnimated;
          }
    }
          ON = !ON;
}
      }
</source>
}</lsl>


|helpers
|helpers
|also_functions
|also_functions={{LSL DefineRow||[[llSetLinkTextureAnim]]}}
|also_events
|also_events
|also_articles
|also_articles
|notes=
|notes=
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 {{Jira|VWR-640}}, it got it's own issue in [[#SVC-3925|SVC-3925]]
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 is lost when using the rezzed in world copy method of shift-drag. Originally brought up in {{Jira|VWR-640}}, it got its own issue in [[#SVC-3925|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.)
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 August 27, 2010.)
|cat1=Media
|cat1=Media
|cat2=Effects
|cat2=Effects
Line 108: Line 115:
|cat5
|cat5
|cat6
|cat6
|history={{LSL Added|0.4.0|remote=http://secondlife.wikia.com/wiki/Version_0.4.0#Scripting}}
}}
}}

Revision as of 13:11, 22 January 2015

Summary

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

Animate the texture on the specified face/faces by setting the texture scale and offset.

• 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.[1]

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. llSetTextureAnim 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 across each row but will "jump" from one row to the next, if off, each frame is displayed in turn centered on the face.

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 llSetTextureAnim more than once on a prim will reset the existing animation.
    • Calling llSetTextureAnim 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
  • llSetTextureAnim, 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. Note - the texture's rotation for each side affects the apparent motion. So if the texture is rotated 90 degrees by use of the edit box, the texture may not flow in the direction expected.

llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1.0, 1.0, 1.0);

This slides a texture smoothly, along the horizontal U-axis, in the opposite direction

llSetTextureAnim(ANIM_ON | SMOOTH | LOOP , ALL_SIDES, 1, 1, 1.0, 1.0, -1.0);

This divides a texture into 64 "cells", 8 across, and 8 down, and flips through them, left to right, top to bottom. This is useful for cell animation.

llSetTextureAnim( ANIM_ON | LOOP, ALL_SIDES, 8, 8, 0.0, 64.0, 6.4 );

This rotates a texture counter-clockwise at 2 revolutions per second. Change the last value to -2*TWO_PI to rotate clockwise.

llSetTextureAnim(ANIM_ON | SMOOTH | ROTATE | LOOP, ALL_SIDES,1,1,0, TWO_PI, 2*TWO_PI);

This scales a texture larger and smaller.

llSetTextureAnim(ANIM_ON | SMOOTH | SCALE | PING_PONG | LOOP, ALL_SIDES, 1, 1, 1.0, 3.0, 2.0);

This turns off all texture animations

llSetTextureAnim(FALSE, ALL_SIDES, 0, 0, 0.0, 0.0, 1.0);

This toggles a looping animation to make it stop at a specific frame.

integer textureIsBeingAnimated;

default
{
    touch_start(integer num_detected)
    {
        if (textureIsBeingAnimated)
            llSetTextureAnim(ANIM_ON | LOOP, ALL_SIDES, 1, 5, 0.0, 0.0, 1.0);
        else
            llSetTextureAnim(ANIM_ON | SMOOTH, ALL_SIDES, 1, 5, 5.0, 1.0, 1.0);

        // toggle back and forth between TRUE (1) and FALSE (0)
        textureIsBeingAnimated = !textureIsBeingAnimated;
    }
}

Notes

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 is 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 August 27, 2010.)

See Also

Functions

•  llSetLinkTextureAnim

Articles

•  Negative Index

Deep Notes

History

All Issues

~ Search JIRA for related Issues
   llSetSyncTime() - a function for synchronising client side effects
   Some persistent prim properties lost when duplicated
   Texture Animation is not copied (llSetTextureAnim)
   Texture animations ignore repeats per face

Footnotes

  1. ^ Though if rate is negative and the REVERSE flag is used, they cancel each other out.
  2. ^ Early release notes were not very accurate or thorough, they sometimes included information about features added in previous releases or failed to include information about features added in that release.

Signature

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