gronod/OpenTTD
1
0
Fork 0
mirror of https://github.com/OpenTTD/OpenTTD.git synced 2025-03-11 18:10:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
rubidium 2011-01-22 09:53:15 +00:00
parent 0cdb1c78cd
commit eb299736c1
33 changed files with 338 additions and 364 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/core/alloc_func.hpp
View File

@ -12,12 +12,13 @@
#ifndef ALLOC_FUNC_HPP
#define ALLOC_FUNC_HPP
/**
/*
* Functions to exit badly with an error message.
* It has to be linked so the error messages are not
* duplicated in each object file making the final
* binary needlessly large.
*/
void NORETURN MallocError(size_t size);
void NORETURN ReallocError(size_t size);

41
src/core/pool_func.hpp
View File

@ -20,6 +20,10 @@
template <class Titem, typename Tindex, size_t Tgrowth_step, size_t Tmax_size, bool Tcache, bool Tzero> \
type Pool<Titem, Tindex, Tgrowth_step, Tmax_size, Tcache, Tzero>
/**
* Create a clean pool.
* @param name The name for the pool.
*/
DEFINE_POOL_METHOD(inline)::Pool(const char *name) :
name(name),
size(0),
@ -31,6 +35,12 @@ DEFINE_POOL_METHOD(inline)::Pool(const char *name) :
alloc_cache(NULL)
{ }
/**
* Resizes the pool so 'index' can be addressed
* @param index index we will allocate later
* @pre index >= this->size
* @pre index < Tmax_size
*/
DEFINE_POOL_METHOD(inline void)::ResizeFor(size_t index)
{
assert(index >= this->size);
@ -44,6 +54,10 @@ DEFINE_POOL_METHOD(inline void)::ResizeFor(size_t index)
this->size = new_size;
}
/**
* Searches for first free index
* @return first free index, NO_FREE_ITEM on failure
*/
DEFINE_POOL_METHOD(inline size_t)::FindFirstFree()
{
size_t index = this->first_free;
@ -69,6 +83,13 @@ DEFINE_POOL_METHOD(inline size_t)::FindFirstFree()
return NO_FREE_ITEM;
}
/**
* Makes given index valid
* @param size size of item
* @param index index of item
* @pre index < this->size
* @pre this->Get(index) == NULL
*/
DEFINE_POOL_METHOD(inline void *)::AllocateItem(size_t size, size_t index)
{
assert(this->data[index] == NULL);
@ -92,6 +113,12 @@ DEFINE_POOL_METHOD(inline void *)::AllocateItem(size_t size, size_t index)
return item;
}
/**
* Allocates new item
* @param size size of item
* @return pointer to allocated item
* @note error() on failure! (no free item)
*/
DEFINE_POOL_METHOD(void *)::GetNew(size_t size)
{
size_t index = this->FindFirstFree();
@ -104,6 +131,13 @@ DEFINE_POOL_METHOD(void *)::GetNew(size_t size)
return this->AllocateItem(size, index);
}
/**
* Allocates new item with given index
* @param size size of item
* @param index index of item
* @return pointer to allocated item
* @note usererror() on failure! (index out of range or already used)
*/
DEFINE_POOL_METHOD(void *)::GetNew(size_t size, size_t index)
{
if (index >= Tmax_size) {
@ -119,6 +153,12 @@ DEFINE_POOL_METHOD(void *)::GetNew(size_t size, size_t index)
return this->AllocateItem(size, index);
}
/**
* Deallocates memory used by this index and marks item as free
* @param index item to deallocate
* @pre unit is allocated (non-NULL)
* @note 'delete NULL' doesn't cause call of this function, so it is safe
*/
DEFINE_POOL_METHOD(void)::FreeItem(size_t index)
{
assert(index < this->size);
@ -136,6 +176,7 @@ DEFINE_POOL_METHOD(void)::FreeItem(size_t index)
if (!this->cleaning) Titem::PostDestructor(index);
}
/** Destroys all items in the pool and resets all member variables. */
DEFINE_POOL_METHOD(void)::CleanPool()
{
this->cleaning = true;

41
src/core/pool_type.hpp
View File

@ -37,9 +37,7 @@ struct Pool {
Titem **data; ///< Pointer to array of pointers to Titem
/** Constructor */
Pool(const char *name);
/** Destroys all items in the pool and resets all member variables */
void CleanPool();
/**
@ -238,52 +236,13 @@ private:
/** Cache of freed pointers */
AllocCache *alloc_cache;
/**
* Makes given index valid
* @param size size of item
* @param index index of item
* @pre index < this->size
* @pre this->Get(index) == NULL
*/
void *AllocateItem(size_t size, size_t index);
/**
* Resizes the pool so 'index' can be addressed
* @param index index we will allocate later
* @pre index >= this->size
* @pre index < Tmax_size
*/
void ResizeFor(size_t index);
/**
* Searches for first free index
* @return first free index, NO_FREE_ITEM on failure
*/
size_t FindFirstFree();
/**
* Allocates new item
* @param size size of item
* @return pointer to allocated item
* @note error() on failure! (no free item)
*/
void *GetNew(size_t size);
/**
* Allocates new item with given index
* @param size size of item
* @param index index of item
* @return pointer to allocated item
* @note usererror() on failure! (index out of range or already used)
*/
void *GetNew(size_t size, size_t index);
/**
* Deallocates memory used by this index and marks item as free
* @param index item to deallocate
* @pre unit is allocated (non-NULL)
* @note 'delete NULL' doesn't cause call of this function, so it is safe
*/
void FreeItem(size_t index);
};

17
src/core/random_func.cpp
View File

@ -15,6 +15,10 @@
Randomizer _random, _interactive_random;
/**
* Generate the next pseudo random number
* @return the random number
*/
uint32 Randomizer::Next()
{
const uint32 s = this->state[0];
@ -24,17 +28,30 @@ uint32 Randomizer::Next()
return this->state[1] = ROR(s, 3) - 1;
}
/**
* Generate the next pseudo random number scaled to max
* @param max the maximum value of the returned random number
* @return the random number
*/
uint32 Randomizer::Next(uint32 max)
{
return ((uint64)this->Next() * (uint64)max) >> 32;
}
/**
* (Re)set the state of the random number generator.
* @param seed the new state
*/
void Randomizer::SetSeed(uint32 seed)
{
this->state[0] = seed;
this->state[1] = seed;
}
/**
* (Re)set the state of the random number generators.
* @param seed the new state
*/
void SetRandomSeed(uint32 seed)
{
_random.SetSeed(seed);

15
src/core/random_func.hpp
View File

@ -37,23 +37,8 @@ struct Randomizer {
/** The state of the randomizer */
uint32 state[2];
/**
* Generate the next pseudo random number
* @return the random number
*/
uint32 Next();
/**
* Generate the next pseudo random number scaled to max
* @param max the maximum value of the returned random number
* @return the random number
*/
uint32 Next(uint32 max);
/**
* (Re)set the state of the random number generator.
* @param seed the new state
*/
void SetSeed(uint32 seed);
};
extern Randomizer _random; ///< Random used in the game state calculations

70
src/network/core/address.cpp
View File

@ -16,6 +16,11 @@
#include "address.h"
#include "../../debug.h"
/**
* Get the hostname; in case it wasn't given the
* IPv4 dotted representation is given.
* @return the hostname
*/
const char *NetworkAddress::GetHostname()
{
if (StrEmpty(this->hostname) && this->address.ss_family != AF_UNSPEC) {
@ -25,6 +30,10 @@ const char *NetworkAddress::GetHostname()
return this->hostname;
}
/**
* Get the port.
* @return the port.
*/
uint16 NetworkAddress::GetPort() const
{
switch (this->address.ss_family) {
@ -40,6 +49,10 @@ uint16 NetworkAddress::GetPort() const
}
}
/**
* Set the port.
* @param port set the port number.
*/
void NetworkAddress::SetPort(uint16 port)
{
switch (this->address.ss_family) {
@ -57,6 +70,12 @@ void NetworkAddress::SetPort(uint16 port)
}
}
/**
* Get the address as a string, e.g. 127.0.0.1:12345.
* @param buffer the buffer to write to
* @param last the last element in the buffer
* @param with_family whether to add the family (e.g. IPvX).
*/
void NetworkAddress::GetAddressAsString(char *buffer, const char *last, bool with_family)
{
if (this->GetAddress()->ss_family == AF_INET6) buffer = strecpy(buffer, "[", last);
@ -75,6 +94,12 @@ void NetworkAddress::GetAddressAsString(char *buffer, const char *last, bool wit
}
}
/**
* Get the address as a string, e.g. 127.0.0.1:12345.
* @param with_family whether to add the family (e.g. IPvX).
* @return the address
* @note NOT thread safe
*/
const char *NetworkAddress::GetAddressAsString(bool with_family)
{
/* 6 = for the : and 5 for the decimal port number */
@ -94,6 +119,10 @@ static SOCKET ResolveLoopProc(addrinfo *runp)
return !INVALID_SOCKET;
}
/**
* Get the address in its internal representation.
* @return the address
*/
const sockaddr_storage *NetworkAddress::GetAddress()
{
if (!this->IsResolved()) {
@ -107,6 +136,11 @@ const sockaddr_storage *NetworkAddress::GetAddress()
return &this->address;
}
/**
* Checks of this address is of the given family.
* @param family the family to check against
* @return true if it is of the given family
*/
bool NetworkAddress::IsFamily(int family)
{
if (!this->IsResolved()) {
@ -115,6 +149,12 @@ bool NetworkAddress::IsFamily(int family)
return this->address.ss_family == family;
}
/**
* Checks whether this IP address is contained by the given netmask.
* @param netmask the netmask in CIDR notation to test against.
* @note netmask without /n assumes all bits need to match.
* @return true if this IP is within the netmask.
*/
bool NetworkAddress::IsInNetmask(char *netmask)
{
/* Resolve it if we didn't do it already */
@ -169,6 +209,15 @@ bool NetworkAddress::IsInNetmask(char *netmask)
return true;
}
/**
* Resolve this address into a socket
* @param family the type of 'protocol' (IPv4, IPv6)
* @param socktype the type of socket (TCP, UDP, etc)
* @param flags the flags to send to getaddrinfo
* @param sockets the list of sockets to add the sockets to
* @param func the inner working while looping over the address info
* @return the resolved socket or INVALID_SOCKET.
*/
SOCKET NetworkAddress::Resolve(int family, int socktype, int flags, SocketList *sockets, LoopProc func)
{
struct addrinfo *ai;
@ -266,6 +315,10 @@ static SOCKET ConnectLoopProc(addrinfo *runp)
return sock;
}
/**
* Connect to the given address.
* @return the connected socket or INVALID_SOCKET.
*/
SOCKET NetworkAddress::Connect()
{
DEBUG(net, 1, "Connecting to %s", this->GetAddressAsString());
@ -324,6 +377,11 @@ static SOCKET ListenLoopProc(addrinfo *runp)
return sock;
}
/**
* Make the given socket listen.
* @param socktype the type of socket (TCP, UDP, etc)
* @param sockets the list of sockets to add the sockets to
*/
void NetworkAddress::Listen(int socktype, SocketList *sockets)
{
assert(sockets != NULL);
@ -340,6 +398,12 @@ void NetworkAddress::Listen(int socktype, SocketList *sockets)
}
}
/**
* Convert the socket type into a string
* @param socktype the socket type to convert
* @return the string representation
* @note only works for SOCK_STREAM and SOCK_DGRAM
*/
/* static */ const char *NetworkAddress::SocketTypeAsString(int socktype)
{
switch (socktype) {
@ -349,6 +413,12 @@ void NetworkAddress::Listen(int socktype, SocketList *sockets)
}
}
/**
* Convert the address family into a string
* @param family the family to convert
* @return the string representation
* @note only works for AF_INET, AF_INET6 and AF_UNSPEC
*/
/* static */ const char *NetworkAddress::AddressFamilyAsString(int family)
{
switch (family) {

77
src/network/core/address.h
View File

@ -41,15 +41,6 @@ private:
*/
typedef SOCKET (*LoopProc)(addrinfo *runp);
/**
* Resolve this address into a socket
* @param family the type of 'protocol' (IPv4, IPv6)
* @param socktype the type of socket (TCP, UDP, etc)
* @param flags the flags to send to getaddrinfo
* @param sockets the list of sockets to add the sockets to
* @param func the inner working while looping over the address info
* @return the resolved socket or INVALID_SOCKET.
*/
SOCKET Resolve(int family, int socktype, int flags, SocketList *sockets, LoopProc func);
public:
/**
@ -105,33 +96,9 @@ public:
memcpy(this, &address, sizeof(*this));
}
/**
* Get the hostname; in case it wasn't given the
* IPv4 dotted representation is given.
* @return the hostname
*/
const char *GetHostname();
/**
* Get the address as a string, e.g. 127.0.0.1:12345.
* @param buffer the buffer to write to
* @param last the last element in the buffer
* @param with_family whether to add the family (e.g. IPvX).
*/
void GetAddressAsString(char *buffer, const char *last, bool with_family = true);
/**
* Get the address as a string, e.g. 127.0.0.1:12345.
* @param with_family whether to add the family (e.g. IPvX).
* @return the address
* @note NOT thread safe
*/
const char *GetAddressAsString(bool with_family = true);
/**
* Get the address in its internal representation.
* @return the address
*/
const sockaddr_storage *GetAddress();
/**
@ -145,16 +112,7 @@ public:
return this->address_length;
}
/**
* Get the port
* @return the port
*/
uint16 GetPort() const;
/**
* Set the port
* @param port set the port number
*/
void SetPort(uint16 port);
/**
@ -166,19 +124,7 @@ public:
return this->address_length != 0;
}
/**
* Checks of this address is of the given family.
* @param family the family to check against
* @return true if it is of the given family
*/
bool IsFamily(int family);
/**
* Checks whether this IP address is contained by the given netmask.
* @param netmask the netmask in CIDR notation to test against.
* @note netmask without /n assumes all bits need to match.
* @return true if this IP is within the netmask.
*/
bool IsInNetmask(char *netmask);
/**
@ -233,33 +179,10 @@ public:
return this->CompareTo(address) < 0;
}
/**
* Connect to the given address.
* @return the connected socket or INVALID_SOCKET.
*/
SOCKET Connect();
/**
* Make the given socket listen.
* @param socktype the type of socket (TCP, UDP, etc)
* @param sockets the list of sockets to add the sockets to
*/
void Listen(int socktype, SocketList *sockets);
/**
* Convert the socket type into a string
* @param socktype the socket type to convert
* @return the string representation
* @note only works for SOCK_STREAM and SOCK_DGRAM
*/
static const char *SocketTypeAsString(int socktype);
/**
* Convert the address family into a string
* @param family the family to convert
* @return the string representation
* @note only works for AF_INET, AF_INET6 and AF_UNSPEC
*/
static const char *AddressFamilyAsString(int family);
};

17
src/network/core/tcp.h
View File

@ -58,13 +58,8 @@ private:
bool killed; ///< Whether we got killed
SOCKET sock; ///< The socket we're connecting with
/** The actual connection function */
void Connect();
/**
* Entry point for the new threads.
* @param param the TCPConnecter instance to call Connect on.
*/
static void ThreadEntry(void *param);
protected:
@ -72,10 +67,6 @@ protected:
NetworkAddress address;
public:
/**
* Create a new connecter for the given address
* @param address the (un)resolved address to connect to
*/
TCPConnecter(const NetworkAddress &address);
/** Silence the warnings */
virtual ~TCPConnecter() {}
@ -91,15 +82,7 @@ public:
*/
virtual void OnFailure() {}
/**
* Check whether we need to call the callback, i.e. whether we
* have connected or aborted and call the appropriate callback
* for that. It's done this way to ease on the locking that
* would otherwise be needed everywhere.
*/
static void CheckCallbacks();
/** Kill all connection attempts. */
static void KillAll();
};

17
src/network/core/tcp_connect.cpp
View File

@ -21,6 +21,10 @@
/** List of connections that are currently being created */
static SmallVector<TCPConnecter *, 1> _tcp_connecters;
/**
* Create a new connecter for the given address
* @param address the (un)resolved address to connect to
*/
TCPConnecter::TCPConnecter(const NetworkAddress &address) :
connected(false),
aborted(false),
@ -34,6 +38,7 @@ TCPConnecter::TCPConnecter(const NetworkAddress &address) :
}
}
/** The actual connection function */
void TCPConnecter::Connect()
{
this->sock = this->address.Connect();
@ -44,12 +49,21 @@ void TCPConnecter::Connect()
}
}
/**
* Entry point for the new threads.
* @param param the TCPConnecter instance to call Connect on.
*/
/* static */ void TCPConnecter::ThreadEntry(void *param)
{
static_cast<TCPConnecter*>(param)->Connect();
}
/**
* Check whether we need to call the callback, i.e. whether we
* have connected or aborted and call the appropriate callback
* for that. It's done this way to ease on the locking that
* would otherwise be needed everywhere.
*/
/* static */ void TCPConnecter::CheckCallbacks()
{
for (TCPConnecter **iter = _tcp_connecters.Begin(); iter < _tcp_connecters.End(); /* nothing */) {
@ -76,6 +90,7 @@ void TCPConnecter::Connect()
}
}
/** Kill all connection attempts. */
/* static */ void TCPConnecter::KillAll()
{
for (TCPConnecter **iter = _tcp_connecters.Begin(); iter != _tcp_connecters.End(); iter++) (*iter)->killed = true;

20
src/network/core/tcp_content.cpp
View File

@ -16,11 +16,13 @@
#include "../../stdafx.h"
#include "tcp_content.h"
/** Clear everything in the struct */
ContentInfo::ContentInfo()
{
memset(this, 0, sizeof(*this));
}
/** Free everything allocated */
ContentInfo::~ContentInfo()
{
free(this->dependencies);
@ -42,6 +44,10 @@ void ContentInfo::TransferFrom(ContentInfo *other)
}
}
/**
* Get the size of the data as send over the network.
* @return the size.
*/
size_t ContentInfo::Size() const
{
size_t len = 0;
@ -54,6 +60,10 @@ size_t ContentInfo::Size() const
sizeof(*this->dependencies) * this->dependency_count;
}
/**
* Is the state either selected or autoselected?
* @return true iff that's the case
*/
bool ContentInfo::IsSelected() const
{
switch (this->state) {
@ -67,6 +77,10 @@ bool ContentInfo::IsSelected() const
}
}
/**
* Is the information from this content info valid?
* @return true iff it's valid
*/
bool ContentInfo::IsValid() const
{
return this->state < ContentInfo::INVALID && this->type >= CONTENT_TYPE_BEGIN && this->type < CONTENT_TYPE_END;
@ -88,8 +102,10 @@ void NetworkContentSocketHandler::Close()
#define CONTENT_COMMAND(type) case type: return this->NetworkPacketReceive_ ## type ## _command(p); break;
/**
* Handle an incoming packets by sending it to the correct function.
* @param p the received packet
* Handle the given packet, i.e. pass it to the right
* parser receive command.
* @param p the packet to handle
* @return true if we should immediately handle further packets, false otherwise
*/
bool NetworkContentSocketHandler::HandlePacket(Packet *p)
{

24
src/network/core/tcp_content.h
View File

@ -82,30 +82,13 @@ struct ContentInfo {
State state; ///< Whether the content info is selected (for download)
bool upgrade; ///< This item is an upgrade
/** Clear everything in the struct */
ContentInfo();
/** Free everything allocated */
~ContentInfo();
void TransferFrom(ContentInfo *other);
/**
* Get the size of the data as send over the network.
* @return the size.
*/
size_t Size() const;
/**
* Is the state either selected or autoselected?
* @return true iff that's the case
*/
bool IsSelected() const;
/**
* Is the information from this content info valid?
* @return true iff it's valid
*/
bool IsValid() const;
};
@ -187,12 +170,6 @@ protected:
*/
DECLARE_CONTENT_RECEIVE_COMMAND(PACKET_CONTENT_SERVER_CONTENT);
/**
* Handle the given packet, i.e. pass it to the right
* parser receive command.
* @param p the packet to handle
* @return true if we should immediately handle further packets, false otherwise
*/
bool HandlePacket(Packet *p);
public:
/**
@ -209,7 +186,6 @@ public:
/** On destructing of this class, the socket needs to be closed */
virtual ~NetworkContentSocketHandler() { this->Close(); }
/** Do the actual receiving of packets. */
void ReceivePackets();
};

19
src/network/core/tcp_http.cpp
View File

@ -23,6 +23,14 @@
/** List of open HTTP connections. */
static SmallVector<NetworkHTTPSocketHandler *, 1> _http_connections;
/**
* Start the querying
* @param sock the socket of this connection
* @param callback the callback for HTTP retrieval
* @param url the url at the server
* @param data the data to send
* @param depth the depth (redirect recursion) of the queries
*/
NetworkHTTPSocketHandler::NetworkHTTPSocketHandler(SOCKET s,
HTTPCallback *callback, const char *host, const char *url,
const char *data, int depth) :
@ -57,6 +65,7 @@ NetworkHTTPSocketHandler::NetworkHTTPSocketHandler(SOCKET s,
*_http_connections.Append() = this;
}
/** Free whatever needs to be freed. */
NetworkHTTPSocketHandler::~NetworkHTTPSocketHandler()
{
this->CloseConnection();
@ -175,6 +184,13 @@ int NetworkHTTPSocketHandler::HandleHeader()
return 0;
}
/**
* Connect to the given URI.
* @param uri the URI to connect to.
* @param callback the callback to send data back on.
* @param data the data we want to send (as POST).
* @param depth the recursion/redirect depth.
*/
/* static */ int NetworkHTTPSocketHandler::Connect(char *uri, HTTPCallback *callback, const char *data, int depth)
{
char *hname = strstr(uri, "://");
@ -274,6 +290,9 @@ int NetworkHTTPSocketHandler::Receive()
}
}
/**
* Do the receiving for all HTTP connections.
*/
/* static */ void NetworkHTTPSocketHandler::HTTPReceive()
{
/* No connections, just bail out. */

19
src/network/core/tcp_http.h
View File

@ -64,33 +64,14 @@ public:
virtual NetworkRecvStatus CloseConnection(bool error = true);
/**
* Start the querying
* @param sock the socket of this connection
* @param callback the callback for HTTP retrieval
* @param url the url at the server
* @param data the data to send
* @param depth the depth (redirect recursion) of the queries
*/
NetworkHTTPSocketHandler(SOCKET sock, HTTPCallback *callback,
const char *host, const char *url, const char *data, int depth);
/** Free whatever needs to be freed. */
~NetworkHTTPSocketHandler();
/**
* Connect to the given URI.
* @param uri the URI to connect to.
* @param callback the callback to send data back on.
* @param data the data we want to send (as POST).
* @param depth the recursion/redirect depth.
*/
static int Connect(char *uri, HTTPCallback *callback,
const char *data = NULL, int depth = 0);
/**
* Do the receiving for all HTTP connections.
*/
static void HTTPReceive();
};

1
src/network/network_content.cpp
View File

@ -982,6 +982,7 @@ void ClientNetworkContentSocketHandler::CheckDependencyState(ContentInfo *ci)
}
}
/** Clear all downloaded content information. */
void ClientNetworkContentSocketHandler::Clear()
{
for (ContentIterator iter = this->infos.Begin(); iter != this->infos.End(); iter++) delete *iter;

2
src/network/network_content.h
View File

@ -136,7 +136,7 @@ public:
ConstContentIterator Get(uint32 index) const { return this->infos.Get(index); }
/** Get the end of the content inf iterator. */
ConstContentIterator End() const { return this->infos.End(); }
/** Clear all downloaded content information. */
void Clear();
/** Add a callback to this class */

1
src/network/network_internal.h
View File

@ -161,7 +161,6 @@ void NetworkExecuteLocalCommandQueue();
void NetworkFreeLocalCommandQueue();
void NetworkSyncCommandQueue(NetworkClientSocket *cs);
/* from network.c */
void NetworkError(StringID error_string);
void NetworkTextMessage(NetworkAction action, TextColour colour, bool self_send, const char *name, const char *str = "", int64 data = 0);
uint NetworkCalculateLag(const NetworkClientSocket *cs);

6
src/newgrf_canal.cpp
View File

@ -97,6 +97,12 @@ static void NewCanalResolver(ResolverObject *res, TileIndex tile, const GRFFile
}
/**
* Lookup the base sprite to use for a canal.
* @param feature Which canal feature we want.
* @param tile Tile index of canal, if appropriate.
* @return Base sprite returned by GRF, or 0 if none.
*/
SpriteID GetCanalSprite(CanalFeature feature, TileIndex tile)
{
ResolverObject object;

6
src/newgrf_canal.h
View File

@ -50,12 +50,6 @@ struct WaterFeature {
extern WaterFeature _water_feature[CF_END];
/**
* Lookup the base sprite to use for a canal.
* @param feature Which canal feature we want.
* @param tile Tile index of canal, if appropriate.
* @return Base sprite returned by GRF, or 0 if none.
*/
SpriteID GetCanalSprite(CanalFeature feature, TileIndex tile);
uint GetCanalSpriteOffset(CanalFeature feature, TileIndex tile, uint cur_offset);

57
src/newgrf_class.h
View File

@ -27,75 +27,18 @@ struct NewGRFClass {
/** The actual classes. */
static NewGRFClass<Tspec, Tid, Tmax> classes[Tmax];
/** Reset the classes, i.e. clear everything. */
static void Reset();
/** Initialise the defaults. */
static void InsertDefaults();
/**
* Allocate a class with a given global class ID.
* @param cls_id The global class id, such as 'DFLT'.
* @return The (non global!) class ID for the class.
* @note Upon allocating the same global class ID for a
* second time, this first allocation will be given.
*/
static Tid Allocate(uint32 global_id);
/**
* Set the name of a particular class.
* @param cls_id The id for the class.
* @pre index < GetCount(cls_id)
* @param name The new name for the class.
*/
static void SetName(Tid cls_id, StringID name);
/**
* Assign a spec to one of the classes.
* @param spec The spec to assign.
* @note The spec must have a valid class id set.
*/
static void Assign(Tspec *spec);
/**
* Get the name of a particular class.
* @param cls_id The class to get the name of.
* @pre index < GetCount(cls_id)
* @return The name of said class.
*/
static StringID GetName(Tid cls_id);
/**
* Get the number of allocated classes.
* @return The number of classes.
*/
static uint GetCount();
/**
* Get the number of allocated specs within a particular class.
* @param cls_id The class to get the size of.
* @pre cls_id < GetCount()
* @return The size of the class.
*/
static uint GetCount(Tid cls_id);
/**
* Get a spec from a particular class at a given index.
* @param cls_id The class to get the spec from.
* @param index The index where to find the spec.
* @pre index < GetCount(cls_id)
* @return The spec at given location.
*/
static const Tspec *Get(Tid cls_id, uint index);
/**
* Retrieve a spec by GRF location.
* @param grfid GRF ID of spec.
* @param local_id Index within GRF file of spec.
* @param index Pointer to return the index of the spec in its class. If NULL then not used.
* @return The spec.
*/
static const Tspec *GetByGrf(uint32 grfid, byte local_id, int *index);
};

49
src/newgrf_class_func.h
View File

@ -21,6 +21,7 @@
template <typename Tspec, typename Tid, Tid Tmax>
NewGRFClass<Tspec, Tid, Tmax> NewGRFClass<Tspec, Tid, Tmax>::classes[Tmax];
/** Reset the classes, i.e. clear everything. */
DEFINE_NEWGRF_CLASS_METHOD(void)::Reset()
{
for (Tid i = (Tid)0; i < Tmax; i++) {
@ -35,6 +36,13 @@ DEFINE_NEWGRF_CLASS_METHOD(void)::Reset()
InsertDefaults();
}
/**
* Allocate a class with a given global class ID.
* @param cls_id The global class id, such as 'DFLT'.
* @return The (non global!) class ID for the class.
* @note Upon allocating the same global class ID for a
* second time, this first allocation will be given.
*/
DEFINE_NEWGRF_CLASS_METHOD(Tid)::Allocate(uint32 global_id)
{
for (Tid i = (Tid)0; i < Tmax; i++) {
@ -52,12 +60,23 @@ DEFINE_NEWGRF_CLASS_METHOD(Tid)::Allocate(uint32 global_id)
return (Tid)0;
}
/**
* Set the name of a particular class.
* @param cls_id The id for the class.
* @pre index < GetCount(cls_id)
* @param name The new name for the class.
*/
DEFINE_NEWGRF_CLASS_METHOD(void)::SetName(Tid cls_id, StringID name)
{
assert(cls_id < Tmax);
classes[cls_id].name = name;
}
/**
* Assign a spec to one of the classes.
* @param spec The spec to assign.
* @note The spec must have a valid class id set.
*/
DEFINE_NEWGRF_CLASS_METHOD(void)::Assign(Tspec *spec)
{
assert(spec->cls_id < Tmax);
@ -69,12 +88,22 @@ DEFINE_NEWGRF_CLASS_METHOD(void)::Assign(Tspec *spec)
cls->spec[i] = spec;
}
/**
* Get the name of a particular class.
* @param cls_id The class to get the name of.
* @pre index < GetCount(cls_id)
* @return The name of said class.
*/
DEFINE_NEWGRF_CLASS_METHOD(StringID)::GetName(Tid cls_id)
{
assert(cls_id < Tmax);
return classes[cls_id].name;
}
/**
* Get the number of allocated classes.
* @return The number of classes.
*/
DEFINE_NEWGRF_CLASS_METHOD(uint)::GetCount()
{
uint i;
@ -82,12 +111,25 @@ DEFINE_NEWGRF_CLASS_METHOD(uint)::GetCount()
return i;
}
/**
* Get the number of allocated specs within a particular class.
* @param cls_id The class to get the size of.
* @pre cls_id < GetCount()
* @return The size of the class.
*/
DEFINE_NEWGRF_CLASS_METHOD(uint)::GetCount(Tid cls_id)
{
assert(cls_id < Tmax);
return classes[cls_id].count;
}
/**
* Get a spec from a particular class at a given index.
* @param cls_id The class to get the spec from.
* @param index The index where to find the spec.
* @pre index < GetCount(cls_id)
* @return The spec at given location.
*/
DEFINE_NEWGRF_CLASS_METHOD(const Tspec *)::Get(Tid cls_id, uint index)
{
assert(cls_id < Tmax);
@ -97,6 +139,13 @@ DEFINE_NEWGRF_CLASS_METHOD(const Tspec *)::Get(Tid cls_id, uint index)
return NULL;
}
/**
* Retrieve a spec by GRF location.
* @param grfid GRF ID of spec.
* @param local_id Index within GRF file of spec.
* @param index Pointer to return the index of the spec in its class. If NULL then not used.
* @return The spec.
*/
DEFINE_NEWGRF_CLASS_METHOD(const Tspec *)::GetByGrf(uint32 grfid, byte local_id, int *index)
{
uint j;

39
src/newgrf_debug.h
View File

@ -34,52 +34,13 @@ struct NewGrfDebugSpritePicker {
extern NewGrfDebugSpritePicker _newgrf_debug_sprite_picker;
/**
* Can we inspect the data given a certain feature and index.
* The index is normally an in-game location/identifier, such
* as a TileIndex or an IndustryID depending on the feature
* we want to inspect.
* @param feature The feature we want to inspect.
* @param index The index/identifier of the feature to inspect.
* @return true if there is something to show.
*/
bool IsNewGRFInspectable(GrfSpecFeature feature, uint index);
/**
* Show the inspect window for a given feature and index.
* The index is normally an in-game location/identifier, such
* as a TileIndex or an IndustryID depending on the feature
* we want to inspect.
* @param feature The feature we want to inspect.
* @param index The index/identifier of the feature to inspect.
*/
void ShowNewGRFInspectWindow(GrfSpecFeature feature, uint index);
/**
* Delete inspect window for a given feature and index.
* The index is normally an in-game location/identifier, such
* as a TileIndex or an IndustryID depending on the feature
* we want to inspect.
* @param feature The feature we want to delete the window for.
* @param index The index/identifier of the feature to delete.
*/
void DeleteNewGRFInspectWindow(GrfSpecFeature feature, uint index);
/**
* Get the GrfSpecFeature associated with the tile.
* @return the GrfSpecFeature.
*/
GrfSpecFeature GetGrfSpecFeature(TileIndex tile);
/**
* Get the GrfSpecFeature associated with the vehicle.
* @return the GrfSpecFeature.
*/
GrfSpecFeature GetGrfSpecFeature(VehicleType type);
/**
* Show the window for aligning sprites.
*/
void ShowSpriteAlignerWindow();
#endif /* NEWGRF_DEBUG_H */

38
src/newgrf_debug_gui.cpp
View File

@ -487,6 +487,14 @@ static const WindowDesc _newgrf_inspect_desc(
_nested_newgrf_inspect_widgets, lengthof(_nested_newgrf_inspect_widgets)
);
/**
* Show the inspect window for a given feature and index.
* The index is normally an in-game location/identifier, such
* as a TileIndex or an IndustryID depending on the feature
* we want to inspect.
* @param feature The feature we want to inspect.
* @param index The index/identifier of the feature to inspect.
*/
void ShowNewGRFInspectWindow(GrfSpecFeature feature, uint index)
{
if (!IsNewGRFInspectable(feature, index)) return;
@ -495,6 +503,14 @@ void ShowNewGRFInspectWindow(GrfSpecFeature feature, uint index)
AllocateWindowDescFront<NewGRFInspectWindow>(&_newgrf_inspect_desc, wno);
}
/**
* Delete inspect window for a given feature and index.
* The index is normally an in-game location/identifier, such
* as a TileIndex or an IndustryID depending on the feature
* we want to inspect.
* @param feature The feature we want to delete the window for.
* @param index The index/identifier of the feature to delete.
*/
void DeleteNewGRFInspectWindow(GrfSpecFeature feature, uint index)
{
if (feature == GSF_INVALID) return;
@ -507,6 +523,15 @@ void DeleteNewGRFInspectWindow(GrfSpecFeature feature, uint index)
if (w != NULL) w->ReInit();
}
/**
* Can we inspect the data given a certain feature and index.
* The index is normally an in-game location/identifier, such
* as a TileIndex or an IndustryID depending on the feature
* we want to inspect.
* @param feature The feature we want to inspect.
* @param index The index/identifier of the feature to inspect.
* @return true if there is something to show.
*/
bool IsNewGRFInspectable(GrfSpecFeature feature, uint index)
{
const NIFeature *nif = GetFeature(GetInspectWindowNumber(feature, index));
@ -514,6 +539,11 @@ bool IsNewGRFInspectable(GrfSpecFeature feature, uint index)
return nif->helper->IsInspectable(index);
}
/**
* Get the GrfSpecFeature associated with the tile.
* @param tile The tile to get the feature from.
* @return the GrfSpecFeature.
*/
GrfSpecFeature GetGrfSpecFeature(TileIndex tile)
{
switch (GetTileType(tile)) {
@ -533,6 +563,11 @@ GrfSpecFeature GetGrfSpecFeature(TileIndex tile)
}
}
/**
* Get the GrfSpecFeature associated with the vehicle.
* @param type The vehicle type to get the feature from.
* @return the GrfSpecFeature.
*/
GrfSpecFeature GetGrfSpecFeature(VehicleType type)
{
switch (type) {
@ -813,6 +848,9 @@ static const WindowDesc _sprite_aligner_desc(
_nested_sprite_aligner_widgets, lengthof(_nested_sprite_aligner_widgets)
);
/**
* Show the window for aligning sprites.
*/
void ShowSpriteAlignerWindow()
{
AllocateWindowDescFront<SpriteAlignerWindow>(&_sprite_aligner_desc, 0);

18
src/newgrf_object.cpp
View File

@ -35,17 +35,31 @@ extern const ObjectSpec _original_objects[NEW_OBJECT_OFFSET];
/** All the object specifications. */
ObjectSpec _object_specs[NUM_OBJECTS];
/**
* Get the specification associated with a specific ObjectType.
* @param index The object type to fetch.
* @return The specification.
*/
/* static */ const ObjectSpec *ObjectSpec::Get(ObjectType index)
{
assert(index < NUM_OBJECTS);
return &_object_specs[index];
}
/**
* Get the specification associated with a tile.
* @param tile The tile to fetch the data for.
* @return The specification.
*/
/* static */ const ObjectSpec *ObjectSpec::GetByTile(TileIndex tile)
{
return ObjectSpec::Get(GetObjectType(tile));
}
/**
* Check whether the object is available at this time.
* @return true if it is available.
*/
bool ObjectSpec::IsAvailable() const
{
return this->enabled && _date > this->introduction_date &&
@ -54,6 +68,10 @@ bool ObjectSpec::IsAvailable() const
(flags & (_game_mode != GM_EDITOR ? OBJECT_FLAG_ONLY_IN_SCENEDIT : OBJECT_FLAG_ONLY_IN_GAME)) == 0;
}
/**
* Gets the index of this spec.
* @return The index.
*/
uint ObjectSpec::Index() const
{
return this - _object_specs;

22
src/newgrf_object.h
View File

@ -72,12 +72,6 @@ struct ObjectSpec {
uint8 views; ///< The number of views.
bool enabled; ///< Is this spec enabled?
/**
* Check whether the object is available at this time.
* @return true if it is available.
*/
bool IsAvailable() const;
/**
* Get the cost for building a structure of this type.
* @return The cost for building.
@ -90,24 +84,10 @@ struct ObjectSpec {
*/
Money GetClearCost() const { return (_price[PR_CLEAR_OBJECT] * this->clear_cost_multiplier); }
/**
* Gets the index of this spec.
* @return The index.
*/
bool IsAvailable() const;
uint Index() const;
/**
* Get the specification associated with a specific ObjectType.
* @param index The object type to fetch.
* @return The specification.
*/
static const ObjectSpec *Get(ObjectType index);
/**
* Get the specification associated with a tile.
* @param tile The tile to fetch the data for.
* @return The specification.
*/
static const ObjectSpec *GetByTile(TileIndex tile);
};

16
src/newgrf_storage.cpp
View File

@ -16,11 +16,27 @@
/** The changed storage arrays */
static std::set<BaseStorageArray*> _changed_storage_arrays;
/**
* Add the changed storage array to the list of changed arrays.
* This is done so we only have to revert/save the changed
* arrays, which saves quite a few clears, etc. after callbacks.
* @param storage the array that has changed
*/
void AddChangedStorage(BaseStorageArray *storage)
{
_changed_storage_arrays.insert(storage);
}
/**
* Clear the changes made since the last ClearStorageChanges.
* This is done for *all* storages that have been registered to with
* AddChangedStorage since the previous ClearStorageChanges.
*
* This can be done in two ways:
* - saving the changes permanently
* - reverting to the previous version
* @param keep_changes do we save or revert the changes since the last ClearChanges?
*/
void ClearStorageChanges(bool keep_changes)
{
/* Loop over all changes arrays */

22
src/newgrf_storage.h
View File

@ -105,6 +105,10 @@ struct PersistentStorageArray : BaseStorageArray {
return this->storage[pos];
}
/**
* Clear the changes, or assign them permanently to the storage.
* @param keep_changes Whether to assign or ditch the changes.
*/
void ClearChanges(bool keep_changes)
{
assert(this->prev_storage != NULL);
@ -166,25 +170,7 @@ struct TemporaryStorageArray : BaseStorageArray {
}
};
/**
* Add the changed storage array to the list of changed arrays.
* This is done so we only have to revert/save the changed
* arrays, which saves quite a few clears, etc. after callbacks.
* @param storage the array that has changed
*/
void AddChangedStorage(BaseStorageArray *storage);
/**
* Clear the changes made since the last ClearStorageChanges.
* This is done for *all* storages that have been registered to with
* AddChangedStorage since the previous ClearStorageChanges.
*
* This can be done in two ways:
* - saving the changes permanently
* - reverting to the previous version
* @param keep_changes do we save or revert the changes since the last ClearChanges?
*/
void ClearStorageChanges(bool keep_changes);
#endif /* NEWGRF_STORAGE_H */

9
src/news_func.h
View File

@ -51,17 +51,8 @@ extern bool _news_ticker_sound;
extern NewsTypeData _news_type_data[];
/**
* Delete a news item type about a vehicle
* if the news item type is INVALID_STRING_ID all news about the vehicle get
* deleted
*/
void DeleteVehicleNews(VehicleID vid, StringID news);
/** Delete news associated with given station */
void DeleteStationNews(StationID sid);
/** Delete news associated with given station */
void DeleteIndustryNews(IndustryID iid);
#endif /* NEWS_FUNC_H */

6
src/news_gui.cpp
View File

@ -754,6 +754,12 @@ static void DeleteNewsItem(NewsItem *ni)
SetWindowDirty(WC_MESSAGE_HISTORY, 0);
}
/**
* Delete a news item type about a vehicle.
* When the news item type is INVALID_STRING_ID all news about the vehicle gets deleted.
* @param vid The vehicle to remove the news for.
* @param news The news type to remove.
*/
void DeleteVehicleNews(VehicleID vid, StringID news)
{
NewsItem *ni = _oldest_news;

8
src/saveload/newgrf_sl.cpp
View File

@ -24,6 +24,10 @@ static const SaveLoad _newgrf_mapping_desc[] = {
SLE_END()
};
/**
* Save a GRF ID + local id -> OpenTTD's id mapping.
* @param mapping The mapping to save.
*/
void Save_NewGRFMapping(const OverrideManagerBase &mapping)
{
for (uint i = 0; i < mapping.GetMaxMapping(); i++) {
@ -32,6 +36,10 @@ void Save_NewGRFMapping(const OverrideManagerBase &mapping)
}
}
/**
* Load a GRF ID + local id -> OpenTTD's id mapping.
* @param mapping The mapping to load.
*/
void Load_NewGRFMapping(OverrideManagerBase &mapping)
{
/* Clear the current mapping stored.

9
src/saveload/newgrf_sl.h
View File

@ -14,16 +14,7 @@
#include "../newgrf_commons.h"
/**
* Save a GRF ID + local id -> OpenTTD's id mapping.
* @param mapping The mapping to save.
*/
void Save_NewGRFMapping(const OverrideManagerBase &mapping);
/**
* Load a GRF ID + local id -> OpenTTD's id mapping.
* @param mapping The mapping to load.
*/
void Load_NewGRFMapping(OverrideManagerBase &mapping);
#endif /* SAVELOAD_NEWGRF_SL_H */

4
src/spriteloader/grf.hpp
View File

@ -14,11 +14,9 @@
#include "spriteloader.hpp"
/** Sprite loader for graphics coming from a (New)GRF. */
class SpriteLoaderGrf : public SpriteLoader {
public:
/**
* Load a sprite from the disk and return a sprite struct which is the same for all loaders.
*/
bool LoadSprite(SpriteLoader::Sprite *sprite, uint8 file_slot, size_t file_pos, SpriteType sprite_type);
};

4
src/spriteloader/png.hpp
View File

@ -14,11 +14,9 @@
#include "spriteloader.hpp"
/** Sprite loader for graphics coming from a PNG image. */
class SpriteLoaderPNG : public SpriteLoader {
public:
/**
* Load a sprite from the disk and return a sprite struct which is the same for all loaders.
*/
bool LoadSprite(SpriteLoader::Sprite *sprite, uint8 file_slot, size_t file_pos, SpriteType sprite_type);
};

5
src/spriteloader/spriteloader.hpp
View File

@ -50,6 +50,11 @@ public:
/**
* Load a sprite from the disk and return a sprite struct which is the same for all loaders.
* @param sprite The sprite to fill with data.
* @param file_slot The file "descriptor" of the file we read from.
* @param file_pos The position within the file the image begins.
* @param sprite_type The type of sprite we're trying to load.
* @return true iff loading went okay.
*/
virtual bool LoadSprite(SpriteLoader::Sprite *sprite, uint8 file_slot, size_t file_pos, SpriteType sprite_type) = 0;