summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoralberth <alberth@openttd.org>2012-11-10 20:46:39 +0000
committeralberth <alberth@openttd.org>2012-11-10 20:46:39 +0000
commit33ff55a8f1287643986621e7130e8acddf42b221 (patch)
tree04af02a5ad82e979ec200570b38628dccc860cdf
parent4c9bea2a714da675217522c39113ba2c2c5bbee4 (diff)
downloadopenttd-33ff55a8f1287643986621e7130e8acddf42b221.tar.xz
(svn r24693) -Doc: Add some doxymentation into the newgrf code.
-rw-r--r--src/newgrf_airport.cpp19
-rw-r--r--src/newgrf_airporttiles.cpp15
-rw-r--r--src/newgrf_airporttiles.h6
-rw-r--r--src/newgrf_canal.cpp9
-rw-r--r--src/newgrf_cargo.cpp13
-rw-r--r--src/newgrf_engine.cpp16
-rw-r--r--src/newgrf_engine.h16
-rw-r--r--src/newgrf_generic.cpp11
-rw-r--r--src/newgrf_house.cpp23
-rw-r--r--src/newgrf_house.h5
-rw-r--r--src/newgrf_industries.cpp18
-rw-r--r--src/newgrf_industries.h14
-rw-r--r--src/newgrf_industrytiles.cpp15
-rw-r--r--src/newgrf_industrytiles.h10
-rw-r--r--src/newgrf_object.cpp16
-rw-r--r--src/newgrf_object.h5
-rw-r--r--src/newgrf_railtype.cpp14
-rw-r--r--src/newgrf_railtype.h4
-rw-r--r--src/newgrf_spritegroup.cpp17
-rw-r--r--src/newgrf_spritegroup.h20
-rw-r--r--src/newgrf_station.cpp16
-rw-r--r--src/newgrf_station.h16
-rw-r--r--src/newgrf_town.cpp12
-rw-r--r--src/newgrf_town.h15
24 files changed, 276 insertions, 49 deletions
diff --git a/src/newgrf_airport.cpp b/src/newgrf_airport.cpp
index c56f097c8..4b43af483 100644
--- a/src/newgrf_airport.cpp
+++ b/src/newgrf_airport.cpp
@@ -17,6 +17,7 @@
#include "station_base.h"
#include "newgrf_class_func.h"
+/** Resolver for the airport scope. */
struct AirportScopeResolver : public ScopeResolver {
struct Station *st; ///< Station of the airport for which the callback is run, or \c NULL for build gui.
byte airport_id; ///< Type of airport for which the callback is run.
@@ -222,12 +223,30 @@ void AirportOverrideManager::SetEntitySpec(AirportSpec *as)
this->st->airport.psa->StoreValue(pos, value);
}
+/**
+ * Constructor of the airport resolver.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st %Station of the airport for which the callback is run, or \c NULL for build gui.
+ * @param airport_id Type of airport for which the callback is run.
+ * @param layout Layout of the airport to build.
+ * @param callback Callback ID.
+ * @param param1 First parameter (var 10) of the callback.
+ * @param param2 Second parameter (var 18) of the callback.
+ */
AirportResolverObject::AirportResolverObject(TileIndex tile, Station *st, byte airport_id, byte layout,
CallbackID callback, uint32 param1, uint32 param2)
: ResolverObject(AirportSpec::Get(airport_id)->grf_prop.grffile, callback, param1, param2), airport_scope(this, tile, st, airport_id, layout)
{
}
+/**
+ * Constructor of the scope resolver for an airport.
+ * @param ro Surrounding resolver.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st %Station of the airport for which the callback is run, or \c NULL for build gui.
+ * @param airport_id Type of airport for which the callback is run.
+ * @param layout Layout of the airport to build.
+ */
AirportScopeResolver::AirportScopeResolver(ResolverObject *ro, TileIndex tile, Station *st, byte airport_id, byte layout) : ScopeResolver(ro)
{
this->st = st;
diff --git a/src/newgrf_airporttiles.cpp b/src/newgrf_airporttiles.cpp
index c25d0db5f..9829286dd 100644
--- a/src/newgrf_airporttiles.cpp
+++ b/src/newgrf_airporttiles.cpp
@@ -204,12 +204,27 @@ static uint32 GetAirportTileIDAtOffset(TileIndex tile, const Station *st, uint32
return (this->st == NULL ? 0 : this->st->random_bits) | (this->tile == INVALID_TILE ? 0 : GetStationTileRandomBits(this->tile) << 16);
}
+/**
+ * Constructor of the resolver for airport tiles.
+ * @param ats Specification of the airport tiles.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st Station of the airport for which the callback is run, or \c NULL for build gui.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
AirportTileResolverObject::AirportTileResolverObject(const AirportTileSpec *ats, TileIndex tile, Station *st,
CallbackID callback, uint32 callback_param1, uint32 callback_param2)
: ResolverObject(ats->grf_prop.grffile, callback, callback_param1, callback_param2), tiles_scope(this, ats, tile, st)
{
}
+/**
+ * Constructor of the scope resolver specific for airport tiles.
+ * @param ats Specification of the airport tiles.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st Station of the airport for which the callback is run, or \c NULL for build gui.
+ */
AirportTileScopeResolver::AirportTileScopeResolver(ResolverObject *ro, const AirportTileSpec *ats, TileIndex tile, Station *st) : ScopeResolver(ro)
{
assert(st != NULL);
diff --git a/src/newgrf_airporttiles.h b/src/newgrf_airporttiles.h
index 8daded34f..7fe57253c 100644
--- a/src/newgrf_airporttiles.h
+++ b/src/newgrf_airporttiles.h
@@ -18,8 +18,9 @@
#include "newgrf_commons.h"
#include "newgrf_spritegroup.h"
+/** Scope resolver for handling the tiles of an airport. */
struct AirportTileScopeResolver : public ScopeResolver {
- struct Station *st; ///< Station of the airport for which the callback is run, or \c NULL for build gui.
+ struct Station *st; ///< %Station of the airport for which the callback is run, or \c NULL for build gui.
byte airport_id; ///< Type of airport for which the callback is run.
TileIndex tile; ///< Tile for the callback, only valid for airporttile callbacks.
@@ -29,8 +30,9 @@ struct AirportTileScopeResolver : public ScopeResolver {
/* virtual */ uint32 GetVariable(byte variable, uint32 parameter, bool *available) const;
};
+/** Resolver for tiles of an airport. */
struct AirportTileResolverObject : public ResolverObject {
- AirportTileScopeResolver tiles_scope;
+ AirportTileScopeResolver tiles_scope; ///< Scope resolver for the tiles.
AirportTileResolverObject(const AirportTileSpec *ats, TileIndex tile, Station *st,
CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_canal.cpp b/src/newgrf_canal.cpp
index 48c1490e6..13b7e15d6 100644
--- a/src/newgrf_canal.cpp
+++ b/src/newgrf_canal.cpp
@@ -18,8 +18,9 @@
/** Table of canal 'feature' sprite groups */
WaterFeature _water_feature[CF_END];
+/** Scope resolver of a canal tile. */
struct CanalScopeResolver : public ScopeResolver {
- TileIndex tile;
+ TileIndex tile; ///< Tile containing the canal.
CanalScopeResolver(ResolverObject *ro, TileIndex tile);
@@ -89,8 +90,12 @@ CanalScopeResolver::CanalScopeResolver(ResolverObject *ro, TileIndex tile) : Sco
}
/**
- * @param tile Tile index of canal.
+ * Canal resolver constructor.
* @param grffile Grf file.
+ * @param tile Tile index of canal.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
*/
CanalResolverObject::CanalResolverObject(const GRFFile *grffile, TileIndex tile,
CallbackID callback, uint32 callback_param1, uint32 callback_param2)
diff --git a/src/newgrf_cargo.cpp b/src/newgrf_cargo.cpp
index b084e835e..d6227b801 100644
--- a/src/newgrf_cargo.cpp
+++ b/src/newgrf_cargo.cpp
@@ -13,6 +13,7 @@
#include "debug.h"
#include "newgrf_spritegroup.h"
+/** Resolver of cargo. */
struct CargoResolverObject : public ResolverObject {
CargoResolverObject(const CargoSpec *cs, CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
@@ -29,11 +30,23 @@ struct CargoResolverObject : public ResolverObject {
return NULL;
}
+/**
+ * Constructor of the cargo resolver.
+ * @param cs Cargo being resolved.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
CargoResolverObject::CargoResolverObject(const CargoSpec *cs, CallbackID callback, uint32 callback_param1, uint32 callback_param2)
: ResolverObject(cs->grffile, callback, callback_param1, callback_param2)
{
}
+/**
+ * Get the custom sprite for the given cargo type.
+ * @param cs Cargo being queried.
+ * @return Custom sprite to draw, or \c 0 if not available.
+ */
SpriteID GetCustomCargoSprite(const CargoSpec *cs)
{
CargoResolverObject object(cs);
diff --git a/src/newgrf_engine.cpp b/src/newgrf_engine.cpp
index 6a286f81e..05300c22b 100644
--- a/src/newgrf_engine.cpp
+++ b/src/newgrf_engine.cpp
@@ -928,6 +928,13 @@ static uint32 VehicleGetVariable(Vehicle *v, const VehicleScopeResolver *object,
return in_motion ? group->loaded[set] : group->loading[set];
}
+/**
+ * Scope resolver of a single vehicle.
+ * @param ro Surrounding resolver.
+ * @param engine_type Engine type
+ * @param v %Vehicle being resolved.
+ * @param info_view Indicates if the item is being drawn in an info window.
+ */
VehicleScopeResolver::VehicleScopeResolver(ResolverObject *ro, EngineID engine_type, const Vehicle *v, bool info_view)
: ScopeResolver(ro)
{
@@ -947,6 +954,15 @@ static const GRFFile *GetEngineGrfFile(EngineID engine_type)
return (e != NULL) ? e->GetGRF() : NULL;
}
+/**
+ * Resolver of a vehicle (chain).
+ * @param engine_type Engine type
+ * @param v %Vehicle being resolved.
+ * @param info_view Indicates if the item is being drawn in an info window.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
VehicleResolverObject::VehicleResolverObject(EngineID engine_type, const Vehicle *v, bool info_view,
CallbackID callback, uint32 callback_param1, uint32 callback_param2)
: ResolverObject(GetEngineGrfFile(engine_type), callback, callback_param1, callback_param2),
diff --git a/src/newgrf_engine.h b/src/newgrf_engine.h
index 645f6310b..7eb65f134 100644
--- a/src/newgrf_engine.h
+++ b/src/newgrf_engine.h
@@ -20,10 +20,11 @@
#include "gfx_type.h"
#include "newgrf_spritegroup.h"
+/** Resolver for a vehicle scope. */
struct VehicleScopeResolver : public ScopeResolver {
- const struct Vehicle *v;
- EngineID self_type;
- bool info_view; ///< Indicates if the item is being drawn in an info window
+ const struct Vehicle *v; ///< The vehicle being resolved.
+ EngineID self_type; ///< Type of the vehicle.
+ bool info_view; ///< Indicates if the item is being drawn in an info window.
VehicleScopeResolver(ResolverObject *ro, EngineID engine_type, const Vehicle *v, bool info_view);
@@ -35,12 +36,13 @@ struct VehicleScopeResolver : public ScopeResolver {
/* virtual */ void SetTriggers(int triggers) const;
};
+/** Resolver for a vehicle (chain) */
struct VehicleResolverObject : public ResolverObject {
- VehicleScopeResolver self_scope;
- VehicleScopeResolver parent_scope;
+ VehicleScopeResolver self_scope; ///< Scope resolver for the indicated vehicle.
+ VehicleScopeResolver parent_scope; ///< Scope resolver for its parent vehicle.
- VehicleScopeResolver relative_scope;
- byte cached_relative_count;
+ VehicleScopeResolver relative_scope; ///< Scope resolver for an other vehicle in the chain.
+ byte cached_relative_count; ///< Relative position of the other vehicle.
VehicleResolverObject(EngineID engine_type, const Vehicle *v, bool info_view = false,
CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_generic.cpp b/src/newgrf_generic.cpp
index 9a55928cf..fe9100bba 100644
--- a/src/newgrf_generic.cpp
+++ b/src/newgrf_generic.cpp
@@ -134,11 +134,20 @@ void AddGenericCallback(uint8 feature, const GRFFile *file, const SpriteGroup *g
return group->loaded[0];
}
-
+/**
+ * Generic resolver.
+ * @param ai_callback Callback comes from the AI.
+ * @param callback Callback ID.
+ */
GenericResolverObject::GenericResolverObject(bool ai_callback, CallbackID callback) : ResolverObject(NULL, callback), generic_scope(this, ai_callback)
{
}
+/**
+ * Generic scope resolver.
+ * @param ro Surrounding resolver.
+ * @param ai_callback Callback comes from the AI.
+ */
GenericScopeResolver::GenericScopeResolver(ResolverObject *ro, bool ai_callback) : ScopeResolver(ro)
{
this->cargo_type = 0;
diff --git a/src/newgrf_house.cpp b/src/newgrf_house.cpp
index dd40ce8e5..0f0cc3138 100644
--- a/src/newgrf_house.cpp
+++ b/src/newgrf_house.cpp
@@ -29,7 +29,16 @@ static HouseClassMapping _class_mapping[HOUSE_CLASS_MAX];
HouseOverrideManager _house_mngr(NEW_HOUSE_OFFSET, HOUSE_MAX, INVALID_HOUSE_ID);
-
+/**
+ * Constructor of a house scope resolver.
+ * @param ro Surrounding resolver.
+ * @param house_id Houe type being queried.
+ * @param tile %Tile containing the house.
+ * @param town %Town containing the house.
+ * @param not_yet_constructed House is still under construction.
+ * @param initial_random_bits Random bits during construction checks.
+ * @param watched_cargo_triggers Cargo types that triggered the watched cargo callback.
+ */
HouseScopeResolver::HouseScopeResolver(ResolverObject *ro, HouseID house_id, TileIndex tile, Town *town,
bool not_yet_constructed, uint8 initial_random_bits, uint32 watched_cargo_triggers)
: ScopeResolver(ro)
@@ -53,6 +62,18 @@ static const GRFFile *GetHouseSpecGrf(HouseID house_id)
return (hs != NULL) ? hs->grf_prop.grffile : NULL;
}
+/**
+ * Construct a resolver for a house.
+ * @param house_id House to query.
+ * @param tile %Tile containing the house.
+ * @param town %Town containing the house.
+ * @param callback Callback ID.
+ * @param param1 First parameter (var 10) of the callback.
+ * @param param2 Second parameter (var 18) of the callback.
+ * @param not_yet_constructed House is still under construction.
+ * @param initial_random_bits Random bits during construction checks.
+ * @param watched_cargo_triggers Cargo types that triggered the watched cargo callback.
+ */
HouseResolverObject::HouseResolverObject(HouseID house_id, TileIndex tile, Town *town,
CallbackID callback, uint32 param1, uint32 param2,
bool not_yet_constructed, uint8 initial_random_bits, uint32 watched_cargo_triggers)
diff --git a/src/newgrf_house.h b/src/newgrf_house.h
index f833f96b0..d6d4beb5d 100644
--- a/src/newgrf_house.h
+++ b/src/newgrf_house.h
@@ -18,9 +18,10 @@
#include "newgrf_spritegroup.h"
#include "newgrf_town.h"
+/** Scope resolver for houses. */
struct HouseScopeResolver : public ScopeResolver {
- HouseID house_id;
- TileIndex tile;
+ HouseID house_id; ///< Type of house being queried.
+ TileIndex tile; ///< Tile of this house.
Town *town; ///< Town of this house.
bool not_yet_constructed; ///< True for construction check.
uint16 initial_random_bits; ///< Random bits during construction checks.
diff --git a/src/newgrf_industries.cpp b/src/newgrf_industries.cpp
index 84f589d86..b1cb80be3 100644
--- a/src/newgrf_industries.cpp
+++ b/src/newgrf_industries.cpp
@@ -404,6 +404,16 @@ static const GRFFile *GetGrffile(IndustryType type)
return (indspec != NULL) ? indspec->grf_prop.grffile : NULL;
}
+/**
+ * Constructor of the industries resolver.
+ * @param tile %Tile owned by the industry.
+ * @param industry %Industry being resolved.
+ * @param type Type of the industry.
+ * @param random_bits Random bits of the new industry.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
IndustriesResolverObject::IndustriesResolverObject(TileIndex tile, Industry *indus, IndustryType type, uint32 random_bits,
CallbackID callback, uint32 callback_param1, uint32 callback_param2)
: ResolverObject(GetGrffile(type), callback, callback_param1, callback_param2),
@@ -436,6 +446,14 @@ TownScopeResolver *IndustriesResolverObject::GetTown()
return this->town_scope;
}
+/**
+ * Scope resolver for industries.
+ * @param ro Surrounding resolver.
+ * @param tile %Tile owned by the industry.
+ * @param industry %Industry being resolved.
+ * @param type Type of the industry.
+ * @param random_bits Random bits of the new industry.
+ */
IndustriesScopeResolver::IndustriesScopeResolver(ResolverObject *ro, TileIndex tile, Industry *industry, IndustryType type, uint32 random_bits)
: ScopeResolver(ro)
{
diff --git a/src/newgrf_industries.h b/src/newgrf_industries.h
index cb1e7f21c..5c95fcdcb 100644
--- a/src/newgrf_industries.h
+++ b/src/newgrf_industries.h
@@ -14,11 +14,12 @@
#include "newgrf_town.h"
+/** Resolver for industry scopes. */
struct IndustriesScopeResolver : public ScopeResolver {
- TileIndex tile;
- Industry *industry;
- IndustryType type;
- uint32 random_bits; ///< Random bits of the new industry.
+ TileIndex tile; ///< Tile owned by the industry.
+ Industry *industry; ///< %Industry being resolved.
+ IndustryType type; ///< Type of the industry.
+ uint32 random_bits; ///< Random bits of the new industry.
IndustriesScopeResolver(ResolverObject *ro, TileIndex tile, Industry *industry, IndustryType type, uint32 random_bits = 0);
@@ -29,9 +30,10 @@ struct IndustriesScopeResolver : public ScopeResolver {
/* virtual */ void StorePSA(uint pos, int32 value);
};
+/** Resolver for industries. */
struct IndustriesResolverObject : public ResolverObject {
- IndustriesScopeResolver industries_scope;
- TownScopeResolver *town_scope;
+ IndustriesScopeResolver industries_scope; ///< Scope resolver for the industry.
+ TownScopeResolver *town_scope; ///< Scope resolver for the associated town (if needed and available, else \c NULL).
IndustriesResolverObject(TileIndex tile, Industry *indus, IndustryType type, uint32 random_bits = 0,
CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_industrytiles.cpp b/src/newgrf_industrytiles.cpp
index e778a3ac7..d23a38298 100644
--- a/src/newgrf_industrytiles.cpp
+++ b/src/newgrf_industrytiles.cpp
@@ -132,6 +132,15 @@ static const GRFFile *GetIndTileGrffile(IndustryGfx gfx)
return (its != NULL) ? its->grf_prop.grffile : NULL;
}
+/**
+ * Constructor of the industry tiles scope resolver.
+ * @param gfx Graphics of the industry.
+ * @param tile %Tile of the industry.
+ * @param indus %Industry owning the tile.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
IndustryTileResolverObject::IndustryTileResolverObject(IndustryGfx gfx, TileIndex tile, Industry *indus,
CallbackID callback, uint32 callback_param1, uint32 callback_param2)
: ResolverObject(GetIndTileGrffile(gfx), callback, callback_param1, callback_param2),
@@ -140,6 +149,12 @@ IndustryTileResolverObject::IndustryTileResolverObject(IndustryGfx gfx, TileInde
{
}
+/**
+ * Constructor of the scope resolver for the industry tile.
+ * @param ro Surrounding resolver.
+ * @param industry %Industry owning the tile.
+ * @param tile %Tile of the industry.
+ */
IndustryTileScopeResolver::IndustryTileScopeResolver(ResolverObject *ro, Industry *industry, TileIndex tile) : ScopeResolver(ro)
{
this->industry = industry;
diff --git a/src/newgrf_industrytiles.h b/src/newgrf_industrytiles.h
index dc8fb238f..f5b88db83 100644
--- a/src/newgrf_industrytiles.h
+++ b/src/newgrf_industrytiles.h
@@ -16,9 +16,10 @@
#include "newgrf_industries.h"
#include "core/random_func.hpp"
+/** Resolver for the industry tiles scope. */
struct IndustryTileScopeResolver : public ScopeResolver {
- Industry *industry;
- TileIndex tile;
+ Industry *industry; ///< Industry owning the tiles.
+ TileIndex tile; ///< %Tile being resolved.
IndustryTileScopeResolver(ResolverObject *ro, Industry *industry, TileIndex tile);
@@ -28,9 +29,10 @@ struct IndustryTileScopeResolver : public ScopeResolver {
/* virtual */ void SetTriggers(int triggers) const;
};
+/** Resolver for industry tiles. */
struct IndustryTileResolverObject : public ResolverObject {
- IndustryTileScopeResolver indtile_scope;
- IndustriesScopeResolver ind_scope;
+ IndustryTileScopeResolver indtile_scope; ///< Scope resolver for the industry tile.
+ IndustriesScopeResolver ind_scope; ///< Scope resolver for the industry owning the tile.
IndustryTileResolverObject(IndustryGfx gfx, TileIndex tile, Industry *indus,
CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_object.cpp b/src/newgrf_object.cpp
index 4c1c46149..1db4b02c6 100644
--- a/src/newgrf_object.cpp
+++ b/src/newgrf_object.cpp
@@ -116,6 +116,13 @@ bool NewGRFClass<Tspec, Tid, Tmax>::IsUIAvailable(uint index) const
INSTANTIATE_NEWGRF_CLASS_METHODS(ObjectClass, ObjectSpec, ObjectClassID, OBJECT_CLASS_MAX)
+/**
+ * Constructor of an object scope resolver.
+ * @param ro Surrounding resolver.
+ * @param obj Object being resolved.
+ * @param tile %Tile of the object.
+ * @param view View of the object.
+ */
ObjectScopeResolver::ObjectScopeResolver(ResolverObject *ro, Object *obj, TileIndex tile, uint8 view)
: ScopeResolver(ro)
{
@@ -355,6 +362,15 @@ static const SpriteGroup *GetObjectSpriteGroup(const ObjectSpec *spec, const Obj
}
+/**
+ * Constructor of the object resolver.
+ * @param obj Object being resolved.
+ * @param tile %Tile of the object.
+ * @param view View of the object.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
ObjectResolverObject::ObjectResolverObject(const ObjectSpec *spec, Object *obj, TileIndex tile, uint8 view,
CallbackID callback, uint32 param1, uint32 param2)
: ResolverObject(spec->grf_prop.grffile, callback, param1, param2), object_scope(this, obj, tile, view)
diff --git a/src/newgrf_object.h b/src/newgrf_object.h
index a1adbb662..4ccca97b8 100644
--- a/src/newgrf_object.h
+++ b/src/newgrf_object.h
@@ -92,6 +92,7 @@ struct ObjectSpec {
static const ObjectSpec *GetByTile(TileIndex tile);
};
+/** Object scope resolver. */
struct ObjectScopeResolver : public ScopeResolver {
struct Object *obj; ///< The object the callback is ran for.
TileIndex tile; ///< The tile related to the object.
@@ -105,8 +106,8 @@ struct ObjectScopeResolver : public ScopeResolver {
/** A resolver object to be used with feature 0F spritegroups. */
struct ObjectResolverObject : public ResolverObject {
- ObjectScopeResolver object_scope;
- TownScopeResolver *town_scope;
+ ObjectScopeResolver object_scope; ///< The object scope resolver.
+ TownScopeResolver *town_scope; ///< The town scope resolver (created on the first call).
ObjectResolverObject(const ObjectSpec *spec, Object *o, TileIndex tile, uint8 view = 0,
CallbackID callback = CBID_NO_CALLBACK, uint32 param1 = 0, uint32 param2 = 0);
diff --git a/src/newgrf_railtype.cpp b/src/newgrf_railtype.cpp
index 4e1673ab2..36ac7260a 100644
--- a/src/newgrf_railtype.cpp
+++ b/src/newgrf_railtype.cpp
@@ -65,12 +65,26 @@
return NULL;
}
+/**
+ * Constructor of the railtype scope resolvers.
+ * @param ro Surrounding resolver.
+ * @param tile %Tile containing the track. For track on a bridge this is the southern bridgehead.
+ * @param context Are we resolving sprites for the upper halftile, or on a bridge?
+ */
RailTypeScopeResolver::RailTypeScopeResolver(ResolverObject *ro, TileIndex tile, TileContext context) : ScopeResolver(ro)
{
this->tile = tile;
this->context = context;
}
+/**
+ * Resolver object for rail types.
+ * @param tile %Tile containing the track. For track on a bridge this is the southern bridgehead.
+ * @param context Are we resolving sprites for the upper halftile, or on a bridge?
+ * @param grffile The GRF to do the lookup for.
+ * @param param1 Extra parameter (first parameter of the callback, except railtypes do not have callbacks).
+ * @param param2 Extra parameter (second parameter of the callback, except railtypes do not have callbacks).
+ */
RailTypeResolverObject::RailTypeResolverObject(TileIndex tile, TileContext context, const GRFFile *grffile, uint32 param1, uint32 param2)
: ResolverObject(grffile, CBID_NO_CALLBACK, param1, param2), railtype_scope(this, tile, context)
{
diff --git a/src/newgrf_railtype.h b/src/newgrf_railtype.h
index 9224ce9e5..c1977eaf8 100644
--- a/src/newgrf_railtype.h
+++ b/src/newgrf_railtype.h
@@ -16,7 +16,7 @@
#include "newgrf_commons.h"
#include "newgrf_spritegroup.h"
-
+/** Resolver for the railtype scope. */
struct RailTypeScopeResolver : public ScopeResolver {
TileIndex tile; ///< Tracktile. For track on a bridge this is the southern bridgehead.
TileContext context; ///< Are we resolving sprites for the upper halftile, or on a bridge?
@@ -29,7 +29,7 @@ struct RailTypeScopeResolver : public ScopeResolver {
/** Resolver object for rail types. */
struct RailTypeResolverObject : public ResolverObject {
- RailTypeScopeResolver railtype_scope;
+ RailTypeScopeResolver railtype_scope; ///< Resolver for the railtype scope.
RailTypeResolverObject(TileIndex tile, TileContext context, const GRFFile *grffile, uint32 param1 = 0, uint32 param2 = 0);
diff --git a/src/newgrf_spritegroup.cpp b/src/newgrf_spritegroup.cpp
index 517cc885d..81b66767b 100644
--- a/src/newgrf_spritegroup.cpp
+++ b/src/newgrf_spritegroup.cpp
@@ -115,7 +115,13 @@ ScopeResolver::~ScopeResolver() {}
*/
/* virtual */ void ScopeResolver::StorePSA(uint reg, int32 value) {}
-
+/**
+ * Resolver constructor.
+ * @param grffile NewGRF file asscoiated with the object (or \c NULL if none).
+ * @param callback Callback code being resolved (default value is #CBID_NO_CALLBACK).
+ * @param callback_param1 First parameter (var 10) of the callback (only used when \a callback is also set).
+ * @param callback_param2 Second parameter (var 18) of the callback (only used when \a callback is also set).
+ */
ResolverObject::ResolverObject(const GRFFile *grffile, CallbackID callback, uint32 callback_param1, uint32 callback_param2)
: default_scope(this)
{
@@ -129,16 +135,21 @@ ResolverObject::ResolverObject(const GRFFile *grffile, CallbackID callback, uint
ResolverObject::~ResolverObject() {}
+/**
+ * Get the real sprites of the grf.
+ * @param group Group to get.
+ * @return The available sprite group.
+ */
/* virtual */ const SpriteGroup *ResolverObject::ResolveReal(const RealSpriteGroup *group) const
{
return NULL;
}
/**
- * Get a specific ScopeResolver.
+ * Get a resolver for the \a scope.
* @param scope Scope to return.
* @param relative Additional parameter for #VSG_SCOPE_RELATIVE.
- * @return ScopeResolver.
+ * @return The resolver for the requested scope.
*/
/* virtual */ ScopeResolver *ResolverObject::GetScope(VarSpriteGroupScope scope, byte relative)
{
diff --git a/src/newgrf_spritegroup.h b/src/newgrf_spritegroup.h
index ac2f939b2..9b6d1fc0e 100644
--- a/src/newgrf_spritegroup.h
+++ b/src/newgrf_spritegroup.h
@@ -303,8 +303,14 @@ struct IndustryProductionSpriteGroup : SpriteGroup {
struct ResolverObject;
+/**
+ * Interface to query and set values specific to a single #VarSpriteGroupScope (action 2 scope).
+ *
+ * Multiple of these interfaces are combined into a #ResolverObject to allow access
+ * to different game entities from a #SpriteGroup-chain (action 1-2-3 chain).
+ */
struct ScopeResolver {
- ResolverObject *ro;
+ ResolverObject *ro; ///< Surrounding resolver object.
ScopeResolver(ResolverObject *ro);
virtual ~ScopeResolver();
@@ -317,15 +323,21 @@ struct ScopeResolver {
virtual void StorePSA(uint reg, int32 value);
};
+/**
+ * Interface for #SpriteGroup-s to access the gamestate.
+ *
+ * Using this interface #SpriteGroup-chains (action 1-2-3 chains) can be resolved,
+ * to get the results of callbacks, rerandomisations or normal sprite lookups.
+ */
struct ResolverObject {
ResolverObject(const GRFFile *grffile, CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
virtual ~ResolverObject();
ScopeResolver default_scope; ///< Default implementation of the grf scope.
- CallbackID callback;
- uint32 callback_param1;
- uint32 callback_param2;
+ CallbackID callback; ///< Callback being resolved.
+ uint32 callback_param1; ///< First parameter (var 10) of the callback.
+ uint32 callback_param2; ///< Second parameter (var 18) of the callback.
byte trigger;
diff --git a/src/newgrf_station.cpp b/src/newgrf_station.cpp
index 61f8bb5a3..4b5c5468a 100644
--- a/src/newgrf_station.cpp
+++ b/src/newgrf_station.cpp
@@ -523,6 +523,15 @@ uint32 Waypoint::GetNewGRFVariable(const ResolverObject *object, byte variable,
return group->loading[0];
}
+/**
+ * Resolver for stations.
+ * @param statspec Station (type) specification.
+ * @param st Instance of the station.
+ * @param tile %Tile of the station.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
StationResolverObject::StationResolverObject(const StationSpec *statspec, BaseStation *st, TileIndex tile,
CallbackID callback, uint32 callback_param1, uint32 callback_param2)
: ResolverObject((statspec != NULL ? statspec->grf_prop.grffile : NULL), callback, callback_param1, callback_param2),
@@ -537,6 +546,13 @@ StationResolverObject::~StationResolverObject()
delete this->town_scope;
}
+/**
+ * Constructor for station scopes.
+ * @param ro Surrounding resolver.
+ * @param statspec Station (type) specification.
+ * @param st Instance of the station.
+ * @param tile %Tile of the station.
+ */
StationScopeResolver::StationScopeResolver(ResolverObject *ro, const StationSpec *statspec, BaseStation *st, TileIndex tile)
: ScopeResolver(ro)
{
diff --git a/src/newgrf_station.h b/src/newgrf_station.h
index ee7757376..a536687a6 100644
--- a/src/newgrf_station.h
+++ b/src/newgrf_station.h
@@ -22,12 +22,13 @@
#include "newgrf_spritegroup.h"
#include "newgrf_town.h"
+/** Scope resolver for stations. */
struct StationScopeResolver : public ScopeResolver {
- TileIndex tile;
- struct BaseStation *st;
- const struct StationSpec *statspec;
- CargoID cargo_type;
- Axis axis; ///< Station axis, used only for the slope check callback.
+ TileIndex tile; ///< %Tile of the station.
+ struct BaseStation *st; ///< Instance of the station.
+ const struct StationSpec *statspec; ///< Station (type) specification.
+ CargoID cargo_type; ///< Type of cargo of the station.
+ Axis axis; ///< Station axis, used only for the slope check callback.
StationScopeResolver(ResolverObject *ro, const StationSpec *statspec, BaseStation *st, TileIndex tile);
@@ -38,9 +39,10 @@ struct StationScopeResolver : public ScopeResolver {
/* virtual */ uint32 GetVariable(byte variable, uint32 parameter, bool *available) const;
};
+/** Station resolver. */
struct StationResolverObject : public ResolverObject {
- StationScopeResolver station_scope;
- TownScopeResolver *town_scope;
+ StationScopeResolver station_scope; ///< The station scope resolver.
+ TownScopeResolver *town_scope; ///< The town scope resolver (created on the first call).
StationResolverObject(const StationSpec *statspec, BaseStation *st, TileIndex tile,
CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_town.cpp b/src/newgrf_town.cpp
index 64514d3e6..95cab9643 100644
--- a/src/newgrf_town.cpp
+++ b/src/newgrf_town.cpp
@@ -14,6 +14,12 @@
#include "town.h"
#include "newgrf_town.h"
+/**
+ * Resolver of a town scope.
+ * @param ro Surrounding resolver.
+ * @param t %Town of the scope.
+ * @param readonly Scope may change persistent storage of the town.
+ */
TownScopeResolver::TownScopeResolver(ResolverObject *ro, Town *t, bool readonly) : ScopeResolver(ro)
{
this->t = t;
@@ -154,6 +160,12 @@ TownScopeResolver::TownScopeResolver(ResolverObject *ro, Town *t, bool readonly)
t->psa_list.push_back(psa);
}
+/**
+ * Resolver for a town.
+ * @param grffile NewGRF file associated with the town.
+ * @param t %Town of the scope.
+ * @param readonly Scope may change persistent storage of the town.
+ */
TownResolverObject::TownResolverObject(const struct GRFFile *grffile, Town *t, bool readonly)
: ResolverObject(grffile), town_scope(this, t, readonly)
{
diff --git a/src/newgrf_town.h b/src/newgrf_town.h
index cd090a7ac..3f6094cdb 100644
--- a/src/newgrf_town.h
+++ b/src/newgrf_town.h
@@ -15,13 +15,15 @@
#include "town_type.h"
#include "newgrf_spritegroup.h"
-/* Currently there is no direct town resolver; we only need to get town
- * variable results from inside stations, house tiles and industries,
- * and to check the town's persistent storage.
+/**
+ * Scope resolver for a town.
+ * @note Currently there is no direct town resolver; we only need to get town
+ * variable results from inside stations, house tiles and industries,
+ * and to check the town's persistent storage.
*/
struct TownScopeResolver : public ScopeResolver {
- Town *t;
- bool readonly;
+ Town *t; ///< %Town of the scope.
+ bool readonly; ///< When set, persistent storage of the town is read-only,
TownScopeResolver(ResolverObject *ro, Town *t, bool readonly);
@@ -29,8 +31,9 @@ struct TownScopeResolver : public ScopeResolver {
virtual void StorePSA(uint reg, int32 value);
};
+/** Resolver of town properties. */
struct TownResolverObject : public ResolverObject {
- TownScopeResolver town_scope;
+ TownScopeResolver town_scope; ///< Scope resolver specific for towns.
TownResolverObject(const struct GRFFile *grffile, Town *t, bool readonly);