Structures and Enumerators

This section describes the structures and enumerators used by the Intel Integrated Performance Primitives for realistic rendering.

The enumerator IpprIndexType is used by the function ipprSurfSmoothNormal and specifies the index type that indicates how to access to the array of normals.

typedef enum {

    ippNormInd = 3,
    ippTriInd  = 4;
} IpprIndexType;

The structure IpprIntersectContext for representing an intersection context that is used by the intersection engine functions is defined as

typedef struct IntersectContext{
    IppBox3D_32f        *pBound;
    IpprTriangleAccel   *pAccel;
    IpprKDTreeNode      *pRootNode;
}IpprIntersectContext;

where

pBound is a pointer to the axis aligned bounding box of current object; pAccel is a pointer to triangle acceleration structure; and pRootNode is a pointer to the root node of the KD-tree.

The following structures are used by the function ipprKDTreeBuildAlloc.

The structure IpprKDTreeNode for representing a KD-tree node is defined as

typedef struct KDTreeNode{
    Ipp32s  flag_k_ofs;
    union _tree_data{
        Ipp32f  split;
        Ipp32s  items;
    }tree_data;
}IpprKDTreeNode;

The structure IpprKDTreeBuildAlg for tree building algorithm identifiers is defined as

typedef enum {
    ippKDTBuildSimple    = 0x499d3dc2,  // Simple building mode
    ippKDTBuildPureSAH   = 0x2d07705b   // SAH building mode
}IpprKDTreeBuildAlg;

The structure IpprSmplBldContext for setting a simple building mode is defined as

typedef struct SimpleBuilderContext{
    IpprKDTreeBuildAlg   Alg;
    Ipp32s               MaxDepth;
}IpprSmplBldContext;

where

Alg must be equal to ippKDTBuildSimple constant;

MaxDepth is reserved.

The structure IpprPSAHBuilderContext for setting a simple building mode is defined as

typedef struct PSAHBuilderContext{
    IpprKDTreeBuildAlg   Alg;
    Ipp32s               MaxDepth;
    Ipp32f               QoS;         
    Ipp32s               AvailMemory; 
    IppBox3D_32f        *Bounds;      
}IpprPSAHBldContext;

where

Alg must be equal to ippKDTBuildPureSAH constant;

MaxDepth is a maximum tree subdivision depth (minimum - 0, maximum - 50);

QoS is a termination criteria modifier (minimum - 0.0, maximum - 1.0);

AvailMemory is a maximum available memory in Mb;

*Bounds is a cut-off bounding box.

Advanced KD-tree building algorithm (ippKDTBuildPureSAH) is based on recursive subspace subdivision according to surface area heuristic (SAH). Recursive subdivision of leaf nodes is made according to the criterion: best SAH cost after split is less than original SAH cost of the leaf plus cost of split. An initial leaf node contains triangles having non-empty intersection with the volume contained in bounding box referenced by the Bounds field. The cost of split depends on QoS field, the higher QoS, the lower the cost of split. In general KD-trees with higher QoS tend to be deeper but more efficient. Additional constraint of the maximal KD-tree depth is defined by the MaxDepth field.

During KD-tree construction, additional memory is allocated on demand for internal structures in chunks up to the limit defined by the AvailMemory field. Actual allocation might be significantly lower than AvailMemory. If demand exceeds this limit, ippStsMemAllocErr error is returned. Setting AvailMemory size incorrectly may result in crash because no additional checks for memory allocation errors are performed during actual allocation. All internally used memory is freed at the end of the build after KD-tree is packed to the compact format. Since it’s impossible to accurately estimate the size of the resulting KD-tree, the best practice is to specify this parameter to the half of the total available memory for a single KD-tree build. In this case you make sure that the resulting tree fits in available memory together with all data needed for construction. For simultaneous KD-trees building in multiple threads you need to adjust the AvailMemory limit to match your hardware. If you use larger number of threads to process complex models, you must to reduce this constant.

The following structures are used by the functions for 3D data processing.

The structure IpprVolume for storing the size of a cuboid is defined as

typedef struct {
    int width;
    int height;
    int depth;
} IpprVolume;

where width , height, and depth denote the dimensions of the rectangle in the x-, y- and z directions, respectively.

The structure IpprCuboid for storing the geometric position and size of a cuboid is defined as

typedef struct {
    int x;
    int y;
    int z;
    int width;
    int height;
    int depth;
} IpprCuboid;

where x, y, z denote the coordinates of the top left corner of the cuboid that has dimensions width in the x-direction, height in the y-direction, and depth in the z-direction.

The structure IpprPoint for storing the geometric position of a point is defined as

typedef struct {
    int x;
    int y;
    int z;
} IpprPoint;

where x, y, and z denote the coordinates of the point.

The structure IpprSHType for selecting the algorithm used in the spherical harmonic transforms is defined as

typedef enum_IpprSHType {
    ipprSHNormDirect=0,
    ipprSHNormRecurr
} IpprSHType;

where ipprSHNormDirect specifies direct algorithm to compute normalized spherical harmonics, ipprSHNormRecurr specifies recurrent algorithm to compute normalized spherical harmonics.