Interface for ray-casting data structures. More...

Classes
class	Hit

Public Types
typedef unsigned int	IntersectRayOptions
	Options for intersectRays. More...

Public Member Functions
virtual const String &	className () const =0

virtual void	clear ()=0

virtual void	intersectBox (const AABox &box, Array< Tri > &results) const =0
	Returns all triangles that lie within the box. More...

virtual bool	intersectRay (const Ray &ray, Hit &hit, IntersectRayOptions options=IntersectRayOptions(0)) const =0
	Intersect a single ray. More...

shared_ptr< Surfel >	intersectRay (const Ray &ray) const
	Special single-ray CPU function for simplicity. More...

virtual void	intersectRays (const Array< Ray > &rays, Array< Hit > &results, IntersectRayOptions options=IntersectRayOptions(0)) const =0
	Batch ray casting. More...

virtual void	intersectRays (const Array< Ray > &rays, Array< shared_ptr< Surfel >> &results, IntersectRayOptions options=IntersectRayOptions(0), const Array< float > &coneBuffer=Array< float >()) const =0
	Values in results will be reused if already allocated, which can increase performance. More...

virtual void	intersectRays (const shared_ptr< Texture > &rayOrigin, const shared_ptr< Texture > &rayDirection, const shared_ptr< GBuffer > &results, IntersectRayOptions options=IntersectRayOptions(0), const shared_ptr< Texture > &rayCone=nullptr) const =0

virtual void	intersectRays (const shared_ptr< GLPixelTransferBuffer > &rayOrigin, const shared_ptr< GLPixelTransferBuffer > &rayDirection, const shared_ptr< GLPixelTransferBuffer > results[5], IntersectRayOptions options=IntersectRayOptions(0), const shared_ptr< GLPixelTransferBuffer > &rayCone=nullptr, const int baseMipLevel=0, const Vector2int32 wavefrontDimensions=Vector2int32(-1,-1), const RenderMask renderMask=0xFFFFFFFF) const =0

virtual void	intersectRays (const shared_ptr< Texture > &rayOrigin, const shared_ptr< Texture > &rayDirection, const shared_ptr< Texture > &booleanResults, IntersectRayOptions options=IntersectRayOptions(0)) const =0

virtual void	intersectRays (const shared_ptr< GLPixelTransferBuffer > &rayOrigin, const shared_ptr< GLPixelTransferBuffer > &rayDirection, const shared_ptr< GLPixelTransferBuffer > &booleanResults, IntersectRayOptions options=IntersectRayOptions(0)) const =0

virtual void	intersectRays (const Array< Ray > &rays, Array< bool > &results, IntersectRayOptions options=IntersectRayOptions(0)) const =0

virtual void	intersectSphere (const Sphere &sphere, Array< Tri > &triArray) const =0
	Returns all triangles that intersect or are contained within the sphere (technically, this is a ball intersection). More...

RealTime	lastBuildTime () const
	Time at which setContents() or rebuild() was last invoked. More...

const Tri &	operator[] (int i) const
	Array access to the stored Tris. More...

virtual void	rebuild ()=0
	Rebuild the tree after m_triArray or CPUVertexArray have been mutated. More...

void	sample (const Hit &hit, shared_ptr< Surfel > &surfel) const

virtual void	setContents (const Array< shared_ptr< Surface >> &surfaceArray, ImageStorage newImageStorage=ImageStorage::COPY_TO_CPU)=0
	Base class implementation populates m_triArray and m_vertexArray and applies the image storage option. More...

virtual void	setContents (const Array< Tri > &triArray, const CPUVertexArray &vertexArray, ImageStorage newStorage=ImageStorage::COPY_TO_CPU)=0

virtual void	setContents (const shared_ptr< class Scene > &scene, ImageStorage newStorage=ImageStorage::COPY_TO_CPU)=0

int	size () const

const Array< Tri > &	triArray () const

Array< Tri > &	triArray ()
	If you mutate this, you must call rebuild() More...

const CPUVertexArray &	vertexArray () const

CPUVertexArray &	vertexArray ()
	If you mutate this, you must call rebuild() More...

