Common partial implementation base class for ray-casting data structures. More...

Inherited by G3D::NativeTriTree, G3D::OptiXTriTree, and G3D::VulkanTriTree.

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

Public Member Functions
virtual	~TriTreeBase ()

virtual const String &	className () const =0

virtual void	clear () override

virtual void	intersectBox (const AABox &box, Array< Tri > &results) const override
	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 override
	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 override
	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 override

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 mask=0xFF) const override

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

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

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

virtual void	intersectSphere (const Sphere &sphere, Array< Tri > &triArray) const override
	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) override
	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) override

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

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
static void	copyToCPU (const shared_ptr< GLPixelTransferBuffer > &rayOrigin, const shared_ptr< GLPixelTransferBuffer > &rayDirection, Array< Ray > &rayBuffer, const int width=-1, const int height=-1)

static void	copyToCPU (const shared_ptr< GLPixelTransferBuffer > &rayCoherence, Array< float > &rayCoherenceBuffer)

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

Common partial implementation base class for ray-casting data structures.

Member Typedef Documentation

◆ IntersectRayOptions

typedef unsigned int G3D::TriTree::IntersectRayOptions

inherited

Options for intersectRays.

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

Constructor & Destructor Documentation

◆ ~TriTreeBase()

virtual G3D::TriTreeBase::~TriTreeBase ( )

virtual

Member Function Documentation

◆ _intersectRay()

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

inlineprotectedinherited

◆ className()

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

pure virtualinherited

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

◆ clear()

virtual void G3D::TriTreeBase::clear ( )

overridevirtual

Implements G3D::TriTree.

Reimplemented in G3D::NativeTriTree.

◆ copyToCPU() [1/2]

static void G3D::TriTreeBase::copyToCPU	(	const shared_ptr< GLPixelTransferBuffer > &	rayOrigin,
		const shared_ptr< GLPixelTransferBuffer > &	rayDirection,
		Array< Ray > &	rayBuffer,
		const int	width = `-1`,
		const int	height = `-1`
	)

staticprotected

◆ copyToCPU() [2/2]

static void G3D::TriTreeBase::copyToCPU	(	const shared_ptr< GLPixelTransferBuffer > &	rayCoherence,
		Array< float > &	rayCoherenceBuffer
	)

staticprotected

◆ create() [1/2]

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

staticinherited

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
	)

staticinherited

◆ 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::TriTreeBase::intersectBox	(	const AABox &	box,
		Array< Tri > &	results
	)		const

overridevirtual

Returns all triangles that lie within the box.

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

Implements G3D::TriTree.

Reimplemented in G3D::NativeTriTree.

◆ intersectRay() [1/2]

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

pure virtualinherited

Intersect a single ray.

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

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

Referenced by G3D::TriTree::_intersectRay().

◆ intersectRay() [2/2]

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

inherited

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::TriTreeBase::intersectRays	(	const Array< Ray > &	rays,
		Array< Hit > &	results,
		IntersectRayOptions	options = `IntersectRayOptions(0)`
	)		const

overridevirtual

Batch ray casting.

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

Implements G3D::TriTree.

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

◆ intersectRays() [2/7]

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

overridevirtual

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

Implements G3D::TriTree.

Reimplemented in G3D::VulkanTriTree, and G3D::OptiXTriTree.

◆ intersectRays() [3/7]

virtual void G3D::TriTreeBase::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

overridevirtual

Deprecated:

Implements G3D::TriTree.

Reimplemented in G3D::VulkanTriTree.

◆ intersectRays() [4/7]

virtual void G3D::TriTreeBase::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 = `0xFF`
	)		const

overridevirtual

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

Implements G3D::TriTree.

Reimplemented in G3D::VulkanTriTree, and G3D::OptiXTriTree.

◆ intersectRays() [5/7]

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

overridevirtual

Deprecated:

Implements G3D::TriTree.

◆ intersectRays() [6/7]

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

overridevirtual

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

Implements G3D::TriTree.

Reimplemented in G3D::VulkanTriTree, and G3D::OptiXTriTree.

◆ intersectRays() [7/7]

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

overridevirtual

Implements G3D::TriTree.

Reimplemented in G3D::VulkanTriTree, and G3D::OptiXTriTree.

◆ intersectSphere()

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

overridevirtual

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.

Implements G3D::TriTree.

Reimplemented in G3D::NativeTriTree.

◆ lastBuildTime()

RealTime G3D::TriTree::lastBuildTime ( ) const

inlineinherited

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

◆ operator[]()

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

inlineinherited

Array access to the stored Tris.

◆ rebuild()

virtual void G3D::TriTree::rebuild ( )

pure virtualinherited

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

inherited

◆ setContents() [1/3]

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

overridevirtual

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

Implements G3D::TriTree.

◆ setContents() [2/3]

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

overridevirtual

Implements G3D::TriTree.

Reimplemented in G3D::VulkanTriTree, and G3D::OptiXTriTree.

◆ setContents() [3/3]

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

overridevirtual

Implements G3D::TriTree.

◆ size()

int G3D::TriTree::size ( ) const

inlineinherited

◆ triArray() [1/2]

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

inlineinherited

◆ triArray() [2/2]

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

inlineinherited

If you mutate this, you must call rebuild()

◆ vertexArray() [1/2]

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

inlineinherited

◆ vertexArray() [2/2]

CPUVertexArray& G3D::TriTree::vertexArray ( )

inlineinherited

If you mutate this, you must call rebuild()

Member Data Documentation

◆ COHERENT_RAY_HINT

const IntersectRayOptions G3D::TriTree::COHERENT_RAY_HINT = 16

staticinherited

Make optimizations appropriate for coherent rays (same origin)

◆ debugConversionOverheadTime

RealTime G3D::TriTree::debugConversionOverheadTime = 0

mutableinherited

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

staticinherited

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

protectedinherited

Referenced by G3D::TriTree::lastBuildTime().

◆ m_sky

shared_ptr<CubeMap> G3D::TriTree::m_sky

protectedinherited

◆ m_triArray

Array<Tri> G3D::TriTree::m_triArray

protectedinherited

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

◆ m_vertexArray

CPUVertexArray G3D::TriTree::m_vertexArray

protectedinherited

Referenced by G3D::TriTree::vertexArray().

◆ NO_PARTIAL_COVERAGE_TEST

const IntersectRayOptions G3D::TriTree::NO_PARTIAL_COVERAGE_TEST = 8

staticinherited

Disable partial coverage (alpha) testing.

◆ OCCLUSION_TEST_ONLY

const IntersectRayOptions G3D::TriTree::OCCLUSION_TEST_ONLY = 1

staticinherited

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

staticinherited

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

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

Constructor & Destructor Documentation

◆ ~TriTreeBase()

Member Function Documentation

◆ _intersectRay()

◆ className()

◆ clear()

◆ copyToCPU() [1/2]

◆ copyToCPU() [2/2]

◆ 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