Raycasting: how and why does this work?

From this unity tutorial: http://unity3d.com/learn/tutorials/projects/stealth/cctv-cameras
, this line...

Code (CSharp):

1. if(Physics.Raycast(transform.position, relPlayerPos, out hit))

looking at the documentation for raycast, it seems to take four inputs. origin point, direction, magnitude/distance (i'll use those words interchangeably), and a filter. I'm not too familiar with raycasting though.

As near as i can tell, "out hit" is not a parameter, but is instead directing the function's return into a variable. Which means this raycast is only being called with two parameters.

relPlayerPos here is the offset between a CCTV camera, and the player. Being used as the direction input doesn;'t entirely make sense because that's going to be a non-normalised value. Does the raycast function normalise the direction input?

If it doesn't then i can see why this would work, but that then begs the question,. If no magnitude is passed shouldn't it default to 0.0, and cause the direction to zero out also? Or if not, then what's the point in having a magnitude value, if that information can already be included in the direction input ?

 

from geometry...

Ray -
Definition: A line which starts at a point with given coordinates, and goes off in a particular direction to infinity, possibly through a second point.

By definition a ray goes on for infinity. So by default the 'magnitude'/'distance' is forever. You can just pull in that ray to a shorter distance if you so desire, because you may not want to test outside of some certain range.

 

As for the 'out hit'. This is a parameter. It's a parameter that uses the 'out' keyword. A parameter defined with the 'out' keyword is referenced, so that if the parameter is modified in the function, the caller is updated as well.

see: http://msdn.microsoft.com/en-us/library/t3c3bfhx.aspx

This is similar to the 'ref' keyword as well. The difference being that a 'ref' param doesn't necessarily get modified in the function. Where as an 'out' param MUST be changed in the funciton.

The 'out' params are often used to have more than one return value from a function. This is useful for validating function calls that return a boolean that says if the method call succeeded, while the 'out' param is the result of the successful operation.

see: Int.TryParse as an example
http://msdn.microsoft.com/en-us/library/f02979c7(v=vs.110).aspx

 

So the Raycast you are calling is this one.
static bool Raycast(Vector3 origin, Vector3 direction, RaycastHit hitInfo, float distance = Mathf.Infinity, int layerMask = DefaultRaycastLayers);

origin: I think you get this one
direction: Which direction. The magnatude of this does not matter at all! Only the direction. The "distance" is set by the 4th parameter.
hitInfo: This does count as a parameter, but you are passing a reference so that the original can be modified. This lets you get information about the hit.
distance: How far do you want to raycast? If you put nothing here, it assumes infinity.
layerMask: which layers should we worry about? If you put nothing here it hits every layer except "IgnoreRaycasts"

 

A normalized value isn't necessary when passing into the 'RayCast' method. Because the method expects it to be a direction, it will normalize it for itself. It's used only as a direction.

 

thank you guys, this makes a lot of sense. Especially garth's post.

there is one other concern. I have no idea exactly where the origin for this is. Obviously, it uses the "position" of the calling object, but what does that actually mean? the centre of it's bounding box?

And if so, what exactly is stopping this raycast from being a complete failure by colliding with the thing it's firing from, and never getting outside of the bounding box at all ? isn't it necessary to use the mask/filter to prevent that?

 

transform.position is from the pivot point. This is the point you see when the object is selected and "Pivot" is selected in the top left of the scene window. ("Center" is the other option.)

The sides of a collider are actually one-way. This means that a Raycast can exit a BoxCollider without hitting it, but it will hit when entering a BoxCollider.