Shoot Rays

Ray Tracing program shot coordinator. This is the heart of LIBRT's ray-tracing capability. More...

Collaboration diagram for Shoot Rays:

Modules
	The Application Structure
	This structure is the only parameter to rt_shootray() and holds information about how the ray-casting should be performed.
	The Raytracing Instance
	The "raytrace instance" structure contains definitions for librt which are specific to the particular model being processed.
	The Resource Structure
	Per-CPU statistics and resources.
	The Ray Structure
	All necessary information about a ray.
	The Hit Structure
	Information about where a ray hits the surface.
	The Segment Structure
	Intersection segment.
	The Partition Structure
	Partitions of a ray.

Files
file	shoot.h

Functions
int	rt_shootray (struct application *ap)
	Shoot a ray. More...
int	rt_shootrays (struct application_bundle *bundle)
	Shoot a bundle of rays. More...
struct partition *	rt_shootray_simple (struct application *ap, point_t origin, vect_t direction)
int	rt_shootray_bundle (struct application *ap, struct xray *rays, int nrays)
void	rt_add_res_stats (struct rt_i *rtip, struct resource *resp)
void	rt_zero_res_stats (struct resource *resp)
void	rt_res_pieces_clean (struct resource *resp, struct rt_i *rtip)
void	rt_res_pieces_init (struct resource *resp, struct rt_i *rtip)
void	rt_vstub (struct soltab *stp[], struct xray *rp[], struct seg segp[], int n, struct application *ap)

Detailed Description

Ray Tracing program shot coordinator. This is the heart of LIBRT's ray-tracing capability.

Given a ray, shoot it at all the relevant parts of the model, (building the finished_segs chain), and then call rt_boolregions() to build and evaluate the partition chain. If the ray actually hit anything, call the application's a_hit() routine with a pointer to the partition chain, otherwise, call the application's a_miss() routine.

It is important to note that rays extend infinitely only in the positive direction. The ray is composed of all points P, where

P = r_pt + K * r_dir

for K ranging from 0 to +infinity. There is no looking backwards.

Function Documentation

rt_shootray()

int rt_shootray

(

struct application *

ap

)

Shoot a ray.

Note that the direction vector r_dir must have unit length; this is mandatory, and is not ordinarily checked, in the name of efficiency.

Input: Pointer to an application structure, with these mandatory fields: a_ray.r_pt ==> Starting point of ray to be fired a_ray.r_dir => UNIT VECTOR with direction to fire in (dir cosines) a_hit =======> Routine to call when something is hit a_miss ======> Routine to call when ray misses everything

Calls user's a_miss() or a_hit() routine as appropriate passing a_hit() a list of partitions intersected. Note that only the hit_dist elements of pt_inhit and pt_outhit are computed. To compute both hit_point and hit_normal, use:

RT_HIT_NORMAL(NULL, hitp, stp, rayp, 0);

To compute just the hit_point, use:

VJOIN1(hitp->hit_point, rp->r_pt, hitp->hit_dist, rp->r_dir);

These calculations are deferred to user code to avoid needless computation in other ray situations.

Formal Return: whatever the application function returns (an int).

NOTE: The application functions may call rt_shootray() recursively. Thus, none of the local variables may be static.

To prevent having to lock the statistics variables in a PARALLEL environment, all the statistics variables have been moved into the 'resource' structure, which is allocated per-CPU.

rt_shootrays()

int rt_shootrays

(

struct application_bundle *

bundle

)

Shoot a bundle of rays.

Function for shooting a bundle of rays. Iteratively walks list of rays contained in the application bundles xrays field 'b_rays' passing each single ray to r_shootray().

Input:

bundle - Pointer to an application_bundle structure.

b_ap - Members in this single ray application structure should be set in a similar fashion as when used with rt_shootray() with the exception of a_hit() and a_miss(). Default implementations of these routines are provided that simple update hit/miss counters and attach the hit partitions and segments to the partition_bundle structure. Users can still override this default functionality but have to make sure to move the partition and segment list to the new partition_bundle structure.

b_hit() Routine to call when something is hit by the ray bundle.

b_miss() Routine to call when ray bundle misses everything.

rt_shootray_simple()

struct partition* rt_shootray_simple	(	struct application *	ap,
		point_t	origin,
		vect_t	direction
	)

Shoot a single ray and return the partition list. Handles callback issues.

Note that it calls malloc(), therefore should NOT be used if performance matters.

rt_shootray_bundle()

int rt_shootray_bundle	(	struct application *	ap,
		struct xray *	rays,
		int	nrays
	)

PRIVATE: this is new API and should be considered private for the time being.

rt_add_res_stats()

void rt_add_res_stats	(	struct rt_i *	rtip,
		struct resource *	resp
	)

To be called only in non-parallel mode, to tally up the statistics from the resource structure(s) into the rt instance structure.

Non-parallel programs should call rt_add_res_stats(rtip, RESOURCE_NULL); to have the default resource results tallied in.

rt_zero_res_stats()

void rt_zero_res_stats

(

struct resource *

resp

)

Tally stats into struct rt_i

rt_res_pieces_clean()

void rt_res_pieces_clean	(	struct resource *	resp,
		struct rt_i *	rtip
	)

rt_res_pieces_init()

void rt_res_pieces_init	(	struct resource *	resp,
		struct rt_i *	rtip
	)

Allocate the per-processor state variables needed to support rt_shootray()'s use of 'solid pieces'.

rt_vstub()

void rt_vstub	(	struct soltab *	stp[],
		struct xray *	rp[],
		struct seg	segp[],
		int	n,
		struct application *	ap
	)