DI-Guy API Version 12.5.1

This file was automatically generated from diguyApp.h. Do not edit this file directly; the changes will be lost.

Contents:

• General Functions
• Directory Functions
• Networking Functions
• C++ Only Callback Functions
• C++ and Script Callback Functions
• Event Handler Functions
• Plugin Functions
• Shader Functions
• Performance Functions
• Threading Functions
• User Input Functions
• DI-Guy Author Functions
• Draw Functions
• Physics Module Functions
• Library Functions
• Experimental Munition Type Functions
• Experimental Functions
• Experimental Log Channel Functions
• Deprecated Functions

Link against: libdiguy

Prototype:

typedef int  (*diguyModuleFunctionVoid)();

class BDI_DECLSPEC_diguy diguyApp { public:     static diguyApp* get_app();     int get_num_scenarios();     diguyScenario* get_scenario_at_index(int index);     int get_num_blend_functions();     const char* get_blend_function_name_at_index(int index);     int is_debug();     int is_api_mode();     int is_module_enabled(const char* module_name);     diguyScenario* get_current_scenario();     static const char* get_diguy_base_dir_path();     static const char* get_diguy_subdir_path(const char* subdir);     diguyExerciseInterface* get_exercise_interface(); #ifdef CPLUSPLUS_ONLY     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);     int remove_default_scenario_callback(int callback_id,         diguyScenarioCallback* callback);     int remove_default_scenario_callback_with_user_data(int callback_id,         void* callback_user_data); #endif     int add_default_scenario_callback_script(int callback_id,         const char* callback_script,         const char* callback_script_type,         int remove_on_scenario_load = 1);     int remove_default_scenario_callback_script(int callback_id,         const char* callback_script,         const char* callback_script_type); #ifdef CPLUSPLUS_ONLY     int register_scenario_event_handler(const char* handler_name,         diguyScenarioCallback* callback,         void* callback_user_data = 0); #endif     int register_scenario_event_handler_from_library(const char* handler_name,         const char* library_name,         const char* function_name,         void* callback_user_data = 0);     int register_scenario_event_handler_script(const char* handler_name,         const char* handler_script,         const char* handler_script_type = NULL);     int has_registered_scenario_event_handler(const char* handler_name);     int unregister_scenario_event_handler(const char* handler_name);     int load_plugin(const char* plugin_name,         int required_by_scenario = 0,         int unload_on_scenario_close = 0,         int accepts_mouse_input = 1);     int unload_plugin(const char* plugin_name);     void unload_all_plugins();     int get_num_plugins();     const char* get_name_of_plugin(int index);     diguyGraphicsShaderProgram* load_shader_program(const char* shader_name,         const char* vertex_shader_filename,         const char* pixel_shader_filename);     void reload_shader_programs();     diguyGraphicsShaderProgram* find_shader_program(const char* shader_name);     int get_num_shader_programs();     diguyGraphicsShaderProgram* get_shader_program_at_index(int index);     diguyGraphicsShaderProgram* get_current_bound_shader_program();     diguyGraphicsShaderTechnique* find_shader_technique(const char* shader_technique_name);     int get_num_shader_techniques();     diguyGraphicsShaderTechnique* get_shader_technique_at_index(int index);     int set_max_character_shader_quality_level(int quality_level);     int get_max_character_shader_quality_level();     int set_max_scene_object_shader_quality_level(int quality_level);     int get_max_scene_object_shader_quality_level();     int get_use_sRGB_textures();     int set_precompute_quaternions_enabled(int enabled);     int get_precompute_quaternions_enabled();     int set_num_rendering_passes(int num_rendering_passes);     int get_num_rendering_passes();     int get_render_pass_flags();     int set_render_pass_flags(int flags);     int get_ideal_num_threads();     int set_num_threads(int num_threads);     int get_num_threads();     int reserve_num_threads(int num_reserve_threads);     int set_base_input_mode(diguyScenarioInputMode mode);     diguyScenarioInputMode get_base_input_mode();     int get_last_clicked_xyz(float* x, float* y, float* z);     void set_last_clicked_xyz(float x, float y, float z);     diguyCharacter* get_last_clicked_character();     int get_mouse_screen_xy(float* sx, float* sy);     int get_xyz_under_mouse(float* x, float* y, float* z);     void set_lua_object_waiting_for_input(const char* object_name);     const char* get_lua_object_waiting_for_input();     diguyAuthorInterface* get_author_interface();     diguyViewPainter* get_view_painter();     void set_collision_group_detection_flag(diguyPhysicsCollisionGroup collision_group1,         diguyPhysicsCollisionGroup collision_group2,         int enable_collisions);     int get_collision_group_detection_flag(diguyPhysicsCollisionGroup collision_group1,         diguyPhysicsCollisionGroup collision_group2);     void set_physics_sim_ground_plane_enabled(int enabled);     int get_physics_sim_ground_plane_enabled();     void set_physics_sim_ground_plane_height(float height);     float get_physics_sim_ground_plane_height();     static const char* get_standard_bdi_library_suffix();     static const char* get_diguy_version_library_suffix();     static const char* get_compiler_library_suffix();     static void* load_module_library(const char* module_lib_name,         int include_diguy_standard_library_suffixes = 1,         int* load_status = NULL);     static void* resolve_module_library_symbol(void* module_handle, const char* symbol_name);     static void unload_module_library(void* module_handle);     int get_sound_factory_is_initialized();     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);     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);     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);     int unload_unreferenced_graphics_files(int garbage_collect_appearances = 1);     int reload_texture_files();     int set_threshold_to_unload_textures(int number);     int get_threshold_to_unload_textures();     int set_texture_unload_frequency(float seconds);     float get_texture_unload_frequency();     int get_unload_unused_after_scenario_load();     int set_unload_unused_after_scenario_load(int val);     int set_cache_optimized_motion_files(int enabled = 0);     int get_cache_optimized_motion_files();     int memory_tracker_print_report(int include_permanent_objects = 0, int just_markers = 0);     int memory_tracker_drop_marker();     void set_reflected_entity_message_list(const char* message);     const char* get_reflected_entity_message_list();     const char* get_scene_object_file_name_from_ui();     int show_generate_navmesh_ui();     diguyLogChannel* create_log_channel();     void destroy_log_channel(diguyLogChannel*);     int get_num_log_channels();     diguyLogChannel* get_log_channel_at_index(int index);     int set_current_painting_subregion(diguySubregionIndex index);

Unless otherwise noted all functions in this class section are callable from:

• C++
• Script

In lua static function are callable as diguyApp_function_name or via the this_app global.

Prototype:

static diguyApp* get_app();

Description:

This static function returns a pointer to the DI-Guy application. All functions below can then be called through this pointer.

Returns:

a pointer of type diguyApp

C++ Example:

diguyApp* app = diguyApp::get_app();

Prototype:

int get_num_scenarios();

Returns:

number of scenarios in the app

Prototype:

diguyScenario* get_scenario_at_index(int index);

Returns:

pointer of type diguyScenario; NULL if no scenario at the specified index

Arguments:

index

index of the scenario; indices start at 0

Prototype:

int get_num_blend_functions();

Returns:

number of blend functions available

Prototype:

const char* get_blend_function_name_at_index(int index);

Returns:

name of blend function at specified index; NULL if no blend function at specified index

Arguments:

index

index of the blend function; indices start at 0

Prototype:

int is_debug();

Description:

This function returns whether or not the application is in debug mode. Useful for choosing which versions of shared libraries to load.

Returns:

1 if app is in debug mode; 0 if not

Prototype:

int is_api_mode();

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.

Returns:

1 if being used as a library; 0 if not

Prototype:

int is_module_enabled(const char* module_name);

Description:

This function returns whether or not the specified module is currently enabled.

Returns:

1 if module is enabled; 0 if not

Prototype:

diguyScenario* get_current_scenario();

Returns:

pointer of type diguyScenario; NULL if no current scenario

• C++
• Script

• C++
• Script

Prototype:

diguyExerciseInterface* get_exercise_interface();

Description:

Gets a pointer to the exercise interface. If DI-Guy is not on the network, the returned pointer will be NULL.

Returns:

pointer of type diguyExerciseInterface on success, NULL on failure or if not on the network

Prototype:

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);

