diguyScenario Class Declaration

diguyScenario.h

DI-Guy API Version 5.1.26

This file was automatically generated from comments in the C/C++ header file diguyScenario.h. Do not edit this file directly; the changes will be lost. Please mail suggestions or corrections to diguy@bdi.com

Alphabetical Index

Includes: diguyCharacter.h | diguyCharacterPath.h | diguySensorRegion.h | diguySignal.h | diguy_constants.h | diguyCharacterFaceExpression.h | diguyView.h | diguyViewCamera.h | diguyViewFog.h | diguyViewLight.h | declspec_diguy.h

Link against: libdiguy

class diguyScenario

class BDI_DECLSPEC_diguy diguyScenario
{
public:
    static diguyScenario* get_current_scenario();
#ifdef CPLUSPLUS_ONLY
    int set_graphics_attach_ptr(void* graphics_attach_ptr);
    int draw();
    int draw_pass1();
    int draw_pass2();
    int post_draw();
#endif
    const char* get_name();
    const char* get_type_name();
    int load(const char* filename);
    int merge(const char* filename);
    int reset();
    int preload_character_type(const char* character_type);
    int preload_appearance(const char* appearance);
    int add_custom_appearance(const char* appearance,
        char** equipment_list,
        char** character_types);
    int add_custom_appearance_based_on_existing_appearance(const char* appearance,
        const char* existing_appearance,
        char** equipment_list);
    int preload_gesture(const char* character_type, const char* gesture_name);
    void print_to_log(int notify_level, const char* string);
    float get_t();
    float get_tin();
    float get_tout();
    int get_playback_loop();
#ifdef CPLUSPLUS_ONLY
    int update(float t);
    int update2(float t, float realtime_t);
    int set_tin(float tin);
    int set_tout(float tout);
    int set_playback_loop(int playback_loop);
#endif
    int get_num_character_types();
    const char* get_character_type_at_index(int index);
    const char* get_character_type_abbreviation(const char* character_type);
    int get_character_type_num_appearances(const char* character_type);
    const char* get_character_type_appearance_at_index(const char* character_type,
        int index);
    int get_character_type_num_actions(const char* character_type);
    const char* get_character_type_action_at_index(const char* character_type,
        int index);
    float get_character_type_action_speed(const char* character_type,
        const char* action_name);
    float get_character_type_action_duration(const char* character_type,
        const char* action_name);
    float get_character_type_action_distance(const char* character_type,
        const char* action_name);
    const char* get_character_type_action_direction(const char* character_type,
        const char* action_name);
    int get_num_characters();
    diguyCharacter* get_character_at_index(int index);
    diguyCharacter* find_character(const char* name);
    diguyCharacter* this_character();
    diguyCharacterPathEvent* this_event_bead();
    void set_iguy_character(const char* name);
    diguyCharacter* create_character(const char* name,
        const char* character_type,
        const char* appearance = NULL);
    int destroy_character(diguyCharacter* character);
    int get_num_path_shapes();
    diguyPathShape* get_path_shape_at_index(int index);
    diguyPathShape* find_path_shape(const char* name);
    diguyPathShape* create_path_shape(const char* name);
    int destroy_path_shape(diguyPathShape* path_shape);
    diguyWaypoint* create_waypoint(float x = 0.0f, float y = 0.0f, float z = 0.0f,
        float yaw = 0.0f, float roll = 0.0f, float pitch = 0.0f,
        float weight = 1.0f);
    int destroy_waypoint(diguyWaypoint* waypoint);
    int get_num_signals();
    diguySignal* get_signal_at_index(int index);
    diguySignal* find_signal(const char* name);
    diguySignal* create_signal(const char* name);
    int destroy_signal(diguySignal* signal);
    void reset_signals();
    int get_num_sounds();
    diguySound* get_sound_at_index(int index);
    diguySound* find_sound(const char* name);
    diguySound* create_sound(const char* name);
    int destroy_sound(diguySound* sound);
    int stop_all_sounds();
    int get_num_groups();
    diguyCharacterGroup* get_group_at_index(int index);
    diguyCharacterGroup* find_group(const char* name);
    diguyCharacterGroup* create_group(const char* name);
    int destroy_group(diguyCharacterGroup* group);
    int get_num_sensor_regions();
    diguySensorRegion* get_sensor_region_at_index(int index);
    diguySensorRegion* find_sensor_region(const char* name);
    int get_num_scene_objects();
    diguySceneObject* get_scene_object_at_index(int index);
    diguySceneObject* find_scene_object(const char* name);
    void set_scene_objects_enabled(int scene_objects_enabled);
    int get_scene_objects_enabled();
    diguyView* get_primary_view();
    int get_num_secondary_views();
    diguyView* get_secondary_view_at_index(int index);
    diguyView* find_view(const char* name);
    diguyViewCamera* get_scenario_camera();
    diguyViewCamera* find_camera(const char* name);
    void set_scenario_camera_affected_by_script_events(int flag);
    int get_scenario_camera_affected_by_script_events();
    void set_scenario_camera_affected_by_script_events_when_iguy_active(int flag);
    int get_scenario_camera_affected_by_script_events_when_iguy_active();
    int get_num_camera_settings();
    diguyViewCameraSettings* get_camera_settings_at_index(int index);
    diguyViewCameraSettings* find_camera_settings(const char* settings_name);
    int load_camera_settings(const char* settings_name);
    diguyViewFog* get_scenario_fog();
    diguyViewFog* find_fog(const char* name);
    int get_num_fog_settings();
    diguyViewFogSettings* get_fog_settings_at_index(int index);
    diguyViewFogSettings* find_fog_settings(const char* settings_name);
    int load_fog_settings(const char* settings_name);
    diguyViewLight* get_scenario_light();
    diguyViewLight* find_light(const char* name);
    int get_num_light_settings();
    diguyViewLightSettings* get_light_settings_at_index(int index);
    diguyViewLightSettings* find_light_settings(const char* settings_name);
    int load_light_settings(const char* settings_name);
    int get_num_info_popups();
    diguyInfoPopup* get_info_popup_at_index(int index);
    diguyInfoPopup* find_info_popup(const char* name);
    int set_info_popup_default_encoding(const char* info_popup_default_encoding);
    const char* get_info_popup_default_encoding();
    int get_num_variables();
    diguyVariable* get_variable_at_index(int index);
    diguyVariable* find_variable(const char* name);
    diguyVariable* find_or_create_variable(const char* name);
    int destroy_variable(diguyVariable* variable);
    int get_num_face_expressions();
    diguyCharacterFaceExpression* get_face_expression_at_index(int index);
    diguyCharacterFaceExpression* find_face_expression(const char* name);
    diguyCharacterFaceExpression* create_face_expression(const char* name);
    int destroy_face_expression(diguyCharacterFaceExpression* face_expression);
    enum {
        CALLBACK_ID_CREATE = 1,
        CALLBACK_ID_DESTROY,
        CALLBACK_ID_RESET,
        CALLBACK_ID_WAIT_CURSOR_SHOW,
        CALLBACK_ID_WAIT_CURSOR_HIDE,
        CALLBACK_ID_LOAD,
        CALLBACK_ID_SAVE,
        CALLBACK_ID_LOAD_SCENARIO_FILE
    };
#ifdef CPLUSPLUS_ONLY
    int add_callback(int callback_id,
        diguyScenarioCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0);
    int remove_callback(int callback_id,
        diguyScenarioCallback* callback);
    int remove_callback_with_user_data(int callback_id,
        void* callback_user_data);
    static int add_default_callback(int callback_id,
        diguyScenarioCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0);
    static int remove_default_callback(int callback_id,
        diguyScenarioCallback* callback);
    static int remove_default_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int set_default_character_altitude_function(diguyAltitudeFunction* altitude_function);
    int add_default_character_callback(int callback_id,
        diguyCharacterCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0);
    int remove_default_character_callback(int callback_id,
        diguyCharacterCallback* callback);
    int remove_default_character_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_path_callback(int callback_id,
        diguyCharacterPathCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0);
    int remove_default_path_callback(int callback_id,
        diguyCharacterPathCallback* callback);
    int remove_default_path_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_sensor_region_callback(int callback_id,
        diguySensorRegionCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0);
    int remove_default_sensor_region_callback(int callback_id,
        diguySensorRegionCallback* callback);
    int remove_default_sensor_region_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_signal_callback(int callback_id,
        diguySignalCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0);
    int remove_default_signal_callback(int callback_id,
        diguySignalCallback* callback);
    int remove_default_signal_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_view_callback(int callback_id,
        diguyViewCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 1);
    int remove_default_view_callback(int callback_id,
        diguyViewCallback* callback);
    int remove_default_view_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_camera_callback(int callback_id,
        diguyViewCameraCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0);
    int remove_default_camera_callback(int callback_id,
        diguyViewCameraCallback* callback);
    int remove_default_camera_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_fog_callback(int callback_id,
        diguyViewFogCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0);
    int remove_default_fog_callback(int callback_id,
        diguyViewFogCallback* callback);
    int remove_default_fog_callback_with_user_data(int callback_id,
        void* callback_user_data);
    int add_default_light_callback(int callback_id,
        diguyViewLightCallback* callback,
        void* callback_params,
        void* callback_user_data,
        int add_to_existing_objects_flag = 0);
    int remove_default_light_callback(int callback_id,
        diguyViewLightCallback* callback);
    int remove_default_light_callback_with_user_data(int callback_id,
        void* callback_user_data);
#endif
#ifdef CPLUSPLUS_ONLY
    int add_named_callback(const char* callback_name,
        diguyScenarioNamedCallback* callback,
        void* user_data);
    int remove_named_callback(const char* callback_name);
#endif
    int call_named_callback(const char* callback_name);
    int save_review_data(const char* filename);
    int get_loaded_from_review_data();
    int get_automatic_graphics_lod_switching();
    void set_automatic_graphics_lod_switching(int enable_graphics_lod_switching);
#ifdef CPLUSPLUS_ONLY
    void set_default_lod_ranges(const char* character_type, float ranges[]);
#endif
    int get_automatic_motion_lod_switching();
    void set_automatic_motion_lod_switching(int enable_motion_lod_switching);
    int eval_script(const char* script_text,
        int save_as_transient = 0);
    int eval_script_file(const char* filename);
    int trigger_script_event(const char* name);
    void push_transient_script_event(float t, const char* script_text);
    void clear_transient_script_events();
    int save_transient_script_events(const char* filename);
    int load_transient_script_events(const char* filename);
    int add_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int remove_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    static int add_default_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type);
    static int remove_default_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type);
    int add_default_character_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0);
    int remove_default_character_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_sensor_region_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0);
    int remove_default_sensor_region_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_signal_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0);
    int remove_default_signal_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_view_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0);
    int remove_default_view_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_camera_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0);
    int remove_default_camera_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_fog_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0);
    int remove_default_fog_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int add_default_light_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL,
        int add_to_existing_objects_flag = 0);
    int remove_default_light_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    diguyCharacterFaceExpression* find_or_create_face_expression(const char* name);
    bdiScenario* get_scripted_object() {return m_scenario;}
};

