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


/******************************************************************************
 **
 *t  diguyRegion
 **
 *b    Link against: libdiguy
 **
 *b  Summary
 **
 **   API for accessing diguyRegion objects generated by the crowd
 **   and region painter.
 **
 **   For information on subregions, see the documentation for the
 **   diguySubregionIndex and diguySubregionMask enumerations in
 **   diguy_constants.h.
 */

#ifndef __diguyRegion_H
#define __diguyRegion_H


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

#ifdef CPLUSPLUS_ONLY
class bdiNavMeshRegionInterface;

#endif


#include <declspec_diguy.h>
#include <diguy_constants.h>

/*!
 ** \class diguyRegion
 ** \ingroup diguyAI
 ** \brief A two-and-a-half-dimensional surface that represents either a navigation
 **  mesh or an area that's been painted by hand with the crowd painter.
 **
 ** Regions can be layered on top of each other. Different colors can be assigned to a region.
 ** See DI-Guy user guides for more info.
*/

/*********************************************************************/
class BDI_DECLSPEC_diguy diguyRegion
{

public:

/*****************************************************************************/
/**
 *3  Query Functions
 **
 */

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

   /*l
    **
    *b  Description:
    **
    **    Returns 1 if a point is approximately inside the region.  Supports
    **    multiple subregions via or'ing masks together.
    **
    **    Use the base mask (DIGUY_SUBREGION_MASK_BASE) to test against the
    **    base of the region.
    **
    *b  Returns:
    **
    **    1 if the point is in the region, 0 if not
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int is_point_in_region(diguySubregionMask subregion_mask,
      float x, float y, float z);

   /*l
    **
    **
    *b  Description:
    **
    **    Returns a random x, y, z point in the region specified. This
    **    function takes a region index (e.g. DIGUY_SUBREGION_BASE).
    **
    *b  Arguments:
    **
    *a    subregion_index - subregion in which to find the point
    *a    res_x, res_y, res_z    - return point
    **
    *b  Returns:
    **
    **    0 if a point was successfully generated, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int get_point_in_region(diguySubregionIndex subregion_index,
      float* res_x, float* res_y, float* res_z);

   /*l
    **
    *b  Description:
    **
    **    Returns a random x, y, z point, near the seed location, in the
    **    subregion specified.
    **
    *b  Arguments:
    **
    *a    subregion_index        - subregion in which to find the point
    *a    seed_x, seed_y, seed_z - location to use as the seed point
    *a    radius                 - radius around the seed point within which
    *a                             the result point should be located
    *a    res_x, res_y, res_z    - return point
    *a
    *b  Returns:
    **
    **    0 if a point was successfully generated, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int get_point_in_region_near_point(diguySubregionIndex subregion_index,
      float seed_x, float seed_y, float seed_z,
      float radius,
      float* res_x, float* res_y, float* res_z);

   /*l
    **
    *b  Description:
    **
    **    Returns the nearest point in the region near the seed location,
    **    in the subregion(s) specified.
    **
    *b  Arguments:
    **
    *a    subregion_mask         - subregion(s) to search
    *a    seed_x, seed_y, seed_z - location to use as the search seed point
    *a    res_x, res_y, res_z    - return point
    **
    *b  Returns:
    **
    **    0 if a point was successfully generated, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int get_nearest_point_in_region(diguySubregionMask subregion_mask,
      float seed_x, float seed_y, float seed_z,
      float* res_x, float* res_y, float* res_z);

   /*l
    **
    *b  Description:
    **
    **    Returns the nearest reachable point to the seed location, inside
    **    the subregion(s) specified by the mask.
    **
    **    Determining reachability involves guaranteeing that there is a
    **    contiguous section of the base region between the seed point
    **    and the resulting point.
    **
    *b  Arguments:
    **
    *a    subregion_mask         - the subregion(s) to search
    *a    seed_x, seed_y, seed_z - the location to use as the search seed point
    *a    res_x, res_y, res_z    - return point
    **
    *b  Returns:
    **
    **    0 if a point was successfully found, -1 on failure
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int get_nearest_reachable_point(diguySubregionMask subregion_mask,
      float seed_x, float seed_y, float seed_z,
      float* res_x, float* res_y, float* res_z);

   /*l
    *b  Returns:
    **
    **    the number of rows in the region
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int get_num_rows();

    /*l
     *b  Returns:
     **
     **    the number of columns in the region
     **
     *b  Callable From:
     **
     *-    - C++
     *-    - Script
     */
   int get_num_columns();

