DI-Guy SDK Documentation  13.1
diguyScenario.h
Go to the documentation of this file.
1 
2 /*********************************************************************
3  ** Copyright (c) 1992-2015 VT MAK
4  ** All rights reserved.
5  *********************************************************************/
6 
7 /*********************************************************************
8  **
9  *t diguyScenario
10  **
11  *b Link against: libdiguy
12  */
13 
14 #ifndef __diguyScenario_H
15 #define __diguyScenario_H
16 
17 #ifdef SWIG
18 %module diguyScenario
19 #else
20 #define CPLUSPLUS_ONLY
21 #endif
22 
23 #ifdef CPLUSPLUS_ONLY
24 
25 #include <declspec_diguy.h>
26 #include <diguyViewCamera.h>
27 #include <diguyViewFog.h>
28 #include <diguyViewLight.h>
29 #include <diguyMotionDirection.h>
30 #include <diguyMotionPosture.h>
31 #include <diguyMotionVariant.h>
32 #include <diguyCharacterTypeMap.h>
33 #include <diguyCharacterFaceExpression.h>
34 #include <diguy_vector_classes.h>
35 
36 #include "diguy_constants.h"
37 #include "diguy_typedefs.h"
38 #include "diguyCharacterPath.h"
39 #include "diguyInteractionMachine.h"
40 #include "diguySensorRegion.h"
41 #include "diguySignal.h"
42 #include "diguyVariable.h"
43 #include "diguyView.h"
44 
45 class bdiScenario;
46 class diguyViewButtonPanel;
47 class diguyChainSettings;
48 class diguyCharacter;
49 class diguyCharacterGroup;
50 class diguyCharacterPathEvent;
51 class diguyCrowd;
52 class diguyCrowdProfile;
53 class diguyLoadManager;
54 class diguyFormation;
55 class diguyViewLabel;
56 class diguyIGuyController;
57 class diguyInfoPopup;
58 class diguyImpact;
59 class diguyPathShape;
60 class diguyRegion;
61 class diguyScenarioMergeSettings;
62 class diguySceneObject;
63 class diguySensorRegion;
64 class diguySound;
65 class diguyVariable;
66 class diguyWaypoint;
67 class diguyView;
68 class diguyViewCameraSettings;
69 class diguyViewFogSettings;
70 class diguyViewLightSettings;
71 class diguyIntersectionResult;
72 struct diguyLightRenderDesc;
73 
74 #endif
75 
92 /****************************************************************************/
93 class BDI_DECLSPEC_diguy diguyScenario
94 {
95 
96 /*****************************************************************************/
106 public:
107 
108  /*l
109  *b Description:
110  **
111  ** This static function returns a pointer to the current scenario
112  ** object. All functions below can then be called through this
113  ** pointer. This is the same pointer returned by the call
114  ** diguy_create_scenario().
115  **
116  ** lua scripts get the current scenario through the variable
117  ** this_scenario.
118  **
119  *b Returns:
120  **
121  ** a pointer of type diguyScenario
122  **
123  *b C++ Example:
124  **
125  *e diguyScenario* sc = diguyScenario::get_current_scenario();
126  *e sc->reset();
127  **
128  *b Lua Example:
129  **
130  *e this_scenario:reset();
131  */
132  static diguyScenario* get_current_scenario();
133 
134  /*l
135  *b Description:
136  **
137  ** Returns the name of the object. This pointer will never be NULL.
138  **
139  *b Returns:
140  **
141  ** name of the object
142  */
143  const char* get_name();
144 
145  /*l
146  *b Description:
147  **
148  ** Returns the type name of the object. This pointer will never be
149  ** NULL.
150  **
151  *b Returns:
152  **
153  ** type name of the object
154  */
155  const char* get_type_name();
156 
157  /*l
158  *b Returns:
159  **
160  ** the scenario description as specified in the scenario info page
161  */
162  const char* get_description();
163 
164 
165 /*****************************************************************************/
175 #ifdef CPLUSPLUS_ONLY
176 
177  /*l
178  *b Description:
179  **
180  ** Sets the desired simulation time of the scenario.
181  **
182  ** Some update operations will use the simulation desired time
183  ** directly.
184  **
185  ** Many other scenario operations -- notably character position and
186  ** pose updates -- will not happen until the desired t passes each
187  ** subsequent tick dt threshold. See set_tick_dt().
188  **
189  ** This function sets both elapsed simulation time and elapsed
190  ** realtime to the same value. This is usually desired in DI-Guy
191  ** applications. To pass separate values for simulation time and
192  ** realtime time, call update2().
193  **
194  ** Time can be run backwards. This happens if the passed t is lower
195  ** than any t previously passed to the update() function; the
196  ** scenario remembers the highest t it has reached. If t is set to
197  ** less that the highest t reached, characters that have history data
198  ** will replay what they were doing at the specified time.
199  ** Characters that do not have history will remain motionless until t
200  ** advances past the previous highest t.
201  **
202  ** Scenario time will never go below 0.
203  **
204  ** If t reaches the scenario tout ("T Out") time (as set by
205  ** set_tout(), a number of things may happen. The scenario may:
206  **
207  *- - simply stop at the tout time
208  *- - continue past the tout time
209  *- - rewind to time 0 and play back recorded history
210  *- - reset and re-simulate the scenario from time 0
211  **
212  ** The default tout time is 60000 for DI-Guy applications. The tout
213  ** can be enabled and disabled with set_tout_enabled().
214  **
215  ** This function cannot explicitly be called for DI-Guy Scenario, but
216  ** the effects of t reaching tout during scenario simulation are
217  ** outlined here anyway.
218  **
219  *b For a DI-Guy application:
220  **
221  *- - If the scenario tout is enabled the scenario will stop.
222  *
223  *- - If the scenario tout is disabled the scenario will continue
224  *- indefinitely, regardless of scenario tout.
225  **
226  ** Note that no playback looping happens in a DI-Guy application if
227  ** tout is reached. Only in DI-Guy Scenario does the loop flag
228  ** have an effect.
229  *-
230  *b For DI-Guy Scenario:
231  **
232  *- - If the loop flag is not set (see set_playback_loop()) or a movie
233  *- is being recorded, the scenario will stop.
234  *
235  *- - If the loop flag is set, and any character in the scenario has
236  *- history data (see the History Functions for diguyCharacter), the
237  *- scenario will be rewound to 0 and play back history data.
238  *
239  *- - If the loop flag is set, but no characters in the scenario have
240  *- history data, the scenario will be reset to 0 and re-simulate
241  *- from there.
242  **
243  *b Arguments:
244  **
245  *a t - desired time in seconds
246  **
247  *b Returns:
248  **
249  ** 0 on success, -1 on failure
250  **
251  *b Callable From:
252  **
253  *- - C++
254  */
255  int update(float t);
256 
257  /*l
258  *b Description:
259  **
260  ** Similar to update(), but the realtime time can be explicitly
261  ** passed in.
262  **
263  *b Arguments:
264  **
265  *a t - desired simulation time in seconds
266  *a realtime_t - elapsed real time in seconds
267  **
268  *b Returns:
269  **
270  ** 0 on success, -1 on failure
271  **
272  *b Callable From:
273  **
274  *- - C++
275  */
276  int update2(float t, float realtime_t);
277 
278  /*l
279  *b Description:
280  **
281  ** This function sets whether the scenario is designed to loop at
282  ** tout. The default is for scenarios to loop.
283  **
284  ** Note that this has an effect only in DI-Guy Scenario. DI-Guy
285  ** applications do not use this flag.
286  **
287  ** See get_playback_loop().
288  **
289  *b Arguments:
290  **
291  *a playback_loop - pass 1 to have scenario loop at tout, 0 to not
292  **
293  *b Returns:
294  **
295  ** 0 on success, -1 on failure
296  **
297  *b Callable From:
298  **
299  *- - C++
300  */
301  int set_playback_loop(int playback_loop);
302 
303  /*l
304  *b Description:
305  **
306  ** Scenarios progress at discrete time steps, called "ticks". Each
307  ** tick is of the same duration. This function sets the amount of
308  ** time each tick takes.
309  **
310  ** Because changing the tick interval of a scenario changes when
311  ** event beads occur, any change may introduce subtle differences in
312  ** scenario playback.
313  **
314  ** Note that loading a .dss file will change the tick dt, as tick dt
315  ** is set on a per scenario basis.
316  **
317  ** The default tick dt of a new scenario is 0.03125 seconds, or 32
318  ** frames per second.
319  **
320  *b Arguments:
321  **
322  *a tick_dt - duration, in seconds, of each scenario tick
323  **
324  *b Returns:
325  **
326  ** 0 on success, -1 on failure
327  **
328  *b Callable From:
329  **
330  *- - C++
331  **
332  *b C++ Example:
333  **
334  *e diguyScenario* sc = diguy_create_scenario();
335  *e if (sc)
336  *e {
337  *e sc->load("my_scenario.dss");
338  *e sc->set_tick_dt(0.033333); // 30 fps
339  *e }
340  */
341  int set_tick_dt(float tick_dt);
342 
343 #endif
344 
345  /*l
346  *b Description:
347  **
348  ** This function returns the time in seconds that the scenario is
349  ** currently at. See update().
350  **
351  ** Note that this value will not necessarily track the t passed in
352  ** the update() function. This t advances only when the scenario's
353  ** current tick changes. See set_tick_dt() and update().
354  **
355  *b Returns:
356  **
357  ** current time in seconds
358  */
359  float get_t();
360 
361  /*l
362  *b Description:
363  **
364  ** This function returns the realtime time in seconds that the
365  ** scenario is currently at. This may be different than
366  ** get_desired_t() if the scenario is stopped or the time passed in
367  ** update() is not tracking realtime.
368  **
369  *b Returns:
370  **
371  ** current time in seconds
372  */
373  float get_realtime_t();
374 
375  /*l
376  *b Description:
377  **
378  ** This function returns the desired time in seconds that the
379  ** scenario is currently at. This may be different than get_t(),
380  ** which advances only when the scenario's current tick changes.
381  **
382  *b Returns:
383  **
384  ** current time in seconds
385  */
386  float get_desired_t();
387 
388  /*l
389  *b Description:
390  **
391  ** This function sets the tout ("T Out") time of the scenario. What
392  ** will happen when the scenario reaches this time depends on a
393  ** number of factors. See update() for more information.
394  **
395  *b Returns:
396  **
397  ** 0 on success, -1 on failure
398  **
399  *b Callable From:
400  **
401  *- - C++
402  */
403  int set_tout(float tout);
404 
405  /*l
406  *b Description:
407  **
408  ** This function returns the tout time of the scenario. This is the
409  ** time at which a scenario is designed to end.
410  **
411  ** See set_tout() and update().
412  **
413  *b Returns:
414  **
415  ** tout of scenario
416  */
417  float get_tout();
418 
419  /*l
420  *b Description:
421  **
422  ** This function sets what will happen when the scenario reaches its
423  ** tout time. If set to 0, the scenario will ignore the tout time
424  ** and continue indefinitely.
425  **
426  ** See update() for more information.
427  */
428  void set_tout_enabled(int tout_enabled);
429 
430  /*l
431  *b Description:
432  **
433  ** This function returns the whether tout is enabled.
434  **
435  ** See set_tout_enabled() and update().
436  **
437  *b Returns:
438  **
439  ** 1 if tout enabled, 0 if not
440  */
441  int get_tout_enabled();
442 
443  /*l
444  *b Description:
445  **
446  ** This function returns whether the scenario is designed to loop
447  ** when the scenario's tout time is reached.
448  **
449  ** See update() for more information about looping.
450  **
451  *b Returns:
452  **
453  ** 0 if no loop desired; 1 if loop desired
454  */
455  int get_playback_loop();
456 
457  /*l
458  *b Description:
459  **
460  ** This function returns the most recent setting of set_tick_dt().
461  */
462  float get_tick_dt();
463 
464  /*l
465  *b Returns:
466  **
467  ** This function returns the most recent setting of
468  ** set_ticks_can_be_dropped().
469  */
470  int get_ticks_can_be_dropped();
471 
472  /*l
473  *b Description:
474  **
475  ** This function sets whether a scenario can "drop" ticks in order to
476  ** catch up if it falls behind.
477  **
478  ** Scenario updates progress in discrete time steps called ticks (see
479  ** set_tick_dt() and update()). If the difference in times specified
480  ** in subsequent calls to update() is greater than the tick dt, which
481  ** can happen if calls to update() are taking too long because the
482  ** scenario is too complex or if the caller is attempting to "fast
483  ** forward" to a particular time in the scenario, the scenario may
484  ** skip processing of intermediate ticks in order to catch up.
485  **
486  ** The scenario will not consider itself behind until the number of
487  ** ticks covered by a particular call to update() is equal to or
488  ** greater than the value set by set_max_ticks_behind_until_drop().
489  **
490  ** Dropping ticks, while it improves performance, may have unintended
491  ** side effects, including:
492  **
493  *- - event beads of characters on paths that fall on the dropped
494  *- ticks -- including aim beads, decision beads, gaze beads, and
495  *- script beads -- will not be evaluated and will therefore have
496  *- no effect on the scenario
497  *- - review playback of characters (see
498  *- diguyCharacter::set_history_type()) over the dropped intervals
499  *- will be choppy
500  **
501  ** Not dropping ticks also has potential side effects:
502  **
503  *- - if a scenario is falling behind more and more on each call
504  *- to update(), it may never be able to catch up and performance
505  *- of DI-Guy will increasingly degrade
506  **
507  ** The default setting is that ticks can be dropped.
508  **
509  *b Arguments:
510  **
511  *a ticks_can_be_dropped - pass 1 for ticks to be dropped; else
512  *a pass 0
513  */
514  void set_ticks_can_be_dropped(int ticks_can_be_dropped);
515 
516  /*l
517  *b Returns:
518  **
519  ** This function returns the most recent setting of
520  ** set_max_ticks_behind_until_drop().
521  */
522  long get_max_ticks_behind_until_drop();
523 
524  /*l
525  *b Description:
526  **
527  ** This function sets how many ticks a scenario must be behind before
528  ** it starts dropping ticks in order to catch up.
529  **
530  ** For a discussion of how a scenario may fall behind, see
531  ** set_ticks_can_be_dropped().
532  **
533  ** Note that if ticks cannot be dropped, (e.g., 0 is passed to
534  ** set_ticks_can_be_dropped()) this function will have no effect.
535  **
536  ** The default value is 0 in the DI-Guy SDK, In DI-Guy Scenario it is 2.
537  **
538  *b Arguments:
539  **
540  *a max_ticks_behind_until_drop - how many ticks a scenario must
541  *a be behind until it drops ticks
542  */
543  void set_max_ticks_behind_until_drop(long max_ticks_behind_until_drop);
544 
545  /*l
546  *b Description:
547  **
548  ** This function sets the current playback mode of DI-Guy Scenario.
549  ** It currently will have no effect in applications using the DI-Guy
550  ** API.
551  **
552  *b Arguments:
553  **
554  *a playback_mode - new playback mode
555  **
556  *b Returns:
557  **
558  ** 0 on success, -1 on failure
559  */
560  int set_playback_mode(diguyScenarioPlaybackMode playback_mode);
561 
562  /*l
563  *b Description:
564  **
565  ** This function is shorthand for the function call
566  ** set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_STOP). It is
567  ** useful for pausing the scenario in decisions and decision beads.
568  **
569  *b Returns:
570  **
571  ** 0 on success, -1 on failure
572  **
573  *b Callable From:
574  **
575  *- - C++
576  *- - Script
577  *- - Decision
578  */
579  int set_playback_mode_stop();
580 
581  /*l
582  *b Description:
583  **
584  ** This function is shorthand for the function call
585  ** set_playback_mode(DIGUY_SCENARIO_PLAYBACK_MODE_PLAY). It is
586  ** useful for resuming a paused scenario in decisions and decision
587  ** beads.
588  **
589  *b Returns:
590  **
591  ** 0 on success, -1 on failure
592  **
593  *b Callable From:
594  **
595  *- - C++
596  *- - Script
597  *- - Decision
598  */
599  int set_playback_mode_play();
600 
601  /*l
602  *b Returns:
603  **
604  ** current playback mode as set by set_playback_mode() or the
605  ** DI-Guy Scenario user interface
606  */
607  diguyScenarioPlaybackMode get_playback_mode();
608 
609  /*l
610  *b Description:
611  **
612  ** This function derives a dt based on an input dt (usually derived
613  ** from change in realtime from previous to current frame) and the
614  ** scenario's current playback mode. The resulting dt can then be
615  ** used to advance the time passed to diguyScenario::update() so that
616  ** it emulates the effect of the VCR buttons in DI-Guy Scenario.
617  **
618  ** This function does not change the scenario's current time or
619  ** playback mode.
620  **
621  ** Examples based on a dt_in of 0.03 seconds:
622  **
623  *- - DIGUY_SCENARIO_PLAYBACK_MODE_STOP: derived_dt = 0.0
624  *- - DIGUY_SCENARIO_PLAYBACK_MODE_PLAY: derived_dt = 0.03
625  *- - DIGUY_SCENARIO_PLAYBACK_MODE_PLAY_REVERSE: derived_dt = -0.03
626  *- - DIGUY_SCENARIO_PLAYBACK_MODE_FF: derived_dt = 0.12
627  *- - DIGUY_SCENARIO_PLAYBACK_MODE_FF_REVERSE: derived_dt = -0.12
628  *- - DIGUY_SCENARIO_PLAYBACK_MODE_SS: derived_dt = frame dt
629  *- - DIGUY_SCENARIO_PLAYBACK_MODE_SS_REVERSE: derived_dt = - frame dt
630  *- - DIGUY_SCENARIO_PLAYBACK_MODE_REWIND: derived_dt = - scenario t
631  **
632  ** Note that the playback mode should be set to
633  ** DIGUY_SCENARIO_PLAYBACK_MODE_STOP after time advances in either of
634  ** the single step ("SS") modes or the rewind mode.
635  **
636  *b Arguments:
637  **
638  *a dt_in - delta time in seconds from advancing simulation time
639  */
640  float derive_playback_mode_dt(float dt_in);
641 
642  /*l
643  *b Description:
644  **
645  ** This function resets all scenario characters, signals, variables,
646  ** and all other scenario objects to their original state. Scenario
647  ** time will be set to 0.
648  **
649  *b Returns:
650  **
651  ** 0 on success, -1 on failure
652  */
653  int reset();
654 
655 
656 /*****************************************************************************/
661 #ifdef CPLUSPLUS_ONLY
662 
663  /*l
664  *b Description:
665  **
666  ** This function loads the specified scenario. Any previously loaded
667  ** scenario objects will be deleted. To merge a scenario into the
668  ** existing scenario (load without deleting existing objects), use
669  ** the call merge().
670  **
671  ** The passed filename can be either a ".dss" file, which is a DI-Guy
672  ** Scenario file, or a ".dsr" file, which is a DI-Guy Review file.
673  **
674  ** Once the file has been loaded an implicit reset() will occur.
675  **
676  *b Arguments:
677  **
678  *a filename - filename of scenario to be loaded
679  **
680  *b Returns:
681  **
682  ** 0 on success, -1 on failure
683  **
684  *b Callable From:
685  **
686  *- - C++
687  */
688  int load(const char* filename);
689 
690  /*l
691  *b Description:
692  **
693  ** Saves the scenario into its current filename. This filename will
694  ** be the most recent of:
695  **
696  *- - the filename used in a load() function call
697  *- - the filename used in a save_as() function call
698  **
699  ** The filename that will be used can be retrieved using the
700  ** get_filename() or get_filename_without_directory() functions.
701  **
702  ** Once saved the "unsaved" flag (as returned by get_unsaved()) will
703  ** be set to 0.
704  **
705  *b Returns:
706  **
707  ** 0 on success, -1 on failure
708  **
709  *b Callable From:
710  **
711  *- - C++
712  */
713  int save();
714 
715  /*l
716  *b Description:
717  **
718  ** Similar to save(), but new filename is specified by the filename
719  ** argument.
720  **
721  *b Arguments:
722  **
723  *a filename - new filename of scenario
724  **
725  *b Returns:
726  **
727  ** 0 on success, -1 on failure
728  **
729  *b Callable From:
730  **
731  *- - C++
732  */
733  int save_as(const char* filename);
734 
735  /*l
736  *b Description:
737  **
738  ** Returns the most recent of:
739  **
740  *- - the filename used in a load() function call
741  *- - the filename used in a save_as() function call
742  **
743  *b Returns:
744  **
745  ** filename of saved scenario
746  **
747  *b Callable From:
748  **
749  *- - C++
750  */
751  const char* get_filename();
752 
753  /*l
754  *b Description:
755  **
756  ** Similar to get_filename(), but with any leading directories
757  ** removed.
758  **
759  *b Callable From:
760  **
761  *- - C++
762  */
763  const char* get_filename_without_directory();
764 
765  /*l
766  *b Returns:
767  **
768  ** 1 if scenario has been modified since save or load, else 0
769  **
770  *b Callable From:
771  **
772  *- - C++
773  */
774  int get_unsaved();
775 
776  /*l
777  *b Description:
778  **
779  ** Manually sets the "unsaved" flag to the passed value.
780  **
781  *b Arguments:
782  **
783  *a unsaved - new unsaved status; 1 for unsaved, 0 for saved
784  **
785  *b Callable From:
786  **
787  *- - C++
788  */
789  void set_unsaved(int unsaved);
790 
791 #endif // CPLUSPLUS_ONLY
792 
793 /*****************************************************************************/
799 #ifdef CPLUSPLUS_ONLY
800 
801  /*l
802  *b Description:
803  **
804  ** This function draws all visible elements of the loaded scenario in
805  ** immediate mode graphics environments (see below). This is the
806  ** equivalent of calling draw_pass1(), immediately followed by
807  ** draw_pass2(), immediately followed by post_draw().
808  **
809  ** Note that any character graphics culling, far position rendering,
810  ** etc., depend on the render camera set by the set_render_camera()
811  ** function. A render camera does not always need to be set; see
812  ** set_render_camera() for more details.
813  **
814  *b Returns:
815  **
816  ** 0 on success, -1 on failure
817  **
818  *i OpenGL Version:
819  **
820  ** This function immediately draws all scenario elements. Either
821  ** this function, or draw_pass1(), draw_pass2(), and post_draw(),
822  ** should be called once per frame.
823  **
824  *b Callable From:
825  **
826  *- - C++
827  */
828  int draw();
829 
830  /*l
831  *b Description:
832  **
833  ** This function, along with draw_pass2(), allows the drawing of
834  ** opaque and transparent polygons to be separated. This function
835  ** draws all opaque polygons.
836  **
837  *b Returns:
838  **
839  ** 0 on success, -1 on failure
840  **
841  *i OpenGL Version:
842  **
843  ** This function immediately draws the opaque scenario elements.
844  ** Either this function or draw() should be called once per frame.
845  **
846  *b Callable From:
847  **
848  *- - C++
849  */
850  int draw_pass1();
851 
852  /*l
853  *b Description:
854  **
855  ** Same as draw_pass1(), but draws transparent scenario elements.
856  ** The also_call_post_draw argument is set to 1 for backwards
857  ** compatibility.
858  **
859  *b Callable From:
860  **
861  *- - C++
862  */
863  int draw_pass2(int also_call_post_draw = 1);
864 
865  /*l
866  *b Description:
867  **
868  ** Clears all the culling bits state for various characters, this should be called before any drawing is done.
869  ** It allows for multiple draw passes culling state info to get accumulated together. This is needed to
870  ** efficiently avoiding updating graphics classes for characters that are out of all rendering viewports. If a
871  ** character is generally visible we will update it's state with our multi-threaded pipeline. If it's not visible.
872  ** then we won't update it until it's actually drawn. In retained mode renderers diguyCharacter::set_is_culled(0)
873  ** must be set for each character that is drawn so that we know to update it's state in the faster manor.
874  **
875  *b Callable From:
876  **
877  *- - C++
878  */
879  void pre_draw_cull_state_reset();
880 
881  /*l
882  *b Description:
883  **
884  ** Saves all the culling bits for various characters, should be called after all drawing is done so that the next
885  ** call to update() has reasonable culling information to work with. See pre_draw_cull_state_reset() for more
886  ** information about graphics update culling.
887  **
888  *b Callable From:
889  **
890  *- - C++
891  */
892  void post_draw_cull_state_save();
893 
894 
895 
896  /*l
897  *b Description:
898  **
899  ** This function draws visual elements that must be drawn after the
900  ** main render has been done.
901  **
902  ** Note that this function is called automatically by the draw()
903  ** call. Only call this function if draw() is not called; e.g.,
904  ** if draw_pass1() and draw_pass2() are used.
905  **
906  ** This function can be called from scene graph type renderers which
907  ** typically don't need or want to have the draw() function called.
908  **
909  *b Arguments:
910  **
911  *a call_plugins_post_draw - pass 1 to call plugin post_draw()
912  *a functions
913  *a call_lua_packages_draw - pass 1 to call lua package draw functions
914  *a call_post_draw_callback - pass 1 to invoke callbacks with callback
915  *a id CALLBACK_ID_POST_DRAW
916  **
917  *b Returns:
918  **
919  ** 0 on success, -1 on failure
920  */
921  int post_draw(int call_plugins_post_draw = 1,
922  int call_lua_packages_draw = 1,
923  int call_post_draw_callback = 1);
924 
925  /*l
926  *b Description:
927  **
928  ** This function sets the attachment point that to be used for
929  ** graphics created by the library.
930  **
931  *b Arguments:
932  **
933  *a graphics_attach_ptr - this is a pointer to a group-type object;
934  *a the specific type is dependent on graphics
935  *a environment
936  **
937  *b Returns:
938  **
939  ** 0 on success, -1 on failure
940  **
941  *i OpenGL Version:
942  **
943  ** This function does not have any effect.
944  **
945  *i Direct3D Version:
946  **
947  ** The passed pointer should be a LPDIRECT3DRMFRAME2.
948  **
949  *e LPDIRECT3DRMFRAME2 attach_frame = get_scene_frame();
950  *e scenario->set_graphics_attach_ptr(attach_frame);
951  **
952  **
953  *b Callable From:
954  **
955  *- - C++
956  */
957  int set_graphics_attach_ptr(void* graphics_attach_ptr);
958 
959 #endif // CPLUSPLUS_ONLY
960 
961 
962 /*****************************************************************************/
972  /*l
973  *b Description:
974  **
975  ** This function creates a merge settings object. This object can
976  ** allow for fine control over which elements in a scenario are
977  ** merged during a merge() call, and what to do if there is a
978  ** collision with an existing element.
979  **
980  ** Once the initial settings are made based on the initial_settings
981  ** argument, the settings can be fine-tuned by calling member
982  ** functions of the diguyScenarioMergeSettings object.
983  **
984  ** Destroy the object with a call to destroy_merge_settings().
985  **
986  *b Arguments:
987  **
988  *a initial_settings - what the initial settings should be when
989  *a the object is created
990  **
991  *i DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT
992  **
993  *a scenario settings - DIGUY_MERGE_FLAG_DONT_MERGE
994  *a current view settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
995  *a character - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
996  *a decision - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
997  *a formation - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
998  *a group - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
999  *a guide - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1000  *a info popup - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1001  *a library function - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1002  *a script - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1003  *a sensor region - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1004  *a signal - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1005  *a variables - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1006  *a camera settings - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1007  *a face exp - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1008  *a fog settings - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1009  *a light settings - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1010  *a particle system - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1011  *a path shape - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1012  *a scene object - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1013  *a scene object grid - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1014  *a sound - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1015  **
1016  *i DIGUY_MERGE_INITIAL_SETTINGS_MERGE_EVERYTHING
1017  **
1018  *a scenario settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
1019  *a current view settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
1020  *a character - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1021  *a decision - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1022  *a formation - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1023  *a group - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1024  *a guide - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1025  *a info popup - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1026  *a library function - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1027  *a script - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1028  *a sensor region - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1029  *a signal - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1030  *a variables - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1031  *a camera settings - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1032  *a face exp - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1033  *a fog settings - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1034  *a light settings - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1035  *a particle system - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1036  *a path shape - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1037  *a scene object - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1038  *a scene object grid - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1039  *a sound - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1040  **
1041  *i DIGUY_MERGE_INITIAL_SETTINGS_MERGE_NOTHING
1042  **
1043  *a scenario settings - DIGUY_MERGE_FLAG_DONT_MERGE
1044  *a current view settings - DIGUY_MERGE_FLAG_DONT_MERGE
1045  *a character - DIGUY_MERGE_FLAG_DONT_MERGE
1046  *a decision - DIGUY_MERGE_FLAG_DONT_MERGE
1047  *a formation - DIGUY_MERGE_FLAG_DONT_MERGE
1048  *a group - DIGUY_MERGE_FLAG_DONT_MERGE
1049  *a guide - DIGUY_MERGE_FLAG_DONT_MERGE
1050  *a info popup - DIGUY_MERGE_FLAG_DONT_MERGE
1051  *a library function - DIGUY_MERGE_FLAG_DONT_MERGE
1052  *a script - DIGUY_MERGE_FLAG_DONT_MERGE
1053  *a sensor region - DIGUY_MERGE_FLAG_DONT_MERGE
1054  *a signal - DIGUY_MERGE_FLAG_DONT_MERGE
1055  *a variables - DIGUY_MERGE_FLAG_DONT_MERGE
1056  *a camera settings - DIGUY_MERGE_FLAG_DONT_MERGE
1057  *a face exp - DIGUY_MERGE_FLAG_DONT_MERGE
1058  *a fog settings - DIGUY_MERGE_FLAG_DONT_MERGE
1059  *a light settings - DIGUY_MERGE_FLAG_DONT_MERGE
1060  *a particle system - DIGUY_MERGE_FLAG_DONT_MERGE
1061  *a path shape - DIGUY_MERGE_FLAG_DONT_MERGE
1062  *a scene object - DIGUY_MERGE_FLAG_DONT_MERGE
1063  *a scene object grid - DIGUY_MERGE_FLAG_DONT_MERGE
1064  *a sound - DIGUY_MERGE_FLAG_DONT_MERGE
1065  **
1066  *i DIGUY_MERGE_INITIAL_SETTINGS_DIGUY6_COMPATIBLE
1067  **
1068  *a scenario settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
1069  *a current view settings - DIGUY_MERGE_FLAG_OVERWRITE_EXISTING
1070  *a character - DIGUY_MERGE_FLAG_RENAME_MERGED_AND_WARN
1071  *a decision - DIGUY_MERGE_FLAG_KEEP_BOTH
1072  *a formation - DIGUY_MERGE_FLAG_KEEP_BOTH
1073  *a group - DIGUY_MERGE_FLAG_KEEP_BOTH
1074  *a guide - DIGUY_MERGE_FLAG_KEEP_BOTH
1075  *a info popup - DIGUY_MERGE_FLAG_KEEP_BOTH
1076  *a library function - DIGUY_MERGE_FLAG_KEEP_BOTH
1077  *a script - DIGUY_MERGE_FLAG_KEEP_BOTH
1078  *a sensor region - DIGUY_MERGE_FLAG_KEEP_BOTH
1079  *a signal - DIGUY_MERGE_FLAG_KEEP_BOTH
1080  *a variables - DIGUY_MERGE_FLAG_KEEP_BOTH
1081  *a camera settings - DIGUY_MERGE_FLAG_KEEP_BOTH
1082  *a face exp - DIGUY_MERGE_FLAG_KEEP_BOTH
1083  *a fog settings - DIGUY_MERGE_FLAG_KEEP_BOTH
1084  *a light settings - DIGUY_MERGE_FLAG_KEEP_BOTH
1085  *a particle system - DIGUY_MERGE_FLAG_KEEP_EXISTING_ONLY_AND_WARN
1086  *a path shape - DIGUY_MERGE_FLAG_KEEP_BOTH
1087  *a scene object - DIGUY_MERGE_FLAG_RENAME_MERGED_IF_NOT_EQUAL
1088  *a scene object grid - DIGUY_MERGE_FLAG_KEEP_BOTH
1089  *a sound - DIGUY_MERGE_FLAG_KEEP_BOTH
1090  **
1091  *b Returns:
1092  **
1093  ** object of type diguyScenarioMergeSettings
1094  */
1095  diguyScenarioMergeSettings* create_merge_settings(diguyScenarioMergeInitialSettings initial_settings = DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT);
1096 
1097  /*l
1098  *b Description:
1099  **
1100  ** This function destroys a merge settings object created by
1101  ** a call to create_merge_settings().
1102  */
1103  void destroy_merge_settings(diguyScenarioMergeSettings* merge_settings);
1104 
1105  /*l
1106  *b Description:
1107  **
1108  ** This function merges the specified scenario. Any previously loaded
1109  ** scenario elements will be retained, depending on settings in
1110  ** the merge_settings argument.
1111  **
1112  *b Arguments:
1113  **
1114  *a filename - filename of scenario to be merged
1115  *a merge_settings - object that controls how elements are merged;
1116  *a pass NULL for default merge handling
1117  **
1118  *b Returns:
1119  **
1120  ** 0 on success, -1 on failure
1121  */
1122  int merge(const char* filename,
1123  diguyScenarioMergeSettings* merge_settings = NULL);
1124 
1125  /*l
1126  *b Description:
1127  **
1128  * Documentation Pending
1129  **
1130  ** This function performs a "micro merge", allowing a scenario to
1131  ** merge in the contents of a text string representing a single
1132  ** object.
1133  **
1134  ** On example of use is for a Lua Package to contain a number of
1135  ** text strings representing particle systems or sounds that an agent
1136  ** need will need. When needed objects in text form can be merged
1137  ** into the scenario using this function.
1138  **
1139  ** The DI-Guy Scenario Particle System page has a "Display Object
1140  ** Text" button that can display the object text of a particle system
1141  ** that is appropriate for use by this function. Other object pages
1142  ** that have this button are Sound, Formation, and Crowd Profile.
1143  **
1144  ** Text can also be taken directly from .dss files.
1145  **
1146  ** See also the diguyCharacter::merge_object() function.
1147  **
1148  ** Note: the parser is very sensitive to tabs and formatting!
1149  */
1150  int merge_object(const char* string);
1151 
1152  /*l
1153  *b Description:
1154  **
1155  ** This function makes the objects in the specified library available
1156  ** for use in the scenario.
1157  **
1158  ** Object libraries allow new content to be created in one scenario
1159  ** and automatically shared to other scenarios. When including a
1160  ** library, objects that are already in the scenario are preserved.
1161  **
1162  ** A library with specified name must be available for inclusion.
1163  ** Object libraries are located in the
1164  ** $(DIGUY)/config/diguy/object_libraries and
1165  ** $(DIGUY)/custom/config/diguy/object_libraries directories. The
1166  ** filename for the library must be "library_[libname].cfg".
1167  **
1168  ** Available object libraries in these directories will automatically
1169  ** be detected by the scenario, but objects in the libraries will not
1170  ** be included in the scenario until this function is called.
1171  **
1172  ** For example, if the objects in the file "library_crowd_sounds.cfg"
1173  ** should be made available in the scenario, the library name
1174  ** "crowd_sounds" should be passed into this function.
1175  **
1176  ** Currently the following object types can be in libraries:
1177  **
1178  *- - particle system
1179  *- - formation
1180  *- - crowd profile
1181  *- - sound
1182  **
1183  *b Arguments:
1184  **
1185  *a library_name - name of library
1186  **
1187  *b Returns:
1188  **
1189  ** 0 on success, -1 on failure
1190  */
1191  int include_object_library(const char* library_name);
1192 
1193  /*l
1194  *b Description:
1195  **
1196  ** This function is the opposite of include_object_library().
1197  ** Objects in the named library are made unavailable to the scenario.
1198  **
1199  *b Arguments:
1200  **
1201  *a library_name - name of library
1202  **
1203  *b Returns:
1204  **
1205  ** 0 on success, -1 on failure
1206  */
1207  int uninclude_object_library(const char* library_name);
1208 
1209 
1210 /*****************************************************************************/
1220  /******************************************************
1221  **
1222  *4 Datetime Functions
1223  **
1224  */
1225 
1226  /*l
1227  *b Description:
1228  **
1229  ** This function will set what the current datetime will be when the
1230  ** scanario is reset.
1231  **
1232  ** Pass -1 for values that should be set based on current datetime.
1233  **
1234  ** Note that if set_base_datetime_default_to_now() and
1235  ** set_base_datetime_default_to_today() can override these values.
1236  */
1237  void set_base_datetime(int year = -1,
1238  int month = -1,
1239  int day = -1,
1240  int hour = -1,
1241  int minute = -1,
1242  int second = -1,
1243  int msec = -1);
1244 
1245  /*l
1246  *b Description:
1247  **
1248  ** Similar to set_base_datetime(), but datetime is stored in the
1249  ** passed string, formatted in the passed format string.
1250  */
1251  void set_base_datetime(const char* datetime_string,
1252  const char* format);
1253 
1254  /*l
1255  *b Description:
1256  **
1257  ** Retrieves the base datetime. Pass NULL for arguments that aren't
1258  ** needed.
1259  */
1260  void get_base_datetime(int* year = NULL,
1261  int* month = NULL,
1262  int* day = NULL,
1263  int* hour = NULL,
1264  int* minute = NULL,
1265  int* second = NULL,
1266  int* msec = NULL);
1267 
1268  /*l
1269  *b Description:
1270  **
1271  ** Setting this value to 1 will cause the time part of the datetime to
1272  ** be set to whatever "real" time it is when reset() is called,
1273  ** instead of the time stored in the base datetime as set by
1274  ** set_base_datetime(). For example, if it is 10:30 AM in "real time"
1275  ** when the scenario is reset, the current time will be set to
1276  ** 10:30:00:000 on reset.
1277  **
1278  ** Setting this value to 0 will restore the default behavior.
1279  */
1280  void set_base_datetime_default_to_now(int to_now);
1281 
1282  /*l
1283  *b Returns:
1284  **
1285  ** 1 if the current time will be set to the "real time" on reset,
1286  ** 0 is not
1287  */
1288  int get_base_datetime_default_to_now();
1289 
1290  /*l
1291  *b Description:
1292  **
1293  ** Similar to set_base_datetime_default_to_now(), but for the date
1294  ** part of the datetime.
1295  */
1296  void set_base_datetime_default_to_today(int to_today);
1297 
1298  /*l
1299  *b Returns:
1300  **
1301  ** 1 if the current date will be set to the "real date" on reset,
1302  ** 0 is not
1303  */
1304  int get_base_datetime_default_to_today();
1305 
1306  /*l
1307  *b Description:
1308  **
1309  ** Allows current datetime to be explicitly set. Note that in most
1310  ** cases the current datetime should be set by the base datetime plus
1311  ** how much time has advanced in the scenario.
1312  **
1313  ** This function can be useful if the datetime needs to be syncronized
1314  ** with that from another source, say, from network exercise data.
1315  */
1316  void set_current_datetime(int year = -1,
1317  int month = -1,
1318  int day = -1,
1319  int hour = -1,
1320  int minute = -1,
1321  int second = -1,
1322  int msec = -1);
1323 
1324  /*l
1325  *b Description:
1326  **
1327  ** Similar to set_current_datetime(), but datetime is stored in the
1328  ** passed string, formatted in the passed format string.
1329  */
1330  void set_current_datetime(const char* datetime_string,
1331  const char* format);
1332 
1333  /*l
1334  *b Description:
1335  **
1336  ** Retrieves the current datetime. Pass NULL for arguments that
1337  ** aren't needed.
1338  */
1339  void get_current_datetime(int* year = NULL,
1340  int* month = NULL,
1341  int* day = NULL,
1342  int* hour = NULL,
1343  int* minute = NULL,
1344  int* second = NULL,
1345  int* msec = NULL);
1346 
1347  /*l
1348  *b Description:
1349  **
1350  ** Retrieves the current datetime in string format.
1351  **
1352  *b Arguments:
1353  **
1354  *a format - format returned string should be in; pass NULL for default
1355  *a "M/d/yyyy h:mm:ss AP" format
1356  */
1357  const char* get_current_datetime_string(const char* format);
1358 
1359  /*l
1360  *b Description:
1361  **
1362  ** Pass 1 to specify that datetimes use UTC time, 0 to specify they
1363  ** are local time.
1364  */
1365  void set_datetimes_are_utc(int are_utc);
1366 
1367  /*l
1368  *b Returns:
1369  **
1370  ** 1 if datetimes use UTC time, 0 if not
1371  */
1372  int get_datetimes_are_utc();
1373 
1374  /*l
1375  *b Description:
1376  **
1377  ** If datetimes use UTC time, this function sets the offset hours
1378  ** of the current time from UTC.
1379  */
1380  void set_utc_offset_hours(float utc_offset_hours);
1381 
1382  /*l
1383  *b Returns:
1384  **
1385  ** offset in hours of datetimes from UTC
1386  */
1387  float get_utc_offset_hours();
1388 
1389  /*l
1390  *b Description:
1391  **
1392  ** Documentation Pending
1393  */
1394  void set_use_local_tz_utc_offset_hours(int use_local_tz);
1395 
1396  /*l
1397  *b Description:
1398  **
1399  ** Documentation Pending
1400  */
1401  int get_use_local_tz_utc_offset_hours();
1402 
1403  /*l
1404  *b Description:
1405  **
1406  ** Documentation Pending
1407  */
1408  void set_current_datetime_advance_method(diguyDatetimeAdvanceMethod advance_method);
1409 
1410  /*l
1411  *b Description:
1412  **
1413  ** Documentation Pending
1414  */
1415  diguyDatetimeAdvanceMethod get_current_datetime_advance_method();
1416 
1417  /*l
1418  *b Description:
1419  **
1420  ** Documentation Pending
1421  */
1422  void set_current_datetime_advance_factor(float advance_factor);
1423 
1424  /*l
1425  *b Description:
1426  **
1427  ** Documentation Pending
1428  */
1429  float get_current_datetime_advance_factor();
1430 
1431  /*l
1432  *b Description:
1433  **
1434  ** Documentation Pending
1435  */
1436  void get_network_datetime(int* year = NULL,
1437  int* month = NULL,
1438  int* day = NULL,
1439  int* hour = NULL,
1440  int* minute = NULL,
1441  int* second = NULL,
1442  int* msec = NULL);
1443 
1444 
1445  /******************************************************
1446  **
1447  *4 Simple Time Functions
1448  **
1449  */
1450 
1451  /*l
1452  *b Description:
1453  **
1454  ** This function sets the time of day which corresponds to scenario
1455  ** tin. It is a wall-clock time, and has no date content.
1456  **
1457  ** Note that if more detailed time and date information is needed
1458  ** refer to the "datetime" functions.
1459  **
1460  *b Arguments:
1461  **
1462  *a t - number of seconds after midnight; zero means
1463  *a midnight; 86399.0 means 11:59:59 pm
1464  **
1465  *b Returns:
1466  **
1467  ** 0 on success, -1 on failure
1468  */
1469  int set_tin_time_of_day(float t);
1470 
1471  /*l
1472  *b Description:
1473  **
1474  ** This function returns what time of day corresponds to scenario tin.
1475  ** It is a wall-clock time, and has no date content.
1476  **
1477  ** See set_tin_time_of_day().
1478  **
1479  ** Note that if more detailed time and date information is needed
1480  ** refer to the "datetime" functions.
1481  **
1482  *b Returns:
1483  **
1484  ** number of seconds after midnight
1485  */
1486  float get_tin_time_of_day();
1487 
1488  /*l
1489  *b Description:
1490  **
1491  ** This function returns what the simulated time of day is right now.
1492  ** It is computed by adding (scenario t - tin) to the value passed to
1493  ** set_tin_time_of_day();
1494  **
1495  ** See set_tin_time_of_day().
1496  **
1497  ** Note that if more detailed time and date information is needed
1498  ** refer to the "datetime" functions.
1499  **
1500  *b Returns:
1501  **
1502  ** number of seconds after midnight (simulated time of day)
1503  */
1504  float get_time_of_day();
1505 
1506 
1507 /*****************************************************************************/
1517 #ifdef CPLUSPLUS_ONLY
1518 
1519  /*l
1520  *b Description:
1521  **
1522  ** This function adds an appearance with the given name to the list of
1523  ** available appearances. If an appearance with the given name
1524  ** already exists the operation will fail and a message will be
1525  ** printed at debug level to the output log.
1526  **
1527  ** Internal copies are made of the passed strings.
1528  **
1529  *b Arguments:
1530  **
1531  *a appearance - name of the appearance
1532  *a equipment_list - NULL-terminated list of equipment that
1533  *a makes up the appearance
1534  *a character_types - NULL-terminated list of character types
1535  *a that this appearance will be available to
1536  *a actor - name of the actor this appearance fits
1537  **
1538  ** If NULL is passed for the actor argument the actor will
1539  ** be set to match the actor of the first character type
1540  ** in the character_types array.
1541  **
1542  *b Returns:
1543  **
1544  ** 0 on success, -1 on failure
1545  **
1546  *b Callable From:
1547  **
1548  *- - C++
1549  */
1550  int add_appearance(const char* appearance,
1551  char** equipment_list,
1552  char** character_types,
1553  const char* actor);
1554 
1555  /*l
1556  *b Description:
1557  **
1558  ** This function is similar to add_appearance(), but adds
1559  ** equipment_list shapes to an existing appearance.
1560  **
1561  ** The character types that the new appearance will be available to
1562  ** will match that of the specified existing appearance.
1563  **
1564  *b Arguments:
1565  **
1566  *a appearance - name of the new appearance
1567  *a existing_appearance - name of the existing appearance on which to
1568  *a base new appearance
1569  *a equipment_list - NULL-terminated list of equipment to add to
1570  ** the existing appearance
1571  **
1572  *b Returns:
1573  **
1574  ** 0 on success, -1 on failure
1575  **
1576  *b Callable From:
1577  **
1578  *- - C++
1579  */
1580  int add_appearance_based_on_existing_appearance(const char* appearance,
1581  const char* existing_appearance,
1582  char** equipment_list);
1583 
1584  /*l
1585  *b Description:
1586  **
1587  ** This function removes an appearance with the given name
1588  ** from the list of available appearances. If an appearance with
1589  ** the given name does not exist the operation will fail and
1590  ** a message will be printed at debug level to the output log.
1591  **
1592  *b NOTE:
1593  **
1594  ** Currently no check is made for whether the appearance is
1595  ** in use by a character. Removing an in-use appearance will
1596  ** result in undefined behavior.
1597  **
1598  *b Arguments:
1599  **
1600  *a appearance - name of the appearance
1601  **
1602  *b Returns:
1603  **
1604  ** 0 on success, -1 on failure
1605  **
1606  *b Callable From:
1607  **
1608  *- - C++
1609  */
1610  int remove_appearance(const char* appearance);
1611 
1612 #endif // CPLUSPLUS_ONLY
1613 
1614  /*l
1615  *b Description:
1616  **
1617  ** This function returns the number of character types associated with
1618  ** the given appearance, if any.
1619  **
1620  *b Arguments:
1621  **
1622  *a appearance - name of the appearance
1623  **
1624  *b Returns:
1625  **
1626  ** the number of character types, or 0
1627  */
1628  int get_num_character_types_with_appearance(const char* appearance_name);
1629 
1630  /*l
1631  *b Description:
1632  **
1633  ** This function returns one of the character types associated with
1634  ** the appearance, if any exists
1635  **
1636  *b Arguments:
1637  **
1638  *a appearance - name of the appearance
1639  *a index - which character type of the set to return
1640  **
1641  *b Returns:
1642  **
1643  ** a character type name on success, "none" on failure
1644  */
1645  const char *get_character_type_from_appearance(const char* appearance_name, int index = 0);
1646 
1647 
1648 /*****************************************************************************/
1658  /*l
1659  *b Description:
1660  **
1661  ** Gets the hand item class associated with a character type.
1662  **
1663  *b Arguments:
1664  **
1665  *a char_type_name - name of the char type
1666  *a appearance_name - optional appearance name, which might yield
1667  *a different results
1668  **
1669  *b Returns:
1670  **
1671  ** Name of hand item class on success, "none" on failure
1672  */
1673  const char *get_hand_item_class(const char *char_type_name, const char *appearance_name = NULL);
1674 
1675  /*l
1676  *b Description:
1677  **
1678  ** Gets the number of hand items in a particular hand item class.
1679  **
1680  *b Arguments:
1681  **
1682  *a hand_item_class - name of hand item class
1683  **
1684  *b Returns:
1685  **
1686  ** Number of hand items in class
1687  */
1688  int get_num_hand_items_in_class(const char *hand_item_class);
1689 
1690  /*l
1691  *b Description:
1692  **
1693  ** Gets the name of a hand item within the set associated with
1694  ** a hand item class.
1695  **
1696  *b Arguments:
1697  **
1698  *a hand_item_class - name of hand item class
1699  *a index - index within set
1700  **
1701  *b Returns:
1702  **
1703  ** Name of hand item, or "none"
1704  */
1705  const char *get_hand_item_from_class(const char *hand_item_class, int index);
1706 
1707 /*****************************************************************************/
1717  /*l
1718  *b Description:
1719  **
1720  ** This function preloads all base motions and the default
1721  ** appearance for the specified character type.
1722  **
1723  ** This can be done during initialization to preload characters that
1724  ** will be needed later in a scenario, to avoid a hitch in frame rate
1725  ** when the characters are loaded.
1726  **
1727  *b Arguments:
1728  **
1729  *a character_type - character type name, as returned by
1730  *a get_character_type_at_index(), for example
1731  **
1732  *b Returns:
1733  **
1734  ** 0 on success, -1 on failure
1735  */
1736  int preload_character_type(const char* character_type);
1737 
1738  /*l
1739  *b Description:
1740  **
1741  ** This function preloads all geometry for the specified appearance.
1742  ** This can be done during initialization to preload geometry that
1743  ** will be needed later in a scenario, to avoid a hitch in frame rate
1744  ** when the geometry is loaded.
1745  **
1746  *b Arguments:
1747  **
1748  *a appearance - name of the appearance whose geometry is to be
1749  *a preloaded
1750  **
1751  *b Returns:
1752  **
1753  ** 0 on success, -1 on failure
1754  */
1755  int preload_appearance(const char* appearance);
1756 
1757  /*l
1758  *b Description:
1759  **
1760  ** This function preloads all motions for the specified gesture
1761  ** for the specified character type.
1762  **
1763  ** This can be done during initialization to preload gestures that
1764  ** will be needed later in a scenario, to avoid a hitch in frame rate
1765  ** when the motions are loaded.
1766  **
1767  *b Arguments:
1768  **
1769  *a character_type - character's type
1770  *a gesture_name - name of the gesture to preload
1771  **
1772  *b Returns:
1773  **
1774  ** 0 on success, -1 on failure
1775  */
1776  int preload_gesture(const char* character_type, const char* gesture_name);
1777 
1778 
1779 /*****************************************************************************/
1794  /*l
1795  *b Description:
1796  **
1797  ** This function enables character culling.
1798  **
1799  ** This function works only in the OpenGL version when a valid render
1800  ** camera is set.
1801  */
1802  void set_character_culling_enabled(int character_culling);
1803 
1804  /*l
1805  *b Description:
1806  **
1807  ** This function gets the state of character culling.
1808  **
1809  ** This function works only in the OpenGL version when a valid render
1810  ** camera is set.
1811  **
1812  *b Returns:
1813  **
1814  ** 1 if enabled, 0 if disabled.
1815  */
1816  int get_character_culling_enabled();
1817 
1818  /*l
1819  *b Description:
1820  **
1821  ** This function enables scene object culling.
1822  **
1823  ** This function works only in the OpenGL version when a
1824  ** valid render camera is set.
1825  */
1826  void set_scene_object_culling_enabled(int object_culling);
1827 
1828  /*l
1829  *b Description:
1830  **
1831  ** This function get the state of scene object culling.
1832  **
1833  ** This function works only in the OpenGL version when a
1834  ** valid render camera is set.
1835  **
1836  *b Returns:
1837  **
1838  ** 1 if enabled, 0 if disabled
1839  */
1840  int get_scene_object_culling_enabled();
1841 
1842  /*l
1843  *b Description:
1844  **
1845  ** This function enables scene object sub object culling.
1846  **
1847  ** This function works only in the OpenGL version when a
1848  ** valid render camera is set.
1849  */
1850  void set_scene_object_sub_culling_enabled(int object_culling);
1851 
1852  /*l
1853  *b Description:
1854  **
1855  ** This function get the state of scene object sub culling.
1856  **
1857  ** This function works only in the OpenGL version when a
1858  ** valid render camera is set.
1859  **
1860  *b Returns:
1861  **
1862  ** 1 if enabled, 0 if disabled
1863  */
1864  int get_scene_object_sub_culling_enabled();
1865 
1866  /*l
1867  *b Description:
1868  **
1869  ** This function enables visualizing a character's bounding
1870  ** volume.
1871  **
1872  ** This function works only in the OpenGL version when a
1873  ** valid render camera is set.
1874  */
1875  void set_character_visualize_bounds_enabled(int visualize_bounds);
1876 
1877  /*l
1878  *b Description:
1879  **
1880  ** This function get the state of character bounding volume
1881  ** visualization.
1882  **
1883  ** This function works only in the OpenGL version when a
1884  ** valid render camera is set.
1885  **
1886  *b Returns:
1887  **
1888  ** 1 if enabled, 0 if disabled
1889  */
1890  int get_character_visualize_bounds_enabled();
1891 
1892  /*l
1893  *b Description:
1894  **
1895  ** This function enables visualizing a scene object's bounding
1896  ** volume.
1897  **
1898  ** This function works only in the OpenGL version when a
1899  ** valid render camera is set.
1900  */
1901  void set_scene_object_visualize_bounds_enabled(int val);
1902 
1903  /*l
1904  *b Description:
1905  **
1906  ** This function gets the state of scene objects bounding volume
1907  ** visualization.
1908  **
1909  ** This function works only in the OpenGL version when a
1910  ** valid render camera is set.
1911  **
1912  *b Returns:
1913  **
1914  ** 1 if enabled, 0 if disabled
1915  */
1916  int get_scene_object_visualize_bounds_enabled();
1917 
1918 
1919 /*****************************************************************************/
1978  /*l
1979  *b Returns:
1980  **
1981  ** number of available character types
1982  */
1983  int get_num_character_types();
1984 
1985  /*l
1986  *b Returns:
1987  **
1988  ** the string identifying the character type at the given index
1989  **
1990  *b Arguments:
1991  **
1992  *a index - index of the character type; indices start at 0
1993  */
1994  const char* get_character_type_at_index(int index);
1995 
1996  /*l
1997  *b Returns:
1998  **
1999  ** abbreviation of the given character type, when a shorter
2000  ** identifier is needed
2001  **
2002  *b Arguments:
2003  **
2004  *a character_type - character type name, as returned by
2005  *a get_character_type_at_index(), for example
2006  */
2007  const char* get_character_type_abbreviation(const char* character_type);
2008 
2009  /*l
2010  *b Description:
2011  **
2012  ** This function returns the version at which the specified
2013  ** character type was deprecated.
2014  **
2015  ** If the character type has not been deprecated, the empty string
2016  ** ("") is returned.
2017  **
2018  *b Arguments:
2019  **
2020  *a character_type - character type name, as returned by
2021  *a get_character_type_at_index(), for example
2022  **
2023  *b Returns:
2024  **
2025  ** version at which character became deprecated; empty string ("")
2026  ** if it hasn't been
2027  **
2028  *b C++ Example:
2029  **
2030  *e const char* version = scenario->get_character_type_deprecated_at_version();
2031  *e if (strlen(version) > 0)
2032  *e {
2033  *e // do something
2034  *e }
2035  */
2036  const char* get_character_type_deprecated_at_version(const char* character_type);
2037 
2038  /*l
2039  *b Description:
2040  **
2041  ** This function returns the suggested character type(s) that are
2042  ** recommended for deprecated character types.
2043  **
2044  ** If the character type has not been deprecated, the empty string
2045  ** ("") is returned.
2046  **
2047  ** If there is more than one suggested alternative, they will be
2048  ** separated by spaces.
2049  **
2050  *b Arguments:
2051  **
2052  *a character_type - character type name, as returned by
2053  *a get_character_type_at_index(), for example
2054  **
2055  *b Returns:
2056  **
2057  ** suggested replacement character type(s)
2058  **
2059  *b C++ Example:
2060  **
2061  *e const char* alternatives = scenario->get_character_type_deprecated_suggested_alternatives();
2062  *e if (strlen(version) > 0)
2063  *e {
2064  *e // do something
2065  *e }
2066  */
2067  const char* get_character_type_deprecated_suggested_alternatives(const char* character_type);
2068 
2069  /*l
2070  *b Description:
2071  **
2072  ** As the number of character types DI-Guy provides has grown,
2073  ** newer character types tend to be better than older ones.
2074  ** This can be because of a greater selection of actions, better
2075  ** quality motions, and other factors.
2076  **
2077  ** This function returns a value representing a qualitative "bias"
2078  ** of this character they relative to other character types.
2079  ** The higher the bias, the more recommended the character type is.
2080  ** A bias of 1 means strongly not recommended, 5 means average,
2081  ** 10 means highly recommended.
2082  **
2083  *b Returns:
2084  **
2085  ** quality bias, a unitless value from 1 to 10
2086  **
2087  *b Arguments:
2088  **
2089  *a character_type - character type name, as returned by
2090  *a get_character_type_at_index(), for example
2091  */
2092  int get_character_type_quality_bias(const char* character_type);
2093 
2094  /*l
2095  *b Description:
2096  **
2097  ** This function returns the type map of the specified character
2098  ** type. See the documentation for diguyCharacterTypeMap for what
2099  ** this information means.
2100  **
2101  ** Only the character type fields will have useful information; the
2102  ** appearance fields will contain default wildcard values.
2103  **
2104  *b Arguments:
2105  **
2106  *a character_type - character type name, as returned by
2107  *a get_character_type_at_index(), for example
2108  **
2109  *b Returns:
2110  **
2111  ** pointer to type diguyCharacterTypeMap; will never be NULL
2112  */
2113  diguyCharacterTypeMap* get_character_type_map(const char* character_type);
2114 
2115  /*l
2116  *b Returns:
2117  **
2118  ** default appearance of the specified character type
2119  **
2120  *b Arguments:
2121  **
2122  *a character_type - character type name, as returned by
2123  *a get_character_type_at_index(), for example
2124  */
2125  const char* get_character_type_default_appearance(const char* character_type);
2126 
2127  /*l
2128  *b Returns:
2129  **
2130  ** default skinned appearance of the specified character type
2131  **
2132  *b Arguments:
2133  **
2134  *a character_type - character type name, as returned by
2135  *a get_character_type_at_index(), for example
2136  */
2137  const char* get_character_type_default_skinned_appearance(const char* character_type);
2138 
2139  /*l
2140  *b Returns:
2141  **
2142  ** number of available appearances for the given character type
2143  **
2144  *b Arguments:
2145  **
2146  *a character_type - character type name, as returned by
2147  *a get_character_type_at_index(), for example
2148  */
2149  int get_character_type_num_appearances(const char* character_type);
2150 
2151  /*l
2152  *b Returns:
2153  **
2154  ** the string identifying the appearance at the given index for
2155  ** the specified character type
2156  **
2157  *b Arguments:
2158  **
2159  *a character_type - character type name, as returned by
2160  *a get_character_type_at_index(), for example
2161  *a index - index of the appearance; indices start at 0
2162  */
2163  const char* get_character_type_appearance_at_index(const char* character_type,
2164  int index);
2165 
2166  /*l
2167  *b Description:
2168  **
2169  ** As the number of appearances DI-Guy provides has grown,
2170  ** newer appearances tend to be better than older ones.
2171  **
2172  ** This function returns a value representing a qualitative "bias"
2173  ** of this character they relative to other character types.
2174  ** The higher the bias, the more recommended the character type is.
2175  ** A bias of 1 means strongly not recommended, 5 means average,
2176  ** 10 means highly recommended.
2177  **
2178  *b Returns:
2179  **
2180  ** quality bias, a unitless value from 1 to 10
2181  **
2182  *b Arguments:
2183  **
2184  *a appearance - appearance name
2185  */
2186  int get_appearance_quality_bias(const char * appearance);
2187  /*l
2188  *b Returns:
2189  **
2190  ** number of available actions for the given character type
2191  **
2192  *b Arguments:
2193  **
2194  *a character_type - character type name, as returned by
2195  *a get_character_type_at_index(), for example
2196  */
2197  int get_character_type_num_actions(const char* character_type);
2198 
2199  /*l
2200  *b Returns:
2201  **
2202  ** the string identifying the action at the given index for
2203  ** the specified character type
2204  **
2205  *b Arguments:
2206  **
2207  *a character_type - character type name, as returned by
2208  *a get_character_type_at_index(), for example
2209  *a index - index of the action name; indices start at 0
2210  */
2211  const char* get_character_type_action_at_index(const char* character_type,
2212  int index);
2213 
2214  /*l
2215  *b Returns:
2216  **
2217  ** the average speed of the specified action for
2218  ** the specified character type
2219  **
2220  *b Arguments:
2221  **
2222  *a character_type - character type name, as returned by
2223  *a get_character_type_at_index(), for example
2224  *a action_name - the action to query
2225  */
2226  float get_character_type_action_speed(const char* character_type,
2227  const char* action_name);
2228 
2229  /*l
2230  *b Returns:
2231  **
2232  ** the duration of one rep of the specified action for
2233  ** the specified character type
2234  **
2235  *b Arguments:
2236  **
2237  *a character_type - character type name, as returned by
2238  *a get_character_type_at_index(), for example
2239  *a action_name - the action to query
2240  */
2241  float get_character_type_action_duration(const char* character_type,
2242  const char* action_name);
2243 
2244  /*l
2245  *b Returns:
2246  **
2247  ** the distance covered by one rep of the specified action for
2248  ** the specified character type
2249  **
2250  *b Arguments:
2251  **
2252  *a character_type - character type name, as returned by
2253  *a get_character_type_at_index(), for example
2254  *a action_name - the action to query
2255  */
2256  float get_character_type_action_distance(const char* character_type,
2257  const char* action_name);
2258 
2259  /*l
2260  *b Returns:
2261  **
2262  ** the diguyMotionDirection identifying the direction of travel of the
2263  ** specified action for the specified character type
2264  **
2265  *b Arguments:
2266  **
2267  *a character_type - character type name, as returned by
2268  *a get_character_type_at_index(), for example
2269  *a action_name - the action to query
2270  */
2271  diguyMotionDirection get_character_type_action_direction(
2272  const char* character_type,
2273  const char* action_name);
2274 
2275  /*l
2276  *b Returns:
2277  **
2278  ** the facing angle at the start of each repetition of the
2279  ** specified action for the specified character type, in degrees
2280  **
2281  *b Arguments:
2282  **
2283  *a character_type - character type name, as returned by
2284  *a get_character_type_at_index(), for example
2285  *a action_name - the action to query
2286  */
2287  float get_character_type_action_facing_angle_in(const char* character_type,
2288  const char* action_name);
2289 
2290  /*l
2291  *b Returns:
2292  **
2293  ** the facing angle at the end of each repetition of the
2294  ** specified action for the specified character type, in degrees
2295  **
2296  *b Arguments:
2297  **
2298  *a character_type - character type name, as returned by
2299  *a get_character_type_at_index(), for example
2300  *a action_name - the action to query
2301  */
2302  float get_character_type_action_facing_angle_out(const char* character_type,
2303  const char* action_name);
2304 
2305  /*l
2306  *b Returns:
2307  **
2308  ** the number of gestures available to
2309  ** the specified character type
2310  **
2311  *b Arguments:
2312  **
2313  *a character_type - character type name, as returned by
2314  *a get_character_type_at_index(), for example;
2315  *a pass "all" to get all gestures available,
2316  *a regardless of character type
2317  */
2318  int get_character_type_num_gestures(const char* character_type);
2319 
2320  /*l
2321  *b Returns:
2322  **
2323  ** the name of the gesture available to the specified
2324  ** character type at the specified index
2325  **
2326  *b Arguments:
2327  **
2328  *a character_type - character type name, as returned by
2329  *a get_character_type_at_index(), for example;
2330  *a pass "all" to get all gestures available,
2331  *a regardless of character type
2332  *a index - index of the gesture; indices start at 0
2333  */
2334  const char* get_character_type_gesture_at_index(const char* character_type,
2335  int index);
2336 
2337 
2338 /*****************************************************************************/
2348  /*l
2349  *b Description:
2350  **
2351  ** This function creates a new character and returns a
2352  ** pointer to it.
2353  **
2354  ** The function preload_character_type() should be called
2355  ** at the beginning of a scenario in which this call will
2356  ** be made to avoid a hitch in frame rate.
2357  **
2358  ** See also retrieve_character_from_recycle_bin() for a
2359  ** potentially faster way of creating a character.
2360  **
2361  *b Arguments:
2362  **
2363  *a name - name of the new character
2364  *a character_type - character's type
2365  *a appearance - base appearance of character; pass
2366  *a NULL to use default appearance
2367  *a hand_item - hand item appearance; pass
2368  *a NULL to use default appearance
2369  **
2370  *b Returns:
2371  **
2372  ** pointer of type diguyCharacter; NULL if creation failed
2373  */
2374  diguyCharacter* create_character(const char* name,
2375  const char* character_type,
2376  const char* appearance = NULL,
2377  const char* head_appearance = NULL,
2378  const char* hand_item = NULL);
2379 
2380  /*l
2381  *b Description:
2382  **
2383  ** This function is very similar to create_character(), but the
2384  ** character created is temporary.
2385  **
2386  ** Temporary characters will be destroyed automatically when the
2387  ** scenario is reset, and are not saved in .dss files. They are
2388  ** commonly used for projectiles, effects, and other objects that can
2389  ** come and go multiple times.
2390  **
2391  ** Temporary characters can be destroyed before scenario reset by
2392  ** calling destroy_character(), and can be sent to the character
2393  ** recycle bin by calling send_character_to_recycle_bin().
2394  **
2395  *b Arguments:
2396  **
2397  *a name - name of the new character
2398  *a character_type - character's type
2399  *a appearance - base appearance of character; pass
2400  *a NULL to use default appearance
2401  **
2402  *b Returns:
2403  **
2404  ** pointer of type diguyCharacter; NULL if creation failed
2405  */
2406  diguyCharacter* create_temporary_character(const char* name,
2407  const char* character_type,
2408  const char* appearance = NULL);
2409 
2410  /*l
2411  *b Description:
2412  **
2413  ** This function destroys a character.
2414  **
2415  ** If a character of the same character type and appearance may be
2416  ** needed later in the scenario, consider using
2417  ** send_character_to_recycle_bin() instead. Characters can be
2418  ** retrieved from the recycle bin more quickly than creating them
2419  ** "from scratch" with create_character().
2420  **
2421  *b Arguments:
2422  **
2423  *a character - pointer to a diguyCharacter
2424  **
2425  *b Returns:
2426  **
2427  ** 0 on success, -1 on failure
2428  **
2429  *b DI-Guy Networking Notes:
2430  **
2431  ** This function should not be called on characters that are reflected
2432  ** network characters. Such characters are destroyed automatically by
2433  ** DI-Guy Networking.
2434  */
2435  int destroy_character(diguyCharacter* character);
2436 
2437  int destroy_character_later(diguyCharacter*)
2438 ;
2439  /*l
2440  *b Description
2441  **
2442  ** This function is an alternative way of removing a character from
2443  ** the scenario. When a character is recycled it is removed from the
2444  ** scenario's list of active characters, but the memory associated
2445  ** with it is not freed. Instead, the character is placed in a
2446  ** "character recycle bin" from which it may be later retrieved with a
2447  ** call to retrieve_character_from_recycle_bin().
2448  **
2449  ** For an application that is creating and destroying a lot of
2450  ** characters with the same character types and appearances, this can
2451  ** avoid performance hiccups that happen when memory is allocated for
2452  ** new characters.
2453  **
2454  ** If it is known ahead of time what types and appearances of
2455  ** characters will be needed in the future, the recycle bin can be
2456  ** "pre-stocked" at scenario load time by first creating and then
2457  ** recycling a large number of characters all at once.
2458  **
2459  *b Returns:
2460  **
2461  ** 0 on success, -1 on failure
2462  */
2463  int send_character_to_recycle_bin(diguyCharacter* character);
2464 
2465  /*l
2466  *b Description
2467  **
2468  ** This function is an alternative way of creating a character. The
2469  ** character recycle bin is checked for a recycled character whose
2470  ** character type and appearance match that requested by this call.
2471  ** Characters are sent to the recycle bin by a call to
2472  ** send_character_to_recycle_bin().
2473  **
2474  ** If a match is found the recycled character will be removed from
2475  ** the recycle bin, given the passed name, and placed in the
2476  ** scenario's list of characters, for the most part just as if the
2477  ** character had been created by a call to create_character(). Some
2478  ** things such as position, current action, etc., may need to be
2479  ** immediately set.
2480  **
2481  ** If a match is not found, this function returns NULL and a call to
2482  ** create_character() must be made instead.
2483  **
2484  *b Arguments:
2485  **
2486  *a name - new name for the character retrieved from bin
2487  *a character_type - the character type to retrieve from the bin
2488  *a appearance - the appearance to retrieve from the bin, pass NULL
2489  *a or "default" to retrieve the default appearance
2490  *a make_character_temporary - pass 1 to make character temporary,
2491  *a 0 to leave permanent
2492  **
2493  *b Returns:
2494  **
2495  ** 0 on success, -1 on failure
2496  */
2497  diguyCharacter* retrieve_character_from_recycle_bin(const char* name,
2498  const char* character_type,
2499  const char* appearance,
2500  int make_character_temporary = 0);
2501 
2502  /*l
2503  *b Returns:
2504  **
2505  ** number of characters in the scenario
2506  */
2507  int get_num_characters();
2508 
2509  /*l
2510  *b Returns:
2511  **
2512  ** pointer of type diguyCharacter; NULL if no character at the
2513  ** specified index
2514  **
2515  *b Arguments:
2516  **
2517  *a index - index of the character; indices start at 0
2518  */
2519  diguyCharacter* get_character_at_index(int index);
2520 
2521  /*l
2522  *b Description:
2523  **
2524  ** This function returns a pointer to the specified character.
2525  **
2526  *b Arguments:
2527  **
2528  *a name - name of character to be found
2529  **
2530  *b Returns:
2531  **
2532  ** pointer of type diguyCharacter; NULL if not found
2533  */
2534  diguyCharacter* find_character(const char* name);
2535 
2536  /*l
2537  *b Description:
2538  **
2539  ** This function changes the scenario camera's position
2540  ** and fix point so it will be looking at the specified
2541  ** character.
2542  */
2543  void look_at_character(diguyCharacter* character);
2544 
2545  /*l
2546  *b Description:
2547  **
2548  ** This function returns a pointer to the target character
2549  ** of an event bead.
2550  **
2551  *b Returns:
2552  **
2553  ** pointer of type diguyCharacter; NULL if no current character
2554  */
2555  diguyCharacter* this_character();
2556 
2557  /*l
2558  *b Description:
2559  **
2560  ** This function returns a pointer to the current event bead.
2561  **
2562  *b Returns:
2563  **
2564  ** pointer of type diguyCharacterPathEvent; NULL if no current event
2565  ** bead
2566  */
2567  diguyCharacterPathEvent* this_event_bead();
2568 
2569 
2570 /*****************************************************************************/
2580  /*l
2581  *b Returns:
2582  **
2583  ** number of path shapes in the scenario
2584  */
2585  int get_num_path_shapes();
2586 
2587  /*l
2588  *b Returns:
2589  **
2590  ** pointer of type diguyPathShape; NULL if no
2591  ** path shape at the specified index
2592  **
2593  *b Arguments:
2594  **
2595  *a index - index of the path shape; indices start at 0
2596  */
2597  diguyPathShape* get_path_shape_at_index(int index);
2598 
2599  /*l
2600  *b Returns:
2601  **
2602  ** pointer of type diguyPathShape; NULL if no
2603  ** path shape at the specified index
2604  */
2605  diguyPathShape* get_current_path_shape();
2606 
2607  /*l
2608  *b Description:
2609  **
2610  ** This function returns a pointer to the specified path shape.
2611  **
2612  *b Arguments:
2613  **
2614  *a name - name of path shape to be found
2615  **
2616  *b Returns:
2617  **
2618  ** pointer of type diguyPathShape; NULL if not found
2619  */
2620  diguyPathShape* find_path_shape(const char* name);
2621 
2622  /*l
2623  *b Description:
2624  **
2625  ** This function creates a new path shape and returns a
2626  ** pointer to it.
2627  **
2628  *b Arguments:
2629  **
2630  *a name - name of the new path shape
2631  **
2632  *b Returns:
2633  **
2634  ** pointer of type diguyPathShape; NULL if creation failed
2635  */
2636  diguyPathShape* create_path_shape(const char* name);
2637 
2638  /*l
2639  *b Description:
2640  **
2641  ** This function creates a new path shape based on an
2642  ** existing path shape and returns a pointer to it.
2643  **
2644  *b Arguments:
2645  **
2646  *a existing_path_shape - pointer to diguyPathShape to be copied
2647  *a name - name of the new path shape
2648  **
2649  *b Returns:
2650  **
2651  ** pointer of type diguyPathShape; NULL if creation failed
2652  */
2653  diguyPathShape* copy_path_shape(diguyPathShape* existing_path_shape,
2654  const char* name);
2655 
2656  /*l
2657  *b Description:
2658  **
2659  ** This function destroys a path shape.
2660  **
2661  *b Arguments:
2662  **
2663  *a path_shape - pointer to a diguyPathShape
2664  **
2665  *b Returns:
2666  **
2667  ** 0 on success, -1 on failure
2668  */
2669  int destroy_path_shape(diguyPathShape* path_shape);
2670 
2671 
2672 /*****************************************************************************/
2677  /*l
2678  *b Description:
2679  **
2680  ** This function creates a new waypoint that can be used for creating
2681  ** new paths and path shapes.
2682  **
2683  ** The returned pointer must be destroyed using destroy_waypoint().
2684  ** The scenario keeps no record of waypoints created with this
2685  ** function.
2686  **
2687  ** The weights of the waypoint control how long the "control handles"
2688  ** of the waypoint are, in meters. The longer the control handle,
2689  ** the more the path will be stretched in the direction of the
2690  ** waypoint's orientation.
2691  **
2692  ** Unless otherwise specified, callable from:
2693  **
2694  *- - C++
2695  *- - Script
2696  **
2697  *b Arguments:
2698  **
2699  *a tx, ty, tz - position in meters from the origin
2700  *a rz, rx, ry - orientations in degrees counter-clockwise
2701  *a from the positive X axis
2702  *a weight_in - how much influence this waypoint exerts
2703  *a over the path curve entering this waypoint
2704  *a weight_out - how much influence this waypoint exerts
2705  *a over the path curve leaving this waypoint
2706  **
2707  ** By default, weight_in will be set to 1, and weight_out will be
2708  ** coupled to weight_in so that changes to one will affect the
2709  ** other. See diguyWaypoint::set_weight_in(). If a non-default
2710  ** value is passed for weight_out the weights of the waypoint will
2711  ** not be coupled.
2712  **
2713  *b Returns:
2714  **
2715  ** pointer to type diguyWaypoint
2716  */
2717  diguyWaypoint* create_waypoint(float x = 0.0f, float y = 0.0f, float z = 0.0f,
2718  float yaw = 0.0f, float roll = 0.0f, float pitch = 0.0f,
2719  float weight_in = DIGUY_DEFAULT_FLOAT,
2720  float weight_out = DIGUY_DEFAULT_FLOAT);
2721 
2722  /*l
2723  *b Description:
2724  **
2725  ** This function destroys a waypoint created by create_waypoint().
2726  ** Path shapes created using this waypoint will not be affected;
2727  ** they make internal copies of the waypoints that are used to
2728  ** create them.
2729  **
2730  ** Do *not* call this function on waypoints not created by
2731  ** create_waypoint()! e.g., a waypoint returned by a call to
2732  ** diguyCharacterPath::get_waypoint_at_index().
2733  **
2734  *b Arguments:
2735  **
2736  *a waypoint - waypoint to destroy
2737  **
2738  *b Returns:
2739  **
2740  ** 0 on success, -1 on failure
2741  */
2742  int destroy_waypoint(diguyWaypoint* waypoint);
2743 
2744 
2745 /*****************************************************************************/
2761  /*l
2762  *b Description:
2763  **
2764  ** This function searches DI-Guy's available character types and
2765  ** appearances for the closest match to the specified fields and
2766  ** values. See the documentation for diguyCharacterTypeMap for
2767  ** information on what fields are available, and what values they
2768  ** may take.
2769  **
2770  *b Arguments:
2771  **
2772  *a field1 - field in type map to check
2773  *a field1_value - value to check for
2774  *a field1_alternate_value - acceptable alternate value
2775  **
2776  ** (Arguments for fields 2 through 8 are the same.)
2777  **
2778  *b Returns:
2779  **
2780  ** pointer to type diguyCharacterTypeMap
2781  */
2782  diguyCharacterTypeMap* get_nearest_character_type_map(
2783  diguyCharacterTypeMapField field1, const char* field1_value, const char* field1_alternate_value,
2784  diguyCharacterTypeMapField field2 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field2_value = NULL, const char* field2_alternate_value = NULL,
2785  diguyCharacterTypeMapField field3 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field3_value = NULL, const char* field3_alternate_value = NULL,
2786  diguyCharacterTypeMapField field4 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field4_value = NULL, const char* field4_alternate_value = NULL,
2787  diguyCharacterTypeMapField field5 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field5_value = NULL, const char* field5_alternate_value = NULL,
2788  diguyCharacterTypeMapField field6 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field6_value = NULL, const char* field6_alternate_value = NULL,
2789  diguyCharacterTypeMapField field7 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field7_value = NULL, const char* field7_alternate_value = NULL,
2790  diguyCharacterTypeMapField field8 = DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN, const char* field8_value = NULL, const char* field8_alternate_value = NULL);
2791 
2792  /*l
2793  *b Description:
2794  **
2795  ** Same as above, but fields to check are specified by string name
2796  ** instead of enumeration value.
2797  */
2798  diguyCharacterTypeMap* get_nearest_character_type_map_using_field_strings(
2799  const char* field1_string, const char* field1_value, const char* field1_alternate_value,
2800  const char* field2_string = NULL, const char* field2_value = NULL, const char* field2_alternate_value = NULL,
2801  const char* field3_string = NULL, const char* field3_value = NULL, const char* field3_alternate_value = NULL,
2802  const char* field4_string = NULL, const char* field4_value = NULL, const char* field4_alternate_value = NULL,
2803  const char* field5_string = NULL, const char* field5_value = NULL, const char* field5_alternate_value = NULL,
2804  const char* field6_string = NULL, const char* field6_value = NULL, const char* field6_alternate_value = NULL,
2805  const char* field7_string = NULL, const char* field7_value = NULL, const char* field7_alternate_value = NULL,
2806  const char* field8_string = NULL, const char* field8_value = NULL, const char* field8_alternate_value = NULL);
2807 
2808  /*l
2809  *b Description:
2810  **
2811  ** Same as above, but field values to match against are specified
2812  ** by the given type map id. No alternate values can be provided,
2813  ** though wildcards can be used by putting a "*" in for a field.
2814  */
2815  diguyCharacterTypeMap* get_nearest_character_type_map_id_match(const char* type_map_id);
2816 
2817  /*l
2818  *b Description:
2819  **
2820  ** This function returns the total number of type map entries that
2821  ** are in DI-Guy. It is against these entries that matches will be
2822  ** made.
2823  **
2824  ** This function, along with get_character_type_map_entry_at_index(),
2825  ** enables all type map information to be queried.
2826  **
2827  *b Returns:
2828  **
2829  ** number of total type map entries against which matches will be
2830  ** made
2831  */
2832  int get_num_character_type_map_entries();
2833 
2834  /*l
2835  *b Returns:
2836  **
2837  ** type map entry at specified index; see
2838  ** get_num_character_type_map_entries()
2839  */
2840  diguyCharacterTypeMap* get_character_type_map_entry_at_index(int index);
2841 
2842  /*l
2843  *b Description:
2844  **
2845  ** This function returns the total number of values that may
2846  ** be specified or returned in the character class field.
2847  **
2848  ** This function, along with get_type_map_character_class_at_index(),
2849  ** enables all available character classes to be queried.
2850  **
2851  *b Returns:
2852  **
2853  ** number of character classes
2854  */
2855  int get_num_type_map_character_classes();
2856 
2857  /*l
2858  *b Returns:
2859  **
2860  ** character class field value at specified index; see
2861  ** get_num_type_map_character_classes()
2862  */
2863  const char* get_type_map_character_class_at_index(int index);
2864 
2865  /*l
2866  *b Description:
2867  **
2868  ** This function returns the total number of values that may
2869  ** be specified or returned in the category field of a type
2870  ** map with the given character class.
2871  **
2872  ** This function, along with get_type_map_category_at_index(),
2873  ** enables all available categories available to each character
2874  ** class to be queried.
2875  **
2876  *b Returns:
2877  **
2878  ** number of categories
2879  */
2880  int get_num_type_map_categories(const char* character_class);
2881 
2882  /*l
2883  *b Returns:
2884  **
2885  ** category field value at specified index; see
2886  ** get_num_type_map_categories()
2887  */
2888  const char* get_type_map_category_at_index(const char* character_class,
2889  int index);
2890 
2891  /*l
2892  *b Description:
2893  **
2894  ** This function returns the total number of values that may
2895  ** be specified or returned in the subcategory field of a type
2896  ** map with the given character class and category.
2897  **
2898  ** This function, along with get_type_map_subcategory_at_index(),
2899  ** enables all available subcategories available to each character
2900  ** class and category to be queried.
2901  **
2902  *b Returns:
2903  **
2904  ** number of subcategories
2905  */
2906  int get_num_type_map_subcategories(const char* character_class,
2907  const char* category);
2908 
2909  /*l
2910  *b Returns:
2911  **
2912  ** subcategory field value at specified index; see
2913  ** get_num_type_map_subcategories()
2914  */
2915  const char* get_type_map_subcategory_at_index(const char* character_class,
2916  const char* category,
2917  int index);
2918 
2919 
2920 /*****************************************************************************/
2930  /*l
2931  *b Returns:
2932  **
2933  ** number of signals in the scenario
2934  */
2935  int get_num_signals();
2936 
2937  /*l
2938  *b Returns:
2939  **
2940  ** pointer of type diguySignal; NULL if no
2941  ** signal at the specified index
2942  **
2943  *b Arguments:
2944  **
2945  *a index - index of the signal; indices start at 0
2946  */
2947  diguySignal* get_signal_at_index(int index);
2948 
2949  /*l
2950  *b Description:
2951  **
2952  ** This function returns a pointer to the specified signal.
2953  **
2954  *b Arguments:
2955  **
2956  *a name - name of signal to be found
2957  **
2958  *b Returns:
2959  **
2960  ** pointer of type diguySignal; NULL if not found
2961  */
2962  diguySignal* find_signal(const char* name);
2963 
2964  /*l
2965  *b Description:
2966  **
2967  ** This function creates a new signal and returns a
2968  ** pointer to it.
2969  **
2970  *b Arguments:
2971  **
2972  *a name - name of the new signal
2973  **
2974  *b Returns:
2975  **
2976  ** pointer of type diguySignal
2977  */
2978  diguySignal* create_signal(const char* name);
2979 
2980  /*l
2981  *b Description:
2982  **
2983  ** This function destroys a signal.
2984  **
2985  *b Arguments:
2986  **
2987  *a signal - pointer to a diguySignal
2988  **
2989  *b Returns:
2990  **
2991  ** 0 on success, -1 on failure
2992  */
2993  int destroy_signal(diguySignal* signal);
2994 
2995  /*l
2996  *b Description:
2997  **
2998  ** This function resets all signals in the scenario.
2999  */
3000  void reset_signals();
3001 
3002 
3003  /*l
3004  *b Description:
3005  **
3006  ** This function hides all signals in the signal palette.
3007  **
3008  *b Arguments:
3009  **
3010  *a filter - optional filter, will only hide signals tagged with
3011  *a info_text equaling filter
3012  */
3013  int signal_palette_hide_all(const char* filter = NULL);
3014 
3015  /*l
3016  *b Description:
3017  **
3018  ** This function shows all signals in the signal palette.
3019  **
3020  *b Arguments:
3021  **
3022  *a filter - optional filter, will only show signals tagged with
3023  *a info_text filter
3024  */
3025  int signal_palette_show_all(const char* filter = NULL);
3026 
3027 
3028 /*****************************************************************************/
3042  /*l
3043  *b Returns:
3044  **
3045  ** number of sounds in the scenario
3046  */
3047  int get_num_sounds();
3048 
3049  /*l
3050  *b Returns:
3051  **
3052  ** pointer of type diguySound; NULL if no sound at the specified
3053  ** index
3054  **
3055  *b Arguments:
3056  **
3057  *a index - index of the sound; indices start at 0
3058  */
3059  diguySound* get_sound_at_index(int index);
3060 
3061  /*l
3062  *b Description:
3063  **
3064  ** This function returns a pointer to the specified sound.
3065  **
3066  *b Arguments:
3067  **
3068  *a name - name of sound to be found
3069  **
3070  *b Returns:
3071  **
3072  ** pointer of type diguySound; NULL if not found
3073  */
3074  diguySound* find_sound(const char* name);
3075 
3076  /*l
3077  *b Description:
3078  **
3079  ** This function creates a new sound and returns a pointer to it.
3080  **
3081  ** Note that sounds are not played directly. Instead they are used as
3082  ** templates for sound instances. See diguyCharacter::play_sound()
3083  ** and diguyCharacter::create_sound_instance().
3084  **
3085  *b Arguments:
3086  **
3087  *a name - name of the new sound
3088  *a sound_filename - filename of the sound
3089  **
3090  ** Note that name isn't the filename of the sound; it is the
3091  ** descriptive name that will show up in the UI and used in
3092  ** diguyCharacter calls that play sounds.
3093  **
3094  ** Pass the filename in the sound_filename argument or use the
3095  ** function diguySound::set_sound_filename() to set the filename of
3096  ** the sound.
3097  **
3098  ** See diguyCharacter::set_current_voice_actor() for information
3099  ** about naming sounds for different voice actors.
3100  **
3101  *b Returns:
3102  **
3103  ** pointer of type diguySound
3104  */
3105  diguySound* create_sound(const char* name,
3106  const char* sound_filename = NULL);
3107 
3108  /*l
3109  *b Description:
3110  **
3111  ** This function destroys a sound.
3112  **
3113  *b Arguments:
3114  **
3115  *a sound - pointer to diguySound to be destroyed
3116  **
3117  *b Returns:
3118  **
3119  ** 0 on success, -1 on failure
3120  */
3121  int destroy_sound(diguySound* sound);
3122 
3123  /*l
3124  *b Description:
3125  **
3126  ** This function preloads data for the sound.
3127  **
3128  *b Arguments:
3129  **
3130  *a sound - pointer to diguySound
3131  **
3132  *b Returns:
3133  **
3134  ** 0 on success, -1 on failure
3135  */
3136  int preload_sound(diguySound* sound);
3137 
3138  /*l
3139  **
3140  *b Description:
3141  **
3142  ** This function stops all sounds playing within the scenario.
3143  **
3144  *b Arguments:
3145  **
3146  *a rampdown_time - how long to allow the sounds to fade out
3147  **
3148  *b Returns:
3149  **
3150  ** 0 on success, -1 on failure
3151  */
3152  int stop_all_sounds(float rampdown_time = 0.0f);
3153 
3154  /*l
3155  **
3156  *b Description:
3157  **
3158  ** This function plays a non looping sound.
3159  **
3160  *b Arguments:
3161  **
3162  *a name - name of the sound
3163  *a x, y, z - location in the world the sound comes from
3164  *a gain - a volume multiplier
3165  *a save_event - if review data should record the creation of this
3166  *a sound
3167  **
3168  *b Returns:
3169  **
3170  ** 0 on success, -1 on failure
3171  */
3172  int play_3d_sound(const char* name,
3173  float x, float y, float z,
3174  float gain,
3175  int save_event);
3176 
3177 
3178 /*****************************************************************************/
3188  /*l
3189  *b Returns:
3190  **
3191  ** number of groups in the scenario
3192  */
3193  int get_num_groups();
3194 
3195  /*l
3196  *b Returns:
3197  **
3198  ** pointer of type diguyCharacterGroup; NULL if no
3199  ** group at the specified index
3200  **
3201  *b Arguments:
3202  **
3203  *a index - index of the group; indices start at 0
3204  */
3205  diguyCharacterGroup* get_group_at_index(int index);
3206 
3207  /*l
3208  *b Description:
3209  **
3210  ** This function returns a pointer to the specified group.
3211  **
3212  *b Arguments:
3213  **
3214  *a name - name of group to be found
3215  **
3216  *b Returns:
3217  **
3218  ** pointer of type diguyCharacterGroup; NULL if not found
3219  */
3220  diguyCharacterGroup* find_group(const char* name);
3221 
3222  /*l
3223  *b Description:
3224  **
3225  ** This function creates a new group and returns a
3226  ** pointer to it.
3227  **
3228  *b Arguments:
3229  **
3230  *a name - name of the new group
3231  **
3232  *b Returns:
3233  **
3234  ** pointer of type diguyCharacterGroup
3235  */
3236  diguyCharacterGroup* create_group(const char* name);
3237 
3238 
3239  /*l
3240  *b Description:
3241  **
3242  ** This function finds the group with the given name or
3243  ** creates it if it doesn't exist.
3244  **
3245  *b Arguments:
3246  **
3247  *a name - name of the group to find or create
3248  **
3249  *b Returns:
3250  **
3251  ** pointer of type diguyGroup; should never be NULL
3252  */
3253  diguyCharacterGroup* find_or_create_group(const char* name);
3254 
3255 
3256  /*l
3257  *b Description:
3258  **
3259  ** This function destroys a group.
3260  **
3261  *b Arguments:
3262  **
3263  *a group - pointer to a diguyCharacterGroup
3264  **
3265  *b Returns:
3266  **
3267  ** 0 on success, -1 on failure
3268  */
3269  int destroy_group(diguyCharacterGroup* group);
3270 
3271 
3272 /*****************************************************************************/
3282  int get_num_sensor_regions();
3284 
3285  /*l
3286  *b Returns:
3287  **
3288  ** pointer of type diguySensorRegion; NULL if no
3289  ** sensor region at the specified index
3290  **
3291  *b Arguments:
3292  **
3293  *a index - index of the sensor region; indices start at 0
3294  */
3295  diguySensorRegion* get_sensor_region_at_index(int index);
3296 
3298  diguySensorRegion* find_sensor_region(const char* name);
3299 
3301  diguySensorRegion* find_or_create_sensor_region(const char* name);
3302 
3303 /*****************************************************************************/
3313  /*l
3314  *b Returns:
3315  **
3316  ** number of scene objects in the scenario
3317  */
3318  int get_num_scene_objects();
3319 
3320  /*l
3321  *b Returns:
3322  **
3323  ** pointer of type diguySceneObject; NULL if no
3324  ** scene object at the specified index
3325  **
3326  *b Arguments:
3327  **
3328  *a index - index of the scene object; indices start at 0
3329  */
3330  diguySceneObject* get_scene_object_at_index(int index);
3331 
3332  /*l
3333  *b Returns:
3334  **
3335  ** pointer of type diguySceneObject; NULL if no
3336  ** scene object with specified name
3337  */
3338  diguySceneObject* find_scene_object(const char* name);
3339 
3340  /*l
3341  *b Description:
3342  **
3343  ** This function sets whether scene objects defined in the
3344  ** scenario are enabled, and therefore potentially visible.
3345  **
3346  ** Scene objects are *not* enabled by default.
3347  **
3348  *b Arguments:
3349  **
3350  *a scene_objects_enabled - flag determining whether scene
3351  *a objects are enabled; 1 for enabled,
3352  *a 0 for disabled
3353  */
3354  void set_scene_objects_enabled(int scene_objects_enabled);
3355 
3356  /*l
3357  *b Returns:
3358  **
3359  ** the most recent setting made by a call to
3360  ** set_scene_objects_enabled()
3361  */
3362  int get_scene_objects_enabled();
3363 
3364  /*l
3365  *b Description:
3366  **
3367  ** This function creates a new scene object and returns a
3368  ** pointer to it.
3369  **
3370  *b Arguments:
3371  **
3372  *a name - name of the new scene object
3373  *a filename - file the scene object should use
3374  **
3375  *b Returns:
3376  **
3377  ** pointer of type diguySceneObject; NULL if creation failed
3378  */
3379  diguySceneObject* create_scene_object(const char* name,
3380  const char* filename);
3381 
3382  /*l
3383  *b Description:
3384  **
3385  ** This function creates a new user defined scene object and returns a
3386  ** pointer to it.
3387  **
3388  *b Arguments:
3389  **
3390  *a name - name of the new scene object
3391  **
3392  *b Returns:
3393  **
3394  ** pointer of type diguySceneObject; NULL if creation failed
3395  */
3396  diguySceneObject* create_user_defined_scene_object(const char* name);
3397 
3398  /*l
3399  *b Description:
3400  **
3401  ** This function destroys a scene object.
3402  **
3403  *b Arguments:
3404  **
3405  *a scene_object - pointer to a diguySceneObject
3406  **
3407  *b Returns:
3408  **
3409  ** 0 on success, -1 on failure
3410  */
3411  int destroy_scene_object(diguySceneObject* scene_object);
3412 
3413 
3414 /*****************************************************************************/
3424  /*l
3425  *b Returns:
3426  **
3427  ** pointer to the scenario's primary view; there is one
3428  ** and only one primary view in the scenario
3429  */
3430  diguyView* get_primary_view();
3431 
3432  /*l
3433  *b Returns:
3434  **
3435  ** number of secondary views in the scenario
3436  */
3437  int get_num_secondary_views();
3438 
3439  /*l
3440  *b Returns:
3441  **
3442  ** pointer of type diguyView; NULL if no
3443  ** secondary view at the specified index
3444  **
3445  *b Arguments:
3446  **
3447  *a index - index of the secondary view; indices start at 0
3448  */
3449  diguyView* get_secondary_view_at_index(int index);
3450 
3451  /*l
3452  *b Description:
3453  **
3454  ** This function returns a pointer to the view with
3455  ** the given name. The primary view and all of the
3456  ** secondary views are checked for a name match.
3457  **
3458  *b Returns:
3459  **
3460  ** pointer of type diguyView; NULL if not found
3461  */
3462  diguyView* find_view(const char* name);
3463 
3464 
3465 /*****************************************************************************/
3475  /*l
3476  *b Description:
3477  **
3478  ** This function returns a pointer to the primary view's camera.
3479  ** This is equivalent to:
3480  **
3481  *e diguyView* v = scenario->get_primary_view();
3482  *e return v->get_camera();
3483  **
3484  *b Returns:
3485  **
3486  ** pointer of type diguyViewCamera; should never be NULL
3487  */
3488  diguyViewCamera* get_scenario_camera();
3489 
3490  /*l
3491  *b Description:
3492  **
3493  ** This function returns a pointer to the camera with
3494  ** the given name. The primary view's camera and all of the
3495  ** secondary views' cameras are checked for a name match.
3496  **
3497  *b Returns:
3498  **
3499  ** pointer of type diguyViewCamera; NULL if not found
3500  */
3501  diguyViewCamera* find_camera(const char* name);
3502 
3503  /*l
3504  *b Description:
3505  **
3506  ** This function sets a flag that determines whether script
3507  ** calls can set the primary view's camera settings.
3508  ** Specifically, if flag is 0, calls to diguyViewCamera::load()
3509  ** will have no effect; the camera should remain completely under
3510  ** user control.
3511  **
3512  *b Arguments:
3513  **
3514  *a flag - 1 to enable, 0 to disable
3515  */
3516  void set_scenario_camera_affected_by_script_events(int flag);
3517 
3518  /*l
3519  *b Returns:
3520  **
3521  ** the most recent setting made by
3522  ** set_scenario_camera_affected_by_script_events()
3523  */
3524  int get_scenario_camera_affected_by_script_events();
3525 
3526  /*l
3527  *b Description:
3528  **
3529  ** This function, like
3530  ** set_scenario_camera_affected_by_script_events(), determines
3531  ** whether script calls can set the primary view's camera settings,
3532  ** but only disables camera changes if there is an active I-Guy
3533  ** character as set by the set_iguy_character() call.
3534  **
3535  ** If set_scenario_camera_affected_by_script_events() has been called
3536  ** with a value of 0, then this function has no effect.
3537  **
3538  *b Arguments:
3539  **
3540  *a flag - 1 to enable, 0 to disable
3541  */
3542  void set_scenario_camera_affected_by_script_events_when_iguy_active(int flag);
3543 
3544  /*l
3545  *b Returns:
3546  **
3547  ** the most recent setting made by
3548  ** set_scenario_camera_affected_by_script_events()
3549  */
3550  int get_scenario_camera_affected_by_script_events_when_iguy_active();
3551 
3552  /*l
3553  *b Returns:
3554  **
3555  ** number of camera settings saved in the scenario
3556  */
3557  int get_num_camera_settings();
3558 
3559  /*l
3560  *b Returns:
3561  **
3562  ** pointer of type diguyViewCameraSettings; NULL if no
3563  ** camera settings at the specified index
3564  **
3565  *b Arguments:
3566  **
3567  *a index - index of the camera settings; indices start at 0
3568  */
3569  diguyViewCameraSettings* get_camera_settings_at_index(int index);
3570 
3571  /*l
3572  *b Description:
3573  **
3574  ** This function returns a pointer to the specified camera settings.
3575  **
3576  *b Arguments:
3577  **
3578  *a settings_name - name of camera settings to be found
3579  **
3580  *b Returns:
3581  **
3582  ** pointer of type diguyViewCamera; NULL if not found
3583  */
3584  diguyViewCameraSettings* find_camera_settings(const char* settings_name);
3585 
3586  /*l
3587  *b Description:
3588  **
3589  ** This function loads the specified camera settings into
3590  ** the primary view's camera.
3591  **
3592  *b Arguments:
3593  **
3594  *a settings_name - name of camera settings to be loaded
3595  *a update_current_camera - whether the current camera should be
3596  *a updated; defaults to 1
3597  **
3598  ** Not updating the current camera will cause the camera history
3599  ** to be lost.
3600  **
3601  *b Returns:
3602  **
3603  ** 0 on success, -1 on failure
3604  */
3605  int load_camera_settings(const char* settings_name, int update_current_camera = 1);
3606 
3607  /*l
3608  *b Description:
3609  **
3610  ** This function sets camera that will be used for down-stream
3611  ** camera-related operations. This includes:
3612  **
3613  *- - far position rendering in the OpenGL renderer
3614  *- - various culling operations (e.g.
3615  *- set_character_culling_enabled())
3616  *- - graphics LOD range scaling; see
3617  *- set_scale_graphics_lod_ranges_from_view_settings()
3618  **
3619  ** Typically the passed camera should be the primary view's camera.
3620  **
3621  ** A render camera does not always need to be set. If one is not
3622  ** set, the above camera-related operations will not be performed.
3623  **
3624  ** If a render camera is set the actual rendering environment
3625  ** camera settings (e.g. as set by gluLookAt() in OpenGL)
3626  ** should match the settings in the render camera, or there
3627  ** may be unexpected visual results.
3628  **
3629  *b Arguments:
3630  **
3631  *a camera - camera to use for camera-related operations
3632  */
3633  void set_render_camera(diguyViewCamera* camera);
3634 
3635 
3636 /*****************************************************************************/
3646  /*l
3647  *b Description:
3648  **
3649  ** This function returns a pointer to the scenario fog.
3650  ** This is the fog of the primary view.
3651  **
3652  *b Returns:
3653  **
3654  ** pointer of type diguyViewFog; should never be NULL
3655  */
3656  diguyViewFog* get_scenario_fog();
3657 
3658  /*l
3659  *b Description:
3660  **
3661  ** This function returns a pointer to the fog with
3662  ** the given name. The primary view's fog and all of the
3663  ** secondary views' fogs are checked for a name match.
3664  **
3665  *b Returns:
3666  **
3667  ** pointer of type diguyViewFog; NULL if not found
3668  */
3669  diguyViewFog* find_fog(const char* name);
3670 
3671  /*l
3672  *b Description:
3673  **
3674  ** This function returns the fog object with the given name, or
3675  ** creates one if not found.
3676  **
3677  *b Returns:
3678  **
3679  ** pointer of type diguyViewFog
3680  **
3681  *b Arguments:
3682  **
3683  *a name
3684  */
3685  diguyViewFog* find_or_create_fog(const char* name);
3686 
3687  /*l
3688  *b Description:
3689  **
3690  ** This function loads the named fog settings the currently active
3691  ** one.
3692  **
3693  *b Arguments:
3694  **
3695  *a name
3696  */
3697  void load_current_fog(const char* name);
3698 
3699  /*l
3700  *b Returns:
3701  **
3702  ** number of fog settings in the scenario
3703  */
3704  int get_num_fog_settings();
3705 
3706  /*l
3707  *b Returns:
3708  **
3709  ** pointer of type diguyViewFogSettings; NULL if no
3710  ** fog at the specified index
3711  **
3712  *b Arguments:
3713  **
3714  *a index - index of the fog settings; indices start at 0
3715  */
3716  diguyViewFogSettings* get_fog_settings_at_index(int index);
3717 
3718  /*l
3719  *b Description:
3720  **
3721  ** This function returns a pointer to the specified fog settings.
3722  **
3723  *b Arguments:
3724  **
3725  *a settings_name - name of fog settings to be found
3726  **
3727  *b Returns:
3728  **
3729  ** pointer of type diguyViewFogSettings; NULL if not found
3730  */
3731  diguyViewFogSettings* find_fog_settings(const char* settings_name);
3732 
3733  /*l
3734  *b Description:
3735  **
3736  ** This function loads the specified fog settings into
3737  ** the scenario fog.
3738  **
3739  *b Arguments:
3740  **
3741  *a settings_name - name of fog settings to be loaded
3742  **
3743  *b Returns:
3744  **
3745  ** pointer of type diguyViewFog; NULL if not found
3746  */
3747  int load_fog_settings(const char* settings_name);
3748 
3749 
3750 /*****************************************************************************/
3760  /*l
3761  *b Description:
3762  **
3763  ** This function returns a pointer to the scenario light.
3764  ** These are the lights of the primary view.
3765  **
3766  *b Arguments:
3767  **
3768  *a number - number of light to be found
3769  **
3770  *b Returns:
3771  **
3772  ** pointer of type diguyViewLight; can be null if asked for a
3773  ** non-existent light
3774  */
3775  diguyViewLight* get_scenario_light(int i = 0);
3776 
3777  /*l
3778  *b Description:
3779  **
3780  ** This function returns a pointer to the light with
3781  ** the given name. The primary view's light and all of the
3782  ** secondary views' lights are checked for a name match.
3783  **
3784  *b Returns:
3785  **
3786  ** pointer of type diguyViewLight; NULL if not found
3787  */
3788  diguyViewLight* find_light(const char* name);
3789 
3790  /*l
3791  *b Returns:
3792  **
3793  ** number of light settings in the scenario
3794  */
3795  int get_num_light_settings();
3796 
3797  /*l
3798  *b Returns:
3799  **
3800  ** pointer of type diguyViewLightSettings; NULL if no
3801  ** light settings at the specified index
3802  **
3803  *b Arguments:
3804  **
3805  *a index - index of the light settings; indices start at 0
3806  */
3807  diguyViewLightSettings* get_light_settings_at_index(int index);
3808 
3809  /*l
3810  *b Description:
3811  **
3812  ** This function returns a pointer to the specified light settings.
3813  **
3814  *b Arguments:
3815  **
3816  *a name - name of light settings to be found
3817  **
3818  *b Returns:
3819  **
3820  ** pointer of type diguyViewLightSettings; NULL if not found
3821  */
3822  diguyViewLightSettings* find_light_settings(const char* settings_name);
3823 
3824  /*l
3825  *b Description:
3826  **
3827  ** This function loads the specified light settings into
3828  ** the scenario light.
3829  **
3830  *b Arguments:
3831  **
3832  *a settings_name - name of light settings to be loaded
3833  *a light_num - which light to load into
3834  **
3835  *b Returns:
3836  **
3837  ** pointer of type diguyViewLight; NULL if not found
3838  */
3839  int load_light_settings(const char* settings_name, int light_num = 0);
3840 
3841 
3842 /*****************************************************************************/
3852  /*l
3853  *b Returns:
3854  **
3855  ** number of info popups in the scenario
3856  */
3857  int get_num_info_popups();
3858 
3859  /*l
3860  *b Returns:
3861  **
3862  ** pointer of type diguyInfoPopup; NULL if no
3863  ** info popup at the specified index
3864  **
3865  *b Arguments:
3866  **
3867  *a index - index of the info popup; indices start at 0
3868  */
3869  diguyInfoPopup* get_info_popup_at_index(int index);
3870 
3871  /*l
3872  *b Description:
3873  **
3874  ** This function returns a pointer to the specified info popup.
3875  **
3876  *b Arguments:
3877  **
3878  *a name - name of info popup to be found
3879  **
3880  *b Returns:
3881  **
3882  ** pointer of type diguyInfoPopup; NULL if not found
3883  */
3884  diguyInfoPopup* find_info_popup(const char* name);
3885 
3886  /*l
3887  *b Description:
3888  **
3889  ** This function sets the default encoding for info popups
3890  ** that do not have an encoding specified.
3891  **
3892  *b Arguments:
3893  **
3894  *a info_popup_default_encoding - new default encoding
3895  **
3896  *b Returns:
3897  **
3898  ** 0 on success, -1 on failure
3899  */
3900  int set_info_popup_default_encoding(const char* info_popup_default_encoding);
3901 
3902  /*l
3903  *b Description:
3904  **
3905  ** This function returns the default encoding of info popups.
3906  **
3907  *b Returns:
3908  **
3909  ** default encoding; value will never be NULL, but may be
3910  ** the empty string ("") if no default encoding has been
3911  ** specified
3912  */
3913  const char* get_info_popup_default_encoding();
3914 
3915 
3916 /*****************************************************************************/
3926  /*l
3927  *b Returns:
3928  **
3929  ** number of variables in the scenario
3930  */
3931  int get_num_variables();
3932 
3933  /*l
3934  *b Returns:
3935  **
3936  ** pointer of type diguyVariable; NULL if no
3937  ** variable at the specified index
3938  **
3939  *b Arguments:
3940  **
3941  *a index - index of the variable; indices start at 0
3942  */
3943  diguyVariable* get_variable_at_index(int index);
3944 
3945  /*l
3946  *b Description:
3947  **
3948  ** This function returns a pointer to the specified variable.
3949  **
3950  *b Arguments:
3951  **
3952  *a name - name of variable to be found
3953  **
3954  *b Returns:
3955  **
3956  ** pointer of type diguyVariable; NULL if not found
3957  */
3958  diguyVariable* find_variable(const char* name);
3959 
3960  /*l
3961  *b Description:
3962  **
3963  ** This function finds the variable with the given name or
3964  ** creates it if it doesn't exist.
3965  **
3966  *b Arguments:
3967  **
3968  *a name - name of the variable to find or create
3969  **
3970  *b Returns:
3971  **
3972  ** pointer of type diguyVariable; should never be NULL
3973  */
3974  diguyVariable* find_or_create_variable(const char* name);
3975 
3976  /*l
3977  *b Description:
3978  **
3979  ** This function destroys the passed variable.
3980  **
3981  *b Arguments:
3982  **
3983  *a variable - pointer to a diguyVariable
3984  **
3985  *b Returns:
3986  **
3987  ** 0 on success, -1 on failure
3988  */
3989  int destroy_variable(diguyVariable* variable);
3990 
3991 
3992 /*****************************************************************************/
4002  /*l
4003  *b Returns:
4004  **
4005  ** number of face_expressions in the scenario
4006  */
4007  int get_num_face_expressions();
4008 
4009  /*l
4010  *b Returns:
4011  **
4012  ** pointer of type diguyCharacterFaceExpression; NULL if no
4013  ** info popup at the specified index
4014  **
4015  *b Arguments:
4016  **
4017  *a index - index of the face_expression; indices start at 0
4018  */
4019  diguyCharacterFaceExpression* get_face_expression_at_index(int index);
4020 
4021  /*l
4022  *b Description:
4023  **
4024  ** This function returns a pointer to the specified face expression.
4025  **
4026  *b Arguments:
4027  **
4028  *a name - name of face_expression to be found
4029  **
4030  *b Returns:
4031  **
4032  ** pointer of type diguyCharacterFaceExpression; NULL if not found
4033  */
4034  diguyCharacterFaceExpression* find_face_expression(const char* name);
4035 
4036  /*l
4037  *b Description:
4038  **
4039  ** This function creates a new face expression with the given name.
4040  **
4041  *b Arguments:
4042  **
4043  *a name - name of the new face expression
4044  *a target_actor - name of the actor to use as template; defaults to
4045  *a "exface" for backwards compatiblity
4046  **
4047  *b Returns:
4048  **
4049  ** pointer of type diguyCharacterFaceExpression
4050  */
4051  diguyCharacterFaceExpression* create_face_expression(const char* name,
4052  const char* target_actor = "exface");
4053 
4054  /*l
4055  *b Description:
4056  **
4057  ** This function destroys the passed face expression.
4058  **
4059  *b Arguments:
4060  **
4061  *a face_expression - pointer to a diguyCharacterFaceExpression
4062  **
4063  *b Returns:
4064  **
4065  ** 0 on success, -1 on failure
4066  */
4067  int destroy_face_expression(diguyCharacterFaceExpression* face_expression);
4068 
4069 
4070 /*****************************************************************************/
4080  /*l
4081  *b Returns:
4082  **
4083  ** number of chain settings in the scenario
4084  */
4085  int get_num_chain_settings();
4086 
4087  /*l
4088  *b Returns:
4089  **
4090  ** pointer of type diguyChainSettings; NULL if no
4091  ** chain settings at the specified index
4092  **
4093  *b Arguments:
4094  **
4095  *a index - index of the chain settings; indices start at 0
4096  */
4097  diguyChainSettings* get_chain_settings_at_index(int index);
4098 
4099  /*l
4100  *b Description:
4101  **
4102  ** This function returns a pointer to the specified chain settings.
4103  **
4104  *b Arguments:
4105  **
4106  *a name - name of chain settings to be found
4107  **
4108  *b Returns:
4109  **
4110  ** pointer of type diguyChainSettings; NULL if not found
4111  */
4112  diguyChainSettings* find_chain_settings(const char* name);
4113 
4114  /*l
4115  *b Description:
4116  **
4117  ** This function creates a new chain settings and returns a
4118  ** pointer to it.
4119  **
4120  *b Arguments:
4121  **
4122  *a name - name of the new chain settings
4123  **
4124  *b Returns:
4125  **
4126  ** pointer of type diguyChainSettings
4127  */
4128  diguyChainSettings* create_chain_settings(const char* name);
4129 
4130  /*l
4131  *b Description:
4132  **
4133  ** This function destroys a chain settings.
4134  **
4135  *b Arguments:
4136  **
4137  *a chain settings - pointer to a diguyChainSettings
4138  **
4139  *b Returns:
4140  **
4141  ** 0 on success, -1 on failure
4142  */
4143  int destroy_chain_settings(diguyChainSettings* chain_settings);
4144 
4145 
4146 /*****************************************************************************/
4156  /*l
4157  *b Description:
4158  **
4159  ** This is an enumeration of the different callbacks
4160  ** that can be registered with add_callback() and
4161  ** add_callback_script().
4162  **
4163  ** Callbacks return a value of type diguyCallbackReturn,
4164  ** which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE.
4165  ** If the callback returns DIGUY_CALLBACK_STOP, the default handler
4166  ** of the function will not be called; the callback is asserting
4167  ** that it has done everything necessary for the function call.
4168  ** If the callback returns DIGUY_CALLBACK_CONTINUE, the default
4169  ** handler for the function will be called after the callback.
4170  **
4171  *************************************************************************
4172  *4 Callback Enums:
4173  **
4174  *i CALLBACK_ID_CREATE
4175  **
4176  ** This callback will be called when a new scenario is created.
4177  ** It should only be used by
4178  ** diguyApp::add_default_scenario_callback(). Using it in
4179  ** set_callback() will have no effect, as by that time the
4180  ** scenario has already been created.
4181  **
4182  *i CALLBACK_ID_RESET
4183  **
4184  ** This callback will be called when the scenario is reset.
4185  **
4186  *i CALLBACK_ID_WAIT_CURSOR_SHOW
4187  **
4188  ** This callback will be called when a diguy operation
4189  ** is likely to take some time, allowing an application to
4190  ** display a wait cursor.
4191  **
4192  *i CALLBACK_ID_WAIT_CURSOR_HIDE
4193  **
4194  ** This callback will be called when a diguy operation
4195  ** that caused a wait cursor to be shown has completed,
4196  ** allowing an application to hide the wait cursor.
4197  **
4198  *i CALLBACK_ID_LOAD
4199  **
4200  ** This callback will be called when a scenario is loaded, thereby
4201  ** giving a chance for custom code to read extra elements from the
4202  ** loaded file.
4203  **
4204  *i CALLBACK_ID_SAVE
4205  **
4206  ** This callback will be called when a scenario is saved, thereby
4207  ** giving a chance for custom code to insert extra elements into the
4208  ** saved file.
4209  **
4210  *i CALLBACK_ID_LOAD_SCENARIO_FILE
4211  **
4212  ** This callback will be called just before a scenario loads
4213  ** a new file.
4214  **
4215  *i CALLBACK_ID_SAVE_SCENARIO_FILE
4216  **
4217  ** This callback will be called just after a scenario saves
4218  ** a new file. With a char * pointer to the file name.
4219  **
4220  *i CALLBACK_ID_MANUALLY_INVOKED
4221  **
4222  ** This callback id will be supplied to event handlers invoked
4223  ** by a call to manually_invoke_event_handler().
4224  **
4225  ** The user's returned diguyCallbackReturn value will be ignored.
4226  **
4227  *i CALLBACK_ID_POST_DRAW
4228  **
4229  ** This callback will be called just after a scenario finishes it's
4230  ** draw commands. The diguyViewPainter class can be used to issue
4231  ** abstract draw commands in DI-Guy Scenario.
4232  **
4233  *i Lua Example:
4234  **
4235  *e local painter = this_app:get_view_painter();
4236  *e painter:set_pen_color(1,1,0);
4237  *e painter:draw_line(0,0,0, 1,1,1);
4238  **
4239  *i CALLBACK_ID_PLAYBACK_MODE_CHANGED
4240  **
4241  ** This callback will be called when the playback mode of the
4242  ** scenario has changed. For example, the Play or Stop buttons are
4243  ** pressed in DI-Guy Scenario, or set_playback_mode() is called.
4244  **
4245  ** The user's returned diguyCallbackReturn value will be ignored.
4246  **
4247  *i CALLBACK_ID_INPUT_MODE_CHANGED
4248  **
4249  ** This callback will be called when the input mode of the
4250  ** scenario has changed. For example, when an Input Mode button is
4251  ** pressed in DI-Guy Scenario, or diguyApp::set_base_input_mode()
4252  ** is called.
4253  **
4254  ** The user's returned diguyCallbackReturn value will be ignored.
4255  **
4256  *i CALLBACK_ID_RENDER_MODE_CHANGED
4257  **
4258  ** This callback will be called if the render mode of the scenario
4259  ** changes, typically due to a set_current_render_mode().
4260  **
4261  ** The user's returned diguyCallbackReturn value will be ignored.
4262  **
4263  *i CALLBACK_ID_POST_LOAD_CHECKPOINT
4264  **
4265  ** This callback will be called just after a scenario finishes
4266  ** loading a checkpoint file.
4267  */
4268  enum {
4269  CALLBACK_ID_CREATE = 1,
4270  CALLBACK_ID_DESTROY,
4271  CALLBACK_ID_RESET,
4272  CALLBACK_ID_WAIT_CURSOR_SHOW,
4273  CALLBACK_ID_WAIT_CURSOR_HIDE,
4274  CALLBACK_ID_LOAD,
4275  CALLBACK_ID_SAVE,
4276  CALLBACK_ID_LOAD_SCENARIO_FILE,
4277  CALLBACK_ID_SAVE_SCENARIO_FILE,
4278  CALLBACK_ID_SCENE_OBJECT_IMPACT,
4279  CALLBACK_ID_LEFT_CLICK_SCENE,
4280  CALLBACK_ID_RIGHT_CLICK_SCENE,
4281  CALLBACK_ID_TIMED_EVENT,
4282  CALLBACK_ID_MANUALLY_INVOKED,
4283  CALLBACK_ID_POST_DRAW,
4284  CALLBACK_ID_PLAYBACK_MODE_CHANGED,
4285  CALLBACK_ID_INPUT_MODE_CHANGED,
4286  CALLBACK_ID_RENDER_MODE_CHANGED,
4287  CALLBACK_ID_PRE_REINITIALIZE,
4288  CALLBACK_ID_POST_REINITIALIZE,
4289  CALLBACK_ID_POST_LOAD_CHECKPOINT
4290  };
4291 
4292 #ifdef CPLUSPLUS_ONLY
4293 
4294  /*l
4295  *b Description:
4296  **
4297  ** This function adds a scenario callback.
4298  **
4299  *b Arguments:
4300  **
4301  *a callback - pointer to function with prototype
4302  *a diguyScenarioCallback (typedefed above)
4303  *a callback_id - integer id of when this callback is to be called
4304  *a callback_params - not currently used; pass NULL
4305  *a callback_user_data - pointer for user's own use; DI-Guy will
4306  *a do nothing to the contents of this pointer
4307  *a beyond passing it back when the callback is
4308  *a invoked
4309  *a remove_on_scenario_load - pass 1 to remove the callback on a
4310  *a scenario load, 0 to not
4311  **
4312  *b Returns:
4313  **
4314  ** 0 on success, -1 on failure
4315  **
4316  *b Callable From:
4317  **
4318  *- - C++
4319  */
4320  int add_callback(int callback_id,
4321  diguyScenarioCallback* callback,
4322  void* callback_params = 0,
4323  void* callback_user_data = 0,
4324  int remove_on_scenario_load = 1);
4325 
4326  /*l
4327  *b Description:
4328  **
4329  ** This function removes a user callback. All callbacks matching
4330  ** the specified callback_id and callback function will be removed.
4331  **
4332  *b Arguments:
4333  **
4334  *a callback_id - integer id of callback
4335  *a callback - pointer to function with prototype
4336  *a diguyCharacterCallback (typedefed above)
4337  **
4338  *b Returns:
4339  **
4340  ** 0 on success, -1 on failure
4341  **
4342  *b Callable From:
4343  **
4344  *- - C++
4345  */
4346  int remove_callback(int callback_id,
4347  diguyScenarioCallback* callback);
4348 
4349  /*l
4350  *b Description:
4351  **
4352  ** This function removes a user callback. All callbacks matching
4353  ** the specified callback_id and callback_user_data pointer will
4354  ** be removed.
4355  **
4356  *b Arguments:
4357  **
4358  *a callback_id - integer id of callback
4359  *a callback_user_data - pointer for user's own use
4360  **
4361  *b Returns:
4362  **
4363  ** 0 on success, -1 on failure
4364  **
4365  *b Callable From:
4366  **
4367  *- - C++
4368  */
4369  int remove_callback_with_user_data(int callback_id,
4370  void* callback_user_data);
4371 
4372  /*l
4373  *b Description:
4374  **
4375  ** This function sets a default user callback that will be added to
4376  ** all new characters. See diguyCharacter::add_callback() for
4377  ** details.
4378  **
4379  *b Callable From:
4380  **
4381  *- - C++
4382  */
4383  int add_default_character_callback(int callback_id,
4384  diguyCharacterCallback* callback,
4385  void* callback_params,
4386  void* callback_user_data,
4387  int add_to_existing_objects_flag = 0,
4388  int remove_on_scenario_load = 1);
4389 
4390  /*l
4391  *b Description:
4392  **
4393  ** This function removes a user callback. All default character
4394  ** callbacks matching the specified callback_id and callback function
4395  ** will be removed.
4396  **
4397  *b Arguments:
4398  **
4399  *a callback_id - integer id of callback
4400  *a callback - pointer to function with prototype
4401  *a diguyCharacterCallback (typedefed above)
4402  **
4403  *b Callable From:
4404  **
4405  *- - C++
4406  */
4407  int remove_default_character_callback(int callback_id,
4408  diguyCharacterCallback* callback);
4409 
4410  /*l
4411  *b Description:
4412  **
4413  ** This function removes a default user callback previously added by
4414  ** add_default_character_callback(). See
4415  ** diguyCharacter::remove_callback_with_user_data() for details.
4416  **
4417  *b Callable From:
4418  **
4419  *- - C++
4420  */
4421  int remove_default_character_callback_with_user_data(int callback_id,
4422  void* callback_user_data);
4423 
4424 
4425  /*l
4426  *b Description:
4427  **
4428  ** This function sets a default user callback that will be added
4429  ** to all new sensor regions. See
4430  ** diguySensorRegion::add_callback() for details.
4431  **
4432  *b Callable From:
4433  **
4434  *- - C++
4435  */
4436  int add_default_sensor_region_callback(int callback_id,
4437  diguySensorRegionCallback* callback,
4438  void* callback_params,
4439  void* callback_user_data,
4440  int add_to_existing_objects_flag = 0,
4441  int remove_on_scenario_load = 1);
4442 
4443  /*l
4444  *b Description:
4445  **
4446  ** This function removes a user callback. All default sensor region
4447  ** callbacks matching the specified callback_id and callback function
4448  ** will be removed.
4449  **
4450  *b Arguments:
4451  **
4452  *a callback_id - integer id of callback
4453  *a callback - pointer to function with prototype
4454  *a diguyCharacterCallback (typedefed above)
4455  **
4456  *b Callable From:
4457  **
4458  *- - C++
4459  */
4460  int remove_default_sensor_region_callback(int callback_id,
4461  diguySensorRegionCallback* callback);
4462 
4463  /*l
4464  *b Description:
4465  **
4466  ** This function removes a default user callback. All default sensor
4467  ** region callbacks matching the specified callback_id and
4468  ** callback_user_data pointer will be removed.
4469  **
4470  *b Arguments:
4471  **
4472  *a callback_id - integer id of callback
4473  *a callback_user_data - pointer for user's own use
4474  **
4475  *b Callable From:
4476  **
4477  *- - C++
4478  */
4479  int remove_default_sensor_region_callback_with_user_data(int callback_id,
4480  void* callback_user_data);
4481 
4482  /*l
4483  *b Description:
4484  **
4485  ** This function adds a default user callback that will be added
4486  ** to all new signals.
4487  **
4488  *b Callable From:
4489  **
4490  *- - C++
4491  */
4492  int add_default_signal_callback(int callback_id,
4493  diguySignalCallback* callback,
4494  void* callback_params,
4495  void* callback_user_data,
4496  int add_to_existing_objects_flag = 0,
4497  int remove_on_scenario_load = 1);
4498 
4499  /*l
4500  *b Description:
4501  **
4502  ** This function removes a user callback. All default signal
4503  ** callbacks matching the specified callback_id and callback function
4504  ** will be removed.
4505  **
4506  *b Arguments:
4507  **
4508  *a callback_id - integer id of callback
4509  *a callback - pointer to function with prototype
4510  *a diguyCharacterCallback (typedefed above)
4511  **
4512  *b Callable From:
4513  **
4514  *- - C++
4515  */
4516  int remove_default_signal_callback(int callback_id,
4517  diguySignalCallback* callback);
4518 
4519  /*l
4520  *b Description:
4521  **
4522  ** This function removes a default user callback. All default signal
4523  ** callbacks matching the specified callback_id and callback_user_data
4524  ** pointer will be removed.
4525  **
4526  *b Arguments:
4527  **
4528  *a callback_id - integer id of callback
4529  *a callback_user_data - pointer for user's own use
4530  **
4531  *b Callable From:
4532  **
4533  *- - C++
4534  */
4535  int remove_default_signal_callback_with_user_data(int callback_id,
4536  void* callback_user_data);
4537 
4538  /*l
4539  *b Description:
4540  **
4541  ** This function adds a default user callback that will be added
4542  ** to all new variables.
4543  **
4544  *b Callable From:
4545  **
4546  *- - C++
4547  */
4548  int add_default_variable_callback(int callback_id,
4549  diguyVariableCallback* callback,
4550  void* callback_params,
4551  void* callback_user_data,
4552  int add_to_existing_objects_flag = 0,
4553  int remove_on_scenario_load = 1);
4554 
4555  /*l
4556  *b Description:
4557  **
4558  ** This function removes a user callback. All default variable
4559  ** callbacks matching the specified callback_id and callback function
4560  ** will be removed.
4561  **
4562  *b Arguments:
4563  **
4564  *a callback_id - integer id of callback
4565  *a callback - pointer to function with prototype
4566  *a diguyCharacterCallback (typedefed above)
4567  **
4568  *b Callable From:
4569  **
4570  *- - C++
4571  */
4572  int remove_default_variable_callback(int callback_id,
4573  diguyVariableCallback* callback);
4574 
4575  /*l
4576  *b Description:
4577  **
4578  ** This function removes a default user callback. All default
4579  ** variable callbacks matching the specified callback_id and
4580  ** callback_user_data pointer will be removed.
4581  **
4582  *b Arguments:
4583  **
4584  *a callback_id - integer id of callback
4585  *a callback_user_data - pointer for user's own use
4586  **
4587  *b Callable From:
4588  **
4589  *- - C++
4590  */
4591  int remove_default_variable_callback_with_user_data(int callback_id,
4592  void* callback_user_data);
4593 
4594  /*l
4595  *b Description:
4596  **
4597  ** This function adds a default user callback that will be added
4598  ** to all new views.
4599  **
4600  ** Note that unlike most of the other add default callback
4601  ** functions, this one's add_to_existing_objects_flag argument
4602  ** defaults to a value of 1, since views in scenarios always
4603  ** exist and are neither created nor destroyed.
4604  **
4605  *b Callable From:
4606  **
4607  *- - C++
4608  */
4609  int add_default_view_callback(int callback_id,
4610  diguyViewCallback* callback,
4611  void* callback_params,
4612  void* callback_user_data,
4613  int add_to_existing_objects_flag = 1,
4614  int remove_on_scenario_load = 1);
4615 
4616  /*l
4617  *b Description:
4618  **
4619  ** This function removes a user callback. All default view
4620  ** callbacks matching the specified callback_id and callback function
4621  ** will be removed.
4622  **
4623  *b Arguments:
4624  **
4625  *a callback_id - integer id of callback
4626  *a callback - pointer to function with prototype
4627  *a diguyCharacterCallback (typedefed above)
4628  **
4629  *b Callable From:
4630  **
4631  *- - C++
4632  */
4633  int remove_default_view_callback(int callback_id,
4634  diguyViewCallback* callback);
4635 
4636  /*l
4637  *b Description:
4638  **
4639  ** This function removes a default user callback. All default view
4640  ** callbacks matching the specified callback_id and callback_user_data
4641  ** pointer will be removed.
4642  **
4643  *b Arguments:
4644  **
4645  *a callback_id - integer id of callback
4646  *a callback_user_data - pointer for user's own use
4647  **
4648  *b Callable From:
4649  **
4650  *- - C++
4651  */
4652  int remove_default_view_callback_with_user_data(int callback_id,
4653  void* callback_user_data);
4654 
4655  /*l
4656  *b Description:
4657  **
4658  ** This function adds a default user callback that will be added
4659  ** to all cameras.
4660  **
4661  *b Callable From:
4662  **
4663  *- - C++
4664  */
4665  int add_default_camera_callback(int callback_id,
4666  diguyViewCameraCallback* callback,
4667  void* callback_params,
4668  void* callback_user_data,
4669  int add_to_existing_objects_flag = 0,
4670  int remove_on_scenario_load = 1);
4671 
4672  /*l
4673  *b Description:
4674  **
4675  ** This function removes a user callback. All default camera
4676  ** callbacks matching the specified callback_id and callback function
4677  ** will be removed.
4678  **
4679  *b Arguments:
4680  **
4681  *a callback_id - integer id of callback
4682  *a callback - pointer to function with prototype
4683  *a diguyCharacterCallback (typedefed above)
4684  **
4685  *b Callable From:
4686  **
4687  *- - C++
4688  */
4689  int remove_default_camera_callback(int callback_id,
4690  diguyViewCameraCallback* callback);
4691 
4692  /*l
4693  *b Description:
4694  **
4695  ** This function removes a default user callback. All default camera
4696  ** callbacks matching the specified callback_id and callback_user_data
4697  ** pointer will be removed.
4698  **
4699  *b Arguments:
4700  **
4701  *a callback_id - integer id of callback
4702  *a callback_user_data - pointer for user's own use
4703  **
4704  *b Callable From:
4705  **
4706  *- - C++
4707  */
4708  int remove_default_camera_callback_with_user_data(int callback_id,
4709  void* callback_user_data);
4710 
4711  /*l
4712  *b Description:
4713  **
4714  ** This function adds a default user callback that will be added
4715  ** to all new fogs.
4716  **
4717  *b Callable From:
4718  **
4719  *- - C++
4720  */
4721  int add_default_fog_callback(int callback_id,
4722  diguyViewFogCallback* callback,
4723  void* callback_params,
4724  void* callback_user_data,
4725  int add_to_existing_objects_flag = 0,
4726  int remove_on_scenario_load = 1);
4727 
4728  /*l
4729  *b Description:
4730  **
4731  ** This function removes a user callback. All default fog
4732  ** callbacks matching the specified callback_id and callback function
4733  ** will be removed.
4734  **
4735  *b Arguments:
4736  **
4737  *a callback_id - integer id of callback
4738  *a callback - pointer to function with prototype
4739  *a diguyCharacterCallback (typedefed above)
4740  **
4741  *b Callable From:
4742  **
4743  *- - C++
4744  */
4745  int remove_default_fog_callback(int callback_id,
4746  diguyViewFogCallback* callback);
4747 
4748  /*l
4749  *b Description:
4750  **
4751  ** This function removes a default user callback. All default fog
4752  ** callbacks matching the specified callback_id and callback_user_data
4753  ** pointer will be removed.
4754  **
4755  *b Arguments:
4756  **
4757  *a callback_id - integer id of callback
4758  *a callback_user_data - pointer for user's own use
4759  **
4760  *b Callable From:
4761  **
4762  *- - C++
4763  */
4764  int remove_default_fog_callback_with_user_data(int callback_id,
4765  void* callback_user_data);
4766 
4767  /*l
4768  *b Description:
4769  **
4770  ** This function adds a default user callback that will be added
4771  ** to all new lights.
4772  **
4773  *b Callable From:
4774  **
4775  *- - C++
4776  */
4777  int add_default_light_callback(int callback_id,
4778  diguyViewLightCallback* callback,
4779  void* callback_params,
4780  void* callback_user_data,
4781  int add_to_existing_objects_flag = 0,
4782  int remove_on_scenario_load = 1);
4783 
4784  /*l
4785  *b Description:
4786  **
4787  ** This function removes a user callback. All default light
4788  ** callbacks matching the specified callback_id and callback function
4789  ** will be removed.
4790  **
4791  *b Arguments:
4792  **
4793  *a callback_id - integer id of callback
4794  *a callback - pointer to function with prototype
4795  *a diguyCharacterCallback (typedefed above)
4796  **
4797  *b Callable From:
4798  **
4799  *- - C++
4800  */
4801  int remove_default_light_callback(int callback_id,
4802  diguyViewLightCallback* callback);
4803 
4804  /*l
4805  *b Description:
4806  **
4807  ** This function removes a default user callback. All default light
4808  ** callbacks matching the specified callback_id and callback_user_data
4809  ** pointer will be removed.
4810  **
4811  *b Arguments:
4812  **
4813  *a callback_id - integer id of callback
4814  *a callback_user_data - pointer for user's own use
4815  **
4816  *b Callable From:
4817  **
4818  *- - C++
4819  */
4820  int remove_default_light_callback_with_user_data(int callback_id,
4821  void* callback_user_data);
4822 
4823 #endif
4824 
4825  /*l
4826  *b Description:
4827  **
4828  ** This function causes all of the scenario callbacks with the given
4829  ** callback_id to be called now.
4830  **
4831  *b Arguments:
4832  **
4833  *a callback_id - integer id of callback
4834  */
4835  void manually_invoke_callbacks_now(int callback_id);
4836 
4837  /*l
4838  *b Description:
4839  **
4840  ** This function adds a user callback script. Callback scripts can
4841  ** be removed with remove_callback_script().
4842  **
4843  ** See diguyCharacter::add_callback_script() for an example
4844  ** of use.
4845  **
4846  *b Arguments:
4847  **
4848  *a callback_id - integer id of the callback
4849  *a callback_script - Script text of callback to be added
4850  *a callback_script_type - the type of script contained in
4851  *a callback_script
4852  *a remove_on_scenario_load - if the callback is removed when a new
4853  *a scenario is loaded
4854  **
4855  ** If NULL is passed for callback_script_type, a default script type
4856  ** will be derived based on the default script interpreter of the
4857  ** scenario.
4858  **
4859  *i Lua specific:
4860  **
4861  ** When the script is called, the object for which it is being called
4862  ** will be in the callback_object global.
4863  **
4864  ** To pass NULL when calling from a lua script, use nil.
4865  **
4866  *b Returns:
4867  **
4868  ** 0 on success, -1 on failure
4869  */
4870  int add_callback_script(int callback_id,
4871  const char* callback_script,
4872  const char* callback_script_type = NULL,
4873  int remove_on_scenario_load = 1);
4874 
4875  /*l
4876  *b Description:
4877  **
4878  ** This function removes a user callback script previously added with
4879  ** add_callback_script().
4880  **
4881  ** See diguyCharacter::remove_callback_script() for an example
4882  ** of use.
4883  **
4884  *b Arguments:
4885  **
4886  *a callback_id - integer id of the callback
4887  *a callback_script - Script text of callback previously added
4888  *a callback_script_type - the type of script contained in
4889  *a callback_script
4890  **
4891  ** If NULL is passed for callback_script, all callback
4892  ** scripts whose ids match callback_id and whose types match
4893  ** callback_script_type will be removed.
4894  **
4895  ** If NULL is passed for callback_script_type, a default script type
4896  ** will be derived based on the default script interpreter of the
4897  ** scenario.
4898  **
4899  *i Lua specific:
4900  **
4901  ** To pass NULL when calling from a lua script, use nil.
4902  **
4903  *b Returns:
4904  **
4905  ** 0 on success, -1 on failure
4906  */
4907  int remove_callback_script(int callback_id,
4908  const char* callback_script,
4909  const char* callback_script_type = NULL);
4910 
4911  /*l
4912  *b Description:
4913  **
4914  ** This function adds a default character callback script.
4915  ** The callback script will be added to all new characters.
4916  ** See diguyCharacter::add_callback_script() for
4917  ** more details.
4918  **
4919  *b Returns:
4920  **
4921  ** 0 on success, -1 on failure
4922  */
4923  int add_default_character_callback_script(int callback_id,
4924  const char* callback_script,
4925  const char* callback_script_type = NULL,
4926  int add_to_existing_objects_flag = 0,
4927  int remove_on_scenario_load = 1);
4928 
4929  /*l
4930  *b Description:
4931  **
4932  ** This function removes a default character callback script.
4933  ** See diguyCharacter::remove_callback_script() for
4934  ** more details.
4935  **
4936  *b Returns:
4937  **
4938  ** 0 on success, -1 on failure
4939  */
4940  int remove_default_character_callback_script(int callback_id,
4941  const char* callback_script,
4942  const char* callback_script_type = NULL);
4943 
4944  /*l
4945  *b Description:
4946  **
4947  ** This function adds a default sensor region callback script.
4948  ** The callback script will be added to all new sensor regions.
4949  ** See diguySensorRegion::add_callback_script() for
4950  ** more details.
4951  **
4952  *b Returns:
4953  **
4954  ** 0 on success, -1 on failure
4955  */
4956  int add_default_sensor_region_callback_script(int callback_id,
4957  const char* callback_script,
4958  const char* callback_script_type = NULL,
4959  int add_to_existing_objects_flag = 0,
4960  int remove_on_scenario_load = 1);
4961 
4962  /*l
4963  *b Description:
4964  **
4965  ** This function removes a default sensor region callback script.
4966  ** See diguySensorRegion::remove_callback_script() for
4967  ** more details.
4968  **
4969  *b Returns:
4970  **
4971  ** 0 on success, -1 on failure
4972  */
4973  int remove_default_sensor_region_callback_script(int callback_id,
4974  const char* callback_script,
4975  const char* callback_script_type = NULL);
4976 
4977  /*l
4978  *b Description:
4979  **
4980  ** This function adds a default signal callback script.
4981  ** The callback script will be added to all new signals.
4982  ** See diguySignal::add_callback_script() for
4983  ** more details.
4984  **
4985  *b Returns:
4986  **
4987  ** 0 on success, -1 on failure
4988  */
4989  int add_default_signal_callback_script(int callback_id,
4990  const char* callback_script,
4991  const char* callback_script_type = NULL,
4992  int add_to_existing_objects_flag = 0,
4993  int remove_on_scenario_load = 1);
4994 
4995  /*l
4996  *b Description:
4997  **
4998  ** This function removes a default signal callback script.
4999  ** See diguySignal::remove_callback_script() for
5000  ** more details.
5001  **
5002  *b Returns:
5003  **
5004  ** 0 on success, -1 on failure
5005  */
5006  int remove_default_signal_callback_script(int callback_id,
5007  const char* callback_script,
5008  const char* callback_script_type = NULL);
5009 
5010  /*l
5011  *b Description:
5012  **
5013  ** This function adds a default variable callback script.
5014  ** The callback script will be added to all new variables.
5015  ** See diguySignal::add_callback_script() for
5016  ** more details.
5017  **
5018  *b Returns:
5019  **
5020  ** 0 on success, -1 on failure
5021  */
5022  int add_default_variable_callback_script(int callback_id,
5023  const char* callback_script,
5024  const char* callback_script_type = NULL,
5025  int add_to_existing_objects_flag = 0,
5026  int remove_on_scenario_load = 1);
5027 
5028  /*l
5029  *b Description:
5030  **
5031  ** This function removes a default variable callback script.
5032  ** See diguySignal::remove_callback_script() for
5033  ** more details.
5034  **
5035  *b Returns:
5036  **
5037  ** 0 on success, -1 on failure
5038  */
5039  int remove_default_variable_callback_script(int callback_id,
5040  const char* callback_script,
5041  const char* callback_script_type = NULL);
5042 
5043  /*l
5044  *b Description:
5045  **
5046  ** This function adds a default view callback script.
5047  ** The callback script will be added to all new views.
5048  ** See diguyView::add_callback_script() for
5049  ** more details.
5050  **
5051  *b Returns:
5052  **
5053  ** 0 on success, -1 on failure
5054  */
5055  int add_default_view_callback_script(int callback_id,
5056  const char* callback_script,
5057  const char* callback_script_type = NULL,
5058  int add_to_existing_objects_flag = 0,
5059  int remove_on_scenario_load = 1);
5060 
5061  /*l
5062  *b Description:
5063  **
5064  ** This function removes a default character view script.
5065  ** See diguyView::remove_callback_script() for
5066  ** more details.
5067  **
5068  *b Returns:
5069  **
5070  ** 0 on success, -1 on failure
5071  */
5072  int remove_default_view_callback_script(int callback_id,
5073  const char* callback_script,
5074  const char* callback_script_type = NULL);
5075 
5076  /*l
5077  *b Description:
5078  **
5079  ** This function adds a default camera callback script.
5080  ** The callback script will be added to all new cameras.
5081  ** See diguyViewCamera::add_callback_script() for
5082  ** more details.
5083  **
5084  *b Returns:
5085  **
5086  ** 0 on success, -1 on failure
5087  */
5088  int add_default_camera_callback_script(int callback_id,
5089  const char* callback_script,
5090  const char* callback_script_type = NULL,
5091  int add_to_existing_objects_flag = 0,
5092  int remove_on_scenario_load = 1);
5093 
5094  /*l
5095  *b Description:
5096  **
5097  ** This function removes a default camera callback script.
5098  ** See diguyViewCamera::remove_callback_script() for
5099  ** more details.
5100  **
5101  *b Returns:
5102  **
5103  ** 0 on success, -1 on failure
5104  */
5105  int remove_default_camera_callback_script(int callback_id,
5106  const char* callback_script,
5107  const char* callback_script_type = NULL);
5108 
5109  /*l
5110  *b Description:
5111  **
5112  ** This function adds a default fog callback script.
5113  ** The callback script will be added to all new fogs.
5114  ** See diguyViewFog::add_callback_script() for
5115  ** more details.
5116  **
5117  *b Returns:
5118  **
5119  ** 0 on success, -1 on failure
5120  */
5121  int add_default_fog_callback_script(int callback_id,
5122  const char* callback_script,
5123  const char* callback_script_type = NULL,
5124  int add_to_existing_objects_flag = 0,
5125  int remove_on_scenario_load = 1);
5126 
5127  /*l
5128  *b Description:
5129  **
5130  ** This function removes a default fog callback script.
5131  ** See diguyViewFog::remove_callback_script() for
5132  ** more details.
5133  **
5134  *b Returns:
5135  **
5136  ** 0 on success, -1 on failure
5137  */
5138  int remove_default_fog_callback_script(int callback_id,
5139  const char* callback_script,
5140  const char* callback_script_type = NULL);
5141 
5142  /*l
5143  *b Description:
5144  **
5145  ** This function adds a default light callback script.
5146  ** The callback script will be added to all new lights.
5147  ** See diguyViewLight::add_callback_script() for
5148  ** more details.
5149  **
5150  *b Returns:
5151  **
5152  ** 0 on success, -1 on failure
5153  */
5154  int add_default_light_callback_script(int callback_id,
5155  const char* callback_script,
5156  const char* callback_script_type = NULL,
5157  int add_to_existing_objects_flag = 0,
5158  int remove_on_scenario_load = 1);
5159 
5160  /*l
5161  *b Description:
5162  **
5163  ** This function removes a default light callback script.
5164  ** See diguyViewLight::remove_callback_script() for
5165  ** more details.
5166  **
5167  *b Returns:
5168  **
5169  ** 0 on success, -1 on failure
5170  */
5171  int remove_default_light_callback_script(int callback_id,
5172  const char* callback_script,
5173  const char* callback_script_type = NULL);
5174 
5175 
5176 /*****************************************************************************/
5192  /*l
5193  *b Description:
5194  **
5195  ** This function maps the event handler with the given name
5196  ** to a callback id. This mapping will be saved in the .dss
5197  ** file and restored when the .dss file is loaded.
5198  **
5199  ** Mappings can also be made via the DI-Guy Scenario UI.
5200  **
5201  ** The event handler is one of the following:
5202  **
5203  *- - a scenario callback function registered by
5204  *- diguyApp::register_scenario_event_handler() or
5205  *- diguyApp::register_scenario_event_handler_from_library()
5206  *- - a script registered by
5207  *- diguyApp::register_scenario_event_handler_script()
5208  *- - a Script, Decision, or Library Function in the scenario
5209  *- whose "Event Type" is "Scenario"
5210  **
5211  *b Arguments:
5212  **
5213  *a callback_id - integer id of callback
5214  *a handler_name - name of the event handler to map
5215  **
5216  *b Returns:
5217  **
5218  ** 0 on success, -1 on failure
5219  */
5220  int map_event_handler_to_callback_id(int callback_id,
5221  const char* handler_name);
5222 
5223  /*l
5224  *b Description:
5225  **
5226  ** This function unmaps the event handler with the given name
5227  ** from a callback id.
5228  **
5229  *b Arguments:
5230  **
5231  *a callback_id - integer id of callback
5232  *a handler_name - name of the event handler to map
5233  *a unmap_all_matches - pass 0 to unmap only the first match,
5234  *a pass 1 to unmap all matches
5235  **
5236  *b Returns:
5237  **
5238  ** 0 on success, -1 on failure
5239  */
5240  int unmap_event_handler_from_callback_id(int callback_id,
5241  const char* handler_name,
5242  int unmap_all_matches = 0);
5243 
5244  /*l
5245  *b Description:
5246  **
5247  ** This function manually invokes the named scenario event handler.
5248  ** The callback_id that will be passed to the event handler will
5249  ** be CALLBACK_ID_MANUALLY_INVOKED.
5250  **
5251  ** Note that care should be taken not to end up in an infinite loop
5252  ** of event calls. In general an event handler should not end up
5253  ** directly or indirectly invoking itself.
5254  **
5255  ** The event handler is one of the following:
5256  **
5257  *- - a scenario callback function registered by
5258  *- diguyApp::register_scenario_event_handler() or
5259  *- diguyApp::register_scenario_event_handler_from_library()
5260  *- - a script registered by
5261  *- diguyApp::register_scenario_event_handler_script()
5262  *- - a Script, Decision, or Library Function in the scenario
5263  *- whose "Event Type" is "Scenario"
5264  **
5265  *b Arguments:
5266  **
5267  *a handler_name - name of the event handler to invoke
5268  **
5269  *b Returns:
5270  **
5271  ** DIGUY_CALLBACK_CONTINUE or DIGUY_CALLBACK_STOP
5272  **
5273  *b Callable From:
5274  **
5275  *- - C++
5276  *- - Script
5277  *- - Decision
5278  */
5279  diguyCallbackReturn manually_invoke_event_handler(const char* handler_name);
5280 
5281 #ifdef CPLUSPLUS_ONLY
5282 
5283  /*l
5284  *b Description:
5285  **
5286  ** This function registers a character event handler
5287  ** function that can later be mapped via a call to
5288  ** diguyCharacter::map_event_handler_to_callback_id().
5289  **
5290  ** Call unregister_character_event_handler() to
5291  ** unregister the function.
5292  **
5293  *b Arguments:
5294  **
5295  *a handler_name - name of the event handler
5296  *a callback - pointer to handler function
5297  *a callback_user_data - pointer for user's own use; DI-Guy will
5298  *a do nothing to the contents of this pointer
5299  *a beyond passing it back when the handler
5300  *a function is called
5301  **
5302  *b Returns:
5303  **
5304  ** 0 on success, -1 on failure
5305  **
5306  *b Callable From:
5307  **
5308  *- - C++
5309  */
5310  int register_character_event_handler(const char* handler_name,
5311  diguyCharacterCallback* callback,
5312  void* callback_user_data = 0);
5313 
5314 #endif
5315 
5316  /*l
5317  *b Description:
5318  **
5319  ** This function registers a character event handler
5320  ** function that can later be mapped via a call to
5321  ** diguyCharacter::map_event_handler_to_callback_id().
5322  **
5323  ** Unlike register_character_event_handler(), which directly
5324  ** passes a function pointer, this function looks up the
5325  ** function pointer from a shared library (a .dll under
5326  ** Windows, a .so under Unix).
5327  **
5328  ** The passed library_name should not include the
5329  ** .dll or .so extension; these will be added automatically.
5330  ** This allows for cross-platform scenarios that don't
5331  ** have differing dynamic library extensions built into
5332  ** them.
5333  **
5334  ** Call unregister_character_event_handler() to
5335  ** unregister the function.
5336  **
5337  *b Arguments:
5338  **
5339  *a handler_name - name of the event handler
5340  *a library_name - pointer to handler function
5341  *a function_name - pointer to handler function
5342  *a callback_user_data - pointer for user's own use; DI-Guy will
5343  *a do nothing to the contents of this pointer
5344  *a beyond passing it back when the handler
5345  *a function is called
5346  **
5347  *b Returns:
5348  **
5349  ** 0 on success, -1 on failure
5350  */
5351  int register_character_event_handler_from_library(const char* handler_name,
5352  const char* library_name,
5353  const char* function_name,
5354  void* callback_user_data = 0);
5355 
5356  /*l
5357  *b Description:
5358  **
5359  ** This function registers a character event handler
5360  ** script that can later be mapped via a call to
5361  ** diguyCharacter::map_event_handler_to_callback_id().
5362  **
5363  ** Call unregister_character_event_handler() to
5364  ** unregister the script.
5365  **
5366  *b Arguments:
5367  **
5368  *a handler_name - name of the event handler
5369  *a handler_script - Script text
5370  *a handler_script_type - type of script; pass NULL
5371  *a for scenario to use the default
5372  *a script interpreter
5373  **
5374  *b Returns:
5375  **
5376  ** 0 on success, -1 on failure
5377  */
5378  int register_character_event_handler_script(const char* handler_name,
5379  const char* handler_script,
5380  const char* handler_script_type = 0);
5381 
5382  /*l
5383  *b Returns:
5384  **
5385  ** 1 if there is a character event handler with the given
5386  ** name, 0 if not
5387  **
5388  *b Arguments:
5389  **
5390  *a handler_name - name of the event handler
5391  */
5392  int has_registered_character_event_handler(const char* handler_name);
5393 
5394  /*l
5395  *b Description:
5396  **
5397  ** This function unregisters a character event handler.
5398  ** This will unmap the event handler from any mappings
5399  ** it is a part of.
5400  **
5401  *b Arguments:
5402  **
5403  *a handler_name - name of the event handler
5404  **
5405  *b Returns:
5406  **
5407  ** 0 on success, -1 on failure
5408  */
5409  int unregister_character_event_handler(const char* handler_name);
5410 
5411 #ifdef CPLUSPLUS_ONLY
5412 
5413  /*l
5414  *b Description:
5415  **
5416  ** This function is analogous to the
5417  ** register_character_event_handler() function,
5418  ** but is for signals rather than characters.
5419  **
5420  *b Callable From:
5421  **
5422  *- - C++
5423  */
5424  int register_signal_event_handler(const char* handler_name,
5425  diguySignalCallback* callback,
5426  void* callback_user_data = 0);
5427 
5428 #endif
5429 
5430  /*l
5431  *b Description:
5432  **
5433  ** This function is analogous to the
5434  ** register_character_event_handler_from_library() function,
5435  ** but is for signals rather than characters.
5436  */
5437  int register_signal_event_handler_from_library(const char* handler_name,
5438  const char* library_name,
5439  const char* function_name,
5440  void* callback_user_data = 0);
5441 
5442  /*l
5443  *b Description:
5444  **
5445  ** This function is analogous to the
5446  ** register_character_event_handler_script() function,
5447  ** but is for signals rather than characters.
5448  */
5449  int register_signal_event_handler_script(const char* handler_name,
5450  const char* handler_script,
5451  const char* handler_script_type = 0);
5452 
5453  /*l
5454  *b Description:
5455  **
5456  ** This function is analogous to the
5457  ** has_registered_character_event_handler() function,
5458  ** but is for signals rather than characters.
5459  */
5460  int has_registered_signal_event_handler(const char* handler_name);
5461 
5462  /*l
5463  *b Description:
5464  **
5465  ** This function is analogous to the
5466  ** unregister_character_event_handler() function,
5467  ** but is for signals rather than characters.
5468  */
5469  int unregister_signal_event_handler(const char* handler_name);
5470 
5471 #ifdef CPLUSPLUS_ONLY
5472 
5473  /*l
5474  *b Description:
5475  **
5476  ** This function is analogous to the
5477  ** register_character_event_handler() function,
5478  ** but is for sensor regions rather than characters.
5479  **
5480  *b Callable From:
5481  **
5482  *- - C++
5483  */
5484  int register_sensor_region_event_handler(const char* handler_name,
5485  diguySensorRegionCallback* callback,
5486  void* callback_user_data = 0);
5487 
5488 #endif
5489 
5490  /*l
5491  *b Description:
5492  **
5493  ** This function is analogous to the
5494  ** register_character_event_handler_from_library() function,
5495  ** but is for sensor regions rather than characters.
5496  */
5497  int register_sensor_region_event_handler_from_library(const char* handler_name,
5498  const char* library_name,
5499  const char* function_name,
5500  void* callback_user_data = 0);
5501 
5502  /*l
5503  *b Description:
5504  **
5505  ** This function is analogous to the
5506  ** register_character_event_handler_script() function,
5507  ** but is for sensor regions rather than characters.
5508  */
5509  int register_sensor_region_event_handler_script(const char* handler_name,
5510  const char* handler_script,
5511  const char* handler_script_type = 0);
5512 
5513  /*l
5514  *b Description:
5515  **
5516  ** This function is analogous to the
5517  ** has_registered_character_event_handler() function,
5518  ** but is for sensor regions rather than characters.
5519  */
5520  int has_registered_sensor_region_event_handler(const char* handler_name);
5521 
5522  /*l
5523  *b Description:
5524  **
5525  ** This function is analogous to the
5526  ** unregister_character_event_handler() function,
5527  ** but is for sensor regions rather than characters.
5528  */
5529  int unregister_sensor_region_event_handler(const char* handler_name);
5530 
5531 #ifdef CPLUSPLUS_ONLY
5532 
5533  /*l
5534  *b Description:
5535  **
5536  ** This function is analogous to the
5537  ** register_character_event_handler() function,
5538  ** but is for variables rather than characters.
5539  **
5540  *b Callable From:
5541  **
5542  *- - C++
5543  */
5544  int register_variable_event_handler(const char* handler_name,
5545  diguyVariableCallback* callback,
5546  void* callback_user_data = 0);
5547 
5548 #endif
5549 
5550  /*l
5551  *b Description:
5552  **
5553  ** This function is analogous to the
5554  ** register_character_event_handler_from_library() function,
5555  ** but is for variables rather than characters.
5556  */
5557  int register_variable_event_handler_from_library(const char* handler_name,
5558  const char* library_name,
5559  const char* function_name,
5560  void* callback_user_data = 0);
5561 
5562  /*l
5563  *b Description:
5564  **
5565  ** This function is analogous to the
5566  ** register_character_event_handler_script() function,
5567  ** but is for variables rather than characters.
5568  */
5569  int register_variable_event_handler_script(const char* handler_name,
5570  const char* handler_script,
5571  const char* handler_script_type = 0);
5572 
5573  /*l
5574  *b Description:
5575  **
5576  ** This function is analogous to the
5577  ** has_registered_character_event_handler() function,
5578  ** but is for variables rather than characters.
5579  */
5580  int has_registered_variable_event_handler(const char* handler_name);
5581 
5582  /*l
5583  *b Description:
5584  **
5585  ** This function is analogous to the
5586  ** unregister_character_event_handler() function,
5587  ** but is for variables rather than characters.
5588  */
5589  int unregister_variable_event_handler(const char* handler_name);
5590 
5591 
5592 
5593 /*****************************************************************************/
5603  /*l
5604  *b Description:
5605  **
5606  ** This function saves the current run of the scenario to the
5607  ** specified file, and other files whose names are derived from
5608  ** the passed filename. The passed filename should end with the
5609  ** extension ".dsr" (DI-Guy Review).
5610  **
5611  ** The review data can be reloaded later by calling the load()
5612  ** function, and passing the same filename.
5613  **
5614  ** The following is saved for later review:
5615  **
5616  *- - all character positions and poses
5617  *- - sounds played by characters due to play_sound() and
5618  ** fire_weapon_n_times() calls
5619  **
5620  ** Note that Paths, Waypoints, and Event Beads per se are *not* saved,
5621  ** but rather their effects on the characters' positions and poses.
5622  **
5623  *b Arguments:
5624  **
5625  *a filename - file in which to save review data
5626  **
5627  *b Returns:
5628  **
5629  ** 0 on success, -1 on failure
5630  *b C++ Example:
5631  **
5632  *e // when shutting down the current run:
5633  *e scenario->save_review_data("review0.dsr");
5634  *e
5635  *e // when after action review is needed:
5636  *e scenario->load("review0.dsr");
5637  */
5638  int save_review_data(const char* filename);
5639 
5640  /*l
5641  *b Returns:
5642  **
5643  ** 1 if scenario was loaded from review data (from a .dsr file);
5644  ** 0 if not (from a .dss file)
5645  */
5646  int get_loaded_from_review_data();
5647 
5648  /*l
5649  *b Description:
5650  **
5651  ** This function sets what type of "history" will be kept for the
5652  ** scenario.
5653  **
5654  ** If time is run backwards in a scenario with history,
5655  ** the following will be "remembered" and replayed:
5656  **
5657  *- - camera settings currently in the primary view's camera
5658  *- - signal trigger counts
5659  *- - enabled/disabled status of scene objects
5660  *- - sounds
5661  **
5662  ** The default is DIGUY_HISTORY_TYPE_NONE for scenarios created
5663  ** using the DI-Guy API, and DIGUY_HISTORY_TYPE_COMPLETE for scenarios
5664  ** created using the DI-Guy Scenario editor.
5665  **
5666  *b Arguments:
5667  **
5668  *a history_type - history type to be used for the scenario
5669  **
5670  ** history_type should be one of the following values:
5671  **
5672  *i DIGUY_HISTORY_TYPE_NONE
5673  **
5674  ** This history type saves no history.
5675  **
5676  *i DIGUY_HISTORY_TYPE_COMPLETE
5677  **
5678  ** This history type saves a complete history.
5679  **
5680  ** DIGUY_HISTORY_TYPE_LAST and DIGUY_HISTORY_TYPE_FIRST are not
5681  ** supported for scenario history.
5682  **
5683  *b Returns:
5684  **
5685  ** 0 on success, -1 on failure
5686  */
5687  int set_history_type(diguyHistoryType history_type);
5688 
5689  /*l
5690  *b Returns:
5691  **
5692  ** the current history type of the scenario; see
5693  ** set_history_type()
5694  */
5695  diguyHistoryType get_history_type();
5696 
5697  /*l
5698  *b Description:
5699  **
5700  ** This function sets the history type for this scenario, as well as
5701  ** the history types of all characters.
5702  **
5703  ** See also diguyScenario::set_history_type() and
5704  ** diguyCharacter::set_history_type().
5705  **
5706  *b Arguments:
5707  **
5708  *a history_type - history type to be used for the scenario and all
5709  *a characters
5710  */
5711  void set_overall_history_type(diguyHistoryType overall_history_type);
5712 
5713  /*l
5714  *b Description:
5715  **
5716  ** This function returns the overall history type of the scenario.
5717  **
5718  ** The return value will be:
5719  **
5720  *- - DIGUY_HISTORY_TYPE_COMPLETE if history is enabled for the
5721  *- scenario and *all* characters
5722  *- - DIGUY_HISTORY_TYPE_PARTIAL if history is enabled for at least
5723  *- one of the scenario or any character, but not all
5724  *- - DIGUY_HISTORY_TYPE_NONE if history is not enabled for the
5725  *- scenario or any character
5726  **
5727  ** See also diguyScenario::get_history_type() and
5728  ** diguyCharacter::get_history_type().
5729  */
5730  diguyHistoryType get_overall_history_type();
5731 
5732  /*l
5733  *b Returns:
5734  **
5735  ** whether the scenario is playing back stored history
5736  */
5737  int get_replaying_history();
5738 
5739  /*l
5740  *b Description:
5741  **
5742  ** This function sets how many sound instances are kept in memory when
5743  ** history is enabled. By keeping them in memory, users can "scrub"
5744  ** backwards in time and hear sounds that were started earlier in time
5745  ** and will be resumed at the proper offset into the sound. This
5746  ** function lets users balance that need with memory management.
5747  **
5748  *b Arguments:
5749  **
5750  *a num_sound_instances - override system default of 100
5751  **
5752  *b Returns:
5753  **
5754  ** none
5755  */
5756  void set_history_max_sound_instances(int num_sound_instances);
5757 
5758 
5759 /*****************************************************************************/
5769  /*l
5770  *b Description:
5771  **
5772  ** This function sets whether automatic graphics LOD switching
5773  ** should be enabled for certain graphics environments (see below).
5774  **
5775  ** By default it is enabled in DI-Guy Scenario, and disabled in a
5776  ** DI-Guy API application.
5777  **
5778  ** There are two ways that DI-Guy calculates the proper
5779  ** graphics LOD. For some graphics environments the calculation
5780  ** is done "manually", using data from a diguyViewCamera.
5781  ** In other environments the calculation is done by the graphics
5782  ** environment itself. The method used in each graphics
5783  ** environment is noted below.
5784  **
5785  *i OpenGL Version:
5786  **
5787  ** This function enables or disables automatic LOD switching.
5788  ** In this graphics environment LOD calculations are done by
5789  ** the renderer; information from the diguyViewCamera is not
5790  ** used.
5791  **
5792  *i DI-Guy Graphics API Version:
5793  **
5794  ** This function enables or disables automatic LOD switching.
5795  ** In this graphics environment LOD calculations are done by
5796  ** the renderer; information from the diguyViewCamera is not
5797  ** used.
5798  */
5799  void set_automatic_graphics_lod_switching(int enable_graphics_lod_switching);
5800 
5802  int get_automatic_graphics_lod_switching();
5803 
5804  /*l
5805  *b Description:
5806  **
5807  ** Turns on skinned instancing system can yield much fast rendering, this value is initially
5808  ** set by use_shader_instancing in the diguy graphics init structures.
5809  */
5810  void set_instancing_enabled(int val);
5811 
5813  int get_instancing_enabled() const;
5814 
5815  /*l
5816  *b Description:
5817  **
5818  ** Sets the minimum LOD that instancing activates for this defaults to LOD 7.
5819  */
5820  void set_instancing_min_lod(int val);
5821 
5823  int get_instancing_min_lod() const;
5824 
5825 #ifdef CPLUSPLUS_ONLY
5826 
5827  /*l
5828  *b Description:
5829  **
5830  ** Sets the distances at which level of detail switching occurs
5831  ** for characters of the specified type. Existing characters
5832  ** are not affected; only newly created characters will have the
5833  ** specified LOD switching ranges.
5834  **
5835  ** Characters will display with the highest level of detail when
5836  ** viewed from a distance between ranges[0] and ranges[1].
5837  ** Characters will not display at all when viewed from further
5838  ** away than the highest switching range.
5839  **
5840  ** Note: ranges[0] should almost always be 0.0.
5841  **
5842  *b Arguments:
5843  **
5844  *a character_type - character type name, as returned by
5845  *a get_character_type_at_index()
5846  *a ranges - an array of 8 non-negative floating point numbers,
5847  *a each larger than the one before, specifying the
5848  *a LOD switching ranges in meters
5849  **
5850  ** Pass "all" for character_type to set the default ranges of all
5851  ** character types.
5852  **
5853  ** The table below indicates the number of polygons for one of the
5854  ** default soldier models in each level of detail, and the LOD
5855  ** switching ranges in effect before this function is called.
5856  **
5857  *e lod polys min max
5858  *e --------------------------
5859  *e 1 2300 0 5
5860  *e 2 900 5 10
5861  *e 3 550 10 20
5862  *e 4 280 20 40
5863  *e 5 130 40 70
5864  *e 6 60 70 100
5865  *e 7 40 100 1000
5866  **
5867  *b Callable From:
5868  **
5869  *- - C++
5870  */
5871  void set_default_lod_ranges(const char* character_type, float* ranges);
5872 
5873 #endif
5874 
5875  /*l
5876  *b Description:
5877  **
5878  ** This function sets whether view and camera settings such as
5879  ** field-of-view (FOV) and window size should be taken into account
5880  ** when determining the graphics LOD from a character's LOD ranges.
5881  **
5882  ** The camera settings that are used are taken from the current
5883  ** render camera, as set by set_render_camera(). This happens
5884  ** automatically in DI-Guy Scenario, but must be set manually
5885  ** in the DI-Guy SDK.
5886  **
5887  ** DI-Guy graphics LODs are distance-based, but this approach can
5888  ** be problematic if the current camera's FOV is very narrow; a
5889  ** narrow FOV essentially acts like a telephoto lens. In this case
5890  ** a character that is far away, and would therefore be rendered
5891  ** with few polygons, can actually be quite large in the 3D view.
5892  **
5893  ** Setting this flag to 1 will cause the FOV to be taken into account
5894  ** when calculating the effective distance of a character from the
5895  ** camera.
5896  **
5897  ** Many DI-Guy LOD distances assume that the vertical FOV of the
5898  ** view is around 40. Smaller FOVs will scale the distances larger
5899  ** so that LOD changes happen further out. Likewise larger FOVs
5900  ** will scale the distances smaller; in this case even nearby
5901  ** characters will appear small and therefore need less resolution.
5902  **
5903  *b Arguments:
5904  **
5905  ** do_scale - pass 1 to enable scaling, 0 to disable
5906  */
5907  void set_scale_graphics_lod_ranges_from_view_settings(int do_scale);
5908 
5909  /*l
5910  *b Returns:
5911  **
5912  ** most recent setting of
5913  ** set_scale_graphics_lod_ranges_from_view_settings()
5914  */
5915  int get_scale_graphics_lod_ranges_from_view_settings();
5916 
5917  /*l
5918  *b Description:
5919  **
5920  ** This function sets whether automatic motion LOD switching
5921  ** should be enabled.
5922  **
5923  ** By default it is enabled in DI-Guy Scenario, and disabled in a
5924  ** DI-Guy API application.
5925  **
5926  ** When running in a user application that uses the DI-Guy
5927  ** API, the primary view's camera's position and orientation
5928  ** must be kept consistent with the application's perception
5929  ** of current camera settings. A pointer to the primary view's
5930  ** camera can be obtained by calling get_scenario_camera().
5931  **
5932  ** The following describes the algorithm used by automatic motion
5933  ** LOD switching:
5934  **
5935  *- - if a character is in front of the primary view's camera,
5936  *- the motion LOD is set to 1 (animate all joints)
5937  *- - else set motion LOD to 5 (stop animating everything but
5938  *- base position)
5939  **
5940  ** Note that if there are multiple views open on the scenario,
5941  ** the character must be behind *all* cameras for the motion
5942  ** LOD to be set to 5.
5943  **
5944  ** Also, if the history type of the character (as set by
5945  ** diguyCharacter::set_history_type()) is anything but
5946  ** DIGUY_HISTORY_TYPE_NONE, motion LOD 1 will be used since
5947  ** during scenario playback the character might be in front
5948  ** of any camera.
5949  */
5950  void set_automatic_motion_lod_switching(int enable_motion_lod_switching);
5951 
5952  /*l
5953  *b Description:
5954  **
5955  ** This function returns whether automatic motion LOD switching
5956  ** is be enabled for characters in the scenario, as set by
5957  ** set_automatic_motion_lod_switching().
5958  **
5959  *b Returns:
5960  **
5961  ** 1 if LODs enabled; 0 if not
5962  */
5963  int get_automatic_motion_lod_switching();
5964 
5965 
5966 /*****************************************************************************/
5976  /*l
5977  *b Description:
5978  **
5979  ** This function sends the passed string through the script
5980  ** interpreter.
5981  **
5982  *b Arguments:
5983  **
5984  *a script_text - string to be evaluated
5985  *a save_as_transient - flag stating whether script_text should
5986  *a be remembered as a transient event at
5987  *a the current scenario t; see
5988  *a push_transient_script_event()
5989  *a script_type - type of script contained in script_text; pass
5990  *a NULL to use scenario's default interpreter
5991  *a script_source - string identifying the 'source' of the script;
5992  *a will be printed in error output if there are
5993  *a syntax errors in the script
5994  **
5995  *b Returns:
5996  **
5997  ** 0 on success, -1 on failure
5998  **
5999  *b C++ Example:
6000  **
6001  *e scenario->eval_script("signal1:trigger();",
6002  *e 0,
6003  *e "lua",
6004  *e "User Script");
6005  */
6006  int eval_script(const char* script_text,
6007  int save_as_transient = 0,
6008  const char* script_type = NULL,
6009  const char* script_source = NULL);
6010 
6011  /*l
6012  *b Description:
6013  **
6014  ** This function sends the contents of the specified file through
6015  ** the script interpreter.
6016  **
6017  *b Arguments:
6018  **
6019  *a filename - filename of script to be evaluated
6020  *a script_type - type of script contained in file; pass NULL
6021  *a to use the scenario's default interpreter
6022  **
6023  *b Returns:
6024  **
6025  ** 0 on success, -1 on failure
6026  **
6027  *b C++ Example:
6028  **
6029  *e scenario->eval_script_file("my_scripts.pl");
6030  */
6031  int eval_script_file(const char* filename,
6032  const char* script_type = NULL);
6033 
6034  /*l
6035  *b Description:
6036  **
6037  ** This function manually triggers a script.
6038  **
6039  *b Arguments:
6040  **
6041  *a script_name - name of the script to be triggered
6042  **
6043  *b Returns:
6044  **
6045  ** return result of script; 0 if script not found
6046  **
6047  *b Callable From:
6048  **
6049  *- - C++
6050  *- - Script
6051  *- - Decision
6052  */
6053  int trigger_script(const char* script_name);
6054 
6055  /*l
6056  *b Description:
6057  **
6058  ** This function is similar to trigger_script(), but delays the
6059  ** trigger by the specified time.
6060  **
6061  *b Arguments:
6062  **
6063  *a script_name - name of the script to be triggered
6064  *a t_delay - how many seconds to delay trigger
6065  **
6066  *b Callable From:
6067  **
6068  *- - C++
6069  *- - Script
6070  *- - Decision
6071  */
6072  void trigger_script_delayed(const char* script_name, float t_delay);
6073 
6074  /*l
6075  *b Description:
6076  **
6077  ** This function manually triggers a decision.
6078  **
6079  *b Arguments:
6080  **
6081  *a decision_name - name of the decision to be triggered
6082  **
6083  *b Returns:
6084  **
6085  ** return result of decision; 0 if decision not found
6086  **
6087  *b Callable From:
6088  **
6089  *- - C++
6090  *- - Script
6091  *- - Decision
6092  */
6093  int trigger_decision(const char* decision_name);
6094 
6095  /*l
6096  *b Description:
6097  **
6098  ** This function is similar to trigger_decision(), but delays the
6099  ** trigger by the specified time.
6100  **
6101  *b Arguments:
6102  **
6103  *a decision_name - name of the decision to be triggered
6104  *a t_delay - how many seconds to delay trigger
6105  **
6106  *b Callable From:
6107  **
6108  *- - C++
6109  *- - Script
6110  *- - Decision
6111  */
6112  void trigger_decision_delayed(const char* decision_name, float t_delay);
6113 
6114  /*l
6115  *b Description:
6116  **
6117  ** This function places the passed script text on a list of scripts
6118  ** that should be re-evaluated when the scenario is replayed from
6119  ** review data.
6120  **
6121  ** Note that the script is *not* evaluated at this time. This can be
6122  ** done by calling eval_script() and passing 1 for the
6123  ** save_as_transient argument.
6124  **
6125  ** If the scenario is reset (as in a call to reset()), all transient
6126  ** scripts will be deleted. The transient script events can be saved
6127  ** and restored by calling save_transient_script_events() and
6128  ** load_transient_script_events(), respectively.
6129  **
6130  *b Arguments:
6131  **
6132  *a t - time at which script should be re-evaluated
6133  *a during scenario playback
6134  *a script_text - Script to be evaluated
6135  *a script_type - Scripting language to use (lua)
6136  **
6137  ** A copy of the passed script text is made.
6138  **
6139  *b Returns:
6140  **
6141  ** 0 on success, -1 on failure
6142  */
6143  void push_transient_script_event(float t, const char* script_text, const char* script_type);
6144 
6145  /*l
6146  *b Description:
6147  **
6148  ** This function deletes all transient script events.
6149  */
6150  void clear_transient_script_events();
6151 
6152  /*l
6153  *b Description:
6154  **
6155  ** This function saves the transient script events to the specified
6156  ** file. They can be restored by calling
6157  ** load_transient_script_events() with the same filename.
6158  **
6159  *b Arguments:
6160  **
6161  *a filename - file in which transient script events should be saved
6162  **
6163  *b Returns:
6164  **
6165  ** 0 on success, -1 on failure
6166  */
6167  int save_transient_script_events(const char* filename);
6168 
6169  /*l
6170  *b Description:
6171  **
6172  ** This function loads transient script events saved by a call to
6173  ** save_transient_script_events().
6174  **
6175  *b Arguments:
6176  **
6177  *a filename - file from which transient script events should be
6178  *a loaded
6179  **
6180  *b Returns:
6181  **
6182  ** 0 on success, -1 on failure
6183  */
6184  int load_transient_script_events(const char* filename);
6185 
6186  /*l
6187  *b Description:
6188  **
6189  ** This function creates a package object that points to an external
6190  ** file. If the language is not specified it will be determined based
6191  ** on the filename's extension. DI-Guy will attempt to derive an
6192  ** appropriate name for the package. In DI-Guy Scenario package
6193  ** dependencies are also extracted and loaded; currently this must be
6194  ** done manually in the SDK.
6195  */
6196  int load_package(const char* filename,
6197  const char* language = NULL,
6198  int warn_if_not_found = 1);
6199 
6200  /*l
6201  *b Description:
6202  **
6203  ** Documentation Pending
6204  */
6205  int load_package_with_dependancy(const char* filename,
6206  const char* depends_on_package,
6207  const char* language = NULL,
6208  int warn_if_not_found = 1);
6209 
6210 
6211 /*****************************************************************************/
6221  /*l
6222  *b Description:
6223  **
6224  ** This function returns the number of postures the specified
6225  ** character type's actions support.
6226  **
6227  ** Use this function along with get_character_type_posture_at_index()
6228  ** to enumerate the character's postures.
6229  **
6230  *b Arguments:
6231  **
6232  *a character_type - character type name, as returned by
6233  *a get_character_type_at_index(), for example
6234  **
6235  *b Returns:
6236  **
6237  ** the number of postures the specified character type's actions
6238  ** support
6239  */
6240  int get_character_type_num_postures(const char* character_type);
6241 
6242  /*l
6243  *b Description:
6244  **
6245  ** This function returns the posture at the specified index.
6246  **
6247  ** Use this function along with get_character_type_num_postures()
6248  ** to enumerate the character's postures.
6249  **
6250  *b Arguments:
6251  **
6252  *a character_type - character type name, as returned by
6253  *a get_character_type_at_index(), for example
6254  *a index - index of the posture; indices start at 0
6255  **
6256  *b Returns:
6257  **
6258  ** the posture at the specified index
6259  */
6260  diguyMotionPosture get_character_type_posture_at_index(const char* character_type,
6261  int index);
6262 
6263  /*l
6264  *b Description:
6265  **
6266  ** This function returns the overall posture of the specified action.
6267  **
6268  ** The results of this function call can be useful in calls to the
6269  ** diguyCharacter::get_action_from_description() function, if
6270  ** for example an action with the same posture but a faster speed
6271  ** is desired.
6272  **
6273  *b Arguments:
6274  **
6275  *a character_type - character type name, as returned by
6276  *a get_character_type_at_index(), for example
6277  *a action_name - the action to query
6278  **
6279  *b Returns:
6280  **
6281  ** the overall posture of the specified action
6282  */
6283  diguyMotionPosture get_character_type_action_posture(const char* character_type,
6284  const char* action_name);
6285 
6286  /*l
6287  *b Description:
6288  **
6289  ** This function returns the number of variants the specified
6290  ** character type's actions support.
6291  **
6292  ** Use this function along with get_character_type_variant_at_index()
6293  ** to enumerate the character's variants.
6294  **
6295  ** This function differs from
6296  ** get_character_type_action_num_variants() in that this function
6297  ** returns the number of variants of *all* actions of the
6298  ** character. The other function returns the number of variants
6299  ** of a single action.
6300  **
6301  *b Arguments:
6302  **
6303  *a character_type - character type name, as returned by
6304  *a get_character_type_at_index(), for example
6305  **
6306  *b Returns:
6307  **
6308  ** the number of variants the specified character type's actions
6309  ** support
6310  */
6311  int get_character_type_num_variants(const char* character_type);
6312 
6313  /*l
6314  *b Description:
6315  **
6316  ** This function returns the variant at the specified index.
6317  **
6318  ** Use this function along with get_character_type_num_variants()
6319  ** to enumerate the character's variants.
6320  **
6321  ** This function differs from
6322  ** get_character_type_action_variant_at_index() in that this function
6323  ** returns one of the variants of *all* actions of the
6324  ** character. The other function returns one of the variants
6325  ** of a single action.
6326  **
6327  *b Arguments:
6328  **
6329  *a character_type - character type name, as returned by
6330  *a get_character_type_at_index(), for example
6331  *a index - index of the posture; indices start at 0
6332  **
6333  *b Returns:
6334  **
6335  ** the variant at the specified index
6336  */
6337  diguyMotionVariant get_character_type_variant_at_index(const char* character_type,
6338  int index);
6339 
6340  /*l
6341  *b Description:
6342  **
6343  ** This function returns the primary variant of the specified action.
6344  **
6345  *b Arguments:
6346  **
6347  *a character_type - character type name, as returned by
6348  *a get_character_type_at_index(), for example
6349  *a action_name - the action to query
6350  **
6351  *b Returns:
6352  **
6353  ** the overall variant of the specified action
6354  */
6355  diguyMotionVariant get_character_type_action_primary_variant(const char* character_type,
6356  const char* action_name);
6357 
6358  /*l
6359  *b Description:
6360  **
6361  ** This function returns the number of variants the specified
6362  ** action of the specified character type has.
6363  **
6364  ** Use this function along with
6365  ** get_character_type_action_variant_at_index()
6366  ** to enumerate the character's variants.
6367  **
6368  ** This function differs from
6369  ** get_character_type_num_variants() in that this function
6370  ** returns the number of variants of a single action of the
6371  ** character. The other function returns the number of variants
6372  ** of *all* actions.
6373  **
6374  *b Arguments:
6375  **
6376  *a character_type - character type name, as returned by
6377  *a get_character_type_at_index(), for example
6378  *a action_name - the action to query
6379  **
6380  *b Returns:
6381  **
6382  ** the number of variants of the specified action of the specified
6383  ** character type
6384  */
6385  int get_character_type_action_num_variants(const char* character_type,
6386  const char* action_name);
6387 
6388  /*l
6389  *b Description:
6390  **
6391  ** This function returns the variant at the specified index.
6392  **
6393  ** Use this function along with
6394  ** get_character_type_action_num_variants()
6395  ** to enumerate the character's variants.
6396  **
6397  ** This function differs from
6398  ** get_character_type_variant_at_index() in that this function
6399  ** returns one of the variants of a single action of the
6400  ** character. The other function returns one of the variants
6401  ** of *all* actions.
6402  **
6403  *b Arguments:
6404  **
6405  *a character_type - character type name, as returned by
6406  *a get_character_type_at_index(), for example
6407  *a index - index of the posture; indices start at 0
6408  **
6409  *b Returns:
6410  **
6411  ** the variant at the specified index
6412  */
6413  diguyMotionVariant get_character_type_action_variant_at_index(const char* character_type,
6414  const char* action_name,
6415  int index);
6416 
6417  /*l
6418  *b Description:
6419  **
6420  ** This function returns the number of directions the specified
6421  ** character type's actions can move.
6422  **
6423  ** Use the get_character_type_direction_at_index() function to
6424  ** enumerate the directions available to a character.
6425  **
6426  ** The results of this function call can be useful in calls to the
6427  ** diguyCharacter::get_action_from_description() function.
6428  **
6429  *b Arguments:
6430  **
6431  *a character_type - character type name, as returned by
6432  *a get_character_type_at_index(), for example
6433  **
6434  *b Returns:
6435  **
6436  ** the number of directions the specified character type's actions
6437  ** can move
6438  */
6439  int get_character_type_num_directions(const char* character_type);
6440 
6441  /*l
6442  *b Description:
6443  **
6444  ** Use the get_character_type_num_directions() function to
6445  ** get the number of directions available to a character.
6446  **
6447  ** The results of this function call can be useful in calls to the
6448  ** diguyCharacter::get_action_from_description() function.
6449  **
6450  *b Arguments:
6451  **
6452  *a character_type - character type name, as returned by
6453  *a get_character_type_at_index(), for example
6454  *a index - index of the direction; indices start at 0
6455  **
6456  *b Returns:
6457  **
6458  ** the direction at the specified index
6459  */
6460  diguyMotionDirection get_character_type_direction_at_index(const char* character_type,
6461  int index);
6462 
6463 
6464 /*****************************************************************************/
6490  /*l
6491  *b Returns:
6492  **
6493  ** number of interaction machines in the scenario
6494  */
6495  int get_num_interaction_machines();
6496 
6497  /*l
6498  *b Description:
6499  **
6500  ** This function creates a new interaction machine and returns a
6501  ** pointer to it.
6502  **
6503  ** Note that there is a shared interaction machine that always
6504  ** exists; a pointer to it can be obtained by calling
6505  ** get_shared_interaction_machine(). See that function for more
6506  ** details.
6507  **
6508  *b Arguments:
6509  **
6510  *a name - name of the new interaction machine
6511  **
6512  *b Returns:
6513  **
6514  ** pointer of type diguyInteractionMachine; NULL if creation failed
6515  */
6516  diguyInteractionMachine* create_interaction_machine(const char* name);
6517 
6518  /*l
6519  *b Description:
6520  **
6521  ** This function destroys the passed interaction machine.
6522  **
6523  ** NOTE: This function should not be called on the shared
6524  ** interaction machine returned by get_shared_interaction_machine().
6525  **
6526  *b Arguments:
6527  **
6528  *a interaction_machine - pointer to a diguyInteractionMachine
6529  *a to be destroyed
6530  */
6531  void destroy_interaction_machine(diguyInteractionMachine* interaction_machine);
6532 
6533  /*l
6534  *b Returns:
6535  **
6536  ** pointer of type diguyInteractionMachine; NULL if no interaction
6537  ** machine at the specified index
6538  **
6539  *b Arguments:
6540  **
6541  *a index - index of the interaction machine; indices start at 0
6542  */
6543  diguyInteractionMachine* get_interaction_machine_at_index(int index);
6544 
6545  /*l
6546  *b Description:
6547  **
6548  ** This function returns a pointer to the specified interaction
6549  ** machine.
6550  **
6551  *b Arguments:
6552  **
6553  *a name - name of interaction machine to be found
6554  **
6555  *b Returns:
6556  **
6557  ** pointer of type diguyInteractionMachine; NULL if not found
6558  */
6559  diguyInteractionMachine* find_interaction_machine(const char* name);
6560 
6561  /*l
6562  *b Description:
6563  **
6564  ** This function returns a pointer to the "active" interaction
6565  ** machine. Only one interaction machine can be showing and
6566  ** accepting input at a time.
6567  **
6568  *b Returns:
6569  **
6570  ** pointer of type diguyInteractionMachine; NULL if no interaction
6571  ** machine is active.
6572  */
6573  diguyInteractionMachine* get_active_interaction_machine();
6574 
6575  /*l
6576  *b Description:
6577  **
6578  ** This function returns a pointer to the shared interaction machine
6579  ** that is always available.
6580  **
6581  ** This shared interaction machine is convenient for quick
6582  ** alerts, notifications, or questions. Because it is shared,
6583  ** however, most or all of its parameters need to be set each
6584  ** time it is to be shown.
6585  **
6586  ** Do not call destroy_interaction_machine() on the returned
6587  ** object. It is owned by the scenario.
6588  **
6589  *b Returns:
6590  **
6591  ** pointer of type diguyInteractionMachine; should never be NULL
6592  */
6593  diguyInteractionMachine* get_shared_interaction_machine();
6594 
6595  /*l
6596  *b Description:
6597  **
6598  ** This is a convenience function for using the shared interaction
6599  ** machine to show a notification to the user. It sets parameters
6600  ** of the shared interaction machine based on the passed info and
6601  ** shows/activates the machine.
6602  **
6603  *b Arguments:
6604  **
6605  *a heading - text that will be at the top of the dialog
6606  *a info - informational text
6607  *a pause_scenario - pass 1 to pause the scenario while the
6608  *a interaction machine is active, 0 to leave
6609  *a the scenario running if it was when this
6610  *a function was called
6611  *a input_text - text that user will have to click to dismiss
6612  *a the interaction machine; something like "Ok"
6613  *a is typical
6614  *a ui_appearance - the color theme of the interaction machine
6615  **
6616  ** See the diguyInteractionMachine documentation for more information
6617  ** on what the various parameters mean.
6618  **
6619  *b Returns:
6620  **
6621  ** 0 on success, -1 on failure
6622  **
6623  *b Lua Example:
6624  **
6625  *e this_scenario:show_notification_with_shared_interaction_machine(
6626  *e "WARNING!",
6627  *e "Moving any closer to the harmful gas is not advised.",
6628  *e 0,
6629  *e "Ok",
6630  *e diguyInteractionMachine_UI_APPEARANCE_NOTIFICATION);
6631  **
6632  */
6633  int show_notification_with_shared_interaction_machine(const char* heading,
6634  const char* info,
6635  int pause_scenario = 0,
6636  const char* input_text = NULL,
6637  int ui_appearance = diguyInteractionMachine::UI_APPEARANCE_NOTIFICATION);
6638 
6639 
6640 /*****************************************************************************/
6650  /*l
6651  *b Description:
6652  **
6653  ** This function returns a pointer to the I-Guy controller object
6654  ** of the scenario.
6655  **
6656  *b Returns:
6657  **
6658  ** pointer of type diguyIGuyController; should never be NULL
6659  */
6660  diguyIGuyController* get_iguy_controller();
6661 
6662 
6663 /*****************************************************************************/
6673  /*l
6674  *b Description:
6675  **
6676  ** This function finds the diguyViewLabel with the given name or
6677  ** creates it if it doesn't exist.
6678  **
6679  *b Arguments:
6680  **
6681  *a name - name of the diguyViewLabel to find or create
6682  **
6683  *b Returns:
6684  **
6685  ** pointer of type diguyViewLabel; should never be NULL
6686  */
6687  diguyViewLabel* find_or_create_label(const char* name);
6688 
6689  /*l
6690  *b Description:
6691  **
6692  ** This function returns a pointer to the specified diguyViewLabel.
6693  **
6694  *b Arguments:
6695  **
6696  *a name - name of diguyViewLabel to be found
6697  **
6698  *b Returns:
6699  **
6700  ** pointer of type diguyViewLabel; NULL if not found
6701  */
6702  diguyViewLabel* find_label(const char* name);
6703 
6704  /*l
6705  *b Description:
6706  **
6707  ** This function destroys the passed in diguyViewLabel.
6708  **
6709  *b Arguments:
6710  **
6711  *a label - pointer to a diguyViewLabel
6712  **
6713  *b Returns:
6714  **
6715  ** 0 on success, -1 on failure
6716  */
6717  int destroy_label(diguyViewLabel* label);
6718 
6719  /*l
6720  *b Returns:
6721  **
6722  ** The number of diguyViewLabel objects in the scenario.
6723  */
6724  int get_num_labels();
6725 
6726  /*l
6727  *b Returns:
6728  **
6729  ** The diguyViewLabel at the given index.
6730  **
6731  *b Arguments:
6732  **
6733  *a index - index of the diguyViewLabel; indices start at 0
6734  */
6735  diguyViewLabel* get_label_at_index(int index);
6736 
6737  /*l
6738  *b Description:
6739  **
6740  ** This function removes all diguyViewLabels in the scenario.
6741  */
6742  void reset_labels();
6743 
6744  /*l
6745  *b Description:
6746  **
6747  ** This function moves the specified diguyViewLabel to the front of
6748  ** the drawing list. This is sometimes necessary if labels overlap.
6749  **
6750  *b Arguments:
6751  **
6752  *a label - pointer to diguyViewLabel to move
6753  */
6754  void send_label_to_front(diguyViewLabel* label);
6755 
6756  /*l
6757  *b Description:
6758  **
6759  ** This function moves the specified diguyViewLabel to the back of
6760  ** the drawing list. This is sometimes necessary if labels overlap.
6761  **
6762  *b Arguments:
6763  **
6764  *a label - pointer to diguyViewLabel to move
6765  */
6766  void send_label_to_back(diguyViewLabel* label);
6767 
6768  /*l
6769  *b Description:
6770  **
6771  ** Functions that allow the built-in OGL renderer to draw labels on screen for
6772  ** debugging use, update_character_labels must be called first.
6773  **
6774  *e scenario->update_character_labels();
6775  *e scenario->draw_character_labels();
6776  **
6777  *b Returns:
6778  **
6779  ** -1 if not possible to draw labels
6780  */
6781  int draw_character_labels();
6782 
6784  void update_character_labels();
6785 
6786 /*****************************************************************************/
6796  /*l
6797  *b Description:
6798  **
6799  ** This function finds the diguyViewButtonPanel with the given name or
6800  ** creates it if it doesn't exist.
6801  **
6802  *b Arguments:
6803  **
6804  *a name - name of the diguyViewButtonPanel to find or create
6805  **
6806  *b Returns:
6807  **
6808  ** pointer of type diguyViewButtonPanel; should never be NULL
6809  */
6810  diguyViewButtonPanel* find_or_create_panel(const char* name,
6811  int horizontal = 0,
6812  int title = 1);
6813 
6814  /*l
6815  *b Description:
6816  **
6817  ** This function returns a pointer to the specified
6818  ** diguyViewButtonPanel.
6819  **
6820  *b Arguments:
6821  **
6822  *a name - name of diguyViewButtonPanel to be found
6823  **
6824  *b Returns:
6825  **
6826  ** pointer of type diguyViewButtonPanel; NULL if not found
6827  */
6828  diguyViewButtonPanel* find_panel(const char* name);
6829 
6830  /*l
6831  *b Description:
6832  **
6833  ** This function destroys the passed in diguyViewButtonPanel.
6834  **
6835  *b Arguments:
6836  **
6837  *a panel - pointer to a diguyViewButtonPanel
6838  **
6839  *b Returns:
6840  **
6841  ** 0 on success, -1 on failure
6842  */
6843  int destroy_panel(diguyViewButtonPanel* panel);
6844 
6845  /*l
6846  *b Returns:
6847  **
6848  ** The number of diguyViewButtonPanel objects in the scenario.
6849  */
6850  int get_num_panels();
6851 
6852  /*l
6853  *b Returns:
6854  **
6855  ** The diguyViewButtonPanel at the given index.
6856  **
6857  *b Arguments:
6858  **
6859  *a index - index of the diguyViewButtonPanel; indices start at 0
6860  */
6861  diguyViewButtonPanel* get_panel_at_index(int index);
6862 
6863 
6864 /*****************************************************************************/
6877  /*l
6878  *b Description:
6879  **
6880  ** This function returns the number of AI minds that are available to
6881  ** AI agent characters.
6882  **
6883  *b Returns:
6884  **
6885  ** number of available minds
6886  */
6887  int get_num_minds();
6888 
6889  /*l
6890  *b Returns:
6891  **
6892  ** name of the AI mind at the specified index
6893  */
6894  const char* get_mind_name_at_index(int index);
6895 
6896  /*l
6897  *b Description:
6898  **
6899  ** This function tests if a diguyCharacter pointer is a valid pointer.
6900  ** This is done by comparing the passed address to those of all
6901  ** characters in the scenario. The function is not exceedingly fast
6902  ** but can be useful when building AI that functions in a networked
6903  ** environment.
6904  **
6905  *b Returns:
6906  **
6907  ** 0 if invalid, 1 if valid
6908  */
6909  int is_valid_character_pointer(diguyCharacter* character);
6910 
6911  /*l
6912  *b Description:
6913  **
6914  ** This function tests if a diguyCharacterGroup pointer is a valid
6915  ** pointer. This is done by comparing the passed address to those of
6916  ** all groups in the scenario. The function is not exceedingly fast
6917  ** but can be useful when building AI that functions in a networked
6918  ** environment.
6919  **
6920  *b Returns:
6921  **
6922  ** 0 if invalid, 1 if valid
6923  */
6924  int is_valid_character_group_pointer(diguyCharacterGroup* character_group);
6925 
6926 /*****************************************************************************/
6942  /*l
6943  *b Description:
6944  **
6945  ** This function creates a new crowd and returns a pointer to it.
6946  **
6947  ** A Lua object is also created that has a pointer to this crowd.
6948  ** This object can be retrieved by calling find_lua_crowd(crowd_name)
6949  ** or find_lua_crowd(diguyCrowd* pointer) in lua.
6950  **
6951  *b Arguments:
6952  **
6953  *a name - name of crowd to be created
6954  *a make_companion_of_all - pass 1 to make this crowd a companion
6955  *a of all existing crowds
6956  **
6957  *b Returns:
6958  **
6959  ** pointer of type diguyCrowd
6960  */
6961  diguyCrowd* create_crowd(const char* name,
6962  int make_companion_of_all = 1);
6963 
6964  /*l
6965  *b Description:
6966  **
6967  ** This function destroys a crowd. It can also optionally destroy the
6968  ** characters that are crowd members, and the path shape that is
6969  ** associated with the crowd.
6970  **
6971  *b Arguments:
6972  **
6973  *a crowd - pointer to a diguyCrowd
6974  *a also_destroy_crowd_members - pass 1 to also destroy crowd member
6975  *a characters
6976  *a also_destroy_path_shapes - pass 1 to also destroy crowd-
6977  *a associated path shapes
6978  *a delay_destruction - pass 1 to wait till the next update
6979  *a call to destroy the crowd; can avoid
6980  *a crashes when AI's receive destruction
6981  *a messages
6982  **
6983  *b Returns:
6984  **
6985  ** 0 on success, -1 on failure
6986  */
6987  int destroy_crowd(diguyCrowd* crowd,
6988  int also_destroy_crowd_members = 0,
6989  int also_destroy_path_shapes = 0,
6990  int delay_destruction = 0);
6991 
6992  /*l
6993  *b Returns:
6994  **
6995  ** the number of crowds in the scenario
6996  */
6997  int get_num_crowds();
6998 
6999  /*l
7000  *b Returns:
7001  **
7002  ** pointer of type diguyCrowd; NULL if no crowd at the specified index
7003  **
7004  *b Arguments:
7005  **
7006  *a index - index of the crowd; indices start at 0
7007  */
7008  diguyCrowd* get_crowd_at_index(int index);
7009 
7010  /*l
7011  *b Returns:
7012  **
7013  ** A unique name based on base_name, e.g. "my_crowd7" from "my_crowd".
7014  **
7015  *b Arguments:
7016  **
7017  *a base_name - base string from which to build a unique name
7018  */
7019  const char* get_unique_crowd_name(const char* base_name);
7020 
7021  /*l
7022  *b Description:
7023  **
7024  ** This function returns a pointer to the specified crowd.
7025  **
7026  *b Arguments:
7027  **
7028  *a name - name of crowd to be found
7029  **
7030  *b Returns:
7031  **
7032  ** pointer of type diguyCrowd; NULL if not found
7033  */
7034  diguyCrowd* find_crowd(const char* crowd_name);
7035 
7036  /*l
7037  *b Description:
7038  **
7039  ** This function returns a pointer to the crowd with the given
7040  ** name. A new crowd with the given name will be created if
7041  ** it doesn't already exist.
7042  **
7043  *b Arguments:
7044  **
7045  *a name - name of the crowd to find or create
7046  *a make_companion_of_all - pass 1 to make this crowd a companion
7047  *a of all existing crowds
7048  **
7049  *b Returns:
7050  **
7051  ** pointer of type diguyCrowd; should never be NULL
7052  */
7053  diguyCrowd* find_or_create_crowd(const char* crowd_name,
7054  int make_companion_of_all = 1);
7055 
7056  /*l
7057  *b Description:
7058  **
7059  ** This function sets whether crowds should be created for
7060  ** incoming network entities.
7061  **
7062  *b Arguments:
7063  **
7064  *a do_create - pass 1 to create network crowds; 0 to not
7065  */
7066  void set_create_network_crowds(int do_create);
7067 
7068  /*l
7069  *b Returns:
7070  **
7071  *a 1 if network crowds will be created; 0 if not
7072  **
7073  */
7074  int get_create_network_crowds();
7075 
7076 
7077 /*****************************************************************************/
7092  /*l
7093  *b Description:
7094  **
7095  ** This function creates a new crowd profile and returns a
7096  ** pointer to it.
7097  **
7098  *b Arguments:
7099  **
7100  *a name - name of crowd profile to be created
7101  **
7102  *b Returns:
7103  **
7104  ** pointer of type diguyCrowdProfile
7105  */
7106  diguyCrowdProfile* create_crowd_profile(const char* name);
7107 
7108  /*l
7109  *b Description:
7110  **
7111  ** This function destroys a crowd profile.
7112  **
7113  *b Arguments:
7114  **
7115  *a crowd_profile - pointer to a diguyCrowdProfile
7116  **
7117  *b Returns:
7118  **
7119  ** 0 on success, -1 on failure
7120  */
7121  int destroy_crowd_profile(diguyCrowdProfile* crowd_profile);
7122 
7123  /*l
7124  *b Returns:
7125  **
7126  ** The number of crowd profiles in the scenario.
7127  */
7128  int get_num_crowd_profiles();
7129 
7130  /*l
7131  *b Returns:
7132  **
7133  ** pointer of type diguyCrowdProfile; NULL if no crowd profile
7134  ** at the specified index
7135  **
7136  *b Arguments:
7137  **
7138  *a index - index of the crowd profile; indices start at 0
7139  */
7140  diguyCrowdProfile* get_crowd_profile_at_index(int index);
7141 
7142  /*l
7143  *b Description:
7144  **
7145  ** This function returns a pointer to the specified crowd profile.
7146  **
7147  *b Arguments:
7148  **
7149  *a name - name of crowd profile to be found
7150  **
7151  *b Returns:
7152  **
7153  ** pointer of type diguyCrowdProfile; NULL if not found
7154  */
7155  diguyCrowdProfile* find_crowd_profile(const char* name);
7156 
7157 
7158 /*****************************************************************************/
7168  /*l
7169  *b Returns:
7170  **
7171  ** pointer of type diguyLoadManager; this scenario's character
7172  ** load manager
7173  */
7174  diguyLoadManager* get_character_load_manager();
7175 
7176 
7177 /*****************************************************************************/
7187  /*l
7188  *b Description:
7189  **
7190  ** This function forces the octtree to rebuild if it's out of date.
7191  */
7192  int force_octtree_generation();
7193 
7194  /*l
7195  *b Description:
7196  **
7197  ** Documentation Pending
7198  */
7199  void add_character_to_octtree(diguyCharacter* character,
7200  int use_bounding_box_only = 0);
7201 
7202  /*l
7203  *b Description:
7204  **
7205  ** Documentation Pending
7206  */
7207  void remove_character_from_octtree(diguyCharacter* character);
7208 
7209  /*l
7210  *b Description:
7211  **
7212  ** Documentation Pending
7213  */
7214  int preload_octtree(const char* character_type, const char* appearance);
7215 
7216  /*l
7217  *b Description:
7218  **
7219  ** This function uses the octtree to check if the path between x1,
7220  ** y1, z1 and x2, y2, z2 has any static obstructions.
7221  **
7222  *b Returns:
7223  **
7224  ** 1 if the path is clear, 0 if static obstructions are present.
7225  */
7226  int check_visibility(float x1, float y1, float z1,
7227  float x2, float y2, float z2);
7228 
7229 
7230 /*****************************************************************************/
7240 #ifdef CPLUSPLUS_ONLY
7241 
7242  /*l
7243  *b Description:
7244  **
7245  ** This function sets a default altitude function that will be added
7246  ** to all characters that are subsequently created. It can be overridden
7247  ** on a per-character basis by a call to diguyCharacter::set_altitude_function().
7248  ** See that function for details.
7249  **
7250  *b Callable From:
7251  **
7252  *- - C++
7253  */
7254  int set_default_character_altitude_function(diguyAltitudeFunction* altitude_function);
7255 
7256  /*l
7257  *b Description:
7258  **
7259  ** This function sets a generic altitude function for the scenario
7260  ** that is used for local path clamping and other operations that
7261  ** require the altitude at specific x, y coordinates to be calculated.
7262  ** This is for the benefit of SDK users who have their own representation
7263  ** of terrain and structures.
7264  **
7265  ** diguyScenario::ground_clamp() can be told to use the registered
7266  ** function, but this is optional.
7267  **
7268  ** DI-Guy Scenario has a default altitude function; replacing the
7269  ** default function is not recommended.
7270  **
7271  *b Callable From:
7272  **
7273  *- - C++
7274  */
7275  void set_altitude_function(diguyScenarioAltitudeFunction* altitude_function);
7276 
7277  /*l
7278  *b Returns:
7279  **
7280  ** the altitude function for the scenario as set by
7281  ** set_altitude_function()
7282  **
7283  *b Callable From:
7284  **
7285  *- - C++
7286  */
7287  diguyScenarioAltitudeFunction* get_altitude_function();
7288 
7289 #endif
7290 
7291  /*
7292  * Documentation Pending
7293  */
7294  void set_altitude_max_climb(float altitude_max_climb);
7295 
7296  /*
7297  * Documentation Pending
7298  */
7299  float get_altitude_max_climb();
7300 
7301  /*
7302  * Documentation Pending
7303  */
7304  void set_altitude_max_drop(float altitude_max_drop);
7305 
7306  /*
7307  * Documentation Pending
7308  */
7309  float get_altitude_max_drop();
7310 
7311 
7312 /*****************************************************************************/
7322  /*l
7323  *b Description:
7324  **
7325  ** Sets the default intersection function. This function will be used to determine
7326  ** whether there is an intersection between a specified ray and the world.
7327  */
7328  static void set_default_intersection_function(diguyScenarioIntersectionFunction* intersection_function);
7329  void set_intersection_function(diguyScenarioIntersectionFunction* intersection_function);
7330 
7331  /*l
7332  *b Description:
7333  **
7334  ** Creates a detonation using the specified munition name. If the
7335  ** DI-Guy networking module is enabled the detonation is broadcast
7336  ** over the network.
7337  **
7338  *b Arguments:
7339  **
7340  *a munition_name - name of the munition to detonate; this will
7341  *a potentially trigger special effects depending
7342  *a on the munition
7343  *a x, y, z - location of the detonation
7344  *a attacker_name - this MUST be specified if the detonation is being
7345  *a broadcast over the network
7346  *a radius_override - defaults to the data in the munition config file
7347  *a broadcast_on_network - pass 0 to not broadcast detonation on DIS
7348  *a network
7349  **
7350  ** Note: Overriding the detonation radius will NOT work on broadcast
7351  ** detonations since the override value is not transmitted.
7352  */
7353  int trigger_detonation(const char* munition_name,
7354  float x, float y, float z,
7355  const char* attacker_name = NULL,
7356  float radius_override = -1.0f,
7357  int broadcast_on_network = 1);
7358 
7359  /*l
7360  *b Description:
7361  **
7362  ** This function checks for intersection against characters in the
7363  ** specified view.
7364  **
7365  ** To check for intersections against both characters and scene
7366  ** objects, call get_intersection_at_screen_coords().
7367  **
7368  ** The returned diguyImpact pointer is owned by the scenario and
7369  ** should not be deleted. It will remain valid until the next call
7370  ** to any one of the following functions:
7371  **
7372  *- - find_character_at_screen_coords()
7373  *- - get_impact_at_screen_coords()
7374  *- - get_intersection_at_screen_coords()
7375  **
7376  *i This function should only be called from a DI-Guy Scenario Plugin.
7377  **
7378  *b Arguments:
7379  **
7380  *a view - view to check
7381  *a sx, sy - view coordinates to check
7382  **
7383  *b Returns:
7384  **
7385  ** pointer of type diguyImpact; NULL if no character intersected
7386  **
7387  *b Callable From:
7388  **
7389  *- - DI-Guy Scenario Plugin
7390  */
7391  diguyImpact* find_character_at_screen_coords(diguyView* view,
7392  float sx,
7393  float sy);
7394 
7395  /*l
7396  *b Description:
7397  **
7398  ** This function creates an impact object based on the sx and sy in
7399  ** the specified view. This function will trigger an impact callback
7400  ** on individuals who are touched, (it will not however kill
7401  ** characters who don't have impact callbacks.
7402  **
7403  ** The returned diguyImpact pointer is owned by the scenario and
7404  ** should not be deleted. It will remain valid until the next call
7405  ** to any one of the following functions:
7406  **
7407  *- - find_character_at_screen_coords()
7408  *- - get_impact_at_screen_coords()
7409  *- - get_intersection_at_screen_coords()
7410  **
7411  *i This function should only be called from a DI-Guy Scenario Plugin.
7412  **
7413  *b Arguments:
7414  **
7415  *a view - view to check
7416  *a sx, sy - view coordinates to check
7417  *a use_octtree - use the octtree; will not test against all
7418  *a characters unless they are explicitly added,
7419  *a but much faster
7420  **
7421  *b Returns:
7422  **
7423  ** pointer of type diguyImpact;
7424  **
7425  *b Callable From:
7426  **
7427  *- - DI-Guy Scenario Plugin
7428  */
7429  diguyImpact* get_impact_at_screen_coords(diguyView* view,
7430  float sx,
7431  float sy,
7432  int use_octtree = 0);
7433 
7434  /*l
7435  *b Description:
7436  **
7437  ** This function checks for intersection against the world *and*
7438  ** characters in the specified view. Unlike the function
7439  ** get_impact_at_screen_coords(), this function doesn't trigger
7440  ** callbacks; instead, it just fills out the impact info.
7441  **
7442  ** The returned diguyImpact pointer is owned by the scenario and
7443  ** should not be deleted. It will remain valid until the next call to
7444  ** any one of the following functions:
7445  **
7446  *- - find_character_at_screen_coords()
7447  *- - get_impact_at_screen_coords()
7448  *- - get_intersection_at_screen_coords()
7449  **
7450  *i This function should only be called from a DI-Guy Scenario Plugin.
7451  **
7452  *b Arguments:
7453  **
7454  *a view - view to check
7455  *a sx, sy - view coordinates to check
7456  *a use_octtree - use the octtree; will not test against all
7457  *a characters unless they are explicitly added,
7458  *a but much faster
7459  **
7460  *b Returns:
7461  **
7462  ** diguyImpact with the xyz location of the intersection; NULL if
7463  ** there was nothing to intersect there
7464  **
7465  *b Callable From:
7466  **
7467  *- - DI-Guy Scenario Plugin
7468  */
7469  diguyImpact* get_intersection_at_screen_coords(diguyView* view,
7470  float sx,
7471  float sy,
7472  int use_octtree = 0);
7473 
7474  /*l
7475  *b Description:
7476  **
7477  ** This function checks for intersection against the world and returns
7478  ** basic collision results.
7479  **
7480  ** This function will only return valid results in environments where
7481  ** the DI-Guy geometry octtree is available; currently that is when
7482  ** using OpenGL and the DI-Guy flight geometry loader. DI-Guy
7483  ** Scenario is such a case.
7484  **
7485  *b Arguments:
7486  **
7487  *a origin_x, origin_y, origin_z - starting location of the ray trace
7488  *a dir_x, dir_y, dir_z - direction of ray trace (should be normalized)
7489  *a max_distance_to_test - max distance ray will travel;
7490  *a -1.0 will test an infinitely long ray
7491  *a intersection_x, _y, and _z - world location of intersection
7492  *a normal_x, normal_y, normal_z - normal of intersection surface
7493  **
7494  ** Smaller values for max_distance_to_test will result in better
7495  ** performance.
7496  **
7497  ** The location of the intersection point is returned in the
7498  ** intersection x, y, and z pointers.
7499  **
7500  ** The normal of the surface intersected is returned in the normal
7501  ** x, y, and z pointers.
7502  **
7503  *b Returns:
7504  **
7505  ** 1 if intersection occurred, 0 if not.
7506  */
7507  int intersect_static_geometry(
7508  float origin_x, float origin_y, float origin_z,
7509  float dir_x, float dir_y, float dir_z,
7510  float max_distance_to_test,
7511  float* intersection_x, float* intersection_y, float* intersection_z,
7512  float* normal_x = NULL, float* normal_y = NULL, float* normal_z = NULL,
7513  int use_callback = 1);
7514 
7515  /*l
7516  *b Description:
7517  **
7518  ** This function returns the z height, or altitude, of the uppermost
7519  ** piece of terrain under the passed x, y, z point.
7520  **
7521  ** Two methods can be used to determine the altitude: a custom scenario
7522  ** altitude function set by the user, or by testing against DI-Guy's
7523  ** internal octtree calculated from terrain geometry.
7524  **
7525  ** See set_altitude_function() for information on the scenario
7526  ** altitude function. DI-Guy Scenario has its own version of this function,
7527  ** which defaults to using the octtree when it's available, and falls back on
7528  ** using a screen render and Z-buffer check when it's not.
7529  **
7530  ** Note that the octtree is not always available. In general, it is
7531  ** available only in DI-Guy Scenario, or when the built-in OpenGL
7532  ** renderer and DI-Guy flight geometry loader are in use. Users of the SDK
7533  ** typically have their own representations of terrain and structures.
7534  **
7535  *b Arguments:
7536  **
7537  *a x, y, z - world location to ground clamp
7538  *a valid - optional pointer to get an explicit result if anything
7539  *a was hit
7540  *a use_altitude_function - pass 1 to use scenario altitude function
7541  *a (tried first)
7542  *a use_octtree - pass 1 to use internal octtree
7543  **
7544  *b Returns:
7545  **
7546  ** new_z if ground clamp was possible, original z if not
7547  */
7548  float ground_clamp(float x, float y, float z,
7549  int* valid = NULL,
7550  int use_altitude_function = 1,
7551  int use_octtree = 0);
7552 
7553 
7554 #ifdef CPLUSPLUS_ONLY
7555 
7556  /******************************************************
7557  **
7558  *4 Impact Callback Functions:
7559  **
7560  ** Unless otherwise specified, callable from:
7561  **
7562  *- - C++
7563  *- - Script
7564  */
7565 
7566  /*l
7567  *b Description:
7568  **
7569  ** The following prototype should be used for the impact
7570  ** function:
7571  **
7572  *e int impact_func(diguyImpact* impact,
7573  *e float from_x,
7574  *e float from_y,
7575  *e float from_z,
7576  *e float to_x,
7577  *e float to_y,
7578  *e float to_z,
7579  *e diguyScenario* s);
7580  **
7581  ** When a character fires their weapon, DI-Guy calls this function
7582  ** with a pointer to the diguyImpact that must be filled out, the x,
7583  ** y, z position of the shot, and the target x, y, z.
7584  **
7585  ** The impact function should then do an intersection test and return
7586  ** 1 if a hit occurred.
7587  **
7588  ** By default the impact should have both the attacker and the
7589  ** munition type already specified. The intersection function must at
7590  ** least call diguyImpact::set_valid_impact() for the system to
7591  ** consider the impact valid. See diguyImpact for a sample function.
7592  **
7593  *b Callable From:
7594  **
7595  *- - C++
7596  */
7597  int set_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);
7598 
7599  /*l
7600  *b Description:
7601  **
7602  ** This function sets an impact function that will be added to all new
7603  ** scenarios. It can be overridden by an explicit call to
7604  ** diguyScenario::set_fire_weapon_intersection_function(). See that
7605  ** function for details.
7606  **
7607  *b Callable From:
7608  **
7609  *- - C++
7610  */
7611  static void set_default_fire_weapon_intersection_function(diguyScenarioFindImpactOnLineFunction* impact_function);
7612 
7613 #endif
7614 
7615  /*l
7616  *b Description:
7617  **
7618  ** Most DI-Guy visual objects (e.g., characters, path shapes,
7619  ** waypoints) have a unique identified, or UID. In many cases these
7620  ** UID values can be coded into 24-bit color values. This can be
7621  ** useful for implementing some types of intersection detection
7622  ** functions, in which each visual object is rendered with a different
7623  ** color.
7624  **
7625  ** This function will take the passed color values and update internal
7626  ** DI-Guy state of which objects objects have been hit.
7627  **
7628  ** It will also return an impact record containing information a
7629  ** subset of that information.
7630  **
7631  ** This can include:
7632  **
7633  *- - the hit character, if one was hit
7634  *- - the hit link and shape of the character
7635  *- - the hit scene object, if one was hit
7636  **
7637  ** Note that the returned impact pointer is owned by DI-Guy and is
7638  ** temporary. The information you need from it should be immediately
7639  ** read, and the pointer should not be stored.
7640  */
7641  diguyImpact* map_color_to_impact(char r, char g, char b);
7642 
7643  /*l
7644  *b Description:
7645  **
7646  ** When the callback with id diguyScenario::CALLBACK_ID_SCENE_OBJECT_IMPACT
7647  ** is called, this function will return the impact object containing
7648  ** information about that impact.
7649  **
7650  ** There may be multiple impacts that result from some operations.
7651  ** In this case this function should be called multiple times, until
7652  ** it returns NULL. When processing of data from each successive
7653  ** impact is done, call set_last_impact_been_processed() to queue up
7654  ** the next impact object for processing.
7655  **
7656  ** The maximum number of unprocessed impacts is finite, and set by
7657  ** the function set_max_unprocessed_impacts().
7658  **
7659  ** Note that the returned impact pointers are owned by DI-Guy and are
7660  ** temporary. The information you need from them should be
7661  ** immediately read, and the pointers should not be stored.
7662  */
7663  diguyImpact* get_last_env_impact_info();
7664 
7665  /*l
7666  *b Description:
7667  **
7668  ** Reading of data from the last impact information will be considered
7669  ** complete when this function is called.
7670  */
7671  void set_last_impact_been_processed();
7672 
7673  /*l
7674  *b Description:
7675  **
7676  ** This function will add the passed impact object to the list of
7677  ** impact objects to be processed by calls to
7678  ** get_last_env_impact_info(). An internal copy of the impact object
7679  ** is made.
7680  */
7681  void set_last_env_impact_info(const diguyImpact& impact);
7682 
7683  /*l
7684  *b Description:
7685  **
7686  ** Sets the maximum number of unprocessed impacts there can be.
7687  **
7688  ** The unprocessed impact array is a first-in-first-out queue. If an
7689  ** impact occurs that pushes the number of unprocessed impacts past
7690  ** this maximum number, earlier impacts will be dropped from the
7691  ** array.
7692  **
7693  ** The initial value is 10.
7694  */
7695  void set_max_unprocessed_impacts(int max_unprocessed_impacts);
7696 
7697 
7698 #ifdef CPLUSPLUS_ONLY
7699 
7700 
7701 /*****************************************************************************/
7721  /*l
7722  *b Description:
7723  **
7724  ** This function sets a default point line of sight function that
7725  ** will be added to all new characters. It can be overridden by an
7726  ** explicit call to diguyCharacter::set_point_los_function(). See
7727  ** that function for details.
7728  **
7729  *b Callable From:
7730  **
7731  *- - C++
7732  */
7733  int set_default_point_los_function(diguyPointLOSFunction* point_los_function);
7734 
7735  /*l
7736  *b Description:
7737  **
7738  ** This function sets a default character line of sight function that
7739  ** will be added to all new characters. It can be overridden by an
7740  ** explicit call to diguyCharacter::set_character_los_function().
7741  ** See that function for details.
7742  **
7743  *b Callable From:
7744  **
7745  *- - C++
7746  */
7747  int set_default_character_los_function(diguyCharacterLOSFunction* character_los_function);
7748 
7749  /*l
7750  *b Description:
7751  **
7752  ** This function sets a default feeler function that will be added
7753  ** to all new DI-Guy AI agents. It can be overridden by an explicit
7754  ** call to diguyCharacter::agent_set_feeler_function().
7755  **
7756  ** See the "User-Defined Feelers" section in diguyCharacter.h for
7757  ** more information.
7758  **
7759  *b Arguments:
7760  **
7761  *a feeler_function - pointer to user-defined feeler function
7762  **
7763  *b Returns:
7764  **
7765  ** 0 on success, -1 on failure
7766  **
7767  *b Callable From:
7768  **
7769  *- - C++
7770  */
7771  int set_default_agent_feeler_function(diguyFeelerFunction* feeler_function);
7772 
7773 #endif
7774 
7775  /*l
7776  *b Description:
7777  **
7778  ** Experimental intersection-detection function.
7779  **
7780  *b Arguments:
7781  **
7782  *a origin_x,origin_y,origin_z - starting point
7783  *a dir_x,dir_y,dir_z - direction vector
7784  *a max_distance_to_test - distance to test to
7785  *a use_callback - 1 to use
7786  **
7787  *b Returns:
7788  **
7789  ** diguyIntersectionResult structure
7790  */
7791  diguyIntersectionResult exp_intersect_geometry(
7792  float origin_x, float origin_y, float origin_z,
7793  float dir_x, float dir_y, float dir_z,
7794  float max_distance_to_test,
7795  int use_callback = 1);
7796 
7797 /*****************************************************************************/
7807  /*l
7808  *b Description:
7809  **
7810  ** This function returns a pointer to the region with the given
7811  ** name. A new region with the given name will be created if
7812  ** it doesn't already exist.
7813  **
7814  *b Arguments:
7815  **
7816  *a name - name of the region to find or create
7817  **
7818  *b Returns:
7819  **
7820  ** pointer of type diguyRegion; should never be NULL
7821  */
7822  diguyRegion* find_or_create_region(const char* name);
7823 
7824  /*l
7825  *b Description:
7826  **
7827  ** This function returns a pointer to the specified region.
7828  **
7829  *b Arguments:
7830  **
7831  *a name - name of region to be found
7832  **
7833  *b Returns:
7834  **
7835  ** pointer of type diguyRegion; NULL if not found
7836  */
7837  diguyRegion* find_region(const char* name);
7838 
7839  /*l
7840  *b Description:
7841  **
7842  ** This function creates a new diguyRegion and returns a pointer to
7843  ** it.
7844  **
7845  *b Arguments:
7846  **
7847  *a name - name of the new region object
7848  **
7849  *b Returns:
7850  **
7851  ** pointer of type diguyRegion
7852  */
7853  diguyRegion* create_region(const char* name);
7854 
7855  /*l
7856  *b Description:
7857  **
7858  ** This function destroys the passed region.
7859  **
7860  *b Arguments:
7861  **
7862  *a region - region to destroy
7863  */
7864  void destroy_region(diguyRegion* region);
7865 
7866  /*l
7867  *b Returns:
7868  **
7869  ** number of regions in the scenario
7870  */
7871  int get_num_regions();
7872 
7873  /*l
7874  *b Returns:
7875  **
7876  ** pointer of type diguyRegion; NULL if no region at the
7877  ** specified index
7878  **
7879  *b Arguments:
7880  **
7881  *a index - index of the region; indices start at 0
7882  */
7883  diguyRegion* get_region_at_index(int index);
7884 
7885  /*l
7886  *b Description:
7887  **
7888  ** The scenario will attempt to create a navigation path on the
7889  ** via_region. An A* path planning algorithm is used to find the
7890  ** path. See also diguyCharacter::agent_move_to_point() and
7891  ** diguyCharacter::agent_move_to_point_via_subregions().
7892  **
7893  *b Arguments:
7894  **
7895  *a x1, y1, z1 - start location
7896  *a x2, y2, z2 - end location
7897  *a via_region - name of the region to run A* on
7898  *a path_shape - path shape that stores the created path
7899  *a preferred_subregions_mask - diguySubregionMask value of regions
7900  *a preferred for travel
7901  *a cost_bias_for_preferred_regions - how much cheaper it will be
7902  *a to cross spaces that are part of desired subregion;
7903  *a should be < 1.0
7904  *a cost_bias_for_neutral_regions - how much more expensive it will be
7905  *a to cross spaces that are not part of desired subregion; see
7906  *a below for more information
7907  *a repulsed_regions_mask - diguySubregionMask value of regions *not*
7908  *a preferred for travel
7909  *a cost_bias_for_repulsed_regions - how much more expensive it will be
7910  *a to cross regions that are marked as repulsive; pass
7911  *a DIGUY_DEFAULT_FLOAT to avoid completely
7912  **
7913  ** Pass DIGUY_DEFAULT_FLOAT for cost_bias_for_neutral_regions and
7914  ** cost_bias_for_repulsed_regions to specify that they should be
7915  ** avoided completely.
7916  **
7917  ** The preferred_subregions_mask and repulsed_regions_mask use
7918  ** DI-Guy subregion mask values combined together. For example,
7919  ** DIGUY_SUBREGION_MASK_SIDEWALK | DIGUY_SUBREGION_MASK_CROSSWALK.
7920  **
7921  ** For cost_bias_for_neutral_regions, specifying a non-zero value for
7922  ** this lowers the likelihood that searches fail on disjointed
7923  ** subregions. A value < 1 will cause the planner to run faster but
7924  ** explore fewer points, possibly missing preferred regions. Values
7925  ** greater then 1 will explore more points but will be slower.
7926  **
7927  *b Returns:
7928  **
7929  ** 0 on success, -1 on failure
7930  */
7931  int find_navigation_path(float x1, float y1, float z1,
7932  float x2, float y2, float z2,
7933  const char* via_region,
7934  diguyPathShape* path_shape,
7935  float cost_bias_for_preferred_regions = 0.25f,
7936  int preferred_subregions_mask = DIGUY_SUBREGION_MASK_NONE,
7937  float cost_bias_for_neutral_regions = 1.1f,
7938  int repulsed_regions_mask = DIGUY_SUBREGION_MASK_NONE,
7939  float cost_bias_for_repulsive_regions = 100.0f);
7940 
7941  /*l
7942  *b Description:
7943  **
7944  ** Sets an upper limit on how far a character is willing to travel as
7945  ** a multiple of the straight line distance between point A and point
7946  ** B before declaring that it can't get to a location.
7947  **
7948  ** Note that internally the straight line distance is forced to have a
7949  ** lower bound of 10 meters, so a character is always willing to
7950  ** travel a minimum of 10 * max_distance_planning_multiplier meters.
7951  **
7952  ** Defaults to -1, which means off.
7953  */
7954  void set_max_distance_planning_multiplier(float mul);
7955 
7956  /*l
7957  *b Returns:
7958  **
7959  ** float constant that's used to decide if planner should give up;
7960  ** -1 means off
7961  */
7962  float get_max_distance_planning_multiplier();
7963 
7964  /*l
7965  *b Description:
7966  **
7967  ** This function returns in seconds how much time has been spent path
7968  ** planning during the current frame. It can be used to avoid 100
7969  ** characters simultaneously hitting the path planner.
7970  **
7971  *b Returns:
7972  **
7973  ** time in seconds
7974  */
7975  float get_time_spent_path_planning_this_frame();
7976 
7977  /*l
7978  *b Description:
7979  **
7980  ** This function enables the path planner to run in a background
7981  ** thread. Note this only occurs if the
7982  ** diguyCharacter::agent_move_to_point_bg() or
7983  ** diguyCharacter::agent_move_to_point_via_subregions_bg() api
7984  ** functions are used.
7985  **
7986  ** By default the multi-threaded path planner is on.
7987  */
7988  void set_multithreaded_path_planning_enabled(int value);
7989  /*l
7990  *b Returns:
7991  **
7992  ** Returns 1 if the path planner is enabled to run in a background
7993  ** thread. By default the multi-threaded path planner is on.
7994  */
7995  int get_multithreaded_path_planning_enabled();
7996 
7997 
7998 /*****************************************************************************/
8008  /*l
8009  *b Returns:
8010  **
8011  ** number of formations in the scenario
8012  */
8013  int get_num_formations();
8014 
8015  /*l
8016  *b Returns:
8017  **
8018  ** pointer of type diguyFormation; NULL if no
8019  ** formation at the specified index
8020  **
8021  *b Arguments:
8022  **
8023  *a index - index of the formation; indices start at 0
8024  */
8025  diguyFormation* get_formation_at_index(int index);
8026 
8027  /*l
8028  *b Description:
8029  **
8030  ** This function returns a pointer to the specified formation.
8031  **
8032  *b Arguments:
8033  **
8034  *a name - name of formation to be found
8035  **
8036  *b Returns:
8037  **
8038  ** pointer of type diguyFormation; NULL if not found
8039  */
8040  diguyFormation* find_formation(const char* name);
8041 
8042  /*l
8043  *b Description:
8044  **
8045  ** This function returns a pointer to the first formation it finds of
8046  ** a given size.
8047  **
8048  *b Arguments:
8049  **
8050  *a size - size of formation to be found
8051  **
8052  *b Returns:
8053  **
8054  ** pointer of type diguyFormation; NULL if not found
8055  */
8056  diguyFormation* find_formation_of_size(int size);
8057 
8058  /*l
8059  *b Description:
8060  **
8061  ** This function creates a new formation and returns a
8062  ** pointer to it.
8063  **
8064  *b Arguments:
8065  **
8066  *a name - name of the new formation
8067  **
8068  *b Returns:
8069  **
8070  ** pointer of type diguyFormation
8071  */
8072  diguyFormation* create_formation(const char* name);
8073 
8074  /*l
8075  *b Description:
8076  **
8077  ** This function finds the formation with the given name or
8078  ** creates it if it doesn't exist.
8079  **
8080  *b Arguments:
8081  **
8082  *a name - name of the formation to find or create
8083  **
8084  *b Returns:
8085  **
8086  ** pointer of type diguyFormation; should never be NULL
8087  */
8088  diguyFormation* find_or_create_formation(const char* name);
8089 
8090  /*l
8091  *b Description:
8092  **
8093  ** This function destroys a formation.
8094  **
8095  *b Arguments:
8096  **
8097  *a formation - pointer to a diguyFormation
8098  **
8099  *b Returns:
8100  **
8101  ** 0 on success, -1 on failure
8102  */
8103  int destroy_formation(diguyFormation* formation);
8104 
8105 
8106 /*****************************************************************************/
8122  void set_draw_authoring_visuals(int visible);
8124  int get_draw_authoring_visuals();
8125 
8126  void set_action_bead_labels_visible(diguyVisibleFlag vflag);
8127  void set_aim_trajectories_visible(diguyVisibleFlag vflag);
8128  void set_author_selection_handles_visible(diguyVisibleFlag vflag);
8129  void set_bead_array_visible(diguyVisibleFlag vflag);
8130  void set_character_labels_visible(diguyVisibleFlag vflag);
8131  void set_character_visible(diguyVisibleFlag vflag);
8132  void set_crowd_behavior_visible(diguyVisibleFlag flag);
8133  void set_crowd_feelers_visible(diguyVisibleFlag flag);
8134  void set_crowd_influence_visible(diguyVisibleFlag flag);
8135  void set_crowd_regions_visible(diguyVisibleFlag flag);
8136  void set_light_array_visible(diguyVisibleFlag vflag);
8137  void set_lua_objects_visible(diguyVisibleFlag flag);
8138  void set_mesh_region_array_visible(diguyVisibleFlag vflag);
8139  void set_sensor_region_array_visible(diguyVisibleFlag vflag);
8140  void set_spath_visible(diguyVisibleFlag vflag);
8141  void set_waypoint_array_visible(diguyVisibleFlag vflag);
8142 
8143  diguyVisibleFlag get_action_bead_labels_visible();
8144  diguyVisibleFlag get_aim_trajectories_visible();
8145  diguyVisibleFlag get_author_selection_handles_visible();
8146  diguyVisibleFlag get_bead_array_visible();
8147  diguyVisibleFlag get_character_labels_visible();
8148  diguyVisibleFlag get_character_visible();
8149  diguyVisibleFlag get_crowd_behavior_visible();
8150  diguyVisibleFlag get_crowd_feelers_visible();
8151  diguyVisibleFlag get_crowd_influence_visible();
8152  diguyVisibleFlag get_crowd_regions_visible();
8153  diguyVisibleFlag get_light_array_visible();
8154  diguyVisibleFlag get_lua_objects_visible();
8155  diguyVisibleFlag get_mesh_region_array_visible();
8156  diguyVisibleFlag get_sensor_region_array_visible();
8157  diguyVisibleFlag get_spath_visible();
8158  diguyVisibleFlag get_waypoint_array_visible();
8159 
8160  void set_hide_author_selection_handles_during_play(int visible);
8161  int get_hide_author_selection_handles_during_play();
8162 
8163 
8164 /*****************************************************************************/
8174  /*l
8175  *b Returns:
8176  **
8177  ** If weapon fire will create light flashes.
8178  */
8179  int get_weapon_fire_effects_enabled();
8180 
8181  /*l
8182  *b Description:
8183  **
8184  ** Sets if weapon fire will create light flashes.
8185  */
8186  int set_weapon_fire_effects_enabled(int enabled);
8187 
8188  /*l
8189  *b Returns:
8190  **
8191  ** The number of light flashes that are currently active
8192  */
8193  int get_num_active_fire_effects();
8194 
8195  /*l
8196  *b Description:
8197  **
8198  ** This function gets the data needed for producing a weapon flash
8199  ** light source in the world. See diguyOglGraphicsShaderProgram::update_light_uniforms()
8200  ** for an example of its use. In the default OpenGL renderer the
8201  ** convenience function diguy_ogl_apply_active_lights() does this work
8202  ** for you.
8203  **/
8204  int get_weapon_fire_effect_data(int index, float * radius,
8205  float * position_x, float * position_y, float * position_z,
8206  float * color_r, float * color_g, float * color_b,
8207  float * falloff_r,
8208  float * falloff_rsq);
8209 
8211  int get_num_active_lights();
8212 
8214  int sort_active_lights();
8215 
8216  /*l
8217  *b Description:
8218  **
8219  ** This function gets the data needed for producing a weapon flash
8220  ** light source in the world. See diguyOglGraphicsShaderProgram::update_light_uniforms()
8221  ** for an example of its use. In the default OpenGL renderer the
8222  ** convenience function diguy_ogl_apply_active_lights() does this work
8223  ** for you.
8224  **/
8225  int get_active_light_data(int index, diguyLightRenderDesc * light_desc);
8226 
8227 /*****************************************************************************/
8242  /*l
8243  *b Description:
8244  **
8245  ** Sets the current selected character in scenario
8246  **
8247  *b Returns:
8248  **
8249  ** 0 on success, -1 on failure
8250  **/
8251  int set_current_character(diguyCharacter* current_character);
8252  /*l
8253  *b Returns:
8254  **
8255  ** The current selected character in scenario
8256  **/
8257  diguyCharacter* get_current_character();
8258 
8259  /*l
8260  *b Description:
8261  **
8262  ** Sets the current selected crowd in scenario
8263  **
8264  *b Returns:
8265  **
8266  ** 0 on success, -1 on failure
8267  **/
8268  int set_current_crowd(diguyCrowd* current_crowd);
8269  /*l
8270  *b Returns:
8271  **
8272  ** The current selected crowd in scenario
8273  **/
8274  diguyCrowd* get_current_crowd();
8275 
8276  /*l
8277  *b Description:
8278  **
8279  ** Sets the active crowd profile, which determines the attributes
8280  ** of subsequently-created crowds. See diguyCrowdProfile.
8281  **
8282  *b Returns:
8283  **
8284  ** 0 on success, -1 on failure
8285  **/
8286  int set_current_crowd_profile(diguyCrowdProfile* current_profile);
8287  /*l
8288  *b Description:
8289  **
8290  ** Sets the active crowd profile by name.
8291  **
8292  *b Returns:
8293  **
8294  ** 0 on success, -1 on failure
8295  **/
8296  int set_current_crowd_profile_by_name(const char* crowd_profile_name);
8297  /*l
8298  *b Returns:
8299  **
8300  ** Active crowd profile
8301  **/
8302  diguyCrowdProfile* get_current_crowd_profile();
8303 
8304  /*l
8305  *b Description:
8306  **
8307  ** Sets the current region. See diguyRegion.
8308  **
8309  *b Returns:
8310  **
8311  ** 0 on success, -1 on failure
8312  **/
8313  int set_current_region(diguyRegion* current_region);
8314  /*l
8315  *b Returns:
8316  **
8317  ** Current region.
8318  **/
8319  diguyRegion* get_current_region();
8320 
8321 
8322 /*****************************************************************************/
8327  /*l
8328  *b Description:
8329  **
8330  ** This function enables or disables the particle module.
8331  ** By default the particle module is enabled.
8332  */
8333  void set_particle_module_disabled(int disable_particle_module);
8334 
8335  /*l
8336  *b Description:
8337  **
8338  ** This function creates a particle system with type description_name
8339  ** at x, y, z. If duration is specified the system will automatically
8340  ** stop emitting after that amount of time.
8341  **
8342  *b Arguments:
8343  **
8344  *a description_name - name of particle description to create
8345  *a x, y, z - the world space position of the system
8346  *a record_transient_event - pass 1 to have this particle system
8347  *a play in history playback
8348  *a duration - how long the emitter should emit; if -1 is
8349  *a specified then the description must have a
8350  *a lifetime specified
8351  */
8352  int create_particle_system(const char* description_name,
8353  float x, float y, float z,
8354  int record_transient_event = 1,
8355  float duration = -1.0f);
8356 
8357  /*l
8358  *b Description:
8359  **
8360  ** Similar to create_particle_system(), but allows orientation to be set.
8361  **
8362  *b Arguments:
8363  **
8364  *a rz, rx, ry - orientation axes
8365  **
8366  ** (See create_particle_system() for other parameters)
8367  */
8368  int create_particle_system_with_orientation(const char* description_name,
8369  float x, float y, float z,
8370  float rz, float rx, float ry,
8371  int record_transient_event = 1,
8372  float duration = -1.0f);
8373 
8374  /*l
8375  *b Returns:
8376  **
8377  ** 1 if the particle description named description_name exists,
8378  ** else 0
8379  */
8380  int has_particle_description(const char* description_name);
8381 
8382  /*l
8383  *b Description:
8384  **
8385  ** Set wind velocity vector for particle system
8386  */
8387  void set_global_wind(float x, float y, float z);
8388 
8389 
8390 /*****************************************************************************/
8396 // These should probably be C++ only. Not sure how much they make sense for
8397 // exposure to the scripting languages, unless you want perl to call lua
8398 // via C++.
8399 
8400  /*l
8401  *b Returns:
8402  **
8403  ** string representation of lua_object.field_name
8404  **
8405  ** Note that the returned string pointer will not remain valid, so
8406  ** the returned string should be copied.
8407  **
8408  *b Arguments:
8409  **
8410  *a lua_object - a global lua object
8411  *a field_name - name of the field; field_name can include ".",
8412  *a allowing retrieval of fields in complex data
8413  *a structures
8414  **
8415  *b Callable From:
8416  **
8417  *- - C++
8418  **/
8419  const char* lua_get_object_field_as_string(const char* lua_object,
8420  const char* field_name);
8421 
8422  /*l
8423  **
8424  *b Description:
8425  **
8426  ** Runs a member function of a lua object.
8427  **
8428  *b Arguments:
8429  **
8430  *a lua_object - a global lua object
8431  *a function_name - name of the function to call
8432  *a argument - optional string argument
8433  *a has_return_string - if set to 1 function will pop the top value of
8434  *a the lua stack and return it as a string
8435  **
8436  *b Returns:
8437  **
8438  ** NULL or string representation of
8439  ** lua_object:function_name(argument).
8440  **
8441  ** The returned string should be copied if it needs to be used later.
8442  **
8443  *b Callable From:
8444  **
8445  *- - C++
8446  **/
8447  const char* lua_evaluate_object_function(const char* lua_object,
8448  const char* function_name,
8449  const char* argument = NULL,
8450  int has_return_string = 0);
8451 
8452  /*l
8453  *b Description:
8454  **
8455  ** A two argument version of lua_evaluate_object_function().
8456  **
8457  *b Callable From:
8458  **
8459  *- - C++
8460  */
8461  const char* lua_evaluate_object_function_2a(const char* lua_object,
8462  const char* function_name,
8463  const char* argument,
8464  const char* argument2,
8465  int has_return_string = 0);
8466 
8467  /*l
8468  *b Description:
8469  **
8470  ** A three argument version of lua_evaluate_object_function().
8471  **
8472  *b Callable From:
8473  **
8474  *- - C++
8475  */
8476  const char* lua_evaluate_object_function_3a(const char* lua_object,
8477  const char* function_name,
8478  const char* argument,
8479  const char* argument2,
8480  const char* argument3,
8481  int has_return_string = 0);
8482 
8483  /*l
8484  *b Description:
8485  **
8486  ** A four argument version of lua_evaluate_object_function().
8487  **
8488  *b Callable From:
8489  **
8490  *- - C++
8491  */
8492  const char* lua_evaluate_object_function_4a(const char* lua_object,
8493  const char* function_name,
8494  const char* argument,
8495  const char* argument2,
8496  const char* argument3,
8497  const char* argument4,
8498  int has_return_string = 0);
8499 
8500  /*l
8501  *b Description:
8502  **
8503  ** Executes a lua_object:state_manager() function call. Useful for
8504  ** creating sleep-able coroutine based objects that aren't
8505  ** characters.
8506  **
8507  *b Callable From:
8508  **
8509  *- - C++
8510  **/
8511  int lua_send_message_to_object(const char* lua_object,
8512  const char* sender,
8513  const char* message_type,
8514  const char* message,
8515  const char* message_params = NULL);
8516 
8517 
8518 #ifdef CPLUSPLUS_ONLY
8519 
8520  /*l
8521  *b Description:
8522  **
8523  ** This function allows low level access to the lua_State pointer.
8524  ** This pointer can be used by a programmer to query and run functions
8525  ** on the Lua virtual machine. This object can also be used to
8526  ** register new C functions to lua, which allows you to instrument and
8527  ** create callbacks from script to your code. See luaL_register
8528  ** on-line.
8529  **
8530  ** For more information on how the Lua C api works see:
8531  ** http://www.lua.org/pil/24.html
8532  **
8533  *b NOTE:
8534  **
8535  ** Currently all scenarios share the same underlying Lua state object.
8536  ** This may cause issues in applications with multiple scenarios.
8537  **
8538  *b Callable From:
8539  **
8540  *- - C++
8541  */
8542  void* get_lua_state();
8543 
8544  /*l
8545  *b Description:
8546  **
8547  ** Mainly used to pass a qt pointer to lua so lqt can be used to
8548  ** modify/read from the widget. This requires the that the lqt package
8549  ** is loaded; see the lqt.lua utility package for more info.
8550  **
8551  *b Arguments:
8552  **
8553  *a lua_state - a Lua_State pointer, might be the same as get_lua_state();
8554  *a depends if the calling function is inside a coroutine
8555  *a class_name - class name should be a core class of qt with a star
8556  *a after it; i.e. "QWidget*" or "QLineEdit*"
8557  *a ptr - pointer to that is returned to the calling function in lua
8558  **
8559  *b Callable From:
8560  **
8561  *- - C++
8562  **
8563  *b C++ Example:
8564  **
8565  *e int push_graphics_view_to_lua(lua_State *L)
8566  *e {
8567  *e bdiQGraphicsView* graphics_view = get_primary_3d_window_graphics_view();
8568  *e if (m_scenario->push_qt_pointer_to_lua(L, "QGraphicsView*", graphics_view) == -1)
8569  *e {
8570  *e return 0;
8571  *e }
8572  *e return 1;
8573  *e }
8574  **
8575  ** Plug-in init code:
8576  **
8577  *e lua_State* L = (lua_State*)scenario->get_lua_state();
8578  *e if (L)
8579  *e {
8580  *e lua_register(L, "get_graphics_view", push_graphics_view_to_lua);
8581  *e }
8582  **
8583  ** In lua:
8584  **
8585  *e local graphics_view = get_graphics_view();
8586  **
8587  **/
8588  int push_qt_pointer_to_lua(void* lua_state,
8589  const char* class_name,
8590  void* ptr);
8591 
8592  /*l
8593  *b Description:
8594  **
8595  ** The most open function calling function available, if this doesn't
8596  ** manage to accomplish what you need you probably want to start
8597  ** using the lua interpreter directly.
8598  **
8599  ** The type arguments are string versions of the type being sent to
8600  ** lua, options include:
8601  *>
8602  *- - '' - empty argument
8603  *- - 'b' boolean - void* argument1 is assumed to be an int
8604  *- - 'f' field - void* argument1 assumed to be character string of
8605  *- a field of a global lua object; supports nested
8606  *- fields like foo.bar.a
8607  *- - 's' string - void* argument1 assumed to be character string
8608  *- - 'd' double - void* argument is assumed to be a double
8609  *- - diguy... - void* argument assumed to be a diguy class
8610  *- pointer ie "diguyCharacter", "diguyCrowd" (no
8611  *- star used for diguy classes)
8612  *- - Q...* - void* argument is assumed to be a pointer to a
8613  *- child of QObject; the class name should be a core
8614  *- class of qt with a star after it, e.g. "QWidget*"
8615  *- or "QLineEdit*"
8616  *<
8617  *b Arguments:
8618  **
8619  *a lua_object - a global lua object
8620  *a function_name - name of the function to call
8621  *a arg(1/2/3/4)_type - is the data type
8622  *a argument(1/2/3/4) - void* pointers to data
8623  *a has_return_string - if set to 1 function will pop the top value of
8624  *a the lua stack and return it as a string
8625  **
8626  *b Returns:
8627  **
8628  ** NULL or string representation of lua_object:function_name(argument)
8629  **
8630  ** The returned string should be copied if it needs to be used later.
8631  **
8632  *b Callable From:
8633  **
8634  *- - C++
8635  **/
8636  const char* lua_evaluate_object_function_4a_flex(const char* lua_object,
8637  const char* function_name,
8638  const char* arg1_type, void* argument1,
8639  const char* arg2_type, void* argument2,
8640  const char* arg3_type, void* argument3,
8641  const char* arg4_type, void* argument4,
8642  int has_return_string = 0);
8643 
8644  /*l
8645  *b Description:
8646  **
8647  ** Effectively the same as diguyScenario::lua_evaluate_object_function_4a_flex()
8648  ** but works on global functions.
8649  **
8650  *b Callable From:
8651  **
8652  *- - C++
8653  */
8654  const char* lua_evaluate_global_function_4a_flex(const char* function_name,
8655  const char* arg_type, void* argument,
8656  const char* arg_type2, void* argument2,
8657  const char* arg_type3, void* argument3,
8658  const char* arg_type4, void* argument4,
8659  int has_return_string = 0);
8660 
8661 #endif
8662 
8663  /*l
8664  *b Description:
8665  **
8666  ** Prints a message to lua interpreter log object. In DI-Guy
8667  ** Scenario this is sent to the AI Mind Editor and used to fill out
8668  ** the error log. The Mind editor log parses debug.traceback()
8669  ** calls.
8670  **/
8671  int lua_log_printf(int notify_level, const char* string);
8672 
8673  /*l
8674  *b Returns:
8675  **
8676  ** package meta data as a formatted string; useful for debugging,
8677  ** only valid inside DI-Guy Scenario
8678  */
8679  const char* dump_package_info(const char* package_name);
8680 
8681 /*****************************************************************************/
8687  /*l
8688  **
8689  *b Description:
8690  **
8691  ** Sends a message to specified diguyCharacter. The recipient must have a
8692  ** Lua mind that is capable of handling the message. The message will wake up
8693  ** the sleep() function in the mind that last relinquished control
8694  ** from the mind's coroutine.
8695  **
8696  *b Arguments:
8697  **
8698  *a to_character - the diguyCharacter to receive the message
8699  *a from_character - the diguyCharacter from whom the message originates
8700  *a message_type - should properly be "signal", but other settings may be used
8701  *a message - the actual name of the message, e.g. "detonation"
8702  *a message_params - comma-separated parameters, for use by the message handler
8703  **
8704  *b Returns:
8705  **
8706  ** 1 if message delivery successful, otherwise 0
8707  **
8708  *b Callable From:
8709  **
8710  *- - C++ and Lua
8711  **/
8712  int send_message(diguyCharacter *to_character,
8713  diguyCharacter *from_character,
8714  const char* message_type,
8715  const char* message,
8716  const char* message_params = NULL);
8717 
8718  /*l
8719  **
8720  *b Description:
8721  **
8722  ** Broadcasts a message to all other diguyCharacters within a certain
8723  ** radius of the from_character. The recipients must have Lua minds
8724  ** that are capable of handling the message. The message will wake up
8725  ** the sleep() function in the mind that last relinquished control
8726  ** from the mind's coroutine.
8727  **
8728  *b Arguments:
8729  **
8730  *a from_character - the diguyCharacter from whom the message originates
8731  *a radius - how far the broadcast goes (in meters) from the from_character
8732  *a message_type - should properly be "broadcast", but other settings may be used
8733  *a message - the actual name of the message, e.g. "detonation"
8734  *a message_params - comma-separated parameters, for use by the message handler
8735  **
8736  *b Returns:
8737  **
8738  ** -1 for failure, >= 0 for number of successful receptions
8739  **
8740  *b Callable From:
8741  **
8742  *- - C++ and Lua
8743  **/
8744  int broadcast_message(diguyCharacter *from_character,
8745  float radius,
8746  const char* message_type,
8747  const char* message,
8748  const char* message_params = NULL);
8749 
8750  /*l
8751  **
8752  *b Description:
8753  **
8754  ** Broadcasts a message to all diguyCharacters within named group, who
8755  ** are within given radius of the from_character. See comments for
8756  ** broadcast_message() above.
8757  **
8758  *b Arguments:
8759  **
8760  *a from_character - the diguyCharacter from whom the message originates
8761  *a group_name - name of group to broadcast to
8762  *a radius - how far the broadcast goes (in meters) from the from_character
8763  *a message_type - should properly be "broadcast", but other settings may be used
8764  *a message - the actual name of the message, e.g. "detonation"
8765  *a message_params - comma-separated parameters, for use by the message handler
8766  **
8767  *b Returns:
8768  **
8769  ** -1 for failure, >= 0 for number of successful receptions
8770  **
8771  *b Callable From:
8772  **
8773  *- - C++ and Lua
8774  **/
8775  int broadcast_message_to_group(diguyCharacter *from_character,
8776  const char * group_name,
8777  float radius,
8778  const char* message_type,
8779  const char* message,
8780  const char* message_params = NULL);
8781 
8782 /****************************************************************************/
8783 /****************************************************************************/
8784 /****************************************************************************/
8791 /****************************************************************************/
8792 /****************************************************************************/
8793 /****************************************************************************/
8794 
8795  /*l
8796  *b Returns:
8797  **
8798  ** value set by last call to set_eval_decisions_as_scripts()
8799  */
8800  int get_eval_decisions_as_scripts();
8801 
8802  /*l
8803  *b Description:
8804  **
8805  ** If called with an argument of 1, all decision beads and decision beads will
8806  ** be converted to scripts before being run.
8807  */
8808  void set_eval_decisions_as_scripts(int eval_decisions_as_scripts);
8809 
8810  /*l
8811  *b Description:
8812  **
8813  ** Gets the point of impact with the world along specified line segment
8814  **
8815  *b Returns:
8816  **
8817  ** pointer to diguyImpact object or NULL
8818  */
8819  diguyImpact* get_impact_on_line(float from_x,
8820  float from_y,
8821  float from_z,
8822  float to_x,
8823  float to_y,
8824  float to_z);
8825 
8826  /*l
8827  *b Description:
8828  **
8829  ** Increments wait cursor counter. If non-zero, then wait cursor is displayed
8830  ** in DI-GUY scenario.
8831  */
8832  void wait_cursor_push();
8833  /*l
8834  *b Description:
8835  **
8836  ** Decrements wait cursor counter.
8837  */
8838  void wait_cursor_pop();
8839 
8840 
8841 #ifdef CPLUSPLUS_ONLY
8842 
8843  /*l
8844  *b Description:
8845  **
8846  ** This function sets a generic node pointer that can later be
8847  ** retrieved by the get_graphics_api_node_ptr() call. The pointer is
8848  ** otherwise not used.
8849  **
8850  *b Arguments:
8851  **
8852  *a node_ptr - generic void* pointer
8853  **
8854  *b Callable From:
8855  **
8856  *- - C++
8857  */
8858  void set_graphics_api_node_ptr(void* node_ptr);
8859 
8860  /*l
8861  *b Returns:
8862  **
8863  ** pointer set by most recent call to set_graphics_api_node_ptr
8864  **
8865  *b Callable From:
8866  **
8867  *- - C++
8868  */
8869  void* get_graphics_api_node_ptr();
8870 
8871 #endif
8872 
8873  /*l
8874  *b Description:
8875  **
8876  ** Sets whether shadow disks are drawn for characters. Call with 1 to turn on,
8877  ** 0 to turn off.
8878  */
8879  void set_draw_character_shadow_disks(int draw_character_shadow_disks);
8880 
8881  /*l
8882  *b Returns:
8883  **
8884  ** 1 if shadow disks are drawn, 0 if not
8885  */
8886  int get_draw_character_shadow_disks();
8887 
8888  /*l
8889  *b Returns:
8890  **
8891  ** size of texture map for shadows
8892  */
8893  int get_shadow_map_size();
8894 
8895  /*l
8896  *b Description:
8897  **
8898  ** Sets size of texture map for shadows. Defaults to 1024. Allowed values
8899  ** are powers of two up to 4096.
8900  */
8901  int set_shadow_map_size(int shadow_size);
8902 
8903  /*l
8904  *b Description:
8905  **
8906  ** Used for DI-Guy OSG Author Programming Example. Sets the default value
8907  ** used for characters. See also diguyCharacter::set_scene_graph_mask()
8908  */
8909  void set_default_character_scene_graph_mask(unsigned long mask);
8910  unsigned long get_default_character_scene_graph_mask();
8911 
8912  /*l
8913  *b Description:
8914  **
8915  ** Used for DI-Guy OSG Author Programming Example. Sets the default value
8916  ** used for characters. See also diguySceneObject::set_scene_graph_mask()
8917  */
8918  void set_default_scene_object_scene_graph_mask(unsigned long mask);
8919  unsigned long get_default_scene_object_scene_graph_mask();
8920 
8921  /*l
8922  *b Description:
8923  **
8924  ** For internal use.
8925  */
8926  void set_internal_int(int var, int val);
8927  void set_internal_float(int var, float val);
8928 
8929  /*l
8930  *b Description:
8931  **
8932  ** This sets the number of point lights that get handed down to
8933  ** diguyGraphicsShaderTechnique::pick_shader_program().
8934  */
8935  int set_num_active_point_lights(int active_lights);
8936 
8937  /*l
8938  *b Description:
8939  ** This gets the number of point lights that get handed down to
8940  ** diguyGraphicsShaderTechnique::pick_shader_program() the default is 0.
8941  ** diguy_ogl_apply_active_lights() automatically updates this value in
8942  ** the OpenGL renderer.
8943  */
8944  int get_num_active_point_lights();
8945 
8946 /****************************************************************************/
8947 /****************************************************************************/
8948 /****************************************************************************/
8952 /****************************************************************************/
8953 /****************************************************************************/
8954 /****************************************************************************/
8955 
8956  /*l
8957  *b Description:
8958  **
8959  ** Sets bounding box of world
8960  **
8961  *b Arguments:
8962  **
8963  *a x_min,y_min,z_min,x_max,y_max,z_max - bounds
8964  **
8965  *b Returns:
8966  **
8967  ** 0 on success, -1 on failure
8968  ** (float * arguments converted to return values in Lua)
8969  */
8970  int set_world_bounds(float x_min, float y_min, float z_min,
8971  float x_max, float y_max, float z_max);
8972 
8973  /*l
8974  *b Description:
8975  **
8976  ** Gets bounding box of world
8977  **
8978  *b Arguments:
8979  **
8980  *a x_min,y_min,z_min,x_max,y_max,z_max - output parameters
8981  **
8982  *b Returns:
8983  **
8984  ** 0 on success, -1 on failure
8985  ** (float * arguments converted to return values in Lua)
8986  */
8987  int get_world_bounds(float* x_min, float* y_min, float* z_min,
8988  float* x_max, float* y_max, float* z_max);
8989 
8990 
8991 
8992 /****************************************************************************/
8993 /****************************************************************************/
8994 /****************************************************************************/
8998 /****************************************************************************/
8999 /****************************************************************************/
9000 /****************************************************************************/
9001 
9002  /*l
9003  *b Description:
9004  **
9005  ** Internal use
9006  */
9007  void set_checkpoint_frequency(float freq);
9008  /*l
9009  *b Description:
9010  **
9011  ** Internal use
9012  */
9013  float get_checkpoint_frequency();
9014  /*l
9015  *b Description:
9016  **
9017  ** Internal use
9018  */
9019  void set_checkpointing_enabled(int enable_checkpointing);
9020  /*l
9021  *b Description:
9022  **
9023  ** Internal use
9024  */
9025  int get_checkpointing_enabled();
9026 
9027  // should be removed, only for testing
9028  //void checkpoint();
9029  //void load_checkpoint();
9030 
9031 /****************************************************************************/
9032 /****************************************************************************/
9033 /****************************************************************************/
9037 /****************************************************************************/
9038 /****************************************************************************/
9039 /****************************************************************************/
9040 
9041  /*l
9042  *b Description:
9043  **
9044  ** Sets initial render mode
9045  **
9046  *b Arguments:
9047  **
9048  *a render_mode - string containing render mode setting name
9049  **
9050  ** Built-in render modes:
9051  **
9052  *- "normal"
9053  *- "shadow"
9054  *- "glow"
9055  *- "alternate1"
9056  *- "alternate2"
9057  *- "alternate3"
9058  */
9059  void set_initial_render_mode(const char* render_mode);
9060 
9061  /*l
9062  *b Returns:
9063  **
9064  ** initial render mode, as string
9065  **
9066  */
9067  const char* get_initial_render_mode();
9068 
9069  /*l
9070  *b Description:
9071  **
9072  ** Sets current render mode. See set_initial_render_mode()
9073  **
9074  */
9075  void set_current_render_mode(const char* render_mode);
9076 
9077  /*l
9078  *b Returns:
9079  **
9080  ** render mode, as string, derived from current light settings
9081  **
9082  *b Arguments:
9083  **
9084  *a set_current_to_derived - if 1, current render mode becomes derived
9085  *- mode
9086  **
9087  */
9088  const char* derive_render_mode_from_light_settings(int set_current_to_derived = 1);
9089 
9091  const char* get_current_render_mode();
9092 
9093  /*l
9094  *b Description:
9095  **
9096  ** Sets default shader for characters
9097  **
9098  *b Arguments:
9099  **
9100  *a render_mode - string containing render mode name
9101  *a shader_name - string containing name of shader technique
9102  *- (there should be a _glsl.cfg file of the same name)
9103  *a update_existing_characters - if 1, all existing characters will now
9104  *- be drawn using this shader
9105  */
9106  void set_default_character_shader(const char* render_mode,
9107  const char* shader_name,
9108  int update_existing_characters = 1);
9109 
9111  const char* get_default_character_shader(const char* render_mode);
9112 
9113  /*l
9114  *b Description:
9115  **
9116  ** Sets default shader for scene objects
9117  **
9118  *b Arguments:
9119  **
9120  *a render_mode - string containing render mode name
9121  *a shader_name - string containing name of shader technique
9122  *- (there should be a _glsl.cfg file of the same name)
9123  *a update_existing_scene_objects - if 1, all existing scene objects will now
9124  *- be drawn using this shader
9125  */
9126  void set_default_scene_object_shader(const char* render_mode,
9127  const char* shader_name,
9128  int update_existing_scene_objects = 1);
9129 
9131  const char* get_default_scene_object_shader(const char* render_mode);
9132 
9133  /*l
9134  *b Description:
9135  **
9136  ** Sets default shader for particle systems
9137  **
9138  *b Arguments:
9139  **
9140  *a render_mode - string containing render mode name
9141  *a shader_name - string containing name of shader technique
9142  *- (there should be a _glsl.cfg file of the same name)
9143  *a update_existing_particle_systems - if 1, all existing particle systems will now
9144  *- be drawn using this shader
9145  */
9146  void set_default_particle_system_shader(const char* render_mode,
9147  const char* shader_name,
9148  int update_existing_particle_systems = 1);
9149 
9151  const char* get_default_particle_system_shader(const char* render_mode);
9152 
9153  /*l
9154  *b Description:
9155  **
9156  ** Sets FaceFX animation set for a given actor.
9157  **
9158  *b Arguments:
9159  **
9160  *a actor_name - actor's name
9161  *a file_name - fully qualified file name ending in ".animset_ingame"
9162  */
9163  int facefx_mount_animset(const char* actor_name, const char* file_name);
9164 
9165  /*l
9166  *b Description:
9167  **
9168  ** Sets vehicle smoothing on or off. If 1, vehicle will be updated
9169  ** at a higher rate than frame dt
9170  **
9171  ** Default is on.
9172  */
9173  int set_vehicle_smoothing_enabled(int enable_smoothing);
9174  int get_vehicle_smoothing_enabled();
9175 
9176  /*l
9177  *b Description:
9178  **
9179  ** Culling distance (from camera) for drawing
9180  */
9181  int set_character_culling_distance(float dist);
9182  float get_character_culling_distance();
9183 
9184  /*l
9185  *b Description:
9186  **
9187  ** Culling distance (from camera)
9188  */
9189  int set_vehicle_culling_distance(float dist);
9190  float get_vehicle_culling_distance();
9191 
9192  /*l
9193  *b Description:
9194  **
9195  ** Culling distance of props (from camera)
9196  */
9197  int set_prop_culling_distance(float dist);
9198  float get_prop_culling_distance();
9199 
9200  /*l
9201  *b Description:
9202  **
9203  * Documentation Pending EXPERIMENTAL IK
9204  */
9205  int set_realtime_ik_enabled(int val);
9206  int get_realtime_ik_enabled();
9207 
9208  int set_draw_ik_visuals(int val);
9209  int get_draw_ik_visuals();
9210 
9211  int set_draw_skeletons(int val);
9212  int get_draw_skeletons();
9213 
9214  float get_last_update_time()
9215  {
9216  if(m_last_update_time == -9999.0f){
9217  return 0.0f;
9218  }
9219  return m_last_update_time;
9220  }
9221 
9222  void set_disable_profiler();
9223 
9226  void calculate_character_lods();
9227 
9228  const char* get_lua_field_as_string(const char* object_name, const char* field_name,
9229  int warn_if_no_field = 1);
9230 
9231  float get_lua_field_as_float(const char* object_name, const char* field_name,
9232  int warn_if_no_field = 1,
9233  int* found_field = NULL);
9234 /****************************************************************************/
9235 /****************************************************************************/
9236 /****************************************************************************/
9247 /****************************************************************************/
9248 /****************************************************************************/
9249 /****************************************************************************/
9250 
9251  // Removed due to head system changes. Body Appearance now dictates what heads are available
9252  /*l
9253  ** Similar to get_character_type_num_appearances(), but for
9254  ** head appearances.
9255  */
9256  int get_character_type_num_head_appearances(const char* character_type);
9257 
9258  /*l
9259  ** Similar to get_character_type_appearance_at_index(), but for
9260  ** head appearances.
9261  */
9262  const char* get_character_type_head_appearance_at_index(const char* character_type,
9263  int index);
9264 
9265 #ifdef CPLUSPLUS_ONLY
9266 
9267  /*l
9268  *b Description:
9269  **
9270  ** Deprecated; use diguyApp::add_default_scenario_callback() instead.
9271  */
9272  static int add_default_callback(int callback_id,
9273  diguyScenarioCallback* callback,
9274  void* callback_params = 0,
9275  void* callback_user_data = 0);
9276 
9277  /*l
9278  *b Description:
9279  **
9280  ** Deprecated; use diguyApp::remove_default_scenario_callback()
9281  ** instead.
9282  */
9283  static int remove_default_callback(int callback_id,
9284  diguyScenarioCallback* callback);
9285 
9286 #endif
9287 
9288  /*l
9289  *b Description:
9290  **
9291  ** Deprecated;
9292  ** use diguyApp::remove_default_scenario_callback_with_User_data()
9293  ** instead.
9294  */
9295  static int remove_default_callback_with_user_data(int callback_id,
9296  void* callback_user_data);
9297 
9298  /*l
9299  *b Description:
9300  **
9301  ** Deprecated; use diguyApp::add_default_scenario_callback_script()
9302  ** instead.
9303  */
9304  static int add_default_callback_script(int callback_id,
9305  const char* callback_script,
9306  const char* callback_script_type);
9307 
9308  /*l
9309  *b Description:
9310  **
9311  ** Deprecated; use diguyApp::remove_default_scenario_callback_script()
9312  ** instead.
9313  */
9314  static int remove_default_callback_script(int callback_id,
9315  const char* callback_script,
9316  const char* callback_script_type);
9317 
9318  /*l
9319  *b Description:
9320  **
9321  ** Deprecated as of 10.0.0; use get_character_type_map() intead,
9322  ** and then call
9323  ** diguyCharacterTypeMap::get_field_value(DIGUY_CHARACTER_TYPE_MAP_FIELD_CHARACTER_CLASS)
9324  */
9325  const char* get_character_type_class(const char* character_type);
9326 
9327  /*l
9328  *b Description:
9329  **
9330  ** Deprecated as of 10.5.1; use merge_object() intead.
9331  */
9332  int merge_asset(const char* string);
9333 
9334  /*l
9335  *b Description:
9336  **
9337  ** Deprecated as of 12.0.0; use bdi_log_print() from libbdilog.h
9338  ** instead.
9339  */
9340  void print_to_log(int notify_level, const char* string);
9341 
9342 
9343 #ifdef CPLUSPLUS_ONLY
9344 
9345  /*
9346  *2 VegaPrime Helper Functions
9347  */
9348  diguyCharacter* create_pending_reflected_character(const char* name,
9349  const char* character_type,
9350  const char* appearance = NULL);
9351 
9352  int set_network_translation(float x, float y, float z);
9353  int get_network_translation(float* x, float* y, float* z);
9354 
9355  /*l
9356  *b Description:
9357  **
9358  ** Deprecated as of 12.0.0; use save_as() instead.
9359  */
9360  void set_project_filename(const char* project_filename);
9361 
9362  /*l
9363  *b Description:
9364  **
9365  ** Deprecated as of 12.0.0; use get_filename() or
9366  ** get_filename_without_directory() intead.
9367  */
9368  const char* get_project_filename();
9369 
9375  bdiScenario* get_scripted_object();
9376 
9377 
9378 private:
9379 
9380  /*l
9381  ** A private constructor. Use the DI-Guy function
9382  ** diguy_create_scenario() to obtain a diguyScenario object pointer.
9383  */
9384  diguyScenario(bdiScenario* scenario);
9385 
9386  /*l
9387  ** A private destructor. Use the DI-Guy function
9388  ** diguy_destroy_scenario() to delete a diguyScenario object pointer.
9389  */
9390  virtual ~diguyScenario();
9391 
9392  /*l
9393  ** A pointer to internal data.
9394  */
9395  bdiScenario* m_scenario;
9396  float m_last_update_time;
9397 
9398  friend class bdiScenario;
9399 
9400 #endif
9401 
9402 };
9403 
9404 #endif /* __diguyScenario_H */
9405 
diguyScenarioFindImpactOnLineFunction
int diguyScenarioFindImpactOnLineFunction(diguyImpact *impact, float from_x, float from_y, float from_z, float to_x, float to_y, float to_z, diguyScenario *s)
Definition: diguy_typedefs.h:145
diguyViewLabel
Definition: diguyViewLabel.h:44
diguyRegion
A two-and-a-half-dimensional surface that represents either a navigation mesh or an area that's been ...
Definition: diguyRegion.h:50
diguyViewCameraSettings
The diguyViewCameraSettings class holds camera settings data that can be loaded into a diguyViewCamer...
Definition: diguyViewCameraSettings.h:43
DIGUY_DEFAULT_FLOAT
#define DIGUY_DEFAULT_FLOAT
This value is a magic number that, when passed to certain functions, means that the function should u...
Definition: diguy_constants.h:79
diguyScenarioCallback
diguyCallbackReturn diguyScenarioCallback(diguyScenario *scenario, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:158
diguyViewFogCallback
diguyCallbackReturn diguyViewFogCallback(diguyViewFog *fog, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:216
diguyViewLightSettings
Summary:
Definition: diguyViewLightSettings.h:45
diguyCharacterCallback
diguyCallbackReturn diguyCharacterCallback(diguyCharacter *character, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:48
diguyCharacterTypeMapField
diguyCharacterTypeMapField
This enumeration allows type map fields to be queried using a numerical value rather than a string na...
Definition: diguyCharacterTypeMap.h:33
diguy_constants.h
diguyHistoryType
diguyHistoryType
DI-Guy history types.
Definition: diguy_constants.h:284
diguyPathShape
Definition: diguyPathShape.h:30
diguyViewLight
Definition: diguyViewLight.h:50
diguy_vector_classes.h
diguyViewFogSettings
The diguyViewFogSettings class holds camera settings data that can be loaded into a diguyViewFog usin...
Definition: diguyViewFogSettings.h:43
diguyIntersectionResult
Experimental class for diguyIntersectionResult exp_intersect_geometry.
Definition: diguyImpact.h:630
diguyMotionDirection
diguyMotionDirection
Definition: diguyMotionDirection.h:26
diguyChainSettings
Definition: diguyChainSettings.h:34
diguyScenarioIntersectionFunction
int diguyScenarioIntersectionFunction(diguyScenario *scenario, float origin_x, float origin_y, float origin_z, float dir_x, float dir_y, float dir_z, float max_distance_to_test, float *intersection_x, float *intersection_y, float *intersection_z, float *normal_x, float *normal_y, float *normal_z)
Definition: diguy_typedefs.h:77
diguyInfoPopup
Definition: diguyInfoPopup.h:32
diguyImpact
A class that represents a bullet impact in the world, often used by AIs to make reaction decisions...
Definition: diguyImpact.h:41
diguyLoadManager
Definition: diguyLoadManager.h:30
diguyCrowdProfile
The class that represents the makeup and base params of a diguyCrowd.
Definition: diguyCrowdProfile.h:37
diguyCharacterPathEvent
Interface to base class of event beads, not often used.
Definition: diguyCharacterPathEvent.h:40
diguyScenarioAltitudeFunction
float diguyScenarioAltitudeFunction(diguyScenario *scenario, float x, float y, float old_z, int *valid)
Definition: diguy_typedefs.h:133
diguyView
A view is a graphics window wherein the scenario and its characters are animated. Note that views hav...
Definition: diguyView.h:48
DIGUY_MERGE_INITIAL_SETTINGS_DEFAULT
Definition: diguy_constants.h:680
DIGUY_CHARACTER_TYPE_MAP_FIELD_UNKNOWN
As string: "unknown".
Definition: diguyCharacterTypeMap.h:38
diguyScenarioMergeInitialSettings
diguyScenarioMergeInitialSettings
This enumeration tells DI-Guy what values to use as defaults when the diguyScenario::create_merge_set...
Definition: diguy_constants.h:678
diguySensorRegionCallback
diguyCallbackReturn diguySensorRegionCallback(diguySensorRegion *sensor_region, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:186
diguyCharacterTypeMap
The character type map provides extra information about DI-Guy character types and appearances...
Definition: diguyCharacterTypeMap.h:291
diguyAltitudeFunction
float diguyAltitudeFunction(diguyCharacter *character, float x, float y, float old_z, int *valid)
Definition: diguy_typedefs.h:54
diguyLightRenderDesc
Definition: diguyViewLight.h:35
diguyCharacterLOSFunction
int diguyCharacterLOSFunction(diguyCharacter *character, diguyCharacter *target_character, int visibility_type)
Definition: diguy_typedefs.h:103
diguyViewLightCallback
diguyCallbackReturn diguyViewLightCallback(diguyViewLight *light, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:180
diguyScenario
Represents the scenario currently being portrayed.
Definition: diguyScenario.h:92
diguyCharacterGroup
A group of DI-Guy characters, useful for organizing your scenarios.
Definition: diguyCharacterGroup.h:39
diguyCharacter
The class that represents a DI-Guy Entity in the world.
Definition: diguyCharacter.h:78
diguyFormation
A class that represents the layout of a group of characters.
Definition: diguyFormation.h:41
diguyWaypoint
Definition: diguyWaypoint.h:29
diguySensorRegion
Definition: diguySensorRegion.h:38
diguyPointLOSFunction
int diguyPointLOSFunction(diguyCharacter *character, float x, float y, float z)
Definition: diguy_typedefs.h:108
diguyViewCallback
diguyCallbackReturn diguyViewCallback(diguyView *view, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:210
declspec_diguy.h
diguySound
This class is represents a sound file on disk.
Definition: diguySound.h:39
diguyFeelerFunction
int diguyFeelerFunction(diguyCharacter *character, float origin_x, float origin_y, float origin_z, float dir_x, float dir_y, float dir_z, float max_distance_to_test, float *intersection_x, float *intersection_y, float *intersection_z, float *normal_x, float *normal_y, float *normal_z)
Definition: diguy_typedefs.h:61
diguyViewCamera
The class that represents a camera in the world.
Definition: diguyViewCamera.h:90
t
static double t
4 Header files and forward declarations
Definition: simple_playback_ogl.cpp:53
diguySignal
Definition: diguySignal.h:36
DIGUY_SUBREGION_MASK_NONE
Definition: diguy_constants.h:1513
diguySignalCallback
diguyCallbackReturn diguySignalCallback(diguySignal *signal, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:192
diguyViewButtonPanel
Definition: diguyViewButtonPanel.h:35
diguyViewFog
Definition: diguyViewFog.h:35
diguy_typedefs.h
diguyCallbackReturn
diguyCallbackReturn
DI-Guy callbacks return a value of type diguyCallbackReturn, which will be DIGUY_CALLBACK_STOP or DIG...
Definition: diguy_constants.h:115
diguyMotionVariant
diguyMotionVariant
Definition: diguyMotionVariant.h:26
diguySceneObject
A scene object is a static (that is, non-moving) object in the scenario. Scene objects are the basic ...
Definition: diguySceneObject.h:43
diguyVisibleFlag
diguyVisibleFlag
This enumeration lists the visibility options for various objects in the DI-Guy Scenario environment...
Definition: diguy_constants.h:519
diguyInteractionMachine::UI_APPEARANCE_NOTIFICATION
Definition: diguyInteractionMachine.h:328
diguyVariable
Definition: diguyVariable.h:38
diguyIGuyController
A class that gives access to IGuy's parameters.
Definition: diguyIGuyController.h:33
diguyScenarioPlaybackMode
diguyScenarioPlaybackMode
This enumeration identifies which playback mode time should follow.
Definition: diguy_constants.h:496
diguyCharacterFaceExpression
A class representing a facial pose.
Definition: diguyCharacterFaceExpression.h:33
diguyScenarioMergeSettings
Definition: diguyScenarioMergeSettings.h:37
diguyInteractionMachine
diguyInteractionMachine objects give DI-Guy Scenario users a way of providing interactive, UI-driven input to a scenario that can change the way a scenario progresses.
Definition: diguyInteractionMachine.h:81
diguyCrowd
The class that represents a DI-Guy Crowd.
Definition: diguyCrowd.h:48
diguyMotionPosture
diguyMotionPosture
Definition: diguyMotionPosture.h:26
diguyDatetimeAdvanceMethod
diguyDatetimeAdvanceMethod
This enumeration lists the methods in which the datetime of a scenario can advance.
Definition: diguy_constants.h:1605
diguyVariableCallback
diguyCallbackReturn diguyVariableCallback(diguyVariable *variable, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:198
scenario
static diguyScenario * scenario
Definition: simple_playback_ogl.cpp:54
diguyViewCameraCallback
diguyCallbackReturn diguyViewCameraCallback(diguyViewCamera *camera, int callback_id, void *callback_params, void *callback_user_data)
Definition: diguy_typedefs.h:204