DI-Guy SDK Documentation  13.2
diguyRegion.h
Go to the documentation of this file.
1 
2 /*********************************************************************
3  ** Copyright (c) 1992-2016 VT MAK
4  ** All rights reserved.
5  *********************************************************************/
6 
7 
8 /******************************************************************************
9  **
10  *t diguyRegion
11  **
12  *b Link against: libdiguy
13  **
14  *b Summary
15  **
16  ** API for accessing diguyRegion objects generated by the crowd
17  ** and region painter.
18  **
19  ** For information on subregions, see the documentation for the
20  ** diguySubregionIndex and diguySubregionMask enumerations in
21  ** diguy_constants.h.
22  */
23 
24 #ifndef __diguyRegion_H
25 #define __diguyRegion_H
26 
27 
28 #ifdef SWIG
29 %module diguyRegion
30 #else
31 #define CPLUSPLUS_ONLY
32 #endif
33 
34 #ifdef CPLUSPLUS_ONLY
35 class bdiNavMeshRegionInterface;
36 
37 #endif
38 
39 
40 #include <declspec_diguy.h>
41 #include <diguy_constants.h>
42 
53 /*********************************************************************/
54 class BDI_DECLSPEC_diguy diguyRegion
55 {
56 
57 public:
58 
59 /*****************************************************************************/
65  /*l
66  *b Description:
67  **
68  ** Returns the name of the region. This pointer will
69  ** never be NULL.
70  **
71  *b Returns:
72  **
73  ** name of the region
74  **
75  *b Callable From:
76  **
77  *- - C++
78  *- - Script
79  */
80  const char* get_name();
81 
82  /*l
83  **
84  *b Description:
85  **
86  ** Returns 1 if a point is approximately inside the region. Supports
87  ** multiple subregions via or'ing masks together.
88  **
89  ** Use the base mask (DIGUY_SUBREGION_MASK_BASE) to test against the
90  ** base of the region.
91  **
92  *b Returns:
93  **
94  ** 1 if the point is in the region, 0 if not
95  **
96  *b Callable From:
97  **
98  *- - C++
99  *- - Script
100  */
101  int is_point_in_region(diguySubregionMask subregion_mask,
102  float x, float y, float z);
103 
104  /*l
105  **
106  **
107  *b Description:
108  **
109  ** Returns a random x, y, z point in the region specified. This
110  ** function takes a region index (e.g. DIGUY_SUBREGION_BASE).
111  **
112  *b Arguments:
113  **
114  *a subregion_index - subregion in which to find the point
115  *a res_x, res_y, res_z - return point
116  **
117  *b Returns:
118  **
119  ** 0 if a point was successfully generated, -1 on failure
120  **
121  *b Callable From:
122  **
123  *- - C++
124  *- - Script
125  */
126  int get_point_in_region(diguySubregionIndex subregion_index,
127  float* res_x, float* res_y, float* res_z);
128 
129  /*l
130  **
131  *b Description:
132  **
133  ** Returns a random x, y, z point, near the seed location, in the
134  ** subregion specified.
135  **
136  *b Arguments:
137  **
138  *a subregion_index - subregion in which to find the point
139  *a seed_x, seed_y, seed_z - location to use as the seed point
140  *a radius - radius around the seed point within which
141  *a the result point should be located
142  *a res_x, res_y, res_z - return point
143  *a
144  *b Returns:
145  **
146  ** 0 if a point was successfully generated, -1 on failure
147  **
148  *b Callable From:
149  **
150  *- - C++
151  *- - Script
152  */
153  int get_point_in_region_near_point(diguySubregionIndex subregion_index,
154  float seed_x, float seed_y, float seed_z,
155  float radius,
156  float* res_x, float* res_y, float* res_z);
157 
158  /*l
159  **
160  *b Description:
161  **
162  ** Returns the nearest point in the region near the seed location,
163  ** in the subregion(s) specified.
164  **
165  *b Arguments:
166  **
167  *a subregion_mask - subregion(s) to search
168  *a seed_x, seed_y, seed_z - location to use as the search seed point
169  *a res_x, res_y, res_z - return point
170  **
171  *b Returns:
172  **
173  ** 0 if a point was successfully generated, -1 on failure
174  **
175  *b Callable From:
176  **
177  *- - C++
178  *- - Script
179  */
180  int get_nearest_point_in_region(diguySubregionMask subregion_mask,
181  float seed_x, float seed_y, float seed_z,
182  float* res_x, float* res_y, float* res_z);
183 
184  /*l
185  **
186  *b Description:
187  **
188  ** Returns the nearest reachable point to the seed location, inside
189  ** the subregion(s) specified by the mask.
190  **
191  ** Determining reachability involves guaranteeing that there is a
192  ** contiguous section of the base region between the seed point
193  ** and the resulting point.
194  **
195  *b Arguments:
196  **
197  *a subregion_mask - the subregion(s) to search
198  *a seed_x, seed_y, seed_z - the location to use as the search seed point
199  *a res_x, res_y, res_z - return point
200  **
201  *b Returns:
202  **
203  ** 0 if a point was successfully found, -1 on failure
204  **
205  *b Callable From:
206  **
207  *- - C++
208  *- - Script
209  */
210  int get_nearest_reachable_point(diguySubregionMask subregion_mask,
211  float seed_x, float seed_y, float seed_z,
212  float* res_x, float* res_y, float* res_z);
213 
214  /*l
215  *b Returns:
216  **
217  ** the number of rows in the region
218  **
219  *b Callable From:
220  **
221  *- - C++
222  *- - Script
223  */
224  int get_num_rows();
225 
226  /*l
227  *b Returns:
228  **
229  ** the number of columns in the region
230  **
231  *b Callable From:
232  **
233  *- - C++
234  *- - Script
235  */
236  int get_num_columns();
237 
238  /*l
239  *b Returns:
240  **
241  ** the resolution of the region in meters per point
242  **
243  *b Callable From:
244  **
245  *- - C++
246  *- - Script
247  */
248  float get_resolution();
249 
250  /*l
251  *b Description:
252  **
253  ** This function returns a random factor between 0 and 1 computed for
254  ** this region. This number can be used, for example, to modify
255  ** colors or depths of region visuals.
256  **
257  ** The number will remain the same for the lifetime of the region.
258  **
259  *b Returns:
260  **
261  ** a random factor between 0 and 1
262  **
263  *b Callable From:
264  **
265  *- - C++
266  *- - Script
267  */
268  float get_random_factor();
269 
270 
271 /*****************************************************************************/
277  /*l
278  **
279  *b Description:
280  **
281  ** Shrinks the region's bounds to just the area with tagged data in
282  ** it. Can help conserve memory. Currently always returns 0.
283  **
284  *b Callable From:
285  **
286  *- - C++
287  *- - Script
288  */
289  int shrink();
290 
291  /*l
292  **
293  *b Description:
294  **
295  ** Erases all region data and then shrinks the region.
296  **
297  *b Callable From:
298  **
299  *- - C++
300  *- - Script
301  */
302  int clear_region();
303 
304  /*l
305  **
306  *b Description:
307  **
308  ** Erases all subregion data and then shrinks the region.
309  **
310  *b Callable From:
311  **
312  *- - C++
313  *- - Script
314  */
315  int clear_subregion(diguySubregionIndex subregion_index);
316 
317  /*l
318  **
319  *b Description:
320  **
321  ** Resamples the mesh and sets the resolution of the mesh to the new
322  ** resolution.
323  **
324  ** Note that the resampled data is currently rough and will probably
325  ** need to be touched up by hand. The system is currently limited to
326  ** creating meshes with a resolution of 0.25 meters per point.
327  **
328  *b Callable From:
329  **
330  *- - C++
331  *- - Script
332  */
333  int resample_mesh(float resolution);
334 
335  /*l
336  **
337  *b Description:
338  **
339  ** This function adds to the specified subregion with a spherical
340  ** brush centered at the specified point and with the specified
341  ** radius.
342  **
343  ** If you are doing a number of edits to the mesh at once, it's
344  ** preferable to wait until the last one before setting
345  ** force_visual_update to 1.
346  **
347  *b Callable From:
348  **
349  *- - C++
350  *- - Script
351  */
352  int paint(diguySubregionIndex subregion_index,
353  float x, float y, float z,
354  float radius,
355  int force_visual_update = 0);
356 
357  /*l
358  **
359  *b Description:
360  **
361  ** This function adds to the specified subregion with a rectangular
362  ** brush stretching from the min point to the max point specified.
363  **
364  ** If you are doing a number of edits to the mesh at once, it's
365  ** preferable to wait until the last one before setting
366  ** force_visual_update to 1.
367  **
368  *b Callable From:
369  **
370  *- - C++
371  *- - Script
372  */
373  int paint_rectangle(diguySubregionIndex subregion_index,
374  float min_x, float min_y, float min_z,
375  float max_x, float max_y, float max_z,
376  int force_visual_update = 0);
377 
378  /*l
379  **
380  *b Description:
381  **
382  ** This function removes from the specified subregion with a spherical
383  ** brush centered at the specified point and with the specified
384  ** radius.
385  **
386  ** If you are doing a number of edits to the mesh at once, it's
387  ** preferable to wait until the last one before setting
388  ** force_visual_update to 1.
389  **
390  ** Returns:
391  **
392  ** 1 if any points were erased, 0 if not
393  **
394  *b Callable From:
395  **
396  *- - C++
397  *- - Script
398  */
399  int erase(diguySubregionIndex subregion_index,
400  float x, float y, float z,
401  float radius,
402  int force_visual_update = 0);
403 
404  /*l
405  **
406  *b Description:
407  **
408  ** This function removes from the specified subregion with a
409  ** rectangular brush stretching from min point to the max point
410  ** specified.
411  **
412  ** If you are doing a number of edits to the mesh at once, it's
413  ** preferable to wait until the last one before setting
414  ** force_visual_update to 1.
415  **
416  ** Returns:
417  **
418  ** 1 if any points were erased, 0 if not
419  **
420  *b Callable From:
421  **
422  *- - C++
423  *- - Script
424  */
425  int erase_rectangle(diguySubregionIndex subregion_index,
426  float min_x, float min_y, float min_z,
427  float max_x, float max_y, float max_z,
428  int force_visual_update = 0);
429 
430  /*l
431  **
432  *b Description:
433  **
434  ** This function attempts to grow the region to encompass the min and
435  ** max points specified as well as determine the reachability of all
436  ** of those points at once. Note: the navmesh reachability algorithm
437  ** is not perfect and the results will probably need to be touched up
438  ** by hand.
439  **
440  *b Callable From:
441  **
442  *- - C++
443  *- - Script
444  */
445  int generate_navmesh(float min_x, float min_y, float min_z,
446  float max_x, float max_y, float max_z);
447 
448 
453 #ifdef CPLUSPLUS_ONLY
454 
455  bdiNavMeshRegionInterface* get_scripted_object() {return m_scripted_object;}
456 
457 private:
458 
459  /*l
460  ** A private constructor.
461  */
462  diguyRegion(bdiNavMeshRegionInterface* scripted_object);
463 
464  /*l
465  ** A private destructor.
466  */
467  ~diguyRegion();
468 
469  /*l
470  ** A pointer to internal data.
471  */
472  bdiNavMeshRegionInterface* m_scripted_object;
473  friend class bdiNavMeshRegionInterface;
474  friend class bdiNavMeshRegion;
475 
476  float m_random_factor;
477 
478 #endif
479 
480 };
481 
482 
483 #endif /* __diguyRegion_H */
484 
485 
486 /*********************************************************************
487  ** Copyright (c) 1992-2016 VT MAK
488  ** All rights reserved.
489  *********************************************************************/
490 
diguyRegion
A two-and-a-half-dimensional surface that represents either a navigation mesh or an area that's been ...
Definition: diguyRegion.h:50
diguySubregionIndex
diguySubregionIndex
DI-Guy subregions.
Definition: diguy_constants.h:1457
diguy_constants.h
declspec_diguy.h
diguySubregionMask
diguySubregionMask
DI-Guy subregions mask values.
Definition: diguy_constants.h:1505