DI-Guy Scenario Functions

function diguyScenario::get_current_scenario

Prototype:

static diguyScenario* get_current_scenario();
Description:

This static function returns a pointer to the current scenario object. All functions below can then be called through this pointer. This is the same pointer returned by the call diguy_create_scenario().

Perl scripts get the current scenario through the variable $this_scenario.

Callable From:

Returns:

a pointer of type diguyScenario

C++ Example:

diguyScenario* sc = diguyScenario::get_current_scenario();
sc->reset();
Perl Example:

$this_scenario->reset();

function diguyScenario::set_graphics_attach_ptr

Prototype:

int set_graphics_attach_ptr(void* graphics_attach_ptr);
Description:

This function sets the attachment point that to be used for graphics created by the library.

Callable From:

Arguments:

graphics_attach_ptrthis is a pointer to a group-type object. The specific type is dependent on graphics environment.
Returns:

0 on success, -1 on failure

Performer 2.x Version:

The passed pointer should be a pfGroup.

pfGroup* attach_group = get_scene_ptr();
ps->set_graphics_attach_ptr(attach_group);
OpenGL Version:

This function does not have any effect.

Direct3D Version:

The passed pointer should be a LPDIRECT3DRMFRAME2.

LPDIRECT3DRMFRAME2 attach_frame = get_scene_frame();
ps->set_graphics_attach_ptr(attach_frame);

