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

 * Find the opposite track to a given track.

   202

 *

   203

 * TRACK_LOWER -> TRACK_UPPER and vice versa, likewise for left/right.

   204

 * TRACK_X is mapped to TRACK_Y and reversed.

   205

 *

   206

 * @param t the track to convert

   207

 * @return the opposite track

   208

 */

   209

static inline Track TrackToOppositeTrack(Track t)

   210

{

   211

	assert(t != INVALID_TRACK);

   212

	return (Track)(t ^ 1);

   213

}

   214

   215

/**

   216

 * Maps a trackdir to the reverse trackdir.

   217

 *

   218

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

   219

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

   220

 *

   221

 * @param trackdir The Trackdir value

   222

 * @return The reverse trackdir

   223

 * @pre trackdir must not be INVALID_TRACKDIR

   224

 */

   225

static inline Trackdir ReverseTrackdir(Trackdir trackdir)

   226

{

   227

	assert(trackdir != INVALID_TRACKDIR);

   228

	return (Trackdir)(trackdir ^ 8);

   229

}

   230

   231

/**

   232

 * Returns the Track that a given Trackdir represents

   233

 *

   234

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

   235

 * returns it as a Track value.

   236

 *

   237

 * @param trackdir The trackdir value

   238

 * @return The Track which is used in the value

   239

 */

   240

static inline Track TrackdirToTrack(Trackdir trackdir)

   241

{

   242

	return (Track)(trackdir & 0x7);

   243

}

   244

   245

/**

   246

 * Returns a Trackdir for the given Track

   247

 *

   248

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

   249

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

   250

 * implementation is quite futile, but this might change

   251

 * in the future.

   252

 *

   253

 * @param track The given Track

   254

 * @return The Trackdir from the given Track

   255

 */

   256

static inline Trackdir TrackToTrackdir(Track track)

   257

{

   258

	return (Trackdir)track;

   259

}

   260

   261

/**

   262

 * Returns a TrackdirBit mask from a given Track

   263

 *

   264

 * The TrackdirBit mask contains the two TrackdirBits that

   265

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

   266

 *

   267

 * @param track The track to get the TrackdirBits from

   268

 * @return The TrackdirBits which the selected tracks

   269

 */

   270

static inline TrackdirBits TrackToTrackdirBits(Track track)

   271

{

   272

	Trackdir td = TrackToTrackdir(track);

   273

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

   274

}

   275

   276

/**

   277

 * Discards all directional information from a TrackdirBits value

   278

 *

   279

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

   280

 *

   281

 * @param bits The TrackdirBits to get the TrackBits from

   282

 * @return The TrackBits

   283

 */

   284

static inline TrackBits TrackdirBitsToTrackBits(TrackdirBits bits)

   285

{

   286

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

   287

}

   288

   289

/**

   290

 * Converts TrackBits to TrackdirBits while allowing both directions.

   291

 *

   292

 * @param bits The TrackBits

   293

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

   294

 */

   295

static inline TrackdirBits TrackBitsToTrackdirBits(TrackBits bits)

   296

{

   297

	return (TrackdirBits)(bits * 0x101);

   298

}

   299

   300

/**

   301

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

   302

 *

   303

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   304

 * @return the present trackdirs

   305

 */

   306

static inline TrackdirBits TrackStatusToTrackdirBits(TrackStatus ts)

   307

{

   308

	return (TrackdirBits)(ts & TRACKDIR_BIT_MASK);

   309

}

   310

   311

/**

   312

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

   313

 *

   314

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   315

 * @return the present tracks

   316

 */

   317

static inline TrackBits TrackStatusToTrackBits(TrackStatus ts)

   318

{

   319

	return TrackdirBitsToTrackBits(TrackStatusToTrackdirBits(ts));

   320

}

   321

   322

/**

   323

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

   324

 *

   325

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

   326

 *

   327

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   328

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

   329

 */

   330

static inline TrackdirBits TrackStatusToRedSignals(TrackStatus ts)

   331

{

   332

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

   333

}

   334

   335

/**

   336

 * Builds a TrackStatus

   337

 *

   338

 * @param trackdirbits present trackdirs

   339

 * @param red_signals red signals

   340

 * @return the TrackStatus representing the given information

   341

 */

   342

static inline TrackStatus CombineTrackStatus(TrackdirBits trackdirbits, TrackdirBits red_signals)

   343

{

   344

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

   345

}

   346

   347

/**

   348

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

   349

 * ahead.

   350

 *

   351

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

   352

 * different (alternating) one for straight trackdirs

   353

 *

   354

 * @param trackdir The given trackdir

   355

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

   356

 */

   357

static inline Trackdir NextTrackdir(Trackdir trackdir)

   358

{

   359

	extern const Trackdir _next_trackdir[TRACKDIR_END];

   360

	return _next_trackdir[trackdir];

   361

}

   362

   363

