/* $Id$ */

/** @file ai_road.hpp Everything to query and build roads */

#ifndef AI_ROAD_HPP
#define AI_ROAD_HPP

#include "ai_object.hpp"

/**
 * Class that handles all road related functions.
 *
 * Roads are always build from tile center to tile center.
 * Furthermore stations and depots need to be build on tiles
 * that already have road on them. For depots and non-drive
 * through stations that means that only one roadbit may be
 * built at the location. The advantage of this method is
 * that the AI does not need to think about pointing the
 * exit of the depots and roadstations towards the correct
 * direction. For drive-through roadstops this works about
 * the same, though they have to be built on straight roads.
 */
class AIRoad : public AIObject {
public:
	/**
	 * The name of the class, needed by several sub-processes.
	 */
	static const char *GetClassName() { return "AIRoad"; }

	/**
	 * Checks whether the given tile is actually a tile with road that
	 * can be used to traverse a tile. This excludes road depots and
	 * 'normal' road stations, but includes drive through stations.
	 * @param tile the tile to check.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @return true if and only if the tile has road.
	 */
	bool IsRoadTile(TileIndex tile);

	/**
	 * Checks whether the given tile is actually a tile with a road depot.
	 * @param tile the tile to check.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @return true if and only if the tile has a road depot.
	 */
	bool IsRoadDepotTile(TileIndex tile);

	/**
	 * Checks whether the given tile is actually a tile with a road station.
	 * @param tile the tile to check.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @return true if and only if the tile has a road station.
	 */
	bool IsRoadStationTile(TileIndex tile);

	/**
	 * Checks whether the given tile is actually a tile with a drive through
	 * road station.
	 * @param tile the tile to check.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @return true if and only if the tile has a drive through road station.
	 */
	bool IsDriveThroughRoadStationTile(TileIndex tile);

	/**
	 * Checks whether the given tiles are directly connected, i.e. whether
	 * a road vehicle can travel from the center of the first tile to the
	 * center of the second tile.
	 * @param t1 the source tile.
	 * @param t2 the destination tile.
	 * @pre t1 is always positive and smaller than AIMap::GetMapSize().
	 * @pre t2 is always positive and smaller than AIMap::GetMapSize().
	 * @pre t1 and t2 are directly neighbouring tiles.
	 * @return true if and only if a road vehicle can go from t1 to t2.
	 */
	bool AreRoadTilesConnected(TileIndex t1, TileIndex t2);

	/**
	 * Count how many neighbours are road.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @param tile the tile to check on.
	 * @return 0 means no neighbour road; max value is 4.
	 */
	static int32 GetNeighbourRoadCount(TileIndex tile);

	/**
	 * Gets the tile in front of a road depot.
	 * @param depot the road depot tile.
	 * @pre IsRoadDepotTile(depot).
	 * @return the tile in front of the depot.
	 */
	TileIndex GetRoadDepotFrontTile(TileIndex depot);

	/**
	 * Gets the tile in front of a road station.
	 * @param station the road station tile.
	 * @pre IsRoadStationTile(station).
	 * @return the tile in front of the road station.
	 */
	TileIndex GetRoadStationFrontTile(TileIndex station);

	/**
	 * Gets the tile at the back of a drive through road station.
	 * So, one side of the drive through station is retrieved with
	 * GetTileInFrontOfStation, the other with this function.
	 * @param station the road station tile.
	 * @pre IsDriveThroughRoadStationTile(station).
	 * @return the tile at the back of the drive through road station.
	 */
	TileIndex GetDriveThroughBackTile(TileIndex station);

