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

 * Maps a Track to the corresponding TrackBits value

    29

 * @param track the track to convert

    30

 * @return the converted TrackBits value of the track

    31

 */

    32

static inline TrackBits TrackToTrackBits(Track track)

    33

{

    34

	return (TrackBits)(1 << track);

    35

}

    36

    37

/**

    38

 * Maps an Axis to the corresponding TrackBits value

    39

 * @param a the axis to convert

    40

 * @return the converted TrackBits value of the axis

    41

 */

    42

static inline TrackBits AxisToTrackBits(Axis a)

    43

{

    44

	return TrackToTrackBits(AxisToTrack(a));

    45

}

    46

    47

/**

    48

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

    49

 *

    50

 * @param corner The corner of a tile.

    51

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

    52

 */

    53

static inline TrackBits CornerToTrackBits(Corner corner)

    54

{

    55

	extern const TrackBits _corner_to_trackbits[];

    56

	assert(IsValidCorner(corner));

    57

	return _corner_to_trackbits[corner];

    58

}

    59

    60

    61

    62

/**

    63

 * Maps a Trackdir to the corresponding TrackdirBits value

    64

 * @param trackdir the track direction to convert

    65

 * @return the converted TrackdirBits value

    66

 */

    67

static inline TrackdirBits TrackdirToTrackdirBits(Trackdir trackdir)

    68

{

    69

	return (TrackdirBits)(1 << trackdir);

    70

}

    71

    72

/**

    73

 * Removes first Track from TrackBits and returns it

    74

 *

    75

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

    76

 * remove this bit from the parameter and returns the found

    77

 * bit as Track value. It returns INVALID_TRACK if the

    78

 * parameter was TRACK_BIT_NONE or INVALID_TRACK_BIT. This

    79

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

    80

 * tracks on a tile until the parameter becomes TRACK_BIT_NONE.

    81

 *

    82

 * @param tracks The value with the TrackBits

    83

 * @return The first Track from the TrackBits value

    84

 * @see FindFirstTrack

    85

 */

    86

static inline Track RemoveFirstTrack(TrackBits *tracks)

    87

{

    88

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

    89

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

    90

		ClrBit(*tracks, first);

    91

		return first;

    92

	}

    93

	return INVALID_TRACK;

    94

}

    95

    96

/**

    97

 * Removes first Trackdir from TrackdirBits and returns it

    98

 *

    99

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

   100

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

   101

 * Trackdir value. It returns INVALID_TRACKDIR if the trackdirs is

   102

 * TRACKDIR_BIT_NONE or INVALID_TRACKDIR_BIT. This is basically used in a

   103

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

   104

 * reaches TRACKDIR_BIT_NONE.

   105

 *

   106

 * @param trackdirs The value with the TrackdirBits

   107

 * @return The first Trackdir from the TrackdirBits value

   108

 * @see FindFirstTrackdir

   109

 */

   110

static inline Trackdir RemoveFirstTrackdir(TrackdirBits *trackdirs)

   111

{

   112

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

   113

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

   114

		ClrBit(*trackdirs, first);

   115

		return first;

   116

	}

   117

	return INVALID_TRACKDIR;

   118

}

   119

   120

/**

   121

 * Returns first Track from TrackBits or INVALID_TRACK

   122

 *

   123

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

   124

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

   125

 *

   126

 * @param tracks The TrackBits value

   127

 * @return The first Track found or INVALID_TRACK

   128

 * @see RemoveFirstTrack

   129

 */

   130

static inline Track FindFirstTrack(TrackBits tracks)

   131

{

   132

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

   133

}

   134

   135

/**

   136

 * Converts TrackBits to Track.

   137

 *

   138

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

   139

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

   140

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

   141

 *

   142

 * @param tracks The TrackBits value to convert

   143

 * @return The Track from the value or INVALID_TRACK

   144

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

   145

 */

   146

static inline Track TrackBitsToTrack(TrackBits tracks)

   147

{

   148

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

   149

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

   150

}

   151

   152

