rr::RRCollider Class Reference

#include <RRCollider.h>

Inheritance diagram for rr::RRCollider:

Public Types
enum	IntersectTechnique {   IT_LINEAR ,   IT_BSP_COMPACT ,   IT_BSP_FAST ,   IT_BSP_FASTER ,   IT_BSP_FASTEST ,   IT_BVH_COMPACT ,   IT_BVH_FAST ,   IT_VERIFICATION }
typedef RRCollider *	Builder(const RRMesh *mesh, const class RRObjects *objects, IntersectTechnique intersectTechnique, bool &aborting, const char *cacheLocation, void *buildParams)

Public Member Functions
virtual void	update ()=0
virtual bool	intersect (RRRay &ray) const =0
void	getDistancesFromPoint (const RRVec3 &point, const RRObject *object, bool shadowRays, RRVec2 &distanceMinMax, unsigned numRays=300) const
void	getDistancesFromCamera (const RRCamera &camera, const RRObject *object, bool shadowRays, RRVec2 &distanceMinMax, unsigned numRays=100) const
virtual const RRMesh *	getMesh () const =0
virtual IntersectTechnique	getTechnique () const =0
virtual void	setTechnique (IntersectTechnique intersectTechnique, bool &aborting)
virtual size_t	getMemoryOccupied () const =0
virtual	~RRCollider ()
Public Member Functions inherited from rr::RRAligned
void *	operator new (std::size_t n)
void *	operator new[] (std::size_t n)
void	operator delete (void *p, std::size_t n)
void	operator delete[] (void *p, std::size_t n)
Public Member Functions inherited from rr::RRUniformlyAllocated
void *	operator new (std::size_t n)
void *	operator new[] (std::size_t n)
void	operator delete (void *p, std::size_t n)
void	operator delete[] (void *p, std::size_t n)

Static Public Member Functions
static void	registerTechnique (unsigned intersectTechnique, Builder *builder)
static RRCollider *	create (const RRMesh *mesh, const class RRObjects *objects, IntersectTechnique intersectTechnique, bool &aborting, const char *cacheLocation=nullptr, void *buildParams=0)

Additional Inherited Members
Protected Member Functions inherited from rr::RRAlignedNonCopyable
	RRAlignedNonCopyable ()
	~RRAlignedNonCopyable ()

Detailed Description

Finds ray - trianglemesh intersections.

Thread safe: yes, stateless, may be accessed by any number of threads simultaneously.

Mesh passed to create() must stay constant for whole life of collider, otherwise collision results are undefined.

Member Typedef Documentation

Builder

typedef RRCollider * rr::RRCollider::Builder(const RRMesh *mesh, const class RRObjects *objects, IntersectTechnique intersectTechnique, bool &aborting, const char *cacheLocation, void *buildParams)

Type of custom collider builder.

Member Enumeration Documentation

IntersectTechnique

enum rr::RRCollider::IntersectTechnique

Built-in techniques for finding ray-mesh intersections. Others can be added via registerTechnique().

Enumerator
IT_LINEAR	Speed 1%, size 0. Fallback technique when better one fails.
IT_BSP_COMPACT	Speed 100%, size ~5 bytes per triangle. Slow build. For platforms with extremely limited memory.
IT_BSP_FAST	Speed 175%, size ~31 bytes per triangle. Slow build. For platforms with limited memory.
IT_BSP_FASTER	Speed 200%, size ~60 bytes per triangle. Slow build.
IT_BSP_FASTEST	Speed 230%, size ~200 bytes per triangle. Slow build.
IT_BVH_COMPACT	Speed 200%, size ~150 bytes per triangle. Fast build.
IT_BVH_FAST	Speed 230%, size ~162 bytes per triangle. Fast build. Usually the best choice.
IT_VERIFICATION	Only for verification purposes, performs tests using all known techniques and compares results.

Constructor & Destructor Documentation

~RRCollider()

virtual rr::RRCollider::~RRCollider ( )

inlinevirtual

Member Function Documentation

registerTechnique()

static void rr::RRCollider::registerTechnique ( unsigned  intersectTechnique, Builder *  builder  )

static

Lets you register custom collider builder. If other builder was already registered with the same intersectTechnique number, it is replaced with the new builder.

create()

static RRCollider * rr::RRCollider::create ( const RRMesh *  mesh, const class RRObjects *  objects, IntersectTechnique  intersectTechnique, bool &  aborting, const char *  cacheLocation = nullptr, void *  buildParams = 0  )

static

Creates and returns collider, acceleration structure for finding ray x mesh intersections.

Parameters