function diguyScenario::draw

Prototype:

int draw();
Description:

This function draws all visible elements of the loaded scenario in immediate mode graphics environments (see below). This is the equivalent of calling draw_pass1() immediately followed by draw_pass2().

Callable From:

Returns:

0 on success, -1 on failure

Performer 2.x Version:

This function has no effect. These environments automatically draw all elements in their visual database.

OpenGL Version:

Direct3D Version:

This function immediately draws all scenario elements. Either this function or draw_pass1() and draw_pass2() should be called once per frame.

function diguyScenario::draw_pass1

Prototype:

int draw_pass1();
Description:

This function, along with draw_pass2(), allows the drawing of opaque and transparent polygons to be separated. This function draws all opaque polygons.

Callable From:

Returns:

0 on success, -1 on failure

Performer 2.x Version:

This function has no effect. These environments automatically draw all elements in their visual database.

OpenGL Version:

Direct3D Version:

This function immediately draws the opaque scenario elements. Either this function or draw() should be called once per frame.

function diguyScenario::draw_pass2

Prototype:

int draw_pass2();
Description:

Same as draw_pass1(), but draws transparent scenario elements.

Callable From:

function diguyScenario::post_draw

Prototype:

int post_draw();
Description:

This function draws visual elements that must be drawn after the main render has been done. What this means is dependent on platform.

