diguy_api.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2014 VT MAK
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************
 **
 *t  DI-Guy API, Main Header File
 **
 **    The API is subject to change in future releases.
 **
 *b    Link against: libdiguy
 */

#ifndef __diguy_api_H
#define __diguy_api_H

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

#ifdef CPLUSPLUS_ONLY

#include <diguy_constants.h>

class diguyApp;
#include "diguy_typedefs.h" // needed for diguyScenarioCallback

#include <declspec_diguy.h>

#endif

#ifdef __cplusplus
extern "C" {
#endif


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

/*l
 *b  Description:
 **
 **    This function sets the filename of the top-level configuration file
 **    that will be read by the DI-Guy software.  The default is "diguy.cfg".
 **
 **    This function must be called before diguy_initialize_[platform]().
 **
 **    It should rarely be necessary to use this function.
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Arguments:
 **
 *a    cfg_file - filename of desired configuration file
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  C++ Example:
 **
 *e #include <diguy_graphics_ogl.h>
 *e
 *e     diguy_set_cfg_file("custom.cfg");
 *e     diguy_ogl_initialize(NULL);
 */
BDI_DECLSPEC_diguy
int diguy_set_cfg_file(const char* cfg_file);

/*l
 *b  Description:
 **
 **    This function sets the base directory in which to search for DI-Guy
 **    files.
 **
 **    This function must be called before diguy_initialize_[platform]().
 **
 **    It should rarely be necessary to use this function.  In typical use,
 **    this directory will be read from the DIGUY environment variable.
 **
 **    Calling this function will override the directory specified in the
 **    DIGUY environment variable.
 **
 **    The base directory can be retrieved by using the function
 **    diguyApp::get_diguy_base_dir_path().
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Arguments:
 **
 *a    directory_name - override directory in which to search for DI-Guy files
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  C++ Example:
 **
 *e #include <diguy_graphics_ogl.h>
 *e
 *e     diguy_set_diguy_base_dir_path("c:/DI-Guy_alternate_directory");
 *e     diguy_ogl_initialize(NULL);
 */
BDI_DECLSPEC_diguy
int diguy_set_diguy_base_dir_path(const char* directory_name);

/*l
 *b  Description:
 **
 **    This function shuts down the DI-Guy software, removing all characters
 **    and cleaning up memory allocated by the library.  No objects created
 **    by the DI-Guy software should be referenced after this call is made.
 **
 *i    This function should only be called once per program execution.
 *i    Do not try to re-initialize the DI-Guy software after calling
 *i    this function.
 **
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  C++ Example:
 **
 *e     diguy_deinitialize();
 */
BDI_DECLSPEC_diguy
int diguy_deinitialize();

#endif


/*****************************************************************************/
/*l
 *b  Description:
 **
 **    This function returns a pointer to the DI-Guy application object.
 **    Only one application object exists per DI-Guy run.  The application
 **    object is created during DI-Guy initialize calls; e.g.
 **    diguy_ogl_initialize().
 **
 *b  Returns:
 **
 **    a pointer of type diguyApp
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  C++ Example:
 **
 *e     diguyApp* app = diguy_get_app();
 **
 */
BDI_DECLSPEC_diguy
diguyApp* diguy_get_app();

/*l
 **  Description:
 **
 **    This function allocates and returns an empty object of type
 **    diguyScenario.  This is the top-level "container" of most
 **    DI-Guy types, and includes objects of type diguyCharacter,
 **    diguyViewCamera, diguySceneObject, and diguySignal.
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Returns:
 **
 **    Pointer to object of type diguyScenario if successful;
 **    NULL if not.
 **
 *b  C++ Example:
 **
 *e     diguyScenario* sc = diguy_create_scenario();
 *e     if (sc)
 *e     {
 *e             sc->load("my_scenario.dss");
 *e     }
 **
 */
BDI_DECLSPEC_diguy
diguyScenario* diguy_create_scenario();

/*l
 **  Description:
 **
 **    This function destroys an object of type diguyScenario allocated
 **    by diguy_create_scenario().
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  C++ Example:
 **
 *e     diguyScenario* sc = diguy_create_scenario();
 *e     // ...
 *e     diguy_destroy_scenario(sc);
 **
 */
BDI_DECLSPEC_diguy
int diguy_destroy_scenario(diguyScenario* scenario);



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

/*l
 *b  Description:
 **
 **    This utility function changes the order of Euler angle triples.
 **    DI-Guy uses the order ZXY for all 3D rotations.
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_convert_euler_angle_order(float src_rx,
        float src_ry,
        float src_rz,
        diguyEulerAngleOrder src_order,
        float* dest_rx,
        float* dest_ry,
        float* dest_rz,
        diguyEulerAngleOrder dest_order);

/*l
 *b  Description:
 **
 **    This utility function converts a DI-Guy ZXY Euler angle triple
 **    into a quaternion.
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_convert_euler_angles_to_quaternion(const float* euler_angle_ptr,
        float* quat_ptr);

/*l
 *b  Description:
 **
 **    To be written.
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_extract_translation_and_euler_angles_from_matrix(float mat[4][4],
        float* translation,
        float* euler_angles,
        diguyEulerAngleOrder euler_angle_order);

/*l
 *b  Description:
 **
 **    To be written.
 **
 *b  Callable From:
 **
 *-    - C++
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_create_matrix_from_translation_and_euler_angles(float mat[4][4],
        float translation[3],
        float euler_angles[3],
        diguyEulerAngleOrder euler_angle_order);

#endif

#ifdef __cplusplus
}
#endif

#endif /* __diguy_api_H */


/*********************************************************************
 ** Copyright (c) 1992-2014 VT MAK
 ** All rights reserved. 
 *********************************************************************/