Added setFromCamera method, updated example

docs/api/core/Raycaster.html

@@ -18,24 +18,22 @@
 		var raycaster = new THREE.Raycaster();
 		var mouse = new THREE.Vector2();
 
-		function onMouseMove(event) {
-			mouse.x = ( event.clientX / window.innerWidth ) * 2 - 1
-			mouse.y = - ( event.clientY / window.innerHeight ) * 2 + 1		
-		}
+		function onMouseMove( event ) {
 
-		function pickingRay( raycaster, coords, camera ) {
-
-		    // the camera is assumed _not_ to be a child of a transformed object
-
-		    raycaster.ray.origin.copy( camera.position );
-		    raycaster.ray.direction.set( coords.x, coords.y, 0.5 ).unproject( camera ).sub( camera.position ).normalize();
+			// calculate mouse position in normalized device coordinates
+			// (-1 to +1) for both components
 
+			mouse.x = ( event.clientX / window.innerWidth ) * 2 - 1
+			mouse.y = - ( event.clientY / window.innerHeight ) * 2 + 1		
+		
 		}
 
 		function render() {
 
-			pickingRay( raycaster, mouse, camera );	
+			// update the picking ray with the camera and mouse position	
+			raycaster.setFromCamera( mouse, camera );	
 
+			// calculate objects intersecting the picking ray
 			var intersects = raycaster.intersectObjects( scene.children );
 
 			for ( var intersect in intersects ) {
@@ -62,7 +60,10 @@
 			[example:webgl_octree_raycasting Raycasting using an octree],
 			[example:webgl_interactive_voxelpainter Raycasting to paint voxels]</div>
 
-		<!-- http://jsfiddle.net/7hfaoeo7/3/ -->
+
+		<div>
+		</div>
+
 
 		<h2>Constructor</h2>
 
@@ -118,16 +119,25 @@
 		Updates the ray with a new origin and direction.
 		</div>
 
+		<h3>[method:null setFromCamera]( [page:Vector2 coords], [page:Camera camera] )</h3>
+		<div>
+		[page:Vector2 coords] — 2D coordinates of the mouse, in normalized device coordinates (NDC)---X and Y components should be between -1 and 1.<br />
+		[page:Camera camera] — camera from which the ray should originate
+		</div>
+		<div>
+		Updates the ray with a new origin and direction.
+		</div>
+
+
 		<h3>[method:Array intersectObject]( [page:Object3D object], [page:Boolean recursive] )</h3>
 		<div>
 		<p>
 		[page:Object3D object] — The object to check for intersection with the ray.<br />
 		[page:Boolean recursive] — If set, it also checks all descendants. Otherwise it only checks intersecton with the object.
 		</p>
-
 		</div>
 		<div>
-		Checks all intersection between the ray and the object with or without the descendants. Intersections are returned sorted by distance, closest first.
+		Checks all intersection between the ray and the object with or without the descendants. Intersections are returned sorted by distance, closest first. An array of intersections is returned...
         <code>
             [ { distance, point, face, faceIndex, indices, object }, ... ]
         </code>
@@ -143,7 +153,10 @@
         When intersecting a [page:Mesh] with a [page:BufferGeometry], the *faceIndex* will be *undefined*, and *indices* will be set; when intersecting a [page:Mesh] with a [page:Geometry], *indices* will be *undefined*. 
         </p>
 		<p>
-		*Raycaster* delegates to the [page:Object3D.raycast raycast] method of the passed object, when evaluating whether the ray intersects the object or not. This allows [page:Mesh meshes] to respond differently than [page:Line lines] to ray casting.
+		*Raycaster* delegates to the [page:Object3D.raycast raycast] method of the passed object, when evaluating whether the ray intersects the object or not. This allows [page:Mesh meshes] to respond differently to ray casting than [page:Line lines] and [page:PointCloud pointclouds].
+		</p>
+		<p>
+		*Note* that for meshes, faces must be pointed towards the origin of the [page:.ray ray] in order to be detected; intersections of the ray passing through the back of a face will not be detected. To raycast against both faces of an object, you'll want to set the [page:Mesh.material material]'s [page:Material.side side] property to *THREE.DoubleSide*.  
 		</p>
 		</div>