   /*l
    *b  Returns:
    **
    **    the resolution of the region in meters per point
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   float get_resolution();

   /*l
    *b  Description:
    **
    **    This function returns a random factor between 0 and 1 computed for
    **    this region.  This number can be used, for example, to modify
    **    colors or depths of region visuals.
    **
    **    The number will remain the same for the lifetime of the region.
    **
    *b  Returns:
    **
    **    a random factor between 0 and 1
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   float get_random_factor();


/*****************************************************************************/
/**
 *3  Editing Functions
 **
 */

   /*l
    **
    *b  Description:
    **
    **    Shrinks the region's bounds to just the area with tagged data in
    **    it.  Can help conserve memory.  Currently always returns 0.
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int shrink();

   /*l
    **
    *b  Description:
    **
    **    Erases all region data and then shrinks the region.
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int clear_region();

   /*l
    **
    *b  Description:
    **
    **    Erases all subregion data and then shrinks the region.
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int clear_subregion(diguySubregionIndex subregion_index);

   /*l
    **
    *b  Description:
    **
    **    Resamples the mesh and sets the resolution of the mesh to the new
    **    resolution.
    **
    **    Note that the resampled data is currently rough and will probably
    **    need to be touched up by hand.  The system is currently limited to
    **    creating meshes with a resolution of 0.25 meters per point.
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int resample_mesh(float resolution);

   /*l
    **
    *b  Description:
    **
    **    This function adds to the specified subregion with a spherical
    **    brush centered at the specified point and with the specified
    **    radius.
    **
    **    If you are doing a number of edits to the mesh at once, it's
    **    preferable to wait until the last one before setting
    **    force_visual_update to 1.
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int paint(diguySubregionIndex subregion_index,
      float x, float y, float z,
      float radius,
      int force_visual_update = 0);

   /*l
    **
    *b  Description:
    **
    **    This function adds to the specified subregion with a rectangular
    **    brush stretching from the min point to the max point specified.
    **
    **    If you are doing a number of edits to the mesh at once, it's
    **    preferable to wait until the last one before setting
    **    force_visual_update to 1.
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int paint_rectangle(diguySubregionIndex subregion_index,
      float min_x, float min_y, float min_z,
      float max_x, float max_y, float max_z,
      int force_visual_update = 0);

   /*l
    **
    *b  Description:
    **
    **    This function removes from the specified subregion with a spherical
    **    brush centered at the specified point and with the specified
    **    radius.
    **
    **    If you are doing a number of edits to the mesh at once, it's
    **    preferable to wait until the last one before setting
    **    force_visual_update to 1.
    **
    **  Returns:
    **
    **    1 if any points were erased, 0 if not
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int erase(diguySubregionIndex subregion_index,
      float x, float y, float z,
      float radius,
      int force_visual_update = 0);

   /*l
    **
    *b  Description:
    **
    **    This function removes from the specified subregion with a
    **    rectangular brush stretching from min point to the max point
    **    specified.
    **
    **    If you are doing a number of edits to the mesh at once, it's
    **    preferable to wait until the last one before setting
    **    force_visual_update to 1.
    **
    **  Returns:
    **
    **    1 if any points were erased, 0 if not
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int erase_rectangle(diguySubregionIndex subregion_index,
      float min_x, float min_y, float min_z,
      float max_x, float max_y, float max_z,
      int force_visual_update = 0);

   /*l
    **
    *b  Description:
    **
    **    This function attempts to grow the region to encompass the min and
    **    max points specified as well as determine the reachability of all
    **    of those points at once.  Note: the navmesh reachability algorithm
    **    is not perfect and the results will probably need to be touched up
    **    by hand.
    **
    *b  Callable From:
    **
    *-    - C++
    *-    - Script
    */
   int generate_navmesh(float min_x, float min_y, float min_z,
      float max_x, float max_y, float max_z);


/**
 *x  The functions and variables past this point are for internal use only.
 **   No external access to them is expected or necessary.
 */
#ifdef CPLUSPLUS_ONLY

   bdiNavMeshRegionInterface* get_scripted_object() {return m_scripted_object;}

private:

   /*l
    **    A private constructor.
    */
   diguyRegion(bdiNavMeshRegionInterface* scripted_object);

   /*l
    **    A private destructor.
    */
   ~diguyRegion();

   /*l
    **    A pointer to internal data.
    */
   bdiNavMeshRegionInterface* m_scripted_object;
   friend class bdiNavMeshRegionInterface;
   friend class bdiNavMeshRegion;

   float m_random_factor;

#endif

};


#endif /* __diguyRegion_H */


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