Description:

This function sets a default user callback that will be added to all new scenarios. See diguyScenario::add_callback() for details.

Prototype:

int remove_default_scenario_callback(int callback_id,
    diguyScenarioCallback* callback);

Description:

This function removes a default user callback previously added by add_default_scenario_callback(). See diguyScenario::remove_callback() for details.

Returns:

0 on success, -1 on failure

Prototype:

int remove_default_scenario_callback_with_user_data(int callback_id,
    void* callback_user_data);

Description:

This function removes a default user callback previously added by add_default_scenario_callback(). See diguyScenario::remove_callback_with_user_data() for details.

Prototype:

int add_default_scenario_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type,
    int remove_on_scenario_load = 1);

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.

Returns:

0 on success, -1 on failure

Prototype:

int remove_default_scenario_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type);

Description:

This function removes a default scenario callback script. See diguyScenario::remove_callback_script() for more details.

Returns:

0 on success, -1 on failure

DI-Guy event handlers are similar to callbacks, but have a name with which they can be referenced. This name allows DI-Guy Scenario to map event handlers to callback ids using a UI, and allows for these mappings to be saved and restored as part of the scenario.

Prototype:

int register_scenario_event_handler(const char* handler_name,
    diguyScenarioCallback* callback,
    void* callback_user_data = 0);

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().

