BRL-CAD
Loading...
Searching...
No Matches
application.h
Go to the documentation of this file.
1/* A P P L I C A T I O N . H
2 * BRL-CAD
3 *
4 * Copyright (c) 1993-2025 United States Government as represented by
5 * the U.S. Army Research Laboratory.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * version 2.1 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this file; see the file named COPYING for more
18 * information.
19 */
20/** @addtogroup rt_application
21 * @brief
22 * This structure is the only parameter to rt_shootray() and holds
23 * information about how the ray-casting should be performed.
24 */
25/** @{ */
26/** @file rt/application.h */
27
28#ifndef RT_APPLICATION_H
29#define RT_APPLICATION_H
30
31#include "common.h"
32#include "vmath.h"
33#include "bu/magic.h"
34#include "bu/log.h"
35#include "bu/ptbl.h"
36#include "bn/tabdata.h"
37#include "rt/defines.h"
38#include "rt/ray_partition.h"
39#include "rt/region.h"
40#include "rt/resource.h"
41#include "rt/seg.h"
42#include "rt/xray.h"
43
45
46struct rt_i; /* forward declaration */
47
48/**
49 * This structure is the only parameter to rt_shootray(). The entire
50 * structure should be zeroed (e.g. by memset) before it is used the
51 * first time.
52 *
53 * When calling rt_shootray(), these fields are mandatory:
54 *
55 * Field | Description
56 * ----------- | ---------------------------------------------------
57 * a_ray.r_pt | Starting point of ray to be fired
58 * a_ray.r_dir | UNIT VECTOR with direction to fire in (dir cosines)
59 * a_hit() | Routine to call when something is hit
60 * a_miss() | Routine to call when ray misses everything
61 * a_rt_i | The current struct rt_i instance, which must be set to the value returned by rt_dirbuild().
62 *
63 * In addition, these fields are used by the library. If they are set
64 * to zero, default behavior will be used.
65 *
66 * Field | Description
67 * ---------------- | ---------------------------------------------------
68 * a_resource | Pointer to CPU-specific resources. Multi-CPU only.
69 * a_overlap() | DEPRECATED, set a_multioverlap() instead.
70 * If non-null, this routine will be called to
71 * handle overlap conditions. See librt/bool.c
72 * for calling sequence.
73 * Return of 0 eliminates partition with overlap entirely
74 * Return of !0 retains one partition in output
75 * a_multioverlap() | Called when two or more regions overlap in a partition.
76 * Default behavior used if pointer not set.
77 * See librt/bool.c for calling sequence.
78 * a_level | Printed by librt on errors, but otherwise not used.
79 * a_x | Printed by librt on errors, but otherwise not used.
80 * a_y | Printed by librt on errors, but otherwise not used.
81 * a_purpose | Printed by librt on errors, but otherwise not used.
82 * a_rbeam | Used to compute beam coverage on geometry,
83 * a_diverge | for spline subdivision & many UV mappings.
84 *
85 * Note that rt_shootray() returns the (int) return of the
86 * a_hit()/a_miss() function called, as well as placing it in
87 * a_return. A future "multiple rays at a time" interface will only
88 * provide a_return.
89 *
90 * Note that the organization of this structure, and the details of
91 * the non-mandatory elements are subject to change in every release.
92 * Therefore, rather than using compile-time structure
93 * initialization, you should create a zeroed-out structure, and then
94 * assign the intended values at runtime. A zeroed structure can be
95 * obtained at compile time with "static struct application
96 * zero_ap;", or at run time by using memset(), bu_calloc(), or
97 * BU_ALLOC().
98 */
101 /* THESE ELEMENTS ARE MANDATORY */
102 struct xray a_ray; /**< @brief Actual ray to be shot */
103 int (*a_hit)(struct application *, struct partition *, struct seg *); /**< @brief called when shot hits model */
104 int (*a_miss)(struct application *); /**< @brief called when shot misses */
105 int a_onehit; /**< @brief flag to stop on first hit */
106 fastf_t a_ray_length; /**< @brief distance from ray start to end intersections */
107 struct rt_i * a_rt_i; /**< @brief this librt instance */
108 int a_zero1; /**< @brief must be zero (sanity check) */
109 /* THESE ELEMENTS ARE USED BY THE LIBRARY, BUT MAY BE LEFT ZERO */
110 struct resource * a_resource; /**< @brief dynamic memory resources */
111 int (*a_overlap)(struct application *, struct partition *, struct region *, struct region *, struct partition *); /**< @brief DEPRECATED */
112 void (*a_multioverlap)(struct application *, struct partition *, struct bu_ptbl *, struct partition *); /**< @brief called to resolve overlaps */
113 void (*a_logoverlap)(struct application *, const struct partition *, const struct bu_ptbl *, const struct partition *); /**< @brief called to log overlaps */
114 int a_level; /**< @brief recursion level (for printing) */
115 int a_x; /**< @brief Screen X of ray, if applicable */
116 int a_y; /**< @brief Screen Y of ray, if applicable */
117 const char * a_purpose; /**< @brief Debug string: purpose of ray */
118 fastf_t a_rbeam; /**< @brief initial beam radius (mm) */
119 fastf_t a_diverge; /**< @brief slope of beam divergence/mm */
120 int a_return; /**< @brief Return of a_hit()/a_miss() */
121 int a_no_booleans; /**< @brief 1= partitions==segs, no booleans */
122 char ** attrs; /**< @brief null terminated list of attributes
123 * This list should be the same as passed to
124 * rt_gettrees_and_attrs() */
125 int a_bot_reverse_normal_disabled; /**< @brief 1= no bot normals get reversed in BOT_UNORIENTED_NORM */
126 /* THESE ELEMENTS ARE USED BY THE PROGRAM "rt" AND MAY BE USED BY */
127 /* THE LIBRARY AT SOME FUTURE DATE */
128 /* AT THIS TIME THEY MAY BE LEFT ZERO */
129 struct pixel_ext * a_pixelext; /**< @brief locations of pixel corners */
130 /* THESE ELEMENTS ARE WRITTEN BY THE LIBRARY, AND MAY BE READ IN a_hit() */
133 vect_t a_inv_dir; /**< @brief filled in by rt_shootray(), inverse of ray direction cosines */
134 /* THE FOLLOWING ELEMENTS ARE MAINLINE & APPLICATION SPECIFIC. */
135 /* THEY SHOULD NEVER BE USED BY THE LIBRARY. */
136 int a_user; /**< @brief application-specific value */
137 void * a_uptr; /**< @brief application-specific pointer */
138 struct bn_tabdata * a_spectrum; /**< @brief application-specific bn_tabdata pointer */
139 fastf_t a_color[3]; /**< @brief application-specific color */
140 fastf_t a_dist; /**< @brief application-specific distance */
141 vect_t a_uvec; /**< @brief application-specific vector */
142 vect_t a_vvec; /**< @brief application-specific vector */
143 fastf_t a_refrac_index; /**< @brief current index of refraction */
144 fastf_t a_cumlen; /**< @brief cumulative length of ray */
145 int a_flag; /**< @brief application-specific flag */
146 int a_zero2; /**< @brief must be zero (sanity check) */
147};
148
149/**
150 * This structure is the only parameter to rt_shootrays(). The entire
151 * structure should be zeroed (e.g. by memset) before it is used the
152 * first time.
153 *
154 * When calling rt_shootrays(), these fields are mandatory:
155 *
156 * - b_ap Members in this single ray application structure should
157 * be set in a similar fashion as when used with
158 * rt_shootray() with the exception of a_hit() and
159 * a_miss(). Default implementations of these routines
160 * are provided that simple update hit/miss counters and
161 * attach the hit partitions and segments to the
162 * partition_bundle structure. Users can still override
163 * this default functionality but have to make sure to
164 * move the partition and segment list to the new
165 * partition_bundle structure.
166 * - b_hit() Routine to call when something is hit by the ray bundle.
167 * - b_miss() Routine to call when ray bundle misses everything.
168 *
169 * Note that rt_shootrays() returns the (int) return of the
170 * b_hit()/b_miss() function called, as well as placing it in
171 * b_return.
172 *
173 * An integer field b_user and a void *field b_uptr are provided in
174 * the structure for custom user data.
175 */
177{
179 /* THESE ELEMENTS ARE MANDATORY */
180 struct xrays b_rays; /**< @brief Actual bundle of rays to be shot */
181 struct application b_ap; /**< @brief application setting to be applied to each ray */
182 int (*b_hit)(struct application_bundle *, struct partition_bundle *); /**< @brief called when bundle hits model */
183 int (*b_miss)(struct application_bundle *); /**< @brief called when entire bundle misses */
184 int b_user; /**< @brief application_bundle-specific value */
185 void *b_uptr; /**< @brief application_bundle-specific pointer */
187};
188
189
190#define RT_APPLICATION_NULL ((struct application *)0)
191#define RT_AFN_NULL ((int (*)(struct application *, struct partition *, struct region *, struct region *, struct partition *))NULL)
192#define RT_CK_AP(_p) BU_CKMAG(_p, RT_AP_MAGIC, "struct application")
193#define RT_CK_APPLICATION(_p) BU_CKMAG(_p, RT_AP_MAGIC, "struct application")
194#define RT_APPLICATION_INIT(_p) { \
195 memset((char *)(_p), 0, sizeof(struct application)); \
196 (_p)->a_magic = RT_AP_MAGIC; \
197 }
198
199
200#ifdef NO_BOMBING_MACROS
201# define RT_AP_CHECK(_ap) (void)(_ap)
202#else
203# define RT_AP_CHECK(_ap) \
204 {if ((_ap)->a_zero1||(_ap)->a_zero2) \
205 bu_bomb("corrupt application struct"); }
206#endif
207
209
210#endif /* RT_APPLICATION_H */
211
212/** @} */
213
214/*
215 * Local Variables:
216 * tab-width: 8
217 * mode: C
218 * indent-tabs-mode: t
219 * c-file-style: "stroustrup"
220 * End:
221 * ex: shiftwidth=4 tabstop=8
222 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
fastf_t vect_t[ELEMENTS_PER_VECT]
3-tuple vector
Definition vmath.h:349
double fastf_t
fastest 64-bit (or larger) floating point type
Definition vmath.h:334
Global registry of recognized magic numbers.
int(* b_hit)(struct application_bundle *, struct partition_bundle *)
called when bundle hits model
void * b_uptr
application_bundle-specific pointer
int b_user
application_bundle-specific value
struct xrays b_rays
Actual bundle of rays to be shot.
struct application b_ap
application setting to be applied to each ray
int(* b_miss)(struct application_bundle *)
called when entire bundle misses
char ** attrs
null terminated list of attributes This list should be the same as passed to rt_gettrees_and_attrs()
struct seg * a_finished_segs_hdp
int a_user
application-specific value
void(* a_multioverlap)(struct application *, struct partition *, struct bu_ptbl *, struct partition *)
called to resolve overlaps
int a_zero2
must be zero (sanity check)
struct partition * a_Final_Part_hdp
fastf_t a_diverge
slope of beam divergence/mm
int a_y
Screen Y of ray, if applicable.
struct resource * a_resource
dynamic memory resources
int a_zero1
must be zero (sanity check)
int a_no_booleans
1= partitions==segs, no booleans
int a_level
recursion level (for printing)
vect_t a_uvec
application-specific vector
int(* a_overlap)(struct application *, struct partition *, struct region *, struct region *, struct partition *)
DEPRECATED.
vect_t a_vvec
application-specific vector
fastf_t a_cumlen
cumulative length of ray
fastf_t a_dist
application-specific distance
void(* a_logoverlap)(struct application *, const struct partition *, const struct bu_ptbl *, const struct partition *)
called to log overlaps
int(* a_miss)(struct application *)
called when shot misses
fastf_t a_ray_length
distance from ray start to end intersections
struct xray a_ray
Actual ray to be shot.
struct bn_tabdata * a_spectrum
application-specific bn_tabdata pointer
struct rt_i * a_rt_i
this librt instance
fastf_t a_refrac_index
current index of refraction
const char * a_purpose
Debug string: purpose of ray.
void * a_uptr
application-specific pointer
int a_onehit
flag to stop on first hit
struct pixel_ext * a_pixelext
locations of pixel corners
int a_bot_reverse_normal_disabled
1= no bot normals get reversed in BOT_UNORIENTED_NORM
uint32_t a_magic
fastf_t a_color[3]
application-specific color
vect_t a_inv_dir
filled in by rt_shootray(), inverse of ray direction cosines
int a_x
Screen X of ray, if applicable.
fastf_t a_rbeam
initial beam radius (mm)
int a_flag
application-specific flag
int a_return
Return of a_hit()/a_miss()
int(* a_hit)(struct application *, struct partition *, struct seg *)
called when shot hits model
Definition ptbl.h:53
Definition seg.h:59
Primary ray data structure.
Definition xray.h:41
Definition xray.h:58
fundamental vector, matrix, quaternion math macros