Static Public Member Functions
static shared_ptr< TriTree >	create (bool preferGPUData=true)
	Create an instance of whatever is the fastest implementation subclass for this machine. More...

static shared_ptr< TriTree >	create (const shared_ptr< Scene > &scene, ImageStorage newImageStorage)

Public Attributes
RealTime	debugConversionOverheadTime = 0
	CPU timing of API conversion overhead for the most recent call to intersectRays. More...

Static Public Attributes
static const IntersectRayOptions	COHERENT_RAY_HINT = 16
	Make optimizations appropriate for coherent rays (same origin) More...

static const IntersectRayOptions	DO_NOT_CULL_BACKFACES = 2
	Do not allow the intersector to perform backface culling as an optimization. More...

static const IntersectRayOptions	NO_PARTIAL_COVERAGE_TEST = 8
	Disable partial coverage (alpha) testing. More...

static const IntersectRayOptions	OCCLUSION_TEST_ONLY = 1
	Test for occlusion and do not necessarily return valid triIndex, backfacing, etc. More...

static const IntersectRayOptions	PARTIAL_COVERAGE_THRESHOLD_ZERO = 4
	Only fail the partial coverage (alpha) test on zero coverage. More...

Protected Member Functions
bool	_intersectRay (const Ray &ray, Hit &hit, IntersectRayOptions options) const

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
RealTime	m_lastBuildTime = -1e6

shared_ptr< CubeMap >	m_sky

Array< Tri >	m_triArray

CPUVertexArray	m_vertexArray

Detailed Description

Interface for ray-casting data structures.

See also: G3D::TriTreeBase

Member Typedef Documentation

◆ IntersectRayOptions

typedef unsigned int G3D::TriTree::IntersectRayOptions

Options for intersectRays.

Default is full intersection with no backface culling optimization and partial coverage (alpha) test passing for values over 0.5.

Member Function Documentation

◆ _intersectRay()

bool G3D::TriTree::_intersectRay	(	const Ray &	ray,
		Hit &	hit,
		IntersectRayOptions	options
	)		const

inlineprotected

◆ className()

virtual const String& G3D::TriTree::className ( ) const

pure virtual

Implemented in G3D::NativeTriTree, G3D::VulkanTriTree, and G3D::OptiXTriTree.

◆ clear()

virtual void G3D::TriTree::clear ( )

pure virtual

Implemented in G3D::NativeTriTree, and G3D::TriTreeBase.

◆ create() [1/2]

static shared_ptr<TriTree> G3D::TriTree::create ( bool preferGPUData = true )

static

Create an instance of whatever is the fastest implementation subclass for this machine.

Parameters

preferGPUData If true, use an implementation that is fast for ray buffers already on the GPU.

Referenced by G3D::MeshShape::bspTree().

◆ create() [2/2]

static shared_ptr<TriTree> G3D::TriTree::create	(	const shared_ptr< Scene > &	scene,
		ImageStorage	newImageStorage
	)

static

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ intersectBox()

virtual void G3D::TriTree::intersectBox	(	const AABox &	box,
		Array< Tri > &	results
	)		const

pure virtual

Returns all triangles that lie within the box.

Default implementation tests each triangle in turn (linear time).

Implemented in G3D::NativeTriTree, and G3D::TriTreeBase.

◆ intersectRay() [1/2]

virtual bool G3D::TriTree::intersectRay	(	const Ray &	ray,
		Hit &	hit,
		IntersectRayOptions	options = `IntersectRayOptions(0)`
	)		const

pure virtual

Intersect a single ray.

Return value is hit.triIndex != Hit::NONE for convenience.

Implemented in G3D::NativeTriTree, G3D::VulkanTriTree, and G3D::OptiXTriTree.

Referenced by _intersectRay().

◆ intersectRay() [2/2]

shared_ptr<Surfel> G3D::TriTree::intersectRay ( const Ray & ray ) const

Special single-ray CPU function for simplicity.

This guarantees a hit...it will synthesize a skybox surfel on a miss if the TriTree was created from a Scene, or return a gray skybox surfel otherwise. This is the absolute slowest way to use a TriTree.

