1

/* $Id$ */

     2

     3

/** @file track_func.h Different conversion functions from one kind of track to another. */

     4

     5

#ifndef TRACK_FUNC_H

     6

#define TRACK_FUNC_H

     7

     8

#include "core/bitmath_func.hpp"

     9

#include "track_type.h"

    10

#include "direction_type.h"

    11

#include "slope_func.h"

    12

    13

/**

    14

 * Convert an Axis to the corresponding Track

    15

 * AXIS_X -> TRACK_X

    16

 * AXIS_Y -> TRACK_Y

    17

 * Uses the fact that they share the same internal encoding

    18

 *

    19

 * @param a the axis to convert

    20

 * @return the track corresponding to the axis

    21

 */

    22

static inline Track AxisToTrack(Axis a)

    23

{

    24

	return (Track)a;

    25

}

    26

    27

    28

    29

/**

    30

 * Maps a Track to the corresponding TrackBits value

    31

 * @param track the track to convert

    32

 * @return the converted TrackBits value of the track

    33

 */

    34

static inline TrackBits TrackToTrackBits(Track track)

    35

{

    36

	return (TrackBits)(1 << track);

    37

}

    38

    39

/**

    40

 * Maps an Axis to the corresponding TrackBits value

    41

 * @param a the axis to convert

    42

 * @return the converted TrackBits value of the axis

    43

 */

    44

static inline TrackBits AxisToTrackBits(Axis a)

    45

{

    46

	return TrackToTrackBits(AxisToTrack(a));

    47

}

    48

    49

/**

    50

 * Returns a single horizontal/vertical trackbit, that is in a specific tile corner.

    51

 *

    52

 * @param corner The corner of a tile.

    53

 * @return The TrackBits of the track in the corner.

    54

 */

    55

static inline TrackBits CornerToTrackBits(Corner corner)

    56

{

    57

	extern const TrackBits _corner_to_trackbits[];

    58

	assert(IsValidCorner(corner));

    59

	return _corner_to_trackbits[corner];

    60

}

    61

    62

    63

    64

/**

    65

 * Maps a Trackdir to the corresponding TrackdirBits value

    66

 * @param trackdir the track direction to convert

    67

 * @return the converted TrackdirBits value

    68

 */

    69

static inline TrackdirBits TrackdirToTrackdirBits(Trackdir trackdir)

    70

{

    71

	return (TrackdirBits)(1 << trackdir);

    72

}

    73

    74

/**

    75

 * Removes first Track from TrackBits and returns it

    76

 *

    77

 * This function searchs for the first bit in the TrackBits,

    78

 * remove this bit from the parameter and returns the found

    79

 * bit as Track value. It returns INVALID_TRACK if the

    80

 * parameter was TRACK_BIT_NONE or INVALID_TRACK_BIT. This

    81

 * is basically used in while-loops to get up to 6 possible

    82

 * tracks on a tile until the parameter becomes TRACK_BIT_NONE.

    83

 *

    84

 * @param tracks The value with the TrackBits

    85

 * @return The first Track from the TrackBits value

    86

 * @see FindFirstTrack

    87

 */

    88

static inline Track RemoveFirstTrack(TrackBits *tracks)

    89

{

    90

	if (*tracks != TRACK_BIT_NONE && *tracks != INVALID_TRACK_BIT) {

    91

		Track first = (Track)FIND_FIRST_BIT(*tracks);

    92

		ClrBit(*tracks, first);

    93

		return first;

    94

	}

    95

	return INVALID_TRACK;

    96

}

    97

    98

/**

    99

 * Removes first Trackdir from TrackdirBits and returns it

   100

 *

   101

 * This function searchs for the first bit in the TrackdirBits parameter,

   102

 * remove this bit from the parameter and returns the fnound bit as

   103

 * Trackdir value. It returns INVALID_TRACKDIR if the trackdirs is

   104

 * TRACKDIR_BIT_NONE or INVALID_TRACKDIR_BIT. This is basically used in a

   105

 * while-loop to get all track-directions step by step until the value

   106

 * reaches TRACKDIR_BIT_NONE.

   107

 *

   108

 * @param trackdirs The value with the TrackdirBits

   109

 * @return The first Trackdir from the TrackdirBits value

   110

 * @see FindFirstTrackdir

   111

 */

   112

