llSetSculptAnim

From Second Life Wiki
Jump to navigation Jump to search
Emblem-important-yellow.png LSL Feature Request
The described function does not exist. This article is a feature request.

Summary

Function: llSetSculptAnim( integer mode, integer sizex, integer sizey, integer start_frame, integer end_frame, float rate, boolean texture_sync );
REQUEST Function ID
0.0 Forced Delay
20.0 Energy

'Animate' a sculpted prim by way of segments of a larger sculpt map. (Rather than by using UUID-swapping via llSetPrimitiveParams)

• integer mode mask of Mode flags
• integer sizex horizontal frames
• integer sizey vertical frames
• integer start_frame first frame in animation cycle
• integer end_frame last frame in animation cycle
• float rate frames per second (must be non-zero)
• boolean texture_sync syncs texture animation with the sculpt's (TRUE or FALSE)

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

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. llSetSculptAnim will animate across these 6 starting with the top left image and going across and down, optionally repeating and/or retracing, using each frame in turn as a sculpt map.

Collisions

Unlike with UUID-swapping, the physics engine is required only once to calculate the collision area for the sculpt map being utilized. The resultant collision area is defined by the maximum ranges defined anywhere within the source sculpt map.

Lag / Load

The nature of this function drastically reduces server-side lag/load by making the sculpted animation a client-side function similar to llSetTextureAnim.

texture_sync

If this is set to TRUE, the texture applied to the prim is divided (as with llSetTextureAnim) and cycled in synchronization with the sculpt map - ie; frame 5 of the texture is active at the same time as frame 5 of the sculpt map. If this is set to FALSE, the texture applied to the prim functions normally; reverting to normal parameters if previously set to TRUE.

Other Characteristics

llSetSculptAnim affects only the sculpt map definition of the applicable prim. It does not affect sizing, positioning, rotation, mirroring, inside-out, etc.

Modes Description
ANIM_ON 0x01 Sculpted animation is on. This must be set to start the animation, cleared to stop it.
LOOP 0x02 Loop the sculpted animation.
REVERSE 0x04 Play animation in reverse direction.
PING_PONG 0x08 Play animation going forwards, then backwards.

Caveats

  • You can only have one sculpt animation on a prim.
  • While sizex & sizey both have a range of 0 to 255, the source sculpt map is limited to a maximum size of 512x512.[2]
  • As sculpted prims are subject to 'vertex vomit', llSetSculptAnim lacks most of the options available with llSetTextureAnim - including SMOOTH, ROTATE, and SCALE, as well as only having one 'face'.
All Issues ~ Search JIRA for related Bugs

Examples

This would divide a texture into 6 "maps", 2 across and 3 down, and animate a sculpted prim through all six frames in one second, then loop to the beginning and continue. This is useful for repeating animations.

llSetSculptAnim(ANIM_ON | LOOP, 2, 3, 0, 5, 6.0, FALSE);


This would do as above but would similarly portion the prim's texture (as llSetTextureAnim), synchronizing the two functions.

llSetSculptAnim(ANIM_ON | LOOP, 2, 3, 0, 5, 6.0, TRUE);


This would do as above but only use the last and first frames, cycling between them and ignoring the other four frames.

llSetSculptAnim(ANIM_ON | LOOP, 2, 3, 5, 0, 2.0, TRUE);


This would stop the first animation above, using the fourth frame (first frame of the second row) as a 'normal' sculpt map. Due to the nature of sculpted prims, sizex, sizey, and start_frame MUST be specified when stopping the animation.

llSetSculptAnim(FALSE, 2, 3, 3, 5, 1.0, TRUE);


This would divide a texture into 24 "maps", 8 across and 3 down, and animate a sculpted prim only through the eight frames of the third row in one second, then loop to the beginning and continue.

llSetSculptAnim(ANIM_ON | LOOP , 8, 3, 16, 23, 8.0, FALSE);
Two other prims could use frames 0-7 and 8-15, respectively. This is useful for using a common texture to animate multiple sculpted prims.

Notes

llSetLinkSculptAnim: This variant (with the addition of a link parameter) would permit the root prim of a linked object to control the same functions of individual child prims without necessitating additional scripts.

With so much emphasis being placed upon the implementation of meshes and rigging this may be a moot proposal, but remains relevant nonetheless. It should be much simpler to incorporate into the existing SL world, as well as providing a (hopefully) simpler alternative for builds/projects which do not require the more complex physics of meshes.

Deep Notes

Search JIRA for related Issues

Footnotes

  1. ^ Though if rate is negative and the REVERSE flag is used, they cancel each other out.
  2. ^ This reduction vs the normal image limit of 1024x1024 is to help compensate for the additional filesize resulting from lossless compression. This effectively limits sculpted prims to a maximum of 64 'frames'. Anything more complex than this requires meshes.

Signature

//function void llSetSculptAnim( integer mode, integer sizex, integer sizey, integer start_frame, integer end_frame, float rate, boolean texture_sync );