diguyView.h

Go to the documentation of this file.

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

/*********************************************************************
 **
 *t  diguyView
 **
 *b    Link against: libdiguy
 */

#ifndef __diguyView_H
#define __diguyView_H

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

#ifdef CPLUSPLUS_ONLY

class bdiScenarioView;
class diguyView;
class diguyViewCamera;
class diguyViewFog;
class diguyViewLight;

#include <stdio.h> // for NULL
#include <diguy_constants.h>
#include <diguy_typedefs.h>


#endif /* CPLUSPLUS_ONLY */


#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyView
{

public:

        /*l
         *b  Description:
         **
         **    Returns the name of the object.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    name of the view
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_name();

        /*l
         *b  Description:
         **
         **    Returns the type name of the object.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    type name of the object
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_type_name();

        /*l
         *b  Description:
         **
         **    Shows the view.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int show();

        /*l
         *b  Description:
         **
         **    Hides the view.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int hide();

        /*l
         *b  Returns:
         **
         **    Returns 1 if the view is showing, 0 if not.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int is_showing();

        /*l
         *b  Description:
         **
         **    Returns the window title of the view.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    window title of the view
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_window_title();

        /*l
         *b  Description:
         **
         **    This function sets the window title of the view.
         **
         *b  Arguments:
         **
         *a    window_title - new window title
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_window_title(const char* window_title);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the view camera.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         **
         *b  Returns:
         **
         **    pointer of type diguyViewCamera; should never be NULL
         */
        diguyViewCamera* get_camera();

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the view fog.
         **
         *b  Returns:
         **
         **    pointer of type diguyViewFog; should never be NULL
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyViewFog* get_fog();

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the view lights.
         **
         *b  Arguments:
         **
         *a    number    - number of light to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyViewLight; can be NULL if light at
         **    specified index doesn't exist
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyViewLight* get_light(int number = 0);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Sets the width of the view, in pixels.
         **
         *b  Arguments:
         **
         *a    width - new width of view, in pixels
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_width(int width);

        /*l
         *b  Returns:
         **
         **    width in pixels of the view
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_width();

        /*l
         *b  Description:
         **
         **    Sets the height of the view, in pixels.  Increasing height value
         **    moves the view window bottom edge lower.
         **
         *b  Arguments:
         **
         *a    width - new height of view, in pixels
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_height(int height);

        /*l
         *b  Returns:
         **
         **    height in pixels of the view
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_height();

        /*l
         *b  Description:
         **
         **    Sets the current x position of the view window relative to the
         **    left-hand edge of the screen.
         **
         *b  Arguments:
         **
         *a    x - new x coordinate of view
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_x(int x);

        /*l
         *b  Returns:
         **
         **    current x coordinate of the view window; see set_x()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_x();

        /*l
         *b  Description:
         **
         **    Sets the current y position of the view window relative to the
         **    upper edge of the screen.  Increasing y moves the view window
         **    lower.
         **
         *b  Arguments:
         **
         *a    y - new y coordinate of view
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_y(int y);

        /*l
         *b  Returns:
         **
         **    current y coordinate of the view window; see set_y()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_y();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This is an enumeration of the different callbacks
         **    that can be registered with add_callback() and
         **    add_callback_script().
         **
         *b  Usable From:
         **
         *-    - C++
         *-    - Script
         */
        enum {
                CALLBACK_ID_SHOW = 1,
                CALLBACK_ID_HIDE,
                CALLBACK_ID_WINDOW_TITLE_CHANGED,
                CALLBACK_ID_WINDOW_GEOMETRY_CHANGED
        };

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function adds a user callback.
         **
         *b  Arguments:
         **
         *a    callback        - pointer to function with prototype
         *a                      diguyViewCallback (typedefed above)
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback_params - not currently used; pass NULL
         *a    callback_user_data - pointer for user's own use; DI-Guy will
         *a                         do nothing to the contents of this pointer
         *a                         beyond passing it back when the callback is
         *a                         invoked
         **
         **    callback_id should be one of the following values:
         **
         *i    CALLBACK_ID_SHOW
         **
         **      This callback will be called whenever the view is
         **      to be shown, whether due to a call to the diguyView::show()
         **      function above or due to the result of a decision
         **      or script.
         **
         **      There are no parameters for this callback.
         **
         *i    CALLBACK_ID_HIDE
         **
         **      This callback will be called whenever the view is
         **      to be hidden, whether due to a call to the diguyView::hide()
         **      function above or due to the result of a decision
         **      or script.
         **
         **      There are no parameters for this callback.
         **
         *i    CALLBACK_ID_WINDOW_TITLE_CHANGED
         **
         **      This callback will be called whenever the view's
         **      window title has been changed.
         **
         **      There are no parameters for this callback.
         **
         *i    Callback Return Values:
         **
         **    Callbacks return a value of type diguyCallbackReturn,
         **    which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE.
         **    If the callback returns DIGUY_CALLBACK_STOP, the default handler
         **    of the function will not be called; the callback is asserting
         **    that it has done everything necessary for the function call.
         **    If the callback returns DIGUY_CALLBACK_CONTINUE, the default
         **    handler for the function will be called after the callback.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int add_callback(int callback_id,
                diguyViewCallback* callback,
                void* callback_params = 0,
                void* callback_user_data = 0);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback function will be removed.
         **
         *b  Arguments:
         **
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback        - pointer to function with prototype
         *a                      diguyCharacterCallback (typedefed above)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback(int callback_id,
                diguyViewCallback* callback);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback_user_data pointer will
         **    be removed.
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of when this callback is to be called
         *a    callback_user_data - pointer for user's own use
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback_with_user_data(int callback_id,
                void* callback_user_data);

#endif /* CPLUSPLUS_ONLY */

        /*l
         *b  Description:
         **
         **    This function adds a user callback script.  Callback scripts can
         **    be removed with remove_callback_script().
         **
         **    See diguyCharacter::add_callback_script() for an example
         **    of use.
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback to be added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  Lua specific:
         **
         **    When the script is called, the object for which it is being called
         **    will be in the callback_object global.
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);

        /*l
         *b  Description:
         **
         **    This function removes a user callback script previously added with
         **    add_callback_script().
         **
         **    See diguyCharacter::remove_callback_script() for an example
         **    of use.
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback previously added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script, all callback
         **    scripts whose ids match callback_id and whose types match
         **    callback_script_type will be removed.
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  Lua specific:
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int remove_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);


#ifdef CPLUSPLUS_ONLY

        bdiScenarioView* get_scripted_object() {return m_scripted_object;}

private:

        /*l
         **    A private constructor.
         */
        diguyView(bdiScenarioView* view);

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

        friend class bdiScenarioView;

#endif /* CPLUSPLUS_ONLY */

};

#endif /* __diguyView_H */