static inline Trackdir RemoveFirstTrackdir(TrackdirBits *trackdirs)

   113

{

   114

	if (*trackdirs != TRACKDIR_BIT_NONE && *trackdirs != INVALID_TRACKDIR_BIT) {

   115

		Trackdir first = (Trackdir)FindFirstBit2x64(*trackdirs);

   116

		ClrBit(*trackdirs, first);

   117

		return first;

   118

	}

   119

	return INVALID_TRACKDIR;

   120

}

   121

   122

/**

   123

 * Returns first Track from TrackBits or INVALID_TRACK

   124

 *

   125

 * This function returns the first Track found in the TrackBits value as Track-value.

   126

 * It returns INVALID_TRACK if the parameter is TRACK_BIT_NONE or INVALID_TRACK_BIT.

   127

 *

   128

 * @param tracks The TrackBits value

   129

 * @return The first Track found or INVALID_TRACK

   130

 * @see RemoveFirstTrack

   131

 */

   132

static inline Track FindFirstTrack(TrackBits tracks)

   133

{

   134

	return (tracks != TRACK_BIT_NONE && tracks != INVALID_TRACK_BIT) ? (Track)FIND_FIRST_BIT(tracks) : INVALID_TRACK;

   135

}

   136

   137

/**

   138

 * Converts TrackBits to Track.

   139

 *

   140

 * This function converts a TrackBits value to a Track value. As it

   141

 * is not possible to convert two or more tracks to one track the

   142

 * parameter must contain only one track or be the INVALID_TRACK_BIT value.

   143

 *

   144

 * @param tracks The TrackBits value to convert

   145

 * @return The Track from the value or INVALID_TRACK

   146

 * @pre tracks must contains only one Track or be INVALID_TRACK_BIT

   147

 */

   148

static inline Track TrackBitsToTrack(TrackBits tracks)

   149

{

   150

	assert(tracks == INVALID_TRACK_BIT || (tracks != TRACK_BIT_NONE && KillFirstBit(tracks & TRACK_BIT_MASK) == TRACK_BIT_NONE));

   151

	return tracks != INVALID_TRACK_BIT ? (Track)FIND_FIRST_BIT(tracks & TRACK_BIT_MASK) : INVALID_TRACK;

   152

}

   153

   154

/**

   155

 * Returns first Trackdir from TrackdirBits or INVALID_TRACKDIR

   156

 *

   157

 * This function returns the first Trackdir in the given TrackdirBits value or

   158

 * INVALID_TRACKDIR if the value is TRACKDIR_BIT_NONE. The TrackdirBits must

   159

 * not be INVALID_TRACKDIR_BIT.

   160

 *

   161

 * @param trackdirs The TrackdirBits value

   162

 * @return The first Trackdir from the TrackdirBits or INVALID_TRACKDIR on TRACKDIR_BIT_NONE.

   163

 * @pre trackdirs must not be INVALID_TRACKDIR_BIT

   164

 * @see RemoveFirstTrackdir

   165

 */

   166

static inline Trackdir FindFirstTrackdir(TrackdirBits trackdirs)

   167

{

   168

	assert((trackdirs & ~TRACKDIR_BIT_MASK) == TRACKDIR_BIT_NONE);

   169

	return (trackdirs != TRACKDIR_BIT_NONE) ? (Trackdir)FindFirstBit2x64(trackdirs) : INVALID_TRACKDIR;

   170

}

   171

   172

/**

   173

 * Checks if a Track is valid.

   174

 *

   175

 * @param track The value to check

   176

 * @return true if the given value is a valid track.

   177

 * @note Use this in an assert()

   178

 */

   179

static inline bool IsValidTrack(Track track)

   180

{

   181

	return track < TRACK_END;

   182

}

   183

   184

/**

   185

 * Checks if a Trackdir is valid.

   186

 *

   187

 * @param trackdir The value to check

   188

 * @return true if the given valie is a valid Trackdir

   189

 * @note Use this in an assert()

   190

 */

   191

static inline bool IsValidTrackdir(Trackdir trackdir)

   192