◆ intersectRays() [1/7]

virtual void G3D::TriTree::intersectRays	(	const Array< Ray > &	rays,
		Array< Hit > &	results,
		IntersectRayOptions	options = `IntersectRayOptions(0)`
	)		const

pure virtual

Batch ray casting.

The default implementation calls the single-ray version using Thread::runConcurrently.

Implemented in G3D::NativeTriTree, G3D::VulkanTriTree, G3D::OptiXTriTree, and G3D::TriTreeBase.

◆ intersectRays() [2/7]

virtual void G3D::TriTree::intersectRays	(	const Array< Ray > &	rays,
		Array< shared_ptr< Surfel >> &	results,
		IntersectRayOptions	options = `IntersectRayOptions(0)`,
		const Array< float > &	coneBuffer = `Array< float >()`
	)		const

pure virtual

Values in results will be reused if already allocated, which can increase performance.

Implemented in G3D::VulkanTriTree, G3D::OptiXTriTree, and G3D::TriTreeBase.

◆ intersectRays() [3/7]

virtual void G3D::TriTree::intersectRays	(	const shared_ptr< Texture > &	rayOrigin,
		const shared_ptr< Texture > &	rayDirection,
		const shared_ptr< GBuffer > &	results,
		IntersectRayOptions	options = `IntersectRayOptions(0)`,
		const shared_ptr< Texture > &	rayCone = `nullptr`
	)		const

pure virtual

Parameters

rayOrigin	must be RGBA32F() = XYZ, min distance
rayDirection	must be RGBA32F() or RGBA16F() = normalized XYZ, max distance
rayCone	must be null or a single-channel (R-only) texture. If not null, each element is the cosine of the half-angle of the cone about rayDirection that should be used to select a MIP-level at the intersection point. The easy way to compute this for primary rays is to pass the dot products of adjacent pixel ray directions.

The GBuffer and both textures must have the same dimensions.

Reconfigures the GBuffer and writes the following fields:

WS_NORMAL is zero at pixels where the ray misses

All other fields are ignored. The GBuffer may be reallocated with textures in a different format as well.

The base class implementation copies all data to the CPU, invokes the intersectRays overload that accepts CPU data, and then copies all data back to the GPU.

Implemented in G3D::VulkanTriTree, and G3D::TriTreeBase.

◆ intersectRays() [4/7]

virtual void G3D::TriTree::intersectRays	(	const shared_ptr< GLPixelTransferBuffer > &	rayOrigin,
		const shared_ptr< GLPixelTransferBuffer > &	rayDirection,
		const shared_ptr< GLPixelTransferBuffer >	results[5],
		IntersectRayOptions	options = `IntersectRayOptions(0)`,
		const shared_ptr< GLPixelTransferBuffer > &	rayCone = `nullptr`,
		const int	baseMipLevel = `0`,
		const Vector2int32	wavefrontDimensions = `Vector2int32(-1,-1)`,
		const RenderMask	renderMask = `0xFFFFFFFF`
	)		const

pure virtual

Parameters

rayOrigin	must be RGBA32F() = XYZ, min distance
rayDirection	must be RGBA32F() or RGBA16F() = normalized XYZ, max distance
rayCone	must be null or a single-channel (R-only) texture. If not null, each element is the cosine of the half-angle of the cone about rayDirection that should be used to select a MIP-level at the intersection point. The easy way to approximate this for primary rays is to pass: `sqrt(dot(rayDir, adjacentRayDir) * 0.5 + 0.5)`. That is only exact for "square" rays, though, and given the number of approximations involved in both MIP maps and approximating a square pixel footprint with a cone, dropping the square root is also reasonable: `dot(rayDir, adjacentRayDir) * 0.5 + 0.5`.

The GBuffer and all buffers must have the same dimensions.

The GBuffer array must have G3D::GLPixelTransferBuffers with exactly the following semantics and format:

WS_NORMAL is zero at pixels where the ray misses

All other fields are ignored.

