OpenSimulator - User contributions [en]

OsGetRegionStats

2009-12-20T00:08:03Z

Godfrey: Fixed typo.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[OsGetRegionStats|osGetRegionStats]]

LSL: '''[[list]] osGetRegionStats()''' 
C#: '''[[LSL_List]] osGetRegionStats()'''

Returns a list of float values representing a number of region statistics (many of the values shown in the "Stats Bar" of LL-based clients). Provides similar functionality to llGetRegionFPS() and llGetRegionTimeDilation(), but returns 21 statistics simultaneously.

This function has a [[threat level]] of Moderate, to prevent griefing scripts from obtaining metrics to gauge their own effectiveness. Please see the [[threat level]] page for information on how to enable the use of this function securely.

The elements in the list may be referred to by the following new LSL constants:

{| style="white-space:nowrap;margin-left:3em;border:1px solid black" cellspacing="0" border="1"
|STATS_TIME_DILATION
|0
|STATS_IMAGE_MS
|11
|-
|STATS_SIM_FPS
|1
|STATS_OTHER_MS
|12
|-
|STATS_PHYSICS_FPS
|2
|STATS_IN_PACKETS_PER_SECOND
|13
|-
|STATS_AGENT_UPDATES
|3
|STATS_OUT_PACKETS_PER_SECOND
|14
|-
|STATS_ROOT_AGENTS
|4
|STATS_UNACKED_BYTES
|15
|-
|STATS_CHILD_AGENTS
|5
|STATS_AGENT_MS
|16
|-
|STATS_TOTAL_PRIMS
|6
|STATS_PENDING_DOWNLOADS
|17
|-
|STATS_ACTIVE_PRIMS
|7
|STATS_PENDING_UPLOADS
|18
|-
|STATS_FRAME_MS
|8
|STATS_ACTIVE_SCRIPTS
|19
|-
|STATS_NET_MS
|9
|STATS_SCRIPT_LPS
|20
|-
|STATS_PHYSICS_MS
|10
|
|
|}

Please note that as of November 2009, some of the elements in the array (to wit, the STATS_*_MS values) do not appear to contain useful information.

Code provided by Implementor:  Godfrey and Implemented in Git Hash 9d05962029fe864408d287d5fa7ef81f312e098a, - Rev 11601

Example script:

<source lang="lsl">
// llGetRegionStats() example script
//
// Displays certain region statistics in hovertext above the prim containing the script.
//
default
{
state_entry()
{
llSetTimerEvent( 5.0 );
}

timer()
{
list Stats = osGetRegionStats();
string s = "Sim FPS: " + (string) llList2Float( Stats, STATS_SIM_FPS ) + "\n";
s += "Physics FPS: " + (string) llList2Float( Stats, STATS_PHYSICS_FPS ) + "\n";
s += "Time Dilation: " + (string) llList2Float( Stats, STATS_TIME_DILATION ) + "\n";
s += "Root Agents: " + (string) llList2Integer( Stats, STATS_ROOT_AGENTS ) + "\n";
s += "Child Agents: " + (string) llList2Integer( Stats, STATS_CHILD_AGENTS ) + "\n";
s += "Total Prims: " + (string) llList2Integer( Stats, STATS_TOTAL_PRIMS ) + "\n";
s += "Active Scripts: " + (string) llList2Integer( Stats, STATS_ACTIVE_SCRIPTS ) + "\n";
s += "Script LPS: " + (string) llList2Float( Stats, STATS_SCRIPT_LPS );
llSetText( s, <0.0,1.0,0.0>, 1.0 );
}
}</source>

OsGetLinkPrimitiveParams

2009-12-20T00:06:56Z

Godfrey: Removed the "Bugs" section after submitting a patch to correct the issues with llGetPrimitiveParams() and osGetLinkPrimitiveParams().

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[OsGetLinkPrimitiveParams|osGetLinkPrimitiveParams]]

LSL: '''[[list]] osGetLinkPrimitiveParams( [[integer]] linknumber, [[list]] params )''' 
C#: '''[[LSL_List]] osGetRegionStats( [[int]] linknumber, [[LSL_List]] params )'''

Returns the primitive parameters for the linkset prim or prims specified by '''linknumber'''. It is possible to use the linkset constants (e.g. '''LINK_SET''', '''LINK_ALL_CHILDREN''') in place of a specific link number, in which case the requested parameters of each relevant prim are concatenated to the end of the list. Otherwise, the usage is identical to llGetPrimitiveParams().

This function has a [[threat level]] of High, to prevent unscrupulous users from easily retrieving the construction details of an entire linkset. Please see the [[threat level]] page for information on how to enable the use of this function securely.

Example script:

<source lang="lsl">
// llGetLinkPrimitiveParams() example script
//
// Trivial example which averages the sizes of all the prims in the linkset and returns the resuilt.
//
default
{
state_entry()
{
vector average = ZERO_VECTOR;
list params = osGetLinkPrimitiveParams( LINK_SET, [ PRIM_SIZE ] );
integer len = llGetListLength( params );
integer i;

for (i = 0; i < len; i++)
average += llList2Vector( params, i );

average /= (float) len;
llOwnerSay( "The average size of the prims in this linkset is " + (string) average );
}
}</source>

OsGetLinkPrimitiveParams

2009-12-19T20:19:45Z

Godfrey: Original page creation

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[OsGetLinkPrimitiveParams|osGetLinkPrimitiveParams]]

LSL: '''[[list]] osGetLinkPrimitiveParams( [[integer]] linknumber, [[list]] params )''' 
C#: '''[[LSL_List]] osGetRegionStats( [[int]] linknumber, [[LSL_List]] params )'''

Returns the primitive parameters for the linkset prim or prims specified by '''linknumber'''. It is possible to use the linkset constants (e.g. '''LINK_SET''', '''LINK_ALL_CHILDREN''') in place of a specific link number, in which case the requested parameters of each relevant prim are concatenated to the end of the list. Otherwise, the usage is identical to llGetPrimitiveParams().

This function has a [[threat level]] of High, to prevent unscrupulous users from easily retrieving the construction details of an entire linkset. Please see the [[threat level]] page for information on how to enable the use of this function securely.

'''Bugs:''' As of this writing (December 2009), some of the values returned are incorrect: specifically, the top shear value returned for '''PRIM_TYPE''' is incorrect if the shear is negative; the revolutions value returned for '''PRIM_TYPE''' is also incorrect (llGetPrimitiveParams() is affected by both of these issues as well). Furthermore, if the root prim of the linkset is rotated in any fashion, the '''PRIM_ROTATION''' values returned for child prims are incorrect.

Example script:

<source lang="lsl">
// llGetLinkPrimitiveParams() example script
//
// Trivial example which averages the sizes of all the prims in the linkset and returns the resuilt.
//
default
{
state_entry()
{
vector average = ZERO_VECTOR;
list params = osGetLinkPrimitiveParams( LINK_SET, [ PRIM_SIZE ] );
integer len = llGetListLength( params );
integer i;

for (i = 0; i < len; i++)
average += llList2Vector( params, i );

average /= (float) len;
llOwnerSay( "The average size of the prims in this linkset is " + (string) average );
}
}</source>

OsGetRegionStats

2009-11-27T16:14:36Z

Godfrey:

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[OsGetRegionStatistics|osGetRegionStatistics]]

LSL: '''[[list]] osGetRegionStats()''' 
C#: '''[[LSL_List]] osGetRegionStats()'''

Returns a list of float values representing a number of region statistics (many of the values shown in the "Stats Bar" of LL-based clients). Provides similar functionality to llGetRegionFPS() and llGetRegionTimeDilation(), but returns 21 statistics simultaneously.

This function has a [[threat level]] of Moderate, to prevent griefing scripts from obtaining metrics to gauge their own effectiveness. Please see the [[threat level]] page for information on how to enable the use of this function securely.

The elements in the list may be referred to by the following new LSL constants:

{| style="white-space:nowrap;margin-left:3em;border:1px solid black" cellspacing="0" border="1"
|STATS_TIME_DILATION
|0
|STATS_IMAGE_MS
|11
|-
|STATS_SIM_FPS
|1
|STATS_OTHER_MS
|12
|-
|STATS_PHYSICS_FPS
|2
|STATS_IN_PACKETS_PER_SECOND
|13
|-
|STATS_AGENT_UPDATES
|3
|STATS_OUT_PACKETS_PER_SECOND
|14
|-
|STATS_ROOT_AGENTS
|4
|STATS_UNACKED_BYTES
|15
|-
|STATS_CHILD_AGENTS
|5
|STATS_AGENT_MS
|16
|-
|STATS_TOTAL_PRIMS
|6
|STATS_PENDING_DOWNLOADS
|17
|-
|STATS_ACTIVE_PRIMS
|7
|STATS_PENDING_UPLOADS
|18
|-
|STATS_FRAME_MS
|8
|STATS_ACTIVE_SCRIPTS
|19
|-
|STATS_NET_MS
|9
|STATS_SCRIPT_LPS
|20
|-
|STATS_PHYSICS_MS
|10
|
|
|}

Please note that as of November 2009, some of the elements in the array (to wit, the STATS_*_MS values) do not appear to contain useful information.

Code provided by Implementor:  Godfrey and Implemented in Git Hash 9d05962029fe864408d287d5fa7ef81f312e098a, - Rev 11601

Example script:

<source lang="lsl">
// llGetRegionStats() example script
//
// Displays certain region statistics in hovertext above the prim containing the script.
//
default
{
state_entry()
{
llSetTimerEvent( 5.0 );
}

timer()
{
list Stats = osGetRegionStats();
string s = "Sim FPS: " + (string) llList2Float( Stats, STATS_SIM_FPS ) + "\n";
s += "Physics FPS: " + (string) llList2Float( Stats, STATS_PHYSICS_FPS ) + "\n";
s += "Time Dilation: " + (string) llList2Float( Stats, STATS_TIME_DILATION ) + "\n";
s += "Root Agents: " + (string) llList2Integer( Stats, STATS_ROOT_AGENTS ) + "\n";
s += "Child Agents: " + (string) llList2Integer( Stats, STATS_CHILD_AGENTS ) + "\n";
s += "Total Prims: " + (string) llList2Integer( Stats, STATS_TOTAL_PRIMS ) + "\n";
s += "Active Scripts: " + (string) llList2Integer( Stats, STATS_ACTIVE_SCRIPTS ) + "\n";
s += "Script LPS: " + (string) llList2Float( Stats, STATS_SCRIPT_LPS );
llSetText( s, <0.0,1.0,0.0>, 1.0 );
}
}</source>

OsGetRegionStats

2009-11-27T15:50:28Z

Godfrey: Documented the function more completely, including the constants used to address the returned list elements. Added templates.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[OsGetRegionStatistics|osGetRegionStatistics]]

LSL: '''[[list]] osGetRegionStats()''' 
C#: '''[[LSL_List]] osGetRegionStats()'''

Returns a list of float values representing a number of region statistics (many of the values shown in the "Stats Bar" of LL-based clients).

This function has a [[threat level]] of Moderate, to prevent griefing scripts from obtaining metrics to gauge their own effectiveness. Please see the [[threat level]] page for information on how to enable the use of this function securely.

The elements in the list may be referred to by the following new LSL constants:

{| style="white-space:nowrap;margin-left:3em;border:1px solid black" cellspacing="0" border="1"
|STATS_TIME_DILATION
|0
|STATS_IMAGE_MS
|11
|-
|STATS_SIM_FPS
|1
|STATS_OTHER_MS
|12
|-
|STATS_PHYSICS_FPS
|2
|STATS_IN_PACKETS_PER_SECOND
|13
|-
|STATS_AGENT_UPDATES
|3
|STATS_OUT_PACKETS_PER_SECOND
|14
|-
|STATS_ROOT_AGENTS
|4
|STATS_UNACKED_BYTES
|15
|-
|STATS_CHILD_AGENTS
|5
|STATS_AGENT_MS
|16
|-
|STATS_TOTAL_PRIMS
|6
|STATS_PENDING_DOWNLOADS
|17
|-
|STATS_ACTIVE_PRIMS
|7
|STATS_PENDING_UPLOADS
|18
|-
|STATS_FRAME_MS
|8
|STATS_ACTIVE_SCRIPTS
|19
|-
|STATS_NET_MS
|9
|STATS_SCRIPT_LPS
|20
|-
|STATS_PHYSICS_MS
|10
|
|
|}

Please note that as of November 2009, some of the elements in the array (to wit, the STATS_*_MS values) do not appear to contain useful information.

Code provided by Implementor:  Godfrey and Implemented in Git Hash 9d05962029fe864408d287d5fa7ef81f312e098a, - Rev 11601

Example script:

<source lang="lsl">
// llGetRegionStats() example script
//
// Displays certain region statistics in hovertext above the prim containing the script.
//
default
{
state_entry()
{
llSetTimerEvent( 5.0 );
}

timer()
{
list Stats = osGetRegionStats();
string s = "Sim FPS: " + (string) llList2Float( Stats, STATS_SIM_FPS ) + "\n";
s += "Physics FPS: " + (string) llList2Float( Stats, STATS_PHYSICS_FPS ) + "\n";
s += "Time Dilation: " + (string) llList2Float( Stats, STATS_TIME_DILATION ) + "\n";
s += "Root Agents: " + (string) llList2Integer( Stats, STATS_ROOT_AGENTS ) + "\n";
s += "Child Agents: " + (string) llList2Integer( Stats, STATS_CHILD_AGENTS ) + "\n";
s += "Total Prims: " + (string) llList2Integer( Stats, STATS_TOTAL_PRIMS ) + "\n";
s += "Active Scripts: " + (string) llList2Integer( Stats, STATS_ACTIVE_SCRIPTS ) + "\n";
s += "Script LPS: " + (string) llList2Float( Stats, STATS_SCRIPT_LPS );
llSetText( s, <0.0,1.0,0.0>, 1.0 );
}
}</source>

Threat level

2009-11-27T15:43:45Z

Godfrey:

{{Template:Quicklinks}}
To permit region owners to enable the extended scripting functionality of [[OSSL]], without allowing malicious scripts to access potentially troublesome functions, each OSSL function is assigned a '''threat level''', and access to the functions is granted or denied based on a default threshold set in [[OpenSim.ini]] (which can be overridden for individual functions on a case-by-case basis).

The threat levels, from wholly unthreatening to most potentially damaging, are:

;None
:Function is no threat at all. It doesn't constitute a threat to either users or the system and has no known side effects.
;Nuisance
:Abuse of this command can cause a nuisance to the region operator, such as log message spew.
;VeryLow
:Extreme levels of abuse of this function can cause impaired functioning of the region, or very gullible users can be tricked into experiencing harmless effects.
;Low
:Intentional abuse can cause crashes or malfunction under certain circumstances, which can be easily rectified; or certain users can be tricked into certain situations in an avoidable manner.
;Moderate
:Intentional abuse can cause denial of service and crashes with potential of data or state loss; or trusting users can be tricked into embarrassing or uncomfortable situations.
;High
:Casual abuse can cause impaired functionality or temporary denial of service conditions. Intentional abuse can easily cause crashes with potential data loss, or can be used to trick experienced and cautious users into unwanted situations, or changes global data permanently and without undo ability.
;VeryHigh
:Even normal use may, depending on the number of instances, or frequency of use, result in severe service impairment or crash with loss of data, or can be used to cause unwanted or harmful effects on users without giving the user a means to avoid it.
;Severe
:Even casual use is a danger to region stability, or function allows console or OS command execution, or function allows taking money without consent, or allows deletion or modification of user data, or allows the compromise of sensitive data by design.

