gronod/OpenTTD
1
0
Fork 0
mirror of https://github.com/OpenTTD/OpenTTD.git synced 2025-03-06 06:15:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

(svn r21846) -Codechange: move documentation towards the code to make it more likely to be updated [o-s].

Browse Source
This commit is contained in:
rubidium 2011-01-18 23:09:43 +00:00
parent 7efd7e19ed
commit 9ca4b629cd
24 changed files with 360 additions and 409 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
src/object.h
View File

@ -16,23 +16,8 @@
#include "company_type.h"
#include "object_type.h"
/**
* Update the CompanyHQ to the state associated with the given score
* @param tile The (northern) tile of the company HQ, or INVALID_TILE.
* @param score The current (performance) score of the company.
*/
void UpdateCompanyHQ(TileIndex tile, uint score);
/**
* Actually build the object.
* @param type The type of object to build.
* @param tile The tile to build the northern tile of the object on.
* @param owner The owner of the object.
* @param town Town the tile is related with.
* @param view The view for the object.
* @pre All preconditions for building the object at that location
* are met, e.g. slope and clearness of tiles are checked.
*/
void BuildObject(ObjectType type, TileIndex tile, CompanyID owner = OWNER_NONE, struct Town *town = NULL, uint8 view = 0);
void PlaceProc_Object(TileIndex tile);

5
src/object_base.h
View File

@ -35,11 +35,6 @@ struct Object : ObjectPool::PoolItem<&_object_pool> {
/** Make sure the right destructor is called as well! */
~Object() {}
/**
* Get the object associated with a tile.
* @param tile The tile to fetch the object for.
* @return The object.
*/
static Object *GetByTile(TileIndex tile);
/**

20
src/object_cmd.cpp
View File

@ -43,6 +43,11 @@ ObjectPool _object_pool("Object");
INSTANTIATE_POOL_METHODS(Object)
uint16 Object::counts[NUM_OBJECTS];
/**
* Get the object associated with a tile.
* @param tile The tile to fetch the object for.
* @return The object.
*/
/* static */ Object *Object::GetByTile(TileIndex tile)
{
return Object::Get(GetObjectIndex(tile));
@ -55,6 +60,16 @@ void InitializeObjects()
Object::ResetTypeCounts();
}
/**
* Actually build the object.
* @param type The type of object to build.
* @param tile The tile to build the northern tile of the object on.
* @param owner The owner of the object.
* @param town Town the tile is related with.
* @param view The view for the object.
* @pre All preconditions for building the object at that location
* are met, e.g. slope and clearness of tiles are checked.
*/
void BuildObject(ObjectType type, TileIndex tile, CompanyID owner, Town *town, uint8 view)
{
const ObjectSpec *spec = ObjectSpec::Get(type);
@ -113,6 +128,11 @@ static void IncreaseAnimationStage(TileIndex tile)
/** We encode the company HQ size in the animation stage. */
#define IncreaseCompanyHQSize IncreaseAnimationStage
/**
* Update the CompanyHQ to the state associated with the given score
* @param tile The (northern) tile of the company HQ, or INVALID_TILE.
* @param score The current (performance) score of the company.
*/
void UpdateCompanyHQ(TileIndex tile, uint score)
{
if (tile == INVALID_TILE) return;

51
src/order_backup.cpp
View File

@ -20,6 +20,7 @@
OrderBackupPool _order_backup_pool("BackupOrder");
INSTANTIATE_POOL_METHODS(OrderBackup)
/** Free everything that is allocated. */
OrderBackup::~OrderBackup()
{
free(this->name);
@ -34,6 +35,11 @@ OrderBackup::~OrderBackup()
}
}
/**
* Create an order backup for the given vehicle.
* @param v The vehicle to make a backup of.
* @param user The user that is requesting the backup.
*/
OrderBackup::OrderBackup(const Vehicle *v, uint32 user)
{
this->user = user;
@ -62,6 +68,10 @@ OrderBackup::OrderBackup(const Vehicle *v, uint32 user)
}
}
/**
* Restore the data of this order to the given vehicle.
* @param v The vehicle to restore to.
*/
void OrderBackup::DoRestore(Vehicle *v)
{
/* If we have a custom name, process that */
@ -84,6 +94,12 @@ void OrderBackup::DoRestore(Vehicle *v)
DoCommand(0, this->group, v->index, DC_EXEC, CMD_ADD_VEHICLE_GROUP);
}
/**
* Create an order backup for the given vehicle.
* @param v The vehicle to make a backup of.
* @param user The user that is requesting the backup.
* @note Will automatically remove any previous backups of this user.
*/
/* static */ void OrderBackup::Backup(const Vehicle *v, uint32 user)
{
/* Don't use reset as that broadcasts over the network to reset the variable,
@ -95,6 +111,12 @@ void OrderBackup::DoRestore(Vehicle *v)
new OrderBackup(v, user);
}
/**
* Restore the data of this order to the given vehicle.
* @param v The vehicle to restore to.
* @param user The user that built the vehicle, thus wants to restore.
* @note After restoration the backup will automatically be removed.
*/
/* static */ void OrderBackup::Restore(Vehicle *v, uint32 user)
{
OrderBackup *ob;
@ -106,6 +128,12 @@ void OrderBackup::DoRestore(Vehicle *v)
}
}
/**
* Reset an OrderBackup given a tile and user.
* @param tile The tile associated with the OrderBackup.
* @param user The user associated with the OrderBackup.
* @note Must not be used from the GUI!
*/
/* static */ void OrderBackup::ResetOfUser(TileIndex tile, uint32 user)
{
OrderBackup *ob;
@ -131,6 +159,12 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1,
return CommandCost();
}
/**
* Reset an user's OrderBackup if needed.
* @param user The user associated with the OrderBackup.
* @pre _network_server.
* @note Must not be used from a command.
*/
/* static */ void OrderBackup::ResetUser(uint32 user)
{
assert(_network_server);
@ -145,6 +179,12 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1,
}
}
/**
* Reset the OrderBackups from GUI/game logic.
* @param tile The tile of the order backup.
* @param from_gui Whether the call came from the GUI, i.e. whether
* it must be synced over the network.
*/
/* static */ void OrderBackup::Reset(TileIndex t, bool from_gui)
{
/* The user has CLIENT_ID_SERVER as default when network play is not active,
@ -177,6 +217,10 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1,
}
}
/**
* Clear the group of all backups having this group ID.
* @param group The group to clear.
*/
/* static */ void OrderBackup::ClearGroup(GroupID group)
{
OrderBackup *ob;
@ -185,6 +229,13 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1,
}
}
/**
* Clear/update the (clone) vehicle from an order backup.
* @param v The vehicle to clear.
* @pre v != NULL
* @note If it is not possible to set another vehicle as clone
* "example", then this backed up order will be removed.
*/
/* static */ void OrderBackup::ClearVehicle(const Vehicle *v)
{
assert(v != NULL);

56
src/order_backup.h
View File

@ -51,77 +51,21 @@ private:
/** Creation for savegame restoration. */
OrderBackup() {}
/**
* Create an order backup for the given vehicle.
* @param v The vehicle to make a backup of.
* @param user The user that is requesting the backup.
*/
OrderBackup(const Vehicle *v, uint32 user);
/**
* Restore the data of this order to the given vehicle.
* @param v The vehicle to restore to.
*/
void DoRestore(Vehicle *v);
public:
/** Free everything that is allocated. */
~OrderBackup();
/**
* Create an order backup for the given vehicle.
* @param v The vehicle to make a backup of.
* @param user The user that is requesting the backup.
* @note Will automatically remove any previous backups of this user.
*/
static void Backup(const Vehicle *v, uint32 user);
/**
* Restore the data of this order to the given vehicle.
* @param v The vehicle to restore to.
* @param user The user that built the vehicle, thus wants to restore.
* @note After restoration the backup will automatically be removed.
*/
static void Restore(Vehicle *v, uint32 user);
/**
* Reset an OrderBackup given a tile and user.
* @param tile The tile associated with the OrderBackup.
* @param user The user associated with the OrderBackup.
* @note Must not be used from the GUI!
*/
static void ResetOfUser(TileIndex tile, uint32 user);
/**
* Reset an user's OrderBackup if needed.
* @param user The user associated with the OrderBackup.
* @pre _network_server.
* @note Must not be used from a command.
*/
static void ResetUser(uint32 user);
/**
* Reset the OrderBackups from GUI/game logic.
* @param tile The tile of the order backup.
* @param from_gui Whether the call came from the GUI, i.e. whether
* it must be synced over the network.
*/
static void Reset(TileIndex tile = INVALID_TILE, bool from_gui = true);
/**
* Clear the group of all backups having this group ID.
* @param group The group to clear.
*/
static void ClearGroup(GroupID group);
/**
* Clear/update the (clone) vehicle from an order backup.
* @param v The vehicle to clear.
* @pre v != NULL
* @note If it is not possible to set another vehicle as clone
* "example", then this backed up order will be removed.
*/
static void ClearVehicle(const Vehicle *v);
};

