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

Macros
#define	RT_GEN_OBJ_PNTS_SURF   0x1
	save only the first and last hit point on a ray
#define	RT_GEN_OBJ_PNTS_GRID   0x2
	sample using an XYZ grid based on the bounding box (default if no method flags are specified)
#define	RT_GEN_OBJ_PNTS_RAND   0x4
	sample using Marsaglia sampling on the bounding sphere with pseudo random numbers
#define	RT_GEN_OBJ_PNTS_SOBOL   0x8
	sample using Marsaglia sampling on the bounding sphere with Sobol' low-discrepancy-sequence generation

Functions
int	rt_shootray (struct application *ap)
	Shoot a ray.
int	rt_shootrays (struct application_bundle *bundle)
	Shoot a bundle of rays.
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)
int	rt_gen_obj_pnts (struct rt_pnts_internal *rpnts, fastf_t *avg_thickness, struct db_i *dbip, const char *obj, struct bn_tol *tol, int flags, int max_pnts, int max_time, int verbosity)
int	rt_sample_pnts (struct bv_scene_obj *s, struct rt_db_internal *ip)

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.

Macro Definition Documentation

RT_GEN_OBJ_PNTS_SURF

#define RT_GEN_OBJ_PNTS_SURF   0x1

save only the first and last hit point on a ray

Definition at line 177 of file shoot.h.

RT_GEN_OBJ_PNTS_GRID

#define RT_GEN_OBJ_PNTS_GRID   0x2

sample using an XYZ grid based on the bounding box (default if no method flags are specified)

Definition at line 178 of file shoot.h.

RT_GEN_OBJ_PNTS_RAND

#define RT_GEN_OBJ_PNTS_RAND   0x4

sample using Marsaglia sampling on the bounding sphere with pseudo random numbers

Definition at line 179 of file shoot.h.

RT_GEN_OBJ_PNTS_SOBOL

#define RT_GEN_OBJ_PNTS_SOBOL   0x8

sample using Marsaglia sampling on the bounding sphere with Sobol' low-discrepancy-sequence generation

Definition at line 180 of file shoot.h.

Function Documentation

rt_shootray()

int rt_shootray ( struct application *  ap )

extern

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 )

extern

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  )

extern

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  )

extern

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  )

extern

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 )

extern

Tally stats into struct rt_i

rt_res_pieces_clean()

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

extern

rt_res_pieces_init()

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

extern

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  )

extern

rt_gen_obj_pnts()

int rt_gen_obj_pnts ( struct rt_pnts_internal *  rpnts, fastf_t *  avg_thickness, struct db_i *  dbip, const char *  obj, struct bn_tol *  tol, int  flags, int  max_pnts, int  max_time, int  verbosity  )

extern

Generate points from a .g object using raytracing. Various sampling options are controlled via setting flags.

Returns: 0 = success, -1 error

rt_sample_pnts()

int rt_sample_pnts ( struct bv_scene_obj *  s, struct rt_db_internal *  ip  )

extern