/**

   364

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

   365

 *

   366

 * For the diagonal directions these are the complement of the

   367

 * direction, for the straight directions these are the

   368

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

   369

 *

   370

 * @param track The given track

   371

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

   372

 */

   373

static inline TrackBits TrackCrossesTracks(Track track)

   374

{

   375

	extern const TrackBits _track_crosses_tracks[TRACK_END];

   376

	return _track_crosses_tracks[track];

   377

}

   378

   379

/**

   380

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

   381

 * that trackdir.

   382

 *

   383

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

   384

 * the straight directions these are the directions from the imagined

   385

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

   386

 * straight direction is leaved from the base-tile.

   387

 *

   388

 * @param trackdir The given track direction

   389

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

   390

 */

   391

static inline DiagDirection TrackdirToExitdir(Trackdir trackdir)

   392

{

   393

	extern const DiagDirection _trackdir_to_exitdir[TRACKDIR_END];

   394

	return _trackdir_to_exitdir[trackdir];

   395

}

   396

   397

/**

   398

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

   399

 * with the exit in the given direction.

   400

 *

   401

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

   402

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

   403

 * as a TRACK_X cannot be applied with DIAG_SE.

   404

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

   405

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

   406

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

   407

 *

   408

 * @param track The track to applie an direction on

   409

 * @param diagdir The DiagDirection to applie on

   410

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

   411

 */

   412

static inline Trackdir TrackExitdirToTrackdir(Track track, DiagDirection diagdir)

   413

{

   414

	extern const Trackdir _track_exitdir_to_trackdir[TRACK_END][DIAGDIR_END];

   415

	return _track_exitdir_to_trackdir[track][diagdir];

   416

}

   417

   418

/**

   419

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

   420

 * with the entry in the given direction.

   421

 *

   422

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

   423

 * track direction or INVALID_TRACKDIR.

   424

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

   425

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

   426

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

   427

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

   428

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

   429

 * INVALID_TRACKDIR.

   430

 *

   431

 * @param track The target track

   432

 * @param diagdir The direction to "come from"

   433

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

   434

 */

   435

static inline Trackdir TrackEnterdirToTrackdir(Track track, DiagDirection diagdir)

   436

{

   437

	extern const Trackdir _track_enterdir_to_trackdir[TRACK_END][DIAGDIR_END];

   438

	return _track_enterdir_to_trackdir[track][diagdir];

   439

}

   440

   441

/**

   442

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

   443

 * the track running in the given direction.

   444

 */

   445

static inline Trackdir TrackDirectionToTrackdir(Track track, Direction dir)

   446

{

   447

	extern const Trackdir _track_direction_to_trackdir[TRACK_END][DIR_END];

   448

	return _track_direction_to_trackdir[track][dir];

   449

}

   450

   451

/**

   452

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

   453

 *

   454

 * @param diagdir The direction

   455

 * @return The resulting Track

   456

 */

   457

static inline Track DiagDirToDiagTrack(DiagDirection diagdir)

   458

{

   459

	return (Track)(diagdir & 1);

   460

}

   461

   462

/**

   463

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

   464

 *

   465

 * @param diagdir The direction

   466

 * @return The resulting TrackBits

   467

 */

   468

static inline TrackBits DiagDirToDiagTrackBits(DiagDirection diagdir)

   469

{

   470

	return TrackToTrackBits(DiagDirToDiagTrack(diagdir));

   471

}

   472

   473

/**

   474

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

   475

 * direction.

   476

 *

   477

 * @param diagdir The direction

   478

 * @return The resulting Trackdir direction

   479

 */

   480

static inline Trackdir DiagDirToDiagTrackdir(DiagDirection diagdir)

   481

{

   482

	extern const Trackdir _dir_to_diag_trackdir[DIAGDIR_END];

   483

	return _dir_to_diag_trackdir[diagdir];

   484

}

   485

   486

/**

   487

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

   488

 * (diagonal) direction.

   489

 *

   490

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

   491

 * about the exact angle of entering

   492

 *

   493

 * @param diagdir The joining direction

   494

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

   495

 * @see DiagdirReachesTracks

   496

 */

   497

static inline TrackdirBits DiagdirReachesTrackdirs(DiagDirection diagdir)

   498

{

   499

	extern const TrackdirBits _exitdir_reaches_trackdirs[DIAGDIR_END];

   500

	return _exitdir_reaches_trackdirs[diagdir];

   501

}

   502

   503

/**

   504

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

   505

 * (diagonal) direction.

   506

 *

   507

 * This will obviously include 90 degree turns, since no

   508

 * information is available about the exact angle of entering

   509

 *

   510

 * @param diagdir The joining irection

   511

 * @return The tracks which can be used

   512

 * @see DiagdirReachesTrackdirs

   513

 */

   514

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

   515

   516

/**

   517

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

   518

 * entering the next tile.

   519

 *

   520

 * This will include 90 degree turns!

   521

 *

   522

 * @param trackdir The track direction which will be leaved