/**

   153

 * Returns first Trackdir from TrackdirBits or INVALID_TRACKDIR

   154

 *

   155

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

   156

 * INVALID_TRACKDIR if the value is TRACKDIR_BIT_NONE. The TrackdirBits must

   157

 * not be INVALID_TRACKDIR_BIT.

   158

 *

   159

 * @param trackdirs The TrackdirBits value

   160

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

   161

 * @pre trackdirs must not be INVALID_TRACKDIR_BIT

   162

 * @see RemoveFirstTrackdir

   163

 */

   164

static inline Trackdir FindFirstTrackdir(TrackdirBits trackdirs)

   165

{

   166

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

   167

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

   168

}

   169

   170

/**

   171

 * Checks if a Track is valid.

   172

 *

   173

 * @param track The value to check

   174

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

   175

 * @note Use this in an assert()

   176

 */

   177

static inline bool IsValidTrack(Track track)

   178

{

   179

	return track < TRACK_END;

   180

}

   181

   182

/**

   183

 * Checks if a Trackdir is valid.

   184

 *

   185

 * @param trackdir The value to check

   186

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

   187

 * @note Use this in an assert()

   188

 */

   189

static inline bool IsValidTrackdir(Trackdir trackdir)

   190

{

   191

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

   192

}

   193

   194

   195

/*

   196

 * Functions describing logical relations between Tracks, TrackBits, Trackdirs

   197

 * TrackdirBits, Direction and DiagDirections.

   198

 */

   199

   200

/**

   201

 * Maps a trackdir to the reverse trackdir.

   202

 *

   203

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

   204

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

   205

 *

   206

 * @param trackdir The Trackdir value

   207

 * @return The reverse trackdir

   208

 * @pre trackdir must not be INVALID_TRACKDIR

   209

 */

   210

static inline Trackdir ReverseTrackdir(Trackdir trackdir)

   211

{

   212

	assert(trackdir != INVALID_TRACKDIR);

   213

	return (Trackdir)(trackdir ^ 8);

   214

}

   215

   216

/**

   217

 * Returns the Track that a given Trackdir represents

   218

 *

   219

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

   220

 * returns it as a Track value.

   221

 *

   222

 * @param trackdir The trackdir value

   223

 * @return The Track which is used in the value

   224

 */

   225

static inline Track TrackdirToTrack(Trackdir trackdir)

   226

{

   227

	return (Track)(trackdir & 0x7);

   228

}

   229

   230

/**

   231

 * Returns a Trackdir for the given Track

   232

 *

   233

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

   234

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

   235

 * implementation is quite futile, but this might change

   236

 * in the future.

   237

 *

   238

 * @param track The given Track

   239

 * @return The Trackdir from the given Track

   240

 */

   241

static inline Trackdir TrackToTrackdir(Track track)

   242

{

   243

	return (Trackdir)track;

   244

}

   245

   246

/**

   247

 * Returns a TrackdirBit mask from a given Track

   248

 *

   249

 * The TrackdirBit mask contains the two TrackdirBits that

   250

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

   251

 *

   252

 * @param track The track to get the TrackdirBits from

   253

 * @return The TrackdirBits which the selected tracks

   254

 */

   255

static inline TrackdirBits TrackToTrackdirBits(Track track)

   256

{

   257

	Trackdir td = TrackToTrackdir(track);

   258

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

   259

}

   260

   261

/**

   262

 * Discards all directional information from a TrackdirBits value

   263

 *

   264

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

   265

 *

   266

 * @param bits The TrackdirBits to get the TrackBits from

   267

 * @return The TrackBits

   268

 */

   269

static inline TrackBits TrackdirBitsToTrackBits(TrackdirBits bits)

   270

{

   271

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

   272

}

   273

   274

/**

   275

 * Converts TrackBits to TrackdirBits while allowing both directions.

   276

 *

   277

 * @param bits The TrackBits

   278

 * @return The TrackdirBits containing of bits in both directions.

   279

 */

   280

