KDTreeBuildAlloc

Builds k-D tree for triangles.

Syntax

IppStatus ipprKDTreeBuildAlloc(IpprKDTreeNode** pDstKDTree, const Ipp32f* const pSrcVert, const Ipp32s* const pSrcTriInx, Ipp32s srcVertSize, Ipp32s srcTriSize, Ipp32s* pDstKDTreeSize, const void* const pBldContext);

Parameters

ppDstKDTree	Pointer to the pointer to the built k-D tree.
pSrcVert	Pointer to the array of the scene element vertexes.
pSrcTriInx	Pointer to the array of indexed scene element triangles.
srcVertSize	Size of the array of vertexes.
srcTriSize	Size of the array of triangles.
pDstKDTreeSize	Pointer to the size of the built tree.
pBldContext	Pointer to the structure that specifies the building algorithm and algorithm-specific parameters.

Description

The function ipprKDTreeBuildAlloc is declared in the ippr.h file. This function allocates memory and builds the k-D tree for the set of triangles. The function uses one of the predefined construction algorithms controlled by the service parameters via the parameter pBldContext. This parameter points to structure of IpprSmplBldContext or IpprPSAHBldContext type (see Structures and Enumerators for more details).

Passing argument of type IpprSmplBldContext with first element Alg set to ippKDTBuildSimple constant causes simple tree construction algorithm. This algorithm is useful for testing purposes only. It builds single-leafed tree with all triangles associated with this leaf. Passing argument of IpprPSAHBldContext with first element Alg set to ippKDTBuildPureSAH constant causes SAH-based tree construction controlled by other structure parameters. See their detailed description in Structures and Enumerators.

Due to the algorithm specific implementation, initial memory allocation for SAH-based tree building cannot be less than 80Mb even for very small scenes, this limits a minimal useful value of the AvailMemory by 81Mb.

It is possible to specify cut-off bounding box that does not enclose all triangles specified by the parameter pSrcTriInx. In this case, k-D tree is built only for specified sub-volume, and output tree leaves contain only indexes to triangles intersected by this sub-volume.

The code example demonstrates how to use this function.

Return Values

ippStsNoErr	Indicates no error. Any other value indicates an error or a warning.
ippStsNullPtrErr	Indicates an error if one of the specified pointers is `NULL`.
ippStsSizeErr	Indicates an error if one of the arrays has negative size.
ippStsOutOfRangeErr	Indicates an error if QoS is out of the range [0.0, 1.0], or MaxDepth is out of the range [0, 50].
ippStsNoMemErr	Indicates an error if there is not enough memory during initial allocation.
ippStsNoMemAllocErr	Indicates an error if there is not enough memory for the actual tree building.
ippStsBadArgErr	Indicates an error if the algorithm type is not valid.
ippStsErr	Indicates an internal algorithm error.