dave/openttd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bulk documentation update, and a few style fixes.

Browse Source
This commit is contained in:
Jonathan G Rennison
2015-07-27 18:55:57 +01:00
parent 75869cae41
commit 3dd51e96b8
5 changed files with 382 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
src/tracerestrict.h
View File

@@ -5,7 +5,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
/** @file tracerestrict.h Header file for Trace Restriction. */
/** @file tracerestrict.h Header file for Trace Restrict */
#ifndef TRACERESTRICT_H
#define TRACERESTRICT_H
@@ -22,10 +22,11 @@
struct Train;
/** Unique identifiers for a trace restrict nodes. */
/** Program pool ID type. */
typedef uint32 TraceRestrictProgramID;
struct TraceRestrictProgram;
/** Tile/track mapping type. */
typedef uint32 TraceRestrictRefId;
/** Type of the pool for trace restrict programs. */
@@ -36,6 +37,7 @@ extern TraceRestrictProgramPool _tracerestrictprogram_pool;
#define FOR_ALL_TRACE_RESTRICT_PROGRAMS_FROM(var, start) FOR_ALL_ITEMS_FROM(TraceRestrictProgram, tr_index, var, start)
#define FOR_ALL_TRACE_RESTRICT_PROGRAMS(var) FOR_ALL_TRACE_RESTRICT_PROGRAMS_FROM(var, 0)
/** Type used for the TraceRestrictRefId -> TraceRestrictProgramID mapping */
struct TraceRestrictMappingItem {
TraceRestrictProgramID program_id;
@@ -46,13 +48,24 @@ struct TraceRestrictMappingItem {
};
typedef std::map<TraceRestrictRefId, TraceRestrictMappingItem> TraceRestrictMapping;
/** The actual mapping from TraceRestrictRefId to TraceRestrictProgramID. */
extern TraceRestrictMapping _tracerestrictprogram_mapping;
void ClearTraceRestrictMapping();
/// Of the fields below, the type and cond flags seem the most likely
/// to need future expansion, hence the reserved bits are placed
/// immediately after them
/** Type of a single instruction, this is bit-packed as per TraceRestrictItemFlagAllocation */
typedef uint32 TraceRestrictItem;
/**
* Describes the allocation of bits to fields in TraceRestrictItem
* Of the fields below, the type seem the most likely
* to need future expansion, hence the reserved bits are placed
* immediately after them
*
* COUNT values describe the field bit width
* OFFSET values describe the field bit offset
*/
enum TraceRestrictItemFlagAllocation {
TRIFA_TYPE_COUNT = 5,
TRIFA_TYPE_OFFSET = 0,
@@ -72,12 +85,18 @@ enum TraceRestrictItemFlagAllocation {
TRIFA_VALUE_OFFSET = 16,
};
/**
* Enumeration of TraceRestrictItem type field
* This is split into two halves:
* * non-conditionals < TRIT_COND_BEGIN
* * conditionals, >= TRIT_COND_BEGIN
*/
enum TraceRestrictItemType {
TRIT_NULL = 0,
TRIT_PF_DENY = 1,
TRIT_PF_PENALTY = 2,
TRIT_NULL = 0, ///< Null-type, not in programs and not valid for execution, mainly used with TraceRestrictNullTypeSpecialValue for start/end
TRIT_PF_DENY = 1, ///< Pathfinder deny/allow
TRIT_PF_PENALTY = 2, ///< Add to pathfinder penalty
TRIT_COND_BEGIN = 8, ///< Start of conditional item types
TRIT_COND_BEGIN = 8, ///< Start of conditional item types, note that this has the save value as TRIT_COND_ENDIF
TRIT_COND_ENDIF = 8, ///< This is an endif block or an else block
TRIT_COND_UNDEFINED = 9, ///< This condition has no type defined (evaluate as false)
TRIT_COND_TRAIN_LENGTH = 10, ///< Test train length
@@ -89,53 +108,72 @@ enum TraceRestrictItemType {
/* space up to 31 */
};
/* no flags set indicates end if for TRIT_COND_ENDIF, if otherwise */
/**
* TraceRestrictItem condition flags field, only valid with conditional types (IsTraceRestrictTypeConditional() is true)
*/
enum TraceRestrictCondFlags {
TRCF_DEFAULT = 0,
TRCF_ELSE = 1 << 0,
TRCF_OR = 1 << 1,
TRCF_DEFAULT = 0, ///< indicates end if for type: TRIT_COND_ENDIF, if otherwise
TRCF_ELSE = 1 << 0, ///< indicates an else block for type: TRIT_COND_ENDIF, elif otherwise
TRCF_OR = 1 << 1, ///< indicates an orif block, not valid with type: TRIT_COND_ENDIF
/* 1 bit spare */
};
DECLARE_ENUM_AS_BIT_SET(TraceRestrictCondFlags)
enum TraceRestictNullTypeSpecialValue {
TRNTSV_NULL = 0,
TRNTSV_START = 1,
TRNTSV_END = 2,
/**
* Enumeration of TraceRestrictItemvalue type field when type is TRIT_NULL
*/
enum TraceRestrictNullTypeSpecialValue {
TRNTSV_NULL = 0, ///< null, what you get when you zero-init a TraceRestrictItemvalue
TRNTSV_START = 1, ///< start tag, generated within GUI
TRNTSV_END = 2, ///< end tag, generated within GUI
};
/**
* TraceRestrictItem condition operator field, only valid with conditional types (IsTraceRestrictTypeConditional() is true)
*/
enum TraceRestrictCondOp {
TRCO_IS = 0,
TRCO_ISNOT = 1,
TRCO_LT = 2,
TRCO_LTE = 3,
TRCO_GT = 4,
TRCO_GTE = 5,
TRCO_IS = 0, ///< equality test, or can carry test for cargo
TRCO_ISNOT = 1, ///< inequality test, or can't carry test for cargo
TRCO_LT = 2, ///< less than test
TRCO_LTE = 3, ///< less than or equal test
TRCO_GT = 4, ///< greater than test
TRCO_GTE = 5, ///< greater than or equal test
/* space up to 7 */
};
/**
* TraceRestrictItem auxiliary type field, for order type conditionals
*/
enum TraceRestrictOrderCondAuxField {
TROCAF_STATION = 0,
TROCAF_WAYPOINT = 1,
TROCAF_DEPOT = 2,
/* space up to 7 */
TROCAF_STATION = 0, ///< value field is a station StationID
TROCAF_WAYPOINT = 1, ///< value field is a waypoint StationID
TROCAF_DEPOT = 2, ///< value field is a depot DepotID
/* space up to 3 */
};
/**
* Enumeration for TraceRestrictProgramResult::flags
*/
enum TraceRestrictProgramResultFlags {
TRPRF_DENY = 1 << 0,
TRPRF_DENY = 1 << 0, ///< Pathfinder deny is set
};
DECLARE_ENUM_AS_BIT_SET(TraceRestrictProgramResultFlags)
/**
* Execution result of a TraceRestrictProgram
*/
struct TraceRestrictProgramResult {
uint32 penalty;
TraceRestrictProgramResultFlags flags;
uint32 penalty; ///< Total additional pathfinder penalty
TraceRestrictProgramResultFlags flags; ///< Flags of other actions to take
TraceRestrictProgramResult()
: penalty(0), flags(static_cast<TraceRestrictProgramResultFlags>(0)) { }
};
typedef uint32 TraceRestrictItem;
/**
* Program type, this stores the instruction list
* This is refcounted, see info at top of tracerestrict.cpp
*/
struct TraceRestrictProgram : TraceRestrictProgramPool::PoolItem<&_tracerestrictprogram_pool> {
std::vector<TraceRestrictItem> items;
uint32 refcount;
@@ -145,99 +183,131 @@ struct TraceRestrictProgram : TraceRestrictProgramPool::PoolItem<&_tracerestrict
void Execute(const Train *v, TraceRestrictProgramResult &out) const;
/**
* Increment ref count, only use when creating a mapping
*/
void IncrementRefCount() { refcount++; }
void DecrementRefCount();
static CommandCost Validate(const std::vector<TraceRestrictItem> &items);
/**
* Call validation function on current program instruction list
*/
CommandCost Validate() const { return TraceRestrictProgram::Validate(items); }
};
/** Get TraceRestrictItem type field */
static inline TraceRestrictItemType GetTraceRestrictType(TraceRestrictItem item)
{
return static_cast<TraceRestrictItemType>(GB(item, TRIFA_TYPE_OFFSET, TRIFA_TYPE_COUNT));
}
/** Get TraceRestrictItem condition flags field */
static inline TraceRestrictCondFlags GetTraceRestrictCondFlags(TraceRestrictItem item)
{
return static_cast<TraceRestrictCondFlags>(GB(item, TRIFA_COND_FLAGS_OFFSET, TRIFA_COND_FLAGS_COUNT));
}
/** Get TraceRestrictItem condition operator field */
static inline TraceRestrictCondOp GetTraceRestrictCondOp(TraceRestrictItem item)
{
return static_cast<TraceRestrictCondOp>(GB(item, TRIFA_COND_OP_OFFSET, TRIFA_COND_OP_COUNT));
}
/** Get TraceRestrictItem auxiliary field */
static inline uint8 GetTraceRestrictAuxField(TraceRestrictItem item)
{
return GB(item, TRIFA_AUX_FIELD_OFFSET, TRIFA_AUX_FIELD_COUNT);
}
/** Get TraceRestrictItem value field */
static inline uint16 GetTraceRestrictValue(TraceRestrictItem item)
{
return static_cast<uint16>(GB(item, TRIFA_VALUE_OFFSET, TRIFA_VALUE_COUNT));
}
/** Set TraceRestrictItem type field */
static inline void SetTraceRestrictType(TraceRestrictItem &item, TraceRestrictItemType type)
{
SB(item, TRIFA_TYPE_OFFSET, TRIFA_TYPE_COUNT, type);
}
/** Set TraceRestrictItem condition operator field */
static inline void SetTraceRestrictCondOp(TraceRestrictItem &item, TraceRestrictCondOp condop)
{
SB(item, TRIFA_COND_OP_OFFSET, TRIFA_COND_OP_COUNT, condop);
}
/** Set TraceRestrictItem condition flags field */
static inline void SetTraceRestrictCondFlags(TraceRestrictItem &item, TraceRestrictCondFlags condflags)
{
SB(item, TRIFA_COND_FLAGS_OFFSET, TRIFA_COND_FLAGS_COUNT, condflags);
}
/** Set TraceRestrictItem auxiliary field */
static inline void SetTraceRestrictAuxField(TraceRestrictItem &item, uint8 data)
{
SB(item, TRIFA_AUX_FIELD_OFFSET, TRIFA_AUX_FIELD_COUNT, data);
}
/** Set TraceRestrictItem value field */
static inline void SetTraceRestrictValue(TraceRestrictItem &item, uint16 value)
{
SB(item, TRIFA_VALUE_OFFSET, TRIFA_VALUE_COUNT, value);
}
/** Is TraceRestrictItemType a conditional type? */
static inline bool IsTraceRestrictTypeConditional(TraceRestrictItemType type)
{
return type >= TRIT_COND_BEGIN;
}
/** Is TraceRestrictItem type field a conditional type? */
static inline bool IsTraceRestrictConditional(TraceRestrictItem item)
{
return IsTraceRestrictTypeConditional(GetTraceRestrictType(item));
}
/**
* Categorisation of what is allowed in the TraceRestrictItem condition op field
* see TraceRestrictTypePropertySet
*/
enum TraceRestrictConditionOpType {
TRCOT_NONE = 0, ///< takes no condition op
TRCOT_BINARY = 1, ///< takes "is" and "is not" condition ops
TRCOT_ALL = 2, ///< takes all condition ops (i.e. all relational ops)
};
/**
* Categorisation of what is in the TraceRestrictItem value field
* see TraceRestrictTypePropertySet
*/
enum TraceRestrictValueType {
TRVT_NONE = 0, ///< value field not used (set to 0)
TRVT_SPECIAL = 1, ///< special handling of value field
TRVT_INT = 2, ///< takes an integer value
TRVT_INT = 2, ///< takes an unsigned integer value
TRVT_DENY = 3, ///< takes a value 0 = deny, 1 = allow (cancel previous deny)
TRVT_SPEED = 4, ///< takes an integer speed value
TRVT_ORDER = 5, ///< takes an order target ID, as per the auxiliary field as type: TraceRestrictOrderCondAuxField
TRVT_CARGO_ID = 6, ///< takes a CargoID
};
void SetTraceRestrictValueDefault(TraceRestrictItem &item, TraceRestrictValueType value_type);
void SetTraceRestrictTypeAndNormalise(TraceRestrictItem &item, TraceRestrictItemType type);
/**
* Describes formats of TraceRestrictItem condition op and value fields
*/
struct TraceRestrictTypePropertySet {
TraceRestrictConditionOpType cond_type;
TraceRestrictValueType value_type;
};
void SetTraceRestrictValueDefault(TraceRestrictItem &item, TraceRestrictValueType value_type);
void SetTraceRestrictTypeAndNormalise(TraceRestrictItem &item, TraceRestrictItemType type);
/**
* Get TraceRestrictTypePropertySet for a given instruction, only looks at value field
*/
static inline TraceRestrictTypePropertySet GetTraceRestrictTypeProperties(TraceRestrictItem item)
{
TraceRestrictTypePropertySet out;
@@ -291,16 +361,19 @@ static inline TraceRestrictTypePropertySet GetTraceRestrictTypeProperties(TraceR
return out;
}
/** Get mapping ref ID from tile and track */
static inline TraceRestrictRefId MakeTraceRestrictRefId(TileIndex t, Track track)
{
return (t << 3) | track;
}
/** Get tile from mapping ref ID */
static inline TileIndex GetTraceRestrictRefIdTileIndex(TraceRestrictRefId ref)
{
return static_cast<TileIndex>(ref >> 3);
}
/** Get track from mapping ref ID */
static inline Track GetTraceRestrictRefIdTrack(TraceRestrictRefId ref)
{
return static_cast<Track>(ref & 7);
@@ -309,16 +382,13 @@ static inline Track GetTraceRestrictRefIdTrack(TraceRestrictRefId ref)
void TraceRestrictCreateProgramMapping(TraceRestrictRefId ref, TraceRestrictProgram *prog);
void TraceRestrictRemoveProgramMapping(TraceRestrictRefId ref);
/// Gets the signal program for the tile identified by @p t and @p track.
/// An empty program will be constructed if none exists, and create_new is true
/// unless the pool is full
TraceRestrictProgram *GetTraceRestrictProgram(TraceRestrictRefId ref, bool create_new);
/// Notify that a signal is being removed
/// Remove any trace restrict items associated with it
void TraceRestrictNotifySignalRemoval(TileIndex tile, Track track);
/// Gets the signal program for the tile identified by @p t and @p track, or NULL
/**
* Gets the existing signal program for the tile identified by @p t and @p track, or NULL
*/
static inline const TraceRestrictProgram *GetExistingTraceRestrictProgram(TileIndex t, Track track)
{
if (IsRestrictedSignal(t)) {
@@ -328,16 +398,18 @@ static inline const TraceRestrictProgram *GetExistingTraceRestrictProgram(TileIn
}
}
// do not re-order
/**
* Enumeration for command action type field, indicates what command to do
*/
enum TraceRestrictDoCommandType {
TRDCT_INSERT_ITEM = 0,
TRDCT_MODIFY_ITEM = 1,
TRDCT_REMOVE_ITEM = 2,
TRDCT_INSERT_ITEM = 0, ///< insert new instruction before offset field as given value
TRDCT_MODIFY_ITEM = 1, ///< modify instruction at offset field to given value
TRDCT_REMOVE_ITEM = 2, ///< remove instruction at offset field
TRDCT_PROG_COPY = 3,
TRDCT_PROG_SHARE = 4,
TRDCT_PROG_UNSHARE = 5,
TRDCT_PROG_RESET = 6,
TRDCT_PROG_COPY = 3, ///< copy program operation. Do not re-order this with respect to other values
TRDCT_PROG_SHARE = 4, ///< share program operation
TRDCT_PROG_UNSHARE = 5, ///< unshare program (copy as a new program)
TRDCT_PROG_RESET = 6, ///< reset program state of signal
};
void TraceRestrictDoCommandP(TileIndex tile, Track track, TraceRestrictDoCommandType type, uint32 offset, uint32 value, StringID error_msg);
@@ -345,6 +417,9 @@ void TraceRestrictDoCommandP(TileIndex tile, Track track, TraceRestrictDoCommand
void TraceRestrictProgMgmtWithSourceDoCommandP(TileIndex tile, Track track, TraceRestrictDoCommandType type,
TileIndex source_tile, Track source_track, StringID error_msg);
/**
* Short-hand to call TraceRestrictProgMgmtWithSourceDoCommandP with 0 for source tile/track
*/
inline void TraceRestrictProgMgmtDoCommandP(TileIndex tile, Track track, TraceRestrictDoCommandType type, StringID error_msg)
{
TraceRestrictProgMgmtWithSourceDoCommandP(tile, track, type, static_cast<TileIndex>(0), static_cast<Track>(0), error_msg);