136
src/order_base.h
View File

@ -53,10 +53,6 @@ public:
Order() : refit_cargo(CT_NO_REFIT) {}
~Order() {}
/**
* Create an order based on a packed representation of that order.
* @param packed the packed representation.
*/
Order(uint32 packed);
/**
@ -72,61 +68,15 @@ public:
*/
inline OrderType GetType() const { return (OrderType)GB(this->type, 0, 4); }
/**
* 'Free' the order
* @note ONLY use on "current_order" vehicle orders!
*/
void Free();
/**
* Makes this order a Go To Station order.
* @param destination the station to go to.
*/
void MakeGoToStation(StationID destination);
/**
* Makes this order a Go To Depot order.
* @param destination the depot to go to.
* @param order is this order a 'default' order, or an overriden vehicle order?
* @param non_stop_type how to get to the depot?
* @param action what to do in the depot?
* @param cargo the cargo type to change to.
* @param subtype the subtype to change to.
*/
void MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderNonStopFlags non_stop_type = ONSF_NO_STOP_AT_INTERMEDIATE_STATIONS, OrderDepotActionFlags action = ODATF_SERVICE_ONLY, CargoID cargo = CT_NO_REFIT, byte subtype = 0);
/**
* Makes this order a Go To Waypoint order.
* @param destination the waypoint to go to.
*/
void MakeGoToWaypoint(StationID destination);
/**
* Makes this order a Loading order.
* @param ordered is this an ordered stop?
*/
void MakeLoading(bool ordered);
/**
* Makes this order a Leave Station order.
*/
void MakeLeaveStation();
/**
* Makes this order a Dummy order.
*/
void MakeDummy();
/**
* Makes this order an conditional order.
* @param order the order to jump to.
*/
void MakeConditional(VehicleOrderID order);
/**
* Makes this order an automatic order.
* @param destination the station to go to.
*/
void MakeAutomatic(StationID destination);
/**
@ -164,12 +114,6 @@ public:
*/
inline byte GetRefitSubtype() const { return this->refit_subtype; }
/**
* Make this depot order also a refit order.
* @param cargo the cargo type to change to.
* @param subtype the subtype to change to.
* @pre IsType(OT_GOTO_DEPOT).
*/
void SetRefit(CargoID cargo, byte subtype = 0);
/** How must the consist be loaded? */
@ -225,38 +169,11 @@ public:
return true;
}
/**
* Assign the given order to this one.
* @param other the data to copy (except next pointer).
*/
void AssignOrder(const Order &other);
/**
* Does this order have the same type, flags and destination?
* @param other the second order to compare to.
* @return true if the type, flags and destination match.
*/
bool Equals(const Order &other) const;
/**
* Pack this order into a 32 bits integer, or actually only
* the type, flags and destination.
* @return the packed representation.
* @note unpacking is done in the constructor.
*/
uint32 Pack() const;
/**
* Pack this order into a 16 bits integer as close to the TTD
* representation as possible.
* @return the TTD-like packed representation.
*/
uint16 MapOldOrder() const;
/**
* Converts this order from an old savegame's version;
* it moves all bits to the new location.
*/
void ConvertFromOldSavegame();
};
@ -296,11 +213,6 @@ public:
/** Destructor. Invalidates OrderList for re-usage by the pool. */
~OrderList() {}
/**
* Recomputes everything.
* @param chain first order in the chain
* @param v one of vehicle that is using this orderlist
*/
void Initialize(Order *chain, Vehicle *v);
/**
@ -309,11 +221,6 @@ public:
*/
inline Order *GetFirstOrder() const { return this->first; }
/**
* Get a certain order of the order chain.
* @param index zero-based index of the order within the chain.
* @return the order at position index.
*/
Order *GetOrderAt(int index) const;
/**
@ -334,24 +241,8 @@ public:
*/
inline VehicleOrderID GetNumManualOrders() const { return this->num_manual_orders; }
/**
* Insert a new order into the order chain.
* @param new_order is the order to insert into the chain.
* @param index is the position where the order is supposed to be inserted.
*/
void InsertOrderAt(Order *new_order, int index);
/**
* Remove an order from the order list and delete it.
* @param index is the position of the order which is to be deleted.
*/
void DeleteOrderAt(int index);
/**
* Move an order to another position within the order list.
* @param from is the zero-based position of the order to move.
* @param to is the zero-based position where the order is moved to.
*/
void MoveOrder(int from, int to);
/**
@ -372,17 +263,7 @@ public:
*/
inline uint GetNumVehicles() const { return this->num_vehicles; }
/**
* Checks whether a vehicle is part of the shared vehicle chain.
* @param v is the vehicle to search in the shared vehicle chain.
*/
bool IsVehicleInSharedOrdersList(const Vehicle *v) const;
/**
* Gets the position of the given vehicle within the shared order vehicle list.
* @param v is the vehicle of which to get the position
* @return position of v within the shared vehicle chain.
*/
int GetPositionInSharedOrderList(const Vehicle *v) const;
/**
@ -393,17 +274,8 @@ public:
*/
inline void AddVehicle(Vehicle *v) { ++this->num_vehicles; }
/**
* Removes the vehicle from the shared order list.
* @note This is supposed to be called when the vehicle is still in the chain
* @param v vehicle to remove from the list
*/
void RemoveVehicle(Vehicle *v);
/**
* Checks whether all orders of the list have a filled timetable.
* @return whether all orders have a filled timetable.
*/
bool IsCompleteTimetable() const;
/**
@ -424,16 +296,8 @@ public:
*/
void UpdateOrderTimetable(Ticks delta) { this->timetable_duration += delta; }
/**
* Free a complete order chain.
* @param keep_orderlist If this is true only delete the orders, otherwise also delete the OrderList.
* @note do not use on "current_order" vehicle orders!
*/
void FreeChain(bool keep_orderlist = false);
/**
* Checks for internal consistency of order list. Triggers assertion if something is wrong.
*/
void DebugCheckSanity() const;
};

