DI-Guy C++ SDK Reference  13.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
diguyCharacterPath.h
Go to the documentation of this file.
1 
2 /*********************************************************************
3  ** Copyright (c) 1992-2014 VT MAK
4  ** All rights reserved.
5  *********************************************************************/
6 
7 /*********************************************************************
8  **
9  *t diguyCharacterPath
10  **
11  *b Link against: libdiguy
12  */
13 
14 #ifndef __diguyCharacterPath_H
15 #define __diguyCharacterPath_H
16 
17 #ifdef SWIG
18 %module diguyCharacterPath
19 #else
20 #define CPLUSPLUS_ONLY
21 #endif
22 
23 #ifdef CPLUSPLUS_ONLY
24 
25 class bdiScenarioPath;
26 class diguyCharacter;
27 class diguyCharacterPath;
28 class diguyCharacterPathActionBead;
29 class diguyCharacterPathScriptBead;
30 class diguyCharacterPathDecisionBead;
31 class diguyCharacterPathGazeBead;
32 class diguyCharacterPathAimBead;
33 class diguyPathShape;
34 class diguyWaypoint;
35 
36 #include <diguy_constants.h>
37 #include <stdlib.h>
38 
39 #endif /* CPLUSPLUS_ONLY */
40 
41 
42 
43 #include <declspec_diguy.h>
44 
45 /****************************************************************************/
46 class BDI_DECLSPEC_diguy diguyCharacterPath
47 {
48 
49 /*****************************************************************************/
59 public:
60 
61  /*l
62  *b Description:
63  **
64  ** Returns the name of the path. This pointer will
65  ** never be NULL.
66  **
67  *b Returns:
68  **
69  ** name of the path
70  */
71  const char* get_name();
72 
73  /*l
74  *b Description:
75  **
76  ** This function sets the name of this object.
77  **
78  *b Returns:
79  **
80  ** 0 on success, -1 on failure
81  */
82  int set_name(const char* name);
83 
84  /*l
85  *b Description:
86  **
87  ** All character paths are assigned a unique identifier, or uid. This
88  ** function returns this path's uid.
89  **
90  ** *Note*: unique identifiers will change between DI-Guy runs!
91  **
92  *b Returns:
93  **
94  ** unique identifier of object
95  */
96  long get_uid();
97 
98  /*l
99  *b Returns:
100  **
101  ** character that owns this path
102  */
103  diguyCharacter* get_character();
104 
105  /*l
106  *b Description:
107  **
108  ** This function should be called after all modifications have
109  ** been made to the path and it is time to re-derive the overall
110  ** path shape and when actions happen.
111  **
112  ** This update is deferred for reasons of performance; if there
113  ** are a lot of modifications to be made to the path they can all
114  ** be done in a group with only a single final update.
115  **
116  ** A call to update() is typically required after certain calls
117  ** are made on objects owned by the path, such as a diguyWaypoint or
118  ** a diguyCharacterPathActionBead. The documentation for function
119  ** calls of these objects will state whether a subsequent update()
120  ** call is necessary.
121  **
122  *b Returns:
123  **
124  ** 0 on success, -1 on failure
125  */
126  int update();
127 
128  /*l
129  *b Description:
130  **
131  ** This function returns the total length of the path,
132  ** in meters.
133  **
134  *b Returns:
135  **
136  ** length of path in meters
137  */
138  float get_length();
139 
140  /*l
141  *b Description:
142  **
143  ** This function returns how long this path is
144  **
145  *b Returns:
146  **
147  ** duration of this path, in seconds
148  */
149  float get_duration();
150 
151  /*l
152  *b Description:
153  **
154  ** This function returns, via the passed variable pointers,
155  ** the position and orientation of the point on the path
156  ** at the specified distance.
157  **
158  *b Arguments:
159  **
160  *a distance_into_path - distance in meters into path
161  *a of the desired point
162  *a x, y, z - position of point in meters from the origin
163  *a rz, rx, ry - orientation of point in degrees counter-clockwise
164  *a from the positive X axis
165  **
166  *b Returns:
167  **
168  ** 0 on success, -1 on failure
169  */
170  int get_point_at_distance(float distance_into_path,
171  float* x, float* y, float* z,
172  float* rz, float* rx, float* ry);
173 
174  /*l
175  *b Description:
176  **
177  ** This function returns the underlying path shape of the
178  ** path. The path shape defines only the waypoints and
179  ** associated spline shape of the path; it doesn't not
180  ** contain any beads or other information.
181  **
182  ** The returned path shape should be considered READ ONLY.
183  ** DO NOT edit the path shape using diguyPathShape member
184  ** functions!
185  **
186  *b Returns:
187  **
188  ** pointer to object of type diguyPathShape
189  */
190  diguyPathShape* get_path_shape();
191 
192 
193 /*****************************************************************************/
203  /*l
204  *b Returns:
205  *
206  ** the number of waypoints belonging to this path
207  */
208  int get_num_waypoints();
209 
210  /*l
211  *b Description:
212  **
213  ** This function gets the waypoint at the specified
214  ** index and returns a pointer to it. The returned
215  ** waypoint can then be queried for information or
216  ** modified.
217  **
218  ** Note that if the waypoint is modified, the update()
219  ** function must be called to update the path's shape
220  ** and other information.
221  **
222  *b Arguments:
223  **
224  *a index - index of the waypoint; indices start at 0
225  **
226  *b Returns:
227  **
228  ** pointer of type diguyWaypoint; NULL if no
229  ** waypoint at the specified index
230  **
231  *b Lua Example:
232  **
233  ** This example gets the first waypoint of the first
234  ** character's first path. It then changes the x coordinate
235  ** of the waypoint and updates the path to reflect the change.
236  **
237  *e local character = this_scenario:get_character_at_index(0);
238  *e local path0 = character:get_path_at_index(0);
239  *e
240  *e local wp0 = path0:get_waypoint_at_index(0);
241  *e local wp0_x = wp0:get_x();
242  *e wp0:set_x(wp0_x + 1.0);
243  *e
244  *e path0:update();
245  */
246  diguyWaypoint* get_waypoint_at_index(int index);
247 
248  /*l
249  *b Description:
250  **
251  ** This function returns a pointer to the specified waypoint.
252  **
253  *b Arguments:
254  **
255  *a name - name of waypoint to be found
256  **
257  *b Returns:
258  **
259  ** pointer of type diguyWaypoint; NULL if not found
260  */
261  diguyWaypoint* find_waypoint(const char* name);
262 
263  /*l
264  *b Description:
265  **
266  ** This function creates a new waypoint that is added to the
267  ** path. Do not call diguyScenario::destroy_waypoint() on
268  ** the returned waypoint; it will be destroyed automatically
269  ** with the path.
270  **
271  *b Arguments:
272  **
273  *a tx, ty, tz - position in meters from the origin
274  *a rz, rx, ry - orientations in degrees counter-clockwise
275  *a from the positive X axis
276  *a weight - how much influence this waypoint exerts
277  *a over the path curve
278  *a index - where the waypoint should be inserted in
279  *a the path; indices start at 0; pass -1 to
280  *a add to end of path
281  **
282  *b Returns:
283  **
284  ** pointer to type diguyWaypoint
285  */
286  diguyWaypoint* create_waypoint(float x = 0.0f, float y = 0.0f, float z = 0.0f,
287  float yaw = 0.0f, float roll = 0.0f, float pitch = 0.0f,
288  float weight = 1.0f,
289  int index = -1);
290 
291  /*l
292  *b Description:
293  **
294  ** This function adds a waypoint to the path.
295  **
296  ** The waypoint should be created using the function
297  ** diguyScenario::create_waypoint(), and destroyed
298  ** using the function diguyScenario::destroy_waypoint().
299  **
300  ** An internal copy of the waypoint is made, so it can
301  ** be destroyed right after this function call or used
302  ** for other path shapes.
303  **
304  *b Arguments:
305  **
306  *a waypoint - waypoint to be appended to end of path
307  **
308  *b Returns:
309  **
310  ** 0 on success, -1 on failure
311  */
312  int add_waypoint(diguyWaypoint* waypoint);
313 
314 
315 /*****************************************************************************/
325  /*l
326  *b Returns:
327  *
328  ** the number of action beads belonging to this path
329  */
330  int get_num_action_beads();
331 
332  /*l
333  *b Description:
334  **
335  ** This function gets the action bead at the specified
336  ** index and returns a pointer to it. The returned
337  ** action bead can then be queried for information or
338  ** modified.
339  **
340  ** Note that if the action bead is modified, the update()
341  ** function must be called to update the path's information.
342  **
343  *b Returns:
344  **
345  ** pointer of type diguyCharacterPathActionBead; NULL if no
346  ** action bead at the specified index
347  **
348  *b Arguments:
349  **
350  *a index - index of the action bead; indices start at 0
351  */
352  diguyCharacterPathActionBead* get_action_bead_at_index(int index);
353 
354  /*l
355  *b Description:
356  **
357  ** This function returns a pointer to the specified bead.
358  **
359  *b Arguments:
360  **
361  *a name - name of bead to be found
362  **
363  *b Returns:
364  **
365  ** pointer of type diguyCharacterPathActionBead; NULL if not found
366  */
367  diguyCharacterPathActionBead* find_action_bead(const char* name);
368 
369  /*l
370  *b Description:
371  **
372  ** This function returns a pointer to the last action bead of the
373  ** path. The last action bead is slightly different than the
374  ** rest. It has no inherent duration or length; instead, it
375  ** effectively specifies what the character should do once this
376  ** path has completed.
377  **
378  ** Calling this function is the same as the following:
379  **
380  *e int num_action_beads = path->get_num_action_beads();
381  *e diguyCharacterPathActionBead* ab;
382  *e ab = path->get_action_bead_at_index(num_action_beads-1);
383  **
384  ** Do not call delete or destroy_action_bead() on the returned
385  ** pointer. All paths must have a final action bead.
386  **
387  *b Returns:
388  **
389  ** pointer of type diguyCharacterPathActionBead; this pointer
390  ** should never be NULL
391  */
392  diguyCharacterPathActionBead* get_final_action_bead();
393 
394  /*l
395  *b Description:
396  **
397  ** This function inserts a new action bead at the specified
398  ** index and returns a pointer to it. The returned
399  ** action bead can then be queried for information or
400  ** modified.
401  **
402  ** Note that the update() function must be called after this
403  ** function.
404  **
405  ** Do not call delete on the returned pointer. Use
406  ** destroy_action_bead() instead.
407  **
408  *b Returns:
409  **
410  ** pointer of type diguyCharacterPathActionBead; NULL if
411  ** insertion failed
412  **
413  *b Arguments:
414  **
415  *a action - action new bead should perform
416  *a index - index of the action bead; indices start at 0;
417  *a pass -1 to append the action bead to the end
418  *a of the path
419  */
420  diguyCharacterPathActionBead* create_action_bead(const char* action,
421  int index = -1);
422 
423  /*l
424  *b Description:
425  **
426  ** This function removes the passed action bead from the
427  ** path and destroys it.
428  **
429  ** Note that the update() function must be called after this
430  ** function.
431  **
432  *b Returns:
433  **
434  ** 0 on success, -1 on failure
435  **
436  *b Arguments:
437  **
438  *a action_bead - object to destroy; must be part of this path
439  */
440  int destroy_action_bead(diguyCharacterPathActionBead* action_bead);
441 
442 
443 /*****************************************************************************/
453  /*l
454  *b Returns:
455  *
456  ** the number of script beads belonging to this path
457  */
458  int get_num_script_beads();
459 
460  /*l
461  *b Description:
462  **
463  ** This function gets the script bead at the specified
464  ** index and returns a pointer to it. The returned
465  ** script bead can then be queried for information or
466  ** modified.
467  **
468  ** Note that if the script bead is modified, the update()
469  ** function must be called to update the path's information.
470  **
471  *b Returns:
472  **
473  ** pointer of type diguyCharacterPathScriptBead; NULL if no
474  ** script bead at the specified index
475  **
476  *b Arguments:
477  **
478  *a index - index of the script bead; indices start at 0
479  */
480  diguyCharacterPathScriptBead* get_script_bead_at_index(int index);
481 
482  /*l
483  *b Description:
484  **
485  ** This function returns a pointer to the specified bead.
486  **
487  *b Arguments:
488  **
489  *a name - name of bead to be found
490  **
491  *b Returns:
492  **
493  ** pointer of type diguyCharacterPathScriptBead; NULL if not found
494  */
495  diguyCharacterPathScriptBead* find_script_bead(const char* name);
496 
497  /*l
498  *b Description:
499  **
500  ** This function inserts a new script bead at the specified
501  ** index and returns a pointer to it. The returned
502  ** script bead can then be queried for information or
503  ** modified.
504  **
505  ** Note that the update() function must be called after this
506  ** function.
507  **
508  ** Do not call delete on the returned pointer. Use
509  ** destroy_script_bead() instead.
510  **
511  *b Returns:
512  **
513  ** pointer of type diguyCharacterPathScriptBead; NULL if
514  ** insertion failed
515  **
516  *b Arguments:
517  **
518  *a script - script new bead should perform
519  *a index - index of the script bead; indices start at 0;
520  *a pass -1 to create the bead at the last index
521  *a script_type - defaults to "lua"
522  */
523  diguyCharacterPathScriptBead* create_script_bead(const char* script,
524  int index = -1,
525  const char* script_type = "lua");
526 
527  /*l
528  *b Description:
529  **
530  ** This function removes the passed script bead from the
531  ** path and destroys it.
532  **
533  ** Note that the update() function must be called after this
534  ** function.
535  **
536  *b Returns:
537  **
538  ** 0 on success, -1 on failure
539  **
540  *b Arguments:
541  **
542  *a script_bead - object to destroy; must be part of this path
543  */
544  int destroy_script_bead(diguyCharacterPathScriptBead* script_bead);
545 
546 
547 /*****************************************************************************/
557  /*l
558  *b Returns:
559  *
560  ** the number of decision beads belonging to this path
561  */
562  int get_num_decision_beads();
563 
564  /*l
565  *b Description:
566  **
567  ** This function gets the decision bead at the specified
568  ** index and returns a pointer to it. The returned
569  ** decision bead can then be queried for information.
570  **
571  ** Note that if the decision bead is modified, the update()
572  ** function must be called to update the path's information.
573  **
574  *b Returns:
575  **
576  ** pointer of type diguyCharacterPathDecisionBead; NULL if no
577  ** script bead at the specified index
578  **
579  *b Arguments:
580  **
581  *a index - index of the decision bead; indices start at 0
582  */
583  diguyCharacterPathDecisionBead* get_decision_bead_at_index(int index);
584 
585  /*l
586  *b Description:
587  **
588  ** This function returns a pointer to the specified bead.
589  **
590  *b Arguments:
591  **
592  *a name - name of bead to be found
593  **
594  *b Returns:
595  **
596  ** pointer of type diguyCharacterPathDecisionBead; NULL if not found
597  */
598  diguyCharacterPathDecisionBead* find_decision_bead(const char* name);
599 
600 
601 /*****************************************************************************/
611  /*l
612  *b Returns:
613  *
614  ** the number of gaze beads belonging to this path
615  */
616  int get_num_gaze_beads();
617 
618  /*l
619  *b Description:
620  **
621  ** This function gets the gaze bead at the specified
622  ** index and returns a pointer to it. The returned
623  ** gaze bead can then be queried for information.
624  **
625  ** Note that if the gaze bead is modified, the update()
626  ** function must be called to update the path's information.
627  **
628  *b Returns:
629  **
630  ** pointer of type diguyCharacterPathDecisionBead; NULL if no
631  ** script bead at the specified index
632  **
633  *b Arguments:
634  **
635  *a index - index of the gaze bead; indices start at 0
636  */
637  diguyCharacterPathGazeBead* get_gaze_bead_at_index(int index);
638 
639  /*l
640  *b Description:
641  **
642  ** This function returns a pointer to the specified bead.
643  **
644  *b Arguments:
645  **
646  *a name - name of bead to be found
647  **
648  *b Returns:
649  **
650  ** pointer of type diguyCharacterPathGazeBead; NULL if not found
651  */
652  diguyCharacterPathGazeBead* find_gaze_bead(const char* name);
653 
654 
655 /*****************************************************************************/
665  /*l
666  *b Returns:
667  *
668  ** the number of aim beads belonging to this path
669  */
670  int get_num_aim_beads();
671 
672  /*l
673  *b Description:
674  **
675  ** This function gets the aim bead at the specified
676  ** index and returns a pointer to it. The returned
677  ** aim bead can then be queried for information.
678  **
679  ** Note that if the aim bead is modified, the update()
680  ** function must be called to update the path's information.
681  **
682  *b Returns:
683  **
684  ** pointer of type diguyCharacterPathDecisionBead; NULL if no
685  ** script bead at the specified index
686  **
687  *b Arguments:
688  **
689  *a index - index of the aim bead; indices start at 0
690  */
691  diguyCharacterPathAimBead* get_aim_bead_at_index(int index);
692 
693  /*l
694  *b Description:
695  **
696  ** This function returns a pointer to the specified bead.
697  **
698  *b Arguments:
699  **
700  *a name - name of bead to be found
701  **
702  *b Returns:
703  **
704  ** pointer of type diguyCharacterPathAimBead; NULL if not found
705  */
706  diguyCharacterPathAimBead* find_aim_bead(const char* name);
707 
708 
709 
710 /****************************************************************************/
711 /****************************************************************************/
712 /****************************************************************************/
719 /****************************************************************************/
720 /****************************************************************************/
721 /****************************************************************************/
722 
723  int translate(float tx, float ty, float tz);
724 
725  int rotate_about_point(float rz, float rx, float ry,
726  float rotation_pt_x, float rotation_pt_y, float rotation_pt_z);
727 
728  int set_ground_clamp_when_on_path(int ground_clamp_when_on_path);
729  int get_ground_clamp_when_on_path();
730 
731  int get_position_at_distance(float distance,
732  float* tx, float* ty, float* tz,
733  float* rz = NULL, float* rx = NULL, float* ry = NULL);
734  int get_position_at_distance_double(float distance,
735  double* tx, double* ty, double* tz,
736  float* rz = NULL, float* rx = NULL, float* ry = NULL);
737 
738  int get_position_at_t(float t,
739  float* tx, float* ty, float* tz,
740  float* rz = NULL, float* rx = NULL, float* ry = NULL);
741  int get_position_at_t_double(float t,
742  double* tx, double* ty, double* tz,
743  float* rz = NULL, float* rx = NULL, float* ry = NULL);
744 
745 
750 #ifdef CPLUSPLUS_ONLY
751 
752  bdiScenarioPath* get_scripted_object() {return m_scripted_object;}
753 
754 private:
755 
756  /*l
757  ** A private constructor.
758  */
759  diguyCharacterPath(bdiScenarioPath* path);
760 
761  /*l
762  ** A private destructor.
763  */
764  ~diguyCharacterPath();
765 
766  /*l
767  ** A pointer to internal data.
768  */
769  bdiScenarioPath* m_scripted_object;
770 
771  friend class bdiScenarioPath;
772  friend class diguyCharacter;
773 
774 #endif /* CPLUSPLUS_ONLY */
775 
776 };
777 
778 #endif /* __diguyCharacterPath_H */
779