Callable From:

• C++

Prototype:

int register_scenario_event_handler_from_library(const char* handler_name,
    const char* library_name,
    const char* function_name,
    void* callback_user_data = 0);

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().

Prototype:

int register_scenario_event_handler_script(const char* handler_name,
    const char* handler_script,
    const char* handler_script_type = NULL);

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().

Prototype:

int has_registered_scenario_event_handler(const char* handler_name);

Description:

This function is analogous to the diguyScenario::has_registered_character_event_handler() function, but is for scenarios rather than characters.

Prototype:

int unregister_scenario_event_handler(const char* handler_name);

Description:

This function is analogous to the diguyScenario::unregister_character_event_handler() function, but is for scenarios rather than characters.

See complete overview at \ref diguyScenarioPluginOverview

\page diguyScenarioPluginOverview DI-Guy Scenario Plug-in Overview

\tableofcontents

A DI-Guy plugin is a dynamic library that adds additional functionality to DI-Guy Scenario or to an application using the standard DI-Guy SDK libraries.

Plugins can be loaded in three ways:

• specified on DI-Guy Scenario command line using "+plugin xyz" argument
• added to a scenario in DI-Guy Scenario via the Scenario ObjectsSpecialized ObjectsPlugins page
• by calling diguyApp::load_plugin()

Once a plugin has successfully been loaded, functions from the plugin will be called at specific times during scenario execution.

Plugins can be unloaded in four ways:

• DI-Guy Scenario is shut down
• if part of a scenario, and the plugin is removed from the scenario by pressing Unload on the Plugins page
• if part of a scenario, "Unload on Scenario Close" on the Plugins page is checked, and a new scenario is loaded
• by calling diguyApp::unload_plugin()

Once a plugin has successfully been loaded, functions from the plugin will be called at specific times during scenario execution.

Following is a list of the functions that DI-Guy will look for in the library. Note that a plugin does not need to implement all of these functions; if a function is missing the plugin will quietly skip it. Only the diguy_version() function must be implemented.

Note that new functions may be added to plugins in the future.

void diguy_version(int* version_major, int* version_minor, int* version_point)

This function will be called once, when the plugin is being loaded. The function should return, via the passed int pointers, the DI-Guy version number as defined in diguy_constants.h. DI-Guy will compare these numbers against the current version number to make sure the plugin is compatible with the current version.

C++ Example:

__declspec(dllexport) void diguy_version(int* version_major, int* version_minor, int* version_point) { *version_major = DIGUY_VERSION_MAJOR; *version_minor = DIGUY_VERSION_MINOR; *version_point = DIGUY_VERSION_POINT; }