123
src/order_cmd.cpp
View File

@ -42,6 +42,10 @@ INSTANTIATE_POOL_METHODS(Order)
OrderListPool _orderlist_pool("OrderList");
INSTANTIATE_POOL_METHODS(OrderList)
/**
* 'Free' the order
* @note ONLY use on "current_order" vehicle orders!
*/
void Order::Free()
{
this->type = OT_NOTHING;
@ -50,6 +54,10 @@ void Order::Free()
this->next = NULL;
}
/**
* Makes this order a Go To Station order.
* @param destination the station to go to.
*/
void Order::MakeGoToStation(StationID destination)
{
this->type = OT_GOTO_STATION;
@ -57,6 +65,15 @@ void Order::MakeGoToStation(StationID destination)
this->dest = destination;
}
/**
* Makes this order a Go To Depot order.
* @param destination the depot to go to.
* @param order is this order a 'default' order, or an overriden vehicle order?
* @param non_stop_type how to get to the depot?
* @param action what to do in the depot?
* @param cargo the cargo type to change to.
* @param subtype the subtype to change to.
*/
void Order::MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderNonStopFlags non_stop_type, OrderDepotActionFlags action, CargoID cargo, byte subtype)
{
this->type = OT_GOTO_DEPOT;
@ -67,6 +84,10 @@ void Order::MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderN
this->SetRefit(cargo, subtype);
}
/**
* Makes this order a Go To Waypoint order.
* @param destination the waypoint to go to.
*/
void Order::MakeGoToWaypoint(StationID destination)
{
this->type = OT_GOTO_WAYPOINT;
@ -74,24 +95,38 @@ void Order::MakeGoToWaypoint(StationID destination)
this->dest = destination;
}
/**
* Makes this order a Loading order.
* @param ordered is this an ordered stop?
*/
void Order::MakeLoading(bool ordered)
{
this->type = OT_LOADING;
if (!ordered) this->flags = 0;
}
/**
* Makes this order a Leave Station order.
*/
void Order::MakeLeaveStation()
{
this->type = OT_LEAVESTATION;
this->flags = 0;
}
/**
* Makes this order a Dummy order.
*/
void Order::MakeDummy()
{
this->type = OT_DUMMY;
this->flags = 0;
}
/**
* Makes this order an conditional order.
* @param order the order to jump to.
*/
void Order::MakeConditional(VehicleOrderID order)
{
this->type = OT_CONDITIONAL;
@ -99,18 +134,33 @@ void Order::MakeConditional(VehicleOrderID order)
this->dest = 0;
}
/**
* Makes this order an automatic order.
* @param destination the station to go to.
*/
void Order::MakeAutomatic(StationID destination)
{
this->type = OT_AUTOMATIC;
this->dest = destination;
}
/**
* Make this depot order also a refit order.
* @param cargo the cargo type to change to.
* @param subtype the subtype to change to.
* @pre IsType(OT_GOTO_DEPOT).
*/
void Order::SetRefit(CargoID cargo, byte subtype)
{
this->refit_cargo = cargo;
this->refit_subtype = subtype;
}
/**
* Does this order have the same type, flags and destination?
* @param other the second order to compare to.
* @return true if the type, flags and destination match.
*/
bool Order::Equals(const Order &other) const
{
/* In case of go to nearest depot orders we need "only" compare the flags
@ -128,11 +178,22 @@ bool Order::Equals(const Order &other) const
return this->type == other.type && this->flags == other.flags && this->dest == other.dest;
}
/**
* Pack this order into a 32 bits integer, or actually only
* the type, flags and destination.
* @return the packed representation.
* @note unpacking is done in the constructor.
*/
uint32 Order::Pack() const
{
return this->dest << 16 | this->flags << 8 | this->type;
}
/**
* Pack this order into a 16 bits integer as close to the TTD
* representation as possible.
* @return the TTD-like packed representation.
*/
uint16 Order::MapOldOrder() const
{
uint16 order = this->GetType();
@ -155,6 +216,10 @@ uint16 Order::MapOldOrder() const
return order;
}
/**
* Create an order based on a packed representation of that order.
* @param packed the packed representation.
*/
Order::Order(uint32 packed)
{
this->type = (OrderType)GB(packed, 0, 8);
@ -191,6 +256,7 @@ void InvalidateVehicleOrder(const Vehicle *v, int data)
*
* Assign data to an order (from another order)
* This function makes sure that the index is maintained correctly
* @param other the data to copy (except next pointer).
*
*/
void Order::AssignOrder(const Order &other)
@ -206,6 +272,11 @@ void Order::AssignOrder(const Order &other)
this->travel_time = other.travel_time;
}
/**
* Recomputes everything.
* @param chain first order in the chain
* @param v one of vehicle that is using this orderlist
*/
void OrderList::Initialize(Order *chain, Vehicle *v)
{
this->first = chain;
@ -230,6 +301,11 @@ void OrderList::Initialize(Order *chain, Vehicle *v)
for (const Vehicle *u = v->NextShared(); u != NULL; u = u->NextShared()) ++this->num_vehicles;
}
/**
* Free a complete order chain.
* @param keep_orderlist If this is true only delete the orders, otherwise also delete the OrderList.
* @note do not use on "current_order" vehicle orders!
*/
void OrderList::FreeChain(bool keep_orderlist)
{
Order *next;
@ -248,6 +324,11 @@ void OrderList::FreeChain(bool keep_orderlist)
}
}
/**
* Get a certain order of the order chain.
* @param index zero-based index of the order within the chain.
* @return the order at position index.
*/
Order *OrderList::GetOrderAt(int index) const
{
if (index < 0) return NULL;
@ -260,6 +341,11 @@ Order *OrderList::GetOrderAt(int index) const
return order;
}
/**
* Insert a new order into the order chain.
* @param new_order is the order to insert into the chain.
* @param index is the position where the order is supposed to be inserted.
*/
void OrderList::InsertOrderAt(Order *new_order, int index)
{
if (this->first == NULL) {
@ -285,6 +371,10 @@ void OrderList::InsertOrderAt(Order *new_order, int index)
}
/**
* Remove an order from the order list and delete it.
* @param index is the position of the order which is to be deleted.
*/
void OrderList::DeleteOrderAt(int index)
{
if (index >= this->num_orders) return;
@ -305,6 +395,11 @@ void OrderList::DeleteOrderAt(int index)
delete to_remove;
}
/**
* Move an order to another position within the order list.
* @param from is the zero-based position of the order to move.
* @param to is the zero-based position where the order is moved to.
*/
void OrderList::MoveOrder(int from, int to)
{
if (from >= this->num_orders || to >= this->num_orders || from == to) return;
@ -332,12 +427,21 @@ void OrderList::MoveOrder(int from, int to)
}
}
/**
* Removes the vehicle from the shared order list.
* @note This is supposed to be called when the vehicle is still in the chain
* @param v vehicle to remove from the list
*/
void OrderList::RemoveVehicle(Vehicle *v)
{
--this->num_vehicles;
if (v == this->first_shared) this->first_shared = v->NextShared();
}
/**
* Checks whether a vehicle is part of the shared vehicle chain.
* @param v is the vehicle to search in the shared vehicle chain.
*/
bool OrderList::IsVehicleInSharedOrdersList(const Vehicle *v) const
{
for (const Vehicle *v_shared = this->first_shared; v_shared != NULL; v_shared = v_shared->NextShared()) {
@ -347,6 +451,11 @@ bool OrderList::IsVehicleInSharedOrdersList(const Vehicle *v) const
return false;
}
/**
* Gets the position of the given vehicle within the shared order vehicle list.
* @param v is the vehicle of which to get the position
* @return position of v within the shared vehicle chain.
*/
int OrderList::GetPositionInSharedOrderList(const Vehicle *v) const
{
int count = 0;
@ -354,6 +463,10 @@ int OrderList::GetPositionInSharedOrderList(const Vehicle *v) const
return count;
}
/**
* Checks whether all orders of the list have a filled timetable.
* @return whether all orders have a filled timetable.
*/
bool OrderList::IsCompleteTimetable() const
{
for (Order *o = this->first; o != NULL; o = o->next) {
@ -364,6 +477,9 @@ bool OrderList::IsCompleteTimetable() const
return true;
}
/**
* Checks for internal consistency of order list. Triggers assertion if something is wrong.
*/
void OrderList::DebugCheckSanity() const
{
VehicleOrderID check_num_orders = 0;
@ -1524,6 +1640,13 @@ void DeleteVehicleOrders(Vehicle *v, bool keep_orderlist)
}
}
/**
* Clamp the service interval to the correct min/max. The actual min/max values
* depend on whether it's in percent or days.
* @param interval proposed service interval
* @param company_id the owner of the vehicle
* @return Clamped service interval
*/
uint16 GetServiceIntervalClamped(uint interval, CompanyID company_id)
{
return (Company::Get(company_id)->settings.vehicle.servint_ispercent) ? Clamp(interval, MIN_SERVINT_PERCENT, MAX_SERVINT_PERCENT) : Clamp(interval, MIN_SERVINT_DAYS, MAX_SERVINT_DAYS);

7
src/order_func.h
View File

@ -32,13 +32,6 @@ void DrawOrderString(const Vehicle *v, const Order *order, int order_index, int
#define MIN_SERVINT_DAYS 30
#define MAX_SERVINT_DAYS 800
/**
* Clamp the service interval to the correct min/max. The actual min/max values
* depend on whether it's in percent or days.
* @param interval proposed service interval
* @param company_id the owner of the vehicle
* @return Clamped service interval
*/
uint16 GetServiceIntervalClamped(uint interval, CompanyID company_id);
#endif /* ORDER_FUNC_H */

31
src/rail.cpp
View File

@ -149,6 +149,9 @@ extern const TrackdirBits _uphill_trackdirs[] = {
TRACKDIR_BIT_X_NE | TRACKDIR_BIT_Y_SE, ///< 30 SLOPE_STEEP_E -> inclined for diagonal track
};
/**
* Return the rail type of tile, or INVALID_RAILTYPE if this is no rail tile.
*/
RailType GetTileRailType(TileIndex tile)
{
switch (GetTileType(tile)) {
@ -174,16 +177,34 @@ RailType GetTileRailType(TileIndex tile)
return INVALID_RAILTYPE;
}
/**
* Finds out if a company has a certain railtype available
* @param company the company in question
* @param railtype requested RailType
* @return true if company has requested RailType available
*/
bool HasRailtypeAvail(const CompanyID company, const RailType railtype)
{
return HasBit(Company::Get(company)->avail_railtypes, railtype);
}
/**
* Validate functions for rail building.
* @param rail the railtype to check.
* @return true if the current company may build the rail.
*/
bool ValParamRailtype(const RailType rail)
{
return rail < RAILTYPE_END && HasRailtypeAvail(_current_company, rail);
}
/**
* Returns the "best" railtype a company can build.
* As the AI doesn't know what the BEST one is, we have our own priority list
* here. When adding new railtypes, modify this function
* @param company the company "in action"
* @return The "best" railtype a company has available
*/
RailType GetBestRailtype(const CompanyID company)
{
if (HasRailtypeAvail(company, RAILTYPE_MAGLEV)) return RAILTYPE_MAGLEV;
@ -226,6 +247,11 @@ RailTypes AddDateIntroducedRailTypes(RailTypes current, Date date)
return rts == current ? rts : AddDateIntroducedRailTypes(rts, date);
}
/**
* Get the rail types the given company can build.
* @param c the company to get the rail types for.
* @return the rail types.
*/
RailTypes GetCompanyRailtypes(CompanyID company)
{
RailTypes rts = RAILTYPES_NONE;
@ -248,6 +274,11 @@ RailTypes GetCompanyRailtypes(CompanyID company)
return AddDateIntroducedRailTypes(rts, _date);
}
/**
* Get the rail type for a given label.
* @param label the railtype label.
* @return the railtype.
*/
RailType GetRailTypeByLabel(RailTypeLabel label)
{
/* Loop through each rail type until the label is found */

43
src/rail.h
View File

@ -360,59 +360,18 @@ int TicksToLeaveDepot(const Train *v);
Foundation GetRailFoundation(Slope tileh, TrackBits bits);
/**
* Finds out if a company has a certain railtype available
* @param company the company in question
* @param railtype requested RailType
* @return true if company has requested RailType available
*/
bool HasRailtypeAvail(const CompanyID company, const RailType railtype);
/**
* Validate functions for rail building.
* @param rail the railtype to check.
* @return true if the current company may build the rail.
*/
bool ValParamRailtype(const RailType rail);
/**
* Returns the "best" railtype a company can build.
* As the AI doesn't know what the BEST one is, we have our own priority list
* here. When adding new railtypes, modify this function
* @param company the company "in action"
* @return The "best" railtype a company has available
*/
RailType GetBestRailtype(const CompanyID company);
RailTypes AddDateIntroducedRailTypes(RailTypes current, Date date);
/**
* Get the rail types the given company can build.
* @param c the company to get the rail types for.
* @return the rail types.
*/
RailType GetBestRailtype(const CompanyID company);
RailTypes GetCompanyRailtypes(const CompanyID c);
/**
* Get the rail type for a given label.
* @param label the railtype label.
* @return the railtype.
*/
RailType GetRailTypeByLabel(RailTypeLabel label);
/**
* Reset all rail type information to its default values.
*/
void ResetRailTypes();
/**
* Resolve sprites of custom rail types
*/
void InitRailTypes();
/**
* Allocate a new rail type label
*/
RailType AllocateRailType(RailTypeLabel label);
#endif /* RAIL_H */

8
src/rail_cmd.cpp
View File

@ -45,7 +45,7 @@ RailtypeInfo _railtypes[RAILTYPE_END];
assert_compile(sizeof(_original_railtypes) <= sizeof(_railtypes));
/**
* Initialize rail type information.
* Reset all rail type information to its default values.
*/
void ResetRailTypes()
{
@ -76,6 +76,9 @@ void ResolveRailTypeGUISprites(RailtypeInfo *rti)
}
}
/**
* Resolve sprites of custom rail types
*/
void InitRailTypes()
{
for (RailType rt = RAILTYPE_BEGIN; rt != RAILTYPE_END; rt++) {
@ -84,6 +87,9 @@ void InitRailTypes()
}
}
/**
* Allocate a new rail type label
*/
RailType AllocateRailType(RailTypeLabel label)
{
for (RailType rt = RAILTYPE_BEGIN; rt != RAILTYPE_END; rt++) {

3
src/rail_map.h
View File

@ -490,9 +490,6 @@ static inline bool HasOnewaySignalBlockingTrackdir(TileIndex tile, Trackdir td)
}
/**
* Return the rail type of tile, or INVALID_RAILTYPE if this is no rail tile.
*/
RailType GetTileRailType(TileIndex tile);
/** The ground 'under' the rail */

22
src/road.cpp
View File

@ -36,6 +36,12 @@ static bool IsPossibleCrossing(const TileIndex tile, Axis ax)
GetFoundationSlope(tile, NULL) == SLOPE_FLAT);
}
/**
* Clean up unneccesary RoadBits of a planed tile.
* @param tile current tile
* @param org_rb planed RoadBits
* @return optimised RoadBits
*/
RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb)
{
if (!IsValidTile(tile)) return ROAD_NONE;
@ -91,6 +97,12 @@ RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb)
return org_rb;
}
/**
* Finds out, whether given company has all given RoadTypes available
* @param company ID of company
* @param rts RoadTypes to test
* @return true if company has all requested RoadTypes available
*/
bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts)
{
RoadTypes avail_roadtypes;
@ -105,11 +117,21 @@ bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts)
return (rts & ~avail_roadtypes) == 0;
}
/**
* Validate functions for rail building.
* @param rt road type to check.
* @return true if the current company may build the road.
*/
bool ValParamRoadType(const RoadType rt)
{
return HasRoadTypesAvail(_current_company, RoadTypeToRoadTypes(rt));
}
/**
* Get the road types the given company can build.
* @param company the company to get the roadtypes for.
* @return the road types.
*/
RoadTypes GetCompanyRoadtypes(CompanyID company)
{
RoadTypes rt = ROADTYPES_NONE;

18
src/road_func.h
View File

@ -148,26 +148,8 @@ static inline RoadBits AxisToRoadBits(Axis a)
return a == AXIS_X ? ROAD_X : ROAD_Y;
}
/**
* Finds out, whether given company has all given RoadTypes available
* @param company ID of company
* @param rts RoadTypes to test
* @return true if company has all requested RoadTypes available
*/
bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts);
/**
* Validate functions for rail building.
* @param rt road type to check.
* @return true if the current company may build the road.
*/
bool ValParamRoadType(const RoadType rt);
/**
* Get the road types the given company can build.
* @param company the company to get the roadtypes for.
* @return the road types.
*/
RoadTypes GetCompanyRoadtypes(const CompanyID company);
void UpdateLevelCrossing(TileIndex tile, bool sound = true);

