diguyLoadManager.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  diguyLoadManager
 **
 *b    Link against: libdiguy
 */

#ifndef __diguyLoadManager_H
#define __diguyLoadManager_H

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

#ifdef CPLUSPLUS_ONLY
class bdiScenarioCharacterLoadManager;
class diguyViewCamera;
#endif

#include <declspec_diguy.h>


/****************************************************************************/
class BDI_DECLSPEC_diguy diguyLoadManager
{

/*****************************************************************************
 **
 **    The DI-Guy Load Manager is responsible for adjusting each
 **    character's motion level of detail, as well as various update rates,
 **    depending on where the character's are in relation to cameras.
 */

public:

        /*l
         *b  Description:
         **
         **    This is the top-level on/off switch for this load manager.
         **    By default, load managers are disabled.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_enabled(int enabled);

        /*l
         *b  Description:
         **
         **    Returns whether this load manager is enabled, as set by the
         **    set_enabled() call.
         **
         *b  Returns:
         **
         **    1 if this load manager is enabled, 0 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_enabled();

        /*l
         *b  Description:
         **
         **    Sets the minimum full update period to be used for all characters.
         **    This potentially overrides the update rates otherwise set for
         **    the character.
         **
         **    For example, if a character's position update rate were so low
         **    that it would not be updated within this minimum update period,
         **    it would be forced to update.
         **
         **    The default minimum update period is 0.5 seconds.
         **
         *b  Arguments:
         **
         *a    period - the minimum update period, in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         **/
        int set_minimum_full_update_period(float period);

        /*l
         *b  Returns:
         **
         **    load manager's minimum full update period as set by
         **    set_minimum_full_update_period()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        float get_minimum_full_update_period();

        /*l
         *b  Description:
         **
         **    This function sets the far extents of load manager zone bounding
         **    planes, in terms of their distance from the camera.  Zone 0 is
         **    between the camera near clipping plane and bounding plane 0.
         **    Zone 1 is between bounding plane 0 and bounding plane 1.  Zone
         **    2 is between bounding plane 1 and the camera far clipping
         **    plane.
         **
         **    The defaults for the zone bounds should work reasonably well
         **    in most cases, but some tweaking may be required in some cases.
         **
         **    Defaults:
         *>
         *-      - zone 0:  10 meters
         *-      - zone 1:  20 meters
         *-      - zone 2:  (camera far plane; cannot be set by this function)
         *<
         *b  Arguments:
         **
         *a    zone       - zone to modify
         *a    far_extent - new far extent of zone
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_far_extent(int zone, float far_extent);

        /*l
         *b  Returns:
         **
         **    far extent of zone as set by set_zone_far_extent(),
         **    -1.0 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        float get_zone_far_extent(int zone);
        /*l
         *b  Description:
         **
         **    This function sets whether view and camera settings such as
         **    field-of-view (FOV) and window size should be taken into account
         **    when determining the zone of a character.
         **
         **    The base zone extents are distance-based, but this approach can
         **    be problematic if the current camera's FOV is very narrow; a
         **    narrow FOV essentially acts like a telephoto lens.  In this case
         **    a character that is far away, and would therefore be rendered
         **    at low resolution, can actually be quite large in the 3D view.
         **
         **    Setting this flag to 1 will cause the FOV to be taken into account
         **    when calculating effective zone extents.
         **
         **    In general zone extents assume that the vertical FOV of the
         **    view is around 40.  Smaller FOVs will scale the thresholds larger
         **    so that zone changes happen further out.  Likewise larger FOVs
         **    will scale the extents smaller; in this case even nearby
         **    characters will appear small and therefore need less resolution.
         **
         *b  Arguments:
         **
         **    do_scale   - pass 1 to enable scaling, 0 to disable
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_scale_zone_extents_from_view_settings(int do_scale);

        /*l
         *b  Returns:
         **
         **    most recent setting of
         **    set_scale_zone_extents_from_view_settings()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int  get_scale_zone_extents_from_view_settings();

        /*l
         *b  Description:
         **
         **    This function set the position update rate for the given zone.
         **
         **    The position update rate is the percentage of frames in
         **    which the overall position of the character will be updated.
         **    Passing 100 will cause character positions to be updated every
         **    frame; passing 50 will cause character positions to be updated
         **    every other frame.
         **
         **    Defaults:
         *>
         *-      - zone 0:  100
         *-      - zone 1:  100
         *-      - zone 2:  100
         *<
         *b  Arguments:
         **
         *a    zone                 - zone to modify
         *a    position_update_rate - new position update rate
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         **
         *b  C++ Example:
         **
         *e    set_zone_position_update_rate(0, 100);
         *e    set_zone_position_update_rate(1, 80);
         *e    set_zone_position_update_rate(2, 50);
         **
         **    In this example characters in zone 0 will have their positions
         **    updated every frame (100%).  Characters in zone 1 will have
         **    their positions updated every four out of five frames (80%).
         **    Characters in zone 2 will have their positions updated every other
         **    frame (50%).
         */
        int set_zone_position_update_rate(int zone, int position_update_rate);

