/*
 * $RCSfile$ $Revision$ $State$
 */
/****************************************************************************
*   File: libroutemap.h                                                     *
*                                                                           *
*       Copyright 1993 by Loral Advanced Distributed Simulation, Inc.       *
*                                                                           *
*               Loral Advanced Distributed Simulation, Inc.                 *
*               10 Moulton Street                                           *
*               Cambridge, MA 02238                                         *
*               617-873-1850                                                *
*                                                                           *
*       This software was developed by Loral under U. S. Government contracts*
*       and may be reproduced by or for the U. S. Government pursuant to    *
*       the copyright license under the clause at DFARS 252.227-7013        *
*       (OCT 1988).                                                         *
*                                                                           *
*       Contents: Public header file for libroutemap                        *
*       Created: Tue Nov  9 1993                                            *
*       Author: jesmith                                                     *
*       Remarks:                                                            *
*                                                                           *
****************************************************************************/

#ifndef _LIBROUTEMAP_INCLUDED
#define _LIBROUTEMAP_INCLUDED

#include "/usr/modsaf/common/libsrc/libctdb/libctdb.h"
#include <stdroute.h>

typedef struct routemap_data *ROUTEMAP_PTR;

/* Obstacle type masks
 */
#define ROUTEMAP_RIVERS         0x00000001
#define ROUTEMAP_LAKES          0x00000002
#define ROUTEMAP_BOULDERS       0x00000004
#define ROUTEMAP_CANOPIES       0x00000008
#define ROUTEMAP_STEEP_AREAS    0x00000010

/* A list of corridors */
typedef struct routemap_corridor_list
{
    int32                     num_corridors;
    struct routemap_corridor *corridors[1];
} ROUTEMAP_CORRIDOR_LIST;

/* A planning boundary */
typedef struct routemap_boundary *ROUTEMAP_BOUNDARY_PTR;

/* routemap_create:
 *
 * Creates a routemap for a terrain database.  This routemap can be
 * used to plan a route around large obstacles.
 */
extern ROUTEMAP_PTR routemap_create(/* CTDB      *ctdb,
				       char      *data_path,
				       uint32     reader_flags
				       */);

/* routemap_preplan:
 *
 * Performs obstacle avoidance around fixed obstacles which match
 * the passed type mask, and returns the shortest course which can
 * be found in the specified time.  The returned plan is dynamically
 * allocated using NS_ROUTE_ALLOCATE_POINTS (from stdroute.h), and thus
 * plan.points should be freed using STDDEALLOC.  If routemap was unable
 * to come up with a perfectly clear plan, a best-effort plan is returned.
 * A zero return value indicates this case.
 */
extern int32 routemap_preplan(/* ROUTEMAP_PTR  routemap,
				 uint32        obstacle_mask,
				 ROUTE_POINTS *goal,
				 int32         unit_width,
				 ROUTE_POINTS *plan
				 */);

/* routemap_find_corridors:
 *
 * Finds all the corridors which are near a point.  These corridors
 * can be passed to routemap_preplan_constrained, as places the plan
 * should not go.  This can be used, for example, to avoid destroyed
 * bridges.  The returned list is allocated dynamically with
 * STDALLOC, and can be freed using STDDEALLOC.  If no corridors are
 * found, NULL is returned;
 */
extern ROUTEMAP_CORRIDOR_LIST *
  routemap_find_corridors(/* ROUTEMAP_PTR routemap,
			     float64      x, y,
			     float64      search_radius
			     */);

/* routemap_create_boundary:
 *
 * Translates a list of points into a boundary for planning purposes.
 */
extern ROUTEMAP_BOUNDARY_PTR
  routemap_create_boundary(/* ROUTE_POINTS *points */);

/* routemap_free_boundary:
 *
 * Frees the memory associated with a routemap boundary.
 */
extern void routemap_free_boundary(/* ROUTEMAP_BOUNDARY_PTR boundary */);

/* routemap_preplan_constrained:
 *
 * Operates just like routemap_preplan, except that the search is
 * constrained to an area between the left and right boundaries,
 * the specified corridors are not used.  NULL may be passed for either
 * boundary.
 */
extern int32
  routemap_preplan_constrained(/* ROUTEMAP_PTR            routemap,
				  uint32                  obstacle_mask,
				  ROUTE_POINTS           *goal,
				  int32                   unit_width,
				  int32                   num_clists,
				  ROUTEMAP_CORRIDOR_LIST *clists[],
				  ROUTEMAP_BOUNDARY_PTR   left_bound,
				  ROUTEMAP_BOUNDARY_PTR   right_bound,
				  ROUTE_POINTS           *plan
				  */);

/* routemap_get_obstacles:
 *
 * This function returns pointers to the first `n_obstacles' obstacles within
 * the given rectangular area that match the passed obstacle mask.  The
 * number of obstacles found is returned in `n_obstacles'.  The pointers
 * in the `obstacles[]' array don't tell the caller much unless they are
 * converted to a list of vertices by `routemap_obstacle_to_vertices()'.
 * If the number of matching obstacles exceeds `n_obstacles', a non-zero
 * value is returned.  Otherwise, a zero is returned.
 */
extern int32 routemap_get_obstacles(/* ROUTEMAP_PTR       routemap,
				       uint32             obstacle_mask,
				       float64            x_min,
				       float64            y_min,
				       float64            x_max,
				       float64            y_max,
				       int32             *n_obstacles,
				       ADDRESS            obstacles[]
				       */);

/* routemap_obstacle_type:
 *
 * Given a pointer to a routemap obstacle, this function returns the type of
 * object, which is one of:
 *
 * ROUTEMAP_RIVERS
 * ROUTEMAP_LAKES
 * ROUTEMAP_BOULDERS
 * ROUTEMAP_CANOPIES
 * ROUTEMAP_STEEP_AREAS
 */
extern uint32 routemap_obstacle_type(/* ADDRESS          obstacle
				      */);

/* routemap_obstacle_to_vertices:
 *
 * Given a pointer to a routemap obstacle, this function finds the vertices
 * of the object specified by the pointer.  The number of vertices is
 * returned in `n_vertices'.  Upon invocation, `n_vertices' should contain
 * the maximum number of vertices that may be found.  If the object has
 * more than this number of vertices, a nonzero value is returned.  Otherwise,
 * zero is returned.
 */
extern int32 routemap_obstacle_to_vertices(/* ADDRESS            obstacle,
					      int32             *n_vertices,
					      float64            vertices[][2]
					      */);

#endif /*_LIBROUTEMAP_INCLUDED*/