static inline TrackdirBits TrackBitsToTrackdirBits(TrackBits bits)

   281

{

   282

	return (TrackdirBits)(bits * 0x101);

   283

}

   284

   285

/**

   286

 * Returns the present-trackdir-information of a TrackStatus.

   287

 *

   288

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   289

 * @return the present trackdirs

   290

 */

   291

static inline TrackdirBits TrackStatusToTrackdirBits(TrackStatus ts)

   292

{

   293

	return (TrackdirBits)(ts & TRACKDIR_BIT_MASK);

   294

}

   295

   296

/**

   297

 * Returns the present-track-information of a TrackStatus.

   298

 *

   299

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   300

 * @return the present tracks

   301

 */

   302

static inline TrackBits TrackStatusToTrackBits(TrackStatus ts)

   303

{

   304

	return TrackdirBitsToTrackBits(TrackStatusToTrackdirBits(ts));

   305

}

   306

   307

/**

   308

 * Returns the red-signal-information of a TrackStatus.

   309

 *

   310

 * Note: The result may contain red signals for non-present tracks.

   311

 *

   312

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   313

 * @return the The trackdirs that are blocked by red-signals

   314

 */

   315

static inline TrackdirBits TrackStatusToRedSignals(TrackStatus ts)

   316

{

   317

	return (TrackdirBits)((ts >> 16) & TRACKDIR_BIT_MASK);

   318

}

   319

   320

/**

   321

 * Builds a TrackStatus

   322

 *

   323

 * @param trackdirbits present trackdirs

   324

 * @param red_signals red signals

   325

 * @return the TrackStatus representing the given information

   326

 */

   327

static inline TrackStatus CombineTrackStatus(TrackdirBits trackdirbits, TrackdirBits red_signals)

   328

{

   329

	return (TrackStatus)(trackdirbits | (red_signals << 16));

   330

}

   331

   332

/**

   333

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

   334

 * ahead.

   335

 *

   336

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

   337

 * different (alternating) one for straight trackdirs

   338

 *

   339

 * @param trackdir The given trackdir

   340

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

   341

 */

   342

static inline Trackdir NextTrackdir(Trackdir trackdir)

   343

{

   344

	extern const Trackdir _next_trackdir[TRACKDIR_END];

   345

	return _next_trackdir[trackdir];

   346

}

   347

   348

/**

   349

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

   350

 *

   351

 * For the diagonal directions these are the complement of the

   352

 * direction, for the straight directions these are the

   353

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

   354

 *

   355

 * @param track The given track

   356

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

   357

 */

   358

static inline TrackBits TrackCrossesTracks(Track track)

   359

{

   360

	extern const TrackBits _track_crosses_tracks[TRACK_END];

   361

	return _track_crosses_tracks[track];

   362

}

   363

   364

/**

   365

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

   366

 * that trackdir.

   367

 *

   368

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

   369

 * the straight directions these are the directions from the imagined

   370

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

   371

 * straight direction is leaved from the base-tile.

   372

 *

   373

 * @param trackdir The given track direction

   374

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

   375

 */

   376

static inline DiagDirection TrackdirToExitdir(Trackdir trackdir)

   377

{

   378

	extern const DiagDirection _trackdir_to_exitdir[TRACKDIR_END];

   379

	return _trackdir_to_exitdir[trackdir];

   380

}

   381

   382

/**

   383

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

   384

 * with the exit in the given direction.

   385

 *

   386

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

   387

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

   388

 * as a TRACK_X cannot be applied with DIAG_SE.

   389

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

   390

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

   391

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

   392

 *

   393

 * @param track The track to applie an direction on

   394

 * @param diagdir The DiagDirection to applie on

   395

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

   396

 */

   397

static inline Trackdir TrackExitdirToTrackdir(Track track, DiagDirection diagdir)

   398

{

   399

	extern const Trackdir _track_exitdir_to_trackdir[TRACK_END][DIAGDIR_END];

   400

	return _track_exitdir_to_trackdir[track][diagdir];

   401

}

   402

   403

