Second Life Wiki - User contributions [en]

User:Becky Pippen/Memory Limits FAQ

2011-09-02T18:11:53Z

Becky Pippen: This page will go away. If anyone want to take ownership of it, go ahead!

I won't be updating this page any more. If anyone would like to take ownership of it and maintain it, please do so. Otherwise this page will disappear soon. -- Becky

== FAQ - Script Memory Limits ==

For the most official announcement so far, see [https://blogs.secondlife.com/community/land/blog/2010/03/19/the-first-step-toward-script-limits here].

'''Q:''' Why do we need script memory limits?
: '''A:''' In some regions, the simulator uses so much script memory that it has to swap virtual memory to disk. That causes major lag, and lag is among the top complaints about Second Life.

'''Q:''' How can I tell if I'm a heavy script user?
: '''A:''' Starting with server version 1.38 and viewer version 2.0, we can now see our individual script memory usage, similar to how estate managers can see top scripts in a region. Also scripters can use the function [[LlGetFreeMemory|llGetFreeMemory()]] to get an approximate idea of memory usage.

'''Q:''' Will this break content?
: '''A:''' Yes, some. The limits are specifically designed to limit the worst 5% of memory consumers so that the remaining 95% can continue to run freely without causing the simulator to swap virtual memory.

'''Q:''' When will all this happen?
: '''A:''' Script memory reporting and the new memory-efficient LSL functions are now available on the main grid using server version 1.38 and version 2.0 of the SL viewer. Server version 1.40 or later will have "Small Scripts" capability (see below). Memory limits will not be enforced until later in 2010 after these features have been deployed on the main grid for some time.

'''Q:''' Will the limits be per avatar or per region?
: '''A:''' There will be limits on avatar, parcel, and region in a way that parallels [[LSL_http_server#Resource_Limitations|how URL resources are managed]].

'''Q:''' Will Linden Lab pay for all the scripted products we bought that will no longer work?
: '''A:''' Most products are reasonably scripted and will continue to work just fine. The only problematic products will be unusual ones that are scripted in ways that use unreasonable amounts of RAM. Try to get the product creator to make a new version that uses less memory.

'''Q:''' Will we see a reduction in lag across the grid?
: '''A:''' It won't have a major impact on most regions. However, it will make a huge improvement on the 5% of the regions that use so much script memory that the server has to swap virtual memory to disk. It is also expected to improve performance on any other simulators running on the same server host using the same disk resources.

'''Q:''' How much RAM are we talking about?
: '''A:''' In the 95% of the regions that run smoothly, the simulator uses less than 800MB of RAM for everything except scripts, and up to 300MB for all the scripts in the region, and that's ok. In the worst 5% of the regions, simulators use up to 2GB of RAM on the server, and that's not ok.

'''Q:''' Why not just add RAM to the servers? RAM is cheap.
: '''A:''' Several thousand Xeon server boards at, say, US$100 each to upgrade, comes out to a bunch of money, even for Linden Lab. Moving forward, new simulators (class 7) will have more RAM.

'''Q:''' Who will be affected?
: '''A:''' All scripts, old and new, will be subject to the new memory limits. When planning for the memory limits, [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2009_11_25 Babbage Linden said], "[2009/11/25 3:43] Babbage Linden: ideally we'd like to have 95+% of people use scripts as they currently do while still having 95+% of simulators running without swapping".

'''Q:''' What's the difference between "Small Scripts Project," "Big Scripts Project," and "Efficient Scripts Project?"
: '''A:''' The ''Efficient Scripts Project'' is the overall effort to reduce the memory consumption of Mono-based scripts, including limits on memory usage. The ''Small Scripts Project'' and ''Big Scripts Project'' both refer to a refinement where each script can request the specific amount of memory it anticipates using instead of being charged with a constant 16KB for LSL or 64KB for Mono scripts. So, for example, a simple Mono sit script might request only 3KB while another data-intensive Mono script might request several megabytes. Since the average Mono script in SL needs only about 9KB, this could help reduce overall script memory usage in a typical region. In [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2010_03_03 Office Hours], Babbage Linden said, "I would like to ship script usage, then small scripts, then script limits, then big scripts... so it would be nice to have mono scripts be able to reserve a lower memory amount before script limits enforcement happens."

'''Q:''' What's the "LSL Penalty?"
: '''A:''' At one time, LL considered charging LSL scripts with more memory than they actually consume as an incentive for scripters to use Mono. That idea has been dropped, and the current plan is to charge all scripts with the actual memory they reserve — currently 16KB for LSL, and 64KB for Mono scripts. In the future after the Small Scripts and Big Scripts Project have been implemented, Mono scripts can be charged for only the amount of memory they reserve, which could be more or less than 64KB. Discussion of this can be found in the [http://lists.secondlife.com/pipermail/opensource-dev/ opensource-dev] mailing list.

'''Q:''' What can I do as a content creator to prepare?
: '''A:''' Be kind to your customers and give them product updates using the [[User:Becky_Pippen/New_LSL_Functions| new efficient LSL functions]]. Learn more about how to [[User:Becky_Pippen/Measure_Script_Memory_Usage|measure memory usage]] and the [[User:Becky_Pippen/Script_Memory_Limits|scripting techniques for reducing memory]].

'''Q:''' What can I do as a customer?
: '''A:''' 95% of scripts are just fine and you don't need to do anything. If you are wearing hair, shoes, or other attachments with a script in every prim, then you can contact the creator and ask if there is a product update that uses the new LSL memory-efficient functions.

User:Becky Pippen

2011-09-02T18:06:39Z

Becky Pippen: Remove link to page of obsolete script timing measurements.

User:Becky Pippen/LSL Performance

2011-09-02T18:04:34Z

Becky Pippen: These old timing measurements are obsolete and this page will disappear soon.

With the move to virtualized class 7 servers and changes to the Mono virtual machine, these performance
measurements made on old class 5 servers are no long very meaningful. Certainly the absolute timings are different now,
and probably the relative timings are different too. The generated CIL code shown below might still be the same
(I haven't checked), but that's about all that's left in this page that's relevant. So, this page is
obsolete and will disappear soon.

==LSL Timings and Rates==
Here are some selected LSL function times and event rates comparing scripts compiled and run using the old LSL toolset (a.k.a LSO), and using Mono.

The basic test framework for these tests is a loop like shown below, where we take the difference in llGetTime() before and after the loop:

while (--i >= 0) {
f(); f(); f(); f(); f(); f(); f(); f();
f(); f(); f(); f(); f(); f(); f(); f();
}

The loop is partially unrolled to make the loop control structure overhead negligible. We take several measurements in multiple Class 5 sims that are running consistently with a total frame time under 10 ms, where each test runs for 30 - 120 minutes, or longer if we fall asleep during the test. We measure several times during a 24-hour period until the numbers converge with a variance of 10% or less.

Measurements are taken in at least three regions, because we've occasionally seen regions with lots of reported spare time per frame, yet scripts seem to run inexplicably slow. If two out of three regions converge and agree, the anomalous region is ignored. Consider the numbers reported on this page to be maximums possible in cooperative regions.

In a Mono test, the result of the first run after script reset is ignored to eliminate the overhead of the VM initialization, JIT compilation, etc.

The Mono CIL shown for some of the LSL code below was obtained by modifying an SL viewer so that it calls lscript_compile() when saving a script. (Scripts are compiled on the simulators nowadays, but Linden Lab has kindly left the script compiler code in the open source viewer source code.) Comments and formatting were added manually.

Note that these are stopwatch times. How rapidly you can call a function or how often an event handler is invoked doesn't necessarily correspond to how much those functions and events lag a sim because of all the throttling and scheduling going on behind the scenes inside the run-time engine.

Class 7 hosts are starting to appear on the main grid as reported [[Beta_Server_Office_Hours/Minutes/2010-02-04|here]] and [[User:Andrew_Linden/Office_Hours/2010_02_02|here]]. As Linden Lab moves toward classless regions, absolute timings like shown on this page will become less meaningful. Maybe we can make use of some sort of relative performance measurements in the future.

== Functions, operators, & control structures ==

===Floating point assignment===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|x = [[PI]];
where x is a global [[float]]
{{!}}-
{{!}}align="center"|LSL: '''0.11''' ms/call
{{!}}align="center"|*Mono: '''0.0007''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
.field public float32 'x' // float x;
. . .
ldarg.0 // push 'this' pointer
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
stfld float32 LSL_script::'x' // pop and store 32-bit x
ldarg.0
ldfld float32 LSL_script::'x'
pop</code>
{{!}}}
:Notes: Verified and updated for server version 1.34.2.142087.

===Call to empty f() { }===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|f();
where f() is defined as f() { }
{{!}}-
{{!}}align="center"|LSL: '''0.33''' ms/call
{{!}}align="center"|*Mono: '''0.0026''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
Function definition:
:<code style="font-size:90%">
.method public hidebysig instance default void 'gf'() cil managed
{
.maxstack 500
ret
}</code>
Caller:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
call instance void class LSL_script::'gf'()</code>
{{!}}}

===[[for]] loop overhead===
:This test measures the overhead of a [[for]] loop that iterates an empty block just once.
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[for]] (i = 0; i == 0; ++i) { }
{{!}}-
{{!}}align="center"|LSL: '''0.07''' ms/loop
{{!}}align="center"|*Mono: '''0.001''' ms/loop
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
// loop init: i = 0
ldc.i4.0 // push 32-bit 0
stloc.s 0 // pop and store in i
ldc.i4 0 // push 32-bit 0
dup // duplicate 0 on the stack
stloc.s 0 // pop and store 0 in i
pop // cleanup

LabelTempJump0:
// top of loop: test i == 0
ldc.i4 0 // push 32-bit 0
ldloc.s 0 // push i
ceq // compare i and 0
brfalse LabelTempJump1 // branch if i != 0

// bottom of loop: ++i
ldloc.s 0 // push i
ldc.i4.1 // push 32-bit 1
add // pop i and 1, add, push result
dup // duplicate result
stloc.s 0 // save result in i
pop // cleanup
br LabelTempJump0

LabelTempJump1:
ret
</code>
{{!}}}

===[[State]] change===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[state]] a;
{{!}}-
{{!}}align="center"|LSL: '''0.14''' ms/transition
{{!}}align="center"|*Mono: '''22.2''' ms/transition
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldstr "state2"
call instance void class [LslUserScript] \
LindenLab.SecondLife.LslUserScript::ChangeState(string)
ret
</code>
{{!}}}
:Notes:
:State changes in Mono are tied to the sim frame rate of 45 fps (per Vektor Linden). The test code for state changes is an outer loop around 16 state changes like this:
<code>
:: . . .
:: state state''N'' { state_entry() { state state''N+1''; } }
:: state state''N+1'' { state_entry() { state state''N+2''; } }
:: . . . etc.
</code>

===[[Vector]] operations===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|v = <PI,[[PI]],PI> + <PI,PI,PI> * PI;
{{!}}-
{{!}}align="center"|LSL: '''0.43''' ms/statement
{{!}}align="center"|*Mono: '''0.025''' ms/statement
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI (vector x)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI (vector y)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI (vector z)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI multiplicand
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'CreateVector'(float32, float32, float32)
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'Multiply'(float32, class [ScriptTypes]LindenLab.SecondLife.Vector)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'CreateVector'(float32, float32, float32)
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'Add'(class [ScriptTypes]LindenLab.SecondLife.Vector, \
class [ScriptTypes]LindenLab.SecondLife.Vector)
// save result in v:
stfld class [ScriptTypes]LindenLab.SecondLife.Vector LSL_script::'v'
ldarg.0 // push 'this' pointer
ldfld class [ScriptTypes]LindenLab.SecondLife.Vector LSL_script::'v'
pop
</code>
{{!}}}

===[[llAbs]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llAbs]]();
{{!}}-
{{!}}align="center"|LSL: '''0.41''' ms/statement
{{!}}align="center"|*Mono: '''0.012''' ms/statement
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 0 // push the integer argument
call int32 class [LslLibrary]LindenLab.SecondLife.Library::'llAbs'(int32)
</code>
{{!}}}
:Notes: verified and updated for server ver. 1.34.2.142087

===[[Category:LSL_CSV|CSV]] [[string]] conversions===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llCSV2List]]([[llList2CSV]](x));
where x is a [[list]] of 10 [[integer]]s
{{!}}-
{{!}}align="center"|LSL: '''3.2''' ms/call
{{!}}align="center"|*Mono: '''4 - 7''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'x'
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llList2CSV'(class [mscorlib]System.Collections.ArrayList)
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] class \
[LslLibrary]LindenLab.SecondLife.Library::'llCSV2List'(string)
</code>
{{!}}}
:Notes: So far, the Mono results vary too much for any meaningful result.

===[[llDetectedName]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llDetectedName]]();
{{!}}-
{{!}}align="center"|LSL: '''1.1''' ms/call
{{!}}align="center"|*Mono: '''0.8''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 0 // push argument
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llDetectedName'(int32)
</code>
{{!}}}

===[[llGetInventoryName]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llGetInventoryName]](INVENTORY_TEXTURE, 0);
{{!}}-
{{!}}align="center"|LSL: '''0.52''' ms/call
{{!}}align="center"|*Mono: '''0.21''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 0 // push INVENTORY_TEXTURE
ldc.i4 0 // push 2nd argument
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llGetInventoryName'(int32, int32)</code>
{{!}}}

===[[llGetObjectDetails]]===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llGetObjectDetails]](k, [OBJECT_OWNER]);
{{!}}-
{{!}}align="center"|LSL: '''1.3''' ms/call
{{!}}align="center"|*Mono: '''1.7''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
// push k:
ldfld valuetype [ScriptTypes]LindenLab.SecondLife.Key LSL_script::'k'
ldc.i4 6 // push OBJECT_OWNER
box [mscorlib]System.Int32
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
CreateList()
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
Prepend(object, class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList])
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llGetObjectDetails'(valuetype \
[ScriptTypes]LindenLab.SecondLife.Key, \
class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList])
</code>
{{!}}}
:Notes: Verified and updated for server ver. 1.34.2.142087

===[[llGetPos]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llGetPos]]();
{{!}}-
{{!}}align="center"|LSL: '''0.39''' ms/call
{{!}}align="center"|*Mono: '''0.025''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llGetPos'()
</code>
{{!}}}
:Notes: Verified and updated for server ver. 1.34.2.142087

===[[llList2Vector]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llList2Vector]](x, 0);
where x = [ [[ZERO_VECTOR]] ]
{{!}}-
{{!}}align="center"|LSL: '''0.55''' ms/call
{{!}}align="center"|*Mono: '''0.012''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
// push list x:
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'x'
ldc.i4 0 // push 2nd argument: 0
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llList2Vector'(class \
[mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList], int32)
</code>
{{!}}}

===[[llMD5String]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llMD5String]](s,0);
where s is a 64-char [[string]]
{{!}}-
{{!}}align="center"|LSL: '''1.4''' ms/call
{{!}}align="center"|*Mono: '''1.4''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push string s
ldc.i4 0 // push 2nd arg: 0
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llMD5String'(string, int32)</code>
{{!}}}

===[[llMessageLinked]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=3 width=520|[[llMessageLinked]]([[LINK_THIS]], 0, "", [[NULL_KEY]]);
{{!}}-
{{!}}One consumer script:
{{!}}align="center"|LSL: '''1.5''' ms/call
{{!}}align="center"|*Mono: '''0.9''' ms/call
{{!}}-
{{!}}Two consumer scripts:
{{!}}align="center"|LSL: '''1.8''' ms/call
{{!}}align="center"|Mono: '''1.2''' ms/call
{{!}}-
{{!}}Four consumer scripts:
{{!}}align="center"|LSL: '''2.4''' ms/call
{{!}}align="center"|Mono: '''1.8''' ms/call
{{!}}-
{{!}}Eight consumer scripts:
{{!}}align="center"|LSL: '''4.4''' ms/call
{{!}}align="center"|Mono: '''3.3''' ms/call
{{!}}-
{{!}}16 consumer scripts:
{{!}}align="center"|LSL: '''9 - 20''' ms/call
{{!}}align="center"|Mono: '''7 - 15''' ms/call
{{!}}-
{{!}}32 consumer scripts:
{{!}}align="center"|LSL: '''22.2''' ms/call
{{!}}align="center"|Mono: '''22.2''' ms/call
{{!}}-
{{!}}colspan=3|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 -4 // push LINK_THIS
ldc.i4 0 // push 2nd arg: 0
ldstr "" // push 3rd arg: ""
ldstr "00000000-0000-0000-0000-000000000000" // push 4th arg as string
// convert that last string to a key type:
call valuetype [ScriptTypes]LindenLab.SecondLife.Key \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'CreateKey'(string)
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llMessageLinked'(int32, int32, string, valuetype \
[ScriptTypes]LindenLab.SecondLife.Key)
</code>
{{!}}}
:Notes: The time it takes to call llMessageLinked() is dependent on the number of consumers of the message, up to about 20-30 consumer scripts. At that point, the time to send a link message becomes constant at one call per 22.2 ms, which is suspiciously similar to the sim's basic frame rate.

===[[llParseString2List]]===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llParseString2List]](s,a,b);
where s is 2000 random digits, a=["0","1"]; b=["2","3"];
{{!}}-
{{!}}align="center"|LSL: '''45''' ms/call
{{!}}align="center"|*Mono: '''24''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push 1st arg: s
ldarg.0 // push 'this'
// push 2nd arg: list a:
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'a'
ldarg.0 // push 'this'
// push 3rd ard: list b:
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'b'
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llParseString2List'(string, \
class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList], \
class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList])
</code>
{{!}}}

===[[llSay]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSay]](-2, "0123456789");
{{!}}-
{{!}}align="center"|LSL: '''0.7''' ms/call
{{!}}align="center"|*Mono: '''0.2''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 2 // push 2...
neg // ...and negate it = -2
ldstr "0123456789" // push 2nd arg
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSay'(int32, string)</code>
{{!}}}
:Notes:
:#The performance of llSay(-2, "0123456789") varies widely by region, although it can be pretty consistent within a region. In some nearly empty regions, llSay() slows to no better than 5 ms/call for reasons unknown. It's as if the throttling for this function is less deterministic than other LSL functions. But even in the worst case, llSay() can transmit faster than llListen() can receive.
:#Verified and updated for server ver. 1.34.2.142087.

===[[llSetLinkAlpha]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSetLinkAlpha]](link, alpha, side);
{{!}}-
{{!}}align="center"|LSL: '''1.0''' ms/call
{{!}}align="center"|*Mono: '''0.52''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 1 // push 1st arg: link number
ldc.r8 (00 00 00 60 b8 1e d5 3f) // push 2nd arg: float alpha
ldc.i4 0 // push 3rd arg: side number
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSetLinkAlpha'(int32, float32, int32)
</code>
{{!}}}

===[[llSetText]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSetText]](s,c,a);
where [[string]] s is 20 chars
{{!}}-
{{!}}align="center"|LSL: '''0.79''' ms/call
{{!}}align="center"|*Mono: '''0.38''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push 1st arg: string s
ldarg.0 // push 'this'
// push 2nd arg: color:
ldfld class [ScriptTypes]LindenLab.SecondLife.Vector LSL_script::'c'
ldarg.0 // push 'this'
ldfld float32 LSL_script::'a' // push 3rd arg: a
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSetText'(string, \
class [ScriptTypes]LindenLab.SecondLife.Vector, float32)
</code>
{{!}}}

===[[llSubStringIndex]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSubStringIndex]](s, "X");
where s is 10000 digits not containing "X"
{{!}}-
{{!}}align="center"|LSL: '''16''' ms/call
{{!}}align="center"|*Mono: '''22''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push 1st arg: string a
ldstr "X" // push 2nd arg: literal string
call int32 class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSubStringIndex'(string, string)
</code>
{{!}}}

== Event handlers ==

===[[dataserver]]() for [[llGetNotecardLine]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[dataserver]]() events using [[llGetNotecardLine]]()
{{!}}-
{{!}}align="center"|LSL: '''6.4''' events/sec
{{!}}align="center"|Mono: '''6.4''' events/sec
{{!}}}

===[[link_message]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[link_message]]() events
{{!}}-
{{!}}align="center"|LSL: '''42-45''' events/sec
{{!}}align="center"|Mono: '''42-45''' events/sec
{{!}}}
:Notes: The results were highly variable over several tens of millions of link_message() events in three lightly loaded sims, but I wonder if the maximum rate is tied to the sim frame rate of 45 fps.

===[[listen]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=3 width=520|Maximum rate of [[listen]]() events
any number of scripts per prim, any number of prims in linkset
{{!}}-
{{!}}1 listener per script:
{{!}}align="center"|LSL: '''14.7''' events/sec
{{!}}align="center"|Mono: '''14.7''' events/sec
{{!}}-
{{!}}Two listeners per script:
{{!}}align="center"|LSL: '''11''' events/sec
{{!}}align="center"|Mono: '''11''' events/sec
{{!}}-
{{!}}Three listeners per script:
{{!}}align="center"|LSL: '''8.9''' events/sec
{{!}}align="center"|Mono: '''8.9''' events/sec
{{!}}}

===[[sensor]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[sensor]]() events
after [[llSensorRepeat]]()
{{!}}-
{{!}}align="center"|LSL: '''15''' events/sec
{{!}}align="center"|Mono: '''22''' events/sec
{{!}}}
:Notes: The maximum rate of sensor() events seems to be independent of the sensor radius or number of things detected.

===[[timer]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[timer]]() events
{{!}}-
{{!}}align="center"|LSL: '''22''' events/sec
{{!}}align="center"|Mono: '''22''' events/sec
{{!}}}
:Notes: About half the sim's basic frame rate of 45 fps.

===[[touch]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[touch]]() events
{{!}}-
{{!}}align="center"|LSL: '''22''' events/sec
{{!}}align="center"|Mono: '''22''' events/sec
{{!}}}
:Notes: About half the sim's basic frame rate of 45 fps.

User:Becky Pippen/Measure Script Memory Usage

2011-08-24T19:14:54Z

Becky Pippen: Add links to new LSL functions for measuring memory usage

News! We now have new LSL functions for measuring script memory usage, and
functions for setting lower memory limits. These were introduced in server
versions 11.06.17.233176
([[Release_Notes/Second_Life_Server/11#11.06.17.233176|release notes]])
and 11.08.10.238207
([[Release_Notes/Second_Life_Server/11#11.08.10.238207|release notes]]).

These new functions include:
* [[llScriptProfiler]] - For Mono, enables runtime memory profiling
* [[llGetSPMaxMemory]] - Maximum memory used during profiling
* [[llGetUsedMemory]] - For Mono or LSO, current script memory usage
* [[llSetMemoryLimit]] - For Mono only, sets a memory limit lower than the default 64KB
* [[llGetMemoryLimit]] - Returns the current maximum memory usage limit
* [[OBJECT_SCRIPT_MEMORY]] - Use with [[llGetObjectDetails]]() to get an object or agent's total memory limit

The old information about measuring memory usage with [[llGetFreeMemory]]() is shown below.

=== Measuring Script Memory Usage ===
Scripters can use [[llGetFreeMemory]]() to make more detailed measurements of how specific functions or
statements affect memory usage.
The memory a script uses is:
* Starting memory (65536 bytes for [[Mono]], 16384 for [[LSO|LSL]])
* minus program statements (e.g., a = 2;)
* minus static (pre-defined) variables (e.g., integer a;)
* minus dynamic (created when running) data and overhead (e.g., f("a" + "b") )
Here is an LSL statement that reports how much free memory you have at the moment it's called:

<lsl>llOwnerSay((string)llGetFreeMemory() + " bytes free");</lsl>

To report how much memory is used (instead of free) in a Mono script, subtract
free from total memory:

<lsl>llOwnerSay((string)(65536 - llGetFreeMemory()) + " bytes used");</lsl>

For LSL-compiled scripts, change 65536 to 16384.

It makes a difference where you place [[llGetFreeMemory]]() in your script. To see how
much memory is used by the script's program code and static (pre-defined) variables,
put [[llGetFreeMemory]]() as the first line in [[state_entry]]() or [[on_rez]]() in the default
state. To see how much memory your script used including all runtime dynamic data,
call [[llGetFreeMemory]]() as the last statement executed after your script has created
all the data it's going to.

To see how much memory is used by a one or a few program statements,
measure the memory before and after and take the difference. Be aware that your
instrumentation for measuring memory might itself consume some memory
if it uses variables or function calls, so do all that prior to the measurement.

Also be aware that the way the LSL and Mono back ends allocate memory (and
perhaps from fluctuations due to garbage collection), you might
get varying results from individual measurements, so it's sometimes useful to
take an average.

For example, suppose we want to measure how much memory gets consumed each time
your script saves a short string to a global list. Here is the statement that we want to
measure:

<lsl>aList += "hello"; // appends one 5-char string to the list</lsl>

To measure the memory used by this statement, we'll average the memory consumption over a hundred loops.
We'll also globally declare the temporary variables we'll need for the measurement
so that between the start and end of the test, there will be no extra variables allocated
or function calls made except the code being measured:

<lsl>
list aList;
integer startFreeMem;
integer endFreeMem;

default
{
touch_start(integer num)
{
integer loops = 100;
startFreeMem = llGetFreeMemory();

while (--loops >= 0) {
aList += "hello"; // appends one 5-char string to the list
}

endFreeMem = llGetFreeMemory();
llOwnerSay("Change in free mem: " + (string)(startFreeMem - endFreeMem));
}
}</lsl>

By the way, the results I got from this test shows that it takes 3486 bytes of memory to
append 100 copies of "hello" to a global list when compiled with LSL, and 752
bytes when compiled with Mono. These results are a little different than those given in
[[LSL_Script_Memory|this page]], and that's why it can
be illuminating to make these measurements in your own scripts. (In this example, the
[[LSL_Hacks|LSL assignment hack]] would help minimize memory consumption for the LSO case.)
===Caveats and geekystuffs===
There are several reasons why [[llGetFreeMemory]]() can give unexpected results:
* '''In Mono, memory may be allocated in blocks''' -- For example, a small change in the script might cause the free memory to change by 512 bytes. To get a better idea of the average memory used by a particular script construct, repeat it a number of times in the script and divide by the number of instances. For more information, see {{Jira|SVC-4387}}.
* '''[[llGetFreeMemory]]() reports the low-water mark before garbage collection''' -- For example, if you fill a list or string with thousands of bytes of data and then clear the list or string, [[llGetFreeMemory]]() will continue to report the lowest amount of memory that occurred and does not reflect the fact that a bunch of memory might be available if only the garbage collector would collect it. To reduce lag, the garbage collector typically frees up memory only when the script runs out of memory and more memory is needed. This is also illustrated in the code example at the end of this article. For more information, see the comments at:
** [[llGetFreeMemory]]()
** {{Jira|SVC-4387}}
** {{Jira|SVC-1852}}
* '''Memory fragmentation''' -- The order in which memory is allocated and freed can cause [[llGetFreeMemory]]() to act differently. In LSO, it might be reporting the largest single block of free memory instead of the total free bytes. It's not clear how fragmentation might affect [[llGetFreeMemory]]() in Mono. For more information, see the comments in:
** {{Jira|SVC-116}}
** {{Jira|SVC-168}}
* '''First run different than a reset''' -- In Mono, the amount of free memory reported by [[llGetFreeMemory]]() as the first line in [[state_entry]]() to be different on the first run after compiling compared to subsequent runs after a script reset.
* '''Mischievous spirits in Mono''' -- Even Mono experts describe Mono's memory management and garbage collection as squirrely and non-deterministic at best, so expect a few puzzling results in Mono.

===Code example===
If you find yourself making lots of measurements and comparisons, you might find a test scaffolding useful. Here is an example of some things you can do. To run your own tests, replace the lines below in touch_start() with your own tests, using the existing code as examples. Insert a call to mem() in between each test. The results in the chat log will be easy to read, and will also automatically log if the tests were run on Mono or LSO so you won't have to remember later.
<lsl> // Demo of a memory-usage reporter
//
// To use: call initMemReporter() in the start of the script, then
// call mem() at any time to report memory used and amount of change.
// This adjusts the numbers automatically depending on whether the
// script is compiled for Mono or classic LSO.
//
integer isMono; // set at runtime to TRUE if Mono VM, FALSE if LSO
integer totalMem; // set at runtime to 65536 or 16384
string vm; // set at runtime to "Mono" or "LSO"
integer lastUsedMem;

// Call this once at the start of the script, then call mem()
// at any time to report memory usage. This function caches a
// few variables so that they don't have to be recomputed in
// mem() every time.
//
initMemReporter()
{
// Test if we're running on LSO or Mono VM using
// the difference between the two reported in
// https://jira.secondlife.com/browse/SVC-3760

isMono = llToLower("Ü") != "Ü";

// Establish total memory:

if (isMono) {
totalMem = 65536;
vm = "(Mono)";
} else {
totalMem = 16384;
vm = "(LSO)";
}

lastUsedMem = totalMem - llGetFreeMemory();
}

// Report the memory used and the change from the last report
//
mem(string label)
{
integer freeMem = llGetFreeMemory();
integer usedMem = totalMem - freeMem;

llOwnerSay(
vm +
" used=" + (string)usedMem +
", free=" + (string)freeMem +
", change=" + (string)(lastUsedMem - usedMem) +
" \t" + label);

lastUsedMem = usedMem;
}

default
{
state_entry()
{
initMemReporter();
mem("initial conditions");
}

touch_start(integer num)
{
integer a;
float f;
list intList;
intList = [];
integer LOOPS = 1000;
integer i = LOOPS;
mem("Start of tests");

//************* Test 1
intList += [0];
mem("after adding the first element to a list");

//************* Test 2
while (--i >= 0) {
intList += 0;
}
mem("after filling a list with " + (string)LOOPS + " zeros");

//************* Test 3
intList = [];
mem("after clearing the previous list");

//************* Test 4
for (i = LOOPS; --i >= 0; ) {
intList += 0;
}
mem("after filling the list again with " + (string)LOOPS + " zeros");
}
} </lsl>
The results in Mono are:
<lsl> (Mono) used=6552, free=58984, change=-18 initial conditions
(Mono) used=6668, free=58868, change=-116 Start of tests
(Mono) used=6668, free=58868, change=0 after adding the first element to a list
(Mono) used=25938, free=39598, change=-19270 after filling a list with 1000 zeros
(Mono) used=26660, free=38876, change=-722 after clearing the previous list
(Mono) used=26660, free=38876, change=0 after filling the list again with 1000 zeros </lsl>

===Also see===
For ways to reduce memory usage in scripts, see [[User:Becky_Pippen/Script_Memory_Limits| this checklist of things you can do]].

User:Becky Pippen/CloudBeGone

2011-02-28T00:14:48Z

Becky Pippen: minor wordsmithing

==Cloud-Be-Gone! A geek's reference==

Tired of being a cloud? Already tried [[Clearing_the_cache|clearing cache and relogging]]?
Everyone has their own favorite
techniques of what to do after that, and here are my contributions.
Some combination of these solutions should work, but to know which solution(s)
to apply requires understanding the reasons why you're a cloud.

You're a cloud because your viewer hasn't yet received your avatar appearance data
from the region's simulator.
When you log in to SL, your viewer connects to the simulator that runs that region, and
the simulator is responsible for getting your avatar appearance data from the central servers,
then it sends that data to all the viewers that need it.
There are two main places where your appearance data might be stuck. Either:
<ol start="1">
<li>the simulator you're connected to hasn't yet received the data from the
[[Service_Disruptions|asset or inventory servers]], or else</li>
<li>the simulator has your appearance, but it got lost on its way to your viewer.</li>
</ol>

Here is how to tell which situation applies, and what to do:

===Stuck between asset/inventory servers and the simulator===
Your appearance might be stuck on the central servers for two possible reasons:
<ol start="1">
<li>the [[Service_Disruptions|asset or inventory servers or other central databases]] and/or Linden Lab's
internal networking services are temporarily overloaded, or</li>
<li>the simulator you're connected to is overburdened.</li>
</ol>

Sometimes you can check for these problems by looking at the Statistics Bar (ctrl-shift-1).
Expand the Simulator section and look at Sim FPS and Pending Downloads [[Improving_Region_Performance|(here's how)]]. If you see
Sim FPS under 45 very often, then the simulator is too busy to keep up with all its tasks in real time.
'''Solution:''' '''teleport to a different, lightly loaded region. Or relog directly into a lightly loaded region'''
[[Changing_your_login_location|(here's how to specify your login region)]].

If Sim FPS looks ok (at 45 most of the time), and especially if there are still Pending Downloads for
very long, then the simulator is running ok and the problem might be more in the asset or inventory servers or Linden's networking.
'''Solution:''' '''Use any technique to change your shape, skin, hair, and eyes to items from the Library part of your Inventory'''
[[How_do_I_get_a_default_avatar|(here's how)]]. You'll be a cloud if any of those four items have not yet been received by the viewer,
so replace them all.
There is a good chance that the simulator you're connected to already
has copies of all the Library items and can immediately
send their data to your viewer without having to wait on the central servers.
Then you can change shape and clothes later when the
servers aren't so busy.

If there are still pending downloads even in a lightly loaded region, then the asset or inventory servers
might just be busy temporarily. '''Solution:''' '''be patient, and relog again later.'''

===Lost on the way to the viewer===
If other people in the region can see your avatar but you can't, then the data may be getting lost on the way from the simulator
to your viewer. (Similarly, if you can see your appearance but others can't, it means your baked appearance got lost on the
way from your viewer to the simulator.)

Sometimes this problem appears in the Basic section of the Statistics Bar (ctrl-shift-1) as Packet Loss
[[How_do_I_check_for_packet_loss_%28network_lag%29|(more about that)]]. Anything over zero is data
lost on the way from the simulator to your viewer. Here are some ways this could happen
and some solutions:
<ol start="1">
<li>Data arriving too fast: '''Solution:''' '''Lower the Network Bandwidth in Preferences''' [[Troubleshooting_teleporting#Turn_Down_Maximum_Bandwidth|(here's how)]].</li>
<li>Sheer quantity of data: '''Solution:''' '''Reduce the amount of data that the simulator has to send to your viewer by reducing the Draw Distance in Preferences''' [[Draw_Distance|(here's how)]]''', then relog.'''</li>
<li>Avatar complexity: '''Solution:''' '''Reduce the amount of data and work the simulator has to do to log you on by removing attachments, especially scripted attachments''' [[How_to_detach_an_object_from_me|(here's how)]]''', then relog.</li>
<li>Laggy viewer: '''Solution:''' '''Reduce how hard your viewer has to work by adjusting the Draw Distance and graphics quality settings to minimum'''
[[Graphics_Preferences_Layout|(here's how)]]''', then relog to a region where there are very few objects in view.'''
This frees up CPU cycles on your own computer so your viewer can pay more attention to the data it receives from the simulator.</li>
<li>Marginal network connection: This could be a problem in your network card, cables, router,
or your ISP. You can test for this by logging in to Second Life on a different computer or in a different location,
use a wired connection instead of wireless, and have your ISP check out your internet connection.'''</li>
</ol>

===Don't give up===

Some combination of the solutions above should work! But if it
doesn't, here are some final things you can do:
<ol start="1">
<li>Enable the [[Advanced_menu|Advanced menu]] and choose [[Debug_Settings|Debug Settings]], enter <code>RenderUnloadedAvatar</code>, and set this to '''TRUE'''. This doesn't solve the problem, but it
replaces the default cloud with a default Ruth avatar while you're waiting for your real appearance to appear. And,</li>
<li>You can try submitting a trouble ticket to [http://secondlife.com/support/ the Support Staff].</li>
</ol>

Even more good resources:
* [[Why_do_I_look_like_a_particle_cloud|Why do I look like a particle cloud?]]
* [[User:Tourmaline_Falken/Character_Test_and_Clear_Cache_Instructions|Character Test and Clear Cache Instructions]]

And for fun:
* [[User:Becky_Pippen/RuthCloudScript|Ruth Cloud script]]

Good luck!

User:Becky Pippen

2011-02-14T01:22:34Z

Becky Pippen: Add links to new pages CloudBeGone and RuthCloudScript.

User:Becky Pippen

2011-02-14T01:18:27Z

Becky Pippen: remove a couple of obsolete links.

User:Becky Pippen/CloudBeGone

2011-02-14T01:16:56Z

Becky Pippen: Yet Another de-Ruthing guide

==Cloud-Be-Gone! A geek's reference==

Tired of being a cloud? Already tried [[Clearing_the_cache|clearing cache and relogging]]?
Everyone has their own favorite
techniques of what to do after that, and here are my contributions.
Some combination of these solutions should work, but to know which solution(s)
to apply requires understanding the reasons why you're a cloud.

You're a cloud because your viewer hasn't yet received your avatar appearance data
from the region's simulator.
When you log in to SL, your viewer connects to the simulator that runs that region, and
the simulator is responsible for getting your avatar appearance data from the central servers,
then it sends that data to all the viewers connected to the region.
There are two main places where your appearance data might be stuck. Either:
<ol start="1">
<li>the simulator you're connected to hasn't yet received the data from the
[[Service_Disruptions|asset or inventory servers]], or else</li>
<li>the simulator has your appearance, but it got lost on its way to your viewer.</li>
</ol>

Here is how to tell which situation applies, and what to do:

===Stuck between asset/inventory servers and the simulator===
Your appearance might be stuck on the central servers for two possible reasons:
<ol start="1">
<li>the [[Service_Disruptions|asset or inventory servers or other central databases]] and/or Linden Lab's
internal networking services are temporarily overloaded, or</li>
<li>the simulator you're connected to is overburdened.</li>
</ol>

Sometimes you can check for these problems by looking at the Statistics Bar (ctrl-shift-1).
Expand the Simulator section and look at Sim FPS and Pending Downloads [[Improving_Region_Performance|(here's how)]]. If you see
Sim FPS under 45 very often, then the simulator is too busy to keep up with all its tasks in real time.
'''Solution:''' '''teleport to a different, lightly loaded region. Or relog directly into a lightly loaded region'''
[[Changing_your_login_location|(here's how to specify your login region)]].

If Sim FPS looks ok (at 45 most of the time) but there are still Pending Downloads for
very long, then the simulator is running ok, and the problem might be more in the asset or inventory servers or Linden's networking.
'''Solution:''' '''Use any technique to change your shape, skin, ''and'' clothing to items from the Library part of your Inventory'''
[[How_do_I_get_a_default_avatar|(here's how)]].
There is a good chance that the simulator you're connected to already
has copies of all the Library items and can immediately
send their data to your viewer without having to wait on the central servers.
Then you can change shape and clothes later when the
servers aren't so busy.

If there are still pending downloads even in a lightly loaded region, then the asset or inventory servers
might just be busy temporarily. '''Solution:''' '''be patient, and relog again later.'''

===Lost on the way to the viewer===
If other people in the region can see your avatar but you can't, then the problem is definitely between the simulator
and your viewer. Also you can tell if this is the problem by looking at the Statistics Bar (ctrl-shift-1).
Expand the Basic section and watch the Packet Loss [[How_do_I_check_for_packet_loss_%28network_lag%29|(more about that)]]. Anything over zero is data
lost on the way from the simulator to your viewer. Here are some ways this could happen
and some solutions:
<ol start="1">
<li>Data arriving too fast: '''Solution:''' '''Lower the Network Bandwidth in Preferences''' [[Troubleshooting_teleporting#Turn_Down_Maximum_Bandwidth|(here's how)]].</li>
<li>Sheer quantity of data: '''Solution:''' '''Reduce the amount of data that the simulator has to send to your viewer by reducing the Draw Distance in Preferences''' [[Draw_Distance|(here's how)]]''', then relog.'''</li>
<li>Avatar complexity: '''Solution:''' '''Reduce the amount of data and work the simulator has to do to log you on by removing attachments, especially scripted attachments''' [[How_to_detach_an_object_from_me|(here's how)]]''', then relog.</li>
<li>Laggy viewer: '''Solution:''' '''Reduce how hard your viewer has to work by adjusting the Draw Distance and graphics quality settings to minimum'''
[[Graphics_Preferences_Layout|(here's how)]]''', then relog to a region where there are very few objects in view.'''
This frees up CPU cycles on your own computer so your viewer can pay more attention to the data it receives from the simulator.</li>
<li>Marginal network connection: This could be a problem in your network card, cables, router,
or your ISP. You can test for this by logging in to Second Life on a different computer or in a different location,
use a wired connection instead of wireless, and have your ISP check out your internet connection.'''</li>
</ol>

===Don't give up===

Some combination of the solutions above should work! But if it
doesn't, here are some final things you can do:
<ol start="1">
<li>Enable the [[Advanced_menu|Advanced menu]] and choose [[Debug_Settings|Debug Settings]], enter <code>RenderUnloadedAvatar</code>, and set this to '''TRUE'''. This doesn't solve the problem, but it
replaces the default cloud with a default Ruth avatar while you're waiting for your real appearance to appear. And,</li>
<li>You can try submitting a trouble ticket to [http://secondlife.com/support/ the Support Staff].</li>
</ol>

Even more good resources:
* [[Why_do_I_look_like_a_particle_cloud|Why do I look like a particle cloud?]]
* [[User:Tourmaline_Falken/Character_Test_and_Clear_Cache_Instructions|Character Test and Clear Cache Instructions]]

And for fun:
* [[User:Becky_Pippen/RuthCloudScript|Ruth Cloud script]]

Good luck!

User:Becky Pippen/RuthCloudScript

2011-02-14T01:09:37Z

Becky Pippen: Yet Another version of a Ruth Cloud LSL script.

==The Ruth Cloud==

Just for giggles, here are the secret parameter settings used to make a Ruth Cloud.
There was already a copy of a
[[Ruth#Cloud_texture_and_particle_parameters|Ruth Particle Cloud script on the wiki]],
but this version corrects one minor error
in one parameter, and adds a scaling factor that you can change to make the cloud larger or smaller than normal.
Just copy and paste this into a script and drop it into any prim to make a Ruth Cloud. Touch to turn
on and off. See the comments in the script for more information.

Are you tired of being a Ruth Cloud? See [[User:Becky_Pippen/CloudBeGone|this article]] for some suggestions.

<lsl> // This is the default Ruth cloud. The particle parameters were extracted from the viewer source file
// indra/slbrowser/newview/llvoavatar.cpp, in function void LLVOAvatar::idleUpdateLoadingEffect(),
// (near line 2856 in version 1.23.4). The original viewer source code comment is:
//
// // fancy particle cloud designed by Brent
//
// referring to Brent Linden. Thanks Brent, they're cute! Now... just make them go away, ok? :-)

// This script was concocted, formulated, and priminized by ❤ Becky Pippen ❤

// Set the scale of the Ruth cloud here. A scale of 1.0 makes a normal sized
// cloud; 0.5 makes one half as high and wide as normal; 2.0 makes one twice as
// wide and high as normal. The maximum scale is 4.0, because that makes the
// particles the maximum size allowed by the SL particle system.
//
float Scale = 4.0; // must be in the range (0.0..4.0]

integer ItIsCloudy;
list RuthCloudUnscaledParameters;

default
{
on_rez(integer param)
{
if (Scale <= 0.0 || Scale > 4.0) {
llSay(0, "Oops! Please edit this script and change the variable named\n" +
"Scale to a number above 0.0, and no greater than 4.0.");
} else {
if (llGetPos() == llGetLocalPos()) {
// We're in a single prim, or root prim, and not in an attachment,
// so adjust our height a little based on the scale of the Ruth Cloud
// so that the cloud won't be half underground: (Comment out this
// line if you don't want that):

llSetPos(llGetPos() + <0.0, 0.0, Scale / 2.0>);
}
}
}

state_entry()
{
integer flags = PSYS_PART_INTERP_COLOR_MASK |
PSYS_PART_INTERP_SCALE_MASK |
PSYS_PART_EMISSIVE_MASK |
PSYS_PART_FOLLOW_SRC_MASK |
PSYS_PART_TARGET_POS_MASK;

RuthCloudUnscaledParameters = [
PSYS_PART_FLAGS, flags,
PSYS_PART_MAX_AGE, 4.0, // particle age (yes, 4, not 3)
PSYS_SRC_PATTERN, PSYS_SRC_PATTERN_ANGLE_CONE, // major mode
PSYS_PART_START_COLOR, <1.0, 1.0, 1.0>, // starting particle color
PSYS_PART_END_COLOR, <1.0, 1.0, 1.0>, // final color (<1,1,1>=white)
PSYS_PART_START_ALPHA, 0.5, // beginning alpha (1.0=opaque)
PSYS_PART_END_ALPHA, 0.0, // final alpha (0.0=clear)
PSYS_SRC_TEXTURE, "f525c30a-1bde-c858-a907-3d4df5e736a7", // cloud-particle.j2c
PSYS_SRC_BURST_RATE, 0.02, // burst interval
PSYS_SRC_BURST_PART_COUNT, 1, // particle count per burst
PSYS_SRC_BURST_RADIUS, 0.0, // burst radius
PSYS_SRC_MAX_AGE, 0.0, // overall duration
PSYS_SRC_ANGLE_BEGIN, 3.14159, // starting angle 180°
PSYS_SRC_ANGLE_END, 0.0 // ending angle
];
}

touch_start(integer num)
{
ItIsCloudy = !ItIsCloudy;

if (ItIsCloudy) {
llParticleSystem(RuthCloudUnscaledParameters + [
PSYS_SRC_BURST_SPEED_MAX, Scale,
PSYS_SRC_BURST_SPEED_MIN, Scale * 0.1,
PSYS_PART_START_SCALE, Scale * <0.8, 1.0, 0.0>,
PSYS_PART_END_SCALE, Scale * <0.02, 0.02, 0.0> ]);
} else {
llParticleSystem([]);
}
}
}</lsl>

User:Becky Pippen/Shared Media LSL Recipes

2010-05-03T18:48:24Z

Becky Pippen: tweaks

==How-to's with Media-on-a-Prim==



The examples here assume you're comfortable with LSL, and you just need a quick reference for the syntax of handling HTML and JavaScript in LSL for Shared Media scripting. All the examples on this page are ready to copy-n-paste and drop into a prim — no other setup needed. The key syntax in each example is highlighted. There's no error handling in these minimalist examples, so add plenty of your own.

===Display plain text — XyText replacement===
[[Image:MoaP-example_1.png‎|thumb|Plain text]]
<tt>
default
{
state_entry()
{
<span style="background-color:#F8F8C8">integer face = 4;</span>
<span style="background-color:#F8F8C8">string message = "Hello World";</span>
<span style="background-color:#F8F8C8">llSetPrimMediaParams(face,</span>
<span style="background-color:#F8F8C8">[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message]);</span>
}
} </tt>

Comments:
* An avatar must press the Reload button on the browser to see this rendered in-world. A page will be auto-loaded if you include the parameter <tt>PRIM_MEDIA_AUTO_PLAY, TRUE</tt>, and if the avatar has auto-load enabled in preferences.
* There's no need to add any %-hex-escaping or to use [[llEscapeURL]](); llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, url]) will automatically escape the string for you.
* This works by feeding a data URI to the on-prim browser. Think of it as serving the contents of the page in the URL itself. For more information, see [[Shared_Media_and_data_URI|here]] and [http://en.wikipedia.org/wiki/Data_URI_scheme here].
* The in-world browser limits the data URI (or any address) to 1024 bytes after %-hex-escaping and encoded in UTF-8. See below for tricks using external or self-served JavaScript or CSS to leverage the data URI.
* If the data URI contains just plain text, the prefix <tt>"data:text/html,"</tt> can be abbreviated <tt>"data:,"</tt>.

===Force a page reload===
<tt>
[[Image:MoaP-example-refreshpage.gif|thumb|Auto-refresh]]
integer face = 4;
string myURL;
<span style="background-color:#F8F8C8">integer seq = 0; // sequence number for unique URLs</span>

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llSetPrimMediaParams(face,
[PRIM_MEDIA_AUTO_PLAY, TRUE,
PRIM_MEDIA_CURRENT_URL, myURL]);
llSetTimerEvent(5.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, "Sim FPS: " + (string)llGetRegionFPS());
}
}

timer()
{
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, myURL + "/?r=" + (string)(++seq)</span>]);
}
} </tt>
Comments:
* The page will reload automatically if <tt>PRIM_MEDIA_AUTO_PLAY</tt> is enabled and if the new <tt>PRIM_MEDIA_CURRENT_URL</tt> is different. This technique appends a short dummy parameter (like <tt>"/?r=12"</tt>) to the end of the URL to make it different each time, forcing a reload. The parameter is otherwise ignored.

===Display text with HTML markup===
[[Image:MoaP-example-markup.png‎‎|thumb|HTML markup]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = <span style="background-color:#F8F8C8">"<i>Hello</i><h2>World!</h2>"</span>;
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* The text of the data URI will be %-hex-escaped automatically for you, so there's no need to use [[llEscapeURL]](). All you need in the data URI is the prefix <tt>data:text/html,</tt> plus your HTML.

===Change window resolution===
[[Image:MoaP-example-size.png‎|thumb|Resized web window]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "Hello World";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message,
<span style="background-color:#F8F8C8">PRIM_MEDIA_WIDTH_PIXELS, 128</span>,
<span style="background-color:#F8F8C8">PRIM_MEDIA_HEIGHT_PIXELS, 32</span>]);
}
} </tt>

Comments:
* The browser will add scroll bars if the rendered HTML doesn't fit within the specified PRIM_MEDIA_* size.

===Display an image — works with animated GIFs too===
[[Image:MoaP-example-animgif.gif‎|thumb|Image on a prim]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://upload.wikimedia.org/wikipedia/commons/7/70/Rotating_earth_(small).gif";
<span style="background-color:#F8F8C8">string dataURI = "data:text/html,<object data='" + imageURL + "'></object>";</span>
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI,
PRIM_MEDIA_WIDTH_PIXELS, 256,
PRIM_MEDIA_HEIGHT_PIXELS, 256]);
}
} </tt>

Comments:
* If attempting to display YouTube video full-frame, see [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/16/viewer-2-tip-shared-media-show-youtube-on-a-full-prims-face this discussion].
* For images, you can also use <tt><image src= ></tt> like this:
string dataURI="data:text/html,<img src='" + imageURL + "'>";

===Display a background image, tiled===

====Method #1 — using CSS in a style element in <head>====
[[Image:MoaP-example-bgTiled.png‎|thumb|Tiled background image]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "data:text/html,<head>"
+ "<span style="background-color:#F8F8C8"><style type='text/css'>body{background-image:url(\"</span>"
+ <span style="background-color:#F8F8C8">imageURL + "\");}</style></span></head><body>Hello World</body>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #2 — using background attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body background='" + imageURL + "'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #3 — using style attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body style='background-image:url(\"" + imageURL + "\")'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

===Text colors — using <font> element===
[[Image:MoaP-example-font-color.png‎|thumb|Font color]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "<span style="background-color:#F8F8C8"><font color='Red'>Hello World</font></span>";
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* You can also specify color and other CSS rules in a style attribute in another element. For example, you can replace message in the example above with:

string message = "<h2 style='color:#FF0000'>Hello World</h2>";

===Link to external CSS file (forms example)===
[[Image:MoaP-example-externalCSS.png‎|thumb|External CSS file]]
<tt>
default
{
state_entry()
{
integer face = 4;
<span style="background-color:#F8F8C8">string externalCSS =</span>
<span style="background-color:#F8F8C8">"http://www.google.com/css/modules/buttons/g-button-chocobo.css";</span>

string dataURI = "data:text/html,<head><span style="background-color:#F8F8C8"><link href='</span>" +
<span style="background-color:#F8F8C8">externalCSS + "' rel='stylesheet' type='text/css' /></span></head>" +
"<form><input type='button' value='Click Me' class='g-button' /></form>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is one way to work around the 1024-byte limitation of data URIs. The external CSS can be as large as the browser permits. Also see the examples below for putting JavaScript in an external file.
* The tag <tt><head></tt> and the attribute <tt>type='text/css'</tt> may be omitted to make the data URI a few bytes shorter.

===Calling external JavaScript functions (JQuery example)===
[[Image:MoaP-example-JQuery.gif‎|thumb|Calling external JQuery]]
<tt>
integer face = 4;
string externalJavascript =
"http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js";
default
{
state_entry()
{
string dataURI = "data:text/html," +
"<head><span style="background-color:#F8F8C8"><script src='" + externalJavascript + "'></script></span></head>" +
"<button>Toggle</button>" +
"<p>Hello<br />World</p>" +
"<span style="background-color:#F8F8C8"><script>$('button').click(function () </span>" +
"<span style="background-color:#F8F8C8">{$('p').slideToggle('slow');});</script></span>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is a technique for working around the 1024-byte limit for data URIs. When you can't fit all the JavaScript you need into one data URI, just move some JavaScript functions into an external file and give the browser a data URI that references the external file with a URL. In this example above, the JavaScript for [http://jquery.com/ JQuery] lives in an external file on Google's servers. You just need enough bytes left over in the data URI to put a JavaScript function call with its parameters inside a <tt><script></tt> element.
* A data URI can be used as a springboard to generate arbitrary complex web pages by making use of these elements:
** a reference to external CSS with <tt><link href= </tt>,
** a reference to external JavaScript with <tt><script src=</tt>, and
** a function call with parameters to the external JavaScript using <tt><script>someFunction(args);</script></tt>. (In the JQuery example above, the name of the external function is <tt>"$"</tt>.)
* See the next two examples for variations of this same technique.

===Self-served HTML and JavaScript===
====Example #1 — using <script src= and .innerHTML= ====
[[Image:MoaP-example-refresh-clock.gif‎|thumb|Self-served auto-refreshed pages]]
<tt>
integer face = 4;
string myURL;

// This can be up to 2KBytes after %-hex-escaping:
<span style="background-color:#F8F8C8">string servedPage =</span> "
function checklength(i){if (i<10) {i='0'+i;} return i;}
<span style="background-color:#F8F8C8">function clock()</span>{
var now = new Date();
var hours = checklength(now.getHours());
var minutes = checklength(now.getMinutes());
var seconds = checklength(now.getSeconds());
var format = 1; //0=24 hour format, 1=12 hour format
var time;
if (format == 1) {
if (hours >= 12) {
if (hours ==12 ) { hours = 12;
} else { hours = hours-12; }
time=hours+':'+minutes+':'+seconds+' PM';
} else if(hours < 12) {
if (hours ==0) {hours=12;}
time=hours+':'+minutes+':'+seconds+' AM';
}
}
if (format == 0) {time= hours+':'+minutes+':'+seconds;}
<span style="background-color:#F8F8C8">document.getElementById('clock').innerHTML=time;</span>
setTimeout('clock();', 500);
} "; // yes, that's one long string.

displayPage()
{
string dataURI = "data:text/html,<span style="background-color:#F8F8C8"><script src='</span>" +
<span style="background-color:#F8F8C8">myURL + "'></script></span>" +
"<span style="background-color:#F8F8C8"><div id='clock'><script>clock();</script></div></span>";
llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);
}

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
<span style="background-color:#F8F8C8">myURL = body;</span>
displayPage();
} else if (method == "GET") {
<span style="background-color:#F8F8C8">llHTTPResponse(id, 200, servedPage);</span>
}
}
} </tt>

Comments:
* This is a technique for trading the 1024-byte limit of data URIs for the 2048-byte-per-page limit that the script can serve itself. As in the previous example, when you can't fit all the JavaScript into one data URI, just move the JavaScript into an external file and reference the file with <tt><script src=URL></script></tt>. When the URL refers to the script's own HTTP-in URL, then the page served can contain up to 2K bytes, so you get at least that many bytes plus whatever logic you can fit into the rest of the data URI. If you move that JavaScript to an external web server, the size of the external JavaScript file can be as large as the client web browser can render.
* Your script can serve an arbitrary number of different pages through one HTTP-in URL by appending a path or parameter to the URL.
* This works by assigning a string containing HTML to the <tt>.innerHTML</tt> contents of the <tt><div></tt> element with id "clock". This achieves something similar to the Ajax-like [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim technique published by Tali Rosca] and mentioned [http://wiki.secondlife.com/wiki/User:Kelly_Linden/lsl_hacks#DHTML_.2F_Javascript_.28Tali_Rosca.29 here]. In those techniques, a string is constructed containing an <tt><a href=</tt> tag and an <tt>href=</tt> that points to the script's HTTP-in URL. That string then replaces the <tt><body></tt> element using:
<tt>document.getElementsByTagName('body')[0].innerHTML = <i>new-content</i></tt>

====Example #2 — using <body onload= (lag graph example)====
[[Image:MoaP-example-laggraph.gif‎|thumb|Refreshed pages]]
<tt>
integer face = 4;
string jsURL; // where to fetch external JavaScript
list numbers;
integer numSamples = 50;

// This is self-served in this example, but can be
// moved to an external server:
//
string externalJavascript()
{
return
"function bar(widthPct,heightPix) {" +
" document.writeln(\"<hr style='padding:0;margin:0;" +
" margin-top:-1px;text-align:left;align:left;border=0;" +
" width:\"+widthPct+\"%;height:\"+heightPix+\"px;" +
" background-color:#c22;color:#c22;'>\");}" +
" function graphBars(arr){for(var i=0;i<arr.length;++i)" +
" {bar(arr[i],18);}}";
}

default
{
state_entry()
{
llClearPrimMedia(face);
llRequestURL();
integer i = numSamples;
while (--i >= 0) {
numbers += 0;
}
}

timer()
{
numbers = llList2List(numbers, 1, -1) + [(integer)(6.0 * (45.0 - llGetRegionFPS()))];

// The dataURI loads external JavaScript functions and calls one with parameters:

string dataURI = "data:text/html," +
"<span style="background-color:#F8F8C8"><head><script src='" + jsURL + "'></script></head></span>" +
"<span style="background-color:#F8F8C8"><body onload=\"graphBars([" + llList2CSV(numbers) + "]);\"></body></span>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI, PRIM_MEDIA_AUTO_PLAY, TRUE]);
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
jsURL = body; // self-serve the JavaScript
llSetTimerEvent(1.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, externalJavascript());
}
}
} </tt>

Comments:
* Like the previous example, this is another variation of how to structure a data URI to serve as a springboard for arbitrarily large pages. In this example, the data URI first uses a <tt><script src=...></tt> tag to read a file of external JavaScript functions in the <tt><head></tt> element, and then the <tt>onload=</tt> attribute in <tt><body></tt> triggers a call to one of the functions which executes a loop creating a bunch of <tt><hr></tt> elements that form the bar chart. The size of HTML generated by the JavaScript can be as large as the browser permits.
* In this example, <tt>jsURL</tt> is set to the script's own HTTP-in URL so that the example can be self-contained, but you can point <tt>jsURL</tt> to an external URL as well. If served by an external server, the JavaScript read in <tt><head></tt> can be as large as the browser permits.
* <tt><head></head></tt> can be omitted in the data URI surrounding the <tt><script src=</tt> tag.

===Reverse Ajax - Long-polling the HTTP-in server, chat logger example===
[[Image:MoaP-example-Long-polling-httpin.gif|thumb|300px|Long-polling HTTP-in]]
<tt>
// Reverse Ajax: Long-polling HTTP-in.
// Becky Pippen, 2010, contributed to the public domain.

integer face = 4; // Prim face for Shared Media

<span style="background-color:#F8F8C8">string myURL; // HTTP-in URL</span>
<span style="background-color:#F8F8C8">key inId = NULL_KEY; // GET request id</span>
<span style="background-color:#E0FDE0">list msgQueue = []; // strings of Javascript</span>

<span style="background-color:#F8F8C8">// url is our own HTTP-in url.
// This sets up a bootloader web page like this:
// <html><body>
// <div><script id='sc'></script></div>
// <script> callbacks and poll.beg() defined here </script>
// <button onclick=poll.beg()>Start</button>
// <div id='dv'></div>
// </body></html>
// When the button is pressed, the JS code sets src= on script#sc
// and reattaches the script element to the parent <div> element which
// initiates a GET to the prim's HTTP-in port
//
setDataURI(string url)
{
string dataURI = "data:text/html,
<!DOCTYPE HTML><html><body><div><script id='sc'></script></div><script>
var poll=function(){var sc=document.getElementById('sc'),t2,seq=0,s0;return{
beg:function(){s0=document.createElement('script');s0.onload=poll.end;t2=setTimeout('poll.end()',20000);
s0.src='" + url + "/?r='+(seq++);sc.parentNode.replaceChild(s0,sc);sc=s0;},
end:function(){clearTimeout(t2);t2=null;sc.onload=null;setTimeout('poll.beg()',500);},};}();</script>
<button id='btn'onclick=poll.beg()>Start</button><div id='dv'></div></body></html>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);</span>
}

<span style="background-color:#E0FDE0">// Returns zero or more queued messages. Assumes no single message is
// longer than MAX_SIZE_CHARS (will hang if there is)
//
string popQueuedMessages()
{
string totalMsg = "";
integer totalMsgSize = 0;
string nextMsg = "";
integer nextMsgSize = 0;

// HTTP response bodies are limited to 2048 bytes after encoding
// in UTF-8. LSL string sizes are measured in characters, which,
// in UTF-8, use one byte (for ASCII chars), two bytes (most Latin-1),
// or three bytes (a few international characters). So, unless
// you re-write this section so that it measures UTF-8 size, keep
// MAX_SIZE_CHARS small enough so the text will fit in a response body.
//
integer MAX_SIZE_CHARS = 1000; // Max HTTP body size

integer numMessagesQueued = llGetListLength(msgQueue);
integer count = 0;
integer done = FALSE;
while (!done && count < numMessagesQueued) {
nextMsg = llList2String(msgQueue, count);
nextMsgSize = llStringLength(nextMsg);

if (totalMsgSize + nextMsgSize < MAX_SIZE_CHARS) {
totalMsg += nextMsg;
totalMsgSize += nextMsgSize;
++count;
} else {
done = TRUE;
}
}

// Delete the messages from the queue that we're going to send:
if (count > 0) {
msgQueue = llDeleteSubList(msgQueue, 0, count - 1);</span>
}

return totalMsg;
}

<span style="background-color:#E0FDE0">// Called when there are previous messages still queued, or if there
// is no GET request currently open to respond to.</span>
//
pushMessageToSend(string msg)
{
<span style="background-color:#E0FDE0">msgQueue = msgQueue + [msg]; // last element is the last one stacked</span>

// See if we can send some messages now:
<span style="background-color:#F8F8C8">if (inId != NULL_KEY) {</span>
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, popQueuedMessages());</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} // else wait for the next incoming GET request
}

// Replaces all occurrences of 'from' with 'to' in 'src'
// From http://snipplr.com/view/13279/lslstrreplace/
//
string str_replace(string subject, string search, string replace)
{
return llDumpList2String(llParseStringKeepNulls(subject, [search], []), replace);
}

// Optionally filter out characters in text that would mess up the
// web page display. This demo just escapes ' and " and adds a space after '<'.
//
string addSlashes(string s)
{
return str_replace(str_replace(str_replace(s, "<", "< "), "\"", "\\\""), "'", "\\\'");
}

// This is the main interface for LSL to control the Shared Media web page.
// The messages we send consist of Javascript function statements that the
// browser will evaluate and execute in the context of the web page.
// See sendMessageF() for a similar function with macro replacement.
//
sendMessage(string msg)
{
// Test for the easy case: if there are no other messages waiting
// in the queue, and if there is an open GET connection, then just
// respond immediately:

<span style="background-color:#E0FDE0">if (llGetListLength(msgQueue) == 0</span> && <span style="background-color:#F8F8C8">inId != NULL_KEY) {</span>
// Nothing in the queue and an open GET, so respond immediately:
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, msg);</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} <span style="background-color:#E0FDE0">else {</span>
<span style="background-color:#E0FDE0">pushMessageToSend(msg);</span>
}
}

// Same as sendMessage() but with macro replacements. For each nth string
// element in replacements, replace all occurrences of {@n}. For example,
// sendMessageF( "alert('{@0} {@1}!')", ["Hello", "World"] );
// will send "alert('Hello World!')" to the web browser.
//
sendMessageF(string msg, list replacements)
{
integer numrepl = llGetListLength(replacements);
integer i;
for (i = 0; i < numrepl; ++i) {
msg = str_replace(msg, "{@" + (string)i + "}", llList2String(replacements, i));
}

<span style="background-color:#F8F8C8">sendMessage(msg);</span>
}

<span style="background-color:#E8E8FF">// Chat logger demo: writes a new <tr> table row to the web page
// for every line of open chat it hears.
//
webAppInit()
{
string msg;
string m0;

// First, send over a few handy function definitions:

msg = "function $$(t) { return document.getElementsByTagName(t)[0]; };";
msg += "function h() { return $$('head'); };";
msg += "function b() { return $$('body'); };";
msg += "function e(id) { return document.getElementById(id); };";
sendMessage(msg);

// Send some CSS. WebKit is sensitive about appending <style> elements
// to <head>, so we'll append it to an existing <div> tag in <body> instead.

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<style>td:nth-child(2) { text-align:right } tr:nth-child(odd) { background-color:#f8e8f8 }</style>";
sendMessageF(msg, [m0]);

// Write a <table> element into element div#dv. The lines of chat will
// become rows in this table appended to tbody#tbd

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<table><tbody id='tbd'></tbody></table>";
sendMessageF(msg, [m0]);

llListen(0, "", NULL_KEY, "");</span>
}

default
{
state_entry()
{
llClearPrimMedia(face);
<span style="background-color:#F8F8C8"> llRequestURL();</span>

<span style="background-color:#E8E8FF"> webAppInit();</span>
}

<span style="background-color:#F8F8C8"> http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llOwnerSay("myURL=" + myURL);
setDataURI(myURL);
} else if (method == "GET") {
// Either send some queued messages now with llHTTPResponse(),
// or if there's nothing to do now, save the GET id and
// wait for somebody to call sendMessage().</span>
<span style="background-color:#E0FDE0"> if (llGetListLength(msgQueue) > 0) {</span>
<span style="background-color:#F8F8C8"> llHTTPResponse(id, 200, popQueuedMessages());
inId = NULL_KEY;
} else {
inId = id;
}
}
}</span>

<span style="background-color:#E8E8FF"> // When we hear chat from name, send a Javascript statement that
// appends HTML to element #tbd. I.e., we'll make a string of HTML
// formatted like this:
// <tr style="color:hsl(200,100%,30%)">
// <td>[01:23]</td>
// <td>Avatar Name</td>
// <td>the chat text</td>
// </tr>
// and send it wrapped it in a Javascript statement like this:
// e('tbd').innerHTML += htmlstring;
//
listen(integer chan, string name, key id, string chat)
{
integer s = (integer)("0x" + llGetSubString((string)id, 0, 6));
string hue = (string)(s % 360);
string color = "hsl(" + hue + ",100%, 30%)";

string msg = "e('tbd').innerHTML += '{@0}';";
string m0 = "<tr style=\"color: {@4}\">";
m0 += "<td>{@1}</td>";
m0 += "<td>{@2}:</td>";
m0 += "<td>{@3}</td>";
m0 += "</tr>";

string t = llGetSubString(llGetTimestamp(), 11, 15);
sendMessageF(msg, [m0, "[" + t + "]", name, addSlashes(chat), color]);
}</span>
}
</tt>

Comments:
<ol start="1">
<li>This "[http://en.wikipedia.org/wiki/Push_technology server-push]" technique using long-polling gives an LSL script the ability to modify the web page displayed on a prim. The Javascript side always keeps an HTTP GET open to the prim's HTTP-in URL, and the LSL side responds whenever it wants to with a response consisting of strings of Javascript to be executed by the web browser. For example, this LSL code causes an alert box to pop up on the web page:
: <code>sendMessage( "alert()" );</code></li>
<li>In the LSL listing above, <span style="background-color:#F8F8C8">the yellow highlighting</span> shows the most important parts of the HTTP long-polling mechanism. The <span style="background-color:#E0FDE0">green highlighting</span> shows the message buffering on top of that. The <span style="background-color:#E8E8FF">blue highlighting</span> is the application code that uses long-polling. To use long-polling for a different application, replace the blue parts. The rest is glue.</li>
<li>To avoid some subtle WebKit problems when dynamically appending or replacing the first-level child nodes in <head> or <body>, we've made two special <div> elements on the bootstrap HTML page. The first surrounds the script#sc element that we replace for each GET. The second is at the end of <body> as a convenient place for the application to insert new content that would otherwise go in <body>.</li>
<li>To make sure that there is nearly always a valid GET request open, the Javascript side starts a new GET after receiving a response, or just before the last unanswered GET times out.</li>
<li>There are two timeouts hard-coded in the bootstrap data URI:
<ol style="list-style-type:lower-roman"><li>The "20000" is the timeout (20 seconds) for when an open GET expires, and should be set to a little less than the minimum of the WebKit outgoing GET request timeout, and the SL-LSL incoming GET timeout. This ensures that GETs are nearly continuous, and the LSL side can always respond to the most recent GET request. [[LlHTTPResponse|This page]] says the timeout on the LSL side is 25 seconds.</li>
<li>The "500" is a throttle that sets an upper limit to how fast the Javascript re-polls HTTP-in to prevent hammering the simulator. It's a half-second delay after receiving a GET response before starting a new GET.</li></ol>
<li> If there's a little gap between two GETs, or if two overlap a little, the sendMessage() message buffering will compensate by queuing up messages to be sent when the next GET arrives. If there are multiple messages in the queue when a GET arrives, the LSL side will concatenate as many messages as possible and send them together.
</li>
<li>On the Javascript side, the GET is not triggered until the <tt><script></tt> element is attached to its parent node with .appendChild() or .replaceChild().</li>
<li>The bootstrap Javascript above in setDataURI() had to be compressed somewhat to fit into the 1024-byte data URI limit. Here's an expanded listing for reference with more descriptive names:</li>
<tt>
<!DOCTYPE HTML>
<html>
<body>
<div>
<script id='script'> </script>
</div>
<script>
var poll=function(){
var script=document.getElementById('script'),
timeoutId,
seq=0,
newScript;
return {
beg:function() { // Initiate a long-poll GET
newScript=document.createElement('script'); // The response will go here
newScript.onload=poll.end; // Call poll.end() when we get a response
timeoutId=setTimeout('poll.end()',20000); // ... or if we time out
newScript.src=' HTTP-in URL goes here /?r='+(seq++);
script.parentNode.replaceChild(newScript,script); // this triggers the GET
script=newScript;},

end:function() {
clearTimeout(timeoutId);
timeoutId=null;
script.onload=null;
setTimeout('poll.beg()',500); // Wait a bit before re-polling
},
};
}();
</script>
<button id='btn'onclick=poll.beg()>Start<button>
<div id='dv'> </div>
</body>
</html>
</tt>
</ol>

===Make TinyURLs by script===
<tt>
string myTinyURL;

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
// Send our full URL to tinyurl.com for conversion
// The answer will come back in http_response()
<span style="background-color:#F8F8C8">llHTTPRequest("http://tinyurl.com/api-create.php?url=" + body, [], "");</span>
} else if (method == "GET") {
llHTTPResponse(id, 200, "Hello Real World from the Virtual World");
}
}

http_response(key req, integer stat, list met, string body)
{
<span style="background-color:#F8F8C8">myTinyURL = body;</span>
llOwnerSay("My HTTP-in TinyURL is: " + myTinyURL + " , Click Me!");
}
} </tt>

Comments:
* Any URL or data URI can be mapped to a TinyURL. The example above reduces an assigned HTTP-in URL, which is a long one such as:
<nowiki>http://sim4605.agni.lindenlab.com:12046/cap/2b9f06f7-431e-5b0f-9271-2d03bd15370b</nowiki>
into a TinyURL this size:
<nowiki>http://tinyurl.com/y9etul3</nowiki>

===Development hints===
# You can develop your HTML and JavaScript outside of Second Life by putting your JavaScript incantations in data URIs that you feed to any web browser. For the most compatible browsers, use Safari or Google Chrome, or any other that uses the [[QtWebKit|WebKit]] HTML rendering engine. If you can't run Safari or Chrome, try the open source [http://code.google.com/p/arora/ Arora web browser] for simulating Media-on-a-Prim: it's based on straight-up WebKit and has the same handy inspector/debugger found in other WebKit browsers.
# If you don't have direct access to a web server while developing this stuff, then consider installing a local copy of [http://www.apache.org/ Apache web server] on your computer. You can restrict it to local access. Then you can refer to files on your own computer with URLs that start with <tt><nowiki>http://localhost/</nowiki>...</tt>, and PHP scripts can simulate what the HTTP-in server would serve. That lets you, for example, edit <tt>myfile.js</tt> on your own computer while working on a data URI that contains <tt><script src="<nowiki>http://localhost/myfile.js</nowiki>"></tt>. Then when <tt>myfile.js</tt> is working, you can put the debugged code into an LSL script that will serve it through its HTTP-in port. That's easier than debugging all that in-world.

===References and sources===
* [[User:Kelly_Linden/lsl_hacks|Kelly Linden's hacks]]
* [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim Tali Rosca's techniques]
* [https://blogs.secondlife.com/message/115303 Notecard Text on a Prim - Demo]
* [[llSetPrimMediaParams]]()
* {{JIRA|SVC-3427}}
* [https://blogs.secondlife.com/message/124144 Ajax in Shared Media #1]
* [https://blogs.secondlife.com/thread/11698 Ajax in Shared Media #2]
* [https://blogs.secondlife.com/thread/12727 Ajax in Shared Media #3]
* [https://blogs.secondlife.com/thread/13455 SVG (Scalable Vector Graphics) in Shared Media]
* [[Shared_Media_and_data_URI|Shared_Media_and_data_URI]]
* [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/17/viewer-2-tip-shared-media-add-custom-content-with-data-uri-no-webpage-upload-needed Shared Media: Add custom content with data: URI]
* [https://blogs.secondlife.com/message/119704 "Shared Media" - A few facts]

[[Category:Shared Media]]

User:Becky Pippen/New LSL Functions

2010-04-27T18:08:15Z

Becky Pippen: tweak wording to show that server 1.38 is here.

== New LSL Functions ==

These memory-saving LSL functions are now available in server version 1.38::

<lsl> list llGetLinkPrimitiveParams(integer linknumber, list params)

llSetLinkPrimitiveParamsFast(integer link, list params)

llLinkParticleSystem(integer link, list rules)

llSetLinkTextureAnim(integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate)
</lsl>

We will also get [[PRIM_TEXT]] for getting and setting hover text with [[llSetLinkPrimitiveParams]]().
The parameter list will be:

<lsl> PRIM_TEXT, string msg, vector color, float alpha </lsl>

===The deal with resizer scripts===

Some content creators prefer to distribute their objects no-mod, yet still allow customers to resize or
retexture the linkset. Scripts can do that in a no-mod linkset, but the obvious solution using
[[llSetLinkPrimitiveParams]]() doesn't work well because of the 0.2-second delay built into the function.
To work around the delay, we have had to put a script in every child prim that can respond immediately
to a message from the root prim. When these functions become available, we will be able to do this kind of thing with a single script.

===Fixing existing scripts===

To fix such a script, locate the call to [[llMessageLinked]]() in the master script where it sends the link
message to the individual prims. It might look something vaguely like this:

<lsl>llMessageLinked(LINK_whatever, command_resize, (string)newSize, NULL_KEY);</lsl>

Replace that with a loop that applies whatever changes you need to each prim using
[[llSetLinkPrimitiveParamsFast]](). The prims have link numbers from 1 through [[llGetNumberOfPrims]](),
so you can make an efficient loop as shown here; just add any additional processing you
need for each prim inside the loop:

<lsl> applyChildParams(list ruleSet)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
llSetLinkPrimitiveParamsFast(linkNum, ruleSet);
}
} </lsl>

For example, to use this function to set the color and alpha of all the prims, build the parameter
list and pass it to applyChildParams() like this:

<lsl>applyChildParams([PRIM_COLOR, ALL_SIDES, <0.9, 0.8, 0.2>, 1.0]);</lsl>

However, when you only need to apply a constant rule set like this to every prim in the linkset,
then the loop above can be simplified to a single statement;

<lsl>llSetLinkPrimitiveParamsFast(LINK_SET, ruleSet);</lsl>

Or use [[LINK_ALL_OTHERS]] or [[LINK_ALL_CHILDREN]] instead of [[LINK_SET]] as appropriate.

For another example, you can make a resizer script apply relative instead of absolute size changes by
using the new function [[llGetLinkPrimitiveParams]](). The script can read each child's current size,
then apply a resize factor and use [[llSetLinkPrimitiveParamsFast]]() to set a new size. This can help
make it easy for the script to do the right thing even if reset and all its variables get reinitialized. The
following function will resize all the prims (including the root itself) by a factor:

<lsl> rescaleLinksetByFactor(float factor)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
llSetLinkPrimitiveParamsFast(linkNum,
[PRIM_SIZE, factor * llList2Vector(params, 0)]);
}
} </lsl>

But what if the function above encounters a prim that, after resized, would have a dimension outside
the legal range of 0.01m to 10.0m? That could have unfortunate consequences, so
here is a function that resizes all the prims by a specified factor but only if all the resulting
dimensions in all the prims will all be in the legal range of 0.01m to 10.0m. If any dimension in
any prim would go out of those bounds, the function will return FALSE without resizing anything.
This example also includes repositioning the child prims within the linkset. Change or add whatever
additional parameters are needed for your particular application.

<lsl> // This is not a complete resizer solution; it's just a demo of
// how to call the new LSL functions.

// Set the minimum and maximum size allowed for any prim in the linkset:
//
float minPrimSize = 0.01;
float maxPrimSize = 10.0;

// Resize all the prims in the linkset. For example, to resize all
// the prims to 1% smaller, call this function with factor=0.99
// Returns TRUE if successful, or FALSE if resizing would have
// set a prim size out of bounds.
//
integer resizeLinksetWithBounds(float factor)
{
// Test to see if it's safe to change all the prim sizes:

integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
vector sz = factor * llList2Vector(params, 0);
if (sz.x < minPrimSize || sz.x > maxPrimSize ||
sz.y < minPrimSize || sz.y > maxPrimSize ||
sz.z < minPrimSize || sz.z > maxPrimSize) {
return FALSE;
}
}

// We've determined that we can safely change all the sizes, so
// let's do so now.

for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list oldParams = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE, PRIM_POSITION]);

list newParams = [ PRIM_SIZE, factor * llList2Vector(oldParams, 0) ];
if (linkNum > 1) {
vector linkPos = (vector)llList2String(oldParams, 1);
vector localPos = (linkPos - llGetRootPosition()) / llGetRootRotation();
newParams += [ PRIM_POSITION, factor * localPos ];
}

llSetLinkPrimitiveParamsFast(linkNum, newParams);
}

return TRUE;
} </lsl>

Here's a silly example of how it's used:

<lsl> // Example of how to call resizeLinksetWithBounds()
//
default
{
touch_start(integer num)
{
float factor = llPow(llFrand(2.0), 2.0); // random factor for demo
if (resizeLinksetWithBounds(factor)) {
llOwnerSay("Resized successfully by factor = " + (string)factor);
} else {
llOwnerSay("Oops, can't resize by factor " + (string)factor);
}
}
} </lsl>
(Acknowledgements: Thanks to Keith Reinard for testing and improving the example above.)

Also see Maestro Linden's newly posted [[Linkset_resizer|linkset resizer]].

===Resizer challenges===

A complete resizer solution is outside the scope of this article, but might need to consider such things as:
* You might need a way to reset all the prims to a known size, position, and orientation in case a resize loop breaks before successfully resizing all the prims.
* The example above might give unexpected results if executed while the object is in motion. For example, there is no way to guarantee that the functions llGetLinkPrimitiveParams() and llGetRootPosition() will be evaluated during the same simulator frame, so the local offset of a child prim could be computed incorrectly as the difference of the root position in one frame and the child position in another frame.
* Roundoff errors could accumulate if proportional scaling is done ''many'' times. (See [[User_talk:Becky_Pippen/New_LSL_Functions|the Discussion page]].)
* It's easy to scale a linkset so that prims get moved beyond their [[Linkability_Rules|linkability limits]], and no easy way for a script to test for this in advance. For more information, see the discussions at {{JIRA|SVC-5328}} and {{JIRA|SVC-5166}}.

===Long range plans===

The new LSL features described above are expected to appear in server version 1.38. Babbage Linden also mentioned a few additional LSL features he would like to implement sometime after 1.38, but with no guarantees if or when:

<lsl> PRIM_NAME, PRIM_DESC // for llGet/SetPrimitiveParams()
llAvatarOnLinkSitTarget()
llLinkSitTarget() </lsl>

===Also see===

* [[Babbage_Linden|Babbage Linden at his Office Hours]]
* [https://blogs.secondlife.com/community/technology/blog/2010/03/05/server-138-beta-now-open this SL Blog announcement]
* [[User:Becky_Pippen/Script_Memory_Limits| Scripter's checklist of things you can do to conserve memory]]
* [[User:Becky_Pippen/Memory_Limits_FAQ| Script memory limits FAQ]]

User:Becky Pippen/Memory Limits FAQ

2010-04-27T17:59:48Z

Becky Pippen: Tweak wording to indicate server 1.38 has been deployed.

== FAQ - Script Memory Limits ==

For the most official announcement so far, see [https://blogs.secondlife.com/community/land/blog/2010/03/19/the-first-step-toward-script-limits here].

'''Q:''' Why do we need script memory limits?
: '''A:''' In some regions, the simulator uses so much script memory that it has to swap virtual memory to disk. That causes major lag, and lag is among the top complaints about Second Life.

'''Q:''' How can I tell if I'm a heavy script user?
: '''A:''' Starting with server version 1.38 and viewer version 2.0, we can now see our individual script memory usage, similar to how estate managers can see top scripts in a region. Also scripters can use the function [[LlGetFreeMemory|llGetFreeMemory()]] to get an approximate idea of memory usage.

'''Q:''' Will this break content?
: '''A:''' Yes, some. The limits are specifically designed to limit the worst 5% of memory consumers so that the remaining 95% can continue to run freely without causing the simulator to swap virtual memory.

'''Q:''' When will all this happen?
: '''A:''' Script memory reporting and the new memory-efficient LSL functions are now available on the main grid using server version 1.38 and version 2.0 of the SL viewer. Server version 1.40 or later will have "Small Scripts" capability (see below). Memory limits will not be enforced until later in 2010 after these features have been deployed on the main grid for some time.

'''Q:''' Will the limits be per avatar or per region?
: '''A:''' There will be limits on avatar, parcel, and region in a way that parallels [[LSL_http_server#Resource_Limitations|how URL resources are managed]].

'''Q:''' Will Linden Lab pay for all the scripted products we bought that will no longer work?
: '''A:''' Most products are reasonably scripted and will continue to work just fine. The only problematic products will be unusual ones that are scripted in ways that use unreasonable amounts of RAM. Try to get the product creator to make a new version that uses less memory.

'''Q:''' Will we see a reduction in lag across the grid?
: '''A:''' It won't have a major impact on most regions. However, it will make a huge improvement on the 5% of the regions that use so much script memory that the server has to swap virtual memory to disk. It is also expected to improve performance on any other simulators running on the same server host using the same disk resources.

'''Q:''' How much RAM are we talking about?
: '''A:''' In the 95% of the regions that run smoothly, the simulator uses less than 800MB of RAM for everything except scripts, and up to 300MB for all the scripts in the region, and that's ok. In the worst 5% of the regions, simulators use up to 2GB of RAM on the server, and that's not ok.

'''Q:''' Why not just add RAM to the servers? RAM is cheap.
: '''A:''' Several thousand Xeon server boards at, say, US$100 each to upgrade, comes out to a bunch of money, even for Linden Lab. Moving forward, new simulators (class 7) will have more RAM.

'''Q:''' Who will be affected?
: '''A:''' All scripts, old and new, will be subject to the new memory limits. When planning for the memory limits, [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2009_11_25 Babbage Linden said], "[2009/11/25 3:43] Babbage Linden: ideally we'd like to have 95+% of people use scripts as they currently do while still having 95+% of simulators running without swapping".

'''Q:''' What's the difference between "Small Scripts Project," "Big Scripts Project," and "Efficient Scripts Project?"
: '''A:''' The ''Efficient Scripts Project'' is the overall effort to reduce the memory consumption of Mono-based scripts, including limits on memory usage. The ''Small Scripts Project'' and ''Big Scripts Project'' both refer to a refinement where each script can request the specific amount of memory it anticipates using instead of being charged with a constant 16KB for LSL or 64KB for Mono scripts. So, for example, a simple Mono sit script might request only 3KB while another data-intensive Mono script might request several megabytes. Since the average Mono script in SL needs only about 9KB, this could help reduce overall script memory usage in a typical region. In [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2010_03_03 Office Hours], Babbage Linden said, "I would like to ship script usage, then small scripts, then script limits, then big scripts... so it would be nice to have mono scripts be able to reserve a lower memory amount before script limits enforcement happens."

'''Q:''' What's the "LSL Penalty?"
: '''A:''' At one time, LL considered charging LSL scripts with more memory than they actually consume as an incentive for scripters to use Mono. That idea has been dropped, and the current plan is to charge all scripts with the actual memory they reserve — currently 16KB for LSL, and 64KB for Mono scripts. In the future after the Small Scripts and Big Scripts Project have been implemented, Mono scripts can be charged for only the amount of memory they reserve, which could be more or less than 64KB. Discussion of this can be found in the [http://lists.secondlife.com/pipermail/opensource-dev/ opensource-dev] mailing list.

'''Q:''' What can I do as a content creator to prepare?
: '''A:''' Be kind to your customers and give them product updates using the [[User:Becky_Pippen/New_LSL_Functions| new efficient LSL functions]]. Learn more about how to [[User:Becky_Pippen/Measure_Script_Memory_Usage|measure memory usage]] and the [[User:Becky_Pippen/Script_Memory_Limits|scripting techniques for reducing memory]].

'''Q:''' What can I do as a customer?
: '''A:''' 95% of scripts are just fine and you don't need to do anything. If you are wearing hair, shoes, or other attachments with a script in every prim, then you can contact the creator and ask if there is a product update that uses the new LSL memory-efficient functions.

Talk:Code Sizer

2010-04-26T18:31:08Z

Becky Pippen:

= MONO v LSO =

I noticed [[Code Sizer|this script]] was written for use with LSO (no mention of that fact though (unless I am missing it)) so I set about writing a version to handle both LSO and MONO. Yet again I find myself pulling faces at the screen whilst trying to make sense of MONO's free memory. I came up with this -
<lsl>GetBytes(integer type)
{
integer this; // How many bytes are used (minimum) to compile and run.
if(type == 64) this = 3844; // This amount is hard to reduce in mono
else this = 354; // Slight changes have big effects in LSO
llOwnerSay((string)((1024 * type) - (llGetFreeMemory() + this)));
}

default
{
state_entry()
{
GetBytes(16); // 1 simple call per test.
// Although (in mono) it is very hard to tell exactly how many bytes are used by each call of GetBytes()
// One thing is for certain...Mono is odd.

// An example of code you might test -

llOwnerSay(llDumpList2String(["is", "how", "much", "does", "this", "code", "take", "up", "in", "bytes?"], " "));

// The llOwnerSay() above takes 512 bytes in mono and 122 in LSO

// When a script is first compiled in mono there is a larger byte count used than after all subsequent resets.
// On the first run the state_entry llOwnerSay() code takes 572 bytes. After reset 512.
// LSO does not have this initial discrepancy.
}
}</lsl>
I am sure someone else can do better. What interests me is how we should accurately measure memory use when [[llGetFreeMemory]] returns some very odd results (if you play around with enough variants for long enough). I wonder if someone wise might share? -- '''[[User:Fred_Gandt|Fred Gandt]]''' <sup><small>([[User talk:Fred_Gandt|talk]]|[[Special:Contributions/Fred_Gandt|contribs]])</small></sup> 23:57, 25 April 2010 (UTC)
: There are a few more clues and links about Mono's memory management, including a possible explanation of the 512-byte change you saw, at [[User:Becky_Pippen/Measure_Script_Memory_Usage|this page]]. Also, [[User:Becky_Pippen/LSL_Performance|this page]] shows examples of the Mono instructions that the compiler generates for an LSL function call. -- [[User:Becky Pippen|Becky Pippen]] 18:31, 26 April 2010 (UTC)

User:Becky Pippen/Shared Media LSL Recipes

2010-04-23T06:31:09Z

Becky Pippen: remove chars that made the TOC look weird

==How-to's with Media-on-a-Prim==



The examples here assume you're comfortable with LSL, and you just need a quick reference for the syntax of handling HTML and JavaScript in LSL for Shared Media scripting. All the examples on this page are ready to copy-n-paste and drop into a prim — no other setup needed. The key syntax in each example is highlighted. There's no error handling in these minimalist examples, so add plenty of your own.

===Display plain text — XyText replacement===
[[Image:MoaP-example_1.png‎|thumb|Plain text]]
<tt>
default
{
state_entry()
{
<span style="background-color:#F8F8C8">integer face = 4;</span>
<span style="background-color:#F8F8C8">string message = "Hello World";</span>
<span style="background-color:#F8F8C8">llSetPrimMediaParams(face,</span>
<span style="background-color:#F8F8C8">[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message]);</span>
}
} </tt>

Comments:
* An avatar must press the Reload button on the browser to see this rendered in-world. A page will be auto-loaded if you include the parameter <tt>PRIM_MEDIA_AUTO_PLAY, TRUE</tt>, and if the avatar has auto-load enabled in preferences.
* There's no need to add any %-hex-escaping or to use [[llEscapeURL]](); llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, url]) will automatically escape the string for you.
* This works by feeding a data URI to the on-prim browser. Think of it as serving the contents of the page in the URL itself. For more information, see [[Shared_Media_and_data_URI|here]] and [http://en.wikipedia.org/wiki/Data_URI_scheme here].
* The in-world browser limits the data URI (or any address) to 1024 bytes after %-hex-escaping and encoded in UTF-8. See below for tricks using external or self-served JavaScript or CSS to leverage the data URI.
* If the data URI contains just plain text, the prefix <tt>"data:text/html,"</tt> can be abbreviated <tt>"data:,"</tt>.

===Force a page reload===
<tt>
[[Image:MoaP-example-refreshpage.gif|thumb|Auto-refresh]]
integer face = 4;
string myURL;
<span style="background-color:#F8F8C8">integer seq = 0; // sequence number for unique URLs</span>

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llSetPrimMediaParams(face,
[PRIM_MEDIA_AUTO_PLAY, TRUE,
PRIM_MEDIA_CURRENT_URL, myURL]);
llSetTimerEvent(5.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, "Sim FPS: " + (string)llGetRegionFPS());
}
}

timer()
{
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, myURL + "/?r=" + (string)(++seq)</span>]);
}
} </tt>
Comments:
* The page will reload automatically if <tt>PRIM_MEDIA_AUTO_PLAY</tt> is enabled and if the new <tt>PRIM_MEDIA_CURRENT_URL</tt> is different. This technique appends a short dummy parameter (like <tt>"/?r=12"</tt>) to the end of the URL to make it different each time, forcing a reload. The parameter is otherwise ignored.

===Display text with HTML markup===
[[Image:MoaP-example-markup.png‎‎|thumb|HTML markup]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = <span style="background-color:#F8F8C8">"<i>Hello</i><h2>World!</h2>"</span>;
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* The text of the data URI will be %-hex-escaped automatically for you, so there's no need to use [[llEscapeURL]](). All you need in the data URI is the prefix <tt>data:text/html,</tt> plus your HTML.

===Change window resolution===
[[Image:MoaP-example-size.png‎|thumb|Resized web window]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "Hello World";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message,
<span style="background-color:#F8F8C8">PRIM_MEDIA_WIDTH_PIXELS, 128</span>,
<span style="background-color:#F8F8C8">PRIM_MEDIA_HEIGHT_PIXELS, 32</span>]);
}
} </tt>

Comments:
* The browser will add scroll bars if the rendered HTML doesn't fit within the specified PRIM_MEDIA_* size.

===Display an image — works with animated GIFs too===
[[Image:MoaP-example-animgif.gif‎|thumb|Image on a prim]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://upload.wikimedia.org/wikipedia/commons/7/70/Rotating_earth_(small).gif";
<span style="background-color:#F8F8C8">string dataURI = "data:text/html,<object data='" + imageURL + "'></object>";</span>
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI,
PRIM_MEDIA_WIDTH_PIXELS, 256,
PRIM_MEDIA_HEIGHT_PIXELS, 256]);
}
} </tt>

Comments:
* If attempting to display YouTube video full-frame, see [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/16/viewer-2-tip-shared-media-show-youtube-on-a-full-prims-face this discussion].
* For images, you can also use <tt><image src= ></tt> like this:
string dataURI="data:text/html,<img src='" + imageURL + "'>";

===Display a background image, tiled===

====Method #1 — using CSS in a style element in <head>====
[[Image:MoaP-example-bgTiled.png‎|thumb|Tiled background image]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "data:text/html,<head>"
+ "<span style="background-color:#F8F8C8"><style type='text/css'>body{background-image:url(\"</span>"
+ <span style="background-color:#F8F8C8">imageURL + "\");}</style></span></head><body>Hello World</body>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #2 — using background attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body background='" + imageURL + "'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #3 — using style attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body style='background-image:url(\"" + imageURL + "\")'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

===Text colors — using <font> element===
[[Image:MoaP-example-font-color.png‎|thumb|Font color]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "<span style="background-color:#F8F8C8"><font color='Red'>Hello World</font></span>";
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* You can also specify color and other CSS rules in a style attribute in another element. For example, you can replace message in the example above with:

string message = "<h2 style='color:#FF0000'>Hello World</h2>";

===Link to external CSS file (forms example)===
[[Image:MoaP-example-externalCSS.png‎|thumb|External CSS file]]
<tt>
default
{
state_entry()
{
integer face = 4;
<span style="background-color:#F8F8C8">string externalCSS =</span>
<span style="background-color:#F8F8C8">"http://www.google.com/css/modules/buttons/g-button-chocobo.css";</span>

string dataURI = "data:text/html,<head><span style="background-color:#F8F8C8"><link href='</span>" +
<span style="background-color:#F8F8C8">externalCSS + "' rel='stylesheet' type='text/css' /></span></head>" +
"<form><input type='button' value='Click Me' class='g-button' /></form>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is one way to work around the 1024-byte limitation of data URIs. The external CSS can be as large as the browser permits. Also see the examples below for putting JavaScript in an external file.
* The tag <tt><head></tt> and the attribute <tt>type='text/css'</tt> may be omitted to make the data URI a few bytes shorter.

===Calling external JavaScript functions (JQuery example)===
[[Image:MoaP-example-JQuery.gif‎|thumb|Calling external JQuery]]
<tt>
integer face = 4;
string externalJavascript =
"http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js";
default
{
state_entry()
{
string dataURI = "data:text/html," +
"<head><span style="background-color:#F8F8C8"><script src='" + externalJavascript + "'></script></span></head>" +
"<button>Toggle</button>" +
"<p>Hello<br />World</p>" +
"<span style="background-color:#F8F8C8"><script>$('button').click(function () </span>" +
"<span style="background-color:#F8F8C8">{$('p').slideToggle('slow');});</script></span>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is a technique for working around the 1024-byte limit for data URIs. When you can't fit all the JavaScript you need into one data URI, just move some JavaScript functions into an external file and give the browser a data URI that references the external file with a URL. In this example above, the JavaScript for [http://jquery.com/ JQuery] lives in an external file on Google's servers. You just need enough bytes left over in the data URI to put a JavaScript function call with its parameters inside a <tt><script></tt> element.
* A data URI can be used as a springboard to generate arbitrary complex web pages by making use of these elements:
** a reference to external CSS with <tt><link href= </tt>,
** a reference to external JavaScript with <tt><script src=</tt>, and
** a function call with parameters to the external JavaScript using <tt><script>someFunction(args);</script></tt>. (In the JQuery example above, the name of the external function is <tt>"$"</tt>.)
* See the next two examples for variations of this same technique.

===Self-served HTML and JavaScript===
====Example #1 — using <script src= and .innerHTML= ====
[[Image:MoaP-example-refresh-clock.gif‎|thumb|Self-served auto-refreshed pages]]
<tt>
integer face = 4;
string myURL;

// This can be up to 2KBytes after %-hex-escaping:
<span style="background-color:#F8F8C8">string servedPage =</span> "
function checklength(i){if (i<10) {i='0'+i;} return i;}
<span style="background-color:#F8F8C8">function clock()</span>{
var now = new Date();
var hours = checklength(now.getHours());
var minutes = checklength(now.getMinutes());
var seconds = checklength(now.getSeconds());
var format = 1; //0=24 hour format, 1=12 hour format
var time;
if (format == 1) {
if (hours >= 12) {
if (hours ==12 ) { hours = 12;
} else { hours = hours-12; }
time=hours+':'+minutes+':'+seconds+' PM';
} else if(hours < 12) {
if (hours ==0) {hours=12;}
time=hours+':'+minutes+':'+seconds+' AM';
}
}
if (format == 0) {time= hours+':'+minutes+':'+seconds;}
<span style="background-color:#F8F8C8">document.getElementById('clock').innerHTML=time;</span>
setTimeout('clock();', 500);
} "; // yes, that's one long string.

displayPage()
{
string dataURI = "data:text/html,<span style="background-color:#F8F8C8"><script src='</span>" +
<span style="background-color:#F8F8C8">myURL + "'></script></span>" +
"<span style="background-color:#F8F8C8"><div id='clock'><script>clock();</script></div></span>";
llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);
}

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
<span style="background-color:#F8F8C8">myURL = body;</span>
displayPage();
} else if (method == "GET") {
<span style="background-color:#F8F8C8">llHTTPResponse(id, 200, servedPage);</span>
}
}
} </tt>

Comments:
* This is a technique for trading the 1024-byte limit of data URIs for the 2048-byte-per-page limit that the script can serve itself. As in the previous example, when you can't fit all the JavaScript into one data URI, just move the JavaScript into an external file and reference the file with <tt><script src=URL></script></tt>. When the URL refers to the script's own HTTP-in URL, then the page served can contain up to 2K bytes, so you get at least that many bytes plus whatever logic you can fit into the rest of the data URI. If you move that JavaScript to an external web server, the size of the external JavaScript file can be as large as the client web browser can render.
* Your script can serve an arbitrary number of different pages through one HTTP-in URL by appending a path or parameter to the URL.
* This works by assigning a string containing HTML to the <tt>.innerHTML</tt> contents of the <tt><div></tt> element with id "clock". This achieves something similar to the Ajax-like [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim technique published by Tali Rosca] and mentioned [http://wiki.secondlife.com/wiki/User:Kelly_Linden/lsl_hacks#DHTML_.2F_Javascript_.28Tali_Rosca.29 here]. In those techniques, a string is constructed containing an <tt><a href=</tt> tag and an <tt>href=</tt> that points to the script's HTTP-in URL. That string then replaces the <tt><body></tt> element using:
<tt>document.getElementsByTagName('body')[0].innerHTML = <i>new-content</i></tt>

====Example #2 — using <body onload= (lag graph example)====
[[Image:MoaP-example-laggraph.gif‎|thumb|Refreshed pages]]
<tt>
integer face = 4;
string jsURL; // where to fetch external JavaScript
list numbers;
integer numSamples = 50;

// This is self-served in this example, but can be
// moved to an external server:
//
string externalJavascript()
{
return
"function bar(widthPct,heightPix) {" +
" document.writeln(\"<hr style='padding:0;margin:0;" +
" margin-top:-1px;text-align:left;align:left;border=0;" +
" width:\"+widthPct+\"%;height:\"+heightPix+\"px;" +
" background-color:#c22;color:#c22;'>\");}" +
" function graphBars(arr){for(var i=0;i<arr.length;++i)" +
" {bar(arr[i],18);}}";
}

default
{
state_entry()
{
llClearPrimMedia(face);
llRequestURL();
integer i = numSamples;
while (--i >= 0) {
numbers += 0;
}
}

timer()
{
numbers = llList2List(numbers, 1, -1) + [(integer)(6.0 * (45.0 - llGetRegionFPS()))];

// The dataURI loads external JavaScript functions and calls one with parameters:

string dataURI = "data:text/html," +
"<span style="background-color:#F8F8C8"><head><script src='" + jsURL + "'></script></head></span>" +
"<span style="background-color:#F8F8C8"><body onload=\"graphBars([" + llList2CSV(numbers) + "]);\"></body></span>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI, PRIM_MEDIA_AUTO_PLAY, TRUE]);
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
jsURL = body; // self-serve the JavaScript
llSetTimerEvent(1.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, externalJavascript());
}
}
} </tt>

Comments:
* Like the previous example, this is another variation of how to structure a data URI to serve as a springboard for arbitrarily large pages. In this example, the data URI first uses a <tt><script src=...></tt> tag to read a file of external JavaScript functions in the <tt><head></tt> element, and then the <tt>onload=</tt> attribute in <tt><body></tt> triggers a call to one of the functions which executes a loop creating a bunch of <tt><hr></tt> elements that form the bar chart. The size of HTML generated by the JavaScript can be as large as the browser permits.
* In this example, <tt>jsURL</tt> is set to the script's own HTTP-in URL so that the example can be self-contained, but you can point <tt>jsURL</tt> to an external URL as well. If served by an external server, the JavaScript read in <tt><head></tt> can be as large as the browser permits.
* <tt><head></head></tt> can be omitted in the data URI surrounding the <tt><script src=</tt> tag.

===Reverse Ajax - Long-polling the HTTP-in server, chat logger example===
[[Image:MoaP-example-Long-polling-httpin.gif|thumb|300px|Long-polling HTTP-in]]
<tt>
// Reverse Ajax: Long-polling HTTP-in.
// Becky Pippen, 2010, contributed to the public domain.

integer face = 4; // Prim face for Shared Media

<span style="background-color:#F8F8C8">string myURL; // HTTP-in URL</span>
<span style="background-color:#F8F8C8">key inId = NULL_KEY; // GET request id</span>
<span style="background-color:#E0FDE0">list msgQueue = []; // strings of Javascript</span>

<span style="background-color:#F8F8C8">// url is our own HTTP-in url.
// This sets up a bootloader web page like this:
// <html><body>
// <div><script id='sc'></script></div>
// <script> callbacks and poll.beg() defined here </script>
// <button onclick=poll.beg()>Start</button>
// <div id='dv'></div>
// </body></html>
// When the button is pressed, the JS code sets src= on script#sc
// and reattaches the script element to the parent <div> element which
// initiates a GET to the prim's HTTP-in port
//
setDataURI(string url)
{
string dataURI = "data:text/html,
<!DOCTYPE HTML><html><body><div><script id='sc'></script></div><script>
var poll=function(){var sc=document.getElementById('sc'),t2,seq=0,s0;return{
beg:function(){s0=document.createElement('script');s0.onload=poll.end;t2=setTimeout('poll.end()',20000);
s0.src='" + url + "/?r='+(seq++);sc.parentNode.replaceChild(s0,sc);sc=s0;},
end:function(){clearTimeout(t2);t2=null;sc.onload=null;setTimeout('poll.beg()',500);},};}();</script>
<button id='btn'onclick=poll.beg()>Start</button><div id='dv'></div></body></html>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);</span>
}

<span style="background-color:#E0FDE0">// Returns zero or more queued messages. Assumes no single message is
// longer than MAX_SIZE_CHARS (will hang if there is)
//
string popQueuedMessages()
{
string totalMsg = "";
integer totalMsgSize = 0;
string nextMsg = "";
integer nextMsgSize = 0;

// HTTP response bodies are limited to 2048 bytes after encoding
// in UTF-8. LSL string sizes are measured in characters, which,
// in UTF-8, use one byte (for ASCII chars), two bytes (most Latin-1),
// or three bytes (a few international characters). So, unless
// you re-write this section so that it measures UTF-8 size, keep
// MAX_SIZE_CHARS small enough so the text will fit in a response body.
//
integer MAX_SIZE_CHARS = 1000; // Max HTTP body size

integer numMessagesQueued = llGetListLength(msgQueue);
integer count = 0;
while (count < numMessagesQueued) {
nextMsg = llList2String(msgQueue, count);
nextMsgSize = llStringLength(nextMsg);

if (totalMsgSize + nextMsgSize < MAX_SIZE_CHARS) {
totalMsg += nextMsg;
totalMsgSize += nextMsgSize;
++count;
}
}

// Delete the messages from the queue that we're going to send:
if (count > 0) {
msgQueue = llDeleteSubList(msgQueue, 0, count - 1);</span>
}

return totalMsg;
}

<span style="background-color:#E0FDE0">// Called when there are previous messages still queued, or if there
// is no GET request currently open to respond to.</span>
//
pushMessageToSend(string msg)
{
<span style="background-color:#E0FDE0">msgQueue = msgQueue + [msg]; // last element is the last one stacked</span>

// See if we can send some messages now:
<span style="background-color:#F8F8C8">if (inId != NULL_KEY) {</span>
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, popQueuedMessages());</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} // else wait for the next incoming GET request
}

// Replaces all occurrences of 'from' with 'to' in 'src'
// From http://snipplr.com/view/13279/lslstrreplace/
//
string str_replace(string subject, string search, string replace)
{
return llDumpList2String(llParseStringKeepNulls(subject, [search], []), replace);
}

// Optionally filter out characters in text that would mess up the
// web page display. This demo just escapes ' and " and adds a space after '<'.
//
string addSlashes(string s)
{
return str_replace(str_replace(str_replace(s, "<", "< "), "\"", "\\\""), "'", "\\\'");
}

// This is the main interface for LSL to control the Shared Media web page.
// The messages we send consist of Javascript function statements that the
// browser will evaluate and execute in the context of the web page.
// See sendMessageF() for a similar function with macro replacement.
//
sendMessage(string msg)
{
// Test for the easy case: if there are no other messages waiting
// in the queue, and if there is an open GET connection, then just
// respond immediately:

<span style="background-color:#E0FDE0">if (llGetListLength(msgQueue) == 0</span> && <span style="background-color:#F8F8C8">inId != NULL_KEY) {</span>
// Nothing in the queue and an open GET, so respond immediately:
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, msg);</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} <span style="background-color:#E0FDE0">else {</span>
<span style="background-color:#E0FDE0">pushMessageToSend(msg);</span>
}
}

// Same as sendMessage() but with macro replacements. For each nth string
// element in replacements, replace all occurrences of {@n}. For example,
// sendMessageF( "alert('{@0} {@1}!')", ["Hello", "World"] );
// will send "alert('Hello World!')" to the web browser.
//
sendMessageF(string msg, list replacements)
{
integer numrepl = llGetListLength(replacements);
integer i;
for (i = 0; i < numrepl; ++i) {
msg = str_replace(msg, "{@" + (string)i + "}", llList2String(replacements, i));
}

<span style="background-color:#F8F8C8">sendMessage(msg);</span>
}

<span style="background-color:#E8E8FF">// Chat logger demo: writes a new <tr> table row to the web page
// for every line of open chat it hears.
//
webAppInit()
{
string msg;
string m0;

// First, send over a few handy function definitions:

msg = "function $$(t) { return document.getElementsByTagName(t)[0]; };";
msg += "function h() { return $$('head'); };";
msg += "function b() { return $$('body'); };";
msg += "function e(id) { return document.getElementById(id); };";
sendMessage(msg);

// Send some CSS. WebKit is sensitive about appending <style> elements
// to <head>, so we'll append it to an existing <div> tag in <body> instead.

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<style>td:nth-child(2) { text-align:right } tr:nth-child(odd) { background-color:#f8e8f8 }</style>";
sendMessageF(msg, [m0]);

// Write a <table> element into element div#dv. The lines of chat will
// become rows in this table appended to tbody#tbd

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<table><tbody id='tbd'></tbody></table>";
sendMessageF(msg, [m0]);

llListen(0, "", NULL_KEY, "");</span>
}

default
{
state_entry()
{
llClearPrimMedia(face);
<span style="background-color:#F8F8C8"> llRequestURL();</span>

<span style="background-color:#E8E8FF"> webAppInit();</span>
}

<span style="background-color:#F8F8C8"> http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llOwnerSay("myURL=" + myURL);
setDataURI(myURL);
} else if (method == "GET") {
// Either send some queued messages now with llHTTPResponse(),
// or if there's nothing to do now, save the GET id and
// wait for somebody to call sendMessage().</span>
<span style="background-color:#E0FDE0"> if (llGetListLength(msgQueue) > 0) {</span>
<span style="background-color:#F8F8C8"> llHTTPResponse(id, 200, popQueuedMessages());
inId = NULL_KEY;
} else {
inId = id;
}
}
}</span>

<span style="background-color:#E8E8FF"> // When we hear chat from name, send a Javascript statement that
// appends HTML to element #tbd. I.e., we'll make a string of HTML
// formatted like this:
// <tr style="color:hsl(200,100%,30%)">
// <td>[01:23]</td>
// <td>Avatar Name</td>
// <td>the chat text</td>
// </tr>
// and send it wrapped it in a Javascript statement like this:
// e('tbd').innerHTML += htmlstring;
//
listen(integer chan, string name, key id, string chat)
{
integer s = (integer)("0x" + llGetSubString((string)id, 0, 6));
string hue = (string)(s % 360);
string color = "hsl(" + hue + ",100%, 30%)";

string msg = "e('tbd').innerHTML += '{@0}';";
string m0 = "<tr style=\"color: {@4}\">";
m0 += "<td>{@1}</td>";
m0 += "<td>{@2}:</td>";
m0 += "<td>{@3}</td>";
m0 += "</tr>";

string t = llGetSubString(llGetTimestamp(), 11, 15);
sendMessageF(msg, [m0, "[" + t + "]", name, addSlashes(chat), color]);
}</span>
}
</tt>

Comments:
<ol start="1">
<li>This "[http://en.wikipedia.org/wiki/Push_technology server-push]" technique using long-polling gives an LSL script the ability to modify the web page displayed on a prim. The Javascript side always keeps an HTTP GET open to the prim's HTTP-in URL, and the LSL side responds whenever it wants to with a response consisting of strings of Javascript to be executed by the web browser. For example, this LSL code causes an alert box to pop up on the web page:
: <code>sendMessage( "alert()" );</code></li>
<li>In the LSL listing above, <span style="background-color:#F8F8C8">the yellow highlighting</span> shows the most important parts of the HTTP long-polling mechanism. The <span style="background-color:#E0FDE0">green highlighting</span> shows the message buffering on top of that. The <span style="background-color:#E8E8FF">blue highlighting</span> is the application code that uses long-polling. To use long-polling for a different application, replace the blue parts. The rest is glue.</li>
<li>To avoid some subtle WebKit problems when dynamically appending or replacing the first-level child nodes in <head> or <body>, we've made two special <div> elements on the bootstrap HTML page. The first surrounds the script#sc element that we replace for each GET. The second is at the end of <body> as a convenient place for the application to insert new content that would otherwise go in <body>.</li>
<li>To make sure that there is nearly always a valid GET request open, the Javascript side starts a new GET after receiving a response, or when the last GET times out.</li>
<li>There are two timeouts hard-coded in the bootstrap data URI:
<ol style="list-style-type:lower-roman"><li>The "20000" is the timeout (20 seconds) for when an open GET expires, and should be set to something around the minimum of the WebKit outgoing GET request timeout, and the SL-LSL incoming GET timeout. This ensures that GETs are nearly continuous. [[LlHTTPResponse|This page]] says the timeout on the LSL side is 25 seconds.</li>
<li>The "500" is a throttle that sets an upper limit to how fast the Javascript re-polls HTTP-in to prevent hammering the simulator. It's a half-second delay after receiving a GET response before starting a new GET.</li></ol>
<li> If there's a little gap between two GETs, or if two overlap a little, the sendMessage() message buffering will compensate by queuing up messages to be sent when the next GET arrives. If there are multiple messages in the queue when a GET arrives, the LSL side will concatenate as many messages as possible and send them together.
</li>
<li>On the Javascript side, the GET is not triggered until the <tt><script></tt> element is attached to its parent node with .appendChild() or .replaceChild().</li>
<li>The bootstrap Javascript above in setDataURI() had to be compressed somewhat to fit into the 1024-byte data URI limit. Here's an expanded listing for reference with more descriptive names:</li>
<tt>
<!DOCTYPE HTML>
<html>
<body>
<div>
<script id='script'> </script>
</div>
<script>
var poll=function(){
var script=document.getElementById('script'),
timeoutId,
seq=0,
newScript;
return {
beg:function(){ // Initiate a long-poll GET
newScript=document.createElement('script'); // The response will go here
newScript.onload=poll.end; // Call poll.end() when we get a response
timeoutId=setTimeout('poll.end()',20000); // ... or if we time out
newScript.src=' HTTP-in URL goes here /?r='+(seq++);
script.parentNode.replaceChild(newScript,script); // this triggers the GET
script=newScript;},

end:function(){
clearTimeout(timeoutId);
timeoutId=null;
script.onload=null;
setTimeout('poll.beg()',500); // Wait a bit before re-polling
},
};
}();
</script>
<button id='btn'onclick=poll.beg()>Start<button>
<div id='dv'> </div>
</body>
</html>
</tt>
</ol>

===Make TinyURLs by script===
<tt>
string myTinyURL;

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
// Send our full URL to tinyurl.com for conversion
// The answer will come back in http_response()
<span style="background-color:#F8F8C8">llHTTPRequest("http://tinyurl.com/api-create.php?url=" + body, [], "");</span>
} else if (method == "GET") {
llHTTPResponse(id, 200, "Hello Real World from the Virtual World");
}
}

http_response(key req, integer stat, list met, string body)
{
<span style="background-color:#F8F8C8">myTinyURL = body;</span>
llOwnerSay("My HTTP-in TinyURL is: " + myTinyURL + " , Click Me!");
}
} </tt>

Comments:
* Any URL or data URI can be mapped to a TinyURL. The example above reduces an assigned HTTP-in URL, which is a long one such as:
<nowiki>http://sim4605.agni.lindenlab.com:12046/cap/2b9f06f7-431e-5b0f-9271-2d03bd15370b</nowiki>
into a TinyURL this size:
<nowiki>http://tinyurl.com/y9etul3</nowiki>

===Development hints===
# You can develop your HTML and JavaScript outside of Second Life by putting your JavaScript incantations in data URIs that you feed to any web browser. For the most compatible browsers, use Safari or Google Chrome, or any other that uses the [[QtWebKit|WebKit]] HTML rendering engine. If you can't run Safari or Chrome, try the open source [http://code.google.com/p/arora/ Arora web browser] for simulating Media-on-a-Prim: it's based on straight-up WebKit and has the same handy inspector/debugger found in other WebKit browsers.
# If you don't have direct access to a web server while developing this stuff, then consider installing a local copy of [http://www.apache.org/ Apache web server] on your computer. You can restrict it to local access. Then you can refer to files on your own computer with URLs that start with <tt><nowiki>http://localhost/</nowiki>...</tt>, and PHP scripts can simulate what the HTTP-in server would serve. That lets you, for example, edit <tt>myfile.js</tt> on your own computer while working on a data URI that contains <tt><script src="<nowiki>http://localhost/myfile.js</nowiki>"></tt>. Then when <tt>myfile.js</tt> is working, you can put the debugged code into an LSL script that will serve it through its HTTP-in port. That's easier than debugging all that in-world.

===References and sources===
* [[User:Kelly_Linden/lsl_hacks|Kelly Linden's hacks]]
* [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim Tali Rosca's techniques]
* [https://blogs.secondlife.com/message/115303 Notecard Text on a Prim - Demo]
* [[llSetPrimMediaParams]]()
* {{JIRA|SVC-3427}}
* [https://blogs.secondlife.com/message/124144 Ajax in Shared Media #1]
* [https://blogs.secondlife.com/thread/11698 Ajax in Shared Media #2]
* [https://blogs.secondlife.com/thread/12727 Ajax in Shared Media #3]
* [https://blogs.secondlife.com/thread/13455 SVG (Scalable Vector Graphics) in Shared Media]
* [[Shared_Media_and_data_URI|Shared_Media_and_data_URI]]
* [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/17/viewer-2-tip-shared-media-add-custom-content-with-data-uri-no-webpage-upload-needed Shared Media: Add custom content with data: URI]
* [https://blogs.secondlife.com/message/119704 "Shared Media" - A few facts]

[[Category:Shared Media]]

User:Becky Pippen/Shared Media LSL Recipes

2010-04-23T06:20:20Z

Becky Pippen:

==How-to's with Media-on-a-Prim==



The examples here assume you're comfortable with LSL, and you just need a quick reference for the syntax of handling HTML and JavaScript in LSL for Shared Media scripting. All the examples on this page are ready to copy-n-paste and drop into a prim — no other setup needed. The key syntax in each example is highlighted. There's no error handling in these minimalist examples, so add plenty of your own.

===Display plain text — XyText replacement===
[[Image:MoaP-example_1.png‎|thumb|Plain text]]
<tt>
default
{
state_entry()
{
<span style="background-color:#F8F8C8">integer face = 4;</span>
<span style="background-color:#F8F8C8">string message = "Hello World";</span>
<span style="background-color:#F8F8C8">llSetPrimMediaParams(face,</span>
<span style="background-color:#F8F8C8">[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message]);</span>
}
} </tt>

Comments:
* An avatar must press the Reload button on the browser to see this rendered in-world. A page will be auto-loaded if you include the parameter <tt>PRIM_MEDIA_AUTO_PLAY, TRUE</tt>, and if the avatar has auto-load enabled in preferences.
* There's no need to add any %-hex-escaping or to use [[llEscapeURL]](); llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, url]) will automatically escape the string for you.
* This works by feeding a data URI to the on-prim browser. Think of it as serving the contents of the page in the URL itself. For more information, see [[Shared_Media_and_data_URI|here]] and [http://en.wikipedia.org/wiki/Data_URI_scheme here].
* The in-world browser limits the data URI (or any address) to 1024 bytes after %-hex-escaping and encoded in UTF-8. See below for tricks using external or self-served JavaScript or CSS to leverage the data URI.
* If the data URI contains just plain text, the prefix <tt>"data:text/html,"</tt> can be abbreviated <tt>"data:,"</tt>.

===Force a page reload===
<tt>
[[Image:MoaP-example-refreshpage.gif|thumb|Auto-refresh]]
integer face = 4;
string myURL;
<span style="background-color:#F8F8C8">integer seq = 0; // sequence number for unique URLs</span>

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llSetPrimMediaParams(face,
[PRIM_MEDIA_AUTO_PLAY, TRUE,
PRIM_MEDIA_CURRENT_URL, myURL]);
llSetTimerEvent(5.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, "Sim FPS: " + (string)llGetRegionFPS());
}
}

timer()
{
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, myURL + "/?r=" + (string)(++seq)</span>]);
}
} </tt>
Comments:
* The page will reload automatically if <tt>PRIM_MEDIA_AUTO_PLAY</tt> is enabled and if the new <tt>PRIM_MEDIA_CURRENT_URL</tt> is different. This technique appends a short dummy parameter (like <tt>"/?r=12"</tt>) to the end of the URL to make it different each time, forcing a reload. The parameter is otherwise ignored.

===Display text with HTML markup===
[[Image:MoaP-example-markup.png‎‎|thumb|HTML markup]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = <span style="background-color:#F8F8C8">"<i>Hello</i><h2>World!</h2>"</span>;
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* The text of the data URI will be %-hex-escaped automatically for you, so there's no need to use [[llEscapeURL]](). All you need in the data URI is the prefix <tt>data:text/html,</tt> plus your HTML.

===Change window resolution===
[[Image:MoaP-example-size.png‎|thumb|Resized web window]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "Hello World";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message,
<span style="background-color:#F8F8C8">PRIM_MEDIA_WIDTH_PIXELS, 128</span>,
<span style="background-color:#F8F8C8">PRIM_MEDIA_HEIGHT_PIXELS, 32</span>]);
}
} </tt>

Comments:
* The browser will add scroll bars if the rendered HTML doesn't fit within the specified PRIM_MEDIA_* size.

===Display an image — works with animated GIFs too===
[[Image:MoaP-example-animgif.gif‎|thumb|Image on a prim]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://upload.wikimedia.org/wikipedia/commons/7/70/Rotating_earth_(small).gif";
<span style="background-color:#F8F8C8">string dataURI = "data:text/html,<object data='" + imageURL + "'></object>";</span>
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI,
PRIM_MEDIA_WIDTH_PIXELS, 256,
PRIM_MEDIA_HEIGHT_PIXELS, 256]);
}
} </tt>

Comments:
* If attempting to display YouTube video full-frame, see [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/16/viewer-2-tip-shared-media-show-youtube-on-a-full-prims-face this discussion].
* For images, you can also use <tt><image src= ></tt> like this:
string dataURI="data:text/html,<img src='" + imageURL + "'>";

===Display a background image, tiled===

====Method #1 — using CSS in a style element in <head>====
[[Image:MoaP-example-bgTiled.png‎|thumb|Tiled background image]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "data:text/html,<head>"
+ "<span style="background-color:#F8F8C8"><style type='text/css'>body{background-image:url(\"</span>"
+ <span style="background-color:#F8F8C8">imageURL + "\");}</style></span></head><body>Hello World</body>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #2 — using background attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body background='" + imageURL + "'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #3 — using style attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body style='background-image:url(\"" + imageURL + "\")'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

===Text colors — using <font> element===
[[Image:MoaP-example-font-color.png‎|thumb|Font color]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "<span style="background-color:#F8F8C8"><font color='Red'>Hello World</font></span>";
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* You can also specify color and other CSS rules in a style attribute in another element. For example, you can replace message in the example above with:

string message = "<h2 style='color:#FF0000'>Hello World</h2>";

===Link to external CSS file (forms example)===
[[Image:MoaP-example-externalCSS.png‎|thumb|External CSS file]]
<tt>
default
{
state_entry()
{
integer face = 4;
<span style="background-color:#F8F8C8">string externalCSS =</span>
<span style="background-color:#F8F8C8">"http://www.google.com/css/modules/buttons/g-button-chocobo.css";</span>

string dataURI = "data:text/html,<head><span style="background-color:#F8F8C8"><link href='</span>" +
<span style="background-color:#F8F8C8">externalCSS + "' rel='stylesheet' type='text/css' /></span></head>" +
"<form><input type='button' value='Click Me' class='g-button' /></form>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is one way to work around the 1024-byte limitation of data URIs. The external CSS can be as large as the browser permits. Also see the examples below for putting JavaScript in an external file.
* The tag <tt><head></tt> and the attribute <tt>type='text/css'</tt> may be omitted to make the data URI a few bytes shorter.

===Calling external JavaScript functions (JQuery example)===
[[Image:MoaP-example-JQuery.gif‎|thumb|Calling external JQuery]]
<tt>
integer face = 4;
string externalJavascript =
"http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js";
default
{
state_entry()
{
string dataURI = "data:text/html," +
"<head><span style="background-color:#F8F8C8"><script src='" + externalJavascript + "'></script></span></head>" +
"<button>Toggle</button>" +
"<p>Hello<br />World</p>" +
"<span style="background-color:#F8F8C8"><script>$('button').click(function () </span>" +
"<span style="background-color:#F8F8C8">{$('p').slideToggle('slow');});</script></span>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is a technique for working around the 1024-byte limit for data URIs. When you can't fit all the JavaScript you need into one data URI, just move some JavaScript functions into an external file and give the browser a data URI that references the external file with a URL. In this example above, the JavaScript for [http://jquery.com/ JQuery] lives in an external file on Google's servers. You just need enough bytes left over in the data URI to put a JavaScript function call with its parameters inside a <tt><script></tt> element.
* A data URI can be used as a springboard to generate arbitrary complex web pages by making use of these elements:
** a reference to external CSS with <tt><link href= </tt>,
** a reference to external JavaScript with <tt><script src=</tt>, and
** a function call with parameters to the external JavaScript using <tt><script>someFunction(args);</script></tt>. (In the JQuery example above, the name of the external function is <tt>"$"</tt>.)
* See the next two examples for variations of this same technique.

===Self-served HTML and JavaScript===
====Example #1 — using <script src= and .innerHTML= ====
[[Image:MoaP-example-refresh-clock.gif‎|thumb|Self-served auto-refreshed pages]]
<tt>
integer face = 4;
string myURL;

// This can be up to 2KBytes after %-hex-escaping:
<span style="background-color:#F8F8C8">string servedPage =</span> "
function checklength(i){if (i<10) {i='0'+i;} return i;}
<span style="background-color:#F8F8C8">function clock()</span>{
var now = new Date();
var hours = checklength(now.getHours());
var minutes = checklength(now.getMinutes());
var seconds = checklength(now.getSeconds());
var format = 1; //0=24 hour format, 1=12 hour format
var time;
if (format == 1) {
if (hours >= 12) {
if (hours ==12 ) { hours = 12;
} else { hours = hours-12; }
time=hours+':'+minutes+':'+seconds+' PM';
} else if(hours < 12) {
if (hours ==0) {hours=12;}
time=hours+':'+minutes+':'+seconds+' AM';
}
}
if (format == 0) {time= hours+':'+minutes+':'+seconds;}
<span style="background-color:#F8F8C8">document.getElementById('clock').innerHTML=time;</span>
setTimeout('clock();', 500);
} "; // yes, that's one long string.

displayPage()
{
string dataURI = "data:text/html,<span style="background-color:#F8F8C8"><script src='</span>" +
<span style="background-color:#F8F8C8">myURL + "'></script></span>" +
"<span style="background-color:#F8F8C8"><div id='clock'><script>clock();</script></div></span>";
llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);
}

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
<span style="background-color:#F8F8C8">myURL = body;</span>
displayPage();
} else if (method == "GET") {
<span style="background-color:#F8F8C8">llHTTPResponse(id, 200, servedPage);</span>
}
}
} </tt>

Comments:
* This is a technique for trading the 1024-byte limit of data URIs for the 2048-byte-per-page limit that the script can serve itself. As in the previous example, when you can't fit all the JavaScript into one data URI, just move the JavaScript into an external file and reference the file with <tt><script src=URL></script></tt>. When the URL refers to the script's own HTTP-in URL, then the page served can contain up to 2K bytes, so you get at least that many bytes plus whatever logic you can fit into the rest of the data URI. If you move that JavaScript to an external web server, the size of the external JavaScript file can be as large as the client web browser can render.
* Your script can serve an arbitrary number of different pages through one HTTP-in URL by appending a path or parameter to the URL.
* This works by assigning a string containing HTML to the <tt>.innerHTML</tt> contents of the <tt><div></tt> element with id "clock". This achieves something similar to the Ajax-like [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim technique published by Tali Rosca] and mentioned [http://wiki.secondlife.com/wiki/User:Kelly_Linden/lsl_hacks#DHTML_.2F_Javascript_.28Tali_Rosca.29 here]. In those techniques, a string is constructed containing an <tt><a href=</tt> tag and an <tt>href=</tt> that points to the script's HTTP-in URL. That string then replaces the <tt><body></tt> element using:
<tt>document.getElementsByTagName('body')[0].innerHTML = <i>new-content</i></tt>

====Example #2 — using <body onload= (lag graph example)====
[[Image:MoaP-example-laggraph.gif‎|thumb|Refreshed pages]]
<tt>
integer face = 4;
string jsURL; // where to fetch external JavaScript
list numbers;
integer numSamples = 50;

// This is self-served in this example, but can be
// moved to an external server:
//
string externalJavascript()
{
return
"function bar(widthPct,heightPix) {" +
" document.writeln(\"<hr style='padding:0;margin:0;" +
" margin-top:-1px;text-align:left;align:left;border=0;" +
" width:\"+widthPct+\"%;height:\"+heightPix+\"px;" +
" background-color:#c22;color:#c22;'>\");}" +
" function graphBars(arr){for(var i=0;i<arr.length;++i)" +
" {bar(arr[i],18);}}";
}

default
{
state_entry()
{
llClearPrimMedia(face);
llRequestURL();
integer i = numSamples;
while (--i >= 0) {
numbers += 0;
}
}

timer()
{
numbers = llList2List(numbers, 1, -1) + [(integer)(6.0 * (45.0 - llGetRegionFPS()))];

// The dataURI loads external JavaScript functions and calls one with parameters:

string dataURI = "data:text/html," +
"<span style="background-color:#F8F8C8"><head><script src='" + jsURL + "'></script></head></span>" +
"<span style="background-color:#F8F8C8"><body onload=\"graphBars([" + llList2CSV(numbers) + "]);\"></body></span>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI, PRIM_MEDIA_AUTO_PLAY, TRUE]);
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
jsURL = body; // self-serve the JavaScript
llSetTimerEvent(1.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, externalJavascript());
}
}
} </tt>

Comments:
* Like the previous example, this is another variation of how to structure a data URI to serve as a springboard for arbitrarily large pages. In this example, the data URI first uses a <tt><script src=...></tt> tag to read a file of external JavaScript functions in the <tt><head></tt> element, and then the <tt>onload=</tt> attribute in <tt><body></tt> triggers a call to one of the functions which executes a loop creating a bunch of <tt><hr></tt> elements that form the bar chart. The size of HTML generated by the JavaScript can be as large as the browser permits.
* In this example, <tt>jsURL</tt> is set to the script's own HTTP-in URL so that the example can be self-contained, but you can point <tt>jsURL</tt> to an external URL as well. If served by an external server, the JavaScript read in <tt><head></tt> can be as large as the browser permits.
* <tt><head></head></tt> can be omitted in the data URI surrounding the <tt><script src=</tt> tag.

===Reverse Ajax — Long-polling the HTTP-in server (chat logger example)===
[[Image:MoaP-example-Long-polling-httpin.gif|thumb|300px|Long-polling HTTP-in]]
<tt>
// Reverse Ajax: Long-polling HTTP-in.
// Becky Pippen, 2010, contributed to the public domain.

integer face = 4; // Prim face for Shared Media

<span style="background-color:#F8F8C8">string myURL; // HTTP-in URL</span>
<span style="background-color:#F8F8C8">key inId = NULL_KEY; // GET request id</span>
<span style="background-color:#E0FDE0">list msgQueue = []; // strings of Javascript</span>

<span style="background-color:#F8F8C8">// url is our own HTTP-in url.
// This sets up a bootloader web page like this:
// <html><body>
// <div><script id='sc'></script></div>
// <script> callbacks and poll.beg() defined here </script>
// <button onclick=poll.beg()>Start</button>
// <div id='dv'></div>
// </body></html>
// When the button is pressed, the JS code sets src= on script#sc
// and reattaches the script element to the parent <div> element which
// initiates a GET to the prim's HTTP-in port
//
setDataURI(string url)
{
string dataURI = "data:text/html,
<!DOCTYPE HTML><html><body><div><script id='sc'></script></div><script>
var poll=function(){var sc=document.getElementById('sc'),t2,seq=0,s0;return{
beg:function(){s0=document.createElement('script');s0.onload=poll.end;t2=setTimeout('poll.end()',20000);
s0.src='" + url + "/?r='+(seq++);sc.parentNode.replaceChild(s0,sc);sc=s0;},
end:function(){clearTimeout(t2);t2=null;sc.onload=null;setTimeout('poll.beg()',500);},};}();</script>
<button id='btn'onclick=poll.beg()>Start</button><div id='dv'></div></body></html>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);</span>
}

<span style="background-color:#E0FDE0">// Returns zero or more queued messages. Assumes no single message is
// longer than MAX_SIZE_CHARS (will hang if there is)
//
string popQueuedMessages()
{
string totalMsg = "";
integer totalMsgSize = 0;
string nextMsg = "";
integer nextMsgSize = 0;

// HTTP response bodies are limited to 2048 bytes after encoding
// in UTF-8. LSL string sizes are measured in characters, which,
// in UTF-8, use one byte (for ASCII chars), two bytes (most Latin-1),
// or three bytes (a few international characters). So, unless
// you re-write this section so that it measures UTF-8 size, keep
// MAX_SIZE_CHARS small enough so the text will fit in a response body.
//
integer MAX_SIZE_CHARS = 1000; // Max HTTP body size

integer numMessagesQueued = llGetListLength(msgQueue);
integer count = 0;
while (count < numMessagesQueued) {
nextMsg = llList2String(msgQueue, count);
nextMsgSize = llStringLength(nextMsg);

if (totalMsgSize + nextMsgSize < MAX_SIZE_CHARS) {
totalMsg += nextMsg;
totalMsgSize += nextMsgSize;
++count;
}
}

// Delete the messages from the queue that we're going to send:
if (count > 0) {
msgQueue = llDeleteSubList(msgQueue, 0, count - 1);</span>
}

return totalMsg;
}

<span style="background-color:#E0FDE0">// Called when there are previous messages still queued, or if there
// is no GET request currently open to respond to.</span>
//
pushMessageToSend(string msg)
{
<span style="background-color:#E0FDE0">msgQueue = msgQueue + [msg]; // last element is the last one stacked</span>

// See if we can send some messages now:
<span style="background-color:#F8F8C8">if (inId != NULL_KEY) {</span>
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, popQueuedMessages());</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} // else wait for the next incoming GET request
}

// Replaces all occurrences of 'from' with 'to' in 'src'
// From http://snipplr.com/view/13279/lslstrreplace/
//
string str_replace(string subject, string search, string replace)
{
return llDumpList2String(llParseStringKeepNulls(subject, [search], []), replace);
}

// Optionally filter out characters in text that would mess up the
// web page display. This demo just escapes ' and " and adds a space after '<'.
//
string addSlashes(string s)
{
return str_replace(str_replace(str_replace(s, "<", "< "), "\"", "\\\""), "'", "\\\'");
}

// This is the main interface for LSL to control the Shared Media web page.
// The messages we send consist of Javascript function statements that the
// browser will evaluate and execute in the context of the web page.
// See sendMessageF() for a similar function with macro replacement.
//
sendMessage(string msg)
{
// Test for the easy case: if there are no other messages waiting
// in the queue, and if there is an open GET connection, then just
// respond immediately:

<span style="background-color:#E0FDE0">if (llGetListLength(msgQueue) == 0</span> && <span style="background-color:#F8F8C8">inId != NULL_KEY) {</span>
// Nothing in the queue and an open GET, so respond immediately:
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, msg);</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} <span style="background-color:#E0FDE0">else {</span>
<span style="background-color:#E0FDE0">pushMessageToSend(msg);</span>
}
}

// Same as sendMessage() but with macro replacements. For each nth string
// element in replacements, replace all occurrences of {@n}. For example,
// sendMessageF( "alert('{@0} {@1}!')", ["Hello", "World"] );
// will send "alert('Hello World!')" to the web browser.
//
sendMessageF(string msg, list replacements)
{
integer numrepl = llGetListLength(replacements);
integer i;
for (i = 0; i < numrepl; ++i) {
msg = str_replace(msg, "{@" + (string)i + "}", llList2String(replacements, i));
}

<span style="background-color:#F8F8C8">sendMessage(msg);</span>
}

<span style="background-color:#E8E8FF">// Chat logger demo: writes a new <tr> table row to the web page
// for every line of open chat it hears.
//
webAppInit()
{
string msg;
string m0;

// First, send over a few handy function definitions:

msg = "function $$(t) { return document.getElementsByTagName(t)[0]; };";
msg += "function h() { return $$('head'); };";
msg += "function b() { return $$('body'); };";
msg += "function e(id) { return document.getElementById(id); };";
sendMessage(msg);

// Send some CSS. WebKit is sensitive about appending <style> elements
// to <head>, so we'll append it to an existing <div> tag in <body> instead.

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<style>td:nth-child(2) { text-align:right } tr:nth-child(odd) { background-color:#f8e8f8 }</style>";
sendMessageF(msg, [m0]);

// Write a <table> element into element div#dv. The lines of chat will
// become rows in this table appended to tbody#tbd

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<table><tbody id='tbd'></tbody></table>";
sendMessageF(msg, [m0]);

llListen(0, "", NULL_KEY, "");</span>
}

default
{
state_entry()
{
llClearPrimMedia(face);
<span style="background-color:#F8F8C8"> llRequestURL();</span>

<span style="background-color:#E8E8FF"> webAppInit();</span>
}

<span style="background-color:#F8F8C8"> http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llOwnerSay("myURL=" + myURL);
setDataURI(myURL);
} else if (method == "GET") {
// Either send some queued messages now with llHTTPResponse(),
// or if there's nothing to do now, save the GET id and
// wait for somebody to call sendMessage().</span>
<span style="background-color:#E0FDE0"> if (llGetListLength(msgQueue) > 0) {</span>
<span style="background-color:#F8F8C8"> llHTTPResponse(id, 200, popQueuedMessages());
inId = NULL_KEY;
} else {
inId = id;
}
}
}</span>

<span style="background-color:#E8E8FF"> // When we hear chat from name, send a Javascript statement that
// appends HTML to element #tbd. I.e., we'll make a string of HTML
// formatted like this:
// <tr style="color:hsl(200,100%,30%)">
// <td>[01:23]</td>
// <td>Avatar Name</td>
// <td>the chat text</td>
// </tr>
// and send it wrapped it in a Javascript statement like this:
// e('tbd').innerHTML += htmlstring;
//
listen(integer chan, string name, key id, string chat)
{
integer s = (integer)("0x" + llGetSubString((string)id, 0, 6));
string hue = (string)(s % 360);
string color = "hsl(" + hue + ",100%, 30%)";

string msg = "e('tbd').innerHTML += '{@0}';";
string m0 = "<tr style=\"color: {@4}\">";
m0 += "<td>{@1}</td>";
m0 += "<td>{@2}:</td>";
m0 += "<td>{@3}</td>";
m0 += "</tr>";

string t = llGetSubString(llGetTimestamp(), 11, 15);
sendMessageF(msg, [m0, "[" + t + "]", name, addSlashes(chat), color]);
}</span>
}
</tt>

Comments:
<ol start="1">
<li>This "[http://en.wikipedia.org/wiki/Push_technology server-push]" technique using long-polling gives an LSL script the ability to modify the web page displayed on a prim. The Javascript side always keeps an HTTP GET open to the prim's HTTP-in URL, and the LSL side responds whenever it wants to with a response consisting of strings of Javascript to be executed by the web browser. For example, this LSL code causes an alert box to pop up on the web page:
: <code>sendMessage( "alert()" );</code></li>
<li>In the LSL listing above, <span style="background-color:#F8F8C8">the yellow highlighting</span> shows the most important parts of the HTTP long-polling mechanism. The <span style="background-color:#E0FDE0">green highlighting</span> shows the message buffering on top of that. The <span style="background-color:#E8E8FF">blue highlighting</span> is the application code that uses long-polling. To use long-polling for a different application, replace the blue parts. The rest is glue.</li>
<li>To avoid some subtle WebKit problems when dynamically appending or replacing the first-level child nodes in <head> or <body>, we've made two special <div> elements on the bootstrap HTML page. The first surrounds the script#sc element that we replace for each GET. The second is at the end of <body> as a convenient place for the application to insert new content that would otherwise go in <body>.</li>
<li>To make sure that there is nearly always a valid GET request open, the Javascript side starts a new GET after receiving a response, or when the last GET times out.</li>
<li>There are two timeouts hard-coded in the bootstrap data URI:
<ol style="list-style-type:lower-roman"><li>The "20000" is the timeout (20 seconds) for when an open GET expires, and should be set to something around the minimum of the WebKit outgoing GET request timeout, and the SL-LSL incoming GET timeout. This ensures that GETs are nearly continuous. [[LlHTTPResponse|This page]] says the timeout on the LSL side is 25 seconds.</li>
<li>The "500" is a throttle that sets an upper limit to how fast the Javascript re-polls HTTP-in to prevent hammering the simulator. It's a half-second delay after receiving a GET response before starting a new GET.</li></ol>
<li> If there's a little gap between two GETs, or if two overlap a little, the sendMessage() message buffering will compensate by queuing up messages to be sent when the next GET arrives. If there are multiple messages in the queue when a GET arrives, the LSL side will concatenate as many messages as possible and send them together.
</li>
<li>On the Javascript side, the GET is not triggered until the <tt><script></tt> element is attached to its parent node with .appendChild() or .replaceChild().</li>
<li>The bootstrap Javascript above in setDataURI() had to be compressed somewhat to fit into the 1024-byte data URI limit. Here's an expanded listing for reference with more descriptive names:</li>
<tt>
<!DOCTYPE HTML>
<html>
<body>
<div>
<script id='script'> </script>
</div>
<script>
var poll=function(){
var script=document.getElementById('script'),
timeoutId,
seq=0,
newScript;
return {
beg:function(){ // Initiate a long-poll GET
newScript=document.createElement('script'); // The response will go here
newScript.onload=poll.end; // Call poll.end() when we get a response
timeoutId=setTimeout('poll.end()',20000); // ... or if we time out
newScript.src=' HTTP-in URL goes here /?r='+(seq++);
script.parentNode.replaceChild(newScript,script); // this triggers the GET
script=newScript;},

end:function(){
clearTimeout(timeoutId);
timeoutId=null;
script.onload=null;
setTimeout('poll.beg()',500); // Wait a bit before re-polling
},
};
}();
</script>
<button id='btn'onclick=poll.beg()>Start<button>
<div id='dv'> </div>
</body>
</html>
</tt>
</ol>

===Make TinyURLs by script===
<tt>
string myTinyURL;

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
// Send our full URL to tinyurl.com for conversion
// The answer will come back in http_response()
<span style="background-color:#F8F8C8">llHTTPRequest("http://tinyurl.com/api-create.php?url=" + body, [], "");</span>
} else if (method == "GET") {
llHTTPResponse(id, 200, "Hello Real World from the Virtual World");
}
}

http_response(key req, integer stat, list met, string body)
{
<span style="background-color:#F8F8C8">myTinyURL = body;</span>
llOwnerSay("My HTTP-in TinyURL is: " + myTinyURL + " , Click Me!");
}
} </tt>

Comments:
* Any URL or data URI can be mapped to a TinyURL. The example above reduces an assigned HTTP-in URL, which is a long one such as:
<nowiki>http://sim4605.agni.lindenlab.com:12046/cap/2b9f06f7-431e-5b0f-9271-2d03bd15370b</nowiki>
into a TinyURL this size:
<nowiki>http://tinyurl.com/y9etul3</nowiki>

===Development hints===
# You can develop your HTML and JavaScript outside of Second Life by putting your JavaScript incantations in data URIs that you feed to any web browser. For the most compatible browsers, use Safari or Google Chrome, or any other that uses the [[QtWebKit|WebKit]] HTML rendering engine. If you can't run Safari or Chrome, try the open source [http://code.google.com/p/arora/ Arora web browser] for simulating Media-on-a-Prim: it's based on straight-up WebKit and has the same handy inspector/debugger found in other WebKit browsers.
# If you don't have direct access to a web server while developing this stuff, then consider installing a local copy of [http://www.apache.org/ Apache web server] on your computer. You can restrict it to local access. Then you can refer to files on your own computer with URLs that start with <tt><nowiki>http://localhost/</nowiki>...</tt>, and PHP scripts can simulate what the HTTP-in server would serve. That lets you, for example, edit <tt>myfile.js</tt> on your own computer while working on a data URI that contains <tt><script src="<nowiki>http://localhost/myfile.js</nowiki>"></tt>. Then when <tt>myfile.js</tt> is working, you can put the debugged code into an LSL script that will serve it through its HTTP-in port. That's easier than debugging all that in-world.

===References and sources===
* [[User:Kelly_Linden/lsl_hacks|Kelly Linden's hacks]]
* [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim Tali Rosca's techniques]
* [https://blogs.secondlife.com/message/115303 Notecard Text on a Prim - Demo]
* [[llSetPrimMediaParams]]()
* {{JIRA|SVC-3427}}
* [https://blogs.secondlife.com/message/124144 Ajax in Shared Media #1]
* [https://blogs.secondlife.com/thread/11698 Ajax in Shared Media #2]
* [https://blogs.secondlife.com/thread/12727 Ajax in Shared Media #3]
* [https://blogs.secondlife.com/thread/13455 SVG (Scalable Vector Graphics) in Shared Media]
* [[Shared_Media_and_data_URI|Shared_Media_and_data_URI]]
* [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/17/viewer-2-tip-shared-media-add-custom-content-with-data-uri-no-webpage-upload-needed Shared Media: Add custom content with data: URI]
* [https://blogs.secondlife.com/message/119704 "Shared Media" - A few facts]

[[Category:Shared Media]]

User:Becky Pippen/Shared Media LSL Recipes

2010-04-23T06:09:55Z

Becky Pippen: Added recipe for Reverse Ajax: Long-polling HTTP-in (chat logger example)

==How-to's with Media-on-a-Prim==



The examples here assume you're comfortable with LSL, and you just need a quick reference for the syntax of handling HTML and JavaScript in LSL for Shared Media scripting. All the examples on this page are ready to copy-n-paste and drop into a prim — no other setup needed. The key syntax in each example is highlighted. There's no error handling in these minimalist examples, so add plenty of your own.

===Display plain text — XyText replacement===
[[Image:MoaP-example_1.png‎|thumb|Plain text]]
<tt>
default
{
state_entry()
{
<span style="background-color:#F8F8C8">integer face = 4;</span>
<span style="background-color:#F8F8C8">string message = "Hello World";</span>
<span style="background-color:#F8F8C8">llSetPrimMediaParams(face,</span>
<span style="background-color:#F8F8C8">[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message]);</span>
}
} </tt>

Comments:
* An avatar must press the Reload button on the browser to see this rendered in-world. A page will be auto-loaded if you include the parameter <tt>PRIM_MEDIA_AUTO_PLAY, TRUE</tt>, and if the avatar has auto-load enabled in preferences.
* There's no need to add any %-hex-escaping or to use [[llEscapeURL]](); llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, url]) will automatically escape the string for you.
* This works by feeding a data URI to the on-prim browser. Think of it as serving the contents of the page in the URL itself. For more information, see [[Shared_Media_and_data_URI|here]] and [http://en.wikipedia.org/wiki/Data_URI_scheme here].
* The in-world browser limits the data URI (or any address) to 1024 bytes after %-hex-escaping and encoded in UTF-8. See below for tricks using external or self-served JavaScript or CSS to leverage the data URI.
* If the data URI contains just plain text, the prefix <tt>"data:text/html,"</tt> can be abbreviated <tt>"data:,"</tt>.

===Force a page reload===
<tt>
[[Image:MoaP-example-refreshpage.gif|thumb|Auto-refresh]]
integer face = 4;
string myURL;
<span style="background-color:#F8F8C8">integer seq = 0; // sequence number for unique URLs</span>

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llSetPrimMediaParams(face,
[PRIM_MEDIA_AUTO_PLAY, TRUE,
PRIM_MEDIA_CURRENT_URL, myURL]);
llSetTimerEvent(5.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, "Sim FPS: " + (string)llGetRegionFPS());
}
}

timer()
{
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, myURL + "/?r=" + (string)(++seq)</span>]);
}
} </tt>
Comments:
* The page will reload automatically if <tt>PRIM_MEDIA_AUTO_PLAY</tt> is enabled and if the new <tt>PRIM_MEDIA_CURRENT_URL</tt> is different. This technique appends a short dummy parameter (like <tt>"/?r=12"</tt>) to the end of the URL to make it different each time, forcing a reload. The parameter is otherwise ignored.

===Display text with HTML markup===
[[Image:MoaP-example-markup.png‎‎|thumb|HTML markup]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = <span style="background-color:#F8F8C8">"<i>Hello</i><h2>World!</h2>"</span>;
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* The text of the data URI will be %-hex-escaped automatically for you, so there's no need to use [[llEscapeURL]](). All you need in the data URI is the prefix <tt>data:text/html,</tt> plus your HTML.

===Change window resolution===
[[Image:MoaP-example-size.png‎|thumb|Resized web window]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "Hello World";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, "data:text/html," + message,
<span style="background-color:#F8F8C8">PRIM_MEDIA_WIDTH_PIXELS, 128</span>,
<span style="background-color:#F8F8C8">PRIM_MEDIA_HEIGHT_PIXELS, 32</span>]);
}
} </tt>

Comments:
* The browser will add scroll bars if the rendered HTML doesn't fit within the specified PRIM_MEDIA_* size.

===Display an image — works with animated GIFs too===
[[Image:MoaP-example-animgif.gif‎|thumb|Image on a prim]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://upload.wikimedia.org/wikipedia/commons/7/70/Rotating_earth_(small).gif";
<span style="background-color:#F8F8C8">string dataURI = "data:text/html,<object data='" + imageURL + "'></object>";</span>
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI,
PRIM_MEDIA_WIDTH_PIXELS, 256,
PRIM_MEDIA_HEIGHT_PIXELS, 256]);
}
} </tt>

Comments:
* If attempting to display YouTube video full-frame, see [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/16/viewer-2-tip-shared-media-show-youtube-on-a-full-prims-face this discussion].
* For images, you can also use <tt><image src= ></tt> like this:
string dataURI="data:text/html,<img src='" + imageURL + "'>";

===Display a background image, tiled===

====Method #1 — using CSS in a style element in <head>====
[[Image:MoaP-example-bgTiled.png‎|thumb|Tiled background image]]
<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL =
"http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "data:text/html,<head>"
+ "<span style="background-color:#F8F8C8"><style type='text/css'>body{background-image:url(\"</span>"
+ <span style="background-color:#F8F8C8">imageURL + "\");}</style></span></head><body>Hello World</body>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #2 — using background attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body background='" + imageURL + "'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

====Method #3 — using style attribute in <body>====

<tt>
default
{
state_entry()
{
integer face = 4;
string imageURL = "http://www.google.com/intl/en_ALL/images/logo.gif";
string dataURI = "<span style="background-color:#F8F8C8">data:text/html,<body style='background-image:url(\"" + imageURL + "\")'></span>"
+ "<span style="background-color:#F8F8C8">Hello World</span>"
+ "<span style="background-color:#F8F8C8"></body></span>";
llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

===Text colors — using <font> element===
[[Image:MoaP-example-font-color.png‎|thumb|Font color]]
<tt>
default
{
state_entry()
{
integer face = 4;
string message = "<span style="background-color:#F8F8C8"><font color='Red'>Hello World</font></span>";
llSetPrimMediaParams(face,
[<span style="background-color:#F8F8C8">PRIM_MEDIA_CURRENT_URL, "data:text/html," + message</span>]);
}
} </tt>

Comments:
* You can also specify color and other CSS rules in a style attribute in another element. For example, you can replace message in the example above with:

string message = "<h2 style='color:#FF0000'>Hello World</h2>";

===Link to external CSS file (forms example)===
[[Image:MoaP-example-externalCSS.png‎|thumb|External CSS file]]
<tt>
default
{
state_entry()
{
integer face = 4;
<span style="background-color:#F8F8C8">string externalCSS =</span>
<span style="background-color:#F8F8C8">"http://www.google.com/css/modules/buttons/g-button-chocobo.css";</span>

string dataURI = "data:text/html,<head><span style="background-color:#F8F8C8"><link href='</span>" +
<span style="background-color:#F8F8C8">externalCSS + "' rel='stylesheet' type='text/css' /></span></head>" +
"<form><input type='button' value='Click Me' class='g-button' /></form>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is one way to work around the 1024-byte limitation of data URIs. The external CSS can be as large as the browser permits. Also see the examples below for putting JavaScript in an external file.
* The tag <tt><head></tt> and the attribute <tt>type='text/css'</tt> may be omitted to make the data URI a few bytes shorter.

===Calling external JavaScript functions (JQuery example)===
[[Image:MoaP-example-JQuery.gif‎|thumb|Calling external JQuery]]
<tt>
integer face = 4;
string externalJavascript =
"http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js";
default
{
state_entry()
{
string dataURI = "data:text/html," +
"<head><span style="background-color:#F8F8C8"><script src='" + externalJavascript + "'></script></span></head>" +
"<button>Toggle</button>" +
"<p>Hello<br />World</p>" +
"<span style="background-color:#F8F8C8"><script>$('button').click(function () </span>" +
"<span style="background-color:#F8F8C8">{$('p').slideToggle('slow');});</script></span>";

llSetPrimMediaParams(face,
[PRIM_MEDIA_CURRENT_URL, dataURI]);
}
} </tt>

Comments:
* This is a technique for working around the 1024-byte limit for data URIs. When you can't fit all the JavaScript you need into one data URI, just move some JavaScript functions into an external file and give the browser a data URI that references the external file with a URL. In this example above, the JavaScript for [http://jquery.com/ JQuery] lives in an external file on Google's servers. You just need enough bytes left over in the data URI to put a JavaScript function call with its parameters inside a <tt><script></tt> element.
* A data URI can be used as a springboard to generate arbitrary complex web pages by making use of these elements:
** a reference to external CSS with <tt><link href= </tt>,
** a reference to external JavaScript with <tt><script src=</tt>, and
** a function call with parameters to the external JavaScript using <tt><script>someFunction(args);</script></tt>. (In the JQuery example above, the name of the external function is <tt>"$"</tt>.)
* See the next two examples for variations of this same technique.

===Self-served HTML and JavaScript===
====Example #1 — using <script src= and .innerHTML= ====
[[Image:MoaP-example-refresh-clock.gif‎|thumb|Self-served auto-refreshed pages]]
<tt>
integer face = 4;
string myURL;

// This can be up to 2KBytes after %-hex-escaping:
<span style="background-color:#F8F8C8">string servedPage =</span> "
function checklength(i){if (i<10) {i='0'+i;} return i;}
<span style="background-color:#F8F8C8">function clock()</span>{
var now = new Date();
var hours = checklength(now.getHours());
var minutes = checklength(now.getMinutes());
var seconds = checklength(now.getSeconds());
var format = 1; //0=24 hour format, 1=12 hour format
var time;
if (format == 1) {
if (hours >= 12) {
if (hours ==12 ) { hours = 12;
} else { hours = hours-12; }
time=hours+':'+minutes+':'+seconds+' PM';
} else if(hours < 12) {
if (hours ==0) {hours=12;}
time=hours+':'+minutes+':'+seconds+' AM';
}
}
if (format == 0) {time= hours+':'+minutes+':'+seconds;}
<span style="background-color:#F8F8C8">document.getElementById('clock').innerHTML=time;</span>
setTimeout('clock();', 500);
} "; // yes, that's one long string.

displayPage()
{
string dataURI = "data:text/html,<span style="background-color:#F8F8C8"><script src='</span>" +
<span style="background-color:#F8F8C8">myURL + "'></script></span>" +
"<span style="background-color:#F8F8C8"><div id='clock'><script>clock();</script></div></span>";
llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);
}

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
<span style="background-color:#F8F8C8">myURL = body;</span>
displayPage();
} else if (method == "GET") {
<span style="background-color:#F8F8C8">llHTTPResponse(id, 200, servedPage);</span>
}
}
} </tt>

Comments:
* This is a technique for trading the 1024-byte limit of data URIs for the 2048-byte-per-page limit that the script can serve itself. As in the previous example, when you can't fit all the JavaScript into one data URI, just move the JavaScript into an external file and reference the file with <tt><script src=URL></script></tt>. When the URL refers to the script's own HTTP-in URL, then the page served can contain up to 2K bytes, so you get at least that many bytes plus whatever logic you can fit into the rest of the data URI. If you move that JavaScript to an external web server, the size of the external JavaScript file can be as large as the client web browser can render.
* Your script can serve an arbitrary number of different pages through one HTTP-in URL by appending a path or parameter to the URL.
* This works by assigning a string containing HTML to the <tt>.innerHTML</tt> contents of the <tt><div></tt> element with id "clock". This achieves something similar to the Ajax-like [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim technique published by Tali Rosca] and mentioned [http://wiki.secondlife.com/wiki/User:Kelly_Linden/lsl_hacks#DHTML_.2F_Javascript_.28Tali_Rosca.29 here]. In those techniques, a string is constructed containing an <tt><a href=</tt> tag and an <tt>href=</tt> that points to the script's HTTP-in URL. That string then replaces the <tt><body></tt> element using:
<tt>document.getElementsByTagName('body')[0].innerHTML = <i>new-content</i></tt>

====Example #2 — using <body onload= (lag graph example)====
[[Image:MoaP-example-laggraph.gif‎|thumb|Refreshed pages]]
<tt>
integer face = 4;
string jsURL; // where to fetch external JavaScript
list numbers;
integer numSamples = 50;

// This is self-served in this example, but can be
// moved to an external server:
//
string externalJavascript()
{
return
"function bar(widthPct,heightPix) {" +
" document.writeln(\"<hr style='padding:0;margin:0;" +
" margin-top:-1px;text-align:left;align:left;border=0;" +
" width:\"+widthPct+\"%;height:\"+heightPix+\"px;" +
" background-color:#c22;color:#c22;'>\");}" +
" function graphBars(arr){for(var i=0;i<arr.length;++i)" +
" {bar(arr[i],18);}}";
}

default
{
state_entry()
{
llClearPrimMedia(face);
llRequestURL();
integer i = numSamples;
while (--i >= 0) {
numbers += 0;
}
}

timer()
{
numbers = llList2List(numbers, 1, -1) + [(integer)(6.0 * (45.0 - llGetRegionFPS()))];

// The dataURI loads external JavaScript functions and calls one with parameters:

string dataURI = "data:text/html," +
"<span style="background-color:#F8F8C8"><head><script src='" + jsURL + "'></script></head></span>" +
"<span style="background-color:#F8F8C8"><body onload=\"graphBars([" + llList2CSV(numbers) + "]);\"></body></span>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI, PRIM_MEDIA_AUTO_PLAY, TRUE]);
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
jsURL = body; // self-serve the JavaScript
llSetTimerEvent(1.0);
} else if (method == "GET") {
llHTTPResponse(id, 200, externalJavascript());
}
}
} </tt>

Comments:
* Like the previous example, this is another variation of how to structure a data URI to serve as a springboard for arbitrarily large pages. In this example, the data URI first uses a <tt><script src=...></tt> tag to read a file of external JavaScript functions in the <tt><head></tt> element, and then the <tt>onload=</tt> attribute in <tt><body></tt> triggers a call to one of the functions which executes a loop creating a bunch of <tt><hr></tt> elements that form the bar chart. The size of HTML generated by the JavaScript can be as large as the browser permits.
* In this example, <tt>jsURL</tt> is set to the script's own HTTP-in URL so that the example can be self-contained, but you can point <tt>jsURL</tt> to an external URL as well. If served by an external server, the JavaScript read in <tt><head></tt> can be as large as the browser permits.
* <tt><head></head></tt> can be omitted in the data URI surrounding the <tt><script src=</tt> tag.

===Reverse Ajax — Long-polling the HTTP-in server (chat logger example)===
[[Image:MoaP-example-Long-polling-httpin.gif|thumb|300px|Long-polling HTTP-in]]
<tt>
// Reverse Ajax: Long-polling HTTP-in.
// Becky Pippen, 2010, contributed to the public domain.
// http://wiki.secondlife.com/wiki/User:Becky_Pippen/MoaP_Snippets

integer face = 4; // Prim face for Shared Media

<span style="background-color:#F8F8C8">string myURL; // HTTP-in URL</span>
<span style="background-color:#F8F8C8">key inId = NULL_KEY; // GET request id</span>
<span style="background-color:#E0FDE0">list msgQueue = []; // strings of Javascript</span>

<span style="background-color:#F8F8C8">// url is our own HTTP-in url.
// This sets up a bootloader web page like this:
// <html><body>
// <div><script id='sc'></script></div>
// <script> callbacks and poll.beg() defined here </script>
// <button onclick=poll.beg()>Start</button>
// <div id='dv'></div>
// </body></html>
// When the button is pressed, the JS code sets src= on script#sc
// and reattaches the script element to the parent <div> element which
// initiates a GET to the prim's HTTP-in port
//
setDataURI(string url)
{
string dataURI = "data:text/html,
<!DOCTYPE HTML><html><body><div><script id='sc'></script></div><script>
var poll=function(){var sc=document.getElementById('sc'),t2,seq=0,s0;return{
beg:function(){s0=document.createElement('script');s0.onload=poll.end;t2=setTimeout('poll.end()',20000);
s0.src='" + url + "/?r='+(seq++);sc.parentNode.replaceChild(s0,sc);sc=s0;},
end:function(){clearTimeout(t2);t2=null;sc.onload=null;setTimeout('poll.beg()',500);},};}();</script>
<button id='btn'onclick=poll.beg()>Start</button><div id='dv'></div></body></html>";

llSetPrimMediaParams(face, [PRIM_MEDIA_CURRENT_URL, dataURI]);</span>
}

<span style="background-color:#E0FDE0">// Returns zero or more queued messages. Assumes no single message is
// longer than MAX_SIZE_CHARS (will hang if there is)
//
string popQueuedMessages()
{
string totalMsg = "";
integer totalMsgSize = 0;
string nextMsg = "";
integer nextMsgSize = 0;

// HTTP response bodies are limited to 2048 bytes after encoding
// in UTF-8. LSL string sizes are measured in characters, which,
// in UTF-8, use one byte (for ASCII chars), two bytes (most Latin-1),
// or three bytes (a few international characters). So, unless
// you re-write this section so that it measures UTF-8 size, keep
// MAX_SIZE_CHARS small enough so the text will fit in a response body.
//
integer MAX_SIZE_CHARS = 1000; // Max HTTP body size

integer numMessagesQueued = llGetListLength(msgQueue);
integer count = 0;
while (count < numMessagesQueued) {
nextMsg = llList2String(msgQueue, count);
nextMsgSize = llStringLength(nextMsg);

if (totalMsgSize + nextMsgSize < MAX_SIZE_CHARS) {
totalMsg += nextMsg;
totalMsgSize += nextMsgSize;
++count;
}
}

// Delete the messages from the queue that we're going to send:
if (count > 0) {
msgQueue = llDeleteSubList(msgQueue, 0, count - 1);</span>
}

return totalMsg;
}

<span style="background-color:#E0FDE0">// Called when there are previous messages still queued, or if there
// is no GET request currently open to respond to.</span>
//
pushMessageToSend(string msg)
{
<span style="background-color:#E0FDE0">msgQueue = msgQueue + [msg]; // last element is the last one stacked</span>

// See if we can send some messages now:
<span style="background-color:#F8F8C8">if (inId != NULL_KEY) {</span>
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, popQueuedMessages());</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} // else wait for the next incoming GET request
}

// Replaces all occurrences of 'from' with 'to' in 'src'
// From http://snipplr.com/view/13279/lslstrreplace/
//
string str_replace(string subject, string search, string replace)
{
return llDumpList2String(llParseStringKeepNulls(subject, [search], []), replace);
}

// Optionally filter out characters in text that would mess up the
// web page display. This demo just escapes ' and " and adds a space after '<'.
//
string addSlashes(string s)
{
return str_replace(str_replace(str_replace(s, "<", "< "), "\"", "\\\""), "'", "\\\'");
}

// This is the main interface for LSL to control the Shared Media web page.
// The messages we send consist of Javascript function statements that the
// browser will evaluate and execute in the context of the web page.
// See sendMessageF() for a similar function with macro replacement.
//
sendMessage(string msg)
{
// Test for the easy case: if there are no other messages waiting
// in the queue, and if there is an open GET connection, then just
// respond immediately:

<span style="background-color:#E0FDE0">if (llGetListLength(msgQueue) == 0</span> && <span style="background-color:#F8F8C8">inId != NULL_KEY) {</span>
// Nothing in the queue and an open GET, so respond immediately:
<span style="background-color:#F8F8C8">llHTTPResponse(inId, 200, msg);</span>
<span style="background-color:#F8F8C8">inId = NULL_KEY;</span>
} <span style="background-color:#E0FDE0">else {</span>
<span style="background-color:#E0FDE0">pushMessageToSend(msg);</span>
}
}

// Same as sendMessage() but with macro replacements. For each nth string
// element in replacements, replace all occurrences of {@n}. For example,
// sendMessageF( "alert('{@0} {@1}!')", ["Hello", "World"] );
// will send "alert('Hello World!')" to the web browser.
//
sendMessageF(string msg, list replacements)
{
integer numrepl = llGetListLength(replacements);
integer i;
for (i = 0; i < numrepl; ++i) {
msg = str_replace(msg, "{@" + (string)i + "}", llList2String(replacements, i));
}

<span style="background-color:#F8F8C8">sendMessage(msg);</span>
}

<span style="background-color:#E8E8FF">// Chat logger demo: writes a new <tr> table row to the web page
// for every line of open chat it hears.
//
webAppInit()
{
string msg;
string m0;

// First, send over a few handy function definitions:

msg = "function $$(t) { return document.getElementsByTagName(t)[0]; };";
msg += "function h() { return $$('head'); };";
msg += "function b() { return $$('body'); };";
msg += "function e(id) { return document.getElementById(id); };";
sendMessage(msg);

// Send some CSS. WebKit is sensitive about appending <style> elements
// to <head>, so we'll append it to an existing <div> tag in <body> instead.

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<style>td:nth-child(2) { text-align:right } tr:nth-child(odd) { background-color:#f8e8f8 }</style>";
sendMessageF(msg, [m0]);

// Write a <table> element into element div#dv. The lines of chat will
// become rows in this table appended to tbody#tbd

msg = "e('dv').innerHTML += \"{@0}\";";
m0 = "<table><tbody id='tbd'></tbody></table>";
sendMessageF(msg, [m0]);

llListen(0, "", NULL_KEY, "");</span>
}

default
{
state_entry()
{
llClearPrimMedia(face);
<span style="background-color:#F8F8C8"> llRequestURL();</span>

<span style="background-color:#E8E8FF"> webAppInit();</span>
}

<span style="background-color:#F8F8C8"> http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
myURL = body;
llOwnerSay("myURL=" + myURL);
setDataURI(myURL);
} else if (method == "GET") {
// Either send some queued messages now with llHTTPResponse(),
// or if there's nothing to do now, save the GET id and
// wait for somebody to call sendMessage().</span>
<span style="background-color:#E0FDE0"> if (llGetListLength(msgQueue) > 0) {</span>
<span style="background-color:#F8F8C8"> llHTTPResponse(id, 200, popQueuedMessages());
inId = NULL_KEY;
} else {
inId = id;
}
}
}</span>

<span style="background-color:#E8E8FF"> // When we hear chat from name, send a Javascript statement that
// appends HTML to element #tbd. I.e., we'll make a string of HTML
// formatted like this:
// <tr style="color:hsl(200,100%,30%)">
// <td>[01:23]</td>
// <td>Avatar Name</td>
// <td>the chat text</td>
// </tr>
// and send it wrapped it in a Javascript statement like this:
// e('tbd').innerHTML += htmlstring;
//
listen(integer chan, string name, key id, string chat)
{
integer s = (integer)("0x" + llGetSubString((string)id, 0, 6));
string hue = (string)(s % 360);
string color = "hsl(" + hue + ",100%, 30%)";

string msg = "e('tbd').innerHTML += '{@0}';";
string m0 = "<tr style=\"color: {@4}\">";
m0 += "<td>{@1}</td>";
m0 += "<td>{@2}:</td>";
m0 += "<td>{@3}</td>";
m0 += "</tr>";

string t = llGetSubString(llGetTimestamp(), 11, 15);
sendMessageF(msg, [m0, "[" + t + "]", name, addSlashes(chat), color]);
}</span>
}
</tt>

Comments:
<ol start="1">
<li>This "[http://en.wikipedia.org/wiki/Push_technology server-push]" technique using long-polling gives an LSL script the ability to modify the web page displayed on a prim. The Javascript side always keeps an HTTP GET open to the prim's HTTP-in URL, and the LSL side responds whenever it wants to with a response consisting of strings of Javascript to be executed by the web browser. For example, this LSL code causes an alert box to pop up on the web page:
: <code>sendMessage( "alert()" );</code></li>
<li>In the LSL listing above, <span style="background-color:#F8F8C8">the yellow highlighting</span> shows the most important parts of the HTTP long-polling mechanism. The <span style="background-color:#E0FDE0">green highlighting</span> shows the message buffering on top of that. The <span style="background-color:#E8E8FF">blue highlighting</span> is the application code that uses long-polling. To use long-polling for a different application, replace the blue parts. The rest is glue.</li>
<li>To avoid some subtle WebKit problems when dynamically appending or replacing the first-level child nodes in <head> or <body>, we've made two special <div> elements on the bootstrap HTML page. The first surrounds the script#sc element that we replace for each GET. The second is at the end of <body> as a convenient place for the application to insert new content that would otherwise go in <body>.</li>
<li>To make sure that there is nearly always a valid GET request open, the Javascript side starts a new GET after receiving a response, or when the last GET times out.</li>
<li>There are two timeouts hard-coded in the bootstrap data URI:
<ol style="list-style-type:lower-roman"><li>The "20000" is the timeout (20 seconds) for when an open GET expires, and should be set to something around the minimum of the WebKit outgoing GET request timeout, and the SL-LSL incoming GET timeout. This ensures that GETs are nearly continuous. [[LlHTTPResponse|This page]] says the timeout on the LSL side is 25 seconds.</li>
<li>The "500" is a throttle that sets an upper limit to how fast the Javascript re-polls HTTP-in to prevent hammering the simulator. It's a half-second delay after receiving a GET response before starting a new GET.</li></ol>
<li> If there's a little gap between two GETs, or if two overlap a little, the sendMessage() message buffering will compensate by queuing up messages to be sent when the next GET arrives. If there are multiple messages in the queue when a GET arrives, the LSL side will concatenate as many messages as possible and send them together.
</li>
<li>On the Javascript side, the GET is not triggered until the <tt><script></tt> element is attached to its parent node with .appendChild() or .replaceChild().</li>
<li>The bootstrap Javascript above in setDataURI() had to be compressed somewhat to fit into the 1024-byte data URI limit. Here's an expanded listing for reference with more descriptive names:</li>
<tt>
<!DOCTYPE HTML>
<html>
<body>
<div>
<script id='script'> </script>
</div>
<script>
var poll=function(){
var script=document.getElementById('script'),
timeoutId,
seq=0,
newScript;
return {
beg:function(){ // Initiate a long-poll GET
newScript=document.createElement('script'); // The response will go here
newScript.onload=poll.end; // Call poll.end() when we get a response
timeoutId=setTimeout('poll.end()',20000); // ... or if we time out
newScript.src=' HTTP-in URL goes here /?r='+(seq++);
script.parentNode.replaceChild(newScript,script); // this triggers the GET
script=newScript;},

end:function(){
clearTimeout(timeoutId);
timeoutId=null;
script.onload=null;
setTimeout('poll.beg()',500); // Wait a bit before re-polling
},
};
}();
</script>
<button id='btn'onclick=poll.beg()>Start<button>
<div id='dv'> </div>
</body>
</html>
</tt>
</ol>

===Make TinyURLs by script===
<tt>
string myTinyURL;

default
{
state_entry()
{
llRequestURL();
}

http_request(key id, string method, string body)
{
if (method == URL_REQUEST_GRANTED) {
// Send our full URL to tinyurl.com for conversion
// The answer will come back in http_response()
<span style="background-color:#F8F8C8">llHTTPRequest("http://tinyurl.com/api-create.php?url=" + body, [], "");</span>
} else if (method == "GET") {
llHTTPResponse(id, 200, "Hello Real World from the Virtual World");
}
}

http_response(key req, integer stat, list met, string body)
{
<span style="background-color:#F8F8C8">myTinyURL = body;</span>
llOwnerSay("My HTTP-in TinyURL is: " + myTinyURL + " , Click Me!");
}
} </tt>

Comments:
* Any URL or data URI can be mapped to a TinyURL. The example above reduces an assigned HTTP-in URL, which is a long one such as:
<nowiki>http://sim4605.agni.lindenlab.com:12046/cap/2b9f06f7-431e-5b0f-9271-2d03bd15370b</nowiki>
into a TinyURL this size:
<nowiki>http://tinyurl.com/y9etul3</nowiki>

===Development hints===
# You can develop your HTML and JavaScript outside of Second Life by putting your JavaScript incantations in data URIs that you feed to any web browser. For the most compatible browsers, use Safari or Google Chrome, or any other that uses the [[QtWebKit|WebKit]] HTML rendering engine. If you can't run Safari or Chrome, try the open source [http://code.google.com/p/arora/ Arora web browser] for simulating Media-on-a-Prim: it's based on straight-up WebKit and has the same handy inspector/debugger found in other WebKit browsers.
# If you don't have direct access to a web server while developing this stuff, then consider installing a local copy of [http://www.apache.org/ Apache web server] on your computer. You can restrict it to local access. Then you can refer to files on your own computer with URLs that start with <tt><nowiki>http://localhost/</nowiki>...</tt>, and PHP scripts can simulate what the HTTP-in server would serve. That lets you, for example, edit <tt>myfile.js</tt> on your own computer while working on a data URI that contains <tt><script src="<nowiki>http://localhost/myfile.js</nowiki>"></tt>. Then when <tt>myfile.js</tt> is working, you can put the debugged code into an LSL script that will serve it through its HTTP-in port. That's easier than debugging all that in-world.

===References and sources===
* [[User:Kelly_Linden/lsl_hacks|Kelly Linden's hacks]]
* [http://talirosca.wikidot.com/bootstrapping-html-on-a-prim Tali Rosca's techniques]
* [https://blogs.secondlife.com/message/115303 Notecard Text on a Prim - Demo]
* [[llSetPrimMediaParams]]()
* {{JIRA|SVC-3427}}
* [https://blogs.secondlife.com/message/124144 Ajax in Shared Media #1]
* [https://blogs.secondlife.com/thread/11698 Ajax in Shared Media #2]
* [https://blogs.secondlife.com/thread/12727 Ajax in Shared Media #3]
* [https://blogs.secondlife.com/thread/13455 SVG (Scalable Vector Graphics) in Shared Media]
* [[Shared_Media_and_data_URI|Shared_Media_and_data_URI]]
* [https://blogs.secondlife.com/community/community/tnt/blog/2010/03/17/viewer-2-tip-shared-media-add-custom-content-with-data-uri-no-webpage-upload-needed Shared Media: Add custom content with data: URI]
* [https://blogs.secondlife.com/message/119704 "Shared Media" - A few facts]

[[Category:Shared Media]]

File:MoaP-example-Long-polling-httpin.gif

2010-04-23T06:02:07Z

Becky Pippen: Media-on-a-Prim example of Long-polling the prim's own HTTP server

Media-on-a-Prim example of Long-polling the prim's own HTTP server

User:Becky Pippen

2010-03-22T23:01:58Z

Becky Pippen: Add link to User:Becky_Pippen/Shared_Media_LSL_Recipes

User:Becky Pippen/Shared Media LSL Recipes

2010-03-22T22:54:31Z

Becky Pippen: Shared Media LSL Recipes

File:MoaP-example 1.png

2010-03-22T22:53:26Z

Becky Pippen: Media-on-a-Prim example of plain text

Media-on-a-Prim example of plain text

File:MoaP-example-refreshpage.gif

2010-03-22T22:47:18Z

Becky Pippen: Media-on-a-Prim example of auto page reload

Media-on-a-Prim example of auto page reload

File:MoaP-example-markup.png

2010-03-22T22:46:30Z

Becky Pippen: Media-on-a-Prim example of HTML markup

Media-on-a-Prim example of HTML markup

File:MoaP-example-size.png

2010-03-22T22:45:37Z

Becky Pippen: Media-on-a-Prim example of scroll bars

Media-on-a-Prim example of scroll bars

File:MoaP-example-animgif.gif

2010-03-22T22:23:49Z

Becky Pippen: Media-on-a-Prim example of animated GIF on a prim face

Media-on-a-Prim example of animated GIF on a prim face

File:MoaP-example-bgTiled.png

2010-03-22T22:21:00Z

Becky Pippen: Media-on-a-Prim example of tiled background image

Media-on-a-Prim example of tiled background image

File:MoaP-example-font-color.png

2010-03-22T22:17:52Z

Becky Pippen: Media-on-a-Prim example of font color

Media-on-a-Prim example of font color

File:MoaP-example-externalCSS.png

2010-03-22T22:17:16Z

Becky Pippen: Media-on-a-Prim example of referring to external CSS

Media-on-a-Prim example of referring to external CSS

File:MoaP-example-JQuery.gif

2010-03-22T22:16:04Z

Becky Pippen: Media-on-a-Prim example of calling external JQuery function

Media-on-a-Prim example of calling external JQuery function

File:MoaP-example-refresh-clock.gif

2010-03-22T22:14:58Z

Becky Pippen: Media-on-a-Prim example of clock - page reloads

Media-on-a-Prim example of clock - page reloads

File:MoaP-example-laggraph.gif

2010-03-22T22:10:45Z

Becky Pippen: Media-on-a-Prim example of graph page reloading

Media-on-a-Prim example of graph page reloading

User:Becky Pippen/Memory Limits FAQ

2010-03-22T08:15:37Z

Becky Pippen: Add link to Jack's official blog announcement.

== FAQ - Script Memory Limits ==

For the most official announcement so far, see [https://blogs.secondlife.com/community/land/blog/2010/03/19/the-first-step-toward-script-limits here].

'''Q:''' Why do we need script memory limits?
: '''A:''' In some regions, the simulator uses so much script memory that it has to swap virtual memory to disk. That causes major lag, and lag is among the top complaints about Second Life.

'''Q:''' How can I tell if I'm a heavy script user?
: '''A:''' Starting with server version 1.38, we'll have new ways built into the sim and viewer to see our individual script memory usage, similar to how estate managers can see top scripts in a region. Also scripters can use the function [[LlGetFreeMemory|llGetFreeMemory()]] to get an approximate idea of memory usage.

'''Q:''' Will this break content?
: '''A:''' Yes, some. The limits are specifically designed to limit the worst 5% of memory consumers so that the remaining 95% can continue to run freely without causing the simulator to swap virtual memory.

'''Q:''' When will all this happen?
: '''A:''' Script memory reporting and the new memory-efficient LSL functions are [https://blogs.secondlife.com/community/technology/blog/2010/03/05/server-138-beta-now-open available for testing on the Preview Grid] using server version 1.38 and beta 2.0 of the SL viewer. Server version 1.40 or later will have "Small Scripts" capability (see below). Memory limits will not be enforced until later in 2010 after these features have been deployed on the main grid for some time.

'''Q:''' Will the limits be per avatar or per region?
: '''A:''' There will be limits on avatar, parcel, and region in a way that parallels [[LSL_http_server#Resource_Limitations|how URL resources are managed]].

'''Q:''' Will Linden Lab pay for all the scripted products we bought that will no longer work?
: '''A:''' Most products are reasonably scripted and will continue to work just fine. The only problematic products will be unusual ones that are scripted in ways that use unreasonable amounts of RAM. Try to get the product creator to make a new version that uses less memory.

'''Q:''' Will we see a reduction in lag across the grid?
: '''A:''' It won't have a major impact on most regions. However, it will make a huge improvement on the 5% of the regions that use so much script memory that the server has to swap virtual memory to disk. Theoretically it might also somewhat improve performance on any other simulators running on the same server host using the same disk resources.

'''Q:''' How much RAM are we talking about?
: '''A:''' In the 95% of the regions that run smoothly, the simulator uses less than 800MB of RAM for everything except scripts, and up to 300MB for all the scripts in the region, and that's ok. In the worst 5% of the regions, simulators use up to 2GB of RAM on the server, and that's not ok.

'''Q:''' Why not just add RAM to the servers? RAM is cheap.
: '''A:''' Several thousand Xeon server boards at, say, US$100 each to upgrade, comes out to a bunch of money, even for Linden Lab.

'''Q:''' Who will be affected?
: '''A:''' All scripts, old and new, will be subject to the new memory limits. When planning for the memory limits, [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2009_11_25 Babbage Linden said], "[2009/11/25 3:43] Babbage Linden: ideally we'd like to have 95+% of people use scripts as they currently do while still having 95+% of simulators running without swapping".

'''Q:''' What's the difference between "Small Scripts Project," "Big Scripts Project," and "Efficient Scripts Project?"
: '''A:''' The ''Efficient Scripts Project'' is the overall effort to reduce the memory consumption of Mono-based scripts, including limits on memory usage. The ''Small Scripts Project'' and ''Big Scripts Project'' both refer to a refinement where each script can request the specific amount of memory it anticipates using instead of being charged with a constant 16KB for LSL or 64KB for Mono scripts. So, for example, a simple Mono sit script might request only 3KB while another data-intensive Mono script might request several megabytes. Since the average Mono script in SL needs only about 9KB, this could help reduce overall script memory usage in a typical region. In [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2010_03_03 Office Hours], Babbage Linden said, "I would like to ship script usage, then small scripts, then script limits, then big scripts... so it would be nice to have mono scripts be able to reserve a lower memory amount before script limits enforcement happens."

'''Q:''' What's the "LSL Penalty?"
: '''A:''' At one time, LL considered charging LSL scripts with more memory than they actually consume as an incentive for scripters to use Mono. That idea has been dropped, and the current plan is to charge all scripts with the actual memory they reserve — currently 16KB for LSL, and 64KB for Mono scripts. In the future after the Small Scripts and Big Scripts Project have been implemented, Mono scripts can be charged for only the amount of memory they reserve, which could be more or less than 64KB. Discussion of this can be found in the [http://lists.secondlife.com/pipermail/opensource-dev/ opensource-dev] mailing list.

'''Q:''' What can I do as a content creator to prepare?
: '''A:''' Be kind to your customers and give them product updates using the [[User:Becky_Pippen/New_LSL_Functions| new efficient LSL functions]] when they become available. Learn more about how to [[User:Becky_Pippen/Measure_Script_Memory_Usage|measure memory usage]] and the [[User:Becky_Pippen/Script_Memory_Limits|scripting techniques for reducing memory]].

'''Q:''' What can I do as a customer?
: '''A:''' 95% of scripts are just fine and you don't need to do anything. If you are wearing hair, shoes, or other attachments with a script in every prim, then you can contact the creator and ask if there is a product update that uses the new LSL memory-efficient functions.

User:Becky Pippen/New LSL Functions

2010-03-13T00:16:42Z

Becky Pippen: Add link to Maestro's Linkset_resizer

== New LSL Functions ==

The information in this section is preliminary and predictive, based on information given by
[[Babbage_Linden|Babbage Linden at his Office Hours]] and in [https://blogs.secondlife.com/community/technology/blog/2010/03/05/server-138-beta-now-open this SL Blog announcement].

To help reduce the number of scripts needed for certain common operations, we will have these new
LSL functions in server version 1.38:

<lsl> list llGetLinkPrimitiveParams(integer linknumber, list params)

llSetLinkPrimitiveParamsFast(integer link, list params)

llLinkParticleSystem(integer link, list rules)

llSetLinkTextureAnim(integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate)
</lsl>

We will also get [[PRIM_TEXT]] for getting and setting hover text with [[llSetLinkPrimitiveParams]]().
The parameter list will be:

<lsl> PRIM_TEXT, string msg, vector color, float alpha </lsl>

===The deal with resizer scripts===

Some content creators prefer to distribute their objects no-mod, yet still allow customers to resize or
retexture the linkset. Scripts can do that in a no-mod linkset, but the obvious solution using
[[llSetLinkPrimitiveParams]]() doesn't work well because of the 0.2-second delay built into the function.
To work around the delay, we have had to put a script in every child prim that can respond immediately
to a message from the root prim. When these functions become available, we will be able to do this kind of thing with a single script.

===Fixing existing scripts===

To fix such a script, locate the call to [[llMessageLinked]]() in the master script where it sends the link
message to the individual prims. It might look something vaguely like this:

<lsl>llMessageLinked(LINK_whatever, command_resize, (string)newSize, NULL_KEY);</lsl>

Replace that with a loop that applies whatever changes you need to each prim using
[[llSetLinkPrimitiveParamsFast]](). The prims have link numbers from 1 through [[llGetNumberOfPrims]](),
so you can make an efficient loop as shown here; just add any additional processing you
need for each prim inside the loop:

<lsl> applyChildParams(list ruleSet)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
llSetLinkPrimitiveParamsFast(linkNum, ruleSet);
}
} </lsl>

For example, to use this function to set the color and alpha of all the prims, build the parameter
list and pass it to applyChildParams() like this:

<lsl>applyChildParams([PRIM_COLOR, ALL_SIDES, <0.9, 0.8, 0.2>, 1.0]);</lsl>

However, when you only need to apply a constant rule set like this to every prim in the linkset,
then the loop above can be simplified to a single statement;

<lsl>llSetLinkPrimitiveParamsFast(LINK_SET, ruleSet);</lsl>

Or use [[LINK_ALL_OTHERS]] or [[LINK_ALL_CHILDREN]] instead of [[LINK_SET]] as appropriate.

For another example, you can make a resizer script apply relative instead of absolute size changes by
using the new function [[llGetLinkPrimitiveParams]](). The script can read each child's current size,
then apply a resize factor and use [[llSetLinkPrimitiveParamsFast]]() to set a new size. This can help
make it easy for the script to do the right thing even if reset and all its variables get reinitialized. The
following function will resize all the prims (including the root itself) by a factor:

<lsl> rescaleLinksetByFactor(float factor)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
llSetLinkPrimitiveParamsFast(linkNum,
[PRIM_SIZE, factor * llList2Vector(params, 0)]);
}
} </lsl>

But what if the function above encounters a prim that, after resized, would have a dimension outside
the legal range of 0.01m to 10.0m? That could have unfortunate consequences, so
here is a function that resizes all the prims by a specified factor but only if all the resulting
dimensions in all the prims will all be in the legal range of 0.01m to 10.0m. If any dimension in
any prim would go out of those bounds, the function will return FALSE without resizing anything.
This example also includes repositioning the child prims within the linkset. Change or add whatever
additional parameters are needed for your particular application.

<lsl> // This is not a complete resizer solution; it's just a demo of
// how to call the new LSL functions.

// Set the minimum and maximum size allowed for any prim in the linkset:
//
float minPrimSize = 0.01;
float maxPrimSize = 10.0;

// Resize all the prims in the linkset. For example, to resize all
// the prims to 1% smaller, call this function with factor=0.99
// Returns TRUE if successful, or FALSE if resizing would have
// set a prim size out of bounds.
//
integer resizeLinksetWithBounds(float factor)
{
// Test to see if it's safe to change all the prim sizes:

integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
vector sz = factor * llList2Vector(params, 0);
if (sz.x < minPrimSize || sz.x > maxPrimSize ||
sz.y < minPrimSize || sz.y > maxPrimSize ||
sz.z < minPrimSize || sz.z > maxPrimSize) {
return FALSE;
}
}

// We've determined that we can safely change all the sizes, so
// let's do so now.

for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list oldParams = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE, PRIM_POSITION]);

list newParams = [ PRIM_SIZE, factor * llList2Vector(oldParams, 0) ];
if (linkNum > 1) {
vector linkPos = (vector)llList2String(oldParams, 1);
vector localPos = (linkPos - llGetRootPosition()) / llGetRootRotation();
newParams += [ PRIM_POSITION, factor * localPos ];
}

llSetLinkPrimitiveParamsFast(linkNum, newParams);
}

return TRUE;
} </lsl>

Here's a silly example of how it's used:

<lsl> // Example of how to call resizeLinksetWithBounds()
//
default
{
touch_start(integer num)
{
float factor = llPow(llFrand(2.0), 2.0); // random factor for demo
if (resizeLinksetWithBounds(factor)) {
llOwnerSay("Resized successfully by factor = " + (string)factor);
} else {
llOwnerSay("Oops, can't resize by factor " + (string)factor);
}
}
} </lsl>
(Acknowledgements: Thanks to Keith Reinard for testing and improving the example above.)

Also see Maestro Linden's newly posted [[Linkset_resizer|linkset resizer]].

===Resizer challenges===

A complete resizer solution is outside the scope of this article, but might need to consider such things as:
* You might need a way to reset all the prims to a known size, position, and orientation in case a resize loop breaks before successfully resizing all the prims.
* The example above might give unexpected results if executed while the object is in motion. For example, there is no way to guarantee that the functions llGetLinkPrimitiveParams() and llGetRootPosition() will be evaluated during the same simulator frame, so the local offset of a child prim could be computed incorrectly as the difference of the root position in one frame and the child position in another frame.
* Roundoff errors could accumulate if proportional scaling is done ''many'' times. (See [[User_talk:Becky_Pippen/New_LSL_Functions|the Discussion page]].)
* It's easy to scale a linkset so that prims get moved beyond their [[Linkability_Rules|linkability limits]], and no easy way for a script to test for this in advance. For more information, see the discussions at {{JIRA|SVC-5328}} and {{JIRA|SVC-5166}}.

===Long range plans===

The new LSL features described above are expected to appear in server version 1.38. Babbage Linden also mentioned a few additional LSL features he would like to implement sometime after 1.38, but with no guarantees if or when:

<lsl> PRIM_NAME, PRIM_DESC // for llGet/SetPrimitiveParams()
llAvatarOnLinkSitTarget()
llLinkSitTarget() </lsl>

===Also see===

* [[User:Becky_Pippen/Script_Memory_Limits| Scripter's checklist of things you can do to conserve memory]]
* [[User:Becky_Pippen/Memory_Limits_FAQ| Script memory limits FAQ]]

User:Becky Pippen/New LSL Functions

2010-03-12T22:01:02Z

Becky Pippen: a few comments on the challenges of resizing.

== New LSL Functions ==

The information in this section is preliminary and predictive, based on information given by
[[Babbage_Linden|Babbage Linden at his Office Hours]] and in [https://blogs.secondlife.com/community/technology/blog/2010/03/05/server-138-beta-now-open this SL Blog announcement].

To help reduce the number of scripts needed for certain common operations, we will have these new
LSL functions in server version 1.38:

<lsl> list llGetLinkPrimitiveParams(integer linknumber, list params)

llSetLinkPrimitiveParamsFast(integer link, list params)

llLinkParticleSystem(integer link, list rules)

llSetLinkTextureAnim(integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate)
</lsl>

We will also get [[PRIM_TEXT]] for getting and setting hover text with [[llSetLinkPrimitiveParams]]().
The parameter list will be:

<lsl> PRIM_TEXT, string msg, vector color, float alpha </lsl>

===The deal with resizer scripts===

Some content creators prefer to distribute their objects no-mod, yet still allow customers to resize or
retexture the linkset. Scripts can do that in a no-mod linkset, but the obvious solution using
[[llSetLinkPrimitiveParams]]() doesn't work well because of the 0.2-second delay built into the function.
To work around the delay, we have had to put a script in every child prim that can respond immediately
to a message from the root prim. When these functions become available, we will be able to do this kind of thing with a single script.

===Fixing existing scripts===

To fix such a script, locate the call to [[llMessageLinked]]() in the master script where it sends the link
message to the individual prims. It might look something vaguely like this:

<lsl>llMessageLinked(LINK_whatever, command_resize, (string)newSize, NULL_KEY);</lsl>

Replace that with a loop that applies whatever changes you need to each prim using
[[llSetLinkPrimitiveParamsFast]](). The prims have link numbers from 1 through [[llGetNumberOfPrims]](),
so you can make an efficient loop as shown here; just add any additional processing you
need for each prim inside the loop:

<lsl> applyChildParams(list ruleSet)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
llSetLinkPrimitiveParamsFast(linkNum, ruleSet);
}
} </lsl>

For example, to use this function to set the color and alpha of all the prims, build the parameter
list and pass it to applyChildParams() like this:

<lsl>applyChildParams([PRIM_COLOR, ALL_SIDES, <0.9, 0.8, 0.2>, 1.0]);</lsl>

However, when you only need to apply a constant rule set like this to every prim in the linkset,
then the loop above can be simplified to a single statement;

<lsl>llSetLinkPrimitiveParamsFast(LINK_SET, ruleSet);</lsl>

Or use [[LINK_ALL_OTHERS]] or [[LINK_ALL_CHILDREN]] instead of [[LINK_SET]] as appropriate.

For another example, you can make a resizer script apply relative instead of absolute size changes by
using the new function [[llGetLinkPrimitiveParams]](). The script can read each child's current size,
then apply a resize factor and use [[llSetLinkPrimitiveParamsFast]]() to set a new size. This can help
make it easy for the script to do the right thing even if reset and all its variables get reinitialized. The
following function will resize all the prims (including the root itself) by a factor:

<lsl> rescaleLinksetByFactor(float factor)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
llSetLinkPrimitiveParamsFast(linkNum,
[PRIM_SIZE, factor * llList2Vector(params, 0)]);
}
} </lsl>

But what if the function above encounters a prim that, after resized, would have a dimension outside
the legal range of 0.01m to 10.0m? That could have unfortunate consequences, so
here is a function that resizes all the prims by a specified factor but only if all the resulting
dimensions in all the prims will all be in the legal range of 0.01m to 10.0m. If any dimension in
any prim would go out of those bounds, the function will return FALSE without resizing anything.
This example also includes repositioning the child prims within the linkset. Change or add whatever
additional parameters are needed for your particular application.

<lsl> // This is not a complete resizer solution; it's just a demo of
// how to call the new LSL functions.

// Set the minimum and maximum size allowed for any prim in the linkset:
//
float minPrimSize = 0.01;
float maxPrimSize = 10.0;

// Resize all the prims in the linkset. For example, to resize all
// the prims to 1% smaller, call this function with factor=0.99
// Returns TRUE if successful, or FALSE if resizing would have
// set a prim size out of bounds.
//
integer resizeLinksetWithBounds(float factor)
{
// Test to see if it's safe to change all the prim sizes:

integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
vector sz = factor * llList2Vector(params, 0);
if (sz.x < minPrimSize || sz.x > maxPrimSize ||
sz.y < minPrimSize || sz.y > maxPrimSize ||
sz.z < minPrimSize || sz.z > maxPrimSize) {
return FALSE;
}
}

// We've determined that we can safely change all the sizes, so
// let's do so now.

for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list oldParams = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE, PRIM_POSITION]);

list newParams = [ PRIM_SIZE, factor * llList2Vector(oldParams, 0) ];
if (linkNum > 1) {
vector linkPos = (vector)llList2String(oldParams, 1);
vector localPos = (linkPos - llGetRootPosition()) / llGetRootRotation();
newParams += [ PRIM_POSITION, factor * localPos ];
}

llSetLinkPrimitiveParamsFast(linkNum, newParams);
}

return TRUE;
} </lsl>

Here's a silly example of how it's used:

<lsl> // Example of how to call resizeLinksetWithBounds()
//
default
{
touch_start(integer num)
{
float factor = llPow(llFrand(2.0), 2.0); // random factor for demo
if (resizeLinksetWithBounds(factor)) {
llOwnerSay("Resized successfully by factor = " + (string)factor);
} else {
llOwnerSay("Oops, can't resize by factor " + (string)factor);
}
}
} </lsl>
(Acknowledgements: Thanks to Keith Reinard for testing and improving the example above.)

===Resizer challenges===

A complete resizer solution is outside the scope of this article, but might need to consider such things as:
* You might need a way to reset all the prims to a known size, position, and orientation in case a resize loop breaks before successfully resizing all the prims.
* The example above might give unexpected results if executed while the object is in motion. For example, there is no way to guarantee that the functions llGetLinkPrimitiveParams() and llGetRootPosition() will be evaluated during the same simulator frame, so the local offset of a child prim could be computed incorrectly as the difference of the root position in one frame and the child position in another frame.
* Roundoff errors could accumulate if proportional scaling is done ''many'' times. (See [[User_talk:Becky_Pippen/New_LSL_Functions|the Discussion page]].)
* It's easy to scale a linkset so that prims get moved beyond their [[Linkability_Rules|linkability limits]], and no easy way for a script to test for this in advance. For more information, see the discussions at {{JIRA|SVC-5328}} and {{JIRA|SVC-5166}}.

===Long range plans===

The new LSL features described above are expected to appear in server version 1.38. Babbage Linden also mentioned a few additional LSL features he would like to implement sometime after 1.38, but with no guarantees if or when:

<lsl> PRIM_NAME, PRIM_DESC // for llGet/SetPrimitiveParams()
llAvatarOnLinkSitTarget()
llLinkSitTarget() </lsl>

===Also see===

* [[User:Becky_Pippen/Script_Memory_Limits| Scripter's checklist of things you can do to conserve memory]]
* [[User:Becky_Pippen/Memory_Limits_FAQ| Script memory limits FAQ]]

User:Becky Pippen/New LSL Functions

2010-03-11T20:43:57Z

Becky Pippen: Fix local vs. global with PRIM_POSITION

== New LSL Functions ==

The information in this section is preliminary and predictive, based on information given by
[[Babbage_Linden|Babbage Linden at his Office Hours]].

To help reduce the number of scripts needed for certain common operations, we will have these new
LSL functions, perhaps as early as server version 1.38:

<lsl> list llGetLinkPrimitiveParams(integer linknumber, list params)

llSetLinkPrimitiveParamsFast(integer link, list params)

llLinkParticleSystem(integer link, list rules)

llSetLinkTextureAnim(integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate)
</lsl>

We will also get PRIM_TEXT for getting and setting hover text with [[llSetLinkPrimitiveParams]]().
The parameter list will be:

<lsl> PRIM_TEXT, string msg, vector color, float alpha </lsl>

===The deal with resizer scripts===

Some content creators prefer to distribute their objects no-mod, yet still allow customers to resize or
retexture the linkset. Scripts can do that in a no-mod linkset, but the obvious solution using
[[llSetLinkPrimitiveParams]]() doesn't work well because of the 0.2-second delay built into the function.
To work around the delay, we have had to put a script in every child prim that can respond immediately
to a message from the root prim. When these functions become available, we will be able to do this kind of thing with a single script.

===Fixing existing scripts===

To fix such a script, locate the call to [[llMessageLinked]]() in the master script where it sends the link
message to the individual prims. It might look something vaguely like this:

<lsl>llMessageLinked(LINK_whatever, command_resize, (string)newSize, NULL_KEY);</lsl>

Replace that with a loop that applies whatever changes you need to each prim using
[[llSetLinkPrimitiveParamsFast]](). The prims have link numbers from 1 through [[llGetNumberOfPrims]](),
so you can make an efficient loop as shown here; just add any additional processing you
need for each prim inside the loop:

<lsl> applyChildParams(list ruleSet)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
llSetLinkPrimitiveParamsFast(linkNum, ruleSet);
}
} </lsl>

For example, to use this function to set the color and alpha of all the prims, build the parameter
list and pass it to applyChildParams() like this:

<lsl>applyChildParams([PRIM_COLOR, ALL_SIDES, <0.9, 0.8, 0.2>, 1.0]);</lsl>

However, when you only need to apply a constant rule set like this to every prim in the linkset,
then the loop above can be simplified to a single statement;

<lsl>llSetLinkPrimitiveParamsFast(LINK_SET, ruleSet);</lsl>

Or use [[LINK_ALL_OTHERS]] or [[LINK_ALL_CHILDREN]] instead of [[LINK_SET]] as appropriate.

For another example, you can make a resizer script apply relative instead of absolute size changes by
using the new function [[llGetLinkPrimitiveParams]](). The script can read each child's current size,
then apply a resize factor and use [[llSetLinkPrimitiveParamsFast]]() to set a new size. This can help
make it easy for the script to do the right thing even if reset and all its variables get reinitialized. The
following function will resize all the prims (including the root itself) by a factor:

<lsl> rescaleLinksetByFactor(float factor)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
llSetLinkPrimitiveParamsFast(linkNum,
[PRIM_SIZE, factor * llList2Vector(params, 0)]);
}
} </lsl>

But what if the function above encounters a prim that, after resized, would have a dimension outside
the legal range of 0.01m to 10.0m? That could have unfortunate consequences, so
here is a function that resizes all the prims by a specified factor but only if all the resulting
dimensions in all the prims will all be in the legal range of 0.01m to 10.0m. If any dimension in
any prim would go out of those bounds, the function will return FALSE without resizing anything.
This example also includes repositioning the child prims within the linkset. Change or add whatever
additional parameters are needed for your particular application.

<lsl> // This is not a complete resizer solution; it's just a demo of
// how to call the new LSL functions.

// Set the minimum and maximum size allowed for any prim in the linkset:
//
float minPrimSize = 0.01;
float maxPrimSize = 10.0;

// Resize all the prims in the linkset. For example, to resize all
// the prims to 1% smaller, call this function with factor=0.99
// Returns TRUE if successful, or FALSE if resizing would have
// set a prim size out of bounds.
//
integer resizeLinksetWithBounds(float factor)
{
// Test to see if it's safe to change all the prim sizes:

integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
vector sz = factor * llList2Vector(params, 0);
if (sz.x < minPrimSize || sz.x > maxPrimSize ||
sz.y < minPrimSize || sz.y > maxPrimSize ||
sz.z < minPrimSize || sz.z > maxPrimSize) {
return FALSE;
}
}

// We've determined that we can safely change all the sizes, so
// let's do so now.

for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list oldParams = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE, PRIM_POSITION]);

list newParams = [ PRIM_SIZE, factor * llList2Vector(oldParams, 0) ];
if (linkNum > 1) {
vector linkPos = (vector)llList2String(oldParams, 1);
vector localPos = (linkPos - llGetRootPosition()) / llGetRootRotation();
newParams += [ PRIM_POSITION, factor * localPos ];
}

llSetLinkPrimitiveParamsFast(linkNum, newParams);
}

return TRUE;
} </lsl>

Here's a silly example of how it's used:

<lsl> // Example of how to call resizeLinksetWithBounds()
//
default
{
touch_start(integer num)
{
float factor = llPow(llFrand(2.0), 2.0); // random factor for demo
if (resizeLinksetWithBounds(factor)) {
llOwnerSay("Resized successfully by factor = " + (string)factor);
} else {
llOwnerSay("Oops, can't resize by factor " + (string)factor);
}
}
} </lsl>
(Acknowledgements: Thanks to Keith Reinard for testing and improving this example.)

===Long range plans===

The new LSL features described above are expected to appear in server version 1.38. Babbage Linden also mentioned a few additional LSL features he would like to implement sometime after 1.38, but with no guarantees if or when:

<lsl> PRIM_NAME, PRIM_DESC // for llGet/SetPrimitiveParams()
llAvatarOnLinkSitTarget()
llLinkSitTarget() </lsl>

===Also see===

* [[User:Becky_Pippen/Script_Memory_Limits| Scripter's checklist of things you can do to conserve memory]]
* [[User:Becky_Pippen/Memory_Limits_FAQ| Script memory limits FAQ]]

User:Becky Pippen/Memory Limits FAQ

2010-03-07T20:00:32Z

Becky Pippen:

== FAQ - Script Memory Limits ==

'''Q:''' Why do we need script memory limits?
: '''A:''' In some regions, the simulator uses so much script memory that it has to swap virtual memory to disk. That causes major lag, and lag is among the top complaints about Second Life.

'''Q:''' How can I tell if I'm a heavy script user?
: '''A:''' Starting with server version 1.38, we'll have new ways built into the sim and viewer to see our individual script memory usage, similar to how estate managers can see top scripts in a region. Also scripters can use the function [[LlGetFreeMemory|llGetFreeMemory()]] to get an approximate idea of memory usage.

'''Q:''' Will this break content?
: '''A:''' Yes, some. The limits are specifically designed to limit the worst 5% of memory consumers so that the remaining 95% can continue to run freely without causing the simulator to swap virtual memory.

'''Q:''' When will all this happen?
: '''A:''' Script memory reporting and the new memory-efficient LSL functions are [https://blogs.secondlife.com/community/technology/blog/2010/03/05/server-138-beta-now-open available for testing on the Preview Grid] using server version 1.38 and beta 2.0 of the SL viewer. Server version 1.40 or later will have "Small Scripts" capability (see below). Memory limits will not be enforced until later in 2010 after these features have been deployed on the main grid for some time.

'''Q:''' Will the limits be per avatar or per region?
: '''A:''' There will be limits on avatar, parcel, and region in a way that parallels [[LSL_http_server#Resource_Limitations|how URL resources are managed]].

'''Q:''' Will Linden Lab pay for all the scripted products we bought that will no longer work?
: '''A:''' Most products are reasonably scripted and will continue to work just fine. The only problematic products will be unusual ones that are scripted in ways that use unreasonable amounts of RAM. Try to get the product creator to make a new version that uses less memory.

'''Q:''' Will we see a reduction in lag across the grid?
: '''A:''' It won't have a major impact on most regions. However, it will make a huge improvement on the 5% of the regions that use so much script memory that the server has to swap virtual memory to disk. Theoretically it might also somewhat improve performance on any other simulators running on the same server host using the same disk resources.

'''Q:''' How much RAM are we talking about?
: '''A:''' In the 95% of the regions that run smoothly, the simulator uses less than 800MB of RAM for everything except scripts, and up to 300MB for all the scripts in the region, and that's ok. In the worst 5% of the regions, simulators use up to 2GB of RAM on the server, and that's not ok.

'''Q:''' Why not just add RAM to the servers? RAM is cheap.
: '''A:''' Several thousand Xeon server boards at, say, US$100 each to upgrade, comes out to a bunch of money, even for Linden Lab.

'''Q:''' Who will be affected?
: '''A:''' All scripts, old and new, will be subject to the new memory limits. When planning for the memory limits, [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2009_11_25 Babbage Linden said], "[2009/11/25 3:43] Babbage Linden: ideally we'd like to have 95+% of people use scripts as they currently do while still having 95+% of simulators running without swapping".

'''Q:''' What's the difference between "Small Scripts Project," "Big Scripts Project," and "Efficient Scripts Project?"
: '''A:''' The ''Efficient Scripts Project'' is the overall effort to reduce the memory consumption of Mono-based scripts, including limits on memory usage. The ''Small Scripts Project'' and ''Big Scripts Project'' both refer to a refinement where each script can request the specific amount of memory it anticipates using instead of being charged with a constant 16KB for LSL or 64KB for Mono scripts. So, for example, a simple Mono sit script might request only 3KB while another data-intensive Mono script might request several megabytes. Since the average Mono script in SL needs only about 9KB, this could help reduce overall script memory usage in a typical region. In [http://wiki.secondlife.com/wiki/User:Babbage_Linden/Office_Hours/2010_03_03 Office Hours], Babbage Linden said, "I would like to ship script usage, then small scripts, then script limits, then big scripts... so it would be nice to have mono scripts be able to reserve a lower memory amount before script limits enforcement happens."

'''Q:''' What's the "LSL Penalty?"
: '''A:''' At one time, LL considered charging LSL scripts with more memory than they actually consume as an incentive for scripters to use Mono. That idea has been dropped, and the current plan is to charge all scripts with the actual memory they reserve — currently 16KB for LSL, and 64KB for Mono scripts. In the future after the Small Scripts and Big Scripts Project have been implemented, Mono scripts can be charged for only the amount of memory they reserve, which could be more or less than 64KB. Discussion of this can be found in the [http://lists.secondlife.com/pipermail/opensource-dev/ opensource-dev] mailing list.

'''Q:''' What can I do as a content creator to prepare?
: '''A:''' Be kind to your customers and give them product updates using the [[User:Becky_Pippen/New_LSL_Functions| new efficient LSL functions]] when they become available. Learn more about how to [[User:Becky_Pippen/Measure_Script_Memory_Usage|measure memory usage]] and the [[User:Becky_Pippen/Script_Memory_Limits|scripting techniques for reducing memory]].

'''Q:''' What can I do as a customer?
: '''A:''' 95% of scripts are just fine and you don't need to do anything. If you are wearing hair, shoes, or other attachments with a script in every prim, then you can contact the creator and ask if there is a product update that uses the new LSL memory-efficient functions.

User:Becky Pippen/Memory Limits FAQ

2010-02-25T01:44:28Z

Becky Pippen: Minor clarifications from Babbage's office hours this week

== FAQ - Script Memory Limits ==

'''Q:''' Why do we need script memory limits?
: '''A:''' In some regions, the simulator uses so much script memory that it has to swap virtual memory to disk. That causes major lag, and lag is among the top complaints about Second Life.

'''Q:''' How can I tell if I'm a heavy script user?
: '''A:''' Starting with server version 1.38, we'll have new ways built into the sim and viewer to see our individual script memory usage, similar to how estate managers can see top scripts in a region. Also scripters can use the function [[LlGetFreeMemory|llGetFreeMemory()]] to get an approximate idea of memory usage.

'''Q:''' Will this break content?
: '''A:''' Yes, some. The limits are specifically designed to limit the worst 5% of memory consumers so that the remaining 95% can continue to run freely without causing the simulator to swap virtual memory.

'''Q:''' When will all this happen?
: '''A:''' Before the end of Q1 of 2010, the new LSL functions and the new UI for displaying memory usage should be available for testing on the Preview Grid, then deployed to the main grid in server version 1.38 in Q2. We'll have several months where we can experiment with the new LSL functions and tools on the preview grid, then on the main grid before the memory limits are enforced sometime later in 2010.

'''Q:''' Will the limits be per avatar or per region?
: '''A:''' That hasn't been determined yet, but it will probably involve limits on avatar, parcel, and region in a way that parallels [[LSL_http_server#Resource_Limitations|how URL resources are managed]].

'''Q:''' Will Linden Lab pay for all the scripted products we bought that will no longer work?
: '''A:''' Most products are reasonably scripted and will continue to work just fine. The only problematic products will be unusual ones that are scripted in ways that use unreasonable amounts of RAM. Try to get the product creator to make a new version that uses less memory.

'''Q:''' Will we see a reduction in lag across the grid?
: '''A:''' It won't have a major impact on most regions. However, it will make a huge improvement on the 5% of the regions that use so much script memory that the server has to swap virtual memory to disk. Theoretically it might also somewhat improve performance on any other simulators running on the same server host using the same disk resources.

'''Q:''' How much RAM are we talking about?
: '''A:''' In the 95% of the regions that run smoothly, the simulator uses less than 800MB of RAM for everything except scripts, and up to 300MB for all the scripts in the region, and that's ok. In the worst 5% of the regions, simulators use up to 2GB of RAM on the server, and that's not ok.

'''Q:''' Why not just add RAM to the servers? RAM is cheap.
: '''A:''' Several thousand Xeon server boards at, say, US$100 each to upgrade, comes out to a bunch of money, even for Linden Lab.

'''Q:''' Who will be affected?
: '''A:''' All scripts, old and new, will be subject to the new memory limits. When planning for the memory limits, Babbage Linden said, "[2009/11/25 3:43] Babbage Linden: ideally we'd like to have 95+% of people use scripts as they currently do while still having 95+% of simulators running without swapping".

'''Q:''' What's the difference between "Small Scripts Project," "Big Scripts Project," and "Efficient Scripts Project?"
: '''A:''' The ''Efficient Scripts Project'' is the overall effort to reduce the memory consumption of Mono-based scripts, including limits on memory usage. The ''Small Scripts Project'' and ''Big Scripts Project'' both refer to a refinement where each script can request the specific amount of memory it anticipates using instead of being charged with a constant 16KB for LSL or 64KB for Mono scripts. So, for example, a simple Mono sit script might request only 3KB while another data-intensive Mono script might request several megabytes. Since the average Mono script in SL needs only about 9KB, this could help reduce overall script memory usage in a typical region.

'''Q:''' What's the "LSL Penalty?"
: '''A:''' At one time, LL considered charging LSL scripts with more memory than they actually consume as an incentive for scripters to use Mono. That idea has been dropped, and the current plan is to charge LSL scripts with actual memory use — currently 16KB for LSL, and 64KB for Mono scripts. In the future after the Small Scripts and Big Scripts Project has been implemented, Mono scripts can be charged for only the amount of memory they reserve, which could be more or less than 64KB.

'''Q:''' What can I do as a content creator to prepare?
: '''A:''' Be kind to your customers and give them product updates using the [[User:Becky_Pippen/New_LSL_Functions| new efficient LSL functions]] when they become available. Learn more about how to [[User:Becky_Pippen/Measure_Script_Memory_Usage|measure memory usage]] and the [[User:Becky_Pippen/Script_Memory_Limits|scripting techniques for reducing memory]].

'''Q:''' What can I do as a customer?
: '''A:''' 95% of scripts are just fine and you don't need to do anything. If you are wearing hair, shoes, or other attachments with a script in every prim, then you can contact the creator and ask if there is a product update that uses the new LSL memory-efficient functions.

User:Becky Pippen

2010-02-17T18:42:22Z

Becky Pippen: Moved the LSL performance data to User:Becky_Pippen/LSL_Performance

User:Becky Pippen/New LSL Functions

2010-02-17T18:25:40Z

Becky Pippen: Minor updates from today's office hours

== New LSL Functions ==

The information in this section is preliminary and predictive, based on information given by
[[Babbage_Linden|Babbage Linden at his Office Hours]].

To help reduce the number of scripts needed for certain common operations, we will have these new
LSL functions, perhaps as early as server version 1.38:

<lsl> list llGetLinkPrimitiveParams(integer linknumber, list params)

llSetLinkPrimitiveParamsFast(integer link, list params)

llLinkParticleSystem(integer link, list rules)

llSetLinkTextureAnim(integer mode, integer face, integer sizex, integer sizey, float start, float length, float rate)
</lsl>

We will also get PRIM_TEXT for getting and setting hover text with [[llSetLinkPrimitiveParams]]().
The parameter list will be:

<lsl> PRIM_TEXT, string msg, vector color, float alpha </lsl>

===The deal with resizer scripts===

Some content creators prefer to distribute their objects no-mod, yet still allow customers to resize or
retexture the linkset. Scripts can do that in a no-mod linkset, but the obvious solution using
[[llSetLinkPrimitiveParams]]() doesn't work well because of the 0.2-second delay built into the function.
To work around the delay, we have had to put a script in every child prim that can respond immediately
to a message from the root prim. When these functions become available, we will be able to do this kind of thing with a single script.

===Fixing existing scripts===

To fix such a script, locate the call to [[llMessageLinked]]() in the master script where it sends the link
message to the individual prims. It might look something vaguely like this:

<lsl>llMessageLinked(LINK_whatever, command_resize, (string)newSize, NULL_KEY);</lsl>

Replace that with a loop that applies whatever changes you need to each prim using
[[llSetLinkPrimitiveParamsFast]](). The prims have link numbers from 1 through [[llGetNumberOfPrims]](),
so you can make an efficient loop as shown here; just add any additional processing you
need for each prim inside the loop:

<lsl> applyChildParams(list ruleSet)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
llSetLinkPrimitiveParamsFast(linkNum, ruleSet);
}
} </lsl>

For example, to use this function to set the color and alpha of all the prims, build the parameter
list and pass it to applyChildParams() like this:

<lsl>applyChildParams([PRIM_COLOR, ALL_SIDES, <0.9, 0.8, 0.2>, 1.0]);</lsl>

However, when you only need to apply a constant rule set like this to every prim in the linkset,
then the loop above can be simplified to a single statement;

<lsl>llSetLinkPrimitiveParamsFast(LINK_SET, ruleSet);</lsl>

Or use [[LINK_ALL_OTHERS]] or [[LINK_ALL_CHILDREN]] instead of [[LINK_SET]] as appropriate.

For another example, you can make a resizer script apply relative instead of absolute size changes by
using the new function [[llGetLinkPrimitiveParams]](). The script can read each child's current size,
then apply a resize factor and use [[llSetLinkPrimitiveParamsFast]]() to set a new size. This can help
make it easy for the script to do the right thing even if reset and all its variables get reinitialized. The
following function will resize all the prims (including the root itself) by a factor:

<lsl> rescaleLinksetByFactor(float factor)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
llSetLinkPrimitiveParamsFast(linkNum,
[PRIM_SIZE, factor * llList2Vector(params, 0)]);
}
} </lsl>

But what if the function above encounters a prim that, after resized, would have a dimension outside
the legal range of 0.01m to 10.0m? That could have unfortunate consequences, so
here is a function that resizes all the prims by a specified factor but only if all the resulting
dimensions in all the prims will all be in the legal range of 0.01m to 10.0m. If any dimension in
any prim would go out of those bounds, the function will return FALSE without resizing anything.
This example also includes repositioning the child prims within the linkset. Change or add whatever
additional parameters are needed for your particular application.

<lsl> // This is not a complete resizer solution; it's just a demo of
// how to call the new LSL functions.

// Set the minimum and maximum size allowed for any prim in the linkset:
//
float minPrimSize = 0.01;
float maxPrimSize = 10.0;

// Resize all the prims in the linkset. For example, to resize all
// the prims to 1% smaller, call this function with factor=0.99
// Returns TRUE if successful, or FALSE if resizing would have
// set a prim size out of bounds.
//
integer resizeLinksetWithBounds(float factor)
{
// Test to see if it's safe to change all the prim sizes:

integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
vector sz = factor * llList2Vector(params, 0);
if (sz.x < minPrimSize || sz.x > maxPrimSize ||
sz.y < minPrimSize || sz.y > maxPrimSize ||
sz.z < minPrimSize || sz.z > maxPrimSize) {
return FALSE;
}
}

// We've determined that we can safely change all the sizes, so
// let's do so now. This example assumes that llGetLinkPrimitiveParams()
// with PRIM_POSITION will return the relative offset from the root prim,
// but those details have not yet been published.

for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list oldParams = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE, PRIM_POSITION]);

list newParams = [ PRIM_SIZE, factor * llList2Vector(oldParams, 0) ];
if (linkNum > 1) {
newParams += [ PRIM_POSITION, factor * llList2Vector(oldParams, 1) ];
}

llSetLinkPrimitiveParamsFast(linkNum, newParams);
}

return TRUE;
} </lsl>

Here's a silly example of how it's used:

<lsl> // Example of how to call resizeLinksetWithBounds()
//
default
{
touch_start(integer num)
{
float factor = llPow(llFrand(2.0), 2.0); // random factor for demo
if (resizeLinksetWithBounds(factor)) {
llOwnerSay("Resized successfully by factor = " + (string)factor);
} else {
llOwnerSay("Oops, can't resize by factor " + (string)factor);
}
}
} </lsl>

===Long range plans===

The new LSL features described above are expected to appear in server version 1.38. Babbage Linden also mentioned a few additional LSL features he would like to implement sometime after 1.38, but with no guarantees if or when:

<lsl> PRIM_NAME, PRIM_DESC // for llGet/SetPrimitiveParams()
llAvatarOnLinkSitTarget()
llLinkSitTarget() </lsl>

===Also see===

* [[User:Becky_Pippen/Script_Memory_Limits| Scripter's checklist of things you can do to conserve memory]]
* [[User:Becky_Pippen/Memory_Limits_FAQ| Script memory limits FAQ]]

User:Becky Pippen/LSL Performance

2010-02-17T04:43:54Z

Becky Pippen: added Mono CIL; reformatted; in preparation for relocation from User:Becky_Pippen

==LSL Timings and Rates==
Here are some selected LSL function times and event rates comparing scripts compiled and run using the old LSL toolset (a.k.a LSO), and using Mono.

The basic test framework for these tests is a loop like shown below, where we take the difference in llGetTime() before and after the loop:

while (--i >= 0) {
f(); f(); f(); f(); f(); f(); f(); f();
f(); f(); f(); f(); f(); f(); f(); f();
}

The loop is partially unrolled to make the loop control structure overhead negligible. We take several measurements in multiple Class 5 sims that are running consistently with a total frame time under 10 ms, where each test runs for 30 - 120 minutes, or longer if we fall asleep during the test. We measure several times during a 24-hour period until the numbers converge with a variance of 10% or less.

Measurements are taken in at least three regions, because we've occasionally seen regions with lots of reported spare time per frame, yet scripts seem to run inexplicably slow. If two out of three regions converge and agree, the anomalous region is ignored. Consider the numbers reported on this page to be maximums possible in cooperative regions.

In a Mono test, the result of the first run after script reset is ignored to eliminate the overhead of the VM initialization, JIT compilation, etc.

The Mono CIL shown for some of the LSL code below was obtained by modifying an SL viewer so that it calls lscript_compile() when saving a script. (Scripts are compiled on the simulators nowadays, but Linden Lab has kindly left the script compiler code in the open source viewer source code.) Comments and formatting were added manually.

Note that these are stopwatch times. How rapidly you can call a function or how often an event handler is invoked doesn't necessarily correspond to how much those functions and events lag a sim because of all the throttling and scheduling going on behind the scenes inside the run-time engine.

Class 7 hosts are starting to appear on the main grid as reported [[Beta_Server_Office_Hours/Minutes/2010-02-04|here]] and [[User:Andrew_Linden/Office_Hours/2010_02_02|here]]. As Linden Lab moves toward classless regions, absolute timings like shown on this page will become less meaningful. Maybe we can make use of some sort of relative performance measurements in the future.

== Functions, operators, & control structures ==

===Floating point assignment===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|x = [[PI]];
where x is a global [[float]]
{{!}}-
{{!}}align="center"|LSL: '''0.11''' ms/call
{{!}}align="center"|*Mono: '''0.0007''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
.field public float32 'x' // float x;
. . .
ldarg.0 // push 'this' pointer
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
stfld float32 LSL_script::'x' // pop and store 32-bit x
ldarg.0
ldfld float32 LSL_script::'x'
pop</code>
{{!}}}
:Notes: Verified and updated for server version 1.34.2.142087.

===Call to empty f() { }===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|f();
where f() is defined as f() { }
{{!}}-
{{!}}align="center"|LSL: '''0.33''' ms/call
{{!}}align="center"|*Mono: '''0.0026''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
Function definition:
:<code style="font-size:90%">
.method public hidebysig instance default void 'gf'() cil managed
{
.maxstack 500
ret
}</code>
Caller:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
call instance void class LSL_script::'gf'()</code>
{{!}}}

===[[for]] loop overhead===
:This test measures the overhead of a [[for]] loop that iterates an empty block just once.
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[for]] (i = 0; i == 0; ++i) { }
{{!}}-
{{!}}align="center"|LSL: '''0.07''' ms/loop
{{!}}align="center"|*Mono: '''0.001''' ms/loop
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
// loop init: i = 0
ldc.i4.0 // push 32-bit 0
stloc.s 0 // pop and store in i
ldc.i4 0 // push 32-bit 0
dup // duplicate 0 on the stack
stloc.s 0 // pop and store 0 in i
pop // cleanup

LabelTempJump0:
// top of loop: test i == 0
ldc.i4 0 // push 32-bit 0
ldloc.s 0 // push i
ceq // compare i and 0
brfalse LabelTempJump1 // branch if i != 0

// bottom of loop: ++i
ldloc.s 0 // push i
ldc.i4.1 // push 32-bit 1
add // pop i and 1, add, push result
dup // duplicate result
stloc.s 0 // save result in i
pop // cleanup
br LabelTempJump0

LabelTempJump1:
ret
</code>
{{!}}}

===[[State]] change===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[state]] a;
{{!}}-
{{!}}align="center"|LSL: '''0.14''' ms/transition
{{!}}align="center"|*Mono: '''22.2''' ms/transition
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldstr "state2"
call instance void class [LslUserScript] \
LindenLab.SecondLife.LslUserScript::ChangeState(string)
ret
</code>
{{!}}}
:Notes:
:State changes in Mono are tied to the sim frame rate of 45 fps (per Vektor Linden). The test code for state changes is an outer loop around 16 state changes like this:
<code>
:: . . .
:: state state''N'' { state_entry() { state state''N+1''; } }
:: state state''N+1'' { state_entry() { state state''N+2''; } }
:: . . . etc.
</code>

===[[Vector]] operations===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|v = <PI,[[PI]],PI> + <PI,PI,PI> * PI;
{{!}}-
{{!}}align="center"|LSL: '''0.43''' ms/statement
{{!}}align="center"|*Mono: '''0.025''' ms/statement
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI (vector x)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI (vector y)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI (vector z)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI multiplicand
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'CreateVector'(float32, float32, float32)
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'Multiply'(float32, class [ScriptTypes]LindenLab.SecondLife.Vector)
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
ldc.r8 (00 00 00 60 fb 21 09 40) // push 64-bit PI
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'CreateVector'(float32, float32, float32)
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'Add'(class [ScriptTypes]LindenLab.SecondLife.Vector, \
class [ScriptTypes]LindenLab.SecondLife.Vector)
// save result in v:
stfld class [ScriptTypes]LindenLab.SecondLife.Vector LSL_script::'v'
ldarg.0 // push 'this' pointer
ldfld class [ScriptTypes]LindenLab.SecondLife.Vector LSL_script::'v'
pop
</code>
{{!}}}

===[[llAbs]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llAbs]]();
{{!}}-
{{!}}align="center"|LSL: '''0.41''' ms/statement
{{!}}align="center"|*Mono: '''0.012''' ms/statement
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 0 // push the integer argument
call int32 class [LslLibrary]LindenLab.SecondLife.Library::'llAbs'(int32)
</code>
{{!}}}
:Notes: verified and updated for server ver. 1.34.2.142087

===[[Category:LSL_CSV|CSV]] [[string]] conversions===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llCSV2List]]([[llList2CSV]](x));
where x is a [[list]] of 10 [[integer]]s
{{!}}-
{{!}}align="center"|LSL: '''3.2''' ms/call
{{!}}align="center"|*Mono: '''4 - 7''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'x'
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llList2CSV'(class [mscorlib]System.Collections.ArrayList)
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] class \
[LslLibrary]LindenLab.SecondLife.Library::'llCSV2List'(string)
</code>
{{!}}}
:Notes: So far, the Mono results vary too much for any meaningful result.

===[[llDetectedName]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llDetectedName]]();
{{!}}-
{{!}}align="center"|LSL: '''1.1''' ms/call
{{!}}align="center"|*Mono: '''0.8''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 0 // push argument
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llDetectedName'(int32)
</code>
{{!}}}

===[[llGetInventoryName]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llGetInventoryName]](INVENTORY_TEXTURE, 0);
{{!}}-
{{!}}align="center"|LSL: '''0.52''' ms/call
{{!}}align="center"|*Mono: '''0.21''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 0 // push INVENTORY_TEXTURE
ldc.i4 0 // push 2nd argument
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llGetInventoryName'(int32, int32)</code>
{{!}}}

===[[llGetObjectDetails]]===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llGetObjectDetails]](k, [OBJECT_OWNER]);
{{!}}-
{{!}}align="center"|LSL: '''1.3''' ms/call
{{!}}align="center"|*Mono: '''1.7''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
// push k:
ldfld valuetype [ScriptTypes]LindenLab.SecondLife.Key LSL_script::'k'
ldc.i4 6 // push OBJECT_OWNER
box [mscorlib]System.Int32
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
CreateList()
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
Prepend(object, class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList])
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llGetObjectDetails'(valuetype \
[ScriptTypes]LindenLab.SecondLife.Key, \
class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList])
</code>
{{!}}}
:Notes: Verified and updated for server ver. 1.34.2.142087

===[[llGetPos]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llGetPos]]();
{{!}}-
{{!}}align="center"|LSL: '''0.39''' ms/call
{{!}}align="center"|*Mono: '''0.025''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llGetPos'()
</code>
{{!}}}
:Notes: Verified and updated for server ver. 1.34.2.142087

===[[llList2Vector]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llList2Vector]](x, 0);
where x = [ [[ZERO_VECTOR]] ]
{{!}}-
{{!}}align="center"|LSL: '''0.55''' ms/call
{{!}}align="center"|*Mono: '''0.012''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
// push list x:
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'x'
ldc.i4 0 // push 2nd argument: 0
call class [ScriptTypes]LindenLab.SecondLife.Vector \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llList2Vector'(class \
[mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList], int32)
</code>
{{!}}}

===[[llMD5String]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llMD5String]](s,0);
where s is a 64-char [[string]]
{{!}}-
{{!}}align="center"|LSL: '''1.4''' ms/call
{{!}}align="center"|*Mono: '''1.4''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push string s
ldc.i4 0 // push 2nd arg: 0
call string class [LslLibrary]LindenLab.SecondLife.Library:: \
'llMD5String'(string, int32)</code>
{{!}}}

===[[llMessageLinked]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=3 width=520|[[llMessageLinked]]([[LINK_THIS]], 0, "", [[NULL_KEY]]);
{{!}}-
{{!}}One consumer script:
{{!}}align="center"|LSL: '''1.5''' ms/call
{{!}}align="center"|*Mono: '''0.9''' ms/call
{{!}}-
{{!}}Two consumer scripts:
{{!}}align="center"|LSL: '''1.8''' ms/call
{{!}}align="center"|Mono: '''1.2''' ms/call
{{!}}-
{{!}}Four consumer scripts:
{{!}}align="center"|LSL: '''2.4''' ms/call
{{!}}align="center"|Mono: '''1.8''' ms/call
{{!}}-
{{!}}Eight consumer scripts:
{{!}}align="center"|LSL: '''4.4''' ms/call
{{!}}align="center"|Mono: '''3.3''' ms/call
{{!}}-
{{!}}16 consumer scripts:
{{!}}align="center"|LSL: '''9 - 20''' ms/call
{{!}}align="center"|Mono: '''7 - 15''' ms/call
{{!}}-
{{!}}32 consumer scripts:
{{!}}align="center"|LSL: '''22.2''' ms/call
{{!}}align="center"|Mono: '''22.2''' ms/call
{{!}}-
{{!}}colspan=3|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 -4 // push LINK_THIS
ldc.i4 0 // push 2nd arg: 0
ldstr "" // push 3rd arg: ""
ldstr "00000000-0000-0000-0000-000000000000" // push 4th arg as string
// convert that last string to a key type:
call valuetype [ScriptTypes]LindenLab.SecondLife.Key \
class [LslUserScript]LindenLab.SecondLife.LslUserScript:: \
'CreateKey'(string)
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llMessageLinked'(int32, int32, string, valuetype \
[ScriptTypes]LindenLab.SecondLife.Key)
</code>
{{!}}}
:Notes: The time it takes to call llMessageLinked() is dependent on the number of consumers of the message, up to about 20-30 consumer scripts. At that point, the time to send a link message becomes constant at one call per 22.2 ms, which is suspiciously similar to the sim's basic frame rate.

===[[llParseString2List]]===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llParseString2List]](s,a,b);
where s is 2000 random digits, a=["0","1"]; b=["2","3"];
{{!}}-
{{!}}align="center"|LSL: '''45''' ms/call
{{!}}align="center"|*Mono: '''24''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push 1st arg: s
ldarg.0 // push 'this'
// push 2nd arg: list a:
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'a'
ldarg.0 // push 'this'
// push 3rd ard: list b:
ldfld class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] LSL_script::'b'
call class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList] \
class [LslLibrary]LindenLab.SecondLife.Library:: \
'llParseString2List'(string, \
class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList], \
class [mscorlib][http://www.gnu.org/projects/dotgnu/pnetlib-doc/System/Collections/ArrayList.html System.Collections.ArrayList])
</code>
{{!}}}

===[[llSay]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSay]](-2, "0123456789");
{{!}}-
{{!}}align="center"|LSL: '''0.7''' ms/call
{{!}}align="center"|*Mono: '''0.2''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 2 // push 2...
neg // ...and negate it = -2
ldstr "0123456789" // push 2nd arg
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSay'(int32, string)</code>
{{!}}}
:Notes:
:#The performance of llSay(-2, "0123456789") varies widely by region, although it can be pretty consistent within a region. In some nearly empty regions, llSay() slows to no better than 5 ms/call for reasons unknown. It's as if the throttling for this function is less deterministic than other LSL functions. But even in the worst case, llSay() can transmit faster than llListen() can receive.
:#Verified and updated for server ver. 1.34.2.142087.

===[[llSetLinkAlpha]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSetLinkAlpha]](link, alpha, side);
{{!}}-
{{!}}align="center"|LSL: '''1.0''' ms/call
{{!}}align="center"|*Mono: '''0.52''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldc.i4 1 // push 1st arg: link number
ldc.r8 (00 00 00 60 b8 1e d5 3f) // push 2nd arg: float alpha
ldc.i4 0 // push 3rd arg: side number
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSetLinkAlpha'(int32, float32, int32)
</code>
{{!}}}

===[[llSetText]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSetText]](s,c,a);
where [[string]] s is 20 chars
{{!}}-
{{!}}align="center"|LSL: '''0.79''' ms/call
{{!}}align="center"|*Mono: '''0.38''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push 1st arg: string s
ldarg.0 // push 'this'
// push 2nd arg: color:
ldfld class [ScriptTypes]LindenLab.SecondLife.Vector LSL_script::'c'
ldarg.0 // push 'this'
ldfld float32 LSL_script::'a' // push 3rd arg: a
call void class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSetText'(string, \
class [ScriptTypes]LindenLab.SecondLife.Vector, float32)
</code>
{{!}}}

===[[llSubStringIndex]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|[[llSubStringIndex]](s, "X");
where s is 10000 digits not containing "X"
{{!}}-
{{!}}align="center"|LSL: '''16''' ms/call
{{!}}align="center"|*Mono: '''22''' ms/call
{{!}}-
{{!}}colspan=2|*Mono CIL:
:<code style="font-size:90%">
ldarg.0 // push 'this' pointer
ldfld string LSL_script::'s' // push 1st arg: string a
ldstr "X" // push 2nd arg: literal string
call int32 class [LslLibrary]LindenLab.SecondLife.Library:: \
'llSubStringIndex'(string, string)
</code>
{{!}}}

== Event handlers ==

===[[dataserver]]() for [[llGetNotecardLine]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[dataserver]]() events using [[llGetNotecardLine]]()
{{!}}-
{{!}}align="center"|LSL: '''6.4''' events/sec
{{!}}align="center"|Mono: '''6.4''' events/sec
{{!}}}

===[[link_message]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[link_message]]() events
{{!}}-
{{!}}align="center"|LSL: '''42-45''' events/sec
{{!}}align="center"|Mono: '''42-45''' events/sec
{{!}}}
:Notes: The results were highly variable over several tens of millions of link_message() events in three lightly loaded sims, but I wonder if the maximum rate is tied to the sim frame rate of 45 fps.

===[[listen]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=3 width=520|Maximum rate of [[listen]]() events
any number of scripts per prim, any number of prims in linkset
{{!}}-
{{!}}1 listener per script:
{{!}}align="center"|LSL: '''14.7''' events/sec
{{!}}align="center"|Mono: '''14.7''' events/sec
{{!}}-
{{!}}Two listeners per script:
{{!}}align="center"|LSL: '''11''' events/sec
{{!}}align="center"|Mono: '''11''' events/sec
{{!}}-
{{!}}Three listeners per script:
{{!}}align="center"|LSL: '''8.9''' events/sec
{{!}}align="center"|Mono: '''8.9''' events/sec
{{!}}}

===[[sensor]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[sensor]]() events
after [[llSensorRepeat]]()
{{!}}-
{{!}}align="center"|LSL: '''15''' events/sec
{{!}}align="center"|Mono: '''22''' events/sec
{{!}}}
:Notes: The maximum rate of sensor() events seems to be independent of the sensor radius or number of things detected.

===[[timer]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[timer]]() events
{{!}}-
{{!}}align="center"|LSL: '''22''' events/sec
{{!}}align="center"|Mono: '''22''' events/sec
{{!}}}
:Notes: About half the sim's basic frame rate of 45 fps.

===[[touch]]()===
:{{{!}} {{Prettytable|style=margin-top:0; font-size:100%}}
{{!}}-
!colspan=2 width=520|Maximum rate of [[touch]]() events
{{!}}-
{{!}}align="center"|LSL: '''22''' events/sec
{{!}}align="center"|Mono: '''22''' events/sec
{{!}}}
:Notes: About half the sim's basic frame rate of 45 fps.

User talk:Becky Pippen/New LSL Functions

2010-01-24T23:05:21Z

Becky Pippen:

Thanks for providing the info. The suggested relative resizing troubles me, since it accumulates error that breaks objects (besides this, no recovery when the position component fails due to not-completely-predictable SL behavior). For objects that only resize a few times, like most jewelry, the error does not grow enough to be noticed, and my concern is more principle than practical. But, I make some objects that resize many times, for example, as part of RP or in response to nearby AV actions, so they use absolute resizing. (Even for jewelry, I use absolute resizing, with a single-script resizer for low script time, but that stores original sizes and positions in memory. They can be re-read from a notecard in case of a script reset, but not during normal operation since that is so slow.) [[User:Xoph Adamczyk|Xoph Adamczyk]] 16:55, 22 January 2010 (UTC)
:Thanks, Xoph, you're quite right about the risks of repositioning this way, and I'm glad you pointed it out. The main point of the code snippets is to suggest a general loop structure for getting and setting parameters in all the prims in a linkset, not the specific parameter changes which need to be carefully considered for each product's use cases. I'd love it if someone contributed a more realistic example for a specific application. [[User:Becky Pippen|Becky Pippen]] 18:03, 22 January 2010 (UTC)

== When the time comes... ==

When the time comes that these functions go live, would you be alright with some of what you have written being used in/as the documentation? -- '''[[User:Strife_Onizuka|Strife]]''' <sup><small>([[User talk:Strife_Onizuka|talk]]|[[Special:Contributions/Strife_Onizuka|contribs]])</small></sup> 22:03, 24 January 2010 (UTC)
:Sure :-) [[User:Becky Pippen|Becky Pippen]] 23:05, 24 January 2010 (UTC)

User talk:Becky Pippen/New LSL Functions

2010-01-22T18:03:58Z

Becky Pippen:

User:Becky Pippen/New LSL Functions

2010-01-20T18:30:42Z

Becky Pippen: added minor updates from today's office hours

== New LSL Functions ==

The information in this section is preliminary and predictive, based on information given by
[[Babbage_Linden|Babbage Linden at his Office Hours]].

To help reduce the number of scripts needed for certain common operations, we will have these new
LSL functions, perhaps as early as server version 1.38:

<lsl> list llGetLinkPrimitiveParams(integer linknumber, list params)

llSetLinkPrimitiveParamsFast(integer link, list params) </lsl>

We will also get PRIM_TEXT for getting and setting hover text with [[llSetLinkPrimitiveParams]]().
The parameter list will be:

<lsl> PRIM_TEXT, string msg, vector color, float alpha </lsl>

===History===

Some content creators prefer to distribute their objects no-mod, yet still allow customers to resize or
retexture the linkset. Scripts can do that in a no-mod linkset, but the obvious solution using
[[llSetLinkPrimitiveParams]]() doesn't work well because of the 0.2-second delay built into the function.
To work around the delay, we have had to put a script in every child prim that can respond immediately
to a message from the root prim. When these functions become available, we will be able to do this kind of thing with a single script.

===Fixing Existing Scripts===

To fix such a script, locate the call to [[llMessageLinked]]() in the master script where it sends the link
message to the individual prims. It might look something vaguely like this:

<lsl>llMessageLinked(LINK_whatever, command_resize, (string)newSize, NULL_KEY);</lsl>

Replace that with a loop that applies whatever changes you need to each prim using
[[llSetLinkPrimitiveParamsFast]](). The prims have link numbers from 1 through [[llGetNumberOfPrims]](),
so you can make an efficient loop as shown here; just add any additional processing you
need for each prim inside the loop:

<lsl> applyChildParams(list ruleSet)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
llSetLinkPrimitiveParamsFast(linkNum, ruleSet);
}
} </lsl>

For example, to use this function to set the color and alpha of all the prims, build the parameter
list and pass it to applyChildParams() like this:

<lsl>applyChildParams([PRIM_COLOR, ALL_SIDES, <0.9, 0.8, 0.2>, 1.0]);</lsl>

However, when you only need to apply a constant rule set like this to every prim in the linkset,
then the loop above can be simplified to a single statement;

<lsl>llSetLinkPrimitiveParamsFast(LINK_SET, ruleSet);</lsl>

Or use [[LINK_ALL_OTHERS]] or [[LINK_ALL_CHILDREN]] instead of [[LINK_SET]] as appropriate.

For another example, you can make a resizer script apply relative instead of absolute size changes by
using the new function [[llGetLinkPrimitiveParams]](). The script can read each child's current size,
then apply a resize factor and use [[llSetLinkPrimitiveParamsFast]]() to set a new size. This can help
make it easy for the script to do the right thing even if reset and all its variables get reinitialized. The
following function will resize all the prims (including the root itself) by a factor:

<lsl> rescaleLinksetByFactor(float factor)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
llSetLinkPrimitiveParamsFast(linkNum,
[PRIM_SIZE, factor * llList2Vector(params, 0)]);
}
} </lsl>

But what if the function above encounters a prim that, after resized, would have a dimension outside
the legal range of 0.01m to 10.0m? That could have unfortunate consequences, so
here is a function that resizes all the prims by a specified factor but only if all the resulting
dimensions in all the prims will all be in the legal range of 0.01m to 10.0m. If any dimension in
any prim would go out of those bounds, the function will return FALSE without resizing anything.
This example also includes repositioning the child prims within the linkset. Change or add whatever
additional parameters are needed for your particular application.

<lsl> // This is not a complete resizer solution; it's just a demo of
// how to call the new LSL functions.

// Set the minimum and maximum size allowed for any prim in the linkset:
//
float minPrimSize = 0.01;
float maxPrimSize = 10.0;

// Resize all the prims in the linkset. For example, to resize all
// the prims to 1% smaller, call this function with factor=0.99
// Returns TRUE if successful, or FALSE if resizing would have
// set a prim size out of bounds.
//
integer resizeLinksetWithBounds(float factor)
{
// Test to see if it's safe to change all the prim sizes:

integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
vector sz = factor * llList2Vector(params, 0);
if (sz.x < minPrimSize || sz.x > maxPrimSize ||
sz.y < minPrimSize || sz.y > maxPrimSize ||
sz.z < minPrimSize || sz.z > maxPrimSize) {
return FALSE;
}
}

// We've determined that we can safely change all the sizes, so
// let's do so now. This example assumes that llGetLinkPrimitiveParams()
// with PRIM_POSITION will return the relative offset from the root prim,
// but those details have not yet been published.

for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list oldParams = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE, PRIM_POSITION]);

list newParams = [ PRIM_SIZE, factor * llList2Vector(oldParams, 0) ];
if (linkNum > 1) {
newParams += [ PRIM_POSITION, factor * llList2Vector(oldParams, 1) ];
}

llSetLinkPrimitiveParamsFast(linkNum, newParams);
}

return TRUE;
} </lsl>

Here's a silly example of how it's used:

<lsl> // Example of how to call resizeLinksetWithBounds()
//
default
{
touch_start(integer num)
{
float factor = llPow(llFrand(2.0), 2.0); // random factor for demo
if (resizeLinksetWithBounds(factor)) {
llOwnerSay("Resized successfully by factor = " + (string)factor);
} else {
llOwnerSay("Oops, can't resize by factor " + (string)factor);
}
}
} </lsl>

===Long range plans===

The new LSL features described above are expected to appear in server version 1.38. Babbage Linden also mentioned a few additional LSL features he would like to implement sometime after 1.38, but with no guarantees if or when:

<lsl> lLinkParticleSystem()
PRIM_NAME, PRIM_DESC // for llGet/SetPrimitiveParams()
llAvatarOnLinkSitTarget()
llLinkSitTarget() </lsl>

===Also see===

* [[User:Becky_Pippen/Script_Memory_Limits| Scripter's checklist of things you can do to conserve memory]]
* [[User:Becky_Pippen/Memory_Limits_FAQ| Script memory limits FAQ]]

User:Becky Pippen/Memory Limits FAQ

2010-01-16T21:47:37Z

Becky Pippen: Added Q: Will the limits be per avatar or per region?

User:Becky Pippen/New LSL Functions

2010-01-14T04:11:03Z

Becky Pippen: minor clarifications

== New LSL Functions ==

The information in this section is preliminary and predictive, based on information given by
Babbage Linden at his Office Hours.

To help reduce the number of scripts needed for certain common operations, we will have these new
LSL functions, perhaps as early as server version 1.38:

<lsl> llGetLinkPrimitiveParams()
llSetLinkPrimitiveParamsFast() </lsl>

And possibly a new parameter ID for setting hover text with llSetLinkPrimitiveParamsFast():

<lsl> PRIM_TEXT </lsl>

===History===

Some content creators prefer to distribute their objects no-mod, yet still allow customers to resize or
retexture the linkset. Scripts can do that in a no-mod linkset, but the obvious solution using
[[llSetLinkPrimitiveParams]]() doesn't work well because of the 0.2-second delay built into the function.
To work around the delay, we have had to put a script in every child prim that can respond immediately
to a message from the root prim. When these functions become available, we will be able to do this kind of thing with a single script.

===Fixing Existing Scripts===

To fix such a script, locate the call to [[llMessageLinked]]() in the master script where it sends the link
message to the individual prims. It might look something vaguely like this:

<lsl>llMessageLinked(LINK_whatever, command_resize, (string)newSize, NULL_KEY);</lsl>

Replace that with a loop that applies whatever changes you need to each prim using
[[llSetLinkPrimitiveParamsFast]](). The prims have link numbers from 1 through [[llGetNumberOfPrims]](),
so you can make an efficient loop as shown here; just add any additional processing you
need for each prim inside the loop:

<lsl> applyChildParams(list ruleSet)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
llSetLinkPrimitiveParamsFast(linkNum, ruleSet);
}
} </lsl>

For example, to use this function to set the color and alpha of all the prims, build the parameter
list and pass it to applyChildParams() like this:

<lsl>applyChildParams([PRIM_COLOR, ALL_SIDES, <0.9, 0.8, 0.2>, 1.0]);</lsl>

However, when you only need to apply a constant rule set like this to every prim in the linkset,
then the loop above can be simplified to a single statement;

<lsl>llSetLinkPrimitiveParamsFast(LINK_SET, ruleSet);</lsl>

Or use [[LINK_ALL_OTHERS]] or [[LINK_ALL_CHILDREN]] instead of [[LINK_SET]] as appropriate.

For another example, you can make a resizer script apply relative instead of absolute size changes by
using the new function [[llGetLinkPrimitiveParams]](). The script can read each child's current size,
then apply a resize factor and use [[llSetLinkPrimitiveParamsFast]]() to set a new size. This can help
make it easy for the script to do the right thing even if reset and all its variables get reinitialized. The
following function will resize all the prims (including the root itself) by a factor:

<lsl> rescaleLinksetByFactor(float factor)
{
integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
llSetLinkPrimitiveParamsFast(linkNum,
[PRIM_SIZE, factor * llList2Vector(params, 0)]);
}
} </lsl>

But what if the function above encounters a prim that, after resized, would have a dimension outside
the legal range of 0.01m to 10.0m? That could have unfortunate consequences, so
here is a function that resizes all the prims by a specified factor but only if all the resulting
dimensions in all the prims will all be in the legal range of 0.01m to 10.0m. If any dimension in
any prim would go out of those bounds, the function will return FALSE without resizing anything.
This example also includes repositioning the child prims within the linkset. Change or add whatever
additional parameters are needed for your particular application.

<lsl> // This is not a complete resizer solution; it's just a demo of
// how to call the new LSL functions.

// Set the minimum and maximum size allowed for any prim in the linkset:
//
float minPrimSize = 0.01;
float maxPrimSize = 10.0;

// Resize all the prims in the linkset. For example, to resize all
// the prims to 1% smaller, call this function with factor=0.99
// Returns TRUE if successful, or FALSE if resizing would have
// set a prim size out of bounds.
//
integer resizeLinksetWithBounds(float factor)
{
// Test to see if it's safe to change all the prim sizes:

integer linkNum;
for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list params = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE]);
vector sz = factor * llList2Vector(params, 0);
if (sz.x < minPrimSize || sz.x > maxPrimSize ||
sz.y < minPrimSize || sz.y > maxPrimSize ||
sz.z < minPrimSize || sz.z > maxPrimSize) {
return FALSE;
}
}

// We've determined that we can safely change all the sizes, so
// let's do so now. This example assumes that llGetLinkPrimitiveParams()
// with PRIM_POSITION will return the relative offset from the root prim,
// but those details have not yet been published.

for (linkNum = llGetNumberOfPrims(); linkNum >= 1; --linkNum) {
list oldParams = llGetLinkPrimitiveParams(linkNum, [PRIM_SIZE, PRIM_POSITION]);

list newParams = [ PRIM_SIZE, factor * llList2Vector(oldParams, 0) ];
if (linkNum > 1) {
newParams += [ PRIM_POSITION, factor * llList2Vector(oldParams, 1) ];
}

llSetLinkPrimitiveParamsFast(linkNum, newParams);
}

return TRUE;
} </lsl>

Here's a silly example of how it's used:

<lsl> // Example of how to call resizeLinksetWithBounds()
//
default
{
touch_start(integer num)
{
float factor = llPow(llFrand(2.0), 2.0); // random factor for demo
if (resizeLinksetWithBounds(factor)) {
llOwnerSay("Resized successfully by factor = " + (string)factor);
} else {
llOwnerSay("Oops, can't resize by factor " + (string)factor);
}
}
} </lsl>

===Also see===

* [[User:Becky_Pippen/Script_Memory_Limits| Scripter's checklist of things you can do to conserve memory]]
* [[User:Becky_Pippen/Memory_Limits_FAQ| Script memory limits FAQ]]

User:Becky Pippen/Text Storage

2010-01-11T19:43:43Z

Becky Pippen: minor tweaks

== Text strings in scripts ==

===Terminology===

Be warned — these terms are not always used correctly and consistently in the LSL wikis. Here's the terminology from their various standards:

'''[http://en.wikipedia.org/wiki/Unicode Unicode]''' is a character set of several thousand character glyphs and their assigned numeric ID codes. The numeric codes are 21-bit integers in the range 0 through 0x10ffff, although a few numbers in that range have special meaning other than character data. How are those 21-bit numbers stored in memory? That's what UTF-8 and UTF-16 are all about.

'''[http://en.wikipedia.org/wiki/Utf-8 UTF-8]''' and '''[http://en.wikipedia.org/wiki/Utf-16 UTF-16]''' are two ways to represent the Unicode numeric codes in memory. UTF-8 encodes a Unicode ID number in a variable-length sequence of one to four bytes. UTF-16 encodes most characters in 16 bits, and some in 32 bits.

For a summary of Unicode character set and examples of the UTF-8 and UTF-16 storage formats, see: [[Unicode_In_5_Minutes]].

LSO-compiled scripts store strings internally in memory in UTF-8 format and Mono uses UTF-16, but all that should be transparent to the script for most purposes. The main impact for the script and scripter is the amount of memory used. [[LSL_Script_Memory|This page]] says that globally scoped strings use one byte per character in LSO and two bytes per character in Mono, which is true for strings containing only 7-bit ASCII characters. When the strings contain mostly international characters outside the ASCII range, then the memory consumption for UTF-8 in LSO and UTF-16 in Mono will both be close to two bytes per character, and in some cases the UTF-8 will be longer if there are many characters that require the three-byte or four-byte forms of UTF-8 encoding.

===So, summarize, ok?===

So, if using only an ASCII character set and compiling with Mono, we can possibly reduce the memory requirements to near LSO levels through clever encoding. Otherwise any attempt made to compress text will probably use more instruction code space than the amount of memory saved.

===ASCII text compression in Mono===

This technique applies if your script uses only ASCII characters and only if compiling with Mono. We'll take the ASCII characters, two at a time, convert them to their Unicode numeric ID codes (which for these characters are identical to their ASCII numeric codes), combine them into a 14-bit integer, add a bias that so that the 14-bit numbers all are inside a valid range of Unicode characters, then convert it into a single Unicode character. This will result in a 16-bit Unicode character that bears no resemblance to the two ASCII characters that it encodes.

The decoding process is just the reverse — convert a Unicode character into its numeric value which will be a 14-bit integer, divide it into two 7-bit numbers, and convert that back to a string of two characters.

For encoding, we need a couple of functions — one to convert a single Unicode character to its numeric ID, and one to convert a 14-bit number into a single Unicode character. Here's the former:

<lsl> // Given a single character c, this returns its Unicode ID number
// This works only for character codes 0 through 0xffff.
//
integer charToUnicodeIdNumber(string c)
integer cInt = llBase64ToInteger(llStringToBase64(c));

if (!(cInt & 0x80000000)) {
// UTF-8 single-byte form
cInt = cInt >> 24;
} else {
if ((cInt & 0xe0000000) == 0xc0000000) {
// two-byte UTF-8 form: 110v vvvv 10vv vvvv
cInt = ((cInt & 0x1f000000) >> 18) |
((cInt & 0x003f0000) >> 16);
} else {
// assume three-byte UTF-8 form: 1110 vvvv 10vv vvvv 10vv vvvv
cInt = ((cInt & 0x0f000000) >> 12) |
((cInt & 0x003f0000) >> 10) |
((cInt & 0x00003f00) >> 8);
} // else ignore the 4-byte UTF-8 form
} </lsl>

This works because the function [[llStringToBase64]]() converts the character c into UTF-8 format first, then into base64 encoding. This isn't documented well, so let's be clear about it — regardless if running in LSO where text is UTF-8 or in Mono where text is UTF-16, the function [[llStringToBase64]]() will return a base64-encoded form of the UTF-8 encoding of its argument.

This function is very similar to the function
<lsl> integer UTF8ToUnicodeInteger(string input); </lsl>
found in [[Combined_Library]]. I'm offering my own version here for two reasons: (1) I've named the function to emphasize that it takes a single character as string input, and to remove "UTF-8" from the function name because the role of UTF-8 in the function is only as a necessary intermediate encoding. The function is meant to work with LSO or Mono so that the underlying internal encoding of the input argument is transparent; and (2) my version is a little easier to read (at the expense of being a few bytes longer).

And just for completeness, if you need to revise the function to also work with Unicode ID codes above 0xffff, the additional else clause looks like this:

<lsl> . . .
} else {
// four-byte UTF-8 form: 1111 0vvv 10vv vvvv 10vv vvvv 10vv vvvv
cInt = ((cInt & 0x07000000) >> 6) |
((cInt & 0x003f0000) >> 4) |
((cInt & 0x00003f00) >> 2) |
(cInt & 0x0000003f);
} </lsl>

Next, we need a way to combine two 7-bit character codes into a single Unicode character. We'll simply combine two numbers to make a 14-bit integer, then convert that to a Unicode character using the function encode15BitsToChar() found in [[User:Becky_Pippen/Numeric_Storage]]:

For decoding, we'll use the function decodeCharTo15Bits() found in [[User:Becky_Pippen/Numeric_Storage]] to get our 14-bit number, then split that into two 7-bit numbers, then use [[llUnescapeURL]]() to turn those into two characters in a string.

===Code Example===

First, we need to run a benchmark to measure memory usage in the normal uncompressed way. Simply put a bunch of ASCII text into a notecard and drop it into a prim with this script. It will concatenate all the notecard lines into a single global string named bigText. I used the text from http://www.gutenberg.org/files/6274/6274.txt as the notecard text. It runs out of memory after saving 1063 notecard lines:

<lsl>
integer lineNumber;
string notecardName = "ASCII text";
integer linesRead;
string bigText;

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string data)
{
if (data != EOF) {
bigText += data;
llOwnerSay((string)(++linesRead) + ":" + data);
llGetNotecardLine(notecardName, lineNumber++);
}
}
}
</lsl>

Now we can compare — here's the same notecard reader script using ASCII compression. Even though the added compression functions consume about 3K of program space, we can now store 1854 lines. '''That's 74% more text using compression.'''

<lsl> // Demo of ASCII compression in Mono scripts
// By Becky Pippen, 2009, contributed to Public Domain

// Report memory free and the change from the last report:
//
integer lastFree;

mem(string label)
{
integer newFree = llGetFreeMemory();
integer change = lastFree - newFree;
llOwnerSay((string)newFree + " free, change = " + (string)change);
lastFree = newFree;
}

// Converts n = [0..0xff] to two hex characters
//
string hexChar2(integer n)
{
string hexChars = "0123456789abcdef";
return llGetSubString(hexChars, n >> 4, n >> 4) +
llGetSubString(hexChars, n & 0xf, n & 0xf);
}

// Given a single character c, this returns its Unicode ID number
// This works only for character codes 0 through 0xffff.
// For a more compact alternative, see UTF8ToUnicodeInteger()
// found in http://wiki.secondlife.com/wiki/Combined_Library .
//
integer charToUnicodeIdNumber(string c)
{
integer cInt = llBase64ToInteger(llStringToBase64(c));

if (!(cInt & 0x80000000)) {
// UTF-8 single-byte form
cInt = cInt >> 24;
} else {
if ((cInt & 0xe0000000) == 0xc0000000) {
// two-byte UTF-8 form: 110v vvvv 10vv vvvv
cInt = ((cInt & 0x1f000000) >> 18) |
((cInt & 0x003f0000) >> 16);
} else {
// assume three-byte UTF-8 form: 1110 vvvv 10vv vvvv 10vv vvvv
cInt = ((cInt & 0x0f000000) >> 12) |
((cInt & 0x003f0000) >> 10) |
((cInt & 0x00003f00) >> 8);
} // else ignore the 4-byte UTF-8 form
}

return cInt;
}

// This is a memory-savings technique for use with Mono-compiled LSL scripts.
// (It probably works in classic LSO too, but not as efficiently.) This technique
// stores 15 bits of information in each 16-bit Unicode character. Use the
// encode function below to convert any 15-bit data to a Unicode character, and
// use the decode function to convert it back to the original 15-bit data.
//
// This example maps the data values 0 through 0x7fff to the Unicode
// characters U-001000 through U-008fff. Use the matching function
// decodeCharTo15Bits() to decode the Unicode character back into the original
// 15-bit number.
//
// The technique used here is very similar to the technique used in the "Base 32768
// Script" in http://wiki.secondlife.com/wiki/Key_Compression .

// Convert any 15-bit integer into a single Unicode character
//
string encode15BitsToChar(integer num)
{
// Check the incoming range

if (num < 0 || num >= 0x8000) {
// illegal input -- do whatever is appropriate
return "�";
}

// Bias the incoming numeric value by 0x1000 to avoid illegal Unicode codes:

num += 0x1000;

// Construct an escaped hex UTF-8 representation and return
// it as a Unicode character

return llUnescapeURL(
"%" + hexChar2(0xe0 + (num >> 12)) +
"%" + hexChar2(0x80 + ((num >> 6) & 0x3f)) +
"%" + hexChar2(0x80 + (num & 0x3f)));
}

// This is the inverse of encode15BitsToChar(), supra, q.v.
// This expects a single 16-bit Unicode character that was created by
// encode15BitsToChar() and returns the 15-bit numeric value used to create it.
// The 15-bit return value will always be in the range 0x0000 - 0x7fff.
//
integer decodeCharTo15Bits(string ch)
{
string utf8 = llEscapeURL(ch); // convert to escaped hex UTF-8

return
(((integer)("0x" + llGetSubString(utf8, 1, 2)) & 0x1f) << 12) +
(((integer)("0x" + llGetSubString(utf8, 4, 5)) & 0x3f) << 6) +
((integer)("0x" + llGetSubString(utf8, 7, 8)) & 0x3f) - 0x1000;
}

// Returns a Unicode string that encodes twice as many ASCII characters.
// Use the matching function decompressAscii() to expand it back into
// the original ASCII.
//
string compressAscii(string s)
{
integer len = llStringLength(s);

// Append a space if needed to make s an even number of chars
if (len % 2) {
s += " ";
++len;
}

string encodedChars;
integer i;
for (i = 0; i < len; i += 2) {
encodedChars += encode15BitsToChar(
charToUnicodeIdNumber(llGetSubString(s, i, i)) << 7 |
charToUnicodeIdNumber(llGetSubString(s, i+1, i+1)));
}

return encodedChars;
}

// This is the inverse of compressAscii()
//
string uncompressAscii(string s)
{
string result;

integer len = llStringLength(s);
integer i;
for (i = 0; i < len; ++i) {
integer cInt15 = decodeCharTo15Bits(llGetSubString(s, i, i));
result += llUnescapeURL("%" + hexChar2(cInt15 >> 7) +
"%" + hexChar2(cInt15 & 0x7f));
}

return result;
}

integer lineNumber;
string notecardName = "ASCII text";
integer linesRead;
string bigText;

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string data)
{
if (data != EOF) {
string compressedLine = compressAscii(data);
bigText += compressedLine;
llOwnerSay((string)(++linesRead) + ":" + uncompressAscii(compressedLine));
llGetNotecardLine(notecardName, lineNumber++);
}
}
}
</lsl>

===Also see===

For more ideas about compressing data and other memory-savings techniques, see
* [[User:Becky_Pippen/Numeric_Storage| Scripting techniques for storing arbitrary binary data without lists]]
* [[User:Becky_Pippen/Script_Memory_Limits| Memory limits FAQ and Checklist for memory reduction]]
* [[User:Becky_Pippen/Hashing| Hashing for memory reduction]]

User:Becky Pippen/Hashing

2010-01-11T18:37:08Z

Becky Pippen: typos and formatting

===Hashing to conserve memory===

Hashing takes a longer item such as an avatar name or [[UUID]] and maps it to something smaller, like an integer or a shorter string. It's compact, but the trade-off is that different inputs can possibly map to the same hash value by accident.

Here's an illustration of how much memory we can save by hashing UUIDs in a Mono script — from 72 bytes in their native form to just a few bytes each. This illustrates techniques discussed in the rest of this article:

[[Image:Key hash-1.jpg|800px]]

There are two problems to solve to make hashing work in LSL: (1) designing a hash function that makes hash codes of the right size, evenly distributed across the hash space, and (2) storing the hash codes efficiently without suffering the overhead of lists. Those two aspects are treated separately below.

===Designing the hash function===

A hash size too small increases the chance of a hash collision. That's when multiple values of the real data map to the same hash value. A hash size too large wastes memory.

Calculating the probability of hash collisions is similar to calculating the [http://betterexplained.com/articles/understanding-the-birthday-paradox/ "Birthday Paradox" probabilities]. The probability that there will be a duplicate among N random hashes of W bits each is approximately:

P = 1.0 - e ^ -(N^2 / (2 * 2^W))

The table below shows some examples of the probability ''P'' of having at least one duplicate among ''N'' hashes of various sizes. For example, there is a probability of 0.0001 that there will be a duplicate in a set of 1000 32-bit hash codes.

{| border="1"
|align="center"|
|align="center"|15-bit
|align="center"|16-bit
|align="center"|30-bit
|align="center"|32-bit
|align="center"|45-bit
|-
|align="center" | ''N''
|align="center" | ''P''
|align="center" | ''P''
|align="center" | ''P''
|align="center" | ''P''
|align="center" | ''P''
|-
|align="right" | 100
|align="left" | 0.14
|align="left" | 0.07
|align="left" | 0.000005
|align="left" | 0.000001
|align="left" | 0.0000000001
|-
|align="right" | 200
|align="left" | 0.46
|align="left" | 0.26
|align="left" | 0.00002
|align="left" | 0.000005
|align="left" | 0.0000000006
|-
|align="right" | 500
|align="left" | 0.978
|align="left" | 0.85
|align="left" | 0.0001
|align="left" | 0.00003
|align="left" | 0.0000000004
|-
|align="right" | 1000
|align="left" | 1.0
|align="left" | 0.9995
|align="left" | 0.0005
|align="left" | 0.0001
|align="left" | 0.00000001
|-
|align="right" | 2000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.001
|align="left" | 0.0005
|align="left" | 0.00000006
|-
|align="right" | 5000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.01
|align="left" | 0.003
|align="left" | 0.0000007
|-
|align="right" | 10000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.05
|align="left" | 0.01
|align="left" | 0.000001
|-
|align="right" | 25000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.26
|align="left" | 0.07
|align="left" | 0.000009
|-
|align="right" | 50000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.69
|align="left" | 0.25
|align="left" | 0.00004
|}

====Hashing UUIDs====

It appears that most [[UUID]]s in SL are constructed with random bits (or sufficiently so for our purposes) in the first six bytes (first 12 hex digits) of the UUID. This lets us make a trivial hash function by extracting some of the hex digits from the UUID. For example, this code extracts the first eight hex digits as a hash:

<lsl> string hash(key k)
{
return llGetSubString((string)k, 0, 7); // first 8 hex chars
} </lsl>

That gives us a hash code with 32 bits of information content (eight hex characters at four bits each).

At this point you might wonder why not reduce the hash code to a regular 32-bit integer that only uses four bytes of memory. Unfortunately, we can't do anything with integers except store them in a list, and that makes any string-based solution more efficient, as described below.

If you have any concern that the first few bytes of the UUID are not really as random as you would like, you can make an MD5 hash out of the UUID, then extract some hex digits from the MD5 hash string to make a shorter hash. For example, this hash function extracts eight hex digits from the MD5 hash of the UUID:

<lsl> string hash(key k)
{
return llGetSubString(llMD5String((string)k, salt), 0, 7);
} </lsl>

Any salt value works in the code above, as long as it's consistent. Choose an unguessable value for salt if you want your hashing function to yield different values than other scripts using the same code snippet above. Think of the salt value as serving a purpose similar to the seed value used in pseudo-random number generators.

We can make the hash code even smaller by treating the eight hex digits as a 32-bit numeric value and converting that number into a six-character string using [http://en.wikipedia.org/wiki/Base64 base64] representation. Something like this:

<lsl> string hash(key k)
{
return llGetSubString(llIntegerToBase64(
(integer)("0x" + llGetSubString((string)k, 0, 7))), 0, 5);
} </lsl>

In other words, the same information contained in eight hex characters fits into six base64 characters.

====Hashing avatar names and other strings====

Almost anything can be hashed using [[llMD5String]](). That's a function historically used for encryption and security, and it's useful for our hashing needs because it nicely distributes all possible input values across its output range. The MD5 conversion gives us a long string of hex characters, and we can simply extract however many we want to use for a hash. The longer the hash, the less likely there will be a hash collision but the more memory it will consume. This example extracts twelve hex characters from the MD5 result to form a hash code worth 48 bits of information:

<lsl> string hash(string input)
{
string md5 = llMD5String(input, salt);
return llGetSubString(md5, 0, 11);
} </lsl>

The problem with this hash function is that the average avatar name in SL is about 14 characters, so a twelve-character hash code is not a dramatic improvement. And then if we store these hash codes in a list, we eat up additional memory with list overhead. To save memory, we need to think of these hash codes as containing so many bits of information, not as characters. Then we need to think of a way to store those bits of information in a more compact form, i.e., without using lists. The next section describes a way of encoding information into Unicode character strings.

===Avoiding list overhead===

It's very difficult to store data compactly in Mono scripts — there are no arrays; lists incur 20+ bytes of overhead per list element; and string data uses a minimum of two bytes per character. About the only way we have to encode arbitrary data in memory is by encoding the information as Unicode characters.

Using the functions in [[User:Becky_Pippen/Numeric_Storage| this article]], you can store 15 bits of arbitrary data in each 16-bit Unicode character. It's not quite as straightforward as interpreting the 15 bits as the Unicode character ID because certain Unicode character codes may not be used. For example, we can't simply use the Unicode character ID 0x000000 to store a numeric value of zero, because 0x000000 is an illegal Unicode character code. So we have to remap any 15-bit number we want to store into some range of legal Unicode characters. The functions [[User:Becky_Pippen/Numeric_Storage#Source_code_example|encode15BitsToChar()]] and [[User:Becky_Pippen/Numeric_Storage#Source_code_example|decodeCharTo15Bits()]] do this remapping by adding 0x1000 to the 15-bit number to make a Unicode character ID in the range 0x1000 through 0x8fff. The result is that a 15-bit hash code can be stored as one character; a 30-bit hash code in two characters, and a 45-bit hash code in three Unicode characters.

===Searching for hash codes when concatenated in a string===

If the consequence of a false positive match is an acceptable risk, then searching a long string for a given hash code can be simplified to a call to [[llSubStringIndex]](). In this example, hash codes are 45-bit values encoded as three Unicode characters each. All hash codes are concatenated into one long string named hashCodes:

<lsl> // Returns logical index of the given hash code
// or -1 if not found

string hashCodes; // all hash codes are concatenated here

integer findHash(string hashCode)
{
integer index = llSubStringIndex(hashCodes, hashCode);
if (index != -1) {
index /= 3; // because each hash code is three Unicode chars
}

return index;
} </lsl>

The code above will find a false match if the hashCode value accidentally randomly matches characters that span two different hash codes in the hashCodes string. Your script can detect false positives by checking if the match occurred on a boundary of hashSize bytes:

<lsl> // Returns logical index of the given hash code
// or -1 if not found

string hashCodes; // all hash codes are concatenated here
integer hashSize = 6; // number of chars in each hash code

integer findHash(string hashCode)
{
integer index = llSubStringIndex(hashCodes, hashCode);
if (index != -1 && (index % hashSize)) {
// this is a false match.
// fall back to a loop search, or whatever is appropriate
} else if (index != -1) {
// a valid match
index /= hashSize;
}

return index;
} </lsl>

===Code Example===

Here is a complete example of a script that stores avatar names read from a notecard. For each name read, the script searches its memory to see if that avatar name has been encountered before. If not, it adds the name to the list. First let's get a benchmark of the memory consumption using the naive approach of storing the names as strings in a global list. The notecard I used for a test contains 2000 actual SL avatar names, one per line. There are only 1500 unique names in the notecard, so 500 of them are duplicates scattered throughout.

<lsl> integer lineNumber;
string notecardName = "names";
integer namesSaved;
list hashedNames;

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string avName)
{
if (avName != EOF) {
if (llListFindList(hashedNames, [avName]) == -1) {
hashedNames += [avName];
llOwnerSay((string)(++namesSaved) + ": " + avName + ", " +
(string)llGetFreeMemory() + " free");
} else {
llOwnerSay("duplicate: " + avName);
}

llGetNotecardLine(notecardName, lineNumber++);
}
}
} </lsl>

The data ate up 56000 bytes of available memory and ran out of memory after saving 1137 unique names. That works out to about 49 bytes consumed per item. That's very close to what we could have predicted in Mono, based on the data in [[LSL_Script_Memory|this page]] — an average of 14 characters per avatar name uses 28 bytes of memory in Mono, plus 22 bytes of overhead per list element for a total of 28+22=50 bytes each.

Here is the same script but with the functions needed to save the avatar identities as 45-bit hash codes encoded as three Unicode characters each. It stores 1500 hashed names in just 9000 bytes. Even adding the 2500 extra bytes of program code to support hashing, that comes out to a total 11500 bytes consumed to store 1500 avatar identities, or 7.7 bytes each, compared to 49 bytes each on the average for the naive list approach above. '''That's an 84% net reduction in memory consumption.'''

<lsl> // Demo - store avatar identities as 45-bit hashes encoded in 3 Unicode
// chars each, concatenated into one string.
// By Becky Pippen, 2010, contributed to the public domain.

// Converts n = [0..0xff] to "%" + two hex characters
//
string escapeHexChar(integer n)
{
string hexChars = "0123456789abcdef";
return "%" +
llGetSubString(hexChars, n >> 4, n >> 4) +
llGetSubString(hexChars, n & 0xf, n & 0xf);
}

// Encode 15 bits of data as a single Unicode character. Use decodeCharTo15Bits()
// to recover the 15-bit data.
//
// The technique used here is very similar to the technique used in the "Base 32768
// Script" in http://wiki.secondlife.com/wiki/Key_Compression .

string encode15BitsToChar(integer num)
{
// Use only the lower 15 bits and bias by 0x1000 to avoid illegal Unicode IDs:

num = 0x1000 + (num & 0x00007fff);

// Construct an escaped hex UTF-8 representation and
// return it as one Unicode character:

return llUnescapeURL(
escapeHexChar(0xe0 + (num >> 12)) +
escapeHexChar(0x80 + ((num >> 6) & 0x3f)) +
escapeHexChar(0x80 + (num & 0x3f)));
}

//****************************************
// demo -- store avatar identities as compressed 45-bit hashes of their name

integer lineNumber; // for the notecard reader
string notecardName = "names"; // notecard of av names, one per line
integer namesSaved; // count how many successfully saved
string hashedNames; // all the hashes get concatenated in this string
integer hashSize = 3; // num of Unicode chars per encoded hash code

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string avName)
{
if (avName != EOF) {
// Pick off 48 bits of information to start with:
string md5 = llMD5String(avName, 0);
integer n1 = (integer)("0x" + llGetSubString(md5, 0, 7));
integer n2 = (integer)("0x" + llGetSubString(md5, 8, 11));

// Map 45 of the bits into three characters. We cannot encode Unicode
// directly from Unicode IDs, but we can do it by constructing an escaped
// hex UTF-8 string representation and converting that to Unicode
//
// |------------------ n1 ------------------| |------- n2 -------|
// x000 0000 0000 0000 x000 0000 0000 0000 x000 0000 0000 0000
// |------char1------| |------char2------| |------char3------|

string encoded3Chars =
encode15BitsToChar(n1 >> 16) +
encode15BitsToChar(n1) +
encode15BitsToChar(n2);

integer idx = llSubStringIndex(hashedNames, encoded3Chars);
if (idx == -1) {
// this is a new one, so save it
hashedNames += encoded3Chars;
llOwnerSay((string)(++namesSaved) + ": " + avName + ", " +
(string)llGetFreeMemory() + " free");
} else if (idx % hashSize) {
llOwnerSay("WARNING!!! False match for " + avName);
} else {
llOwnerSay("Duplicate, already saved: " + avName);
}

llGetNotecardLine(notecardName, lineNumber++);
}
}
} </lsl>

===Also see===

For more ideas about compressing bits into Unicode strings, see
* [[User:Becky_Pippen/Numeric_Storage| Scripting techniques for storing arbitrary binary data without lists]]
* [[User:Becky_Pippen/Script_Memory_Limits| Memory limits FAQ and Checklist for memory reduction]]

If you need to store many keys without losing any bits, see the suggestions at [[Key_Compression]].

User:Becky Pippen/Measure Script Memory Usage

2010-01-10T06:21:53Z

Becky Pippen: additional info

=== Measuring Script Memory Usage ===
In addition to upcoming new tools that will let us conveniently measure scripts in use,
scripters can also use [[llGetFreeMemory]]() to make more detailed measurements of how specific functions or
statements affect memory usage.
The memory a script uses is:
* Starting memory (65536 bytes for [[Mono]], 16384 for [[LSO|LSL]])
* minus program statements (e.g., a = 2;)
* minus static (pre-defined) variables (e.g., integer a;)
* minus dynamic (created when running) data and overhead (e.g., f("a" + "b") )
Here is an LSL statement that reports how much free memory you have at the moment it's called:

<lsl>llOwnerSay((string)llGetFreeMemory() + " bytes free");</lsl>

To report how much memory is used (instead of free) in a Mono script, subtract
free from total memory:

<lsl>llOwnerSay((string)(65536 - llGetFreeMemory()) + " bytes used");</lsl>

For LSL-compiled scripts, change 65536 to 16384.

It makes a difference where you place [[llGetFreeMemory]]() in your script. To see how
much memory is used by the script's program code and static (pre-defined) variables,
put [[llGetFreeMemory]]() as the first line in [[state_entry]]() or [[on_rez]]() in the default
state. To see how much memory your script used including all runtime dynamic data,
call [[llGetFreeMemory]]() as the last statement executed after your script has created
all the data it's going to.

To see how much memory is used by a one or a few program statements,
measure the memory before and after and take the difference. Be aware that your
instrumentation for measuring memory might itself consume some memory
if it uses variables or function calls, so do all that prior to the measurement.

Also be aware that the way the LSL and Mono back ends allocate memory (and
perhaps from fluctuations due to garbage collection), you might
get varying results from individual measurements, so it's sometimes useful to
take an average.

For example, suppose we want to measure how much memory gets consumed each time
your script saves a short string to a global list. Here is the statement that we want to
measure:

<lsl>aList += "hello"; // appends one 5-char string to the list</lsl>

To measure the memory used by this statement, we'll average the memory consumption over a hundred loops.
We'll also globally declare the temporary variables we'll need for the measurement
so that between the start and end of the test, there will be no extra variables allocated
or function calls made except the code being measured:

<lsl>
list aList;
integer startFreeMem;
integer endFreeMem;

default
{
touch_start(integer num)
{
integer loops = 100;
startFreeMem = llGetFreeMemory();

while (--loops >= 0) {
aList += "hello"; // appends one 5-char string to the list
}

endFreeMem = llGetFreeMemory();
llOwnerSay("Change in free mem: " + (string)(startFreeMem - endFreeMem));
}
}</lsl>

By the way, the results I got from this test shows that it takes 3486 bytes of memory to
append 100 copies of "hello" to a global list when compiled with LSL, and 752
bytes when compiled with Mono. These results are a little different than those given in
[[LSL_Script_Memory|this page]], and that's why it can
be illuminating to make these measurements in your own scripts. (In this example, the
[[LSL_Hacks|LSL assignment hack]] would help minimize memory consumption for the LSO case.)
===Caveats and geekystuffs===
There are several reasons why [[llGetFreeMemory]]() can give unexpected results:
* '''In Mono, memory may be allocated in blocks''' -- For example, a small change in the script might cause the free memory to change by 512 bytes. To get a better idea of the average memory used by a particular script construct, repeat it a number of times in the script and divide by the number of instances. For more information, see {{Jira|SVC-4387}}.
* '''[[llGetFreeMemory]]() reports the low-water mark before garbage collection''' -- For example, if you fill a list or string with thousands of bytes of data and then clear the list or string, [[llGetFreeMemory]]() will continue to report the lowest amount of memory that occurred and does not reflect the fact that a bunch of memory might be available if only the garbage collector would collect it. To reduce lag, the garbage collector typically frees up memory only when the script runs out of memory and more memory is needed. This is also illustrated in the code example at the end of this article. For more information, see the comments at:
** [[llGetFreeMemory]]()
** {{Jira|SVC-4387}}
** {{Jira|SVC-1852}}
* '''Memory fragmentation''' -- The order in which memory is allocated and freed can cause [[llGetFreeMemory]]() to act differently. In LSO, it might be reporting the largest single block of free memory instead of the total free bytes. It's not clear how fragmentation might affect [[llGetFreeMemory]]() in Mono. For more information, see the comments in:
** {{Jira|SVC-116}}
** {{Jira|SVC-168}}
* '''First run different than a reset''' -- In Mono, the amount of free memory reported by [[llGetFreeMemory]]() as the first line in [[state_entry]]() to be different on the first run after compiling compared to subsequent runs after a script reset.
* '''Mischievous spirits in Mono''' -- Even Mono experts describe Mono's memory management and garbage collection as squirrely and non-deterministic at best, so expect a few puzzling results in Mono.

===Code example===
If you find yourself making lots of measurements and comparisons, you might find a test scaffolding useful. Here is an example of some things you can do. To run your own tests, replace the lines below in touch_start() with your own tests, using the existing code as examples. Insert a call to mem() in between each test. The results in the chat log will be easy to read, and will also automatically log if the tests were run on Mono or LSO so you won't have to remember later.
<lsl> // Demo of a memory-usage reporter
//
// To use: call initMemReporter() in the start of the script, then
// call mem() at any time to report memory used and amount of change.
// This adjusts the numbers automatically depending on whether the
// script is compiled for Mono or classic LSO.
//
integer isMono; // set at runtime to TRUE if Mono VM, FALSE if LSO
integer totalMem; // set at runtime to 65536 or 16384
string vm; // set at runtime to "Mono" or "LSO"
integer lastUsedMem;

// Call this once at the start of the script, then call mem()
// at any time to report memory usage. This function caches a
// few variables so that they don't have to be recomputed in
// mem() every time.
//
initMemReporter()
{
// Test if we're running on LSO or Mono VM using
// the difference between the two reported in
// https://jira.secondlife.com/browse/SVC-3760

isMono = llToLower("Ü") != "Ü";

// Establish total memory:

if (isMono) {
totalMem = 65536;
vm = "(Mono)";
} else {
totalMem = 16384;
vm = "(LSO)";
}

lastUsedMem = totalMem - llGetFreeMemory();
}

// Report the memory used and the change from the last report
//
mem(string label)
{
integer freeMem = llGetFreeMemory();
integer usedMem = totalMem - freeMem;

llOwnerSay(
vm +
" used=" + (string)usedMem +
", free=" + (string)freeMem +
", change=" + (string)(lastUsedMem - usedMem) +
" \t" + label);

lastUsedMem = usedMem;
}

default
{
state_entry()
{
initMemReporter();
mem("initial conditions");
}

touch_start(integer num)
{
integer a;
float f;
list intList;
intList = [];
integer LOOPS = 1000;
integer i = LOOPS;
mem("Start of tests");

//************* Test 1
intList += [0];
mem("after adding the first element to a list");

//************* Test 2
while (--i >= 0) {
intList += 0;
}
mem("after filling a list with " + (string)LOOPS + " zeros");

//************* Test 3
intList = [];
mem("after clearing the previous list");

//************* Test 4
for (i = LOOPS; --i >= 0; ) {
intList += 0;
}
mem("after filling the list again with " + (string)LOOPS + " zeros");
}
} </lsl>
The results in Mono are:
<lsl> (Mono) used=6552, free=58984, change=-18 initial conditions
(Mono) used=6668, free=58868, change=-116 Start of tests
(Mono) used=6668, free=58868, change=0 after adding the first element to a list
(Mono) used=25938, free=39598, change=-19270 after filling a list with 1000 zeros
(Mono) used=26660, free=38876, change=-722 after clearing the previous list
(Mono) used=26660, free=38876, change=0 after filling the list again with 1000 zeros </lsl>

===Also see===
For ways to reduce memory usage in scripts, see [[User:Becky_Pippen/Script_Memory_Limits| this checklist of things you can do]].

User:Becky Pippen

2010-01-06T22:36:58Z

Becky Pippen: minor formatting

== About ==
I love helping new residents get addicted... er, I mean acclimated to Second Life. Here are some notes I've picked up along the way that might be of help.
== SL Glossary ==
[http://www.inkwelle.com/glossary_nci.shtml Second Life's most complete glossary]
== What is Mono? ==
=== John and Mary ===
John and Mary are LSL scripters. John prefers the old-fashioned way of doing things, while Mary enjoys all the latest new technology, like Mono. They both write LSL scripts. John runs his scripts under the old way, and Mary runs hers using Mono.

When John writes an LSL script and clicks the Save button, the client viewer compiles the script into proprietary bytecode and uploads it to the servers. The server runs the script by using a proprietary interpreter to interpret the bytecode. It runs slow.

Mary writes the identical script -- no change in the LSL language syntax. When she presses "Save", the client uploads her script text to the servers where it gets compiled into standardized CIL assembly language. (CIL is a bytecode that originally came from Microsoft's .NET technology.) Because the Linden servers are Linux machines, there's no .NET framework available to run the CIL code. So the servers use the open-source Mono framework to execute the CIL. Mono includes an open-source JIT ("Just in Time") compiler that converts the CIL bytecode into machine code as it's needed, and that compiled machine code is what makes the script execute faster than the old way.
=== How it all Flows ===
Old way:
LSL ---> LSL compiler ---> proprietary bytecode ---> LSL bytecode interpreter

New way:
LSL ---> LSL compiler |
C# (future) ---> C# compiler | ---> CIL bytecode ---> Mono CIL execution engine
Other languages (future) ---> other compiler |
=== Do Scripts Running in Mono Get More Memory? ===
Yes, it's true that each Mono script gets 64K of memory to use. Non-Mono scripts have to fit inside 16K of memory. (That's compiled code plus stack plus heap.) Unfortunately, Mono-compiled code is a bit of a memory hog and can take up to 4 times as much memory as the old runtime environment. So, scripts using Mono end up with a little more memory to play with depending on the code-to-data ratio, but not four times as much. The advantage to the servers is that small Mono scripts only consume as much server memory as they actually use, while the older LSL virtual machine had to allocate a chunk of 16K of memory to every script regardless of how little memory it actually needed.
=== Evolving Terminology ===
LSL - Used to refer to the whole system -- the language, the front-end compiler, and the back-end interpreter. Now it's confusing because it's used in one of two ways and its meaning depends on the context: (1) LSL is the language, the source code, which has not changed with Mono. E.g., "Take this LSL script and compile it with Mono and it will run faster." Or (2) LSL refers to the old compiler front-end and interpreter virtual machine back-end. E.g., "When I compile this script with LSL it runs very slowly." Both meanings are used in the sentence, "This LSL script was compiled with LSL, but that LSL script was compiled with Mono."

The term LSO refers to the bytecode generated by the traditional LSL compiler and executed by the old LSL runtime, and is a term that can be used to distinguish the old LSL tool set from the Mono tool set.
=== Can We Use Other Languages? ===
Mono just runs CIL bytecode. It doesn't know or care what the original language was. At this time (mid-2008) only LSL source code can be compiled into CIL and run on Mono. But maybe someday we will be able to compile C# and possibly other languages into CIL which will run under Mono. A single object could contain scripts that originally were written in different languages.

The LSL language -- the source syntax -- will probably be supported for a very long time.

However, the servers will support both back-ends for a very long time -- the one that executes the old proprietary LSL bytecode, and the new Mono virtual machine that executes standard CIL. All the millions of existing LSL scripts compiled the old way will continue to run indefinitely. New LSL scripts may be compiled using the old LSL compiler or the new Mono compiler.
=== What To Expect After Mono Hits the Main Grid ===
* '''''Old LSL scripts already compiled:''''' will continue to run indefinitely. You don't have to do a thing.

* '''''Any LSL script if you have the source code:''''' can be recompiled under the old LSL compiler or the new Mono compiler, at your choice, for a long time to come.

* '''''C# and other languages:''''' probably added at some future time.

== LSL Timings and Rates ==
Here are some LSL function times and event rates comparing scripts compiled and run using the old LSL toolset and using Mono.

The basic test framework for these tests is to set i to a large value, and take the difference in llGetTime() before and after the loop shown below (the loop is partially unrolled to make the loop control structure overhead negligible), and take several measurements in multiple Class 5 sims that are running consistently with a total frame time under 10 ms, where each test runs for 30 - 120 minutes, and measured several times during a 24-hour period until the numbers converge with a variance of 10% or less:
while (--i >= 0) {
f(); f(); f(); f(); f(); f(); f(); f();
f(); f(); f(); f(); f(); f(); f(); f();
}

In a Mono sim, the result of the first run after script reset is ignored to eliminate the overhead of the VM initialization, JIT compilation, etc.

Note that these are stopwatch times. How rapidly you can call a function or how often an event handler is invoked doesn't necessarily correspond to how much those functions and events lag a sim because of all the throttling and scheduling going on behind the scenes inside the run-time engine.

=== Functions, operators, & control structures ===

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to empty f() { }
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.33
|align="center"|0.0026
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|for loop overhead
for (i = 0; i == 0; ++i) { }
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.07
|align="center"|0.001
|align="center"|ms/loop
|}

This test measures the overhead of a for loop that iterates an empty block just once, including its setup. The code generated for this should be something like one integer assignment, one increment, and one test-and-branch. Or as one developer said, "if it's not, it should be."

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|state change
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.14
|align="center"|22.2
|align="center"|ms/transition
|}

State changes in Mono are tied to the sim frame rate of 45 fps (per Vektor Linden). The test code for state changes is an outer loop around 16 state changes like this:
. . .
state state''N'' { state_entry() { state state''N+1''; } }
state state''N+1'' { state_entry() { state state''N+2''; } }
. . . etc.

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|v = <PI,PI,PI> + <PI,PI,PI> * PI;
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.43
|align="center"|0.025
|align="center"|ms/statement
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llCSV2List(llList2CSV(x));
where x is a list of 10 integers
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|3.2
|align="center"|4 - 7
|align="center"|ms/call
|}

So far, the Mono results vary too much for any meaningful result.

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llDetectedName()
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|1.1
|align="center"|0.8
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llGetInventoryName(INVENTORY_TEXTURE, 0);
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.52
|align="center"|0.21
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llGetPos();
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.44
|align="center"|0.045
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llList2Vector(x, 0);
where x = [ ZERO_VECTOR ]
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.55
|align="center"|0.014
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llMD5String(s,0);
where s is a 64-char string
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|1.4
|align="center"|1.4
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llMessageLinked(LINK_THIS, 0, "", NULL_KEY);
One consumer script with empty link_message() { }
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|1.5
|align="center"|0.9
|align="center"|ms/call
|-
|align="center"|Two consumer scripts
|align="center"|1.8
|align="center"|1.2
|align="center"|ms/call
|-
|align="center"|Four consumer scripts
|align="center"|2.4
|align="center"|1.8
|align="center"|ms/call
|-
|align="center"|Eight consumer scripts
|align="center"|4.4
|align="center"|3.3
|align="center"|ms/call
|-
|align="center"|16 consumer scripts
|align="center"|9 - 20
|align="center"|7 - 15
|align="center"|ms/call
|-
|align="center"|32 - 64 consumer scripts
|align="center"|22.2
|align="center"|22.2
|align="center"|ms/call
|}

The time it takes to call llMessageLinked() is dependent on the number of consumers of the message, up to about 20-30 consumer scripts. At that point, the time to send a link message becomes constant at one call per 22.2 ms, which is suspiciously similar to the sim's basic frame rate.

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llParseString2List(s,a,b)
where s is 2000 random digits, a=["0","1"]; b=["2","3"];
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|45
|align="center"|24
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llSay(-2, "0123456789");
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.66
|align="center"|0.3 - 0.8
|align="center"|ms/call
|}

The Mono results vary too much for meaningful results.

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llSetLinkAlpha();
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|1.0
|align="center"|0.52
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llSetText(s,c,a)
where string s is 20 chars
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|0.79
|align="center"|0.38
|align="center"|ms/call
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|call to llSubStringIndex(s, "X"); where s is 10000 digits not containing "X"
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|16
|align="center"|22
|align="center"|ms/call
|}

=== Event handlers ===

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|Maximum rate of dataserver() events after llGetNotecardLine()
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|6.4
|align="center"|6.4
|align="center"|events/sec
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|Maximum rate of link_message() events
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|42-45
|align="center"|42-45
|align="center"|events/sec
|}

The results were highly variable over several tens of millions of link_message() events in three lightly loaded sims, but I wonder if the maximum rate is tied to the sim frame rate of 45 fps.

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|Maximum rate of listen() events
1 listener per script, any number of scripts per prim, any number of prims in linkset
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|14.7
|align="center"|14.7
|align="center"|events/sec
|-
|align="center"|Two listeners per script
|align="center"|11
|align="center"|11
|align="center"|events/sec
|-
|align="center"|Three listeners per script
|align="center"|8.8
|align="center"|8.9
|align="center"|events/sec
|}

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|Maximum rate of sensor() events after llSensorRepeat()
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|15
|align="center"|22
|align="center"|events/sec
|}

The maximum rate of sensor() events seems to be independent of the sensor radius or number of things detected.

{| cellpadding="2" cellspacing="0" border="1"
|-
|align="center" width="300" rowspan="2"|Maximum rate of timer() events
Maximum rate of touch() events
|align="center" width="80"|LSL
|align="center" width="80"|Mono
|align="center" width="80"|Units
|-
|align="center"|22
|align="center"|22
|align="center"|events/sec
|}

About half the sim's basic frame rate of 45 fps.

== Animation Frame Rate ==
=== The Problem ===
You may have heard rumors that animations (BVH files) get reduced to 12 FPS when uploaded or played, and there's no need to make an animation faster than 12 frames per second (FPS). Other rumors say that fast animation frame rates give smoother animations, while other rumors say that you should use the lowest animation frame rate possible. Confused? Here's some information that might help.
=== The SL Viewer Interpolates ===
Part of the confusion is that the term "frame rate" means different things in different contexts. The SL viewer renders frames of the scene, including any animations in the scene, as fast as it can. You can always see how fast the client is rendering frames by looking for the FPS number in the Basic section in the Statistics Bar (Ctrl-Shift-1). The frame rate in an animation file is just there to establish the time scale of the animation information. It's a different kind of "frame." So how do the two "frame rates" relate and how does it all work? It's simple -- when the viewer renders a frame, it determines how far along it is in the animation and interpolates the avatar's bone rotations based on the nearest two frames in the animation file.

Refer to the following illustration to see how you can demonstrate this interpolation. Using your favorite animation editor, make an animation file consisting of just three or four frames. The first frame is the requisite reference frame, then frame 2 is the first key frame of the animation that defines the start of a movement. Frame 3 is the last frame of the movement. Optionally you can add a frame 4 that is a copy of frame2 to make a loop. Make a large movement between frames 2 and 3, such as arms straight down in frame 2 and straight up in frame 3. Set the animation for 1 frame per second. Upload the short animation file and set the looping parameters if needed so that the animation loops continuously.

With the animation set to one frame per second, the arms should start at the sides, then one second later be raised above the head, then two seconds after the start of the animation, the arms should be back at the sides, then repeat. What happens if the client renders frames faster than one per second? If the viewer didn't interpolate, you would expect the avatar's arms to snap suddenly from one position to the other... snap up... snap down... etc. at one-second intervals. But that's not what happens at all. Regardless of your viewer frame rate, you'll see your avatar's hands moving smoothly, up and down, with all the intermediate positions between animation frames interpolated smoothly. To examine the effect in more detail, click Advanced->Character->Slow Motion Animations, then you'll have a whole bunch of interpolated rendered frames to examine.

[[Image:Animation-interpolation.jpg|500px|||Viewer interpolates animation frames]]

=== Asynchronous Frame Rates ===
In the following timeline example, the top lines represent the frames in an animation file, and the bottom lines show how fast the viewer renders frames and where the rendered frames correspond in time to the animation file. In this illustration, the animation frames are numbered starting at two, because frame one is the reference frame that never gets rendered. When the client is rendering the first frame of the animation (render frame 0 in the illustration), it corresponds to frame 2 in the animation file. In this illustration, the client is running at a fairly constant rate a little more than three times the rate of frames in the animation file:
<lsl>
animation frame number 2 3 4 5

animation frames: K-------------------------K-------------------------K-------------------------K-----

viewer rendered frames: |-------|-------|-------|-------|-------|-------|-------|-------|-------|-------|

viewer frame number: 0 1 2 3 4 5 6 7 8 9 10
</lsl>
When the viewer is rendering frame 0, the bone rotations exactly correspond to frame 2 in the animation file. After that, the time when a frame is rendered will almost always fall somewhere between two of the animation frames and the client will interpolate the bone rotations. For example, when the client renders frame 1, the bone rotations will be something between the rotations in frames 2 and 3 of the animation file, but closer to the rotations in frame 2.

If the client is running slow in comparison to the animation file, then some data in the animation file must be skipped:
<lsl>
animation frame number 2 3 4 5 6 7 8 9 10 11 12 13 14 15

animation key frames: K-----K-----K-----K-----K-----K-----K-----K-----K-----K-----K-----K-----K-----K---

viewer rendered frames: |--------------|---------------|---------------|---------------|---------------|--

viewer frame number: 0 1 2 3 4 5
</lsl>
In this scenario, when it's time for the client to render frame 1, the animation information is interpolated from frames 4 and 5 in the animation file, which means that any quick movement defined in frames 3 and 4 of the animation file will have been ignored that time around. If the animation loops, then perhaps on a subsequent loop the frames will align differently and a different set of animation frames will be ignored.

=== Other Considerations ===
There are additional forces at work you need to be aware of:

1. The higher the animation frame rate, the larger the file that has to be sent from the sim to every client in viewing range of the animation. Smaller is less laggy.

2. When you upload an animation, the viewer silently drops small movements. It does this by comparing each bone's rotation in two adjacent frames, then dropping any data for bones that don't move much. The exact algorithm is complicated, but in general the threshold is a few degrees in any axis from one frame to the next. If a bone's rotation changes from one frame to the next less than 3 or 4 degrees in all axes, it might be dropped. If the movement is more than about 10 degrees in any axis, it's likely to be retained. If an animation is made with a high frame rate, then the movement from frame to frame will be smaller and more movements will be dropped. If the animation frames are less frequent, then the movement between frames will be larger and more likely to be retained.

3. When the viewer interpolates bone rotations from the animation file, it uses a linear interpolation between the nearest frames, which sometimes looks a bit robotic. A higher animation rate lets you specify movements in finer resolution and make the movement start slow, get faster in the middle of the movement, then slow down when it reaches its maximum extent.

=== Summary ===
The last two forces mentioned above work against each other, so the challenge for animators is to find a balance. The animation needs to be made with a high enough frame rate to describe the movements the way you want them to appear, yet it needs to be as low a frame rate as possible to avoid having the client discard small movements on upload. It depends on the animation, but a good starting point might be around 10 FPS for the animation. Try a lower animation frame rate if the animation appears ok with fewer frames, relying more on the linear interpolation by the client to smooth it out. Use a higher animation frame rate if the linear interpolation doesn't look quite right and you need finer resolution to describe more complex or non-linear movements.

== Script Memory Limits ==
Script Memory limits are coming in 2010! Here's some information to help you prepare;
* [[User:Becky_Pippen/Memory_Limits_FAQ| FAQ about script memory limits]]
* [[User:Becky_Pippen/Measure_Script_Memory_Usage|Measuring your script memory usage]]
* [[User:Becky_Pippen/Memory_Efficiency|Calculating memory needed and memory usage efficiency]]
* [[User:Becky_Pippen/Script_Memory_Limits| A checklist for scripters -- techniques for reducing memory usage]]
* [[User:Becky_Pippen/New_LSL_Functions| New LSL functions llGetLinkPrimitiveParams() and llSetLinkPrimitiveParamsFast()]]
* [[User:Becky_Pippen/Hashing| Scripting techniques for hashing data to conserve memory]]
* [[User:Becky_Pippen/Numeric_Storage| Scripting techniques for storing arbitrary binary data without lists]]
* [[User:Becky_Pippen/Text_Storage| Scripting techniques for compressing ASCII text in Mono]]
* [http://lslwiki.net/lslwiki/wakka.php?wakka=MemoryUsage Empirical measurements of memory usage by data type and scope (lslwiki.net)]
* [[LSL_Script_Memory|Empirical measurements of memory usage by data type and scope (SL wiki)]]

== Links ==
* [http://slurl.com/secondlife/Nevia/128/128/23 The Community of the Nevia Archipelago] [http://www.inkwelle.com Website]
* [http://jira.secondlife.com/ JIRA Issue Tracker]
* [https://wiki.secondlife.com/wiki/About_AWG Architecture Working Group]
* [https://wiki.secondlife.com/wiki/Mono Mono wiki]
{{skills
|Builder=*
|Scripter=*
|Terraformer=
|Architect=
|Scenographer=
|SLogistician=
|}}

User:Becky Pippen/Text Storage

2010-01-06T22:33:13Z

Becky Pippen: minor tweaks

== Text strings in scripts ==

===Terminology===

Be warned -- these terms are not always used correctly and consistently in the LSL wikis. Here's the terminology from their various standards:

'''[http://en.wikipedia.org/wiki/Unicode Unicode]''' is a character set of several thousand character glyphs and their assigned numeric ID codes. The numeric codes are 21-bit integers in the range 0 through 0x10ffff, although a few numbers in that range have special meaning other than character data. How are those 21-bit numbers stored in memory? That's what UTF-8 and UTF-16 are all about.

'''[http://en.wikipedia.org/wiki/Utf-8 UTF-8]''' and '''[http://en.wikipedia.org/wiki/Utf-16 UTF-16]''' are two ways to represent the Unicode numeric codes in memory. UTF-8 encodes a Unicode ID number in a variable-length sequence of one to four bytes. UTF-16 encodes most characters in 16 bits, and some in 32 bits.

For a summary of Unicode character set and examples of the UTF-8 and UTF-16 storage formats, see: [[Unicode_In_5_Minutes]].

LSO-compiled scripts store strings internally in memory in UTF-8 format and Mono uses UTF-16, but all that should be transparent to the script for most purposes. The main impact for the script and scripter is the amount of memory used. [[LSL_Script_Memory|This page]] says that globally scoped strings use one byte per character in LSO and two bytes per character in Mono, which is true for strings containing only 7-bit ASCII characters. When the strings contain mostly international characters outside the ASCII range, then the memory consumption for UTF-8 in LSO and UTF-16 in Mono will both be close to two bytes per character, and in some cases the UTF-8 will be longer if there are many characters that require the three-byte or four-byte forms of UTF-8 encoding.

===So, summarize, ok?===

So, if using only ASCII and compiling with Mono, we can possibly reduce the memory requirements to LSO levels through clever encoding. Otherwise any attempt made to compress text will probably use more instruction code space than the amount of memory saved.

===ASCII text compression in Mono===

This technique applies if your script uses only ASCII characters and only if compiling with Mono. We'll take the ASCII characters, two at a time, convert them to their Unicode numeric ID codes (which for these characters are identical to their ASCII numeric codes), combine them into a 14-bit integer, add a bias that so that the 14-bit numbers all are inside a valid range of Unicode characters, then convert it into a single Unicode character. This will result in a 16-bit Unicode character that bears no resemblance to the two ASCII characters that it encodes.

The decoding process is just the reverse -- convert a Unicode character into its numeric value which will be a 14-bit integer, divide it into two 7-bit numbers, and convert that back to a string of two characters.

For encoding, we need a couple of functions -- one to convert a single Unicode character to its numeric ID, and one to convert a 14-bit number into a single Unicode character. Here's the former:

<lsl> // Given a single character c, this returns its Unicode ID number
// This works only for character codes 0 through 0xffff.
//
integer charToUnicodeIdNumber(string c)
integer cInt = llBase64ToInteger(llStringToBase64(c));

if (!(cInt & 0x80000000)) {
// UTF-8 single-byte form
cInt = cInt >> 24;
} else {
if ((cInt & 0xe0000000) == 0xc0000000) {
// two-byte UTF-8 form: 110v vvvv 10vv vvvv
cInt = ((cInt & 0x1f000000) >> 18) |
((cInt & 0x003f0000) >> 16);
} else {
// assume three-byte UTF-8 form: 1110 vvvv 10vv vvvv 10vv vvvv
cInt = ((cInt & 0x0f000000) >> 12) |
((cInt & 0x003f0000) >> 10) |
((cInt & 0x00003f00) >> 8);
} // else ignore the 4-byte UTF-8 form
} </lsl>

This works because the function [[llStringToBase64]]() converts the character c into UTF-8 format first, then into base64 encoding. This isn't documented well, so let's be clear about it -- regardless if running in LSO where text is UTF-8 or in Mono where text is UTF-16, the function [[llStringToBase64]]() will return a base64-encoded form of the UTF-8 encoding of its argument.

This function is very similar to the function
<lsl> integer UTF8ToUnicodeInteger(string input); </lsl>
found in [[Combined_Library]]. I'm offering my own version here for two reasons: (1) I've named the function to emphasize that it takes a single character as string input, and to remove "UTF-8" from the function name because the role of UTF-8 in the function is only as a necessary intermediate encoding. The function is meant to work with LSO or Mono so that the underlying internal encoding of the input argument is transparent; and (2) my version is a little easier to read (at the expense of being a few bytes longer).

And just for completeness, if you need to revise the function to also work with Unicode ID codes above 0xffff, the additional else clause looks like this:

<lsl> . . .
} else {
// four-byte UTF-8 form: 1111 0vvv 10vv vvvv 10vv vvvv 10vv vvvv
cInt = ((cInt & 0x07000000) >> 6) |
((cInt & 0x003f0000) >> 4) |
((cInt & 0x00003f00) >> 2) |
(cInt & 0x0000003f);
} </lsl>

Next, we need a way to combine two 7-bit character codes into a single Unicode character. We'll simply combine two numbers to make a 14-bit integer, then convert that to a Unicode character using the function encode15BitsToChar() found in [[User:Becky_Pippen/Numeric_Storage]]:

For decoding, we'll use the function decodeCharTo15Bits() found in [[User:Becky_Pippen/Numeric_Storage]] to get our 14-bit number, then split that into two 7-bit numbers, then use [[llUnescapeURL]]() to turn those into two characters in a string.

===Code Example===

First, we need to run a benchmark to measure memory usage in the normal uncompressed way. Simply put a bunch of ASCII text into a notecard and drop it into a prim with this script. It will concatenate all the notecard lines into a single global string named bigText. I used the text from http://www.gutenberg.org/files/6274/6274.txt as the notecard text. It runs out of memory after saving 1063 notecard lines:

<lsl>
integer lineNumber;
string notecardName = "ASCII text";
integer linesRead;
string bigText;

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string data)
{
if (data != EOF) {
bigText += data;
llOwnerSay((string)(++linesRead) + ":" + data);
llGetNotecardLine(notecardName, lineNumber++);
}
}
}
</lsl>

Now we can compare -- here's the same notecard reader script using ASCII compression. Even though the added compression functions consume about 3K of program space, we can now store 1854 lines. '''That's 74% more text using compression.'''

<lsl> // Demo of ASCII compression in Mono scripts
// By Becky Pippen, 2009, contributed to Public Domain

// Report memory free and the change from the last report:
//
integer lastFree;

mem(string label)
{
integer newFree = llGetFreeMemory();
integer change = lastFree - newFree;
llOwnerSay((string)newFree + " free, change = " + (string)change);
lastFree = newFree;
}

// Converts n = [0..0xff] to two hex characters
//
string hexChar2(integer n)
{
string hexChars = "0123456789abcdef";
return llGetSubString(hexChars, n >> 4, n >> 4) +
llGetSubString(hexChars, n & 0xf, n & 0xf);
}

// Given a single character c, this returns its Unicode ID number
// This works only for character codes 0 through 0xffff.
// For a more compact alternative, see UTF8ToUnicodeInteger()
// found in http://wiki.secondlife.com/wiki/Combined_Library .
//
integer charToUnicodeIdNumber(string c)
{
integer cInt = llBase64ToInteger(llStringToBase64(c));

if (!(cInt & 0x80000000)) {
// UTF-8 single-byte form
cInt = cInt >> 24;
} else {
if ((cInt & 0xe0000000) == 0xc0000000) {
// two-byte UTF-8 form: 110v vvvv 10vv vvvv
cInt = ((cInt & 0x1f000000) >> 18) |
((cInt & 0x003f0000) >> 16);
} else {
// assume three-byte UTF-8 form: 1110 vvvv 10vv vvvv 10vv vvvv
cInt = ((cInt & 0x0f000000) >> 12) |
((cInt & 0x003f0000) >> 10) |
((cInt & 0x00003f00) >> 8);
} // else ignore the 4-byte UTF-8 form
}

return cInt;
}

// This is a memory-savings technique for use with Mono-compiled LSL scripts.
// (It probably works in classic LSO too, but not as efficiently.) This technique
// stores 15 bits of information in each 16-bit Unicode character. Use the
// encode function below to convert any 15-bit data to a Unicode character, and
// use the decode function to convert it back to the original 15-bit data.
//
// This example maps the data values 0 through 0x7fff to the Unicode
// characters U-001000 through U-008fff. Use the matching function
// decodeCharTo15Bits() to decode the Unicode character back into the original
// 15-bit number.
//
// The technique used here is very similar to the technique used in the "Base 32768
// Script" in http://wiki.secondlife.com/wiki/Key_Compression .

// Convert any 15-bit integer into a single Unicode character
//
string encode15BitsToChar(integer num)
{
// Check the incoming range

if (num < 0 || num >= 0x8000) {
// illegal input -- do whatever is appropriate
return "�";
}

// Bias the incoming numeric value by 0x1000 to avoid illegal Unicode codes:

num += 0x1000;

// Construct an escaped hex UTF-8 representation and return
// it as a Unicode character

return llUnescapeURL(
"%" + hexChar2(0xe0 + (num >> 12)) +
"%" + hexChar2(0x80 + ((num >> 6) & 0x3f)) +
"%" + hexChar2(0x80 + (num & 0x3f)));
}

// This is the inverse of encode15BitsToChar(), supra, q.v.
// This expects a single 16-bit Unicode character that was created by
// encode15BitsToChar() and returns the 15-bit numeric value used to create it.
// The 15-bit return value will always be in the range 0x0000 - 0x7fff.
//
integer decodeCharTo15Bits(string ch)
{
string utf8 = llEscapeURL(ch); // convert to escaped hex UTF-8

return
(((integer)("0x" + llGetSubString(utf8, 1, 2)) & 0x1f) << 12) +
(((integer)("0x" + llGetSubString(utf8, 4, 5)) & 0x3f) << 6) +
((integer)("0x" + llGetSubString(utf8, 7, 8)) & 0x3f) - 0x1000;
}

// Returns a Unicode string that encodes twice as many ASCII characters.
// Use the matching function decompressAscii() to expand it back into
// the original ASCII.
//
string compressAscii(string s)
{
integer len = llStringLength(s);

// Append a space if needed to make s an even number of chars
if (len % 2) {
s += " ";
++len;
}

string encodedChars;
integer i;
for (i = 0; i < len; i += 2) {
encodedChars += encode15BitsToChar(
charToUnicodeIdNumber(llGetSubString(s, i, i)) << 7 |
charToUnicodeIdNumber(llGetSubString(s, i+1, i+1)));
}

return encodedChars;
}

// This is the inverse of compressAscii()
//
string uncompressAscii(string s)
{
string result;

integer len = llStringLength(s);
integer i;
for (i = 0; i < len; ++i) {
integer cInt15 = decodeCharTo15Bits(llGetSubString(s, i, i));
result += llUnescapeURL("%" + hexChar2(cInt15 >> 7) +
"%" + hexChar2(cInt15 & 0x7f));
}

return result;
}

integer lineNumber;
string notecardName = "ASCII text";
integer linesRead;
string bigText;

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string data)
{
if (data != EOF) {
string compressedLine = compressAscii(data);
bigText += compressedLine;
llOwnerSay((string)(++linesRead) + ":" + uncompressAscii(compressedLine));
llGetNotecardLine(notecardName, lineNumber++);
}
}
}
</lsl>

===Also see===

For more ideas about compressing bits into Unicode strings, see
* [[User:Becky_Pippen/Key_Storage| Scripting techniques for storing lots of keys (UUIDs)]]
* [[User:Becky_Pippen/Numeric_Storage| Scripting techniques for storing arbitrary binary data without lists]]
* [[User:Becky_Pippen/Script_Memory_Limits| Memory limits FAQ and Checklist for memory reduction]]
* [[User:Becky_Pippen/Hashing| Hashing for memory reduction]]

User:Becky Pippen/Hashing

2010-01-06T22:28:00Z

Becky Pippen: minor tweaks

==Hashing to conserve memory==

Hashing takes a longer item like an avatar name or [[UUID]] and maps it to something smaller, like an integer or a shorter string. It's compact, but the trade-off is that different inputs can possibly map to the same hash value by accident.

Here's an illustration of how much memory we can save by hashing UUIDs in a Mono script -- from 72 bytes in their native form to just a few bytes each. This illustrates techniques discussed in the rest of this article:

[[Image:Key hash-1.jpg|800px]]

There are two problems to solve to make hashing work in LSL: (1) designing a hash function that makes hash codes of the right size, evenly distributed across the hash space, and (2) storing the hash codes efficiently without suffering the overhead of lists. Those two aspects are treated separately below.

===Designing the hash function===

A hash size too small increases the chance of a hash collision. That's when multiple values of the real data map to the same hash value. A hash size too large wastes memory.

Calculating the probability of hash collisions is similar to calculating the [http://betterexplained.com/articles/understanding-the-birthday-paradox/ "Birthday Paradox" probabilities]. The probability that there will be a duplicate among N random hashes of W bits each is approximately:

P = 1.0 - e ^ -(N^2 / (2 * 2^W))

The table below shows some examples of the probability ''P'' of having at least one duplicate among ''N'' hashes of various sizes. For example, there is a probability of 0.0001 that there will be a duplicate in a set of 1000 32-bit hash codes.

{| border="1"
|align="center"|
|align="center"|15-bit
|align="center"|16-bit
|align="center"|30-bit
|align="center"|32-bit
|align="center"|45-bit
|-
|align="center" | ''N''
|align="center" | ''P''
|align="center" | ''P''
|align="center" | ''P''
|align="center" | ''P''
|align="center" | ''P''
|-
|align="right" | 100
|align="left" | 0.14
|align="left" | 0.07
|align="left" | 0.000005
|align="left" | 0.000001
|align="left" | 0.0000000001
|-
|align="right" | 200
|align="left" | 0.46
|align="left" | 0.26
|align="left" | 0.00002
|align="left" | 0.000005
|align="left" | 0.0000000006
|-
|align="right" | 500
|align="left" | 0.978
|align="left" | 0.85
|align="left" | 0.0001
|align="left" | 0.00003
|align="left" | 0.0000000004
|-
|align="right" | 1000
|align="left" | 1.0
|align="left" | 0.9995
|align="left" | 0.0005
|align="left" | 0.0001
|align="left" | 0.00000001
|-
|align="right" | 2000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.001
|align="left" | 0.0005
|align="left" | 0.00000006
|-
|align="right" | 5000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.01
|align="left" | 0.003
|align="left" | 0.0000007
|-
|align="right" | 10000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.05
|align="left" | 0.01
|align="left" | 0.000001
|-
|align="right" | 25000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.26
|align="left" | 0.07
|align="left" | 0.000009
|-
|align="right" | 50000
|align="left" | 1.0
|align="left" | 1.0
|align="left" | 0.69
|align="left" | 0.25
|align="left" | 0.00004
|}

====Hashing UUIDs====

It appears that most [[UUID]]s in SL are constructed with random bits (or sufficiently so for our purposes) in the first six bytes (first 12 hex digits) of the UUID. This lets us make a trivial hash function by extracting some of the hex digits from the UUID. For example, this code extracts the first eight hex digits as a hash:

<lsl> string hash(key k)
{
return llGetSubString((string)k, 0, 7); // first 8 hex chars
} </lsl>

That gives us a hash code with 32 bits of information content (eight hex characters at four bits each).

At this point you might wonder why not reduce the hash code to a regular 32-bit integer that only uses four bytes of memory. Unfortunately, we can't do anything with integers except store them in a list, and that makes any string-based solution more efficient, as described below.

If you have any concern that the first few bytes of the UUID are not really as random as you would like, you can make an MD5 hash out of the UUID, then take hex digits from the MD5 hash string. For example, this hash function extracts eight hex digits from the MD5 hash of the UUID:

<lsl> string hash(key k)
{
return llGetSubString(llMD5String((string)k, salt), 0, 7);
} </lsl>

Any salt value works in the code above, as long as it's consistent. Choose an unguessable value for salt if you want your hashing function to yield different values than other scripts using the same code snippet above. Think of the salt value as serving a purpose similar to the seed value used in pseudo-random number generators.

We can make the hash code even smaller by treating the eight hex digits as a 32-bit numeric value and converting that number into a six-character string using [http://en.wikipedia.org/wiki/Base64 base64] representation. Something like this:

<lsl> string hash(key k)
{
return llGetSubString(llIntegerToBase64(
(integer)("0x" + llGetSubString((string)k, 0, 7))), 0, 5);
} </lsl>

In other words, the same information contained in eight hex characters fits into six base64 characters.

====Hashing avatar names and other strings====

Almost anything can be hashed using [[llMD5String]](). That's a function historically used for encryption and security, and it's useful for our hashing needs because it nicely distributes all possible input values across its output range. The MD5 conversion gives us a long string of hex characters, and we can simply extract however many we want to use for a hash. The longer the hash, the less likely there will be a hash collision but the more memory it will consume. This example extracts twelve hex characters from the MD5 result to form a hash code worth 48 bits of information:

<lsl> string hash(string input)
{
string md5 = llMD5String(input, salt);
return llGetSubString(md5, 0, 11);
} </lsl>

The problem with this hash function is that the average avatar name in SL is about 14 characters, so a twelve-character hash code is not a dramatic improvement. And then if we store these hash codes in a list, we eat up additional memory with list overhead. To save memory, we need to think of these hash codes as containing so many bits of information, not as characters. Then we need to think of a way to store those bits of information in a more compact form, i.e., without using lists. The next section describes a way of encoding information into Unicode character strings.

===Avoiding list overhead===

It's very difficult to store data compactly in Mono scripts -- there are no arrays; lists incur 20+ bytes of overhead per list element; and string data uses a minimum of two bytes per character. About the only way we have to encode arbitrary data in memory is by encoding the information as Unicode characters.

Using the functions in [[User:Becky_Pippen/Numeric_Storage| this article]], you can store 15 bits of arbitrary data in each 16-bit Unicode character. It's not quite as straightforward as interpreting the 15 bits as the Unicode character ID because certain Unicode character codes may not be used. For example, we can't simply use the Unicode character ID 0x000000 to store a numeric value of zero, because 0x000000 is an illegal Unicode character code. So we have to remap any 15-bit number we want to store into some range of legal Unicode characters. The functions [[User:Becky_Pippen/Numeric_Storage#Source_code_example|encode15BitsToChar()]] and [[User:Becky_Pippen/Numeric_Storage#Source_code_example|decodeCharTo15Bits()]] do this remapping by adding 0x1000 to the 15-bit number to make a Unicode character ID in the range 0x1000 through 0x8fff. The result is that a 15-bit hash code can be stored as one character; a 30-bit hash code in two characters, and a 45-bit hash code in three Unicode characters.

===Searching for hash codes when concatenated in a string===

If the consequence of a false positive match is an acceptable risk, then searching a long string for a given hash code can be simplified to a call to [[llSubStringIndex]](). In this example, hash codes are 45-bit values encoded as three Unicode characters each. All hash codes are concatenated into one long string named hashCodes:

<lsl> // Returns logical index of the given hash code
// or -1 if not found

string hashCodes; // all hash codes are concatenated here

integer findHash(string hashCode)
{
integer index = llSubStringIndex(hashCodes, hashCode);
if (index != -1) {
index /= 3; // because each hash code is three Unicode chars
}

return index;
} </lsl>

The code above will find a false match if the hashCode value accidentally randomly matches characters that span two different hash codes in the hashCodes string. Your script can detect false positives by checking if the match occurred on a boundary of hashSize bytes:

<lsl> // Returns logical index of the given hash code
// or -1 if not found

string hashCodes; // all hash codes are concatenated here
integer hashSize = 6; // number of chars in each hash code

integer findHash(string hashCode)
{
integer index = llSubStringIndex(hashCodes, hashCode);
if (index != -1 && (index % hashSize)) {
// this is a false match.
// fall back to a loop search, or whatever is appropriate
} else if (index != -1) {
// a valid match
index /= hashSize;
}

return index;
} </lsl>

===Code Example===

Here is a complete example of a script that stores avatar names read from a notecard. First let's get a benchmark of the memory consumption using the naive approach of storing the names in a global list. The notecard I used for a test contains 2000 actual SL avatar names, one per line. There are only 1500 unique names in the notecard, so 500 of them are duplicates.

<lsl> integer lineNumber;
string notecardName = "names";
integer namesSaved;
list hashedNames;

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string avName)
{
if (avName != EOF) {
if (llListFindList(hashedNames, [avName]) == -1) {
hashedNames += [avName];
llOwnerSay((string)(++namesSaved) + ": " + avName + ", " +
(string)llGetFreeMemory() + " free");
} else {
llOwnerSay("duplicate: " + avName);
}

llGetNotecardLine(notecardName, lineNumber++);
}
}
} </lsl>

The data ate up 56000 bytes of available memory and ran out of memory after saving 1137 unique names. That works out to about 49 bytes consumed per item. That's roughly what we expected in Mono, based on the data in [[LSL_Script_Memory|this page]] -- an average of 14 characters per avatar name uses 28 bytes of memory in Mono, plus 22 bytes of overhead per list element for a total of 14+28=42 bytes each.

Here is the same script but with the functions needed to save the avatar identities as 45-bit hash codes encoded as three Unicode characters each. It stores 1500 hashed names in just 9000 bytes. Even adding the 2500 extra bytes of program code to support hashing, that comes out to a total 11500 bytes consumed to store 1500 avatar identities, or 7.7 bytes each, compared to 49 bytes each on the average for the naive list approach above. '''That's an 84% net reduction in memory consumption.'''

<lsl> // Demo - store avatar identities as 45-bit hases encoded in 3 Unicode
// chars each, concatenated into one string.
// By Becky Pippen, 2010, contributed to the public domain.

integer lastFree;

// Report memory free and the change from the last report:
//
mem(string label)
{
integer newFree = llGetFreeMemory();
integer change = lastFree - newFree;
llOwnerSay((string)newFree + " free, change = " + (string)change);
lastFree = newFree;
}

// Converts n = [0..0xff] to "%" + two hex characters
//
string escapeHexChar(integer n)
{
string hexChars = "0123456789abcdef";
return "%" +
llGetSubString(hexChars, n >> 4, n >> 4) +
llGetSubString(hexChars, n & 0xf, n & 0xf);
}

// Encode 15 bits of data as a single Unicode character. Use decodeCharTo15Bits()
// to recover the 15-bit data.
//
// The technique used here is very similar to the technique used in the "Base 32768
// Script" in http://wiki.secondlife.com/wiki/Key_Compression .

string encode15BitsToChar(integer num)
{
// Use only the lower 15 bits and bias by 0x1000 to avoid illegal Unicode IDs:

num = 0x1000 + (num & 0x00007fff);

// Construct an escaped hex UTF-8 representation and
// return it as one Unicode character:

return llUnescapeURL(
escapeHexChar(0xe0 + (num >> 12)) +
escapeHexChar(0x80 + ((num >> 6) & 0x3f)) +
escapeHexChar(0x80 + (num & 0x3f)));
}

//****************************************
// demo -- store avatar identities as compressed 45-bit hashes of their name

integer lineNumber; // for the notecard reader
string notecardName = "names"; // notecard of av names, one per line
integer namesSaved; // count how many successfully saved
string hashedNames; // all the hashes get concatenated in this string
integer hashSize = 3; // num of Unicode chars per encoded hash code

default
{
touch_start(integer num)
{
llGetNotecardLine(notecardName, lineNumber++);
}

dataserver(key id, string avName)
{
if (avName != EOF) {
// Pick off 48 bits of information to start with:
string md5 = llMD5String(avName, 0);
integer n1 = (integer)("0x" + llGetSubString(md5, 0, 7));
integer n2 = (integer)("0x" + llGetSubString(md5, 8, 11));

// Map 45 of the bits into three characters. We cannot encode Unicode
// directly, so we have to use UTF-8 as an intermediate form
//
// |------------------ n1 ------------------| |------- n2 -------|
// x000 0000 0000 0000 x000 0000 0000 0000 x000 0000 0000 0000
// |------char1------| |------char2------| |------char3------|

string encoded3Chars =
encode15BitsToChar(n1 >> 16) +
encode15BitsToChar(n1) +
encode15BitsToChar(n2);

integer idx = llSubStringIndex(hashedNames, encoded3Chars);
if (idx == -1) {
// this is a new one, so save it
hashedNames += encoded3Chars;
llOwnerSay((string)(++namesSaved) + ": " + avName + ", " +
(string)llGetFreeMemory() + " free");
} else if (idx % hashSize) {
llOwnerSay("WARNING!!! False match for " + avName);
} else {
llOwnerSay("Duplicate, already saved: " + avName);
}

llGetNotecardLine(notecardName, lineNumber++);
}
}
} </lsl>

===Also see===

For more ideas about compressing bits into Unicode strings, see
* [[User:Becky_Pippen/Numeric_Storage| Scripting techniques for storing arbitrary binary data without lists]]
* [[User:Becky_Pippen/Script_Memory_Limits| Memory limits FAQ and Checklist for memory reduction]]

If you need to store a lot of keys without losing any bits, see the suggestions at [[Key_Compression]].