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

 * Converts TrackBits to TrackdirBits while allowing both directions.

   278

 *

   279

 * @param bits The TrackBits

   280

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

   281

 */

   282

static inline TrackdirBits TrackBitsToTrackdirBits(TrackBits bits)

   283

{

   284

	return (TrackdirBits)(bits * 0x101);

   285

}

   286

   287

/**

   288

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

   289

 *

   290

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   291

 * @return the present trackdirs

   292

 */

   293

static inline TrackdirBits TrackStatusToTrackdirBits(TrackStatus ts)

   294

{

   295

	return (TrackdirBits)(ts & TRACKDIR_BIT_MASK);

   296

}

   297

   298

/**

   299

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

   300

 *

   301

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   302

 * @return the present tracks

   303

 */

   304

static inline TrackBits TrackStatusToTrackBits(TrackStatus ts)

   305

{

   306

	return TrackdirBitsToTrackBits(TrackStatusToTrackdirBits(ts));

   307

}

   308

   309

/**

   310

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

   311

 *

   312

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

   313

 *

   314

 * @param ts The TrackStatus returned by GetTileTrackStatus()

   315

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

   316

 */

   317

static inline TrackdirBits TrackStatusToRedSignals(TrackStatus ts)

   318

{

   319

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

   320

}

   321

   322

/**

   323

 * Builds a TrackStatus

   324

 *

   325

 * @param trackdirbits present trackdirs

   326

 * @param red_signals red signals

   327

 * @return the TrackStatus representing the given information

   328

 */

   329

static inline TrackStatus CombineTrackStatus(TrackdirBits trackdirbits, TrackdirBits red_signals)

   330

{

   331

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

   332

}

   333

   334

/**

   335

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

   336

 * ahead.

   337

 *

   338

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

   339

 * different (alternating) one for straight trackdirs

   340

 *

   341

 * @param trackdir The given trackdir

   342

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

   343

 */

   344

static inline Trackdir NextTrackdir(Trackdir trackdir)

   345

{

   346

	extern const Trackdir _next_trackdir[TRACKDIR_END];

   347

	return _next_trackdir[trackdir];

   348

}

   349

   350

/**

   351

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

   352

 *

   353

 * For the diagonal directions these are the complement of the

   354

 * direction, for the straight directions these are the

   355

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

   356

 *

   357

 * @param track The given track

   358

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

   359

 */

   360

static inline TrackBits TrackCrossesTracks(Track track)

   361

{

   362

	extern const TrackBits _track_crosses_tracks[TRACK_END];

   363

	return _track_crosses_tracks[track];

   364

}

   365

   366

/**

   367

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

   368

 * that trackdir.

   369

 *

   370

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

   371

 * the straight directions these are the directions from the imagined

   372

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

   373

 * straight direction is leaved from the base-tile.

   374

 *

   375

 * @param trackdir The given track direction

   376

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

   377

 */

   378

static inline DiagDirection TrackdirToExitdir(Trackdir trackdir)

   379

{

   380

	extern const DiagDirection _trackdir_to_exitdir[TRACKDIR_END];

   381

	return _trackdir_to_exitdir[trackdir];

   382

}

   383

   384

/**

   385

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

   386

 * with the exit in the given direction.

   387

 *

   388

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

   389

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

   390

 * as a TRACK_X cannot be applied with DIAG_SE.

   391

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

   392

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

   393

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

   394

 *

   395

 * @param track The track to applie an direction on

   396

 * @param diagdir The DiagDirection to applie on

   397

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

   398

 */

   399

static inline Trackdir TrackExitdirToTrackdir(Track track, DiagDirection diagdir)

   400

{

   401

	extern const Trackdir _track_exitdir_to_trackdir[TRACK_END][DIAGDIR_END];

   402

	return _track_exitdir_to_trackdir[track][diagdir];

   403

}

   404

   405

/**

   406

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

   407

 * with the entry in the given direction.

   408

 *

   409

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

   410

 * track direction or INVALID_TRACKDIR.

   411

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

   412

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

   413

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

   414

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

   415

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

   416

 * INVALID_TRACKDIR.

   417

 *

   418

 * @param track The target track

   419

 * @param diagdir The direction to "come from"

   420

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

   421

 */

   422

static inline Trackdir TrackEnterdirToTrackdir(Track track, DiagDirection diagdir)

   423

{

   424

	extern const Trackdir _track_enterdir_to_trackdir[TRACK_END][DIAGDIR_END];

   425

	return _track_enterdir_to_trackdir[track][diagdir];

   426

}

   427

   428

/**

   429

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

   430

 * the track running in the given direction.

   431

 */

   432

static inline Trackdir TrackDirectionToTrackdir(Track track, Direction dir)

   433

{

   434

	extern const Trackdir _track_direction_to_trackdir[TRACK_END][DIR_END];

   435

	return _track_direction_to_trackdir[track][dir];

   436

}

   437

   438

/**

   439

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

   440

 * direction.

   441

 *

   442

 * @param diagdir The direction

   443

 * @return The resulting Trackdir direction

   444

 */

   445

static inline Trackdir DiagdirToDiagTrackdir(DiagDirection diagdir)

   446

{

   447

	extern const Trackdir _dir_to_diag_trackdir[DIAGDIR_END];

   448

	return _dir_to_diag_trackdir[diagdir];

   449

}

   450

   451

/**

   452

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

   453

 * (diagonal) direction.

   454

 *

   455

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

   456

 * about the exact angle of entering

   457

 *

   458

 * @param diagdir The joining direction

   459

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

   460

 * @see DiagdirReachesTracks

   461

 */

   462

static inline TrackdirBits DiagdirReachesTrackdirs(DiagDirection diagdir)

   463

{

   464

	extern const TrackdirBits _exitdir_reaches_trackdirs[DIAGDIR_END];

   465

	return _exitdir_reaches_trackdirs[diagdir];

   466

}

   467

   468

/**

   469

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

   470

 * (diagonal) direction.

   471

 *

   472

 * This will obviously include 90 degree turns, since no

   473

 * information is available about the exact angle of entering

   474

 *

   475

 * @param diagdir The joining irection

   476

 * @return The tracks which can be used

   477

 * @see DiagdirReachesTrackdirs

   478

 */

   479

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

   480

   481

/**

   482

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

   483

 * entering the next tile.

   484

 *

   485

 * This will include 90 degree turns!

   486

 *

   487

 * @param trackdir The track direction which will be leaved

   488

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

   489

 */

   490

static inline TrackdirBits TrackdirReachesTrackdirs(Trackdir trackdir)

   491