Callable From:

Returns:

0 on success, -1 on failure

Performer 2.x Version:

Text overlays will be rendered. The Performer DRAW process should call this function once per frame.

C++ Example:

pfChanTravFunc(shared_data->channel, PFTRAV_DRAW, draw_channel);

...

void draw_channel(pfChannel *channel, void *data)
{
    ...
    pfPushState();
    pfBasicState();
    diguy_scenario->post_draw();
    pfPopState();
    ...
}

function diguyScenario::get_name

Prototype:

const char* get_name();
Description:

Returns the name of the object. This pointer will never be NULL.

Callable From:

Returns:

name of the object

function diguyScenario::get_type_name

Prototype:

const char* get_type_name();
Description:

Returns the type name of the object. This pointer will never be NULL.

Callable From:

Returns:

type name of the object

function diguyScenario::load

Prototype:

int load(const char* filename);
Description:

This function loads the specified scenario. Any previously loaded scenario elements will be deleted.

The passed filename can be either a ".dss" file, which is a DI-Guy Scenario file, or a ".dsr" file, which is a DI-Guy Review file.

Callable From:

Arguments:

filenamefilename of scenario to be loaded
Returns:

0 on success, -1 on failure

function diguyScenario::merge

Prototype:

int merge(const char* filename);
Description:

This function merges the specified scenario. Any previously loaded scenario elements will be retained.

Callable From:

Arguments:

filenamefilename of scenario to be merged
Returns:

0 on success, -1 on failure

function diguyScenario::reset

Prototype:

int reset();
Description:

This function resets all scenario characters and signals. Data for scenario elements will be recalculated on the next call to update().

Callable From:

Returns:

0 on success, -1 on failure

function diguyScenario::preload_character_type

Prototype:

int preload_character_type(const char* character_type);
Description:

This function preloads all base motions and the default appearance for the specified character type.

This can be done during initialization to preload characters that will be needed later in a scenario, to avoid a hitch in frame rate when the characters are loaded.

