API Reference

Data types

In order to simplify the usage of blazeRT we have introduced type aliases for blaze vector and matrix types which can be seen below. In order to have a smooth coding experience, we suggest to use these type aliases.

Vector types

using blazert::Vec3r = blaze::StaticVector<T, 3UL, blaze::columnVector, A_, P_>

3D vector of type T

using blazert::Vec2r = blaze::StaticVector<T, 2UL, blaze::columnVector, A_, P_>

2D vector of type T.

using blazert::Vec3ui = blaze::StaticVector<unsigned int, 3UL, blaze::columnVector, A_, P_>

3D vector of type unsigned int.

using blazert::Vec2ui = blaze::StaticVector<unsigned int, 2UL, blaze::columnVector, A_, P_>

2D vector of type unsigned int.

Matrix types

using blazert::Mat3r = blaze::StaticMatrix<T, 3UL, 3UL, blaze::rowMajor, A_, P_>

3x3 matrix of type T.

Container types

Note

If you define lists of vectors or matrices, you should use the following container aliases.

using blazert::Vec3rList = std::vector<Vec3r<T>, blaze::AlignedAllocator<Vec3r<T>>>

std::vector with Vec3r<T> and blaze allocator for aligned allocation.

using blazert::Vec3iList = std::vector<Vec3ui, blaze::AlignedAllocator<Vec3ui>>

std::vector with Vec3ui and blaze allocator for aligned allocation.

using blazert::Mat3rList = std::vector<Mat3r<T>, blaze::AlignedAllocator<Mat3r<T>>>

std::vector with Mat3r<T> and blaze allocator for aligned allocation.

BlazertScene

template<typename T>
class blazert::BlazertScene

BlazertScene provides the high-level interface for ray tracing with blazert.

BlazertScene is responsible for the entire ray tracing process. It provides measures to add different geometry types. Furthermore, it encapsulates the BVH for each geometry type. Parametrization is available for the floating point precision type. This is useful for scientific applications.

Note

This API is considered to be stable.

Template Parameters

  • T: floating point type

Public Functions

unsigned int add_mesh(const Vec3rList<T> &vertices, const Vec3iList &triangles)

Adds a triangular mesh to the scene.

A triangular mesh can be used to describe any geometry. The mesh is described by vertices and a list of triangles which describe which vertices form a triangle. The prim_id is set in the rayhit structure by the intersection functions.

Return

geometry id for the mesh.

Note

vertices and triangles need to be allocated on the heap.

Parameters

  • vertices: Vertices need to be allocated on the heap!

  • triangles: Triangles need to be allocated on the heap!

unsigned int add_spheres(const Vec3rList<T> &centers, const std::vector<T> &radii)

Adds spheres at centers with radii.

The spheres are described by centers and radii. For \(N\) spheres, each of these vectors needs to have \(N\) entries describing the corresponding sphere’s center and radius.

The prim_id is set in the rayhit structure by the intersection functions.

Return

geometry id of the spheres

Note

centers and radii need to be allocated on the heap.

Note

centers and spheres should be of the same length.

Parameters

  • centers: specifies centers of the spheres (needs to be allocated on heap)

  • radii: specifies radii of the spheres (needs to be allocated on heap)

unsigned int add_planes(const Vec3rList<T> &centers, const std::vector<T> &dxs, const std::vector<T> &dys, const Mat3rList<T> &rotations)

Adds planes at centers with dimensions dxs and dys rotated around rotations.

The planes are described by centers, dimensions in x and y direction as well as rotation matrices. For \(N\) planes, each of these vectors needs to have \(N\) entries describing the corresponding planes’ centers, dimensions in x and y direction and rotation matrices.

The prim_id is set in the rayhit structure by the intersection functions.

Return

geometry id of the planes

Note

centers, dxy, dys, and rotations need to be allocated on the heap.

Note

centers, dxy, dys, and rotations should be of the same length.