This function will be called once, when the plugin is being loaded.

If the plugin is being loaded because it was specified on the DI-Guy Scenario command line, this function will be called as DI-Guy Scenario is initializing, before the first scenario is created.

If the plugin is part of a scenario (is shown in the DI-Guy Scenario Scenario ObjectsSpecialized ObjectsPlugins page), the call will happen when the scenario is loaded.

If the plugin is being loaded because of a load_plugin() call, this function will be called during the load_plugin() call.

void deinitialize_plugin(diguyApp* app)

This function will be called once, when the plugin is being unloaded. The call will happen while DI-Guy Scenario is shutting down, or during the unload_plugin() call if the plugin is being explicitly unloaded by function call.

void initialize(diguyScenario* s)

This function will be called when the passed scenario first becomes aware of the plugin. This will be when the scenario is created if the plugin has already been loaded, or during the load_plugin() call if the plugin is loaded after the scenario was created.

void deinitialize(diguyScenario* s)

This function will be called when the scenario is deleted, or when unload_plugin() is called.

void pre_update(diguyScenario* s)

This function will be called during the diguyScenario::update() call, before anything else is changed due to the update. (i.e., characters will not have moved yet, etc.)

void post_update(diguyScenario* s)

This function will be called during the diguyScenario::update() call, after everything else is changed due to the update. (i.e., characters will have moved, etc.)

void pre_draw(diguyScenario* s)

This function will be called during the diguyScenario::draw() call, before anything else is drawn.

void post_draw(diguyScenario* s)

This function will be called during the diguyScenario::draw() call, after everything else is drawn.

void reset(diguyScenario* s)

This function will be called when the scenario is reset, either due to pressing the Reset button in DI-Guy Scenario, or calling the diguyScenario::reset() function. The scenario is also implicitly reset when a .dss file is loaded.

diguyPluginMouseCursor get_mouse_cursor(diguyScenario* s)

This function should return which type of cursor should be used when the mouse is in a 3D view. See the documentation for diguyPluginMouseCursor for which values are available. If this function is not exported from the plugin, the default cursor DIGUY_PLUGIN_MOUSE_CURSOR_LEFT_ARROW will be used.