Callable From:

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
Returns:

0 on success, -1 on failure

function diguyScenario::preload_appearance

Prototype:

int preload_appearance(const char* appearance);
Description:

This function preloads all geometry for the specified appearance. This can be done during initialization to preload geometry that will be needed later in a scenario, to avoid a hitch in frame rate when the geometry is loaded.

Callable From:

Arguments:

appearancename of the appearance whose geometry is to be preloaded
Returns:

0 on success, -1 on failure

function diguyScenario::add_custom_appearance

Prototype:

int add_custom_appearance(const char* appearance,
		char** equipment_list,
		char** character_types);
Description:

This function adds a custom appearance with the given name to the list of available appearances. If an appearance with the given name already exists the operation will fail and a message will be printed at debug level to the output log.

Internal copies are made of the passed strings.

Callable From:

Arguments:

appearance name of the appearance
equipment_list NULL-terminated list of equipment that makes up the appearance
character_typesNULL-terminated list of character types that this appearance will be available to
Returns:

0 on success, -1 on failure

function diguyScenario::add_custom_appearance_based_on_existing_appearance

Prototype:

int add_custom_appearance_based_on_existing_appearance(const char* appearance,
		const char* existing_appearance,
		char** equipment_list);
Description:

This function is similar to add_custom_appearance(), but adds equipment_list shapes to an existing appearance.

The character types that the new appearance will be available to will match that of the specified existing appearance.

Callable From:

Arguments:

appearance name of the new appearance
existing_appearancename of the existing appearance on which to base new appearance
equipment_list NULL-terminated list of equipment to add to the
existing appearance

Returns:

0 on success, -1 on failure

function diguyScenario::preload_gesture

Prototype:

int preload_gesture(const char* character_type, const char* gesture_name);
Description:

This function preloads all motions for the specified gesture for the specified character type.

This can be done during initialization to preload gestures that will be needed later in a scenario, to avoid a hitch in frame rate when the motions are loaded.

Callable From:

Arguments:

character_type character's type
gesture_name name of the gesture to preload
Returns:

0 on success, -1 on failure

function diguyScenario::print_to_log

Prototype:

void print_to_log(int notify_level, const char* string);
Description:

This function takes the passed string and prints it in the DI-Guy log.

Callable From:

Arguments:

notify_level"importance" of message; 1 means extremely important, 6 means debug output, 3 is a good level to use in general
string the message to be printed

Time Control and Playback Functions

function diguyScenario::get_t

Prototype:

float get_t();
Description:

This function returns the time in seconds that the scenario is currently at.

Callable From:

Returns:

current time in seconds

function diguyScenario::get_tin

Prototype:

float get_tin();
Description:

This function returns the tin time of the scenario. This is the time at which a scenario would prefer to begin.

Returns:

tin of scenario

Callable From:

function diguyScenario::get_tout

Prototype:

float get_tout();
Description:

This function returns the tout time of the scenario. This is the time at which a scenario would prefer to end.

Returns:

tout of scenario

Callable From:

function diguyScenario::get_playback_loop

Prototype:

int get_playback_loop();
Description:

This function returns whether the scenario is designed to loop. If so, when time reaches tout (as returned by get_tout()), it should be set back to tin (as returned by get_tin()).

Returns:

0 if no loop desired; 1 if loop desired

Callable From:

function diguyScenario::update

Prototype:

int update(float t);
Description:

Updates all elements of the loaded scenario to be at time t.

Note that time will not extend beyond the tout of the scenario or before the tin of the scenario. These boundaries are set when a scenario is loaded by the load() function, or can be set manually by calling set_tin() and set_tout().

Callable From:

Arguments:

tdesired time in seconds
Returns:

0 on success, -1 on failure

Performer 2.x Version:

The Performer APP process should call this function once per frame.

function diguyScenario::update2

Prototype:

int update2(float t, float realtime_t);
Description:

Updates all elements of the loaded scenario to be at time t.

Callable From:

Arguments:

t desired simulation time in seconds
realtime_telapsed real time in seconds
Returns:

0 on success, -1 on failure

function diguyScenario::set_tin

Prototype:

int set_tin(float tin);
Description:

This function sets the tin time of the scenario. See get_tin().

Returns:

0 on success, -1 on failure

Callable From:

function diguyScenario::set_tout

Prototype:

int set_tout(float tout);
Description:

This function sets the tout time of the scenario. See get_tout().

Returns:

0 on success, -1 on failure

Callable From:

function diguyScenario::set_playback_loop

Prototype:

int set_playback_loop(int playback_loop);
Description:

This function sets whether the scenario is designed to loop. See get_playback_loop().

Returns:

0 on success, -1 on failure

Callable From:

Query Functions

These functions query the scenario for what specific types of scenario elements are available. This includes:

Example:

int num_character_types = diguy_scenario->get_num_character_types();
int character_type_index;
for (character_type_index = 0;
    character_type_index < num_character_types;
    character_type_index++)
{
    const char* character_type = diguy_scenario->get_character_type_at_index(character_type_index);
    bdi_log_printf(BDI_LOG_INFO, "Character type at index %d: %s\n",
        character_type_index,
        character_type);

    int num_appearances = diguy_scenario->get_character_type_num_appearances(character_type);
    int appearance_index;
    for (appearance_index = 0;
        appearance_index < num_appearances;
        appearance_index++)
    {
        const char* appearance = diguy_scenario->get_character_type_appearance_at_index(character_type,
            appearance_index);
        bdi_log_printf(BDI_LOG_INFO, "\tAppearance at index %d: %s\n",
            appearance_index,
            appearance);
    }

    int num_actions = diguy_scenario->get_character_type_num_actions(character_type);
    int action_index;
    for (action_index = 0;
        action_index < num_actions;
        action_index++)
    {
        const char* action_name = diguy_scenario->get_character_type_action_at_index(character_type,
            action_index);
        bdi_log_printf(BDI_LOG_INFO, "\tAction at index %d: %s\n",
            action_index,
            action_name);
    }
}

function diguyScenario::get_num_character_types

Prototype:

int get_num_character_types();
Returns:

number of available character types

Callable From:

function diguyScenario::get_character_type_at_index

Prototype:

const char* get_character_type_at_index(int index);
Returns:

the string identifying the character type at the given index

Arguments:

indexindex of the character type; indices start at 0
Callable From:

function diguyScenario::get_character_type_abbreviation

Prototype:

const char* get_character_type_abbreviation(const char* character_type);
Returns:

abbreviation of the given character type, when a shorter identifier is needed

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
Callable From:

function diguyScenario::get_character_type_num_appearances

Prototype:

int get_character_type_num_appearances(const char* character_type);
Returns:

number of available appearances for the given character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
Callable From:

function diguyScenario::get_character_type_appearance_at_index

Prototype:

const char* get_character_type_appearance_at_index(const char* character_type,
		int index);
Returns:

the string identifying the appearance at the given index for the specified character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
index index of the appearance; indices start at 0
Callable From:

function diguyScenario::get_character_type_num_actions

Prototype:

int get_character_type_num_actions(const char* character_type);
Returns:

number of available actions for the given character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
Callable From:

function diguyScenario::get_character_type_action_at_index

Prototype:

const char* get_character_type_action_at_index(const char* character_type,
		int index);
Returns:

the string identifying the action at the given index for the specified character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
index index of the action name; indices start at 0
Callable From:

function diguyScenario::get_character_type_action_speed

Prototype:

float get_character_type_action_speed(const char* character_type,
		const char* action_name);
Returns:

the average speed of the specified action for the specified character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
index index of the action name; indices start at 0
Callable From:

function diguyScenario::get_character_type_action_duration

Prototype:

float get_character_type_action_duration(const char* character_type,
		const char* action_name);
Returns:

the duration of one rep of the specified action for the specified character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
index index of the action name; indices start at 0
Callable From:

function diguyScenario::get_character_type_action_distance

Prototype:

float get_character_type_action_distance(const char* character_type,
		const char* action_name);
Returns:

the distance covered by one rep of the specified action for the specified character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
index index of the action name; indices start at 0
Callable From:

function diguyScenario::get_character_type_action_direction

Prototype:

const char* get_character_type_action_direction(const char* character_type,
		const char* action_name);
Returns:

the string identifying the direction of travel of the specified action for the specified character type

Arguments:

character_typecharacter type name, as returned by get_character_type_at_index(), for example
index index of the action name; indices start at 0
Callable From:

Character Functions

function diguyScenario::get_num_characters

Prototype:

int get_num_characters();
Returns:

number of characters in the scenario

Callable From:

function diguyScenario::get_character_at_index

Prototype:

diguyCharacter* get_character_at_index(int index);
Returns:

pointer of type diguyCharacter; NULL if no character at the specified index

Arguments:

indexindex of the character; indices start at 0
Callable From:

function diguyScenario::find_character

Prototype:

diguyCharacter* find_character(const char* name);
Description:

This function returns a pointer to the specified character.

Callable From:

Arguments:

name name of character to be found
Returns:

pointer of type diguyCharacter; NULL if not found

function diguyScenario::this_character

Prototype:

diguyCharacter* this_character();
Description:

This function returns a pointer to the target character of an event bead.

Callable From:

Returns:

pointer of type diguyCharacter; NULL if no current character

function diguyScenario::this_event_bead

Prototype:

diguyCharacterPathEvent* this_event_bead();
Description:

This function returns a pointer to the current event bead.

Callable From:

Returns:

pointer of type diguyCharacterPathEvent; NULL if no current event bead

function diguyScenario::set_iguy_character

Prototype:

void set_iguy_character(const char* name);
Description:

This function sets the interactive character (I-Guy). A session can have at most one interactive guy at a time.

Callable From:

Arguments:

name name of character to become I-Guy

function diguyScenario::create_character

Prototype:

diguyCharacter* create_character(const char* name,
		const char* character_type,
		const char* appearance = NULL);
Description:

This function creates a new character and returns a pointer to it.

The function preload_character_type() should be called at the beginning of a scenario in which this call will be made to avoid a hitch in frame rate.

Callable From:

API Level 2

Arguments:

name name of the new character
character_type character's type
appearance base appearance of character; pass NULL to use default appearance
Returns:

pointer of type diguyCharacter; NULL if not found

function diguyScenario::destroy_character

Prototype:

int destroy_character(diguyCharacter* character);
Description:

This function destroys a character.

Callable From:

API Level 2

Arguments:

characterpointer to a diguyCharacter
Returns:

0 on success, -1 on failure

Path Shape Functions

function diguyScenario::get_num_path_shapes

Prototype:

int get_num_path_shapes();
Returns:

number of path shapes in the scenario

Callable From:

function diguyScenario::get_path_shape_at_index

Prototype:

diguyPathShape* get_path_shape_at_index(int index);
Returns:

pointer of type diguyPathShape; NULL if no path shape at the specified index

Arguments:

indexindex of the path shape; indices start at 0
Callable From:

function diguyScenario::find_path_shape

Prototype:

diguyPathShape* find_path_shape(const char* name);
Description:

This function returns a pointer to the specified path shape.

Callable From:

Arguments:

name name of path shape to be found
Returns:

pointer of type diguyPathShape; NULL if not found

function diguyScenario::create_path_shape

Prototype:

diguyPathShape* create_path_shape(const char* name);
Description:

This function creates a new path shape and returns a pointer to it.

Callable From:

API Level 2

Arguments:

name name of the new path shape
Returns:

pointer of type diguyPathShape; NULL if not found

function diguyScenario::destroy_path_shape

Prototype:

int destroy_path_shape(diguyPathShape* path_shape);
Description:

This function destroys a path shape.

Callable From:

API Level 2

Arguments:

path_shapepointer to a diguyPathShape
Returns:

0 on success, -1 on failure

Waypoint Functions

function diguyScenario::create_waypoint

