diguyIGuyController.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************
 **
 *t  diguyIGuyController
 **
 */

#ifndef __diguyIGuyController_H
#define __diguyIGuyController_H

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

#ifdef CPLUSPLUS_ONLY

#include <declspec_diguy.h>
#include <diguyMotionPosture.h>
#include <diguyMotionVariant.h>

class bdiScenarioIGuy;
class diguyCharacter;

#endif


/****************************************************************************/
class BDI_DECLSPEC_diguy diguyIGuyController
{

public:

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the interactive character (I-Guy).
         **
         **    The I-Guy character's actions, position, and orientation
         **    can be 'driven' by input from the mouse, keyboard, or
         **    a joystick.
         **
         **    There can be at most one I-Guy at a time.
         **
         *b  Arguments:
         **
         *a    name            - name of character to become I-Guy
         *a    initial_posture - this argument is not currently used,
         *a                      but will be implemented in a future
         *a                      version of DI-Guy
         *a    initial_variant - the initial motion variant the
         *a                      I-Guy character should assume
         **
         **    Passing DIGUY_MOTION_VARIANT_ANY as the initial
         **    variant will cause DI-Guy to select a default initial
         **    variant.  Passing DIGUY_MOTION_VARIANT_NORMAL will
         **    cause the character to start in a non-aiming action.
         **    Passing DIGUY_MOTION_VARIANT_AIM will cause the
         **    character to start in an aiming action, if available.
         **    Other variants will be supported in a future version.
         */
        void set_iguy_character(const char* name,
                diguyMotionPosture initial_posture = DIGUY_MOTION_POSTURE_ANY,
                diguyMotionVariant initial_variant = DIGUY_MOTION_VARIANT_ANY);

        /*l
         *b  Returns:
         **
         **    pointer of type diguyCharacter* to the current I-Guy character
         */
        diguyCharacter* get_iguy_character();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns the character clicked on when in I-Guy
         **    Input Mode.  The pointer is valid during
         **    CALLBACK_ID_IGUY_INTERACT_WITH_SUBJECT callbacks.
         **
         *b  Returns:
         **
         **    pointer to type diguyCharacter; NULL if there is no interaction
         **    subject
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_interaction_subject();



/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller should update
         **    the primary view's camera to keep the I-Guy in view.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable camera changes, 0 to disable
         */
        void set_camera_change_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if I-Guy affects camera, 0 if not
         */
        int get_camera_change_enabled();

        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controlled camera should be
         **    1st person (from-the-eyes view), or 3rd person (over the shoulder).
         **
         *b  Arguments:
         **
         *a    flag - pass 1 for 1st person, 0 for 3rd
         */
        void set_camera_use_1st_person_flag(int flag);

        /*l
         *b  Returns:
         **
         **    1 if I-Guy controlled camera is 1st person, 0 if 3rd
         */
        int get_camera_use_1st_person_flag();

        /*l
         *b  Description:
         **
         **    This function sets which link the I-Guy controlled camera will
         **    be attached to.  For human characters, the best link is typically
         **    "cervical" (the neck), or NULL (to use the base position of the
         **    character).  The default is "cervical".
         **
         **    This setting affects both 1st person and 3rd person cameras.
         **
         *b  Arguments:
         **
         *a    attachment_link - name of the link to attach to
         **
         **    Pass NULL to have the camera be attached to the I-Guy character's
         **    base position.
         */
        void set_camera_attachment_link(const char* attachment_link);

        /*l
         *b  Returns:
         **
         **    the name of the current camera attachment link, or the empty
         **    string ("") if there is none
         */
        const char* get_camera_attachment_link();