The base class implementation copies all data to the CPU, invokes the intersectRays overload that accepts CPU data, and then copies all data back to the GPU.

This is the fastest overload for OptiXTriTree

Only supports the first two bits (0b11 = 3) of renderMask. Reports hits where (renderMask & surface->renderMask() & 3) != 0

Implemented in G3D::VulkanTriTree, G3D::OptiXTriTree, and G3D::TriTreeBase.

◆ intersectRays() [5/7]

virtual void G3D::TriTree::intersectRays	(	const shared_ptr< Texture > &	rayOrigin,
		const shared_ptr< Texture > &	rayDirection,
		const shared_ptr< Texture > &	booleanResults,
		IntersectRayOptions	options = `IntersectRayOptions(0)`
	)		const

pure virtual

Parameters

booleanResults The red channel is nonzero on hit, 0 on miss. Subclasses are free to change the format of the booleanResults texture to whatever is most convenient for them, so make no assumptions other than that it has a red channel.

Implemented in G3D::TriTreeBase.

◆ intersectRays() [6/7]

virtual void G3D::TriTree::intersectRays	(	const shared_ptr< GLPixelTransferBuffer > &	rayOrigin,
		const shared_ptr< GLPixelTransferBuffer > &	rayDirection,
		const shared_ptr< GLPixelTransferBuffer > &	booleanResults,
		IntersectRayOptions	options = `IntersectRayOptions(0)`
	)		const

pure virtual

Parameters

booleanResults The red channel is nonzero on hit, 0 on miss. Subclasses are free to change the format of the booleanResults texture to whatever is most convenient for them, so make no assumptions other than that it has a red channel. This is the fastest overload for OptiXTriTree

Implemented in G3D::VulkanTriTree, G3D::OptiXTriTree, and G3D::TriTreeBase.

◆ intersectRays() [7/7]

virtual void G3D::TriTree::intersectRays	(	const Array< Ray > &	rays,
		Array< bool > &	results,
		IntersectRayOptions	options = `IntersectRayOptions(0)`
	)		const

pure virtual

Implemented in G3D::VulkanTriTree, G3D::OptiXTriTree, and G3D::TriTreeBase.

◆ intersectSphere()

virtual void G3D::TriTree::intersectSphere	(	const Sphere &	sphere,
		Array< Tri > &	triArray
	)		const

pure virtual

Returns all triangles that intersect or are contained within the sphere (technically, this is a ball intersection).

Default implementation calls intersectBox and then filters the results for the sphere.

Implemented in G3D::NativeTriTree, and G3D::TriTreeBase.

◆ lastBuildTime()

RealTime G3D::TriTree::lastBuildTime ( ) const

inline

Time at which setContents() or rebuild() was last invoked.

◆ operator[]()

const Tri& G3D::TriTree::operator[] ( int i ) const

inline

Array access to the stored Tris.

◆ rebuild()

virtual void G3D::TriTree::rebuild ( )

pure virtual

Rebuild the tree after m_triArray or CPUVertexArray have been mutated.

Called automatically by setContents()

Implemented in G3D::NativeTriTree, and G3D::VulkanTriTree.

◆ sample()

void G3D::TriTree::sample	(	const Hit &	hit,
		shared_ptr< Surfel > &	surfel
	)		const

◆ setContents() [1/3]

virtual void G3D::TriTree::setContents	(	const Array< shared_ptr< Surface >> &	surfaceArray,
		ImageStorage	newImageStorage = `ImageStorage::COPY_TO_CPU`
	)

pure virtual

Base class implementation populates m_triArray and m_vertexArray and applies the image storage option.

Implemented in G3D::TriTreeBase.

◆ setContents() [2/3]

virtual void G3D::TriTree::setContents	(	const Array< Tri > &	triArray,
		const CPUVertexArray &	vertexArray,
		ImageStorage	newStorage = `ImageStorage::COPY_TO_CPU`
	)

pure virtual

Implemented in G3D::VulkanTriTree, G3D::OptiXTriTree, and G3D::TriTreeBase.

◆ setContents() [3/3]