void mouse_press(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called on an initial press of any mouse button in a 3D view. Use the query functions of the diguyPluginMouseEvent object to retrieve which view the press occurred in and the x and y screen coordinates of the press.

void mouse_drag(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called when the mouse is moved in a 3D while one or more buttons are pressed.

void mouse_release(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called when any mouse button is released in a 3D view.

void mouse_move(diguyScenario* s, diguyPluginMouseEvent* mouse_event)

This function is called when the mouse is moved in a 3D while no buttons are pressed.

int key_press(diguyScenario* s, diguyPluginKeyboardEvent* keyboard_event)

This function is called on an initial press of any key in a 3D view. Use the query functions of the diguyPluginKeyboardEvent object to retrieve which view the press occurred in and the code of the key. The code can be a standard ASCII value, or one of the DIGUY_SPECIAL_KEY_* values defined in diguy_constants.h. Return 1 to indicate that the key was handled and that the default key handler should not be called. Return 0 for the default key handler to be called.

int key_release(diguyScenario* s, diguyPluginKeyboardEvent* keyboard_event)

The same as key_press(), but called when the key is released.

void save_review_data(diguyScenario* s, const char* filename)

This function will be called when after-action review data for the scenario is saved by a call to diguyScenario::save_review_data().

void load_review_data(diguyScenario* s, const char* filename)

This function will be called when after-action review data for the scenario is loaded by a call to diguyScenario::load().

Windows Specific:

Plugin functions should be declared with __declspec(dllexport) to make sure that the symbols are properly exported from the DLL.

The LIBC version that the plugin uses (MD, MDd, MT, or MTd) must be the same as that of DI-Guy Scenario or the DI-Guy libraries used. If this does not happen conflicting versions of the DI-Guy DLLs will be loaded and the program will be unstable.

Prototype:

int load_plugin(const char* plugin_name,
    int required_by_scenario = 0,
    int unload_on_scenario_close = 0,
    int accepts_mouse_input = 1);

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.

Arguments:

plugin_name	name of the plugin; should be dynamic library name without the extension
required_by_scenario	if set to 1, this plugin is required for proper execution of this scenario; when the scenario is loaded this plugin will be loaded as well if it is not already active; default value is 0
unload_on_scenario_close	if set to 1, this plugin will be unloaded if this scenario is closed or a new scenario is opened; default value is 0
accepts_mouse_input	if set to 1, this plugin will receive mouse events via the mouse plugin functions when the input mode is "Plugin"; default value is 1

Returns:

0 on success, -1 on failure

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

Prototype:

int unload_plugin(const char* plugin_name);

Description:

This function unloads a dynamic library plugin from the app that was added using the load_plugin() function.

Arguments:

name	name of the plugin

Returns:

0 on success, -1 on failure

See complete overview at \ref diguyScenarioPluginOverview

Prototype:

void unload_all_plugins();

Description:

Unloads all plug-ins.

Prototype:

int get_num_plugins();

Returns:

This function returns the number of dynamic library plugins currently loaded.

See complete overview at \ref diguyScenarioPluginOverview

Prototype:

const char* get_name_of_plugin(int index);

Returns:

the name of a specific plug-in at a specified index

Arguments:

See complete overview at \ref diguyScenarioPluginOverview

Prototype:

diguyGraphicsShaderProgram* load_shader_program(const char* shader_name,
    const char* vertex_shader_filename,
    const char* pixel_shader_filename);

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.

Arguments:

Returns:

pointer to object type diguyGraphicsShaderProgram on success, NULL on failure

Prototype:

void reload_shader_programs();

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.

Prototype:

diguyGraphicsShaderProgram* find_shader_program(const char* shader_name);

Description:

This function looks for the previously loaded shader program with the given name.

Arguments:

Returns:

pointer to object type diguyGraphicsShaderProgram on success, NULL on failure

Prototype:

int get_num_shader_programs();

Returns:

number of loaded shader programs

Prototype:

diguyGraphicsShaderProgram* get_shader_program_at_index(int index);

Description:

This function returns the shader program at the specified index.

Arguments:

Returns:

pointer to object type diguyGraphicsShaderProgram on success, NULL on failure

Prototype:

diguyGraphicsShaderProgram* get_current_bound_shader_program();

Description:

This function returns the shader program that's currently active

Returns:

pointer to object type diguyGraphicsShaderProgram on success, NULL on failure

Prototype:

diguyGraphicsShaderTechnique* find_shader_technique(const char* shader_technique_name);

Description:

This function looks for the previously loaded shader technique with the given name.

Arguments:

Returns:

pointer to object type diguyGraphicsShaderTechnique on success, NULL on failure

Prototype:

int get_num_shader_techniques();

Returns:

number of loaded shader techniques

Prototype:

diguyGraphicsShaderTechnique* get_shader_technique_at_index(int index);

Returns:

a pointer to a diguyGraphicsShaderTechnique on success at the specified index, NULL on failure.

Arguments:

Prototype:

int set_max_character_shader_quality_level(int quality_level);

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.

Prototype:

int get_max_character_shader_quality_level();

Prototype:

int set_max_scene_object_shader_quality_level(int quality_level);

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.

Prototype:

int get_max_scene_object_shader_quality_level();

Prototype:

int get_use_sRGB_textures();

Returns:

the value that was passed in for init.use_sRGB_corrected_textures allows end users to procedurally choose gamma correction behavior.

Prototype:

int set_precompute_quaternions_enabled(int enabled);

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.

Arguments:

Returns:

0 on success, -1 on failure

C++ Example:

diguy_graphics_initialize(); diguyApp* the_app = diguy_get_app(); the_app->set_precompute_quaternions_enabled(1);

Prototype:

int get_precompute_quaternions_enabled();

Returns:

current setting of whether quaternions are enabled; see set_precompute_quaternions_enabled()

Prototype:

int set_num_rendering_passes(int num_rendering_passes);

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.

Arguments:

Returns:

0 on success, -1 on failure

Prototype:

int get_num_rendering_passes();

Returns:

current setting of number of rendering passes; see set_num_rendering_passes()

Prototype:

int get_render_pass_flags();

Description:

Gets current render pass flags. See diguyRenderPassFlags. The values are or'd together.

Prototype:

int set_render_pass_flags(int flags);

Description:

Sets current render pass flags. See diguyRenderPassFlags.

Prototype:

int get_ideal_num_threads();

Description:

This function returns the ideal number of threads available on the system. This will correspond to the number of available processors.

Returns:

ideal number of threads on the system; -1 on failure to detect

Prototype:

int set_num_threads(int num_threads);

Description:

This function sets how many threads are available to DI-Guy.

Arguments:

Returns:

0 on success, -1 on failure

Prototype:

int get_num_threads();

Returns:

number of threads available to DI-Guy

Prototype:

int reserve_num_threads(int num_reserve_threads);

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).

Arguments:

Returns:

0 on success, -1 on failure

Prototype:

int set_base_input_mode(diguyScenarioInputMode mode);

Description:

This function changes the current Input Mode of the DI-Guy Scenario application or a DI-Guy Author Host IG.

Arguments:

mode	the new base Input Mode of DI-Guy Scenario or DI-Guy Author

Returns:

-1 if mode change failed (e.g., tried for AI-related mode but AI not available, 0 on no error

Prototype:

diguyScenarioInputMode get_base_input_mode();

Returns:

the current Input Mode of the DI-Guy Scenario application or a DI-Guy Author Host IG.

Prototype:

int get_last_clicked_xyz(float* x, float* y, float* z);

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.

Arguments:

x, y, z

position in meters from the origin

Pass NULL for any values that are not needed.

Prototype:

void set_last_clicked_xyz(float x, float y, float z);

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.

Arguments:

x, y, z

position in meters from the origin

Prototype:

diguyCharacter* get_last_clicked_character();

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.

Returns:

pointer of type diguyCharacter; may be NULL if no character has been clicked

Prototype:

int get_mouse_screen_xy(float* sx, float* sy);

Description:

This function returns the current screen coordinates x and y position of the mouse.

Prototype:

int get_xyz_under_mouse(float* x, float* y, float* z);

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.

Arguments:

x, y, z

resulting position in meters from the origin

Prototype:

void set_lua_object_waiting_for_input(const char* object_name);

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.

Arguments:

object_name

resulting position in meters from the origin

Prototype:

const char* get_lua_object_waiting_for_input();

Returns:

The name of the lua object that's currently waiting for input events. Can return NULL if there's no active object.

Prototype:

diguyAuthorInterface* get_author_interface();

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.

Prototype:

diguyViewPainter* get_view_painter();

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.

Prototype:

void set_collision_group_detection_flag(diguyPhysicsCollisionGroup collision_group1,
    diguyPhysicsCollisionGroup collision_group2,
    int enable_collisions);

Description:

This function sets whether the two specified collision groups should collide against each other.

Arguments:

collision_group1	first collision group
collision_group2	second collision group
enable_collisions	pass 1 to have groups collide, 0 to not

Prototype:

int get_collision_group_detection_flag(diguyPhysicsCollisionGroup collision_group1,
    diguyPhysicsCollisionGroup collision_group2);

Description:

This function returns whether the two specified collision groups should collide against each other.

Arguments:

collision_group1	first collision group
collision_group2	second collision group

Returns:

1 if collision groups collide, 0 if not

Prototype:

void set_physics_sim_ground_plane_enabled(int enabled);

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.

Arguments:

enabled

pass 1 to enable ground plane, 0 to disable

Prototype:

int get_physics_sim_ground_plane_enabled();

Returns:

1 if physics sim ground plane enabled, 0 if not

Prototype:

void  set_physics_sim_ground_plane_height(float height);

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.

Arguments:

height

height in meters

Prototype:

float get_physics_sim_ground_plane_height();

Returns:

height of physics sim ground plane

These functions provide support for loading DI-Guy modules at runtime, without need for linking against module import libraries.

Prototype:

static void* load_module_library(const char* module_lib_name,
    int include_diguy_standard_library_suffixes = 1,
    int* load_status = NULL);

Description:

Loads dynamic library module. The handle returned can be passed into resolve_symbol() or unload_module_library().

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 : ?

Prototype:

static void* resolve_module_library_symbol(void* module_handle, const char* symbol_name);

Description:

Returns pointer to function provided by already-loaded dynamic library module. Pointer should be cast to one of:

- diguyModuleFunctionInt - diguyModuleFunctionVoid - diguyModuleFunctionVoidReturnsVoid

Returns:

pointer to function, or NULL if function not found.

Prototype:

static void unload_module_library(void* module_handle);

Description:

Unloads dynamic library module, given handle to it.

Prototype:

int get_sound_factory_is_initialized();

Description:

Returns 1 if a sound factory is initialized.

These functions provide access to munition types defined for DI-Guy.

Prototype:

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);

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.

Arguments:

Prototype:

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);

Description:

Similar to set_munition_type_DIS_impact_septet(), but overrides the septet for tracer type.

Prototype:

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);

