diguyLoadManager.h

Go to the documentation of this file.

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

/*********************************************************************
 **
 *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>


/*****************************************************************************
 **
 **    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.
 **    All functions are callable From:
 **
 *-    - C++
 *-    - Script
 **
 * \ingroup diguyCore
 */
class BDI_DECLSPEC_diguy diguyLoadManager
{


public:

   /*l
    *b  Description:
    **
    **    This is the top-level on/off switch for this load manager.
    **    By default, load managers are disabled.
    */
   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
    */
   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
    **/
   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()
    */
   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
    */
   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
    */
   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
    */
   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()
    */
   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  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
    */
   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
    */
   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
    */
   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
    */
   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
    */
   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
    */
   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
    */
   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
    */
   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
    */
   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
    */
   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
    **
    */
   int get_zone_all_blends_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
    */
   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
    */
   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
    */
   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
    */
   int get_zone_graphics_api_shape_update_disabled(int zone);

   int set_draw_visuals(int value);
   int get_draw_visuals();


/****************************************************************************/
/****************************************************************************/
/*****************************************************************************
 **
 *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.
 **
 */
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
    // removed functionality
    // int set_zone_shape_switches_disabled(int zone, int disabled_flag);

    // int get_zone_shape_switches_disabled(int zone);
#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