User:Rand Linden/LlCastRay: Difference between revisions

From Second Life Wiki
Jump to navigation Jump to search
← Older edit
Rand Linden (talk | contribs)
9,923 edits
Rand Linden (talk | contribs)
9,923 edits
Redirected page to LlCastRay
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
{{LSL_Function
#REDIRECT [[LlCastRay]]
|func=llCastRay
|func_id=?
|func_desc=Description TBD
 
|func_sleep=
|func_energy=
 
|func_footnote=
|return_type=list
|return_text=consisting of a three values for each hit:
* UUID
* Link number
* Hit position
 
|p1_type=Vector|p1_name=start|p1_desc=starting location
 
|p2_type=Vector|p2_name=end|p2_desc=ending location
 
|p3_type=list|p3_name=options|p3_desc= Consists of one or more of:
*RC_REJECT_TYPES followed by an integer "filter" described below.
*RC_DATA_FLAGS followed by an integer "flags" described below.
*RC_MAX_HITS followed by an integer specifying the max number of hits to return. 
*RC_DETECT_PHANTOM followed by a boolean integer (default 0, FALSE).
 
|constants=
<table class=lltable border=1>
<tr>
<th>Constant</th>
<th>Default Value</th>
<th>Description</th>
</tr>
<tr><td>RC_REJECT_TYPES </td>
<td>0</td>
<td></td>
</tr>
<tr><td>RC_DATA_FLAGS </td>
<td>0</td>
<td></td>
</tr>
<tr><td>RC_MAX_HITS</td>
<td>1</td>
<td>Maximum number of hits to return.  Maximum value is 256--To avoid performance issues, keep it small.</td>
</tr>
<tr><td>RC_DETECT_PHANTOM</td>
<td>0, FALSE</td>
<td>Set to TRUE (or nonzero) to detect phantom AND volume detect objects. It is not possible to detect only phantom objects or only volume detect objects. If set to TRUE, phantom and volume detect objects will always be detected, even if RC_REJECT_NONPHYSICAL and RC_REJECT_PHYSICAL are set in RC_REJECT_TYPES.</td>
</tr>
</table>
 
|caveats=
Ray casts are throttled by the amount of time actually taken to perform the cast. Each region is allotted a 2ms pool, divided proportionally over parcels the same way prim limits are. Each agent is allotted 100us. All scripts in attachments and, objects on which an avatar is seated, use the agent pool whereas all scripts use the parcel pool. A ray cast can be performed if at least 30us of raycast time remain in the appropriate pool. If there is insufficient time remaining, RCERR_CAST_TIME_EXCEEDED is returned as the status code. The exact time used by the ray cast is measured when it is performed and that number (in microseconds) is subtracted from the pool. (The time remaining can be a negative number.) Over time, the pool is automatically replenished (at a rate of 25% of the max time per frame).
 
For example, if you start out with 100us and perform a 50us raycast, 50us will be remain. If you then a 70us raycast during the same frame, you will have -20us remaining. Subsequent calls to llCastRay that frame will fail with status code RCERR_CAST_TIME_EXCEEDED. At the start of the next frame, you will have 5us available (25us are restored each frame) and any attempt to call llCastRay will again fail as you need 30us to execute a raycast. One frame after that, 30us will be available and a raycast can once again be performed.
 
This method of throttling puts the scripter "closer to the machine". That is, you're only being charged for what you use, and more efficient raycast techniques will automatically be charged less than less efficient ones. The exact throttle values are subject to change at any time before release to the main grid.
 
Tips for Efficient Raycasts:
*Keep the max number of hits returned as small as possible
*Set as many RC_REJECT_TYPES as possible (of factors you can control, this will likely have the largest impact). For example, if you only want to know where the nearest agent is along a ray, use RC_REJECT_LAND | RC_REJECT_PHYSICAL | RC_REJECT_NONPHYSICAL
*When possible, avoid raycasting through piles of prims and avoid raycasting against concave physics objects (anything with cut, hollow, twist, and so on, and any mesh object that has no decomposition and has physics type "prim"). Obviously this can't always be avoided, so some casts may take significantly longer than others. Plan for that with robust scripts that handle RCERR_CAST_TIME_EXCEEDED responsibly, namely by sleeping briefly after the call and waiting for a few frames to go by before trying again.
 
 
''Filter'' is a bitwise-or combination of the following constants: ''RC_REJECT_AGENTS'', ''RC_REJECT_PHYSICAL'', ''RC_REJECT_NONPHYSICAL'', and ''RC_REJECT_LAND'' except that if you select all four of them, a script runtime error will be generated (it makes no sense to cast a ray and reject everything!). Note that phantom and volume detect objects are never returned and that seated agents are treated like unseated agents. I.e., you either get seated and unseated agents in your results, or you use ''RC_REJECT_AGENTS'' and get neither. Using 0 as the filter value will return all hits.
 
''Flags'' is a bitwise-or combination of: ''RC_GET_NORMAL'', ''RC_GET_ROOT_KEY'', and ''RC_GET_LINK_NUM''. These select whether you want link numbers and hit normals in your results list. By default, you will get the UUID ('key') of the exact child prim hit. If instead you want the key of the root prim, set ''RC_GET_ROOT_KEY''. A terrain hit will register as NULL_KEY.
 
''Status_code'' is a number tacked onto the end of the strided list to give you extra information about the ray cast. If the cast succeeded, it will be &gt;=0 and will indicate the number of hits. If the ray cast failed (which should only happen right now if the simulator performance is running low), you'll get a negative status code. ''RCERR_SIM_PERF_LOW'' will be used as the status code if the overall physics time in the simulator is too high to perform raycasts. The idea is that you will know to try your cast again in a few frames.
 
 
|examples=
<lsl>
integer filter = 0;
 
default
{
    state_entry()
    {
        llSay(0, "Hello, Avatar!");
    }
 
    touch_start(integer total_number)
    {
        vector start = llGetPos();
        vector end = start - <0,-25,0>;
       
        if ( filter > 8 )
        {
            filter = 0;
        }
       
        llOwnerSay("Filter " + (string)filter);
 
        list results = llCastRay(start, end, [RC_REJECT_TYPES, filter, RC_MAX_HITS, 4] );
       
        integer hitNum = 0;
        // Handle error conditions here by checking llList2Integer(results, -1) >= 0
        for ( hitNum = 0; hitNum < llList2Integer(results, -1); hitNum++ )
        {
            // Stride is 2 because we didn't request normals or link numbers
            key uuid = llList2Key(results, 2*hitNum);
            string name;
            if ( uuid == NULL_KEY )
            {
                name = "Land";
            }               
            else
            {
                name = llKey2Name(uuid);
            }
            llOwnerSay("Hit " + name);
        }
       
        filter += 1;
    }
}
</lsl>
 
|notes=
Use [[llDumpList2String]] to see what the output looks like when you try a new set of flags.
 
|cat1=LSL Physics
|cat2=LSL Light
}}

Latest revision as of 16:38, 24 June 2011

Redirect to:

Retrieved from "https://wiki.secondlife.com/w/index.php?title=User:Rand_Linden/LlCastRay&oldid=1147494"