The '''OSFunctionThreatLevel''' setting in the script engines' configuration sections of [[OpenSim.ini]] controls what classes of functions are accessible to scripts owned by any avatar; any function at the same threat level or lower than the value provided for '''OsFunctionThreatLevel''' is permitted to run. If '''OSFunctionThreatLevel''' is absent from the configuration file, the default value is '''VeryLow'''.

OSSL functions may also be permitted or prohibited on an individual basis, by adding '''Allow_*''' lines to the script engine's configuration section. To permit scripts owned by anyone to access a function, even if its threat level exceeds the value of '''OSFunctionThreatLevel''', use the value 'true':

<source lang="ini">
Allow_osMakeNotecard = true
</source>

To prohibit scripts owned by anyone from accessing a function, even if its threat level is equal to or below the value of '''OSFunctionThreatLevel''', use the value 'false':

<source lang="ini">
Allow_osMovePen = false
</source>

To allow scripts owned by only certain avatars to access a function, use the UUIDs of the avatars owning the scripts. If multiple avatars are to be permitted access, separate the UUIDs with commas:

<source lang="ini">
Allow_osMakeNotecard = a1cbbdd7-8adb-4158-aa52-c0ee882c4492
Allow_osTeleportAgent = a1cbbdd7-8adb-4158-aa52-c0ee882c4492,9cab27da-764c-4469-a628-369d978ba436
</source>

Below is a list of OSSL functions grouped by threat level:

;None
:[[osDrawEllipse]], [[osDrawFilledRectangle]], [[osDrawImage]], [[osDrawLine]], [[osDrawRectangle]], [[osDrawText]], [[osGetAgents]], [[osGetCurrentSunHour]], [[osList2Double]], [[osMovePen]], [[osParseJSON]], [[osSetFontSize]], [[osSetPenColour]], [[osSetPenSize]], [[osSunGetParam]], [[osSunSetParam]], [[osTerrainGetHeight]], [[osWindActiveModelPluginName]]

;Nuisance
:[[osSetRegionSunSettings]], [[osSetEstateSunSettings]]

;VeryLow
:[[osGetDrawStringSize]], [[osSetDynamicTextureData]], [[osSetDynamicTextureDataBlend]], [[osSetDynamicTextureDataBlendFace]], [[osSetDynamicTextureURL]], [[osSetDynamicTextureURLBlend]], [[osSetDynamicTextureURLBlendFace]], [[osSetParcelMediaURL]], [[osSetPrimFloatOnWater]], [[osTerrainFlush]], [[osWindParamGet]], [[osWindParamSet]]

;Low
:[[osAvatarName2Key]], [[osFormatString]], [[osKey2Name]], [[osLoadedCreationDate]], [[osLoadedCreationID]], [[osLoadedCreationTime]], [[osMessageObject]]

;Moderate
:[[osGetGridLoginURI]], [[osGetGridName]], [[osGetGridNick]], [[osGetRegionStats]]

;High
:[[osGetAgentIP]], [[osGetScriptEngineName]], [[osGetSimulatorVersion]], [[osMakeNotecard]], [[osMatchString]], [[osRegionRestart]], [[osSetRegionWaterHeight]], [[osSetStateEvents]], [[osTeleportAgent]], [[osTerrainSetHeight]]

;VeryHigh
:[[osAvatarPlayAnimation]], [[osAvatarStopAnimation]], [[osGetNotecard]], [[osGetNotecardLine]], [[osGetNumberOfNotecardLines]], [[osRegionNotice]], [[osSetRot]]

;Severe
:[[osConsoleCommand]]

== Ascertaining privilege to use a function ==

There is not currently a function which would allow a script to determine whether or not it has permission to use any specific OSSL function. Such a function was proposed, but rejected by a developer on the grounds that it could permit a griefer script too much knowledge of its environment (though, as shown below, this information is already available through other methods, albeit less efficient ones).

Leaving the question of griefer scripts aside, such knowledge is also useful to legitimate scripts (for instance, an animation vendor with a "Try me!" button, which might use osAvatarPlayAnimation() to demonstrate the animation without requiring the user to explicitly grant permission, but fall back to llStartAnimation() in the event that osAvatarPlayAnimation() is unavailable).

If a script attempts to use an OSSL function that it does not have permission to use, only the current invocation of the event handler which called the function crashes; the script remains running, and the event handler will be executed again the next time the event fires. A script may take advantage of this fact to ascertain which functions are available to it, by using an information-gathering state with a timer to iterate quickly through the OSSL functions it needs; when a function call succeeds, it can then set a variable indicating that the function is available. Once it has iterated through all the functions, it then switches out of the information-gathering state.

<source lang="lsl">
// OSSL Function Availability Tester
//
// Demonstrates a method by which a script may determine whether or not it is permitted to call
// various OSSL functions.
//
integer WhichProbeFunction; // to tell us which function we're probing
integer NumberOfFunctionsToCheck; // how many functions are we probing?
list FunctionNames = [ "osTeleportAgent", "osGetAgentIP", "osGetAgents", "osAvatarPlayAnimation",
"osAvatarStopAnimation", "osAvatarName2Key", "osKey2Name" ];
list FunctionPermitted = [ 0, 0, 0, 0, 0, 0, 0 ]; // 0 = not permitted, 1 = permitted

// isFunctionAvailable() takes the name of a function, and returns 1 if it is available, and 0 if
// it is forbidden or has not been tested.
//
integer isFunctionAvailable( string whichFunction )
{
integer index = llListFindList( FunctionNames, whichFunction );
if (index == -1) return 0; // Return FALSE if the function name wasn't one of the ones we checked.
return llList2Integer( FunctionPermitted, index ); // return the appropriate availability flag.
}

// The default state uses the timer to call all the OSSL functions we're interested in using, in turn.
// If the function call fails, the timer event handler will abend, but the script doesn't crash. We can
// use this fact to check all of our desired functions in turn, and then pass control to the Running
// state once we've checked them all.
//
default
{
state_entry()
{
llOwnerSay( "Probing OSSL functions to see what we can use" );
NumberOfFunctionsToCheck = llGetListLength( FunctionNames );
WhichProbeFunction = -1;
llSetTimerEvent( 0.25 ); // check only four functions a second, just to be nice.
}

timer()
{
string BogusKey = "12345678-1234-1234-1234-123456789abc"; // it doesn't need to be valid
string s; // for storing the result of string functions
list l; // for storing the result of list functions
if (++WhichProbeFunction == NumberOfFunctionsToCheck) // Increment WhichProbeFunction; exit if we're done
{
llSetTimerEvent( 0.0 ); // stop the timer
state Running; // switch to the Running state
}
llOwnerSay( "Checking function " + llList2String( FunctionNames, WhichProbeFunction )); // say status
if (WhichProbeFunction == 0)
osTeleportAgent( BogusKey, ZERO_VECTOR, ZERO_VECTOR );
else if (WhichProbeFunction == 1)
s = osGetAgentIP( BogusKey );
else if (WhichProbeFunction == 2)
l = osGetAgents();
else if (WhichProbeFunction == 3)
osAvatarPlayAnimation( BogusKey, BogusKey );
else if (WhichProbeFunction == 4)
osAvatarStopAnimation( BogusKey, BogusKey );
else if (WhichProbeFunction == 5)
s = osAvatarName2Key( "John", "Smith" );
else if (WhichProbeFunction == 6)
s = osKey2Name( BogusKey );

// If we got here, then the timer() handler didn't crash, which means the function it checked for
// was actually permitted. So we update the list to indicate that we can use that particular function.
FunctionPermitted = llListReplaceList( FunctionPermitted, [ 1 ], WhichProbeFunction, WhichProbeFunction );
}
}

state Running
{
state_entry()
{
string s = "Here are the functions we can use: ";
string t = "Here are the functions we cannot use: ";
integer i = llGetListLength( FunctionNames );
while (i--)
if (llList2Integer( FunctionPermitted, i ))
s += llList2String( FunctionNames, i ) + " ";
else
t += llList2String( FunctionNames, i ) + " ";
llOwnerSay( s );
llOwnerSay( t );
if (isFunctionAvailable( "osKey2Name" ))
{
key theUUID = "190482f8-b1bc-4c36-aa8d-cfb36c8fea61";
llOwnerSay( "UUID " + (string) theUUID + " maps to the name " + osKey2Name( theUUID ) + "." );
}
else
{
llOwnerSay( "osKey2Name() is unavailable; cannot map UUID to name." );
}
}
}
</source>

Threat level

2009-08-18T23:07:58Z

Godfrey: Fixed comment in the example script so that it more closely resembles reality.

{{Template:Quicklinks}}
To permit region owners to enable the extended scripting functionality of [[OSSL]], without allowing malicious scripts to access potentially troublesome functions, each OSSL function is assigned a '''threat level''', and access to the functions is granted or denied based on a default threshold set in [[OpenSim.ini]] (which can be overridden for individual functions on a case-by-case basis).

The threat levels, from wholly unthreatening to most potentially damaging, are:

;None
:Function is no threat at all. It doesn't constitute a threat to either users or the system and has no known side effects.
;Nuisance
:Abuse of this command can cause a nuisance to the region operator, such as log message spew.
;VeryLow
:Extreme levels of abuse of this function can cause impaired functioning of the region, or very gullible users can be tricked into experiencing harmless effects.
;Low
:Intentional abuse can cause crashes or malfunction under certain circumstances, which can be easily rectified; or certain users can be tricked into certain situations in an avoidable manner.
;Moderate
:Intentional abuse can cause denial of service and crashes with potential of data or state loss; or trusting users can be tricked into embarrassing or uncomfortable situations.
;High
:Casual abuse can cause impaired functionality or temporary denial of service conditions. Intentional abuse can easily cause crashes with potential data loss, or can be used to trick experienced and cautious users into unwanted situations, or changes global data permanently and without undo ability.
;VeryHigh
:Even normal use may, depending on the number of instances, or frequency of use, result in severe service impairment or crash with loss of data, or can be used to cause unwanted or harmful effects on users without giving the user a means to avoid it.
;Severe
:Even casual use is a danger to region stability, or function allows console or OS command execution, or function allows taking money without consent, or allows deletion or modification of user data, or allows the compromise of sensitive data by design.

The '''OSFunctionThreatLevel''' setting in the script engines' configuration sections of [[OpenSim.ini]] controls what classes of functions are accessible to scripts owned by any avatar; any function at the same threat level or lower than the value provided for '''OsFunctionThreatLevel''' is permitted to run. If '''OSFunctionThreatLevel''' is absent from the configuration file, the default value is '''VeryLow'''.

OSSL functions may also be permitted or prohibited on an individual basis, by adding '''Allow_*''' lines to the script engine's configuration section. To permit scripts owned by anyone to access a function, even if its threat level exceeds the value of '''OSFunctionThreatLevel''', use the value 'true':

<source lang="ini">
Allow_osMakeNotecard = true
</source>

To prohibit scripts owned by anyone from accessing a function, even if its threat level is equal to or below the value of '''OSFunctionThreatLevel''', use the value 'false':

<source lang="ini">
Allow_osMovePen = false
</source>

To allow scripts owned by only certain avatars to access a function, use the UUIDs of the avatars owning the scripts. If multiple avatars are to be permitted access, separate the UUIDs with commas:

<source lang="ini">
Allow_osMakeNotecard = a1cbbdd7-8adb-4158-aa52-c0ee882c4492
Allow_osTeleportAgent = a1cbbdd7-8adb-4158-aa52-c0ee882c4492,9cab27da-764c-4469-a628-369d978ba436
</source>

Below is a list of OSSL functions grouped by threat level:

;None
:[[osDrawEllipse]], [[osDrawFilledRectangle]], [[osDrawImage]], [[osDrawLine]], [[osDrawRectangle]], [[osDrawText]], [[osGetAgents]], [[osGetCurrentSunHour]], [[osList2Double]], [[osMovePen]], [[osParseJSON]], [[osSetFontSize]], [[osSetPenColour]], [[osSetPenSize]], [[osSunGetParam]], [[osSunSetParam]], [[osTerrainGetHeight]], [[osWindActiveModelPluginName]]

;Nuisance
:[[osSetRegionSunSettings]], [[osSetEstateSunSettings]]

;VeryLow
:[[osGetDrawStringSize]], [[osSetDynamicTextureData]], [[osSetDynamicTextureDataBlend]], [[osSetDynamicTextureDataBlendFace]], [[osSetDynamicTextureURL]], [[osSetDynamicTextureURLBlend]], [[osSetDynamicTextureURLBlendFace]], [[osSetParcelMediaURL]], [[osSetPrimFloatOnWater]], [[osTerrainFlush]], [[osWindParamGet]], [[osWindParamSet]]

;Low
:[[osAvatarName2Key]], [[osFormatString]], [[osKey2Name]], [[osLoadedCreationDate]], [[osLoadedCreationID]], [[osLoadedCreationTime]], [[osMessageObject]]

;Moderate
:[[osGetGridLoginURI]], [[osGetGridName]], [[osGetGridNick]]

;High
:[[osGetAgentIP]], [[osGetScriptEngineName]], [[osGetSimulatorVersion]], [[osMakeNotecard]], [[osMatchString]], [[osRegionRestart]], [[osSetRegionWaterHeight]], [[osSetStateEvents]], [[osTeleportAgent]], [[osTerrainSetHeight]]

;VeryHigh
:[[osAvatarPlayAnimation]], [[osAvatarStopAnimation]], [[osGetNotecard]], [[osGetNotecardLine]], [[osGetNumberOfNotecardLines]], [[osRegionNotice]], [[osSetRot]]

;Severe
:[[osConsoleCommand]]

== Ascertaining privilege to use a function ==

There is not currently a function which would allow a script to determine whether or not it has permission to use any specific OSSL function. Such a function was proposed, but rejected by a developer on the grounds that it could permit a griefer script too much knowledge of its environment (though, as shown below, this information is already available through other methods, albeit less efficient ones).

Leaving the question of griefer scripts aside, such knowledge is also useful to legitimate scripts (for instance, an animation vendor with a "Try me!" button, which might use osAvatarPlayAnimation() to demonstrate the animation without requiring the user to explicitly grant permission, but fall back to llStartAnimation() in the event that osAvatarPlayAnimation() is unavailable).

If a script attempts to use an OSSL function that it does not have permission to use, only the current invocation of the event handler which called the function crashes; the script remains running, and the event handler will be executed again the next time the event fires. A script may take advantage of this fact to ascertain which functions are available to it, by using an information-gathering state with a timer to iterate quickly through the OSSL functions it needs; when a function call succeeds, it can then set a variable indicating that the function is available. Once it has iterated through all the functions, it then switches out of the information-gathering state.

<source lang="lsl">
// OSSL Function Availability Tester
//
// Demonstrates a method by which a script may determine whether or not it is permitted to call
// various OSSL functions.
//
integer WhichProbeFunction; // to tell us which function we're probing
integer NumberOfFunctionsToCheck; // how many functions are we probing?
list FunctionNames = [ "osTeleportAgent", "osGetAgentIP", "osGetAgents", "osAvatarPlayAnimation",
"osAvatarStopAnimation", "osAvatarName2Key", "osKey2Name" ];
list FunctionPermitted = [ 0, 0, 0, 0, 0, 0, 0 ]; // 0 = not permitted, 1 = permitted

// isFunctionAvailable() takes the name of a function, and returns 1 if it is available, and 0 if
// it is forbidden or has not been tested.
//
integer isFunctionAvailable( string whichFunction )
{
integer index = llListFindList( FunctionNames, whichFunction );
if (index == -1) return 0; // Return FALSE if the function name wasn't one of the ones we checked.
return llList2Integer( FunctionPermitted, index ); // return the appropriate availability flag.
}

// The default state uses the timer to call all the OSSL functions we're interested in using, in turn.
// If the function call fails, the timer event handler will abend, but the script doesn't crash. We can
// use this fact to check all of our desired functions in turn, and then pass control to the Running
// state once we've checked them all.
//
default
{
state_entry()
{
llOwnerSay( "Probing OSSL functions to see what we can use" );
NumberOfFunctionsToCheck = llGetListLength( FunctionNames );
WhichProbeFunction = -1;
llSetTimerEvent( 0.25 ); // check only four functions a second, just to be nice.
}

timer()
{
string BogusKey = "12345678-1234-1234-1234-123456789abc"; // it doesn't need to be valid
string s; // for storing the result of string functions
list l; // for storing the result of list functions
if (++WhichProbeFunction == NumberOfFunctionsToCheck) // Increment WhichProbeFunction; exit if we're done
{
llSetTimerEvent( 0.0 ); // stop the timer
state Running; // switch to the Running state
}
llOwnerSay( "Checking function " + llList2String( FunctionNames, WhichProbeFunction )); // say status
if (WhichProbeFunction == 0)
osTeleportAgent( BogusKey, ZERO_VECTOR, ZERO_VECTOR );
else if (WhichProbeFunction == 1)
s = osGetAgentIP( BogusKey );
else if (WhichProbeFunction == 2)
l = osGetAgents();
else if (WhichProbeFunction == 3)
osAvatarPlayAnimation( BogusKey, BogusKey );
else if (WhichProbeFunction == 4)
osAvatarStopAnimation( BogusKey, BogusKey );
else if (WhichProbeFunction == 5)
s = osAvatarName2Key( "John", "Smith" );
else if (WhichProbeFunction == 6)
s = osKey2Name( BogusKey );

// If we got here, then the timer() handler didn't crash, which means the function it checked for
// was actually permitted. So we update the list to indicate that we can use that particular function.
FunctionPermitted = llListReplaceList( FunctionPermitted, [ 1 ], WhichProbeFunction, WhichProbeFunction );
}
}

state Running
{
state_entry()
{
string s = "Here are the functions we can use: ";
string t = "Here are the functions we cannot use: ";
integer i = llGetListLength( FunctionNames );
while (i--)
if (llList2Integer( FunctionPermitted, i ))
s += llList2String( FunctionNames, i ) + " ";
else
t += llList2String( FunctionNames, i ) + " ";
llOwnerSay( s );
llOwnerSay( t );
if (isFunctionAvailable( "osKey2Name" ))
{
key theUUID = "190482f8-b1bc-4c36-aa8d-cfb36c8fea61";
llOwnerSay( "UUID " + (string) theUUID + " maps to the name " + osKey2Name( theUUID ) + "." );
}
else
{
llOwnerSay( "osKey2Name() is unavailable; cannot map UUID to name." );
}
}
}
</source>

Threat level

2009-08-13T16:30:42Z

Godfrey: Added section: "Ascertaining privilege to use a function"

{{Template:Quicklinks}}
To permit region owners to enable the extended scripting functionality of [[OSSL]], without allowing malicious scripts to access potentially troublesome functions, each OSSL function is assigned a '''threat level''', and access to the functions is granted or denied based on a default threshold set in [[OpenSim.ini]] (which can be overridden for individual functions on a case-by-case basis).

The threat levels, from wholly unthreatening to most potentially damaging, are:

;None
:Function is no threat at all. It doesn't constitute a threat to either users or the system and has no known side effects.
;Nuisance
:Abuse of this command can cause a nuisance to the region operator, such as log message spew.
;VeryLow
:Extreme levels of abuse of this function can cause impaired functioning of the region, or very gullible users can be tricked into experiencing harmless effects.
;Low
:Intentional abuse can cause crashes or malfunction under certain circumstances, which can be easily rectified; or certain users can be tricked into certain situations in an avoidable manner.
;Moderate
:Intentional abuse can cause denial of service and crashes with potential of data or state loss; or trusting users can be tricked into embarrassing or uncomfortable situations.
;High
:Casual abuse can cause impaired functionality or temporary denial of service conditions. Intentional abuse can easily cause crashes with potential data loss, or can be used to trick experienced and cautious users into unwanted situations, or changes global data permanently and without undo ability.
;VeryHigh
:Even normal use may, depending on the number of instances, or frequency of use, result in severe service impairment or crash with loss of data, or can be used to cause unwanted or harmful effects on users without giving the user a means to avoid it.
;Severe
:Even casual use is a danger to region stability, or function allows console or OS command execution, or function allows taking money without consent, or allows deletion or modification of user data, or allows the compromise of sensitive data by design.

The '''OSFunctionThreatLevel''' setting in the script engines' configuration sections of [[OpenSim.ini]] controls what classes of functions are accessible to scripts owned by any avatar; any function at the same threat level or lower than the value provided for '''OsFunctionThreatLevel''' is permitted to run. If '''OSFunctionThreatLevel''' is absent from the configuration file, the default value is '''VeryLow'''.

OSSL functions may also be permitted or prohibited on an individual basis, by adding '''Allow_*''' lines to the script engine's configuration section. To permit scripts owned by anyone to access a function, even if its threat level exceeds the value of '''OSFunctionThreatLevel''', use the value 'true':

<source lang="ini">
Allow_osMakeNotecard = true
</source>

To prohibit scripts owned by anyone from accessing a function, even if its threat level is equal to or below the value of '''OSFunctionThreatLevel''', use the value 'false':

<source lang="ini">
Allow_osMovePen = false
</source>

To allow scripts owned by only certain avatars to access a function, use the UUIDs of the avatars owning the scripts. If multiple avatars are to be permitted access, separate the UUIDs with commas:

<source lang="ini">
Allow_osMakeNotecard = a1cbbdd7-8adb-4158-aa52-c0ee882c4492
Allow_osTeleportAgent = a1cbbdd7-8adb-4158-aa52-c0ee882c4492,9cab27da-764c-4469-a628-369d978ba436
</source>

Below is a list of OSSL functions grouped by threat level:

;None
:[[osDrawEllipse]], [[osDrawFilledRectangle]], [[osDrawImage]], [[osDrawLine]], [[osDrawRectangle]], [[osDrawText]], [[osGetAgents]], [[osGetCurrentSunHour]], [[osList2Double]], [[osMovePen]], [[osParseJSON]], [[osSetFontSize]], [[osSetPenColour]], [[osSetPenSize]], [[osSunGetParam]], [[osSunSetParam]], [[osTerrainGetHeight]], [[osWindActiveModelPluginName]]

;Nuisance
:[[osSetRegionSunSettings]], [[osSetEstateSunSettings]]

;VeryLow
:[[osGetDrawStringSize]], [[osSetDynamicTextureData]], [[osSetDynamicTextureDataBlend]], [[osSetDynamicTextureDataBlendFace]], [[osSetDynamicTextureURL]], [[osSetDynamicTextureURLBlend]], [[osSetDynamicTextureURLBlendFace]], [[osSetParcelMediaURL]], [[osSetPrimFloatOnWater]], [[osTerrainFlush]], [[osWindParamGet]], [[osWindParamSet]]

;Low
:[[osAvatarName2Key]], [[osFormatString]], [[osKey2Name]], [[osLoadedCreationDate]], [[osLoadedCreationID]], [[osLoadedCreationTime]], [[osMessageObject]]

;Moderate
:[[osGetGridLoginURI]], [[osGetGridName]], [[osGetGridNick]]

;High
:[[osGetAgentIP]], [[osGetScriptEngineName]], [[osGetSimulatorVersion]], [[osMakeNotecard]], [[osMatchString]], [[osRegionRestart]], [[osSetRegionWaterHeight]], [[osSetStateEvents]], [[osTeleportAgent]], [[osTerrainSetHeight]]

;VeryHigh
:[[osAvatarPlayAnimation]], [[osAvatarStopAnimation]], [[osGetNotecard]], [[osGetNotecardLine]], [[osGetNumberOfNotecardLines]], [[osRegionNotice]], [[osSetRot]]

;Severe
:[[osConsoleCommand]]

== Ascertaining privilege to use a function ==

There is not currently a function which would allow a script to determine whether or not it has permission to use any specific OSSL function. Such a function was proposed, but rejected by a developer on the grounds that it could permit a griefer script too much knowledge of its environment (though, as shown below, this information is already available through other methods, albeit less efficient ones).

Leaving the question of griefer scripts aside, such knowledge is also useful to legitimate scripts (for instance, an animation vendor with a "Try me!" button, which might use osAvatarPlayAnimation() to demonstrate the animation without requiring the user to explicitly grant permission, but fall back to llStartAnimation() in the event that osAvatarPlayAnimation() is unavailable).

If a script attempts to use an OSSL function that it does not have permission to use, only the current invocation of the event handler which called the function crashes; the script remains running, and the event handler will be executed again the next time the event fires. A script may take advantage of this fact to ascertain which functions are available to it, by using an information-gathering state with a timer to iterate quickly through the OSSL functions it needs; when a function call succeeds, it can then set a variable indicating that the function is available. Once it has iterated through all the functions, it then switches out of the information-gathering state.

<source lang="lsl">
// OSSL Function Availability Tester
//
// Demonstrates a method by which a script may determine whether or not it is permitted to call
// various OSSL functions.
//
integer WhichProbeFunction; // to tell us which function we're probing
integer NumberOfFunctionsToCheck; // how many functions are we probing?
list FunctionNames = [ "osTeleportAgent", "osGetAgentIP", "osGetAgents", "osAvatarPlayAnimation",
"osAvatarStopAnimation", "osAvatarName2Key", "osKey2Name" ];
list FunctionPermitted = [ 0, 0, 0, 0, 0, 0, 0 ]; // 0 = not permitted, 1 = permitted

// isFunctionAvailable() is not actually used in this script; this is just an example of how it
// could be implemented.
integer isFunctionAvailable( string whichFunction )
{
integer index = llListFindList( FunctionNames, whichFunction );
if (index == -1) return 0; // Return FALSE if the function name wasn't one of the ones we checked.
return llList2Integer( FunctionPermitted, index ); // return the appropriate availability flag.
}

// The default state uses the timer to call all the OSSL functions we're interested in using, in turn.
// If the function call fails, the timer event handler will abend, but the script doesn't crash. We can
// use this fact to check all of our desired functions in turn, and then pass control to the Running
// state once we've checked them all.
default
{
state_entry()
{
llOwnerSay( "Probing OSSL functions to see what we can use" );
NumberOfFunctionsToCheck = llGetListLength( FunctionNames );
WhichProbeFunction = -1;
llSetTimerEvent( 0.25 ); // check only four functions a second, just to be nice.
}

timer()
{
string BogusKey = "12345678-1234-1234-1234-123456789abc"; // it doesn't need to be valid
string s; // for storing the result of string functions
list l; // for storing the result of list functions
if (++WhichProbeFunction == NumberOfFunctionsToCheck) // Increment WhichProbeFunction; exit if we're done
{
llSetTimerEvent( 0.0 ); // stop the timer
state Running; // switch to the Running state
}
llOwnerSay( "Checking function " + llList2String( FunctionNames, WhichProbeFunction )); // say status
if (WhichProbeFunction == 0)
osTeleportAgent( BogusKey, ZERO_VECTOR, ZERO_VECTOR );
else if (WhichProbeFunction == 1)
s = osGetAgentIP( BogusKey );
else if (WhichProbeFunction == 2)
l = osGetAgents();
else if (WhichProbeFunction == 3)
osAvatarPlayAnimation( BogusKey, BogusKey );
else if (WhichProbeFunction == 4)
osAvatarStopAnimation( BogusKey, BogusKey );
else if (WhichProbeFunction == 5)
s = osAvatarName2Key( "John", "Smith" );
else if (WhichProbeFunction == 6)
s = osKey2Name( BogusKey );

// If we got here, then the timer() handler didn't crash, which means the function it checked for
// was actually permitted. So we update the list to indicate that we can use that particular function.
FunctionPermitted = llListReplaceList( FunctionPermitted, [ 1 ], WhichProbeFunction, WhichProbeFunction );
}
}

state Running
{
state_entry()
{
string s = "Here are the functions we can use: ";
string t = "Here are the functions we cannot use: ";
integer i = llGetListLength( FunctionNames );
while (i--)
if (llList2Integer( FunctionPermitted, i ))
s += llList2String( FunctionNames, i ) + " ";
else
t += llList2String( FunctionNames, i ) + " ";
llOwnerSay( s );
llOwnerSay( t );
if (isFunctionAvailable( "osKey2Name" ))
{
key theUUID = "190482f8-b1bc-4c36-aa8d-cfb36c8fea61";
llOwnerSay( "UUID " + (string) theUUID + " maps to the name " + osKey2Name( theUUID ) + "." );
}
else
{
llOwnerSay( "osKey2Name() is unavailable; cannot map UUID to name." );
}
}
}
</source>

Threat level

2009-08-09T17:48:46Z

Godfrey: Clarification

Threat level

2009-07-30T14:53:08Z

Godfrey: Elucidation and minor reformat

Dynamic textures

2009-07-30T14:43:47Z

Godfrey: Linked "threat level" to the appropriate page

{{Template:Quicklinks}}

[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]]

Dynamic textures allow scripts to create images on the fly, combining graphics loaded from the World Wide Web with text, lines, ellipses and filled or unfilled rectangles. The textures thus created are temporary, maintained by the individual region in which they are created, and are not permanently stored in the [[Asset Server]].

In general, one creates a string containing a list of [[Drawing commands]] and parameters, either directly or with the aid of one of the "convenience" drawing functions listed below, then passes this string as a parameter to one of the osSetDynamicTexture* commands.

In the list below, the [[threat level]] of each function is indicated in parentheses after the function name. There is no threat level associated with the [[Drawing_commands | drawing commands]].

{| width="100%"
| valign="top" width="50%"|'''Graphics Primitive Drawing Functions'''
*[[osDrawEllipse]] (None)
*[[osDrawFilledRectangle]] (None)
*[[osDrawImage]] (None)
*[[osDrawLine]] (None)
*[[osDrawRectangle]] (None)
*[[osMovePen]] (None)
*[[osSetPenColour]] (None)
*[[osSetPenSize]] (None)

'''Text Drawing Functions'''
*[[osDrawText]] (None)
*[[osSetFontSize]] (None)
*[[osGetDrawStringSize]] (VeryLow)

'''Dynamic Texture Creation Functions'''
*[[osSetDynamicTextureURL]] (VeryLow)
*[[osSetDynamicTextureURLBlend]] (VeryLow)
*[[osSetDynamicTextureURLBlendFace]] (VeryLow)
*[[osSetDynamicTextureData]] (VeryLow)
*[[osSetDynamicTextureDataBlend]] (VeryLow)
*[[osSetDynamicTextureDataBlendFace]] (VeryLow)
| valign="top" width="50%"|'''Graphics Primitive Drawing Commands'''
*[[Drawing commands#Ellipse|Ellipse]]
*[[Drawing commands#FillRectangle|FillRectangle]]
*[[Drawing commands#Image|Image]]
*[[Drawing commands#LineTo|LineTo]]
*[[Drawing commands#MoveTo|MoveTo]]
*[[Drawing commands#PenColour|PenColour]]
*[[Drawing commands#PenSize|PenSize]]
*[[Drawing commands#Rectangle|Rectangle]]

'''Text Drawing Commands'''
*[[Drawing commands#FontName|FontName]]
*[[Drawing commands#FontProp|FontProp]]
*[[Drawing commands#FontSize|FontSize]]
*[[Drawing commands#Text|Text]]
|}

Threat level

2009-07-30T14:42:33Z

Godfrey: .

{{Template:Quicklinks}}
To permit region owners to enable the extended scripting functionality of [[OSSL]], without allowing malicious scripts to access potentially troublesome functions, each OSSL function is assigned a '''threat level'''. These threat levels, from least threatening to most potentially damaging, are:

;None
:Function is no threat at all. It doesn't constitute a threat to either users or the system and has no known side effects.
;Nuisance
:Abuse of this command can cause a nuisance to the region operator, such as log message spew.
;VeryLow
:Extreme levels of abuse of this function can cause impaired functioning of the region, or very gullible users can be tricked into experiencing harmless effects.
;Low
:Intentional abuse can cause crashes or malfunction under certain circumstances, which can be easily rectified; or certain users can be tricked into certain situations in an avoidable manner.
;Moderate
:Intentional abuse can cause denial of service and crashes with potential of data or state loss; or trusting users can be tricked into embarrassing or uncomfortable situations.
;High
:Casual abuse can cause impaired functionality or temporary denial of service conditions. Intentional abuse can easily cause crashes with potential data loss, or can be used to trick experienced and cautious users into unwanted situations, or changes global data permanently and without undo ability.
;VeryHigh
:Even normal use may, depending on the number of instances, or frequency of use, result in severe service impairment or crash with loss of data, or can be used to cause unwanted or harmful effects on users without giving the user a means to avoid it.
;Severe
:Even casual use is a danger to region stability, or function allows console or OS command execution, or function allows taking money without consent, or allows deletion or modification of user data, or allows the compromise of sensitive data by design.

The '''OSFunctionThreatLevel''' setting in the script engines' configuration sections of [[OpenSim.ini]] controls what classes of functions are accessible to scripts owned by any avatar; any function at the same threat level or lower than the value provided for '''OsFunctionThreatLevel''' is permitted to run. If '''OSFunctionThreatLevel''' is absent from the configuration file, the default value is '''VeryLow'''.

OSSL functions may also be permitted or prohibited on an individual basis, by adding '''Allow_*''' lines to the script engine's configuration section. To permit scripts owned by anyone to access a function, even if its threat level exceeds the value of '''OSFunctionThreatLevel''', use the value 'true':

<source lang="ini">
Allow_osMakeNotecard = true
</source>

To prohibit scripts owned by anyone from accessing a function, even if its threat level is equal to or below the value of '''OSFunctionThreatLevel''', use the value 'false':

<source lang="ini">
Allow_osMovePen = false
</source>

To allow scripts owned by only certain avatars to access a function, use the UUIDs of the avatars. If multiple avatars are to be permitted access, separate the UUIDs with commas:

<source lang="ini">
Allow_osMakeNotecard = a1cbbdd7-8adb-4158-aa52-c0ee882c4492
Allow_osTeleportAgent = a1cbbdd7-8adb-4158-aa52-c0ee882c4492,9cab27da-764c-4469-a628-369d978ba436
</source>

Below is a list of OSSL functions grouped by threat level:

;None
:[[osDrawEllipse]], [[osDrawFilledRectangle]], [[osDrawImage]], [[osDrawLine]], [[osDrawRectangle]], [[osDrawText]], [[osGetAgents]], [[osGetCurrentSunHour]], [[osList2Double]], [[osMovePen]], [[osParseJSON]], [[osSetFontSize]], [[osSetPenColour]], [[osSetPenSize]], [[osSunGetParam]], [[osSunSetParam]], [[osTerrainGetHeight]], [[osWindActiveModelPluginName]]

;Nuisance
:[[osSetRegionSunSettings]], [[osSetEstateSunSettings]]

;VeryLow
:[[osGetDrawStringSize]], [[osSetDynamicTextureData]], [[osSetDynamicTextureDataBlend]], [[osSetDynamicTextureDataBlendFace]], [[osSetDynamicTextureURL]], [[osSetDynamicTextureURLBlend]], [[osSetDynamicTextureURLBlendFace]], [[osSetParcelMediaURL]], [[osSetPrimFloatOnWater]], [[osTerrainFlush]], [[osWindParamGet]], [[osWindParamSet]]

;Low
:[[osAvatarName2Key]], [[osFormatString]], [[osKey2Name]], [[osLoadedCreationDate]], [[osLoadedCreationID]], [[osLoadedCreationTime]], [[osMessageObject]]

;Moderate
:[[osGetGridLoginURI]], [[osGetGridName]], [[osGetGridNick]]

;High
:[[osGetAgentIP]], [[osGetScriptEngineName]], [[osGetSimulatorVersion]], [[osMakeNotecard]], [[osMatchString]], [[osRegionRestart]], [[osSetRegionWaterHeight]], [[osSetStateEvents]], [[osTeleportAgent]], [[osTerrainSetHeight]]

;VeryHigh
:[[osAvatarPlayAnimation]], [[osAvatarStopAnimation]], [[osGetNotecard]], [[osGetNotecardLine]], [[osGetNumberOfNotecardLines]], [[osRegionNotice]], [[osSetRot]]

;Severe
:[[osConsoleCommand]]

Threat level

2009-07-30T14:41:58Z

Godfrey: Got, a little, carried away, with the commas, there,

{{Template:Quicklinks}}
To permit region owners to enable the extended scripting functionality of [[OSSL]], without allowing malicious scripts to access potentially troublesome functions, each OSSL function is assigned a '''threat level'''. These threat levels, from least threatening to most potentially damaging, are:

;None
:Function is no threat at all. It doesn't constitute a threat to either users or the system and has no known side effects.
;Nuisance
:Abuse of this command can cause a nuisance to the region operator, such as log message spew.
;VeryLow
:Extreme levels of abuse of this function can cause impaired functioning of the region, or very gullible users can be tricked into experiencing harmless effects
;Low
:Intentional abuse can cause crashes or malfunction under certain circumstances, which can be easily rectified; or certain users can be tricked into certain situations in an avoidable manner.
;Moderate
:Intentional abuse can cause denial of service and crashes with potential of data or state loss; or trusting users can be tricked into embarrassing or uncomfortable situations.
;High
:Casual abuse can cause impaired functionality or temporary denial of service conditions. Intentional abuse can easily cause crashes with potential data loss, or can be used to trick experienced and cautious users into unwanted situations, or changes global data permanently and without undo ability.
;VeryHigh
:Even normal use may, depending on the number of instances, or frequency of use, result in severe service impairment or crash with loss of data, or can be used to cause unwanted or harmful effects on users without giving the user a means to avoid it.
;Severe
:Even casual use is a danger to region stability, or function allows console or OS command execution, or function allows taking money without consent, or allows deletion or modification of user data, or allows the compromise of sensitive data by design.

The '''OSFunctionThreatLevel''' setting in the script engines' configuration sections of [[OpenSim.ini]] controls what classes of functions are accessible to scripts owned by any avatar; any function at the same threat level or lower than the value provided for '''OsFunctionThreatLevel''' is permitted to run. If '''OSFunctionThreatLevel''' is absent from the configuration file, the default value is '''VeryLow'''.

OSSL functions may also be permitted or prohibited on an individual basis, by adding '''Allow_*''' lines to the script engine's configuration section. To permit scripts owned by anyone to access a function, even if its threat level exceeds the value of '''OSFunctionThreatLevel''', use the value 'true':

<source lang="ini">
Allow_osMakeNotecard = true
</source>

To prohibit scripts owned by anyone from accessing a function, even if its threat level is equal to or below the value of '''OSFunctionThreatLevel''', use the value 'false':

<source lang="ini">
Allow_osMovePen = false
</source>

To allow scripts owned by only certain avatars to access a function, use the UUIDs of the avatars. If multiple avatars are to be permitted access, separate the UUIDs with commas:

<source lang="ini">
Allow_osMakeNotecard = a1cbbdd7-8adb-4158-aa52-c0ee882c4492
Allow_osTeleportAgent = a1cbbdd7-8adb-4158-aa52-c0ee882c4492,9cab27da-764c-4469-a628-369d978ba436
</source>

Below is a list of OSSL functions grouped by threat level:

;None
:[[osDrawEllipse]], [[osDrawFilledRectangle]], [[osDrawImage]], [[osDrawLine]], [[osDrawRectangle]], [[osDrawText]], [[osGetAgents]], [[osGetCurrentSunHour]], [[osList2Double]], [[osMovePen]], [[osParseJSON]], [[osSetFontSize]], [[osSetPenColour]], [[osSetPenSize]], [[osSunGetParam]], [[osSunSetParam]], [[osTerrainGetHeight]], [[osWindActiveModelPluginName]]

;Nuisance
:[[osSetRegionSunSettings]], [[osSetEstateSunSettings]]

;VeryLow
:[[osGetDrawStringSize]], [[osSetDynamicTextureData]], [[osSetDynamicTextureDataBlend]], [[osSetDynamicTextureDataBlendFace]], [[osSetDynamicTextureURL]], [[osSetDynamicTextureURLBlend]], [[osSetDynamicTextureURLBlendFace]], [[osSetParcelMediaURL]], [[osSetPrimFloatOnWater]], [[osTerrainFlush]], [[osWindParamGet]], [[osWindParamSet]]

;Low
:[[osAvatarName2Key]], [[osFormatString]], [[osKey2Name]], [[osLoadedCreationDate]], [[osLoadedCreationID]], [[osLoadedCreationTime]], [[osMessageObject]]

;Moderate
:[[osGetGridLoginURI]], [[osGetGridName]], [[osGetGridNick]]

;High
:[[osGetAgentIP]], [[osGetScriptEngineName]], [[osGetSimulatorVersion]], [[osMakeNotecard]], [[osMatchString]], [[osRegionRestart]], [[osSetRegionWaterHeight]], [[osSetStateEvents]], [[osTeleportAgent]], [[osTerrainSetHeight]]

;VeryHigh
:[[osAvatarPlayAnimation]], [[osAvatarStopAnimation]], [[osGetNotecard]], [[osGetNotecardLine]], [[osGetNumberOfNotecardLines]], [[osRegionNotice]], [[osSetRot]]

;Severe
:[[osConsoleCommand]]

Threat level

2009-07-30T14:40:17Z

Godfrey: Added definitions of each threat level, and list of functions grouped by threat level.

{{Template:Quicklinks}}
To permit region owners to enable the extended scripting functionality of [[OSSL]], without allowing malicious scripts to access potentially troublesome functions, each OSSL function is assigned a '''threat level'''. These threat levels, from least threatening to most potentially damaging, are:

;None
:Function is no threat at all. It doesn't constitute a threat to either users or the system and has no known side effects.
;Nuisance
:Abuse of this command can cause a nuisance to the region operator, such as log message spew.
;VeryLow
:Extreme levels of abuse of this function can cause impaired functioning of the region, or very gullible users can be tricked into experiencing harmless effects
;Low
:Intentional abuse can cause crashes or malfunction under certain circumstances, which can be easily rectified; or certain users can be tricked into certain situations in an avoidable manner.
;Moderate
:Intentional abuse can cause denial of service and crashes with potential of data or state loss; or trusting users can be tricked into embarrassing or uncomfortable situations.
;High
:Casual abuse can cause impaired functionality or temporary denial of service conditions. Intentional abuse can easily cause crashes with potential data loss, or can be used to trick experienced and cautious users into unwanted situations, or changes global data permanently and without undo ability.
;VeryHigh
:Even normal use may, depending on the number of instances, or frequency of use, result in severe service impairment or crash with loss of data, or can be used to cause unwanted or harmful effects on users without giving the user a means to avoid it.
;Severe
:Even casual use is a danger to region stability, or function allows console or OS command execution, or function allows taking money without consent, or allows deletion or modification of user data, or allows the compromise of sensitive data by design.

The '''OSFunctionThreatLevel''' setting in the script engines' configuration sections of [[OpenSim.ini]] controls what classes of functions are accessible to scripts owned by any avatar; any function at the same threat level or lower than the value provided for '''OsFunctionThreatLevel''' is permitted to run. If '''OSFunctionThreatLevel''' is absent from the configuration file, the default value is '''VeryLow'''.

OSSL functions may also be permitted or prohibited on an individual basis, by adding '''Allow_*''' lines to the script engine's configuration section. To permit scripts owned by anyone to access a function, even if its threat level exceeds the value of '''OSFunctionThreatLevel''', use the value 'true':

<source lang="ini">
Allow_osMakeNotecard = true
</source>

To prohibit scripts owned by anyone from accessing a function, even if its threat level is equal to or below the value of '''OSFunctionThreatLevel''', use the value 'false':

<source lang="ini">
Allow_osMovePen = false
</source>

To allow scripts owned by only certain avatars to access a function, use the UUIDs of the avatars. If multiple avatars are to be permitted access, separate the UUIDs with commas:

<source lang="ini">
Allow_osMakeNotecard = a1cbbdd7-8adb-4158-aa52-c0ee882c4492
Allow_osTeleportAgent = a1cbbdd7-8adb-4158-aa52-c0ee882c4492,9cab27da-764c-4469-a628-369d978ba436
</source>

Below is a list of OSSL functions grouped by threat level:

;None
:[[osDrawEllipse]], [[osDrawFilledRectangle]], [[osDrawImage]], [[osDrawLine]], [[osDrawRectangle]], [[osDrawText]], [[osGetAgents]], [[osGetCurrentSunHour]], [[osList2Double]], [[osMovePen]], [[osParseJSON]], [[osSetFontSize]], [[osSetPenColour]], [[osSetPenSize]], [[osSunGetParam]], [[osSunSetParam]], [[osTerrainGetHeight]], [[osWindActiveModelPluginName]]

;Nuisance
:[[osSetRegionSunSettings]], [[osSetEstateSunSettings]],

;VeryLow
:[[osGetDrawStringSize]], [[osSetDynamicTextureData]], [[osSetDynamicTextureDataBlend]], [[osSetDynamicTextureDataBlendFace]], [[osSetDynamicTextureURL]], [[osSetDynamicTextureURLBlend]], [[osSetDynamicTextureURLBlendFace]], [[osSetParcelMediaURL]], [[osSetPrimFloatOnWater]], [[osTerrainFlush]], [[osWindParamGet]], [[osWindParamSet]]

;Low
:[[osAvatarName2Key]], [[osFormatString]], [[osKey2Name]], [[osLoadedCreationDate]], [[osLoadedCreationID]], [[osLoadedCreationTime]], [[osMessageObject]]

;Moderate
:[[osGetGridLoginURI]], [[osGetGridName]], [[osGetGridNick]]

;High
:[[osGetAgentIP]], [[osGetScriptEngineName]], [[osGetSimulatorVersion]], [[osMakeNotecard]], [[osMatchString]], [[osRegionRestart]], [[osSetRegionWaterHeight]], [[osSetStateEvents]], [[osTeleportAgent]], [[osTerrainSetHeight]],

;VeryHigh
:[[osAvatarPlayAnimation]], [[osAvatarStopAnimation]], [[osGetNotecard]], [[osGetNotecardLine]], [[osGetNumberOfNotecardLines]], [[osRegionNotice]], [[osSetRot]]

;Severe
:[[osConsoleCommand]]

Threat level

2009-07-30T14:09:21Z

Godfrey: Page created.

{{Template:Quicklinks}}
To permit region owners to enable the extended scripting functionality of [[OSSL]], without allowing malicious scripts to access potentially troublesome functions, each OSSL function is assigned a '''threat level'''. These threat levels, from least threatening to most potentially damaging, are '''None''', '''VeryLow''', '''Low''', '''Moderate''', '''High''', '''VeryHigh''' and '''Severe'''. A function with a threat level of '''None''' poses no risk whatsoever; a threat level of '''Severe''' indicates potential for the region to be compromised. Threat levels in between generally indicate the capability of the function to affect the performance of the region or grid if abused by a malicious script.

The '''OSFunctionThreatLevel''' setting in the script engines' configuration sections of [[OpenSim.ini]] controls what classes of functions are accessible to scripts owned by any avatar; any function at the same threat level or lower than the value provided for '''OsFunctionThreatLevel''' is permitted to run. If '''OSFunctionThreatLevel''' is absent from the configuration file, the default value is '''VeryLow'''.

OSSL functions may also be permitted or prohibited on an individual basis, by adding '''Allow_*''' lines to the script engine's configuration section. To permit scripts owned by anyone to access a function, even if its threat level exceeds the value of '''OSFunctionThreatLevel''', use the value 'true':

<source lang="ini">
Allow_osMakeNotecard = true
</source>

To prohibit scripts owned by anyone from accessing a function, even if its threat level is equal to or below the value of '''OSFunctionThreatLevel''', use the value 'false':

<source lang="ini">
Allow_osMovePen = false
</source>

To allow scripts owned by only certain avatars to access a function, use the UUIDs of the avatars. If multiple avatars are to be permitted access, separate the UUIDs with commas:

<source lang="ini">
Allow_osMakeNotecard = a1cbbdd7-8adb-4158-aa52-c0ee882c4492
Allow_osTeleportAgent = a1cbbdd7-8adb-4158-aa52-c0ee882c4492,9cab27da-764c-4469-a628-369d978ba436
</source>

Dynamic textures

2009-07-30T13:32:17Z

Godfrey: Added threat levels

{{Template:Quicklinks}}

[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]]

Dynamic textures allow scripts to create images on the fly, combining graphics loaded from the World Wide Web with text, lines, ellipses and filled or unfilled rectangles. The textures thus created are temporary, maintained by the individual region in which they are created, and are not permanently stored in the [[Asset Server]].

In general, one creates a string containing a list of [[Drawing commands]] and parameters, either directly or with the aid of one of the "convenience" drawing functions listed below, then passes this string as a parameter to one of the osSetDynamicTexture* commands.

In the list below, the threat level of each function is indicated in parentheses after the function name. There is no threat level associated with the [[Drawing_commands | drawing commands]].

{| width="100%"
| valign="top" width="50%"|'''Graphics Primitive Drawing Functions'''
*[[osDrawEllipse]] (None)
*[[osDrawFilledRectangle]] (None)
*[[osDrawImage]] (None)
*[[osDrawLine]] (None)
*[[osDrawRectangle]] (None)
*[[osMovePen]] (None)
*[[osSetPenColour]] (None)
*[[osSetPenSize]] (None)

'''Text Drawing Functions'''
*[[osDrawText]] (None)
*[[osSetFontSize]] (None)
*[[osGetDrawStringSize]] (VeryLow)

'''Dynamic Texture Creation Functions'''
*[[osSetDynamicTextureURL]] (VeryLow)
*[[osSetDynamicTextureURLBlend]] (VeryLow)
*[[osSetDynamicTextureURLBlendFace]] (VeryLow)
*[[osSetDynamicTextureData]] (VeryLow)
*[[osSetDynamicTextureDataBlend]] (VeryLow)
*[[osSetDynamicTextureDataBlendFace]] (VeryLow)
| valign="top" width="50%"|'''Graphics Primitive Drawing Commands'''
*[[Drawing commands#Ellipse|Ellipse]]
*[[Drawing commands#FillRectangle|FillRectangle]]
*[[Drawing commands#Image|Image]]
*[[Drawing commands#LineTo|LineTo]]
*[[Drawing commands#MoveTo|MoveTo]]
*[[Drawing commands#PenColour|PenColour]]
*[[Drawing commands#PenSize|PenSize]]
*[[Drawing commands#Rectangle|Rectangle]]

'''Text Drawing Commands'''
*[[Drawing commands#FontName|FontName]]
*[[Drawing commands#FontProp|FontProp]]
*[[Drawing commands#FontSize|FontSize]]
*[[Drawing commands#Text|Text]]
|}

OsGetDrawStringSize

2009-07-30T13:23:54Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsGetDrawStringSize | osGetDrawStringSize]]

LSL: '''[[vector]] osGetDrawStringSize( [[string]] contentType, [[string]] text, [[string]] fontName, [[integer]] fontSize )''' 
C#: '''[[LSL_Vector]] osGetDrawStringSize( [[string]] contentType, [[string]] text, [[string]] fontName, [[int]] fontSize )'''

Returns a vector containing the horizontal and vertical dimensions in pixels of the specified text, if drawn in the specified font and at the specified point size. The horizontal extent is returned in the '''.x''' component of the vector, and the vertical extent is returned in '''.y'''. The '''.z''' component is not used.

The '''contentType''' parameter should be "vector".

If the '''[[OSSetFontSize | osSetFontSize]]'''() function has not been used, and neither the '''[[Drawing_commands#FontName | FontName]]''' nor '''[[Drawing_commands#FontProp | FontProp]]''' commands have been added to the draw list, specify "Arial" as the font name, and 14 as the font size.

Example:
<source lang="lsl">
// Example of osGetDrawStringSize
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
string TextToDraw = "Hello, World!"; // text to draw

vector Extents = osGetDrawStringSize( "vector", TextToDraw, "Arial", 14 );

integer xpos = 128 - ((integer) Extents.x >> 1); // Center the text horizontally
integer ypos = 127 - ((integer) Extents.y >> 1); // and vertically
CommandList = osMovePen( CommandList, xpos, ypos ); // Position the text
CommandList = osDrawText( CommandList, TextToDraw ); // Place the text

// Now draw the text
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

Drawing commands

2009-07-30T13:10:23Z

Godfrey: /* FontSize */ Clarify wording

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[Drawing commands]]

The drawing commands are strings of text which are concatenated to create a larger string of graphical instructions, which is then passed as a parameter to the [[Dynamic textures|dynamic texture]] drawing functions. With two exceptions, there are convenience functions, such as [[osDrawRectangle]](), provided to assist in building the command list. It is slightly more efficient to directly manipulate the string containing the drawing commands, as it avoids the overhead of multiple function calls (albeit with an arguable loss of readability).

In general, the drawing commands consist of a case-sensitive token which identifies the command, followed by one or more comma-delimited parameters, and terminating in a separator character (a semicolon by default). Whitespace surrounding the commas and/or separator is permitted.

In the examples which follow, it is assumed that ''CommandList'' is a string variable which has already been defined within the script source code.

==Graphics Primitive Drawing Commands==

===Ellipse===

;Ellipse float width, float height;
:Draws an ellipse with the current pen size and color.

:The ellipse is drawn with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Ellipse 100,100;";
</source>

===FillRectangle===

;FillRectangle float width, float height;
:Draws a rectangle, bordered and filled with the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "FillRectangle 150,75;";
</source>

===Image===

;Image float height, float width, string URL;
:Retrieves an image specified by the URL parameter and draws it at the specified height and width, with the upper left corner of the image placed at the pen's current position. After the image is drawn, the width and height values are added to the pen's X and Y position, respectively.

:If the URL points to an invalid location, an image type not supported by libgdi, or a non-image MIME type, nothing is drawn. If either or both of the '''width''' or '''height''' parameters are zero or negative, nothing is drawn, but the image is still retrieved.

:Although the '''width''' and '''height''' parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Image 293,62,<nowiki>http://opensimulator.org/skins/osmonobook/images/headerLogo.png</nowiki>;";
</source>

===LineTo===

;LineTo float x, float y;
:Draws a line from the pen's current location to the specified coordinates, using the pen's current color and width.

:After the line is drawn, the specified coordinates become the pen's new current location.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "LineTo 640,480;";
</source>

===MoveTo===

;MoveTo float x, float y;
:Updates the pen's current position to the coordinates provided in the parameters. Nothing is drawn.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "MoveTo 570,23;";
</source>

===PenColour===

;PenColour string NewColor;
:Sets the pen's drawing color to either the specified [http://msdn.microsoft.com/en-us/library/aa358802.aspx named .NET color] or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

:For full opacity, use an alpha value of ff (e.g. <tt>ffff0000</tt> for red); for varying degrees of transparency, reduce the alpha value (e.g. <tt>800000ff</tt> for half-transparent blue).

:The color names and hexadecimal color representations are not case-sensitive.

Example:
<source lang="lsl">
CommandList += "PenColour MidnightBlue;";
CommandList += "PenColour ff191970;";
</source>

===PenSize===

;PenSize float width;
:Sets the pen size to a square of '''width''' pixels by '''width''' pixels. If '''width''' is an odd number, the pen will be exactly centered on the coordinates provided in the various drawing commands; if it is an even number, it will be centered slightly higher and to the left of the actual coordinates.

:Although the parameter accepts a floating-point value, anything following a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "PenSize 5;";
</source>

===Rectangle===

;Rectangle float width, float height;
:Draws an unfilled rectangle, using the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Rectangle 150,75;";
</source>

==Text Drawing Commands==

===FontName===

;FontName string fontname;
:Sets the font used by the '''[[#Text|Text]]''' command. If the specified font is not installed on the system, the default font (Arial or its local equivalent) is used.

:There is no equivalent convenience function; if you wish to change the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontName Times New Roman;";
</source>

===FontProp===

;FontProp string properties;
:Sets the text display properties (Regular, Boldface, Underline, Italic and Strikeout) used by subsequent '''[[#Text|Text]]''' calls. The properties are represented by single letters (R,B,U,I and S, respectively), separated by commas. 'R' is a special case which turns off all other properties, while the others are additive.

:There is no equivalent convenience function; if you wish to change the properties of the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontProp B,I;";
</source>

===FontSize===

;FontSize float size;
:Sets the font size used by subsequent '''[[#Text|Text]]''' commands. The '''size''' parameter represents the font height in points.

:Please note that the font height is given in ''points'', not in ''pixels''. The resulting size of the font in pixels may vary depending on the system settings, specifically the display system's "dots per inch" metric. A system set to 96dpi will produce differently sized text than a system set to 120dpi. If precise text size is required, consider using the [[osGetDrawStringSize]]() function to help calculate the proper FontSize value to use (but bear in mind that [[osGetDrawStringSize]]() takes an integer parameter for the size, whereas FontSize does use floating-point values).

:Unlike the other drawing commands, anything following a decimal point in the '''size''' parameter is significant.

:If a negative FontSize parameter is specified, any text subsequently added will be displayed upside down and to the right of the point of origin.

Example:
:<source lang="lsl">
CommandList += "FontSize 12;";
</source>

===Text===

;Text string text;
:Draws the specified string of text with the current pen color, using the currently defined [[#FontName|font]], [[#FontSize|size]] and [[#FontProp|properties]] (which default to regular 14-point Arial).

:The text will be drawn with the upper left corner of the first glyph at the pen's current position (however, note that glyphs within the font may be defined to extend to the left of their origin point).

:If you need to include a semicolon in the text to be displayed, you will have to change the command delimiter in the <tt>extraParams</tt> parameter to the osSetDynamicTexture* functions. However, this will require that ''all'' commands be terminated with the alternate delimiter, and you cannot use the convenience functions (which are hardcoded to use a semicolon).

:The text may or may not be antialiased, depending on the system settings of the machine upon which the simulator is running. Furthermore, if the system is configured to use LCD subpixel antialiasing (e.g. ClearType), the text may have colored fringes on the smoothed pixels, which may result in a less than optimum image.

:Please note that the pen position is ''not'' updated after this call.

Example:
:<source lang="lsl">
CommandList += "Text Nobody here but us hippos!;";
</source>

OsSetFontSize

2009-07-30T13:09:29Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsSetFontSize | osSetFontSize]]

LSL: '''[[string]] osSetFontSize( [[string]] drawList, [[integer]] fontSize )''' 
C#: '''[[string]] osSetFontSize( [[string]] drawList, [[int]] fontSize )'''

Appends a [[Drawing_commands#FontSize|FontSize]] drawing command to the string provided in '''drawList''' and returns the result.

Sets the size of the font used by subsequent '''[[OsDrawText | osDrawTextText]]'''() calls. The '''fontSize''' parameter represents the font height in points.

Please note that the font height is given in ''points'', not in ''pixels''. The resulting size of the font in pixels may vary depending on the system settings, specifically the display system's "dots per inch" metric. A system set to 96dpi will produce differently sized text than a system set to 120dpi. If precise text size is required, consider using the [[osGetDrawStringSize]]() function to help calculate the proper fontSize value to use.

If a negative '''fontSize''' parameter is specified, any text subsequently added will be displayed upside down and to the right of the point of origin.

Please note that the pen position is ''not'' updated after this call.

Example:
<source lang="lsl">
// Example of osDrawText
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osMovePen( CommandList, 10, 10 ); // Upper left corner at <10,10>
CommandList = osSetFontSize( CommandList, 10 ); // Use 10-point text
CommandList = osDrawText( CommandList, "Ten points!" ); // Place some text
CommandList = osMovePen( CommandList, 10, 27 ); // New text placement
CommandList = osSetFontSize( CommandList, 15 ); // Use 10-point text
CommandList = osDrawText( CommandList, "Fifteen points!" ); // Place some text
CommandList = osMovePen( CommandList, 10, 50 ); // New text placement
CommandList = osSetFontSize( CommandList, 20 ); // Use 10-point text
CommandList = osDrawText( CommandList, "Twenty points!" ); // Place some text

// Now draw the image
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawText

2009-07-30T12:59:59Z

Godfrey: Reword the return value line to be more specific.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawText | osDrawText]]

LSL: '''[[string]] osDrawText( [[string]] drawList, [[string]] text )''' 
C#: '''[[string]] osDrawText( [[string]] drawList, [[string]] text )'''

Appends a [[Drawing_commands#Text|Text]] drawing command to the string provided in '''drawList''' and returns the result.

The specified text will be drawn with the current pen color, using the currently defined [[Drawing_commands#FontName|font]], [[OsSetFontSize|size]] and [[Drawing_commands#FontProp|properties]] (which default to regular 14-point Arial).

The text will be drawn with the upper left corner of the first glyph at the pen's current position (however, note that glyphs within the font may be defined to extend to the left of their origin point).

If you need to include a semicolon in the text to be displayed, you will need to directly manipulate the draw list string using the [[Drawing_commands|drawing commands]] rather than the dynamic texture convenience functions, then specify an alternate data delimiter in the <tt>extraParams</tt> parameter to the <tt>osSetDynamicTexture*</tt> functions. The convenience functions (including '''osDrawImage''') are hardcoded to terminate each command with a semicolon.

The text may or may not be antialiased, depending on the system settings of the machine upon which the simulator is running. Furthermore, if the system is configured to use LCD subpixel antialiasing (e.g. ClearType), the text may have colored fringes on the smoothed pixels, which may result in a less than optimum image.

Please note that the pen position is ''not'' updated after this call.

Example:
<source lang="lsl">
// Example of osDrawText
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osMovePen( CommandList, 10, 10 ); // Upper left corner at <10,10>
CommandList = osDrawText( CommandList, "Hello, World!" ); // Place some text

// Now draw the image
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsSetPenSize

2009-07-30T12:58:25Z

Godfrey: Identify the return value.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsSetPenSize | osSetPenSize]]

LSL: '''[[string]] osSetPenSize( [[string]] drawList, [[integer]] penSize )''' 
C#: '''[[string]] osDrawLine( [[string]] drawList, [[int]] penSize )'''

Appends a [[Drawing_commands#PenSize|PenSize]] drawing command to the string provided in '''drawList''' and returns the result.

This sets the pen size to a square of '''penSize''' pixels by '''penSize''' pixels. If '''penSize''' is an odd number, the pen will be exactly centered on the coordinates provided in the various drawing commands; if it is an even number, it will be centered slightly higher and to the left of the actual coordinates.

Example:
<source lang="lsl">
// Example of osSetPenSize
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenColour( CommandList, "Red" ); // Set the pen color to red

for (i = 1; i < 13; ++i)
{
CommandList = osSetPenSize( CommandList, i ); // Set the pen size
CommandList = osDrawLine( CommandList, 15, i*20, 241, i*20 ); // Draw a horizontal line
}

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsSetPenColour

2009-07-30T12:57:19Z

Godfrey: Identify the return value.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsSetPenColour | osSetPenColour]]

LSL: '''[[string]] osSetPenColour( [[string]] drawList, string colour )''' 
C#: '''[[string]] osMovePen( [[string]] drawList, string colour )'''

Appends a [[Drawing_commands#PenColour|PenColour]] drawing command to the string provided in '''drawList''' and returns the result.

This sets the pen's drawing color to either the specified [http://msdn.microsoft.com/en-us/library/aa358802.aspx named .NET color] or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

For full opacity, use an alpha value of ff (e.g. <tt>ffff0000</tt> for red); for varying degrees of transparency, reduce the alpha value (e.g. <tt>800000ff</tt> for half-transparent blue).

The color names and hexadecimal color representations are not case-sensitive.

Example:
<source lang="lsl">
// Example of osSetPenColour

string hexDigits = "0123456789abcdef";
list colorNames = [ "AliceBlue", "AntiqueWhite", "Aqua", "Aquamarine", "Azure", "Beige", "Bisque",
"Black", "BlanchedAlmond", "Blue", "BlueViolet", "Brown", "BurlyWood",
"CadetBlue", "Chartreuse", "Chocolate", "Coral", "CornflowerBlue", "Cornsilk",
"Crimson", "Cyan", "DarkBlue", "DarkCyan", "DarkGoldenrod", "DarkGrey",
"DarkGreen", "DarkKhaki", "DarkMagenta", "DarkOliveGreen", "DarkOrange",
"DarkOrchid", "DarkRed", "DarkSalmon", "DarkSeaGreen", "DarkSlateBlue",
"DarkSlateGrey", "DarkTurquoise", "DarkViolet", "DeepPink", "DeepSkyBlue",
"DimGrey", "DodgerBlue", "FireBrick", "FloralWhite", "ForestGreen", "Fuchsia",
"Gainsboro", "GhostWhite", "Gold", "Goldenrod", "Grey", "Green", "GreenYellow",
"Honeydew", "HotPink", "IndianRed", "Indigo", "Ivory", "Khaki", "Lavender",
"LavenderBlush", "LawnGreen", "LemonChiffon", "LightBlue", "LightCoral",
"LightCyan", "LightGoldenrodYellow", "LightGreen", "LightGrey", "LightPink",
"LightSalmon", "LightSeaGreen", "LightSkyBlue", "LightSlateGrey",
"LightSteelBlue", "LightYellow", "Lime", "LimeGreen", "Linen", "Magenta",
"Maroon", "MediumAquamarine", "MediumBlue", "MediumOrchid", "MediumPurple",
"MediumSeaGreen", "MediumSlateBlue", "MediumSpringGreen", "MediumTurquoise",
"MediumVioletRed", "MidnightBlue", "MintCream", "MistyRose", "Moccasin",
"NavajoWhite", "Navy", "OldLace", "Olive", "OliveDrab", "Orange", "OrangeRed",
"Orchid", "PaleGoldenrod", "PaleGreen", "PaleTurquoise", "PaleVioletRed",
"PapayaWhip", "PeachPuff", "Peru", "Pink", "Plum", "PowderBlue", "Purple",
"Red", "RosyBrown", "RoyalBlue", "SaddleBrown", "Salmon", "SandyBrown",
"SeaGreen", "Seashell", "Sienna", "Silver", "SkyBlue", "SlateBlue", "SlateGrey",
"Snow", "SpringGreen", "SteelBlue", "Tan", "Teal", "Thistle", "Tomato",
"Turquoise", "Violet", "Wheat", "White", "WhiteSmoke", "Yellow", "YellowGreen" ];

default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenSize( CommandList, 1 ); // Set the pen width to 1 pixel

for (i = 0; i < 140; ++i) // draw each named color as a single horizontal line
{
// Set the pen to the next color name in our list
CommandList = osSetPenColour( CommandList, llList2String( colorNames, i ));
// Now draw a line in that color
CommandList = osDrawLine( CommandList, 0, i, 255, i );
}

// Now let's fill up the remainder with lines of random colors, leaving a gap of 20 lines.
for (i = 161; i < 256; ++i)
{
string thisColor = "ff"; // give it an opaque alpha
integer j;
for (j = 0; j < 6; ++j) // then choose six random hex digits for the color
{
integer k = (integer) llFrand( 16.0 );
thisColor += llGetSubString( hexDigits, k, k );
}
CommandList = osSetPenColour( CommandList, thisColor );
CommandList = osDrawLine( CommandList, 0, i, 255, i );
}
// Now generate the texture and apply it to the prim
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsMovePen

2009-07-30T12:55:59Z

Godfrey: Identify the return value.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsMovePen | osMovePen]]

LSL: '''[[string]] osMovePen( [[string]] drawList, [[integer]] x, [[integer]] y )''' 
C#: '''[[string]] osMovePen( [[string]] drawList, [[int]] x, [[int]] y )'''

Appends a [[Drawing_commands#MoveTo|MoveTo]] drawing command to the string provided in '''drawList''' and returns the result.

This moves the pen's location to the coordinates specified by the '''x''' and '''y''' parameters, without drawing anything.

Example:
<source lang="lsl">
// Example of osMovePen
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue

for (i = 0; i < 256; i += 20)
{
CommandList = osMovePen( CommandList, 255, i ); // Move to the right side
CommandList = osDrawLine( CommandList, 0, i+20 ); // Draw left and slightly down
}

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawText

2009-07-30T12:53:27Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawText | osDrawText]]

LSL: '''[[string]] osDrawText( [[string]] drawList, [[string]] text )''' 
C#: '''[[string]] osDrawText( [[string]] drawList, [[string]] text )'''

Returns the [[Drawing_commands | drawing commands]] to draw the specified text on the dynamic texture, appended to the string provided in '''drawList'''.

The specified text will be drawn with the current pen color, using the currently defined [[Drawing_commands#FontName|font]], [[OsSetFontSize|size]] and [[Drawing_commands#FontProp|properties]] (which default to regular 14-point Arial).

The text will be drawn with the upper left corner of the first glyph at the pen's current position (however, note that glyphs within the font may be defined to extend to the left of their origin point).

If you need to include a semicolon in the text to be displayed, you will need to directly manipulate the draw list string using the [[Drawing_commands|drawing commands]] rather than the dynamic texture convenience functions, then specify an alternate data delimiter in the <tt>extraParams</tt> parameter to the <tt>osSetDynamicTexture*</tt> functions. The convenience functions (including '''osDrawImage''') are hardcoded to terminate each command with a semicolon.

The text may or may not be antialiased, depending on the system settings of the machine upon which the simulator is running. Furthermore, if the system is configured to use LCD subpixel antialiasing (e.g. ClearType), the text may have colored fringes on the smoothed pixels, which may result in a less than optimum image.

Please note that the pen position is ''not'' updated after this call.

Example:
<source lang="lsl">
// Example of osDrawText
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osMovePen( CommandList, 10, 10 ); // Upper left corner at <10,10>
CommandList = osDrawText( CommandList, "Hello, World!" ); // Place some text

// Now draw the image
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsSetPenSize

2009-07-28T00:21:20Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsSetPenSize | osSetPenSize]]

LSL: '''[[string]] osSetPenSize( [[string]] drawList, [[integer]] penSize )''' 
C#: '''[[string]] osDrawLine( [[string]] drawList, [[int]] penSize )'''

Sets the pen size to a square of '''penSize''' pixels by '''penSize''' pixels. If '''penSize''' is an odd number, the pen will be exactly centered on the coordinates provided in the various drawing commands; if it is an even number, it will be centered slightly higher and to the left of the actual coordinates.

Example:
<source lang="lsl">
// Example of osSetPenSize
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenColour( CommandList, "Red" ); // Set the pen color to red

for (i = 1; i < 13; ++i)
{
CommandList = osSetPenSize( CommandList, i ); // Set the pen size
CommandList = osDrawLine( CommandList, 15, i*20, 241, i*20 ); // Draw a horizontal line
}

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsSetPenColour

2009-07-28T00:19:53Z

Godfrey: Copypasta error

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsSetPenColour | osSetPenColour]]

LSL: '''[[string]] osSetPenColour( [[string]] drawList, string colour )''' 
C#: '''[[string]] osMovePen( [[string]] drawList, string colour )'''

Sets the pen's drawing color to either the specified [http://msdn.microsoft.com/en-us/library/aa358802.aspx named .NET color] or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

For full opacity, use an alpha value of ff (e.g. <tt>ffff0000</tt> for red); for varying degrees of transparency, reduce the alpha value (e.g. <tt>800000ff</tt> for half-transparent blue).

The color names and hexadecimal color representations are not case-sensitive.

Example:
<source lang="lsl">
// Example of osSetPenColour

string hexDigits = "0123456789abcdef";
list colorNames = [ "AliceBlue", "AntiqueWhite", "Aqua", "Aquamarine", "Azure", "Beige", "Bisque",
"Black", "BlanchedAlmond", "Blue", "BlueViolet", "Brown", "BurlyWood",
"CadetBlue", "Chartreuse", "Chocolate", "Coral", "CornflowerBlue", "Cornsilk",
"Crimson", "Cyan", "DarkBlue", "DarkCyan", "DarkGoldenrod", "DarkGrey",
"DarkGreen", "DarkKhaki", "DarkMagenta", "DarkOliveGreen", "DarkOrange",
"DarkOrchid", "DarkRed", "DarkSalmon", "DarkSeaGreen", "DarkSlateBlue",
"DarkSlateGrey", "DarkTurquoise", "DarkViolet", "DeepPink", "DeepSkyBlue",
"DimGrey", "DodgerBlue", "FireBrick", "FloralWhite", "ForestGreen", "Fuchsia",
"Gainsboro", "GhostWhite", "Gold", "Goldenrod", "Grey", "Green", "GreenYellow",
"Honeydew", "HotPink", "IndianRed", "Indigo", "Ivory", "Khaki", "Lavender",
"LavenderBlush", "LawnGreen", "LemonChiffon", "LightBlue", "LightCoral",
"LightCyan", "LightGoldenrodYellow", "LightGreen", "LightGrey", "LightPink",
"LightSalmon", "LightSeaGreen", "LightSkyBlue", "LightSlateGrey",
"LightSteelBlue", "LightYellow", "Lime", "LimeGreen", "Linen", "Magenta",
"Maroon", "MediumAquamarine", "MediumBlue", "MediumOrchid", "MediumPurple",
"MediumSeaGreen", "MediumSlateBlue", "MediumSpringGreen", "MediumTurquoise",
"MediumVioletRed", "MidnightBlue", "MintCream", "MistyRose", "Moccasin",
"NavajoWhite", "Navy", "OldLace", "Olive", "OliveDrab", "Orange", "OrangeRed",
"Orchid", "PaleGoldenrod", "PaleGreen", "PaleTurquoise", "PaleVioletRed",
"PapayaWhip", "PeachPuff", "Peru", "Pink", "Plum", "PowderBlue", "Purple",
"Red", "RosyBrown", "RoyalBlue", "SaddleBrown", "Salmon", "SandyBrown",
"SeaGreen", "Seashell", "Sienna", "Silver", "SkyBlue", "SlateBlue", "SlateGrey",
"Snow", "SpringGreen", "SteelBlue", "Tan", "Teal", "Thistle", "Tomato",
"Turquoise", "Violet", "Wheat", "White", "WhiteSmoke", "Yellow", "YellowGreen" ];

default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenSize( CommandList, 1 ); // Set the pen width to 1 pixel

for (i = 0; i < 140; ++i) // draw each named color as a single horizontal line
{
// Set the pen to the next color name in our list
CommandList = osSetPenColour( CommandList, llList2String( colorNames, i ));
// Now draw a line in that color
CommandList = osDrawLine( CommandList, 0, i, 255, i );
}

// Now let's fill up the remainder with lines of random colors, leaving a gap of 20 lines.
for (i = 161; i < 256; ++i)
{
string thisColor = "ff"; // give it an opaque alpha
integer j;
for (j = 0; j < 6; ++j) // then choose six random hex digits for the color
{
integer k = (integer) llFrand( 16.0 );
thisColor += llGetSubString( hexDigits, k, k );
}
CommandList = osSetPenColour( CommandList, thisColor );
CommandList = osDrawLine( CommandList, 0, i, 255, i );
}
// Now generate the texture and apply it to the prim
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsMovePen

2009-07-28T00:19:39Z

Godfrey: Copypasta error

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsMovePen | osMovePen]]

LSL: '''[[string]] osMovePen( [[string]] drawList, [[integer]] x, [[integer]] y )''' 
C#: '''[[string]] osMovePen( [[string]] drawList, [[int]] x, [[int]] y )'''

Moves the pen's location to the coordinates specified by the '''x''' and '''y''' parameters, without drawing anything.

Example:
<source lang="lsl">
// Example of osMovePen
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue

for (i = 0; i < 256; i += 20)
{
CommandList = osMovePen( CommandList, 255, i ); // Move to the right side
CommandList = osDrawLine( CommandList, 0, i+20 ); // Draw left and slightly down
}

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawLine

2009-07-28T00:18:38Z

Godfrey: Copypasta error

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawLine | osDrawLine]]

LSL: '''[[string]] osDrawLine( [[string]] drawList, [[integer]] startX, [[integer]] startY, [[integer]] endX, [[integer]] endY )''' 
:'''[[string]] osDrawLine( [[string]] drawList, [[integer]] endX, [[integer]] endY )'''
C#: '''[[string]] osDrawLine( [[string]] drawList, [[int]] startX, [[int]] startY, [[int]] endX, [[int]] endY )''' 
:'''[[string]] osDrawLine( [[string]] drawList, [[int]] endX, [[int]] endY )'''

Depending on the form, appends a [[Drawing_commands#LineTo|LineTo]] drawing command, or [[Drawing_commands#MoveTo|MoveTo]] and [[Drawing_commands#LineTo|LineTo]] commands, to the string provided in '''drawList''' and returns the result.

In the longer form, draws a line using the current pen size and color from to the coordinates indicated by '''startX''' and '''startY''' to the coordinates indicated by '''endX''' and '''endY'''.

In the shorter form, draws a line using the current pen size and color from the pen's current position to the coordinates indicated by '''endX''' and '''endY'''.

After the line is drawn, the pen's X and Y coordinates are set to '''endX''' and '''endY''', respectively.

Example:
<source lang="lsl">
// Example of osDrawLine
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Red" ); // Set the pen color to red
CommandList = osDrawLine( CommandList, 10, 10, 128, 246 ); // Draw the first line (long form)
CommandList = osSetPenColour( CommandList, "Green" ); // Set the pen color to green
CommandList = osDrawLine( CommandList, 246, 10); // Draw the second line (short form)

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsSetPenColour

2009-07-28T00:10:38Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsSetPenColour | osSetPenColour]]

LSL: '''[[string]] osSetPenColour( [[string]] drawList, string colour )''' 
LSL: '''[[string]] osMovePen( [[string]] drawList, string colour )'''

Sets the pen's drawing color to either the specified [http://msdn.microsoft.com/en-us/library/aa358802.aspx named .NET color] or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

For full opacity, use an alpha value of ff (e.g. <tt>ffff0000</tt> for red); for varying degrees of transparency, reduce the alpha value (e.g. <tt>800000ff</tt> for half-transparent blue).

The color names and hexadecimal color representations are not case-sensitive.

Example:
<source lang="lsl">
// Example of osSetPenColour

string hexDigits = "0123456789abcdef";
list colorNames = [ "AliceBlue", "AntiqueWhite", "Aqua", "Aquamarine", "Azure", "Beige", "Bisque",
"Black", "BlanchedAlmond", "Blue", "BlueViolet", "Brown", "BurlyWood",
"CadetBlue", "Chartreuse", "Chocolate", "Coral", "CornflowerBlue", "Cornsilk",
"Crimson", "Cyan", "DarkBlue", "DarkCyan", "DarkGoldenrod", "DarkGrey",
"DarkGreen", "DarkKhaki", "DarkMagenta", "DarkOliveGreen", "DarkOrange",
"DarkOrchid", "DarkRed", "DarkSalmon", "DarkSeaGreen", "DarkSlateBlue",
"DarkSlateGrey", "DarkTurquoise", "DarkViolet", "DeepPink", "DeepSkyBlue",
"DimGrey", "DodgerBlue", "FireBrick", "FloralWhite", "ForestGreen", "Fuchsia",
"Gainsboro", "GhostWhite", "Gold", "Goldenrod", "Grey", "Green", "GreenYellow",
"Honeydew", "HotPink", "IndianRed", "Indigo", "Ivory", "Khaki", "Lavender",
"LavenderBlush", "LawnGreen", "LemonChiffon", "LightBlue", "LightCoral",
"LightCyan", "LightGoldenrodYellow", "LightGreen", "LightGrey", "LightPink",
"LightSalmon", "LightSeaGreen", "LightSkyBlue", "LightSlateGrey",
"LightSteelBlue", "LightYellow", "Lime", "LimeGreen", "Linen", "Magenta",
"Maroon", "MediumAquamarine", "MediumBlue", "MediumOrchid", "MediumPurple",
"MediumSeaGreen", "MediumSlateBlue", "MediumSpringGreen", "MediumTurquoise",
"MediumVioletRed", "MidnightBlue", "MintCream", "MistyRose", "Moccasin",
"NavajoWhite", "Navy", "OldLace", "Olive", "OliveDrab", "Orange", "OrangeRed",
"Orchid", "PaleGoldenrod", "PaleGreen", "PaleTurquoise", "PaleVioletRed",
"PapayaWhip", "PeachPuff", "Peru", "Pink", "Plum", "PowderBlue", "Purple",
"Red", "RosyBrown", "RoyalBlue", "SaddleBrown", "Salmon", "SandyBrown",
"SeaGreen", "Seashell", "Sienna", "Silver", "SkyBlue", "SlateBlue", "SlateGrey",
"Snow", "SpringGreen", "SteelBlue", "Tan", "Teal", "Thistle", "Tomato",
"Turquoise", "Violet", "Wheat", "White", "WhiteSmoke", "Yellow", "YellowGreen" ];

default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenSize( CommandList, 1 ); // Set the pen width to 1 pixel

for (i = 0; i < 140; ++i) // draw each named color as a single horizontal line
{
// Set the pen to the next color name in our list
CommandList = osSetPenColour( CommandList, llList2String( colorNames, i ));
// Now draw a line in that color
CommandList = osDrawLine( CommandList, 0, i, 255, i );
}

// Now let's fill up the remainder with lines of random colors, leaving a gap of 20 lines.
for (i = 161; i < 256; ++i)
{
string thisColor = "ff"; // give it an opaque alpha
integer j;
for (j = 0; j < 6; ++j) // then choose six random hex digits for the color
{
integer k = (integer) llFrand( 16.0 );
thisColor += llGetSubString( hexDigits, k, k );
}
CommandList = osSetPenColour( CommandList, thisColor );
CommandList = osDrawLine( CommandList, 0, i, 255, i );
}
// Now generate the texture and apply it to the prim
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsMovePen

2009-07-27T23:37:10Z

Godfrey: Correct formatting error

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsMovePen | osMovePen]]

LSL: '''[[string]] osMovePen( [[string]] drawList, [[integer]] x, [[integer]] y )''' 
LSL: '''[[string]] osMovePen( [[string]] drawList, [[int]] x, [[int]] y )'''

Moves the pen's location to the coordinates specified by the '''x''' and '''y''' parameters, without drawing anything.

Example:
<source lang="lsl">
// Example of osMovePen
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue

for (i = 0; i < 256; i += 20)
{
CommandList = osMovePen( CommandList, 255, i ); // Move to the right side
CommandList = osDrawLine( CommandList, 0, i+20 ); // Draw left and slightly down
}

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsMovePen

2009-07-27T23:35:11Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsMovePen | osMovePen]]

LSL: '''[[string]] osMovePen( [[string]] drawList, [[integer]] x, [[integer]] y )'''
LSL: '''[[string]] osMovePen( [[string]] drawList, [[int]] x, [[int]] y )'''

Moves the pen's location to the coordinates specified by the '''x''' and '''y''' parameters, without drawing anything.

Example:
<source lang="lsl">
// Example of osMovePen
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
integer i;

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue

for (i = 0; i < 256; i += 20)
{
CommandList = osMovePen( CommandList, 255, i ); // Move to the right side
CommandList = osDrawLine( CommandList, 0, i+20 ); // Draw left and slightly down
}

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawRectangle

2009-07-27T23:32:11Z

Godfrey: Oops.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawRectangle | osDrawRectangle]]

LSL: '''[[string]] osDrawRectangle( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawRectangle( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends a [[Drawing_commands#Rectangle|Rectangle]] drawing command to the string provided in '''drawList''' and returns the result.

The outline of a rectangle is drawn with the current pen size and color, at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively (that is, the pen is positioned at the lower right corner of the rectangle.

Example:
<source lang="lsl">
// Example of osDrawRectangle
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Green" ); // Set the pen color to green
CommandList = osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList = osDrawRectangle( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the rectangle
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawLine

2009-07-27T23:31:53Z

Godfrey: Oops.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawLine | osDrawLine]]

LSL: '''[[string]] osDrawLine( [[string]] drawList, [[integer]] startX, [[integer]] startY, [[integer]] endX, [[integer]] endY )''' 
:'''[[string]] osDrawLine( [[string]] drawList, [[integer]] endX, [[integer]] endY )'''
LSL: '''[[string]] osDrawLine( [[string]] drawList, [[int]] startX, [[int]] startY, [[int]] endX, [[int]] endY )''' 
:'''[[string]] osDrawLine( [[string]] drawList, [[int]] endX, [[int]] endY )'''

Depending on the form, appends a [[Drawing_commands#LineTo|LineTo]] drawing command, or [[Drawing_commands#MoveTo|MoveTo]] and [[Drawing_commands#LineTo|LineTo]] commands, to the string provided in '''drawList''' and returns the result.

In the longer form, draws a line using the current pen size and color from to the coordinates indicated by '''startX''' and '''startY''' to the coordinates indicated by '''endX''' and '''endY'''.

In the shorter form, draws a line using the current pen size and color from the pen's current position to the coordinates indicated by '''endX''' and '''endY'''.

After the line is drawn, the pen's X and Y coordinates are set to '''endX''' and '''endY''', respectively.

Example:
<source lang="lsl">
// Example of osDrawLine
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Red" ); // Set the pen color to red
CommandList = osDrawLine( CommandList, 10, 10, 128, 246 ); // Draw the first line (long form)
CommandList = osSetPenColour( CommandList, "Green" ); // Set the pen color to green
CommandList = osDrawLine( CommandList, 246, 10); // Draw the second line (short form)

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawImage

2009-07-27T23:31:33Z

Godfrey: Oops.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawImage | osDrawImage]]

LSL: '''[[string]] osDrawImage( [[string]] drawList, [[integer]] width, [[integer]] height, [[string]] imageUrl )''' 
C#: '''[[string]] osDrawImage( [[string]] drawList, [[int]] width, [[int]] height, [[string]] imageUrl )'''

Appends an [[Drawing_commands#Image|Image]] drawing command to the string provided in '''drawList''' and returns the result.

Retrieves an image specified by the imageUrl parameter and draws it at the specified height and width, with the upper left corner of the image placed at the pen's current position. After the image is drawn, the width and height values are added to the pen's X and Y position, respectively (that is, the pen's current position is set to the lower right corner of the image).

If imageUrl points to an invalid location, an image type not supported by libgdi, or a non-image MIME type, nothing is drawn. If either or both of the '''width''' or '''height''' parameters are zero or negative, nothing is drawn, but the image is still retrieved.

Example:
<source lang="lsl">
// Example of osDrawImage
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
string ImageURL = "http://opensimulator.org/skins/osmonobook/images/headerLogo.png";
CommandList = osMovePen( CommandList, 0, 0 ); // Upper left corner at <0,0>
CommandList = osDrawImage( CommandList, 256, 54, ImageURL ); // 200 pixels by 100 pixels

// Now draw the image
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawFilledRectangle

2009-07-27T23:31:15Z

Godfrey: Oops.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawFilledRectangle | osDrawFilledRectangle]]

LSL: '''[[string]] osDrawFilledRectangle( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawFilledRectangle( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends a [[Drawing_commands#FillRectangle|FillRectangle]] drawing command to the string provided in '''drawList''' and returns the result.

The filled rectangle is drawn with the current pen size and color, at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively (that is, the pen is positioned at the lower right corner of the rectangle.

Example:
<source lang="lsl">
// Example of osDrawFilledRectangle
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Red" ); // Set the pen color to red
CommandList = osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList = osDrawFilledRectangle( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the rectangle
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawEllipse

2009-07-27T23:30:53Z

Godfrey: Oops.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawEllipse | osDrawEllipse]]

LSL: '''[[string]] osDrawEllipse( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawEllipse( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends an [[Drawing_commands#Ellipse|Ellipse]] drawing command to the string provided in '''drawList''' and returns the result.

The ellipse is drawn with the current pen size and color, with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

Example:
<source lang="lsl">
// Example of osDrawEllipse
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList = osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList = osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue
CommandList = osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList = osDrawEllipse( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the ellipse
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawLine

2009-07-27T23:23:13Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawLine | osDrawLine]]

LSL: '''[[string]] osDrawLine( [[string]] drawList, [[integer]] startX, [[integer]] startY, [[integer]] endX, [[integer]] endY )''' 
:'''[[string]] osDrawLine( [[string]] drawList, [[integer]] endX, [[integer]] endY )'''
LSL: '''[[string]] osDrawLine( [[string]] drawList, [[int]] startX, [[int]] startY, [[int]] endX, [[int]] endY )''' 
:'''[[string]] osDrawLine( [[string]] drawList, [[int]] endX, [[int]] endY )'''

Depending on the form, appends a [[Drawing_commands#LineTo|LineTo]] drawing command, or [[Drawing_commands#MoveTo|MoveTo]] and [[Drawing_commands#LineTo|LineTo]] commands, to the string provided in '''drawList''' and returns the result.

In the longer form, draws a line using the current pen size and color from to the coordinates indicated by '''startX''' and '''startY''' to the coordinates indicated by '''endX''' and '''endY'''.

In the shorter form, draws a line using the current pen size and color from the pen's current position to the coordinates indicated by '''endX''' and '''endY'''.

After the line is drawn, the pen's X and Y coordinates are set to '''endX''' and '''endY''', respectively.

Example:
<source lang="lsl">
// Example of osDrawLine
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList += osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList += osSetPenColour( CommandList, "Red" ); // Set the pen color to red
CommandList += osDrawLine( CommandList, 10, 10, 128, 246 ); // Draw the first line (long form)
CommandList += osSetPenColour( CommandList, "Green" ); // Set the pen color to green
CommandList += osDrawLine( CommandList, 246, 10); // Draw the second line (short form)

// Now draw the lines
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawImage

2009-07-27T23:07:40Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawImage | osDrawImage]]

LSL: '''[[string]] osDrawImage( [[string]] drawList, [[integer]] width, [[integer]] height, [[string]] imageUrl )''' 
C#: '''[[string]] osDrawImage( [[string]] drawList, [[int]] width, [[int]] height, [[string]] imageUrl )'''

Appends an [[Drawing_commands#Image|Image]] drawing command to the string provided in '''drawList''' and returns the result.

Retrieves an image specified by the imageUrl parameter and draws it at the specified height and width, with the upper left corner of the image placed at the pen's current position. After the image is drawn, the width and height values are added to the pen's X and Y position, respectively (that is, the pen's current position is set to the lower right corner of the image).

If imageUrl points to an invalid location, an image type not supported by libgdi, or a non-image MIME type, nothing is drawn. If either or both of the '''width''' or '''height''' parameters are zero or negative, nothing is drawn, but the image is still retrieved.

Example:
<source lang="lsl">
// Example of osDrawImage
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands
string ImageURL = "http://opensimulator.org/skins/osmonobook/images/headerLogo.png";
CommandList += osMovePen( CommandList, 0, 0 ); // Upper left corner at <0,0>
CommandList += osDrawImage( CommandList, 256, 54, ImageURL ); // 200 pixels by 100 pixels

// Now draw the image
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawRectangle

2009-07-27T22:58:40Z

Godfrey: Fixed a link

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawRectangle | osDrawRectangle]]

LSL: '''[[string]] osDrawRectangle( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawRectangle( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends a [[Drawing_commands#Rectangle|Rectangle]] drawing command to the string provided in '''drawList''' and returns the result.

The outline of a rectangle is drawn with the current pen size and color, at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively (that is, the pen is positioned at the lower right corner of the rectangle.

Example:
<source lang="lsl">
// Example of osDrawRectangle
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList += osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList += osSetPenColour( CommandList, "Green" ); // Set the pen color to green
CommandList += osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList += osDrawRectangle( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the rectangle
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawRectangle

2009-07-27T22:57:21Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawFilledRectangle | osDrawRectangle]]

LSL: '''[[string]] osDrawRectangle( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawRectangle( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends a [[Drawing_commands#Rectangle|Rectangle]] drawing command to the string provided in '''drawList''' and returns the result.

The outline of a rectangle is drawn with the current pen size and color, at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively (that is, the pen is positioned at the lower right corner of the rectangle.

Example:
<source lang="lsl">
// Example of osDrawRectangle
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList += osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList += osSetPenColour( CommandList, "Green" ); // Set the pen color to green
CommandList += osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList += osDrawRectangle( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the rectangle
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawFilledRectangle

2009-07-27T22:54:25Z

Godfrey: Page created.

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawFilledRectangle | osDrawFilledRectangle]]

LSL: '''[[string]] osDrawFilledRectangle( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawFilledRectangle( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends a [[Drawing_commands#FillRectangle|FillRectangle]] drawing command to the string provided in '''drawList''' and returns the result.

The filled rectangle is drawn with the current pen size and color, at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively (that is, the pen is positioned at the lower right corner of the rectangle.

Example:
<source lang="lsl">
// Example of osDrawFilledRectangle
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList += osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList += osSetPenColour( CommandList, "Red" ); // Set the pen color to red
CommandList += osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList += osDrawFilledRectangle( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the rectangle
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawEllipse

2009-07-27T22:48:52Z

Godfrey: Added hierarchical navigation links

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[OsDrawEllipse | osDrawEllipse]]

LSL: '''[[string]] osDrawEllipse( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawEllipse( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends an [[Drawing_commands#Ellipse|Ellipse]] drawing command to the string provided in '''drawList''' and returns the result.

The ellipse is drawn with the current pen size and color, with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

Example:
<source lang="lsl">
// Example of osDrawEllipse
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList += osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList += osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue
CommandList += osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList += osDrawEllipse( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the ellipse
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

Drawing commands

2009-07-27T22:47:43Z

Godfrey: Fixed spacing

{{Template:Quicklinks}}
[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[Drawing commands]]

The drawing commands are strings of text which are concatenated to create a larger string of graphical instructions, which is then passed as a parameter to the [[Dynamic textures|dynamic texture]] drawing functions. With two exceptions, there are convenience functions, such as [[osDrawRectangle]](), provided to assist in building the command list. It is slightly more efficient to directly manipulate the string containing the drawing commands, as it avoids the overhead of multiple function calls (albeit with an arguable loss of readability).

In general, the drawing commands consist of a case-sensitive token which identifies the command, followed by one or more comma-delimited parameters, and terminating in a separator character (a semicolon by default). Whitespace surrounding the commas and/or separator is permitted.

In the examples which follow, it is assumed that ''CommandList'' is a string variable which has already been defined within the script source code.

==Graphics Primitive Drawing Commands==

===Ellipse===

;Ellipse float width, float height;
:Draws an ellipse with the current pen size and color.

:The ellipse is drawn with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Ellipse 100,100;";
</source>

===FillRectangle===

;FillRectangle float width, float height;
:Draws a rectangle, bordered and filled with the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "FillRectangle 150,75;";
</source>

===Image===

;Image float height, float width, string URL;
:Retrieves an image specified by the URL parameter and draws it at the specified height and width, with the upper left corner of the image placed at the pen's current position. After the image is drawn, the width and height values are added to the pen's X and Y position, respectively.

:If the URL points to an invalid location, an image type not supported by libgdi, or a non-image MIME type, nothing is drawn. If either or both of the '''width''' or '''height''' parameters are zero or negative, nothing is drawn, but the image is still retrieved.

:Although the '''width''' and '''height''' parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Image 293,62,<nowiki>http://opensimulator.org/skins/osmonobook/images/headerLogo.png</nowiki>;";
</source>

===LineTo===

;LineTo float x, float y;
:Draws a line from the pen's current location to the specified coordinates, using the pen's current color and width.

:After the line is drawn, the specified coordinates become the pen's new current location.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "LineTo 640,480;";
</source>

===MoveTo===

;MoveTo float x, float y;
:Updates the pen's current position to the coordinates provided in the parameters. Nothing is drawn.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "MoveTo 570,23;";
</source>

===PenColour===

;PenColour string NewColor;
:Sets the pen's drawing color to either the specified [http://msdn.microsoft.com/en-us/library/aa358802.aspx named .NET color] or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

:For full opacity, use an alpha value of ff (e.g. <tt>ffff0000</tt> for red); for varying degrees of transparency, reduce the alpha value (e.g. <tt>800000ff</tt> for half-transparent blue).

:The color names and hexadecimal color representations are not case-sensitive.

Example:
<source lang="lsl">
CommandList += "PenColour MidnightBlue;";
CommandList += "PenColour ff191970;";
</source>

===PenSize===

;PenSize float width;
:Sets the pen size to a square of '''width''' pixels by '''width''' pixels. If '''width''' is an odd number, the pen will be exactly centered on the coordinates provided in the various drawing commands; if it is an even number, it will be centered slightly higher and to the left of the actual coordinates.

:Although the parameter accepts a floating-point value, anything following a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "PenSize 5;";
</source>

===Rectangle===

;Rectangle float width, float height;
:Draws an unfilled rectangle, using the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Rectangle 150,75;";
</source>

==Text Drawing Commands==

===FontName===

;FontName string fontname;
:Sets the font used by the '''[[#Text|Text]]''' command. If the specified font is not installed on the system, the default font (Arial or its local equivalent) is used.

:There is no equivalent convenience function; if you wish to change the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontName Times New Roman;";
</source>

===FontProp===

;FontProp string properties;
:Sets the text display properties (Regular, Boldface, Underline, Italic and Strikeout) used by subsequent '''[[#Text|Text]]''' calls. The properties are represented by single letters (R,B,U,I and S, respectively), separated by commas. 'R' is a special case which turns off all other properties, while the others are additive.

:There is no equivalent convenience function; if you wish to change the properties of the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontProp B,I;";
</source>

===FontSize===

;FontSize float size;
:Sets the font size used by subsequent '''[[#Text|Text]]''' calls. The '''size''' parameter represents the font height in points.

:Please note that the font height is given in ''points'', not in ''pixels''. The resulting size of the font in pixels may vary depending on the system settings, specifically the display system's "dots per inch" metric. A system set to 96dpi will produce differently sized text than a system set to 120dpi. If precise text size is required, consider using the [[osGetDrawStringSize]]() function to help calculate the proper FontSize value to use (but bear in mind that [[osGetDrawStringSize]]() takes an integer parameter for the size, whereas FontSize does use floating-point values).

:Unlike the other drawing commands, anything following a decimal point in the '''size''' parameter is significant.

:If a negative FontSize parameter is specified, any text subsequently added will be displayed upside down and to the right of the point of origin.

Example:
:<source lang="lsl">
CommandList += "FontSize 12;";
</source>

===Text===

;Text string text;
:Draws the specified string of text with the current pen color, using the currently defined [[#FontName|font]], [[#FontSize|size]] and [[#FontProp|properties]] (which default to regular 14-point Arial).

:The text will be drawn with the upper left corner of the first glyph at the pen's current position (however, note that glyphs within the font may be defined to extend to the left of their origin point).

:If you need to include a semicolon in the text to be displayed, you will have to change the command delimiter in the <tt>extraParams</tt> parameter to the osSetDynamicTexture* functions. However, this will require that ''all'' commands be terminated with the alternate delimiter, and you cannot use the convenience functions (which are hardcoded to use a semicolon).

:The text may or may not be antialiased, depending on the system settings of the machine upon which the simulator is running. Furthermore, if the system is configured to use LCD subpixel antialiasing (e.g. ClearType), the text may have colored fringes on the smoothed pixels, which may result in a less than optimum image.

:Please note that the pen position is ''not'' updated after this call.

Example:
:<source lang="lsl">
CommandList += "Text Nobody here but us hippos!;";
</source>

Drawing commands

2009-07-27T22:47:10Z

Godfrey: Added hierarchical navigation links

{{Template:Quicklinks}}

[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]] -> [[Drawing commands]]

The drawing commands are strings of text which are concatenated to create a larger string of graphical instructions, which is then passed as a parameter to the [[Dynamic textures|dynamic texture]] drawing functions. With two exceptions, there are convenience functions, such as [[osDrawRectangle]](), provided to assist in building the command list. It is slightly more efficient to directly manipulate the string containing the drawing commands, as it avoids the overhead of multiple function calls (albeit with an arguable loss of readability).

In general, the drawing commands consist of a case-sensitive token which identifies the command, followed by one or more comma-delimited parameters, and terminating in a separator character (a semicolon by default). Whitespace surrounding the commas and/or separator is permitted.

In the examples which follow, it is assumed that ''CommandList'' is a string variable which has already been defined within the script source code.

==Graphics Primitive Drawing Commands==

===Ellipse===

;Ellipse float width, float height;
:Draws an ellipse with the current pen size and color.

:The ellipse is drawn with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Ellipse 100,100;";
</source>

===FillRectangle===

;FillRectangle float width, float height;
:Draws a rectangle, bordered and filled with the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "FillRectangle 150,75;";
</source>

===Image===

;Image float height, float width, string URL;
:Retrieves an image specified by the URL parameter and draws it at the specified height and width, with the upper left corner of the image placed at the pen's current position. After the image is drawn, the width and height values are added to the pen's X and Y position, respectively.

:If the URL points to an invalid location, an image type not supported by libgdi, or a non-image MIME type, nothing is drawn. If either or both of the '''width''' or '''height''' parameters are zero or negative, nothing is drawn, but the image is still retrieved.

:Although the '''width''' and '''height''' parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Image 293,62,<nowiki>http://opensimulator.org/skins/osmonobook/images/headerLogo.png</nowiki>;";
</source>

===LineTo===

;LineTo float x, float y;
:Draws a line from the pen's current location to the specified coordinates, using the pen's current color and width.

:After the line is drawn, the specified coordinates become the pen's new current location.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "LineTo 640,480;";
</source>

===MoveTo===

;MoveTo float x, float y;
:Updates the pen's current position to the coordinates provided in the parameters. Nothing is drawn.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "MoveTo 570,23;";
</source>

===PenColour===

;PenColour string NewColor;
:Sets the pen's drawing color to either the specified [http://msdn.microsoft.com/en-us/library/aa358802.aspx named .NET color] or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

:For full opacity, use an alpha value of ff (e.g. <tt>ffff0000</tt> for red); for varying degrees of transparency, reduce the alpha value (e.g. <tt>800000ff</tt> for half-transparent blue).

:The color names and hexadecimal color representations are not case-sensitive.

Example:
<source lang="lsl">
CommandList += "PenColour MidnightBlue;";
CommandList += "PenColour ff191970;";
</source>

===PenSize===

;PenSize float width;
:Sets the pen size to a square of '''width''' pixels by '''width''' pixels. If '''width''' is an odd number, the pen will be exactly centered on the coordinates provided in the various drawing commands; if it is an even number, it will be centered slightly higher and to the left of the actual coordinates.

:Although the parameter accepts a floating-point value, anything following a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "PenSize 5;";
</source>

===Rectangle===

;Rectangle float width, float height;
:Draws an unfilled rectangle, using the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Rectangle 150,75;";
</source>

==Text Drawing Commands==

===FontName===

;FontName string fontname;
:Sets the font used by the '''[[#Text|Text]]''' command. If the specified font is not installed on the system, the default font (Arial or its local equivalent) is used.

:There is no equivalent convenience function; if you wish to change the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontName Times New Roman;";
</source>

===FontProp===

;FontProp string properties;
:Sets the text display properties (Regular, Boldface, Underline, Italic and Strikeout) used by subsequent '''[[#Text|Text]]''' calls. The properties are represented by single letters (R,B,U,I and S, respectively), separated by commas. 'R' is a special case which turns off all other properties, while the others are additive.

:There is no equivalent convenience function; if you wish to change the properties of the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontProp B,I;";
</source>

===FontSize===

;FontSize float size;
:Sets the font size used by subsequent '''[[#Text|Text]]''' calls. The '''size''' parameter represents the font height in points.

:Please note that the font height is given in ''points'', not in ''pixels''. The resulting size of the font in pixels may vary depending on the system settings, specifically the display system's "dots per inch" metric. A system set to 96dpi will produce differently sized text than a system set to 120dpi. If precise text size is required, consider using the [[osGetDrawStringSize]]() function to help calculate the proper FontSize value to use (but bear in mind that [[osGetDrawStringSize]]() takes an integer parameter for the size, whereas FontSize does use floating-point values).

:Unlike the other drawing commands, anything following a decimal point in the '''size''' parameter is significant.

:If a negative FontSize parameter is specified, any text subsequently added will be displayed upside down and to the right of the point of origin.

Example:
:<source lang="lsl">
CommandList += "FontSize 12;";
</source>

===Text===

;Text string text;
:Draws the specified string of text with the current pen color, using the currently defined [[#FontName|font]], [[#FontSize|size]] and [[#FontProp|properties]] (which default to regular 14-point Arial).

:The text will be drawn with the upper left corner of the first glyph at the pen's current position (however, note that glyphs within the font may be defined to extend to the left of their origin point).

:If you need to include a semicolon in the text to be displayed, you will have to change the command delimiter in the <tt>extraParams</tt> parameter to the osSetDynamicTexture* functions. However, this will require that ''all'' commands be terminated with the alternate delimiter, and you cannot use the convenience functions (which are hardcoded to use a semicolon).

:The text may or may not be antialiased, depending on the system settings of the machine upon which the simulator is running. Furthermore, if the system is configured to use LCD subpixel antialiasing (e.g. ClearType), the text may have colored fringes on the smoothed pixels, which may result in a less than optimum image.

:Please note that the pen position is ''not'' updated after this call.

Example:
:<source lang="lsl">
CommandList += "Text Nobody here but us hippos!;";
</source>

Dynamic textures

2009-07-27T22:46:10Z

Godfrey: Added hierarchical navigation links

{{Template:Quicklinks}}

[[Technical Reference | Technical Reference]] -> [[Technical Reference/terms | Terms]] -> [[Status | Status Page]] -> [[OSSL_Implemented| OSSL Implemented Functions]] -> [[Dynamic textures]]

Dynamic textures allow scripts to create images on the fly, combining graphics loaded from the World Wide Web with text, lines, ellipses and filled or unfilled rectangles. The textures thus created are temporary, maintained by the individual region in which they are created, and are not permanently stored in the [[Asset Server]].

In general, one creates a string containing a list of [[Drawing commands]] and parameters, either directly or with the aid of one of the "convenience" drawing functions listed below, then passes this string as a parameter to one of the osSetDynamicTexture* commands.
{| width="100%"
| valign="top" width="50%"|'''Graphics Primitive Drawing Functions'''
*[[osDrawEllipse]]
*[[osDrawFilledRectangle]]
*[[osDrawImage]]
*[[osDrawLine]]
*[[osDrawRectangle]]
*[[osMovePen]]
*[[osSetPenColour]]
*[[osSetPenSize]]

'''Text Drawing Functions'''
*[[osDrawText]]
*[[osSetFontSize]]
*[[osGetDrawStringSize]]

'''Dynamic Texture Creation Functions'''
*[[osSetDynamicTextureURL]]
*[[osSetDynamicTextureURLBlend]]
*[[osSetDynamicTextureURLBlendFace]]
*[[osSetDynamicTextureData]]
*[[osSetDynamicTextureDataBlend]]
*[[osSetDynamicTextureDataBlendFace]]
| valign="top" width="50%"|'''Graphics Primitive Drawing Commands'''
*[[Drawing commands#Ellipse|Ellipse]]
*[[Drawing commands#FillRectangle|FillRectangle]]
*[[Drawing commands#Image|Image]]
*[[Drawing commands#LineTo|LineTo]]
*[[Drawing commands#MoveTo|MoveTo]]
*[[Drawing commands#PenColour|PenColour]]
*[[Drawing commands#PenSize|PenSize]]
*[[Drawing commands#Rectangle|Rectangle]]

'''Text Drawing Commands'''
*[[Drawing commands#FontName|FontName]]
*[[Drawing commands#FontProp|FontProp]]
*[[Drawing commands#FontSize|FontSize]]
*[[Drawing commands#Text|Text]]
|}

Dynamic textures

2009-07-27T22:42:17Z

Godfrey: Added Quicklinks

{{Template:Quicklinks}}
Dynamic textures allow scripts to create images on the fly, combining graphics loaded from the World Wide Web with text, lines, ellipses and filled or unfilled rectangles. The textures thus created are temporary, maintained by the individual region in which they are created, and are not permanently stored in the [[Asset Server]].

In general, one creates a string containing a list of [[Drawing commands]] and parameters, either directly or with the aid of one of the "convenience" drawing functions listed below, then passes this string as a parameter to one of the osSetDynamicTexture* commands.
{| width="100%"
| valign="top" width="50%"|'''Graphics Primitive Drawing Functions'''
*[[osDrawEllipse]]
*[[osDrawFilledRectangle]]
*[[osDrawImage]]
*[[osDrawLine]]
*[[osDrawRectangle]]
*[[osMovePen]]
*[[osSetPenColour]]
*[[osSetPenSize]]

'''Text Drawing Functions'''
*[[osDrawText]]
*[[osSetFontSize]]
*[[osGetDrawStringSize]]

'''Dynamic Texture Creation Functions'''
*[[osSetDynamicTextureURL]]
*[[osSetDynamicTextureURLBlend]]
*[[osSetDynamicTextureURLBlendFace]]
*[[osSetDynamicTextureData]]
*[[osSetDynamicTextureDataBlend]]
*[[osSetDynamicTextureDataBlendFace]]
| valign="top" width="50%"|'''Graphics Primitive Drawing Commands'''
*[[Drawing commands#Ellipse|Ellipse]]
*[[Drawing commands#FillRectangle|FillRectangle]]
*[[Drawing commands#Image|Image]]
*[[Drawing commands#LineTo|LineTo]]
*[[Drawing commands#MoveTo|MoveTo]]
*[[Drawing commands#PenColour|PenColour]]
*[[Drawing commands#PenSize|PenSize]]
*[[Drawing commands#Rectangle|Rectangle]]

'''Text Drawing Commands'''
*[[Drawing commands#FontName|FontName]]
*[[Drawing commands#FontProp|FontProp]]
*[[Drawing commands#FontSize|FontSize]]
*[[Drawing commands#Text|Text]]
|}

OsDrawEllipse

2009-07-27T22:41:45Z

Godfrey: Added Quicklinks

{{Template:Quicklinks}}
LSL: '''[[string]] osDrawEllipse( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawEllipse( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends an [[Drawing_commands#Ellipse|Ellipse]] drawing command to the string provided in '''drawList''' and returns the result.

The ellipse is drawn with the current pen size and color, with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

Example:
<source lang="lsl">
// Example of osDrawEllipse
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList += osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList += osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue
CommandList += osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList += osDrawEllipse( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the ellipse
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

OsDrawEllipse

2009-07-27T22:40:51Z

Godfrey: Page created.

LSL: '''[[string]] osDrawEllipse( [[string]] drawList, [[integer]] width, [[integer]] height )''' 
C#: '''[[string]] osDrawEllipse( [[string]] drawList, [[int]] width, [[int]] height )'''

Appends an [[Drawing_commands#Ellipse|Ellipse]] drawing command to the string provided in '''drawList''' and returns the result.

The ellipse is drawn with the current pen size and color, with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

Example:
<source lang="lsl">
// Example of osDrawEllipse
default
{
state_entry()
{
string CommandList = ""; // Storage for our drawing commands

CommandList += osSetPenSize( CommandList, 3 ); // Set the pen width to 3 pixels
CommandList += osSetPenColour( CommandList, "Blue" ); // Set the pen color to blue
CommandList += osMovePen( CommandList, 28, 78 ); // Upper left corner at <28,78>
CommandList += osDrawEllipse( CommandList, 200, 100 ); // 200 pixels by 100 pixels

// Now draw the ellipse
osSetDynamicTextureData( "", "vector", CommandList, "width:256,height:256", 0 );
}
}
</source>

Dynamic textures

2009-07-27T21:39:08Z

Godfrey: Page created.

Dynamic textures allow scripts to create images on the fly, combining graphics loaded from the World Wide Web with text, lines, ellipses and filled or unfilled rectangles. The textures thus created are temporary, maintained by the individual region in which they are created, and are not permanently stored in the [[Asset Server]].

In general, one creates a string containing a list of [[Drawing commands]] and parameters, either directly or with the aid of one of the "convenience" drawing functions listed below, then passes this string as a parameter to one of the osSetDynamicTexture* commands.
{| width="100%"
| valign="top" width="50%"|'''Graphics Primitive Drawing Functions'''
*[[osDrawEllipse]]
*[[osDrawFilledRectangle]]
*[[osDrawImage]]
*[[osDrawLine]]
*[[osDrawRectangle]]
*[[osMovePen]]
*[[osSetPenColour]]
*[[osSetPenSize]]

'''Text Drawing Functions'''
*[[osDrawText]]
*[[osSetFontSize]]
*[[osGetDrawStringSize]]

'''Dynamic Texture Creation Functions'''
*[[osSetDynamicTextureURL]]
*[[osSetDynamicTextureURLBlend]]
*[[osSetDynamicTextureURLBlendFace]]
*[[osSetDynamicTextureData]]
*[[osSetDynamicTextureDataBlend]]
*[[osSetDynamicTextureDataBlendFace]]
| valign="top" width="50%"|'''Graphics Primitive Drawing Commands'''
*[[Drawing commands#Ellipse|Ellipse]]
*[[Drawing commands#FillRectangle|FillRectangle]]
*[[Drawing commands#Image|Image]]
*[[Drawing commands#LineTo|LineTo]]
*[[Drawing commands#MoveTo|MoveTo]]
*[[Drawing commands#PenColour|PenColour]]
*[[Drawing commands#PenSize|PenSize]]
*[[Drawing commands#Rectangle|Rectangle]]

'''Text Drawing Commands'''
*[[Drawing commands#FontName|FontName]]
*[[Drawing commands#FontProp|FontProp]]
*[[Drawing commands#FontSize|FontSize]]
*[[Drawing commands#Text|Text]]
|}

Talk:Drawing commands

2009-07-27T20:34:44Z

Godfrey: Explanation

I know this page contains information available elsewhere in the wiki (e.g. [[OSSL_TextureDrawing]]); I'm trying to create a more complete and up-to-date set of reference pages for OSSL, and I felt splitting the information into logical sections would make it ultimately more usable.

Drawing commands

2009-07-27T20:31:21Z

Godfrey: Page created.

{{Template:Quicklinks}}
The drawing commands are strings of text which are concatenated to create a larger string of graphical instructions, which is then passed as a parameter to the [[Dynamic textures|dynamic texture]] drawing functions. With two exceptions, there are convenience functions, such as [[osDrawRectangle]](), provided to assist in building the command list. It is slightly more efficient to directly manipulate the string containing the drawing commands, as it avoids the overhead of multiple function calls (albeit with an arguable loss of readability).

In general, the drawing commands consist of a case-sensitive token which identifies the command, followed by one or more comma-delimited parameters, and terminating in a separator character (a semicolon by default). Whitespace surrounding the commas and/or separator is permitted.

In the examples which follow, it is assumed that ''CommandList'' is a string variable which has already been defined within the script source code.

==Graphics Primitive Drawing Commands==

===Ellipse===

;Ellipse float width, float height;
:Draws an ellipse with the current pen size and color.

:The ellipse is drawn with the specified width and height (in pixels), centered on a point which is (width/2) pixels to the right of the pen's current X position, and (height/2) pixels below the pen's current Y position. After the ellipse is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Ellipse 100,100;";
</source>

===FillRectangle===

;FillRectangle float width, float height;
:Draws a rectangle, bordered and filled with the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "FillRectangle 150,75;";
</source>

===Image===

;Image float height, float width, string URL;
:Retrieves an image specified by the URL parameter and draws it at the specified height and width, with the upper left corner of the image placed at the pen's current position. After the image is drawn, the width and height values are added to the pen's X and Y position, respectively.

:If the URL points to an invalid location, an image type not supported by libgdi, or a non-image MIME type, nothing is drawn. If either or both of the '''width''' or '''height''' parameters are zero or negative, nothing is drawn, but the image is still retrieved.

:Although the '''width''' and '''height''' parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Image 293,62,<nowiki>http://opensimulator.org/skins/osmonobook/images/headerLogo.png</nowiki>;";
</source>

===LineTo===

;LineTo float x, float y;
:Draws a line from the pen's current location to the specified coordinates, using the pen's current color and width.

:After the line is drawn, the specified coordinates become the pen's new current location.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "LineTo 640,480;";
</source>

===MoveTo===

;MoveTo float x, float y;
:Updates the pen's current position to the coordinates provided in the parameters. Nothing is drawn.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "MoveTo 570,23;";
</source>

===PenColour===

;PenColour string NewColor;
:Sets the pen's drawing color to either the specified [http://msdn.microsoft.com/en-us/library/aa358802.aspx named .NET color] or to a 32-bit color value (formatted as eight hexadecimal digits in the format aarrggbb, representing the eight-bit alpha, red, green and blue channels).

:For full opacity, use an alpha value of ff (e.g. <tt>ffff0000</tt> for red); for varying degrees of transparency, reduce the alpha value (e.g. <tt>800000ff</tt> for half-transparent blue).

:The color names and hexadecimal color representations are not case-sensitive.

Example:
<source lang="lsl">
CommandList += "PenColour MidnightBlue;";
CommandList += "PenColour ff191970;";
</source>

===PenSize===

;PenSize float width;
:Sets the pen size to a square of '''width''' pixels by '''width''' pixels. If '''width''' is an odd number, the pen will be exactly centered on the coordinates provided in the various drawing commands; if it is an even number, it will be centered slightly higher and to the left of the actual coordinates.

:Although the parameter accepts a floating-point value, anything following a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "PenSize 5;";
</source>

===Rectangle===

;Rectangle float width, float height;
:Draws an unfilled rectangle, using the current pen size and color.

:The rectangle is drawn at the specified width and height (in pixels), with the upper left corner of the rectangle placed at the pen's current position. After the rectangle is drawn, the width and height values are added to the pen's X and Y position, respectively.

:Although the parameters accept floating-point values, anything after a decimal point will be ignored.

Example:
:<source lang="lsl">
CommandList += "Rectangle 150,75;";
</source>

==Text Drawing Commands==

===FontName===

;FontName string fontname;
:Sets the font used by the '''[[#Text|Text]]''' command. If the specified font is not installed on the system, the default font (Arial or its local equivalent) is used.

:There is no equivalent convenience function; if you wish to change the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontName Times New Roman;";
</source>

===FontProp===

;FontProp string properties;
:Sets the text display properties (Regular, Boldface, Underline, Italic and Strikeout) used by subsequent '''[[#Text|Text]]''' calls. The properties are represented by single letters (R,B,U,I and S, respectively), separated by commas. 'R' is a special case which turns off all other properties, while the others are additive.

:There is no equivalent convenience function; if you wish to change the properties of the font used by the '''[[#Text|Text]]''' command, you must manipulate the string directly.

Example:
:<source lang="lsl">
CommandList += "FontProp B,I;";
</source>

===FontSize===

;FontSize float size;
:Sets the font size used by subsequent '''[[#Text|Text]]''' calls. The '''size''' parameter represents the font height in points.

:Please note that the font height is given in ''points'', not in ''pixels''. The resulting size of the font in pixels may vary depending on the system settings, specifically the display system's "dots per inch" metric. A system set to 96dpi will produce differently sized text than a system set to 120dpi. If precise text size is required, consider using the [[osGetDrawStringSize]]() function to help calculate the proper FontSize value to use (but bear in mind that [[osGetDrawStringSize]]() takes an integer parameter for the size, whereas FontSize does use floating-point values).

:Unlike the other drawing commands, anything following a decimal point in the '''size''' parameter is significant.

:If a negative FontSize parameter is specified, any text subsequently added will be displayed upside down and to the right of the point of origin.

Example:
:<source lang="lsl">
CommandList += "FontSize 12;";
</source>

===Text===

;Text string text;
:Draws the specified string of text with the current pen color, using the currently defined [[#FontName|font]], [[#FontSize|size]] and [[#FontProp|properties]] (which default to regular 14-point Arial).

:The text will be drawn with the upper left corner of the first glyph at the pen's current position (however, note that glyphs within the font may be defined to extend to the left of their origin point).

:If you need to include a semicolon in the text to be displayed, you will have to change the command delimiter in the <tt>extraParams</tt> parameter to the osSetDynamicTexture* functions. However, this will require that ''all'' commands be terminated with the alternate delimiter, and you cannot use the convenience functions (which are hardcoded to use a semicolon).

:The text may or may not be antialiased, depending on the system settings of the machine upon which the simulator is running. Furthermore, if the system is configured to use LCD subpixel antialiasing (e.g. ClearType), the text may have colored fringes on the smoothed pixels, which may result in a less than optimum image.

:Please note that the pen position is ''not'' updated after this call.

Example:
:<source lang="lsl">
CommandList += "Text Nobody here but us hippos!;";
</source>