The librt Ray Tracing Pipeline

librt computes ray/geometry intersections against BRL-CAD’s constructive solid geometry (CSG) models. Unlike a surface-only renderer, it reports in/out pairs of hits so that closed volumes can be characterized correctly, and it evaluates the Boolean combination trees (union, intersection, subtraction) that define regions. The result of shooting a ray is a set of partitions, each describing a span of the ray that lies inside one region.

A typical ray tracing session follows four phases:

The following sections walk through each phase. The central data structures are struct rt_i (the ray tracing instance, declared in include/rt/rt_instance.h) and struct application (the per-ray request, declared in include/rt/application.h).

rt_dirbuild() (declared in include/rt/db_io.h) opens a .g geometry database and reads its object directory, returning a pointer to a newly allocated struct rt_i. This rt_i instance is the handle you pass to the rest of the pipeline; the pointer it returns becomes the a_rt_i field of your application structure.

If the database cannot be opened, rt_dirbuild() returns RTI_NULL. A companion entry point, rt_dirbuild_inmem(), builds an instance from an in-memory database image rather than a file.

Opening the database makes its objects available but does not yet load any geometry for ray tracing. To select which objects participate, call rt_gettree() (declared in include/rt/rt_instance.h) once per top-level object you want to trace against. It walks the named object’s combination tree, imports the referenced primitives, and associates them with the rt_i instance.

Related entry points give you more control:

These functions determine the set of solids (primitives) and regions that subsequent rays will intersect.

Before any ray can be shot, the loaded geometry must be prepped. Preparation computes each primitive’s bounding information and builds the spatial acceleration structure (the space partitioning used to quickly reject geometry a ray cannot possibly hit).

The rt_i instance tracks whether preparation is required via its needprep field. In practice, rt_shootray() will trigger preparation automatically if it has not yet been done, but calling rt_prep() (or rt_prep_parallel()) explicitly lets you control when this potentially expensive step happens, and is required when tracing in parallel so that the acceleration structures are ready before multiple threads begin shooting.

struct application is the single parameter to rt_shootray(). It carries the ray to shoot, the callbacks to invoke, the instance to trace against, and a number of application-specific fields. Always initialize it with the RT_APPLICATION_INIT() macro before setting fields, so that reserved sanity fields are zeroed.

The mandatory fields are:

Other commonly used fields include a_resource (per-CPU resources, required for multithreaded tracing), a_onehit (stop after the first hit), a_level and a_x/a_y (bookkeeping used in logging), and the application-specific a_uptr, a_color, and a_user fields, which the library never touches and which you can use to carry your own state into the callbacks. See include/rt/application.h for the complete, authoritative field list.

rt_shootray() (declared in include/rt/shoot.h) takes a fully populated struct application and intersects a_ray against the prepped geometry. Internally it traverses the space partitioning acceleration structure, intersects candidate primitives to produce *segments (struct seg, in include/rt/seg.h), and evaluates the region Boolean trees to produce partitions (struct partition, in include/rt/ray_partition.h).

rt_shootray() then dispatches to exactly one of your callbacks and returns the value that callback placed in a_return.

The library also provides related shooting entry points, including rt_shootrays() for ray bundles (see struct application_bundle) and rt_shootray_simple(), but rt_shootray() is the fundamental operation.

When two regions claim the same span of a ray, the geometry overlaps. librt resolves overlaps through the a_multioverlap callback and reports them through a_logoverlap; a default implementation is provided if you do not supply your own. Overlaps usually indicate a modeling error, and the reporting hooks let tools surface them to the user.

For multithreaded tracing, each CPU needs its own struct resource (declared in include/rt/resource.h), assigned to a_resource, so that per-ray scratch memory is not shared across threads. Prepare the instance with rt_prep_parallel() before launching worker threads, give each thread its own application structure and resource, and let each call rt_shootray() independently.

When you are finished, release the resources associated with the instance. rt_clean() returns an rt_i to a pre-gettree state so it can be reused, and the resource-cleanup entry points (for example, rt_clean_resource_basic()) release per-CPU resources. See include/rt/rt_instance.h for the current, non-deprecated cleanup functions.

For generated API documentation covering these headers, build and consult the API Reference.