        /*l
         *b  Returns:
         **
         **    position update rate of zone as set by
         **    set_zone_position_update_rate();
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_position_update_rate(int zone);

        /*l
         *b  Description:
         **
         **    This function set the altitude update rate for the given zone.
         **
         **    The position update rate is the percentage of frames in
         **    which the altitude, or Z position, of the character will be
         **    updated.
         **
         **    Passing 100 will cause character altitudes to be updated every
         **    frame; passing 50 will cause character altitudes to be updated
         **    every other frame.
         **
         **    Defaults:
         *>
         *-      - zone 0:  100
         *-      - zone 1:  100
         *-      - zone 2:  100
         *<
         *b  Arguments:
         **
         *a    zone        - zone to modify
         *a    update_rate - new update rate
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_altitude_update_rate(int zone, int update_rate);

        /*l
         *b  Returns:
         **
         **    altitude update rate of zone as set by
         **    set_zone_altitude_update_rate();
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_altitude_update_rate(int zone);

        /*l
         *b  Description:
         **
         **    This function set the pose update rate for the given zone.
         **
         **    The pose update rate is the percentage of frames in which the
         **    pose of the character will be updated.  The pose includes all
         **    joint angles of the character, but does not include the overall
         **    position.
         **
         **    Defaults:
         *>
         *-      - zone 0:  100
         *-      - zone 1:  50
         *-      - zone 2:  33
         *<
         *b  Arguments:
         **
         *a    zone             - zone to modify
         *a    pose_update_rate - new pose update rate
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_pose_update_rate(int zone, int pose_update_rate);

        /*l
         *b  Returns:
         **
         **    pose update rate of zone as set by
         **    set_zone_pose_update_rate();
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_pose_update_rate(int zone);

        /*l
         *b  Description:
         **
         **    This function set the motion LOD for the given zone.
         **
         **    See diguyCharacter::set_motion_lod() for a discussion
         **    of motion LODs.
         **
         **    Defaults:
         *>
         *-      - zone 0:  1
         *-      - zone 1:  2
         *-      - zone 2:  3
         *<
         *b  Arguments:
         **
         *a    zone       - zone to modify
         *a    motion_lod - new motion LOD
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_motion_lod(int zone, int motion_lod);

        /*l
         *b  Returns:
         **
         **    motion LOD of zone as set by set_zone_motion_lod();
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_motion_lod(int zone);

        /*l
         *b  Description:
         **
         **    See diguyCharacter::set_minimum_cpl() for a description
         **    of what affect this parameter will have on load managed
         **    characters.
         *<
         *b  Arguments:
         **
         *a    zone        - zone to modify
         *a    minimum_cpl - new minimum CPL
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_minimum_cpl(int zone, int minimum_cpl);

        /*l
         *b  Returns:
         **
         **    minimum CPL of zone as set by get_zone_minimum_cpl();
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_minimum_cpl(int zone);

        /*l
         *b  Description:
         **
         **    See diguyCharacter::set_all_blends_disabled() for a description
         **    of what affect this parameter will have on load managed
         **    characters.
         *<
         *b  Arguments:
         **
         *a    zone          - zone to modify
         *a    disabled_flag - pass 1 to disable, 0 to enable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_all_blends_disabled(int zone, int disabled_flag);

        /*l
         *b  Returns:
         **
         **    whether all blends are disabled in the specified zone;
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_all_blends_disabled(int zone);

        /*l
         *b  Description:
         **
         **    See diguyCharacter::set_shape_switches_disabled() for a
         **    description of what affect this parameter will have on load
         **    managed characters.
         *<
         *b  Arguments:
         **
         *a    zone          - zone to modify
         *a    disabled_flag - pass 1 to disable, 0 to enable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_shape_switches_disabled(int zone, int disabled_flag);

        /*l
         *b  Returns:
         **
         **    whether all shape switches are disabled in the specified zone;
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_shape_switches_disabled(int zone);

        /*l
         *b  Description:
         **
         **    See diguyCharacter::set_shape_callbacks_disabled() for a
         **    description of what affect this parameter will have on load
         **    managed characters.
         *<
         *b  Arguments:
         **
         *a    zone          - zone to modify
         *a    disabled_flag - pass 1 to disable, 0 to enable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_shape_callbacks_disabled(int zone, int disabled_flag);

        /*l
         *b  Returns:
         **
         **    whether all shape callbacks are disabled in the specified zone;
         **    -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_shape_callbacks_disabled(int zone);

        /*l
         *b  Description:
         **
         **    See diguyCharacter::set_graphics_api_shape_update_disabled()
         **    for a description of what affect this parameter will have on
         **    load managed characters.
         *<
         *b  Arguments:
         **
         *a    zone          - zone to modify
         *a    disabled_flag - pass 1 to disable, 0 to enable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_zone_graphics_api_shape_update_disabled(int zone, int disabled_flag);

        /*l
         *b  Returns:
         **
         **    whether all graphics API shape updates are disabled in the
         **    specified zone; -1 on failure
         **
         *b  Arguments:
         **
         *a    zone - zone to query
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_zone_graphics_api_shape_update_disabled(int zone);


/****************************************************************************/
/****************************************************************************/
/*****************************************************************************
 **
 *2  Deprecated Functions
 **
 **  The following functions are deprecated.
 **
 **  As these functions may disappear in a future version of DI-Guy,
 **   it is recommended that you remove calls to these functions from
 **   your application.
 **
 */
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