mesh	Mesh you want to collide with. If set, objects must be nullptr.
objects	Objects you want to collide with. If set, mesh must be nullptr.
intersectTechnique	Technique used for accelerating collision searches. See IntersectTechnique.
aborting	May be set asynchronously. When set, collider creation is aborted.
cacheLocation	Optional location of cache, path to directory where acceleration structures may be cached. Default nullptr caches in temp, "*" or any other invalid path disables caching, any valid is path where to cache colliders.
buildParams	Optional additional parameters, specific for each technique and not revealed for public use.

Returns

Created collider.

update()

virtual void rr::RRCollider::update ( )

pure virtual

Faster alternative to deleting and recreating collider.

When working with single RRMesh, default BVH collider rereads all mesh data (updates fully) while BSP colliders stay unchanged, they don't implement update() yet. When working with RRObject[s], collider rereads object's transformation matrices, but ignores possible changes in triangle meshes (you are responsible for calling collider->update() on colliders that had mesh changed).

intersect()

virtual bool rr::RRCollider::intersect ( RRRay &  ray ) const

pure virtual

Finds ray x mesh intersections.

Parameters

ray	All inputs and outputs for search.

Returns

True if intersection was found and reported into ray.

Finds nearest intersection of ray and mesh in distance <ray->rayLengthMin,ray->rayLengthMax> and fills output attributes in ray specified by ray->rayFlags.
See RRRay for more details on inputs, especially flags that further specify collision test.
When ray->collisionHandler!=nullptr, it is called and it may accept or refuse intersection.
When collisionHandler accepts intersection, true is returned. When collisionHandler rejects intersection, search continues.
False is returned when there were no accepted intersection.

There is an exception for IntersectTechnique IT_LINEAR: intersections are found in random order.

CollisionHandler

Ray->collisionHandler can be used to:

• gather all intersections instead of just first one. CollisionHandler can gather or immediately process them. This is faster and more precise approach than multiple calls of intersect() with increasing rayLengthMin to distance of last intersection.
• not collide with optional parts of mesh (layers) that are turned off at this moment.
• find pixel precise collisions with alpha keyed textures.
• collide with specific probability.

Multithreading

You are encouraged to find multiple intersections in multiple threads at the same time. This will improve your performance on multicore CPUs.
Even with Intel's hyperthreading, which is inferior to two fully-fledged cores, searching multiple intersections at the same time brings surprisingly high performance bonus.
All you need is one RRRay and optionally one RRCollisionHandler for each thread, other structures like RRMesh and RRCollider are stateless and may be accessed by arbitrary number of threads simultaneously.
If you are not familiar with OpenMP, be sure to examine it. With OpenMP, which is built-in feature of modern compilers, searching multiple intersections at the same time is matter of one or few lines of code.

getDistancesFromPoint()

void rr::RRCollider::getDistancesFromPoint	(	const RRVec3 &	point,
		const RRObject *	object,
		bool	shadowRays,
		RRVec2 &	distanceMinMax,
		unsigned	numRays = 300
	)		const

Shoots rays from point, measures distance to first collision, updates distanceMinMax. It can be used for automatic near/far adjustment.

Parameters

point	Point to shoot from.
object	Optional, enables testing materials, rays don't stop when they go through transparent pixels.
shadowRays	True if you wish to measure distance to the nearest shadow caster (even if it is invisible), rather than to visible object.
distanceMinMax	Has to be initialized. distanceMinMax[0] is decreased whenever closer collision is found, distanceMinMax[1] is increased whenever farther collision is found. Stays unchanged when ray doesn't collide at all.
numRays	Approximately how many rays it shoots (higher number = slower but more accurate).

getDistancesFromCamera()

void rr::RRCollider::getDistancesFromCamera	(	const RRCamera &	camera,
		const RRObject *	object,
		bool	shadowRays,
		RRVec2 &	distanceMinMax,
		unsigned	numRays = 100
	)		const

Similar to getDistancesFromPoint, but shoots from camera.

getMesh()

virtual const RRMesh * rr::RRCollider::getMesh ( ) const

pure virtual

Returns

Mesh that was passed to create(). Must always return valid mesh, implementation is not allowed to return nullptr.

getTechnique()

virtual IntersectTechnique rr::RRCollider::getTechnique ( ) const

pure virtual

Returns

Technique used by collider. May differ from technique requested in create().

setTechnique()

virtual void rr::RRCollider::setTechnique ( IntersectTechnique  intersectTechnique, bool &  aborting  )

virtual

Changes technique, but only if collider was created with IT_LINEAR.

Other colliders have technique hardcoded, for tiny bit higher speed.

Parameters

intersectTechnique	Technique used for accelerating collision searches. See IntersectTechnique.
aborting	May be set asynchronously. When set, technique change is aborted, old one is preserved.

getMemoryOccupied()

virtual size_t rr::RRCollider::getMemoryOccupied ( ) const

pure virtual

Returns

Total amount of system memory occupied by collider.