11
src/road_internal.h
View File

@ -15,21 +15,10 @@
#include "tile_cmd.h"
#include "road_type.h"
/**
* Clean up unneccesary RoadBits of a planed tile.
* @param tile current tile
* @param org_rb planed RoadBits
* @return optimised RoadBits
*/
RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb);
CommandCost CheckAllowRemoveRoad(TileIndex tile, RoadBits remove, Owner owner, RoadType rt, DoCommandFlag flags, bool town_check = true);
/**
* Draw the catenary for tram road bits
* @param ti information about the tile (position, slope)
* @param tram the roadbits to draw the catenary for
*/
void DrawTramCatenary(const TileInfo *ti, RoadBits tram);
#endif /* ROAD_INTERNAL_H */

16
src/road_map.cpp
View File

@ -14,6 +14,22 @@
#include "tunnelbridge_map.h"
/**
* Returns the RoadBits on an arbitrary tile
* Special behaviour:
* - road depots: entrance is treated as road piece
* - road tunnels: entrance is treated as road piece
* - bridge ramps: start of the ramp is treated as road piece
* - bridge middle parts: bridge itself is ignored
*
* If straight_tunnel_bridge_entrance is set a ROAD_X or ROAD_Y
* for bridge ramps and tunnel entrances is returned depending
* on the orientation of the tunnel or bridge.
* @param tile the tile to get the road bits for
* @param rt the road type to get the road bits form
* @param straight_tunnel_bridge_entrance whether to return straight road bits for tunnels/bridges.
* @return the road bits of the given tile
*/
RoadBits GetAnyRoadBits(TileIndex tile, RoadType rt, bool straight_tunnel_bridge_entrance)
{
if (!HasTileRoadType(tile, rt)) return ROAD_NONE;

16
src/road_map.h
View File

@ -536,22 +536,6 @@ static inline DiagDirection GetRoadDepotDirection(TileIndex t)
}
/**
* Returns the RoadBits on an arbitrary tile
* Special behaviour:
* - road depots: entrance is treated as road piece
* - road tunnels: entrance is treated as road piece
* - bridge ramps: start of the ramp is treated as road piece
* - bridge middle parts: bridge itself is ignored
*
* If straight_tunnel_bridge_entrance is set a ROAD_X or ROAD_Y
* for bridge ramps and tunnel entrances is returned depending
* on the orientation of the tunnel or bridge.
* @param tile the tile to get the road bits for
* @param rt the road type to get the road bits form
* @param straight_tunnel_bridge_entrance whether to return straight road bits for tunnels/bridges.
* @return the road bits of the given tile
*/
RoadBits GetAnyRoadBits(TileIndex tile, RoadType rt, bool straight_tunnel_bridge_entrance = false);