Prototype:

diguyWaypoint* create_waypoint(float x = 0.0f, float y = 0.0f, float z = 0.0f,
		float yaw = 0.0f, float roll = 0.0f, float pitch = 0.0f,
		float weight = 1.0f);
Description:

This function creates a new waypoint that can be used for creating new paths and path shapes.

The returned pointer must be destroyed using destroy_waypoint(). The scenario keeps no record of waypoints created with this function.

Callable From:

API Level 2

Arguments:

tx, ty, tzposition in meters from the origin
rz, rx, ryorientations in degrees counter-clockwise
from the positive X axis

weight how much influence this waypoint exerts
over the path curve

Returns:

pointer to type diguyWaypoint

function diguyScenario::destroy_waypoint

Prototype:

int destroy_waypoint(diguyWaypoint* waypoint);
Description:

This function destroys a waypoint created by create_waypoint(). Path shapes created using this waypoint will not be affected; they make internal copies of the waypoint.

Callable From:

API Level 2

Arguments:

waypointwaypoint to destroy
Returns:

0 on success, -1 on failure

Signal Functions

function diguyScenario::get_num_signals

Prototype:

int get_num_signals();
Returns:

number of signals in the scenario

Callable From:

function diguyScenario::get_signal_at_index

Prototype:

diguySignal* get_signal_at_index(int index);
Returns:

pointer of type diguySignal; NULL if no signal at the specified index

Arguments:

indexindex of the signal; indices start at 0
Callable From:

function diguyScenario::find_signal

Prototype:

diguySignal* find_signal(const char* name);
Description:

This function returns a pointer to the specified signal.

Callable From:

Arguments:

name name of signal to be found
Returns:

pointer of type diguySignal; NULL if not found

function diguyScenario::create_signal

Prototype:

diguySignal* create_signal(const char* name);
Description:

This function creates a new signal and returns a pointer to it.

Callable From:

API Level 2

Arguments:

namename of the new signal
Returns:

pointer of type diguySignal

function diguyScenario::destroy_signal

Prototype:

int destroy_signal(diguySignal* signal);
Description:

This function destroys a signal.

Callable From:

API Level 2

Arguments:

signalpointer to a diguySignal
Returns:

0 on success, -1 on failure

function diguyScenario::reset_signals

Prototype:

void reset_signals();
Description:

This function resets all signals in the scenario.

Callable From:

Sound Functions

Note that sounds are not played directly. Instead they are used as templates for sound instances. See diguyCharacter::play_sound() and diguyCharacter::create_sound_instance().

function diguyScenario::get_num_sounds

Prototype:

int get_num_sounds();
Returns:

number of sounds in the scenario

Callable From:

function diguyScenario::get_sound_at_index

Prototype:

diguySound* get_sound_at_index(int index);
Returns:

pointer of type diguySound; NULL if no sound at the specified index

Arguments:

indexindex of the sound; indices start at 0
Callable From:

function diguyScenario::find_sound

Prototype:

diguySound* find_sound(const char* name);
Description:

This function returns a pointer to the specified sound.

Callable From:

Arguments:

name name of sound to be found
Returns:

pointer of type diguySound; NULL if not found

function diguyScenario::create_sound

Prototype:

diguySound* create_sound(const char* name);
Description:

This function creates a new sound and returns a pointer to it.

Note that sounds are not played directly. Instead they are used as templates for sound instances. See diguyCharacter::play_sound() and diguyCharacter::create_sound_instance().

Callable From:

API Level 2

Arguments:

namename of the new sound
Returns:

pointer of type diguySound

function diguyScenario::destroy_sound

Prototype:

int destroy_sound(diguySound* sound);
Description:

This function destroys a sound.

Callable From:

API Level 2

Arguments:

characterpointer to a diguySound
Returns:

0 on success, -1 on failure

function diguyScenario::stop_all_sounds

Prototype:

int stop_all_sounds();
Description:

This function stops all sounds playing within the scenario.

Returns:

0 on success, -1 on failure

Group Function