virtual void G3D::TriTree::setContents	(	const shared_ptr< class Scene > &	scene,
		ImageStorage	newStorage = `ImageStorage::COPY_TO_CPU`
	)

pure virtual

Implemented in G3D::TriTreeBase.

◆ size()

int G3D::TriTree::size ( ) const

inline

◆ triArray() [1/2]

const Array<Tri>& G3D::TriTree::triArray ( ) const

inline

◆ triArray() [2/2]

Array<Tri>& G3D::TriTree::triArray ( )

inline

If you mutate this, you must call rebuild()

◆ vertexArray() [1/2]

const CPUVertexArray& G3D::TriTree::vertexArray ( ) const

inline

◆ vertexArray() [2/2]

CPUVertexArray& G3D::TriTree::vertexArray ( )

inline

If you mutate this, you must call rebuild()

Member Data Documentation

◆ COHERENT_RAY_HINT

const IntersectRayOptions G3D::TriTree::COHERENT_RAY_HINT = 16

static

Make optimizations appropriate for coherent rays (same origin)

◆ debugConversionOverheadTime

RealTime G3D::TriTree::debugConversionOverheadTime = 0

mutable

CPU timing of API conversion overhead for the most recent call to intersectRays.

◆ DO_NOT_CULL_BACKFACES

const IntersectRayOptions G3D::TriTree::DO_NOT_CULL_BACKFACES = 2

static

Do not allow the intersector to perform backface culling as an optimization.

Backface culling is not required in any case.

◆ m_lastBuildTime

RealTime G3D::TriTree::m_lastBuildTime = -1e6

protected

Referenced by lastBuildTime().

◆ m_sky

shared_ptr<CubeMap> G3D::TriTree::m_sky

protected

◆ m_triArray

Array<Tri> G3D::TriTree::m_triArray

protected

Referenced by operator[](), size(), and triArray().

◆ m_vertexArray

CPUVertexArray G3D::TriTree::m_vertexArray

protected

Referenced by vertexArray().

◆ NO_PARTIAL_COVERAGE_TEST

const IntersectRayOptions G3D::TriTree::NO_PARTIAL_COVERAGE_TEST = 8

static

Disable partial coverage (alpha) testing.

◆ OCCLUSION_TEST_ONLY

const IntersectRayOptions G3D::TriTree::OCCLUSION_TEST_ONLY = 1

static

Test for occlusion and do not necessarily return valid triIndex, backfacing, etc.

data (useful for shadow rays and testing line of sight)

◆ PARTIAL_COVERAGE_THRESHOLD_ZERO

const IntersectRayOptions G3D::TriTree::PARTIAL_COVERAGE_THRESHOLD_ZERO = 4

static

Only fail the partial coverage (alpha) test on zero coverage.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ IntersectRayOptions

Member Function Documentation

◆ _intersectRay()

◆ className()

◆ clear()

◆ create() [1/2]

◆ create() [2/2]

◆ createShared()

◆ intersectBox()

◆ intersectRay() [1/2]

◆ intersectRay() [2/2]

◆ intersectRays() [1/7]

◆ intersectRays() [2/7]

◆ intersectRays() [3/7]

◆ intersectRays() [4/7]

◆ intersectRays() [5/7]

◆ intersectRays() [6/7]

◆ intersectRays() [7/7]

◆ intersectSphere()

◆ lastBuildTime()

◆ operator[]()

◆ rebuild()

◆ sample()

◆ setContents() [1/3]

◆ setContents() [2/3]

◆ setContents() [3/3]

◆ size()

◆ triArray() [1/2]

◆ triArray() [2/2]

◆ vertexArray() [1/2]

◆ vertexArray() [2/2]

Member Data Documentation

◆ COHERENT_RAY_HINT

◆ debugConversionOverheadTime

◆ DO_NOT_CULL_BACKFACES

◆ m_lastBuildTime

◆ m_sky

◆ m_triArray

◆ m_vertexArray

◆ NO_PARTIAL_COVERAGE_TEST

◆ OCCLUSION_TEST_ONLY

◆ PARTIAL_COVERAGE_THRESHOLD_ZERO