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