{

   193

	return (TrackdirToTrackdirBits(trackdir) & TRACKDIR_BIT_MASK) != 0;

   194

}

   195

   196

   197

/*

   198

 * Functions describing logical relations between Tracks, TrackBits, Trackdirs

   199

 * TrackdirBits, Direction and DiagDirections.

   200

 */

   201

   202

/**

   203

 * Maps a trackdir to the reverse trackdir.

   204

 *

   205

 * Returns the reverse trackdir of a Trackdir value. The reverse trackdir

   206

 * is the same track with the other direction on it.

   207

 *

   208

 * @param trackdir The Trackdir value

   209

 * @return The reverse trackdir

   210

 * @pre trackdir must not be INVALID_TRACKDIR

   211

 */

   212

static inline Trackdir ReverseTrackdir(Trackdir trackdir)

   213

{

   214

	assert(trackdir != INVALID_TRACKDIR);

   215

	return (Trackdir)(trackdir ^ 8);

   216

}

   217

   218

/**

   219

 * Returns the Track that a given Trackdir represents

   220

 *

   221

 * This function filters the Track which is used in the Trackdir value and

   222

 * returns it as a Track value.

   223

 *

   224

 * @param trackdir The trackdir value

   225

 * @return The Track which is used in the value

   226

 */

   227

static inline Track TrackdirToTrack(Trackdir trackdir)

   228

{

   229

	return (Track)(trackdir & 0x7);

   230

}

   231

   232

/**

   233

 * Returns a Trackdir for the given Track

   234

 *

   235

 * Since every Track corresponds to two Trackdirs, we choose the

   236

 * one which points between NE and S. Note that the actual

   237

 * implementation is quite futile, but this might change

   238

 * in the future.

   239

 *

   240

 * @param track The given Track

   241

 * @return The Trackdir from the given Track

   242

 */

   243

static inline Trackdir TrackToTrackdir(Track track)

   244

{

   245

	return (Trackdir)track;

   246

}

   247

   248

/**

   249

 * Returns a TrackdirBit mask from a given Track

   250

 *

   251

 * The TrackdirBit mask contains the two TrackdirBits that

   252

 * correspond with the given Track (one for each direction).

   253

 *

   254

 * @param track The track to get the TrackdirBits from

   255

 * @return The TrackdirBits which the selected tracks

   256

 */

   257

static inline TrackdirBits TrackToTrackdirBits(Track track)

   258

{

   259

	Trackdir td = TrackToTrackdir(track);

   260

	return (TrackdirBits)(TrackdirToTrackdirBits(td) | TrackdirToTrackdirBits(ReverseTrackdir(td)));

   261

}

   262

   263

/**

   264

 * Discards all directional information from a TrackdirBits value

   265

 *

   266

 * Any Track which is present in either direction will be present in the result.

   267

 *

   268

 * @param bits The TrackdirBits to get the TrackBits from

   269

 * @return The TrackBits

   270

 */

   271

static inline TrackBits TrackdirBitsToTrackBits(TrackdirBits bits)

   272

{

   273

	return (TrackBits)((bits | (bits >> 8)) & TRACK_BIT_MASK);

   274

}

   275

   276

/**

   277

 * Maps a trackdir to the trackdir that you will end up on if you go straight

   278

 * ahead.

   279

 *

   280

 * This will be the same trackdir for diagonal trackdirs, but a

   281

 * different (alternating) one for straight trackdirs

   282

 *

   283

 * @param trackdir The given trackdir

   284

 * @return The next Trackdir value of the next tile.

   285

 */

   286

static inline Trackdir NextTrackdir(Trackdir trackdir)

   287

{

   288

	extern const Trackdir _next_trackdir[TRACKDIR_END];

   289

	return _next_trackdir[trackdir];

   290

}

   291

   292

/**

   293

 * Maps a track to all tracks that make 90 deg turns with it.

   294

 *

   295

 * For the diagonal directions these are the complement of the

   296

 * direction, for the straight directions these are the

   297

 * two vertical or horizontal tracks, depend on the given direction

   298

 *

   299

 * @param track The given track

   300

 * @return The TrackBits with the tracks marked which cross the given track by 90 deg.

   301

 */

   302