        /*l
         *b  Description:
         **
         **    This function sets the offset that is used from the attachment
         **    link's position for the 3rd person camera's position.
         **
         **    Typically this has a slightly negative x value, to move the
         **    camera behind the I-Guy character, and a positive z value, to
         **    move the camera up so it can see over the character's head.
         **
         **    The default is x=-2.0, y=0.0f, z=0.35.
         **
         **    This setting affects only 3rd person cameras.
         **
         *b  Arguments:
         **
         *a    x, y, z - offset of camera position from attachment link
         */
        void set_camera_3rd_person_look_from_offset(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    This function retrieves the offset that is used from the
         **    attachment link's position for the 3rd person camera's position.
         **    The offset values should be put into the variables pointed to.
         **
         *b  Arguments:
         **
         *a    x, y, z - pointers to variables in which offset should be
         *a              returned
         */
        void get_camera_3rd_person_look_from_offset(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    This function is similar to
         **    set_camera_3rd_person_look_from_offset(), but affects the look-at
         **    point instead.
         **
         **    The default is x=0.0, y=0.0, z=0.3.
         **
         *b  Arguments:
         **
         *a    x, y, z - offset of camera look-at point from attachment link
         */
        void set_camera_3rd_person_look_at_offset(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    This function is similar to
         **    get_camera_3rd_person_look_from_offset(), but affects the look-at
         **    point instead.
         **
         *b  Arguments:
         **
         *a    x, y, z - pointers to variables in which offset should be
         *a              returned
         */
        void get_camera_3rd_person_look_at_offset(float* x, float* y, float* z);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether mouse input will affect the I-Guy
         **    character.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable mouse input, 0 to disable
         */
        void set_mouse_input_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if mouse input is enabled, 0 if not
         */
        int get_mouse_input_enabled();

        /*l
         *b  Description:
         **
         **    This function sets whether mouse input should be "captured".
         **
         **    A captured mouse's cursor doesn't move, but stays in the middle of
         **    the view.  This mode is common in first-person shooter (FPS) style
         **    games.
         **
         **    A non-captured mouse's cursor is free to move anywhere on the
         **    screen.
         **
         **    The setting only has an effect in DI-Guy Scenario.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable input capture, 0 to disable
         */
        void set_input_capture_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if input is captured, 0 if not
         */
        int get_input_capture_enabled();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether keyboard input will affect the I-Guy
         **    character.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable keyboard input, 0 to disable
         */
        void set_keyboard_input_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if keyboard input is enabled, 0 if not
         */
        int get_keyboard_input_enabled();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether joystick input will affect the I-Guy
         **    character.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable joystick input, 0 to disable
         */
        void set_joystick_input_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if joystick input is enabled, 0 if not
         */
        int get_joystick_input_enabled();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller can affect the
         **    posture of the character.
         **
         **    The default is 1, posture change enabled.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable posture changes, 0 to disable
         */
        void set_posture_change_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if posture changes enabled, 0 if not
         */
        int get_posture_change_enabled();

        /*l
         *b  Description:
         **
         **    This function sets the desired posture of the I-Guy character.
         **
         **    Note that the character may not be able to maintain this posture.
         **    For example, if the desired posture is prone but the character type
         **    has no moving prone actions, a crouched action may be used for
         **    moving instead.
         **
         **    This function will have no effect if posture changes are disabled,
         **    as set by set_posture_change_enabled().
         **
         *b  Arguments:
         **
         *a    posture - desired posture
         */
        void set_posture(diguyMotionPosture posture);

        /*l
         *b  Returns:
         **
         **    the desired posture of the I-Guy character
         */
        diguyMotionPosture get_posture();

        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller can affect the
         **    variant of the character.
         **
         **    The default is 1, variant change enabled.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable variant changes, 0 to disable
         */
        void set_variant_change_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if variant changes enabled, 0 if not
         */
        int get_variant_change_enabled();

        /*l
         *b  Description:
         **
         **    This function sets the desired variant of the I-Guy character.
         **
         **    This function will have no effect if variant changes are disabled,
         **    as set by set_variant_change_enabled().
         **
         **    Most often the variant of an I-Guy character should be one of:
         **
         *-    - DIGUY_MOTION_VARIANT_NORMAL
         *-    - DIGUY_MOTION_VARIANT_AIM
         **
         *b  Arguments:
         **
         *a    variant - desired variant
         */
        void set_variant(diguyMotionVariant variant);

        /*l
         *b  Returns:
         **
         **    the desired variant of the I-Guy character
         */
        diguyMotionVariant get_variant();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller can affect the gaze
         **    state of the character.
         **
         **    The default is 1, gaze change enabled.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable gaze changes, 0 to disable
         */
        void set_gaze_change_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if gaze changes enabled, 0 if not
         */
        int get_gaze_change_enabled();

        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller can affect the
         **    orientation of the character.
         **
         **    The default is 1, orientation change enabled.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable orientation changes, 0 to disable
         */
        void set_orientation_change_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if gaze orientation enabled, 0 if not
         */
        int get_orientation_change_enabled();

        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller can affect the
         **    position of the character.
         **
         **    The default is 1, position change enabled.
         **
         *b  Arguments:
         **
         *a    enabled - pass 1 to enable position changes, 0 to disable
         */
        void set_position_change_enabled(int enabled);

        /*l
         *b  Returns:
         **
         **    1 if position changes enabled, 0 if not
         */
        int get_position_change_enabled();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller will change the
         **    controlled character's action abruptly or allow action changes to
         **    take place smoothly.
         **
         **    Forced action changes provide better responsiveness, but don't
         **    look as nice.
         **
         **    See the functions diguyCharacter::force_action() and
         **    diguyCharacter::set_desired_action().
         **
         **    The set_skip_transitions_flag() also has an effect on
         **    responsiveness and how nice the action transitions look.
         **
         **    The default is 1, force actions.
         **
         *b  Arguments:
         **
         *a    use_force_action_flag - pass 1 to force quick action changes,
         *a                            0 to smooth action changes
         */
        void set_use_force_action_flag(int use_force_action_flag);

        /*l
         *b  Returns:
         **
         **    whether actions are forced (returns 1) or not (returns 0)
         */
        int get_use_force_action_flag();

        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy controller will, when new
         **    actions are forced, the transition motions from the current
         **    to the new action are skipped.
         **
         **    Skipping transitions provides better responsiveness, but doesn't
         **    look as nice.
         **
         **    This setting only has an effect if the force action flag is set
         **    to 1 (see set_use_force_action_flag()).
         **
         **    The default is 1, skip transitions.
         **
         *b  Arguments:
         **
         *a    skip_transitions_flag - pass 1 to skip transition motions,
         *a                            0 to play them
         */
        void set_skip_transitions_flag(int skip_transitions_flag);

        /*l
         *b  Returns:
         **
         **    whether transitions between actions are skipped (returns 1) or
         **    not (returns 0)
         */
        int get_skip_transitions_flag();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets whether the I-Guy character will always try
         **    to run, or move at its top speed.
         **
         **    The default is 0, don't always run.
         **
         *b  Arguments:
         **
         *a    always_run_flag - pass 1 to always run, 0 to be able to walk
         *a                      and/or jog when moving slower
         */
        void set_always_run_flag(int always_run_flag);

        /*l
         *b  Returns:
         **
         **    whether the I-Guy character will always try to run (returns 1),
         **    or not (returns 0)
         */
        int get_always_run_flag();


        /*l
         *b  Returns:
         **
         **    whether the I-Guy character is currently bumping into something in the world limiting its motion.
         */
        int get_is_colliding();

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns the current azimiuth (left/right) facing
         **    angle of the I-Guy character.  This value will change as the
         **    character is moved around by the I-Guy controller.
         **
         *b  Returns:
         **
         **    current rz facing angle, in degrees
         */
        float get_face_rz();

        /*l
         *b  Description:
         **
         **    This function returns the current elevation (down/up) facing
         **    angle of the I-Guy character.  This value will change as the
         **    character is moved around by the I-Guy controller.
         **
         *b  Returns:
         **
         **    current ry facing angle, in degrees
         */
        float get_face_ry();

        /*l
         *b  Description:
         **
         **    This function sets the desired azimiuth (left/right) facing
         **    angle of the I-Guy character.
         **
         **    Most often this value is changed via mouse, keyboard, or joystick
         **    input, not by this function.
         */
        void set_face_rz_desired(float face_rz_desired);

        /*l
         *b  Returns:
         **
         **    desired rz facing angle, in degrees
         */
        float get_face_rz_desired();

        /*l
         *b  Description:
         **
         **    This function sets the desired elevation (down/up) facing
         **    angle of the I-Guy character.
         **
         **    Most often this value is changed via mouse, keyboard, or joystick
         **    input, not by this function.
         */
        void set_face_ry_desired(float face_ry_desired);

        /*l
         *b  Returns:
         **
         **    desired ry facing angle, in degrees
         */
        float get_face_ry_desired();

        /*l
         *b  Description:
         **
         **    This function sets the desired rz and ry facing angles of the
         **    I-Guy controlled character toward the specified character.
         */
        void face_character(const char* character_name,
                const char* link,
                float offset_rz = 0.0f,
                float offset_ry = 0.0f);




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

        /*l
         **  Deprecated; use set_orientation_change_enabled() instead.
         */
        void set_mouse_look_changes_orientation(int val);

        /*l
         **  Deprecated; use get_orientation_change_enabled() instead.
         */
        int get_mouse_look_changes_orientation();


#ifdef CPLUSPLUS_ONLY

        bdiScenarioIGuy* get_scripted_object() {return m_scripted_object;}

private:

        /*l
         **  A private constructor.
         */
        diguyIGuyController(bdiScenarioIGuy* iguy);

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

        friend class bdiScenarioIGuy;

#endif

};

#endif /* __diguyIGuyController_H */