Description:

Returns the munition type name based on the passed septet values.

Arguments:

Prototype:

int unload_unreferenced_graphics_files(int garbage_collect_appearances = 1);

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.

Arguments:

Prototype:

int reload_texture_files();

Description:

Causes textures that have changes to be reloaded

Prototype:

int set_threshold_to_unload_textures(int number);

Description:

How many textures in memory before texture unloading starts (defaults to 5000)

Prototype:

int get_threshold_to_unload_textures();

Prototype:

int set_texture_unload_frequency(float seconds);

Description:

How often to check if inactive textures should be unloaded.

Prototype:

float get_texture_unload_frequency();

Prototype:

int get_unload_unused_after_scenario_load();

Description:

Should unused assets be garbage collected after loading a new scenario.

Prototype:

int set_unload_unused_after_scenario_load(int val);

Prototype:

int set_cache_optimized_motion_files(int enabled = 0);

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.

Arguments:

Prototype:

int get_cache_optimized_motion_files();

Returns:

1 if caching of optimized motion files is enabled, 0 if disabled

Prototype:

int memory_tracker_print_report(int include_permanent_objects = 0, int just_markers = 0);

Description:

Prints to the log a report about memory usage and leaks.

Arguments:

Prototype:

int memory_tracker_drop_marker();

