diguyApp.h

Go to the documentation of this file.

/*
 *  Copyright (C) 1992-2013 Boston Dynamics
 *  ALL RIGHTS RESERVED.
 *
 *  These coded instructions, statements, and computer programs
 *  contain unpublished proprietary information of Boston Dynamics
 *  and are protected by Copyright Laws of the United States.
 *  They may not be used, duplicated, or disclosed in any form, in
 *  whole or in part, without the prior written consent from Boston
 *  Dynamics.
 *
 *  RESTRICTED RIGHTS LEGEND
 *  Use, duplication, or disclosure by the government is subject
 *  to restrictions as set forth in FAR 52.227.19(c)(2) or
 *  subparagraph (c)(1)(ii) of the Rights in Technical Data and
 *  Computer Software clause at DFARS 252.227-7013 and/or in
 *  similar or successor clauses in the FAR, or the DOD or NASA
 *  FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the
 *  Commercial Computer Software--Restricted Rights at 48 CFR
 *  52.227-19, as applicable.  Unpublished-rights reserved under
 *  the Copyright Laws of the United States.
 *  Contractor/Manufacturer is:
 *  Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.
 */

/*********************************************************************/
#ifndef __diguyApp_H
#define __diguyApp_H

#ifdef SWIG
%module diguyApp
#else
#define CPLUSPLUS_ONLY
#endif

#ifdef CPLUSPLUS_ONLY

typedef int  (*diguyModuleFunctionVoid)();
class bdiScenarioApp;
class diguyAuthorInterface;
class diguyExerciseInterface;
class diguyGraphicsShaderProgram;
class diguyGraphicsShaderTechnique;
class diguyLoadManager;
class diguyLogChannel;
class diguyVariable;
class diguyViewPainter;

#include <declspec_diguy.h>
#include <diguy_typedefs.h>
#include <diguy_constants.h>
// for NULL
#include <stdlib.h>

#endif


/****************************************************************************/
class BDI_DECLSPEC_diguy diguyApp
{

public:
/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This static function returns a pointer to the DI-Guy
         **    application.  All functions below can then be called
         **    through this pointer.
         **
         *b  Returns:
         **
         **    a pointer of type diguyApp
         **
         *b  C++ Example:
         **
         *e     diguyApp* app = diguyApp::get_app();
         **
         */
        static diguyApp* get_app();

        /*l
         *b  Returns:
         **
         **    number of scenarios in the app
         */
        int get_num_scenarios();

        /*l
         *b  Returns:
         **
         **    pointer of type diguyScenario; NULL if no
         **    scenario at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the scenario; indices start at 0
         */
        diguyScenario* get_scenario_at_index(int index);

        /*l
         *b  Returns:
         **
         **    number of blend functions available
         */
        int get_num_blend_functions();

        /*l
         *b  Returns:
         **
         **    name of blend function at specified index; NULL if no blend
         **    function at specified index
         **
         *b  Arguments:
         **
         *a    index - index of the blend function; indices start at 0
         */
        const char* get_blend_function_name_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns whether or not the application is in debug
         **    mode.  Useful for choosing which versions of shared libraries to
         **    load.
         **
         *b  Returns:
         **
         **    1 if app is in debug mode; 0 if not
         */
        int is_debug();

        /*l
         *b  Description:
         **
         **    This function returns whether or not the DI-Guy SDK is being used
         **    inside of DI-Guy Scenario or as an embedded C++ library.
         **
         *b  Returns:
         **
         **    1 if being used as a library; 0 if not
         */
        int is_api_mode();

        /*l
         *b  Description:
         **
         **    This function returns whether or not the specified module is
         **    currently enabled.
         **
         *b  Returns:
         **
         **    1 if module is enabled; 0 if not
         */
        int is_module_enabled(const char* module_name);

        /*l
         *b  Returns:
         **
         **    pointer of type diguyScenario; NULL if no current scenario
         */
        diguyScenario* get_current_scenario();


/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    the path to the base directory of the DI-Guy installation;
         **    this is typically set by the environment variable DIGUY
         */
        static const char* get_diguy_base_dir_path();