Parameters

  • centers: center of planes

  • dxs: dimensions in x direction

  • dys: dimensions in y direction

  • rotations: local rotation matrices

unsigned int add_cylinders(const Vec3rList<T> &centers, const std::vector<T> &semi_axes_a, const std::vector<T> &semi_axes_b, const std::vector<T> &heights, const Mat3rList<T> &rotations)

Adds cylinders at centers, described by two semi_axes and heights.

The cylinders are described by their centers, two semi-axes describing the ellipoidal shape of the top and bottom their height and rotations. For \(N\) planes, each of these vectors needs to have \(N\) entries describing the corresponding cylinderes’ centers, dimensions in x and y direction and rotation matrices.

The prim_id is set in the rayhit structure by the intersection functions.

Return

geometry id of the cylinders

Note

centers, dxy, dys, and rotations need to be allocated on the heap.

Note

centers, dxy, dys, and rotations should be of the same length.

Parameters

  • centers: centers of the cylinders

  • semi_axes_a: semi-axes in x-direction

  • semi_axes_b: semi-axes in y-direction

  • heights: heights of the cylinders

  • rotations: rotation matrices

inline bool commit()

Commits the scene and builds BVH for each geometry type.

It is necessary to run this function before running the intersect functions. The bounding volume hierarchy is built for each geometry type present in the scene.

Return

returns true if scene has been committed

template<typename T>
inline bool blazert::intersect1(const BlazertScene<T> &scene, const Ray<T> &ray, RayHit<T> &rayhit)

Runs intersection tests for a given BlazertScene and Ray.

intersect1 runs intersection test for 1 ray with the given scene. Thus, the BVH for each individual geometry is traversed until a hit is found.

Return

True if a hit is found, otherwise false

Template Parameters

  • T: floating point type, which is usually float or double, but in the future, quadruple precision might be useful

Parameters

  • scene: BlazertScene against which the ray is tested.

  • ray: The Ray is used for the intersection testing.

  • rayhit: RayHit structure to save the intersection data in.

Ray & RayHit

template<typename T>
class blazert::Ray

Ray<T> defines a ray for the ray tracing.

Template Parameters

  • T: floating point type

Public Functions

inline Ray(const Vec3r<T> &origin, const Vec3r<T> &direction, T min_hit_distance = T(0.), T max_hit_distance = std::numeric_limits<T>::max(), CullBackFace cull_back_face = CullBackFace::no, AnyHit any_hit = AnyHit::no)

Constructor for a Ray<T> to be used in ray tracing.

A lot of additional information is calculated in the constructor which is of interest in the build or traversal of the BVH.

Todo:

backface culling is no implemented yet.

Parameters

  • origin: Starting point from where the ray is launched.

  • direction: Dircetion in which the ray is launched.

  • min_hit_distance: Minimum length the ray needs to have (default = 0).

  • max_hit_distance: Maximum length the ray can have (default = std::numeric_limits<T>::max()).

  • cull_back_face: If set to blazert::Ray<T>::CullBackFace::yes, culling backfaces will be used (default = no).

  • any_hit: If set to blazert::Ray<T>::AnyHit::yes, the first hit found in the traversal will register as the hit, which might not be the hit (default = no) closest to the ray origin.

template<typename T>
struct blazert::RayHit

RayHit structure holds information about an intersection between a ray and an object.

Template Parameters

  • T: floating point type

Public Members

Vec3r<T> normal

normal vector on surface at the intersection point

Vec2r<T> uv

uv coordinates

T hit_distance = std::numeric_limits<T>::max()

distance between ray origin and the intersection point

unsigned int prim_id = static_cast<unsigned int>(-1)

primitive id of the hit object (= which exact primitive was it)

unsigned int geom_id = static_cast<unsigned int>(-1)

geometry id of the hit object (= which kind of geometry was it, e.g. sphere, triangle)