Description:

Add a marker for use by memory_tracker_print_report()

Prototype:

void set_reflected_entity_message_list(const char* message);

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.

Arguments:

Prototype:

const char* get_reflected_entity_message_list();

Description:

Returns a string containing a comma-separated list of supported reflected-entity messages, as set by set_reflected_entity_message_list()

Prototype:

const char* get_scene_object_file_name_from_ui();

Description:

In DI-Guy Scenario pops up a user interface asking the end user to pick a scene object file name.

Prototype:

int show_generate_navmesh_ui();

Description:

Causes DI-Guy to display UI relevant to navmesh generation

Prototype:

diguyLogChannel* create_log_channel();

Returns:

Newly-created log channel

Prototype:

void destroy_log_channel(diguyLogChannel*);

Description:

Destroys specified log channel

Prototype:

int get_num_log_channels();

Returns:

Number of log channels

Prototype:

diguyLogChannel* get_log_channel_at_index(int index);

Returns:

Log channel at index

Prototype:

int set_current_painting_subregion(diguySubregionIndex index);

Deprecated as of DI-Guy 12.0.0. Use diguyAuthorVisualRegionPaintbrush::set_painting_subregion() instead.

Alphabetical Index

• add_default_scenario_callback (diguyApp)
• add_default_scenario_callback_script (diguyApp)
• create_log_channel (diguyApp)
• destroy_log_channel (diguyApp)
• diguyApp
• find_shader_program (diguyApp)
• find_shader_technique (diguyApp)
• get_app (diguyApp)
• get_author_interface (diguyApp)
• get_base_input_mode (diguyApp)
• get_blend_function_name_at_index (diguyApp)
• get_cache_optimized_motion_files (diguyApp)
• get_collision_group_detection_flag (diguyApp)
• get_current_bound_shader_program (diguyApp)
• get_current_scenario (diguyApp)
• get_exercise_interface (diguyApp)
• get_ideal_num_threads (diguyApp)
• get_last_clicked_character (diguyApp)
• get_last_clicked_xyz (diguyApp)
• get_log_channel_at_index (diguyApp)
• get_lua_object_waiting_for_input (diguyApp)
• get_max_character_shader_quality_level (diguyApp)
• get_max_scene_object_shader_quality_level (diguyApp)
• get_mouse_screen_xy (diguyApp)
• get_munition_type_from_DIS_septet (diguyApp)
• get_name_of_plugin (diguyApp)
• get_num_blend_functions (diguyApp)
• get_num_log_channels (diguyApp)
• get_num_plugins (diguyApp)
• get_num_rendering_passes (diguyApp)
• get_num_scenarios (diguyApp)
• get_num_shader_programs (diguyApp)
• get_num_shader_techniques (diguyApp)
• get_num_threads (diguyApp)
• get_physics_sim_ground_plane_enabled (diguyApp)
• get_physics_sim_ground_plane_height (diguyApp)
• get_precompute_quaternions_enabled (diguyApp)
• get_reflected_entity_message_list (diguyApp)
• get_render_pass_flags (diguyApp)
• get_scenario_at_index (diguyApp)
• get_scene_object_file_name_from_ui (diguyApp)
• get_shader_program_at_index (diguyApp)
• get_shader_technique_at_index (diguyApp)
• get_sound_factory_is_initialized (diguyApp)
• get_texture_unload_frequency (diguyApp)
• get_threshold_to_unload_textures (diguyApp)
• get_unload_unused_after_scenario_load (diguyApp)
• get_use_sRGB_textures (diguyApp)
• get_view_painter (diguyApp)
• get_xyz_under_mouse (diguyApp)
• has_registered_scenario_event_handler (diguyApp)
• int
• is_api_mode (diguyApp)
• is_debug (diguyApp)
• is_module_enabled (diguyApp)
• load_module_library (diguyApp)
• load_plugin (diguyApp)
• load_shader_program (diguyApp)
• memory_tracker_drop_marker (diguyApp)
• memory_tracker_print_report (diguyApp)
• register_scenario_event_handler (diguyApp)
• register_scenario_event_handler_from_library (diguyApp)
• register_scenario_event_handler_script (diguyApp)
• reload_shader_programs (diguyApp)
• reload_texture_files (diguyApp)
• remove_default_scenario_callback (diguyApp)
• remove_default_scenario_callback_script (diguyApp)
• remove_default_scenario_callback_with_user_data (diguyApp)
• reserve_num_threads (diguyApp)
• resolve_module_library_symbol (diguyApp)
• set_base_input_mode (diguyApp)
• set_cache_optimized_motion_files (diguyApp)
• set_collision_group_detection_flag (diguyApp)
• set_current_painting_subregion (diguyApp)
• set_last_clicked_xyz (diguyApp)
• set_lua_object_waiting_for_input (diguyApp)
• set_max_character_shader_quality_level (diguyApp)
• set_max_scene_object_shader_quality_level (diguyApp)
• set_munition_type_DIS_impact_septet (diguyApp)
• set_munition_type_DIS_tracer_septet (diguyApp)
• set_num_rendering_passes (diguyApp)
• set_num_threads (diguyApp)
• set_physics_sim_ground_plane_enabled (diguyApp)
• set_physics_sim_ground_plane_height (diguyApp)
• set_precompute_quaternions_enabled (diguyApp)
• set_reflected_entity_message_list (diguyApp)
• set_render_pass_flags (diguyApp)
• set_texture_unload_frequency (diguyApp)
• set_threshold_to_unload_textures (diguyApp)
• set_unload_unused_after_scenario_load (diguyApp)
• show_generate_navmesh_ui (diguyApp)
• unload_all_plugins (diguyApp)
• unload_module_library (diguyApp)
• unload_plugin (diguyApp)
• unload_unreferenced_graphics_files (diguyApp)
• unregister_scenario_event_handler (diguyApp)