/**

   404

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

   405

 * with the entry in the given direction.

   406

 *

   407

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

   408

 * track direction or INVALID_TRACKDIR.

   409

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

   410

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

   411

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

   412

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

   413

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

   414

 * INVALID_TRACKDIR.

   415

 *

   416

 * @param track The target track

   417

 * @param diagdir The direction to "come from"

   418

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

   419

 */

   420

static inline Trackdir TrackEnterdirToTrackdir(Track track, DiagDirection diagdir)

   421

{

   422

	extern const Trackdir _track_enterdir_to_trackdir[TRACK_END][DIAGDIR_END];

   423

	return _track_enterdir_to_trackdir[track][diagdir];

   424

}

   425

   426

/**

   427

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

   428

 * the track running in the given direction.

   429

 */

   430

static inline Trackdir TrackDirectionToTrackdir(Track track, Direction dir)

   431

{

   432

	extern const Trackdir _track_direction_to_trackdir[TRACK_END][DIR_END];

   433

	return _track_direction_to_trackdir[track][dir];

   434

}

   435

   436

/**

   437

 * Maps a (4-way) direction to the diagonal track incidating with that diagdir

   438

 *

   439

 * @param diagdir The direction

   440

 * @return The resulting Track

   441

 */

   442

static inline Track DiagDirToDiagTrack(DiagDirection diagdir)

   443

{

   444

	return (Track)(diagdir & 1);

   445

}

   446

   447

/**

   448

 * Maps a (4-way) direction to the diagonal track bits incidating with that diagdir

   449

 *

   450

 * @param diagdir The direction

   451

 * @return The resulting TrackBits

   452

 */

   453

static inline TrackBits DiagDirToDiagTrackBits(DiagDirection diagdir)

   454

{

   455

	return TrackToTrackBits(DiagDirToDiagTrack(diagdir));

   456

}

   457

   458

/**

   459

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

   460

 * direction.

   461

 *

   462

 * @param diagdir The direction

   463

 * @return The resulting Trackdir direction

   464

 */

   465

static inline Trackdir DiagDirToDiagTrackdir(DiagDirection diagdir)

   466

{

   467

	extern const Trackdir _dir_to_diag_trackdir[DIAGDIR_END];

   468

	return _dir_to_diag_trackdir[diagdir];

   469

}

   470

   471

/**

   472

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

   473

 * (diagonal) direction.

   474

 *

   475

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

   476

 * about the exact angle of entering

   477

 *

   478

 * @param diagdir The joining direction

   479

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

   480

 * @see DiagdirReachesTracks

   481

 */

   482

static inline TrackdirBits DiagdirReachesTrackdirs(DiagDirection diagdir)

   483

{

   484

	extern const TrackdirBits _exitdir_reaches_trackdirs[DIAGDIR_END];

   485

	return _exitdir_reaches_trackdirs[diagdir];

   486

}

   487

   488

/**

   489

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

   490

 * (diagonal) direction.

   491

 *

   492

 * This will obviously include 90 degree turns, since no

   493

 * information is available about the exact angle of entering

   494

 *

   495

 * @param diagdir The joining irection

   496

 * @return The tracks which can be used

   497

 * @see DiagdirReachesTrackdirs

   498

 */

   499

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

   500

   501

/**

   502

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

   503

 * entering the next tile.

   504

 *

   505

 * This will include 90 degree turns!

   506

 *

   507

 * @param trackdir The track direction which will be leaved

   508

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

   509

 */

   510

static inline TrackdirBits TrackdirReachesTrackdirs(Trackdir trackdir)

   511

{

   512

	extern const TrackdirBits _exitdir_reaches_trackdirs[DIAGDIR_END];

   513

	return _exitdir_reaches_trackdirs[TrackdirToExitdir(trackdir)];

   514

}

   515

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

   516

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

   517

   518

/**

   519

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

   520

 *

   521

 * For the diagonal tracks this returns the track direction bits

   522

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

   523

 * the given track direction.

   524