Add a new pickVoxel function.

Hopefully this pickVoxel function will fulfil most most need with
raycasting which aren't covered by the existing raycast functions.

It's essentially a wrapper around the current functions, using a custom
functor to store the position of a solid voxel as well as the previous
empty voxel. It doesn't require the user to provide a functor of their own,
just the value that they've assigned to empty voxels.

As well as the function itself, we also have a unit test as well as it
being built in the bindings.

library/PolyVoxCore/CMakeLists.txt

@@ -75,6 +75,8 @@ SET(CORE_INC_FILES
 	include/PolyVoxCore/MaterialDensityPair.h
 	include/PolyVoxCore/MinizCompressor.h
 	include/PolyVoxCore/PolyVoxForwardDeclarations.h
+	include/PolyVoxCore/Picking.h
+	include/PolyVoxCore/Picking.inl
 	include/PolyVoxCore/RawVolume.h
 	include/PolyVoxCore/RawVolume.inl
 	include/PolyVoxCore/RawVolumeSampler.inl

library/PolyVoxCore/include/PolyVoxCore/Picking.h

@@ -0,0 +1,48 @@
+/*******************************************************************************
+Copyright (c) 2013 Matt Williams
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+    1. The origin of this software must not be misrepresented; you must not
+    claim that you wrote the original software. If you use this software
+    in a product, an acknowledgment in the product documentation would be
+    appreciated but is not required.
+
+    2. Altered source versions must be plainly marked as such, and must not be
+    misrepresented as being the original software.
+
+    3. This notice may not be removed or altered from any source
+    distribution.
+*******************************************************************************/
+
+#ifndef __PolyVox_Picking_H__
+#define __PolyVox_Picking_H__
+
+#include "PolyVoxCore/Vector.h"
+
+namespace PolyVox
+{
+	/**
+	 * A structure containing the information about a picking operation
+	 */
+	struct PickResult
+	{
+		bool didHit; ///< Did the picking operation hit anything
+		Vector3DInt32 hitVoxel; ///< The location of the solid voxel it hit
+		Vector3DInt32 previousVoxel; ///< The location of the voxel before the one it hit
+	};
+	
+	/// Pick the first solid voxel along a vector
+	template<typename VolumeType>
+	PickResult pickVoxel(VolumeType* volData, const Vector3DFloat& v3dStart, const Vector3DFloat& v3dDirectionAndLength, const typename VolumeType::VoxelType& emptyVoxelExample = typename VolumeType::VoxelType());
+}
+
+#include "PolyVoxCore/Picking.inl"
+
+#endif //__PolyVox_Picking_H__

library/PolyVoxCore/include/PolyVoxCore/Picking.inl

@@ -0,0 +1,84 @@
+/*******************************************************************************
+Copyright (c) 2013 Matt Williams
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+    1. The origin of this software must not be misrepresented; you must not
+    claim that you wrote the original software. If you use this software
+    in a product, an acknowledgment in the product documentation would be
+    appreciated but is not required.
+
+    2. Altered source versions must be plainly marked as such, and must not be
+    misrepresented as being the original software.
+
+    3. This notice may not be removed or altered from any source
+    distribution.
+*******************************************************************************/
+
+#include "PolyVoxCore/Raycast.h"
+
+namespace PolyVox
+{
+	namespace 
+	{
+		/**
+		 * This is just an implementation class for the pickVoxel function
+		 * 
+		 * It makes note of the sort of empty voxel you're looking for in the constructor.
+		 * 
+		 * Each time the operator() is called:
+		 *  * if it's hit a voxel it sets up the result and returns false
+		 *  * otherwise it preps the result for the next iteration and returns true
+		 */
+		template <typename VolumeType>
+		class RaycastPickingFunctor
+		{
+		public:
+			RaycastPickingFunctor(const typename VolumeType::VoxelType& emptyVoxelExample)
+				:m_emptyVoxelExample(emptyVoxelExample)
+				,m_result{false}
+			{
+			}
+		
+			bool operator()(const typename VolumeType::Sampler& sampler)
+			{
+				if(sampler.getVoxel() != m_emptyVoxelExample) //If we've hit something
+				{
+					m_result.didHit = true;
+					m_result.hitVoxel = sampler.getPosition();
+					return false;
+				}
+				
+				m_result.previousVoxel = sampler.getPosition();
+				
+				return true;
+			}
+			const typename VolumeType::VoxelType& m_emptyVoxelExample;
+			PickResult m_result;
+		};
+	}
+	
+	/**
+	 * \param volData The volume to pass the ray though
+	 * \param v3dStart The start position in the volume
+	 * \param v3dDirectionAndLength The direction and length of the ray
+	 * \param emptyVoxelExample The value used to represent empty voxels in your volume
+	 * 
+	 * \return A PickResult containing the hit information
+	 */
+	template<typename VolumeType>
+	PickResult pickVoxel(VolumeType* volData, const Vector3DFloat& v3dStart, const Vector3DFloat& v3dDirectionAndLength, const typename VolumeType::VoxelType& emptyVoxelExample)
+	{
+		RaycastPickingFunctor<VolumeType> functor(emptyVoxelExample);
+		
+		RaycastResult raycastResult = raycastWithDirection(volData, v3dStart, v3dDirectionAndLength, functor);
+		
+		return functor.m_result;
+	}
+}