	/**
	 * Builds a road from the center of tile start to the
	 * center of tile end.
	 * @param start the start tile of the road.
	 * @param end   the end tile of the road.
	 * @pre start is not equal to end
	 * @pre start is always positive and smaller than AIMap::GetMapSize().
	 * @pre end is always positive and smaller than AIMap::GetMapSize().
	 * @pre start and end are in a straight line, i.e.
	 *  AIMap::GetTileX(start) == AIMap::GetTileX(end) or
	 *  AIMap::GetTileY(start) == AIMap::GetTileY(end).
	 * @return whether the road has been/can be build or not.
	 */
	bool BuildRoad(TileIndex start, TileIndex end);

	/**
	 * Builds a road from the edge of tile start to the
	 * edge of tile end (both included).
	 * @param start the start tile of the road.
	 * @param end   the end tile of the road.
	 * @pre start is not equal to end
	 * @pre start is always positive and smaller than AIMap::GetMapSize().
	 * @pre end is always positive and smaller than AIMap::GetMapSize().
	 * @pre start and end are in a straight line, i.e.
	 *  AIMap::GetTileX(start) == AIMap::GetTileX(end) or
	 *  AIMap::GetTileY(start) == AIMap::GetTileY(end).
	 * @return whether the road has been/can be build or not.
	 */
	bool BuildRoadFull(TileIndex start, TileIndex end);

	/**
	 * Builds a road depot.
	 * @param tile  place to build the depot.
	 * @param front the tile exactly in front of the depot
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @pre front is always positive and smaller than AIMap::GetMapSize().
	 * @pre tile is not equal to front
	 * @return whether the road depot has been/can be build or not.
	 */
	bool BuildRoadDepot(TileIndex tile, TileIndex front);

	/**
	 * Builds a road bus or truck station.
	 * @param tile  place to build the depot.
	 * @param front the tile exactly in front of the station.
	 *   For drive-through stations either entrance side can be used.
	 * @param truck whether to build a truck (true) or bus (false) station.
	 * @param drive_through whether to make the station drive through or not.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @pre front is always positive and smaller than AIMap::GetMapSize().
	 * @pre tile is not equal to front
	 * @return whether the station has been/can be build or not.
	 */
	bool BuildRoadStation(TileIndex tile, TileIndex front, bool truck, bool drive_through);

	/**
	 * Removes a road from the center of tile start to the
	 * center of tile end.
	 * @param start the start tile of the road.
	 * @param end   the end tile of the road.
	 * @pre start is always positive and smaller than AIMap::GetMapSize().
	 * @pre end is always positive and smaller than AIMap::GetMapSize().
	 * @pre start and end are in a straight line, i.e.
	 *  AIMap::GetTileX(start) == AIMap::GetTileX(end) or
	 *  AIMap::GetTileY(start) == AIMap::GetTileY(end).
	 * @return whether the road has been/can be removed or not.
	 */
	bool RemoveRoad(TileIndex start, TileIndex end);

	/**
	 * Removes a road from the edge of tile start to the
	 * edge of tile end (both included).
	 * @param start the start tile of the road.
	 * @param end   the end tile of the road.
	 * @pre start is always positive and smaller than AIMap::GetMapSize().
	 * @pre end is always positive and smaller than AIMap::GetMapSize().
	 * @pre start and end are in a straight line, i.e.
	 *  AIMap::GetTileX(start) == AIMap::GetTileX(end) or
	 *  AIMap::GetTileY(start) == AIMap::GetTileY(end).
	 * @return whether the road has been/can be removed or not.
	 */
	bool RemoveRoadFull(TileIndex start, TileIndex end);

	/**
	 * Removes a road depot.
	 * @param tile place to remove the depot from.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @pre tile is a road depot.
	 * @return whether the road depot has been/can be removed or not.
	 */
	bool RemoveRoadDepot(TileIndex tile);

	/**
	 * Removes a road bus or truck station.
	 * @param tile place to remove the station from.
	 * @pre tile is always positive and smaller than AIMap::GetMapSize().
	 * @pre tile is a road station.
	 * @return whether the station has been/can be removed or not.
	 */
	bool RemoveRoadStation(TileIndex tile);
};

#endif /* AI_ROAD_HPP */