static inline TrackBits TrackCrossesTracks(Track track)

   303

{

   304

	extern const TrackBits _track_crosses_tracks[TRACK_END];

   305

	return _track_crosses_tracks[track];

   306

}

   307

   308

/**

   309

 * Maps a trackdir to the (4-way) direction the tile is exited when following

   310

 * that trackdir.

   311

 *

   312

 * For the diagonal directions these are the same directions. For

   313

 * the straight directions these are the directions from the imagined

   314

 * base-tile to the bordering tile which will be joined if the given

   315

 * straight direction is leaved from the base-tile.

   316

 *

   317

 * @param trackdir The given track direction

   318

 * @return The direction which points to the resulting tile if following the Trackdir

   319

 */

   320

static inline DiagDirection TrackdirToExitdir(Trackdir trackdir)

   321

{

   322

	extern const DiagDirection _trackdir_to_exitdir[TRACKDIR_END];

   323

	return _trackdir_to_exitdir[trackdir];

   324

}

   325

   326

/**

   327

 * Maps a track and an (4-way) dir to the trackdir that represents the track

   328

 * with the exit in the given direction.

   329

 *

   330

 * For the diagonal tracks the resulting track direction are clear for a given

   331

 * DiagDirection. It either matches the direction or it returns INVALID_TRACKDIR,

   332

 * as a TRACK_X cannot be applied with DIAG_SE.

   333

 * For the straight tracks the resulting track direction will be the

   334

 * direction which the DiagDirection is pointing. But this will be INVALID_TRACKDIR

   335

 * if the DiagDirection is pointing 'away' the track.

   336

 *

   337

 * @param track The track to applie an direction on

   338

 * @param diagdir The DiagDirection to applie on

   339

 * @return The resulting track direction or INVALID_TRACKDIR if not possible.

   340

 */

   341

static inline Trackdir TrackExitdirToTrackdir(Track track, DiagDirection diagdir)

   342

{

   343

	extern const Trackdir _track_exitdir_to_trackdir[TRACK_END][DIAGDIR_END];

   344

	return _track_exitdir_to_trackdir[track][diagdir];

   345

}

   346

   347

/**

   348

 * Maps a track and an (4-way) dir to the trackdir that represents the track

   349

 * with the entry in the given direction.

   350

 *

   351

 * For the diagonal tracks the return value is clear, its either the matching

   352

 * track direction or INVALID_TRACKDIR.

   353

 * For the straight tracks this returns the track direction which results if

   354

 * you follow the DiagDirection and then turn by 45 deg left or right on the

   355

 * next tile. The new direction on the new track will be the returning Trackdir

   356

 * value. If the parameters makes no sense like the track TRACK_UPPER and the

   357

 * diraction DIAGDIR_NE (target track cannot be reached) this function returns

   358

 * INVALID_TRACKDIR.

   359

 *

   360

 * @param track The target track

   361

 * @param diagdir The direction to "come from"

   362

 * @return the resulting Trackdir or INVALID_TRACKDIR if not possible.

   363

 */

   364

static inline Trackdir TrackEnterdirToTrackdir(Track track, DiagDirection diagdir)

   365

{

   366

	extern const Trackdir _track_enterdir_to_trackdir[TRACK_END][DIAGDIR_END];

   367

	return _track_enterdir_to_trackdir[track][diagdir];

   368

}

   369

   370

/**

   371

 * Maps a track and a full (8-way) direction to the trackdir that represents

   372

 * the track running in the given direction.

   373

 */

   374

static inline Trackdir TrackDirectionToTrackdir(Track track, Direction dir)

   375

{

   376

	extern const Trackdir _track_direction_to_trackdir[TRACK_END][DIR_END];

   377

	return _track_direction_to_trackdir[track][dir];

   378

}

   379

   380

/**

   381

 * Maps a (4-way) direction to the diagonal trackdir that runs in that

   382

 * direction.

   383

 *

   384

 * @param diagdir The direction

   385

 * @return The resulting Trackdir direction

   386

 */

   387

static inline Trackdir DiagdirToDiagTrackdir(DiagDirection diagdir)

   388

{

   389

	extern const Trackdir _dir_to_diag_trackdir[DIAGDIR_END];

   390

	return _dir_to_diag_trackdir[diagdir];

   391

}

   392

   393