        /*l
         *b  Returns:
         **
         **    the path to a subdirectory of the DI-Guy installation;
         **    this is typically derived from the environment variable
         **    DIGUY, but is sometimes overridden by other environment
         **    variables
         **
         *b  Arguments:
         **
         *a    subdir - name of the subdirectory
         */
        static const char* get_diguy_subdir_path(const char* subdir);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Gets a pointer to the exercise interface.  If DI-Guy is not
         **    on the network, the returned pointer will be NULL.
         **
         *b  Returns:
         **
         **    pointer of type diguyExerciseInterface on success,
         **    NULL on failure or if not on the network
         */
        diguyExerciseInterface* get_exercise_interface();


/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function sets a default user callback that will be added
         **    to all new scenarios.  See diguyScenario::add_callback() for
         **    details.
         */
        int add_default_scenario_callback(int callback_id,
                diguyScenarioCallback* callback,
                void* callback_params = 0,
                void* callback_user_data = 0,
                int remove_on_scenario_load = 1);

        /*l
         *b  Description:
         **
         **    This function removes a default user callback previously added by
         **    add_default_scenario_callback().  See
         **    diguyScenario::remove_callback() for details.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_default_scenario_callback(int callback_id,
                diguyScenarioCallback* callback);

        /*l
         *b  Description:
         **
         **    This function removes a default user callback previously added by
         **    add_default_scenario_callback().  See
         **    diguyScenario::remove_callback_with_user_data() for details.
         */
        int remove_default_scenario_callback_with_user_data(int callback_id,
                void* callback_user_data);

#endif

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function adds a default scenario callback script.
         **    The callback script will be added to all new scenarios.
         **    See diguyScenario::add_callback_script() for
         **    more details.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_default_scenario_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type,
                int remove_on_scenario_load = 1);

        /*l
         *b  Description:
         **
         **    This function removes a default scenario callback script.
         **    See diguyScenario::remove_callback_script() for
         **    more details.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_default_scenario_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type);


/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function is analogous to the
         **    diguyScenario::register_character_event_handler() function, but
         **    is for scenarios rather than characters.
         **
         **    The registered event handler can be mapped to an event via the
         **    DI-Guy Scenario UI, or by the function
         **    diguyScenario::map_event_handler_to_callback_id().
         **
         **    It can also be manually invoked by the function call
         **    diguyScenario::manually_invoke_event_handler().
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int register_scenario_event_handler(const char* handler_name,
                diguyScenarioCallback* callback,
                void* callback_user_data = 0);

#endif

        /*l
         *b  Description:
         **
         **    This function is analogous to the
         **    diguyScenario::register_character_event_handler_from_library()
         **    function, but is for scenarios rather than characters.
         **
         **    The registered event handler can be mapped to an event via the
         **    DI-Guy Scenario UI, or by the function
         **    diguyScenario::map_event_handler_to_callback_id().
         **
         **    It can also be manually invoked by the function call
         **    diguyScenario::manually_invoke_event_handler().
         */
        int register_scenario_event_handler_from_library(const char* handler_name,
                const char* library_name,
                const char* function_name,
                void* callback_user_data = 0);

        /*l
         *b  Description:
         **
         **    This function is analogous to the
         **    diguyScenario::register_character_event_handler_script()
         **    function, but is for scenarios rather than characters.
         **
         **    The registered event handler can be mapped to an event via the
         **    DI-Guy Scenario UI, or by the function
         **    diguyScenario::map_event_handler_to_callback_id().
         **
         **    It can also be manually invoked by the function call
         **    diguyScenario::manually_invoke_event_handler().
         */
        int register_scenario_event_handler_script(const char* handler_name,
                const char* handler_script,
                const char* handler_script_type = NULL);

        /*l
         *b  Description:
         **
         **    This function is analogous to the
         **    diguyScenario::has_registered_character_event_handler()
         **    function, but is for scenarios rather than characters.
         */
        int has_registered_scenario_event_handler(const char* handler_name);

        /*l
         *b  Description:
         **
         **    This function is analogous to the
         **    diguyScenario::unregister_character_event_handler()
         **    function, but is for scenarios rather than characters.
         */
        int unregister_scenario_event_handler(const char* handler_name);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function adds a new dynamic library plugin to the app.
         **    Plugins work within DI-Guy Scenario as well as the DI-Guy SDK.
         **
         *b  Arguments:
         **
         *a    plugin_name              - name of the plugin; should be dynamic
         *a                               library name without the extension
         *a    required_by_scenario     - if set to 1, this plugin is required
         *a                               for proper execution of this scenario;
         *a                               when the scenario is loaded this plugin
         *a                               will be loaded as well if it is not
         *a                               already active; default value is 0
         *a    unload_on_scenario_close - if set to 1, this plugin will be
         *a                               unloaded if this scenario is closed
         *a                               or a new scenario is opened; default
         *a                               value is 0
         *a    accepts_mouse_input      - if set to 1, this plugin will receive
         *a                               mouse events via the mouse plugin
         *a                               functions when the input mode is
         *a                               "Plugin"; default value is 1
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *i  Windows Specific:
         **
         **    The DLL should be placed in a directory that is in the path, or in
         **    the same directory as the DI-Guy Scenario executable.
         **
         **    The DLL version of DI-Guy Scenario or the SDK must be used for
         **    plugins to work.
         ** 
         **  See complete overview at \ref diguyScenarioPluginOverview
         */
        int load_plugin(const char* plugin_name,
                int required_by_scenario = 0,
                int unload_on_scenario_close = 0,
                int accepts_mouse_input = 1);

        /*l
         *b  Description:
         **
         **    This function unloads a dynamic library plugin from the app
         **    that was added using the load_plugin() function.
         **
         *b  Arguments:
         **
         *a    name - name of the plugin
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         ** 
         **  See complete overview at \ref diguyScenarioPluginOverview
         */
        int unload_plugin(const char* plugin_name);

        /*l
         *b  Description:
         **
         **    Unloads all plug-ins.
         */
        void unload_all_plugins();

        /*l
         *b  Returns:
         **
         **    This function returns the number of dynamic library plugins
         **    currently loaded.
         ** 
         **  See complete overview at \ref diguyScenarioPluginOverview
         */
        int get_num_plugins();

        /*l
         *b  Returns:
         **
         **    the name of a specific plug-in at a specified index
         **
         *b  Arguments:
         **
         *-    index - index of the plugin to query
         ** 
         **  See complete overview at \ref diguyScenarioPluginOverview
         */
        const char* get_name_of_plugin(int index);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function loads (or reloads) shader source files into a shader
         **    program.  The shader program can be attached to a character in two
         **    ways:
         **
         **    First, a shader may be explicitly added to a character using the
         **    diguyCharacter::set_shader_program() function.
         **
         **    Second, a shader may be implicitly added to a character if its
         **    appearance specifies an associated shader required to make the
         **    appearance look right.  Most often this is for appearances that
         **    are skinned, requiring a shader to transform the vertices
         **    correctly.  DI-Guy most often uses the 'diguy_object' shader for
         **    this.
         **
         **    If a shader program with the same name has already been loaded,
         **    this function will replace it.
         **
         **    DI-Guy Scenario uses GLSL shaders.
         **
         *b  Arguments:
         **
         *-    shader_name            - name by which shader program will be
         *-                             referenced
         *-    vertex_shader_filename - name of file containing vertex shader
         *-                             source code
         *-    pixel_shader_filename  - name of file containing vertex shader
         *-                             source code
         **
         *b  Returns:
         **
         **    pointer to object type diguyGraphicsShaderProgram on success, NULL
         **    on failure
         */
        diguyGraphicsShaderProgram* load_shader_program(const char* shader_name,
                const char* vertex_shader_filename,
                const char* pixel_shader_filename);

        /*l
         *b  Description:
         **
         **    This function reloads all previously loaded shader programs, using
         **    the same source filenames as were used when the shader was
         **    initially loaded.
         **
         **    This function can be used to reload/replace an existing shader
         **    with the same name, allowing for quick edit and test cycles when
         **    working on new shaders.
         */
        void reload_shader_programs();

        /*l
         *b  Description:
         **
         **    This function looks for the previously loaded shader program with
         **    the given name.
         **
         *b  Arguments:
         **
         *-    shader_name - name of program to find
         **
         *b  Returns:
         **
         **    pointer to object type diguyGraphicsShaderProgram on success, NULL
         **    on failure
         */
        diguyGraphicsShaderProgram* find_shader_program(const char* shader_name);

        /*l
         *b  Returns:
         **
         **    number of loaded shader programs
         */
        int get_num_shader_programs();

        /*l
         *b  Description:
         **
         **    This function returns the shader program at the specified index.
         **
         *b  Arguments:
         **
         *-    index - index of shader program
         **
         *b  Returns:
         **
         **    pointer to object type diguyGraphicsShaderProgram on success, NULL
         **    on failure
         */
        diguyGraphicsShaderProgram* get_shader_program_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns the shader program that's currently active
         **
         *b  Returns:
         **
         **    pointer to object type diguyGraphicsShaderProgram on success, NULL
         **    on failure
         */
        diguyGraphicsShaderProgram* get_current_bound_shader_program();

        /*l
         *b  Description:
         **
         **    This function looks for the previously loaded shader technique with
         **    the given name.
         **
         *b  Arguments:
         **
         *-    shader_technique_name - name of program to find
         **
         *b  Returns:
         **
         **    pointer to object type diguyGraphicsShaderTechnique on success,
         **    NULL on failure
         */
        diguyGraphicsShaderTechnique* find_shader_technique(const char* shader_technique_name);

        /*l
         *b  Returns:
         **
         **    number of loaded shader techniques
         */
        int get_num_shader_techniques();

        /*l
         *b  Returns:
         **    
         **    a pointer to a diguyGraphicsShaderTechnique on success at the 
         **    specified index, NULL on failure.
         **
         *b  Arguments:
         **
         *-    index - index of shader technique
         */
        diguyGraphicsShaderTechnique* get_shader_technique_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function sets the max shader quality level for characters in
         **    the application.  See diguyGraphicsShaderProgram.h for the
         **    diguyGraphicsShaderQualityLevel enum.  This quality level, which
         **    can range from no lighting to normal mapped characters, will be
         **    used to pick an appropriate shader from a shader technique.
         */
        int set_max_character_shader_quality_level(int quality_level);
        int get_max_character_shader_quality_level();

        /*l
         *b  Description:
         **
         **    This function sets the maximum shader quality level for scene
         **    objects in the application.  See
         **    diguyApp::set_max_character_shader_quality_level() for more
         **    information.
         */
        int set_max_scene_object_shader_quality_level(int quality_level);
        int get_max_scene_object_shader_quality_level();

        /*l
         *b  Returns:
         **
         **    the value that was passed in for init.use_sRGB_corrected_textures
         **    allows end users to procedurally choose gamma correction behavior.
         */
        int get_use_sRGB_textures();

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function tells DI-Guy to use quaternions for all joint
         **    angles in motions.  It should be called after DI-Guy is
         **    initialized and before characters are created.  By default
         **    DI-Guy data uses Euler angles.
         **
         **    Some motion operations are faster using quaternions, while
         **    some are not.  In general anything that requires blending
         **    of motions will be faster when using quaternions.
         **
         **    This function should not have any negative effect on character
         **    motion quality.
         **
         *b  Arguments:
         **
         *-    enables - pass 1 to use quaternions for motions, 0 to use
         *-              Euler angles
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  C++ Example:
         **
         *e     diguy_graphics_initialize();
         *e     diguyApp* the_app = diguy_get_app();
         *e     the_app->set_precompute_quaternions_enabled(1);
         **
         */
        int set_precompute_quaternions_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    current setting of whether quaternions are enabled;
         **    see set_precompute_quaternions_enabled()
         */
        int get_precompute_quaternions_enabled();

        /*l
         *b  Description:
         **
         **    This function sets how may rendering passes DI-Guy will use
         **    to draw objects such as characters and scene objects.
         **
         **    By default DI-Guy uses two rendering passes.  Fully opaque
         **    objects are drawn in the first pass; semi-transparent objects
         **    are drawn in the second.
         **
         **    If few or no objects have transparency, the number of rendering
         **    passes can be set to 1, which will increase rendering
         **    performance.
         **
         **    If the number of rendering passes is set to 1, semi-transparent
         **    objects may incorrectly occlude objects behind them, depending
         **    on object rendering order.
         **
         **    This function can be called at any time.
         **
         *b  Arguments:
         **
         *-    num_rendering_passes - how many rendering passes to use;
         *-                           default is 2
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_num_rendering_passes(int num_rendering_passes);

        /*l
         *b  Returns:
         **
         **    current setting of number of rendering passes;
         **    see set_num_rendering_passes()
         */
        int get_num_rendering_passes();

        /*l
         *b  Description:
         **
         **   Gets current render pass flags. See diguyRenderPassFlags. 
         **   The values are or'd together.
         */
        int get_render_pass_flags();

        /*l
         *b  Description:
         **
         **   Sets current render pass flags. See diguyRenderPassFlags. 
         */
        int set_render_pass_flags(int flags);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns the ideal number of threads available on the
         **    system.  This will correspond to the number of available
         **    processors.
         **
         *b  Returns:
         **
         **    ideal number of threads on the system; -1 on failure to detect
         */
        int get_ideal_num_threads();

        /*l
         *b  Description:
         **
         **    This function sets how many threads are available to DI-Guy.
         **
         *b  Arguments:
         **
         *-    num_threads - number of threads available to DI-Guy
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_num_threads(int num_threads);

        /*l
         *b  Returns:
         **
         **    number of threads available to DI-Guy
         */
        int get_num_threads();

        /*l
         *b  Description:
         **
         **    This function reserves threads for the client application by
         **    setting the number of threads available to DI-Guy.  DI-Guy will use
         **    up to (max_num_threads - reserve_num_threads).
         **
         *b  Arguments:
         **
         *-    reserve_num_threads - how many threads to reserve
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int reserve_num_threads(int num_reserve_threads);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function changes the current Input Mode of the DI-Guy Scenario
         **    application or a DI-Guy Author Host IG.
         **
         *b  Arguments:
         **
         *a    mode - the new base Input Mode of DI-Guy Scenario or DI-Guy Author
         **
         *b  Returns:
         **
         **    -1 if mode change failed (e.g., tried for AI-related mode but AI
         **    not available, 0 on no error
         */
        int set_base_input_mode(diguyScenarioInputMode mode);

        /*l
         *b  Returns:
         **
         **    the current Input Mode of the DI-Guy Scenario application or a
         **    DI-Guy Author Host IG.
         */
        diguyScenarioInputMode get_base_input_mode();

        /*l
         *b  Description:
         **
         **    This function returns the 3D world position of the last clicked
         **    point in a DI-Guy Scenario 3D view.
         **
         **    This function is meant to complement the use of callbacks with
         **    callback id DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         **
         **    Pass NULL for any values that are not needed.
         */
        int get_last_clicked_xyz(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    This function sets the 3D world position of the last clicked point
         **    in a DI-Guy Scenario 3D view.
         **
         **    This function is meant to complement the use of callbacks with
         **    callback id DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         */
        void set_last_clicked_xyz(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    This function returns the last character clicked by the mouse in
         **    DI-Guy Scenario.
         **
         **    This function is meant to complement the use of callbacks with
         **    callback id DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacter; may be NULL if no character has
         **    been clicked
         */
        diguyCharacter* get_last_clicked_character();

        /*l
         *b  Description:
         **
         **    This function returns the current screen coordinates x and y
         **    position of the mouse.
         */
        int get_mouse_screen_xy(float* sx, float* sy);

        /*l
         *b  Description:
         **
         **    This function returns the current xyz coordinates under the mouse
         **    location, this is a fairly speedy test since the octtree is used.
         **    Typically this function is used to help build interactive UI tools.
         **
         *b  Arguments:
         **
         *a    x, y, z - resulting position in meters from the origin
         */
        int get_xyz_under_mouse(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    This function sets up the UI to notify a lua object of mouse events
         **    via messages while in input mode
         **    DIGUY_SCENARIO_INPUT_MODE_POINT_SELECT.
         **
         **    The following callbacks are generated:
         *>
         *-      - CALLBACK_ID_UI_MOUSE_DOWN
         *-      - CALLBACK_ID_UI_MOUSE_UP
         *-      - CALLBACK_ID_UI_RIGHT_MOUSE_DOWN
         *-      - CALLBACK_ID_UI_RIGHT_MOUSE_UP
         *<
         **    See luaUIStateMachine:get_user_selected_point() to see an example
         **    of usage. Typically this function is used to help build interactive
         **    UI tools.
         **
         *b  Arguments:
         **
         *a   object_name - resulting position in meters from the origin
         */
        void set_lua_object_waiting_for_input(const char* object_name);

        /*l
         *b  Returns:
         **
         **   The name of the lua object that's currently waiting for input
         **   events.  Can return NULL if there's no active object.
         */
        const char* get_lua_object_waiting_for_input();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function is equivalent to the function
         **    diguy_author_get_author_interface() in diguy_author.h.  It is made
         **    available here so it is available to scripts.
         */
        diguyAuthorInterface* get_author_interface();


/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    This function returns a pointer to a diguyViewPainter object.
         **    This object can be used to draw lines, text, and other primitives
         **    in the 3D views of DI-Guy Scenario.
         */
        diguyViewPainter* get_view_painter();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether the two specified collision groups
         **    should collide against each other.
         **
         *b  Arguments:
         **
         *a    collision_group1  - first collision group
         *a    collision_group2  - second collision group
         *a    enable_collisions - pass 1 to have groups collide, 0 to not
         */
        void set_collision_group_detection_flag(diguyPhysicsCollisionGroup collision_group1,
                diguyPhysicsCollisionGroup collision_group2,
                int enable_collisions);

        /*l
         *b  Description:
         **
         **    This function returns whether the two specified collision groups
         **    should collide against each other.
         **
         *b  Arguments:
         **
         *a    collision_group1  - first collision group
         *a    collision_group2  - second collision group
         **
         *b  Returns:
         **
         **    1 if collision groups collide, 0 if not
         */
        int get_collision_group_detection_flag(diguyPhysicsCollisionGroup collision_group1,
                diguyPhysicsCollisionGroup collision_group2);

        /*l
         *b  Description:
         **
         **    The physics simulation module can have an optional ground plane
         **    enabled through which no objects will pass.  This function sets
         **    whether the ground plane is enabled.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable ground plane, 0 to disable
         */
        void set_physics_sim_ground_plane_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if physics sim ground plane enabled, 0 if not
         */
        int get_physics_sim_ground_plane_enabled();

        /*l
         *b  Description:
         **
         **    The physics simulation module can have an optional ground plane
         **    enabled through which no objects will pass.  This function sets the
         **    height of the ground plane.
         **
         *b  Arguments:
         **
         *a    height - height in meters
         */
        void  set_physics_sim_ground_plane_height(float height);

        /*l
         *b  Returns:
         **
         **    height of physics sim ground plane
         */
        float get_physics_sim_ground_plane_height();


/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    the library suffix, which is derived from the dll compiling flags, e.g. "_x86_vc9_md"
         */
        static const char* get_standard_bdi_library_suffix();

        /*l
         *b  Returns:
         **
         **    the library suffix, which is derived from the version number, e.g. "_1250"
         */
        static const char* get_diguy_version_library_suffix();

        /*l
         *b  Returns:
         **
         **    the library suffix, which is derived from the compiler type, e.g. "_vc9"
         */
        static const char* get_compiler_library_suffix();

        /*l
         *b  Description:
         **
         **    Loads dynamic library module.  The handle returned can be
         **    passed into resolve_symbol() or unload_module_library().
         **
         *b  Returns:
         **
         **    handle as (void *) pointer, NULL if library is not found or failed to load.
         **
         **    Load status is set to:
         **
         **     0 : load successful
         **    -1 : library not found
         **    -2 : ?
         */
        static void* load_module_library(const char* module_lib_name,
                int include_diguy_standard_library_suffixes = 1,
                int* load_status = NULL);

        /*l
         *b  Description:
         **
         **    Returns pointer to function provided by already-loaded dynamic library module.
         **    Pointer should be cast to one of:
         **
         **    - diguyModuleFunctionInt
         **    - diguyModuleFunctionVoid
         **    - diguyModuleFunctionVoidReturnsVoid
         **
         *b  Returns:
         **
         **    pointer to function, or NULL if function not found.
         */
        static void* resolve_module_library_symbol(void* module_handle, const char* symbol_name);

        /*l
         *b  Description:
         **
         **    Unloads dynamic library module, given handle to it.
         **
         */
        static void unload_module_library(void* module_handle);

        /*l
         *b  Description:
         **
         **    Returns 1 if a sound factory is initialized.
         */
        int get_sound_factory_is_initialized();

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets override values for the specified munition type's DIS impact
         **    septet.
         **
         **    Munition types are defined in the config file munition_types.cfg,
         **    located under the DI-Guy installation config directory.
         **
         *b  Arguments:
         **
         *-    munition_type - name of munition type to modify; e.g., "m16"
         *-    sep1, etc.    - new DIS septet values
         */
        int set_munition_type_DIS_impact_septet(const char* munition_type,
                int sep1, int sep2, int sep3, int sep4, int sep5, int sep6, int sep7);

        /*l
         *b  Description:
         **
         **    Similar to set_munition_type_DIS_impact_septet(), but overrides the
         **    septet for tracer type.
         */
        int set_munition_type_DIS_tracer_septet(const char* munition_type,
                int sep1, int sep2, int sep3, int sep4, int sep5, int sep6, int sep7);

        /*l
         *b  Description:
         **
         **    Returns the munition type name based on the passed septet values.
         **
         *b  Arguments:
         **
         *-    sep1, etc.    - DIS septet values
         *-    include_last_septet_value - pass 1 to include the last septet
         *-                    value in the search, 0 to not
         */
        const char* get_munition_type_from_DIS_septet(
                int sep1, int sep2, int sep3, int sep4, int sep5, int sep6, int sep7,
                int include_last_septet_value = 1);


/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

        /*l
         *b  Description:
         **
         **    Causes garbage-collection to unload graphics files that have been
         **   previously loaded into memory, but are unused, freeing up memory. There
         **   may be a frame hitch if graphics files are to be used again and need to be 
         **   reloaded.
         **
         *b  Arguments:
         **
         *-    garbage_collect_appearances - setting to 1 will attempt to remove
         *-                   unused character appearance geometry as well as
         *-                   scene objects; default is 1. If 0, only scene object
         *-                   files will be discarded.
         */
        int unload_unreferenced_graphics_files(int garbage_collect_appearances = 1);

        /*l
         *b  Description:
         **
         **    Causes textures that have changes to be reloaded
         */
        int reload_texture_files();

        /*l
         *b  Description:
         **
         **    How many textures in memory before texture unloading starts (defaults to 5000)
         */
        int set_threshold_to_unload_textures(int number);
        int get_threshold_to_unload_textures();

        /*l
         *b  Description:
         **
         **    How often to check if inactive textures should be unloaded.
         */
        int set_texture_unload_frequency(float seconds);
        float get_texture_unload_frequency();

        /*l
         *b  Description:
         **
         **    Should unused assets be garbage collected after loading a new scenario.
         */
        int get_unload_unused_after_scenario_load();
        int set_unload_unused_after_scenario_load(int val);

        /*l
         *b  Description:
         **
         **    Sets whether optimized versions of motion files should be cached to
         **    disk when they are loaded.
         **
         **    This is still experimental.  The default is 0, don't enable
         **    caching.
         **
         *b  Arguments:
         **
         *-    enabled - pass 1 to enable caching, 0 to disable
         */
        int set_cache_optimized_motion_files(int enabled = 0);

        /*l
         *b  Returns:
         **
         **    1 if caching of optimized motion files is enabled, 0 if disabled
         */
        int get_cache_optimized_motion_files();

        /*l
         *b  Description:
         **
         **    Prints to the log a report about memory usage and leaks.
         **
         *b  Arguments:
         **
         *-    include_permanent_objects - pass 1 to include permanent objects 
         *-                                in reports; 0 is default
         *-    just_markers              - pass 1 to only generate reports for
         *-                                memory use at instants after a marker
         *-                                is dropped
         */
        int memory_tracker_print_report(int include_permanent_objects = 0, int just_markers = 0);
        /*l
         *b  Description:
         **
         **    Add a marker for use by memory_tracker_print_report()
         */
        int memory_tracker_drop_marker();

        /*l
         *b  Description:
         **
         **    Provide DI-Guy Scenario with a list of messages that the user can access
         **   from the right-click menu. When a message is selected, it is sent over the
         **   network to the AIs of remote entities. If the AIs can process the message,
         **   they will. Typically used to kill remote entities from a master server.
         **
         *b  Arguments:
         **
         *-    message - a string containing a comma-separated list of messages. 
         */
        void set_reflected_entity_message_list(const char* message);

        /*l
         *b  Description:
         **
         **    Returns a string containing a comma-separated list of supported 
         **    reflected-entity messages, as set by set_reflected_entity_message_list()
         */
        const char* get_reflected_entity_message_list();

        /*l
         *b  Description:
         **
         **    In DI-Guy Scenario pops up a user interface asking the end user to 
         **    pick a scene object file name.
         */
        const char* get_scene_object_file_name_from_ui();

        /*l
         *b  Description:
         **
         **    Causes DI-Guy to display UI relevant to navmesh generation
         */
        int show_generate_navmesh_ui();


/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

        /*l
         *b  Returns:
         **
         **    Newly-created log channel
         */
        diguyLogChannel* create_log_channel();

        /*l
         *b  Description:
         **
         **    Destroys specified log channel
         */
        void destroy_log_channel(diguyLogChannel*);

        /*l
         *b  Returns:
         **
         **    Number of log channels
         */
        int get_num_log_channels();

        /*l
         *b  Returns:
         **
         **    Log channel at index
         */
        diguyLogChannel* get_log_channel_at_index(int index);


/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

        /*l
         **  Deprecated as of DI-Guy 12.0.0.
         **  Use diguyAuthorVisualRegionPaintbrush::set_painting_subregion()
         **  instead.
         */
        int set_current_painting_subregion(diguySubregionIndex index);



#ifdef CPLUSPLUS_ONLY

        void set_no_blend_test(int flag);

        void set_motion_events_log_enabled(int enabled);

        void dump_motion_events_to_file(const char* filename,
                int show_event_id_strings = 0,
                int indent = 0);

        bdiScenarioApp* get_scripted_object() {return m_scripted_object;}


private:

        /*l
         **    A private constructor.  Use the DI-Guy function
         **    get_app() to obtain a diguyApp object pointer.
         */
        diguyApp(bdiScenarioApp* scenario);

        /*l
         **    A private destructor.  Use the DI-Guy function
         **    diguy_deinitialize() to delete a diguyApp object pointer.
         */
        virtual ~diguyApp();

        /*l
         **    A pointer to internal data.
         */
        bdiScenarioApp* m_scripted_object;

        friend class bdiScenarioApp;

#endif

};

#endif /* __diguyApp_H */