        /*l
         *b  Description:
         **
         **    Deprecated as of 7.1.0, removed in 8.5.0.
         **    Use the function diguyLoadManager::set_minimum_full_update_period()
         **    instead.
         */
        //int set_max_update_period(float period);

        /*l
         *b  Description:
         **
         **    Deprecated as of 7.1.0, removed in 8.5.0.
         **    Use the function diguyLoadManager::set_zone_position_update_rate()
         **    instead, with the zone argument set to
         **    DIGUY_LOAD_MANAGER_NUM_NONVISIBLE_ZONE_INDEX.
         */
        //void set_nonvisible_update_rate(int update_rate);

        /*l
         *b  Description:
         **
         **    Deprecated as of 7.1.0, removed in 8.5.0.
         **    Use the function diguyLoadManager::set_zone_far_extent() instead.
         */
        //int set_zone_bounds(float distance0, float distance1);

        /*l
         *b  Description:
         **
         **    Deprecated as of 7.1.0, removed in 8.5.0.
         **    Use the following functions instead:
         *>
         *-     - diguyLoadManager::set_zone_position_update_rate()
         *-     - diguyLoadManager::set_zone_pose_update_rate()
         *-     - diguyLoadManager::set_zone_motion_lod()
         *<
         */
        //int set_zone_parameters(int zone,
        //      int position_update_rate,
        //      int motion_update_rate,
        //      int motion_lod);

#ifdef CPLUSPLUS_ONLY

        bdiScenarioCharacterLoadManager* get_scripted_object() {return m_load_manager;}

private:

        /*l
         **    A private constructor.  Use the DI-Guy function
         **    diguy_create_load_manager() to obtain a diguyLoadManager object
         **    pointer.
         */
        diguyLoadManager(bdiScenarioCharacterLoadManager* lm);

        /*l
         **    A private destructor.
         */
        virtual ~diguyLoadManager();

        /*l
         **    A pointer to internal data.
         */
        bdiScenarioCharacterLoadManager* m_load_manager;

        friend class bdiScenarioCharacterLoadManager;

#endif

};

#endif