/**

   394

 * Returns all trackdirs that can be reached when entering a tile from a given

   395

 * (diagonal) direction.

   396

 *

   397

 * This will obviously include 90 degree turns, since no information is available

   398

 * about the exact angle of entering

   399

 *

   400

 * @param diagdir The joining direction

   401

 * @return The TrackdirBits which can be used from the given direction

   402

 * @see DiagdirReachesTracks

   403

 */

   404

static inline TrackdirBits DiagdirReachesTrackdirs(DiagDirection diagdir)

   405

{

   406

	extern const TrackdirBits _exitdir_reaches_trackdirs[DIAGDIR_END];

   407

	return _exitdir_reaches_trackdirs[diagdir];

   408

}

   409

   410

/**

   411

 * Returns all tracks that can be reached when entering a tile from a given

   412

 * (diagonal) direction.

   413

 *

   414

 * This will obviously include 90 degree turns, since no

   415

 * information is available about the exact angle of entering

   416

 *

   417

 * @param diagdir The joining irection

   418

 * @return The tracks which can be used

   419

 * @see DiagdirReachesTrackdirs

   420

 */

   421

static inline TrackBits DiagdirReachesTracks(DiagDirection diagdir) { return TrackdirBitsToTrackBits(DiagdirReachesTrackdirs(diagdir)); }

   422

   423

/**

   424

 * Maps a trackdir to the trackdirs that can be reached from it (ie, when

   425

 * entering the next tile.

   426

 *

   427

 * This will include 90 degree turns!

   428

 *

   429

 * @param trackdir The track direction which will be leaved

   430

 * @return The track directions which can be used from this direction (in the next tile)

   431

 */

   432

static inline TrackdirBits TrackdirReachesTrackdirs(Trackdir trackdir)

   433

{

   434

	extern const TrackdirBits _exitdir_reaches_trackdirs[DIAGDIR_END];

   435

	return _exitdir_reaches_trackdirs[TrackdirToExitdir(trackdir)];

   436

}

   437

/* Note that there is no direct table for this function (there used to be),

   438

 * but it uses two simpeler tables to achieve the result */

   439

   440

/**

   441

 * Maps a trackdir to all trackdirs that make 90 deg turns with it.

   442

 *

   443

 * For the diagonal tracks this returns the track direction bits

   444

 * of the other axis in both directions, which cannot be joined by

   445

 * the given track direction.

   446

 * For the straight tracks this returns all possible 90 deg turns

   447

 * either on the current tile (which no train can joined) or on the

   448

 * bordering tiles.

   449

 *

   450

 * @param trackdir The track direction

   451

 * @return The TrackdirBits which are (more or less) 90 deg turns.

   452

 */

   453

static inline TrackdirBits TrackdirCrossesTrackdirs(Trackdir trackdir)

   454

{

   455

	extern const TrackdirBits _track_crosses_trackdirs[TRACKDIR_END];

   456

	return _track_crosses_trackdirs[TrackdirToTrack(trackdir)];

   457

}

   458

   459

/**

   460

 * Checks if a given Track is diagonal

   461

 *

   462

 * @param track The given track to check

   463

 * @return true if diagonal, else false

   464

 */

   465

static inline bool IsDiagonalTrack(Track track)

   466

{

   467

	return (track == TRACK_X) || (track == TRACK_Y);

   468

}

   469

   470

/**

   471

 * Checks if a given Trackdir is diagonal.

   472

 *

   473

 * @param trackdir The given trackdir

   474

 * @return true if the trackdir use a diagonal track

   475

 */

   476

static inline bool IsDiagonalTrackdir(Trackdir trackdir)

   477

{

   478

	return IsDiagonalTrack(TrackdirToTrack(trackdir));

   479

}

   480

   481

   482

/**

   483

 * Checks if the given tracks overlap, ie form a crossing. Basically this

   484

 * means when there is more than one track on the tile, exept when there are

   485

 * two parallel tracks.

   486

 * @param  bits The tracks present.

   487

 * @return Whether the tracks present overlap in any way.

   488

 */

   489

static inline bool TracksOverlap(TrackBits bits)

   490

{