4
src/saveload/order_sl.cpp
View File

@ -17,6 +17,10 @@
#include "saveload.h"
/**
* Converts this order from an old savegame's version;
* it moves all bits to the new location.
*/
void Order::ConvertFromOldSavegame()
{
uint8 old_flags = this->flags;

4
src/signs.cpp
View File

@ -22,11 +22,15 @@
SignPool _sign_pool("Sign");
INSTANTIATE_POOL_METHODS(Sign)
/**
* Creates a new sign
*/
Sign::Sign(Owner owner)
{
this->owner = owner;
}
/** Destroy the sign */
Sign::~Sign()
{
free(this->name);

5
src/signs_base.h
View File

@ -28,12 +28,7 @@ struct Sign : SignPool::PoolItem<&_sign_pool> {
byte z;
OwnerByte owner; // placed by this company. Anyone can delete them though. OWNER_NONE for gray signs from old games.
/**
* Creates a new sign
*/
Sign(Owner owner = INVALID_OWNER);
/** Destroy the sign */
~Sign();
void UpdateVirtCoord();

5
src/station.cpp
View File

@ -155,6 +155,11 @@ void Station::AddFacility(StationFacility new_facility_bit, TileIndex facil_xy)
this->build_date = _date;
}
/**
* Marks the tiles of the station as dirty.
*
* @ingroup dirty
*/
void Station::MarkTilesDirty(bool cargo_change) const
{
TileIndex tile = this->train_station.tile;

5
src/station_base.h
View File

@ -199,11 +199,6 @@ public:
void AddFacility(StationFacility new_facility_bit, TileIndex facil_xy);
/**
* Marks the tiles of the station as dirty.
*
* @ingroup dirty
*/
void MarkTilesDirty(bool cargo_change) const;
void UpdateVirtCoord();

76
src/string.cpp
View File

@ -48,6 +48,20 @@ static int CDECL vseprintf(char *str, const char *last, const char *format, va_l
return min((int)diff, vsnprintf(str, diff + 1, format, ap));
}
/**
* Appends characters from one string to another.
*
* Appends the source string to the destination string with respect of the
* terminating null-character and the maximum size of the destination
* buffer.
*
* @note usage ttd_strlcat(dst, src, lengthof(dst));
* @note lengthof() applies only to fixed size arrays
*
* @param dst The buffer containing the target string
* @param src The buffer containing the string to append
* @param size The maximum size of the destination buffer
*/
void ttd_strlcat(char *dst, const char *src, size_t size)
{
assert(size > 0);
@ -60,6 +74,20 @@ void ttd_strlcat(char *dst, const char *src, size_t size)
}
/**
* Copies characters from one buffer to another.
*
* Copies the source string to the destination buffer with respect of the
* terminating null-character and the maximum size of the destination
* buffer.
*
* @note usage ttd_strlcpy(dst, src, lengthof(dst));
* @note lengthof() applies only to fixed size arrays
*
* @param dst The destination buffer
* @param src The buffer containing the string to copy
* @param size The maximum size of the destination buffer
*/
void ttd_strlcpy(char *dst, const char *src, size_t size)
{
assert(size > 0);
@ -70,6 +98,22 @@ void ttd_strlcpy(char *dst, const char *src, size_t size)
}
/**
* Appends characters from one string to another.
*
* Appends the source string to the destination string with respect of the
* terminating null-character and and the last pointer to the last element
* in the destination buffer. If the last pointer is set to NULL no
* boundary check is performed.
*
* @note usage: strecat(dst, src, lastof(dst));
* @note lastof() applies only to fixed size arrays
*
* @param dst The buffer containing the target string
* @param src The buffer containing the string to append
* @param last The pointer to the last element of the destination buffer
* @return The pointer to the terminating null-character in the destination buffer
*/
char *strecat(char *dst, const char *src, const char *last)
{
assert(dst <= last);
@ -82,6 +126,22 @@ char *strecat(char *dst, const char *src, const char *last)
}
/**
* Copies characters from one buffer to another.
*
* Copies the source string to the destination buffer with respect of the
* terminating null-character and the last pointer to the last element in
* the destination buffer. If the last pointer is set to NULL no boundary
* check is performed.
*
* @note usage: strecpy(dst, src, lastof(dst));
* @note lastof() applies only to fixed size arrays
*
* @param dst The destination buffer
* @param src The buffer containing the string to copy
* @param last The pointer to the last element of the destination buffer
* @return The pointer to the terminating null-character in the destination buffer
*/
char *strecpy(char *dst, const char *src, const char *last)
{
assert(dst <= last);
@ -115,6 +175,14 @@ char *CDECL str_fmt(const char *str, ...)
}
/**
* Scans the string for valid characters and if it finds invalid ones,
* replaces them with a question mark '?' (if not ignored)
* @param str the string to validate
* @param last the last valid character of str
* @param allow_newlines whether newlines should be allowed or ignored
* @param ignore whether to ignore or replace with a question mark
*/
void str_validate(char *str, const char *last, bool allow_newlines, bool ignore)
{
/* Assume the ABSOLUTE WORST to be in str as it comes from the outside. */
@ -169,6 +237,13 @@ void str_validate(char *str, const char *last, bool allow_newlines, bool ignore)
*dst = '\0';
}
/**
* Checks whether the given string is valid, i.e. contains only
* valid (printable) characters and is properly terminated.
* @param str The string to validate.
* @param last The last character of the string, i.e. the string
* must be terminated here or earlier.
*/
bool StrValid(const char *str, const char *last)
{
/* Assume the ABSOLUTE WORST to be in str as it comes from the outside. */
@ -193,6 +268,7 @@ bool StrValid(const char *str, const char *last)
return *str == '\0';
}
/** Scans the string for colour codes and strips them */
void str_strip_colours(char *str)
{
char *dst = str;

89
src/string_func.h
View File

@ -29,101 +29,20 @@
#include "core/bitmath_func.hpp"
#include "string_type.h"
/**
* Appends characters from one string to another.
*
* Appends the source string to the destination string with respect of the
* terminating null-character and the maximum size of the destination
* buffer.
*
* @note usage ttd_strlcat(dst, src, lengthof(dst));
* @note lengthof() applies only to fixed size arrays
*
* @param dst The buffer containing the target string
* @param src The buffer containing the string to append
* @param size The maximum size of the destination buffer
*/
void ttd_strlcat(char *dst, const char *src, size_t size);
/**
* Copies characters from one buffer to another.
*
* Copies the source string to the destination buffer with respect of the
* terminating null-character and the maximum size of the destination
* buffer.
*
* @note usage ttd_strlcpy(dst, src, lengthof(dst));
* @note lengthof() applies only to fixed size arrays
*
* @param dst The destination buffer
* @param src The buffer containing the string to copy
* @param size The maximum size of the destination buffer
*/
void ttd_strlcpy(char *dst, const char *src, size_t size);
/**
* Appends characters from one string to another.
*
* Appends the source string to the destination string with respect of the
* terminating null-character and and the last pointer to the last element
* in the destination buffer. If the last pointer is set to NULL no
* boundary check is performed.
*
* @note usage: strecat(dst, src, lastof(dst));
* @note lastof() applies only to fixed size arrays
*
* @param dst The buffer containing the target string
* @param src The buffer containing the string to append
* @param last The pointer to the last element of the destination buffer
* @return The pointer to the terminating null-character in the destination buffer
*/
char *strecat(char *dst, const char *src, const char *last);
/**
* Copies characters from one buffer to another.
*
* Copies the source string to the destination buffer with respect of the
* terminating null-character and the last pointer to the last element in
* the destination buffer. If the last pointer is set to NULL no boundary
* check is performed.
*
* @note usage: strecpy(dst, src, lastof(dst));
* @note lastof() applies only to fixed size arrays
*
* @param dst The destination buffer
* @param src The buffer containing the string to copy
* @param last The pointer to the last element of the destination buffer
* @return The pointer to the terminating null-character in the destination buffer
*/
char *strecpy(char *dst, const char *src, const char *last);
int CDECL seprintf(char *str, const char *last, const char *format, ...) WARN_FORMAT(3, 4);
char *CDECL str_fmt(const char *str, ...) WARN_FORMAT(1, 2);
/**
* Scans the string for valid characters and if it finds invalid ones,
* replaces them with a question mark '?' (if not ignored)
* @param str the string to validate
* @param last the last valid character of str
* @param allow_newlines whether newlines should be allowed or ignored
* @param ignore whether to ignore or replace with a question mark
*/
void str_validate(char *str, const char *last, bool allow_newlines = false, bool ignore = false);
/** Scans the string for colour codes and strips them */
void str_strip_colours(char *str);
/** Convert the given string to lowercase, only works with ASCII! */
void strtolower(char *str);
/**
* Checks whether the given string is valid, i.e. contains only
* valid (printable) characters and is properly terminated.
* @param str The string to validate.
* @param last The last character of the string, i.e. the string
* must be terminated here or earlier.
*/
bool StrValid(const char *str, const char *last);
/**
@ -152,16 +71,8 @@ static inline size_t ttd_strnlen(const char *str, size_t maxlen)
return t - str;
}
/** Convert the md5sum number to a 'hexadecimal' string, return next pos in buffer */
char *md5sumToString(char *buf, const char *last, const uint8 md5sum[16]);
/**
* Only allow certain keys. You can define the filter to be used. This makes
* sure no invalid keys can get into an editbox, like BELL.
* @param key character to be checked
* @param afilter the filter to use
* @return true or false depending if the character is printable/valid or not
*/
bool IsValidChar(WChar key, CharSetFilter afilter);
size_t Utf8Decode(WChar *c, const char *s);