1

/* $Id$ */

     2

     3

/** @file macros.h */

     4

     5

#ifndef MACROS_H

     6

#define MACROS_H

     7

     8

/**

     9

 * Fetch n bits from x, started at bit s.

    10

 *

    11

 * This function can be used to fetch n bits from the value x. The

    12

 * s value set the startposition to read. The startposition is

    13

 * count from the LSB and starts at 0. The result starts at a

    14

 * LSB, as this isn't just an and-bitmask but also some

    15

 * bit-shifting operations. GB(0xFF, 2, 1) will so

    16

 * return 0x01 (0000 0001) instead of

    17

 * 0x04 (0000 0100).

    18

 *

    19

 * @param x The value to read some bits.

    20

 * @param s The startposition to read some bits.

    21

 * @param n The number of bits to read.

    22

 * @return The selected bits, aligned to a LSB.

    23

 */

    24

template<typename T> static inline uint GB(const T x, const uint8 s, const uint8 n)

    25

{

    26

	return (x >> s) & ((1U << n) - 1);

    27

}

    28

    29

/** Set n bits from x starting at bit s to d

    30

 *

    31

 * This function sets n bits from x which started as bit s to the value of

    32

 * d. The parameters x, s and n works the same as the parameters of

    33

 * #GB. The result is saved in x again. Unused bits in the window

    34

 * provided by n are set to 0 if the value of b isn't "big" enough.

    35

 * This is not a bug, its a feature.

    36

 *

    37

 * @note Parameter x must be a variable as the result is saved there.

    38

 * @note To avoid unexpecting results the value of b should not use more

    39

 *       space as the provided space of n bits (log2)

    40

 * @param x The variable to change some bits

    41

 * @param s The startposition for the new bits

    42

 * @param n The size/window for the new bits

    43

 * @param d The actually new bits to save in the defined position.

    44

 * @return The new value of x

    45

 */

    46

template<typename T, typename U> static inline T SB(T& x, const uint8 s, const uint8 n, const U d)

    47

{

    48

	x &= (T)(~(((1U << n) - 1) << s));

    49

	x |= (T)(d << s);

    50

	return x;

    51

}

    52

    53

/** Add i to n bits of x starting at bit s.

    54

 *

    55

 * This add the value of i on n bits of x starting at bit s. The parameters x,

    56

 * s, i are similar to #GB besides x must be a variable as the result are

    57

 * saved there. An overflow does not affect the following bits of the given

    58

 * bit window and is simply ignored.

    59

 *

    60

 * @note Parameter x must be a variable as the result is saved there.

    61

 * @param x The variable to add some bits at some position

    62

 * @param s The startposition of the addition

    63

 * @param n The size/window for the addition

    64

 * @param i The value to add at the given startposition in the given window.

    65

 * @return The new value of x

    66

 */

    67

template<typename T, typename U> static inline T AB(T& x, const uint8 s, const uint8 n, const U i)

    68

{

    69

	const T mask = (T)(((1U << n) - 1) << s);

    70

	x = (T)((x & ~mask) | ((x + (i << s)) & mask));

    71

	return x;

    72

}

    73

    74

#ifdef min

    75

#undef min

    76

#endif

    77

    78

#ifdef max

    79

#undef max

    80

#endif

    81

    82

#ifdef abs

    83

#undef abs

    84

#endif

    85

    86

/**

    87

 * Returns the maximum of two values.

    88

 *

    89

 * This function returns the greater value of two given values.

    90

 * If they are equal the value of a is returned.

    91

 *

    92

 * @param a The first value

    93

 * @param b The second value

    94

 * @return The greater value or a if equals

    95

 */

    96

template<typename T> static inline T max(const T a, const T b)

    97

{

    98

	return a >= b ? a : b;

    99

}

   100

   101

/**

   102

 * Returns the minimum of two values.

   103

 *

   104

 * This function returns the smaller value of two given values.

   105

 * If they are equal the value of b is returned.

   106

 *

   107

 * @param a The first value

   108

 * @param b The second value

   109

 * @return The smaller value or b if equals

   110

 */

   111

template<typename T> static inline T min(const T a, const T b)

   112

{

   113

	return a < b ? a : b;

   114

}

   115

   116

/**

   117

 * Returns the minimum of two integer.

   118

 *

   119

 * This function returns the smaller value of two given integers.

   120

 *

   121

 * @param a The first integer

   122

 * @param b The second integer

   123

 * @return The smaller value

   124

 */

   125

static inline int min(const int a, const int b)

   126

{

   127

	return a < b ? a : b;

   128

}

   129

   130

/**

   131

 * Returns the minimum of two unsigned integers.

   132

 *

   133

 * This function returns the smaller value of two given unsigned integers.

   134

 *

   135

 * @param a The first unsigned integer

   136

 * @param b The second unsigned integer

   137

 * @return The smaller value

   138

 */

   139

static inline uint minu(const uint a, const uint b)

   140

{

   141

	return a < b ? a : b;

   142

}

   143

   144

/**

   145

 * Returns the absolute value of (scalar) variable.

   146

 *

   147

 * @note assumes variable to be signed

   148

 * @param a The value we want to unsign

   149

 * @return The unsigned value

   150

 */

   151

template <typename T> static inline T abs(T a)

   152

{

   153

	return (a < (T)0) ? -a : a;

   154

}

   155

   156

/**

   157

 * Clamp an integer between an interval.

   158

 *

   159

 * This function returns a value which is between the given interval of

   160

 * min and max. If the given value is in this interval the value itself

   161

 * is returned otherwise the border of the interval is returned, according

   162

 * which side of the interval was 'left'.

   163

 *

   164

 * @note The min value must be less or equal of max or you get some

   165

 *       unexpected results.

   166

 * @param a The value to clamp/truncate.

   167

 * @param min The minimum of the interval.

   168

 * @param max the maximum of the interval.

   169

 * @returns A value between min and max which is closest to a.

   170

 * @see ClampU(uint, uint, uint)

   171

 */

   172

static inline int Clamp(const int a, const int min, const int max)

   173

{

   174

	if (a <= min) return min;

   175

	if (a >= max) return max;

   176

	return a;

   177

}

   178

   179

/**

   180

 * Clamp an unsigned integer between an interval.

   181

 *

   182

 * This function returns a value which is between the given interval of

   183

 * min and max. If the given value is in this interval the value itself

   184

 * is returned otherwise the border of the interval is returned, according

   185

 * which side of the interval was 'left'.

   186

 *

   187

 * @note The min value must be less or equal of max or you get some

   188

 *       unexpected results.

   189

 * @param a The value to clamp/truncate.

   190

 * @param min The minimum of the interval.

   191

 * @param max the maximum of the interval.

   192

 * @returns A value between min and max which is closest to a.

   193

 * @see Clamp(int, int, int)

   194

 */

   195

static inline uint ClampU(const uint a, const uint min, const uint max)

   196

{

   197

	if (a <= min) return min;

   198

	if (a >= max) return max;

   199

	return a;

   200

}

   201

   202

/**

   203

 * Reduce a signed 64-bit int to a signed 32-bit one

   204

 *

   205

 * This function clamps a 64-bit integer to a 32-bit integer.

   206

 * If the 64-bit value is smaller than the smallest 32-bit integer

   207

 * value 0x80000000 this value is returned (the left one bit is the sign bit).

   208

 * If the 64-bit value is greater than the greatest 32-bit integer value 0x7FFFFFFF

   209

 * this value is returned. In all other cases the 64-bit value 'fits' in a

   210

 * 32-bits integer field and so the value is casted to int32 and returned.

   211

 *

   212

 * @param a The 64-bit value to clamps

   213

 * @return The 64-bit value reduced to a 32-bit value

   214

 * @see Clamp(int, int, int)

   215

 */

   216

static inline int32 ClampToI32(const int64 a)

   217

{

   218

	if (a <= (int32)0x80000000) return 0x80000000;

   219

	if (a >= (int32)0x7FFFFFFF) return 0x7FFFFFFF;

   220

	return (int32)a;

   221

}

   222

   223

/**

   224

 * Checks if a bit in a value is set.

   225

 *

   226

 * This function checks if a bit inside a value is set or not.

   227

 * The y value specific the position of the bit, started at the

   228

 * LSB and count from 0.

   229

 *

   230

 * @param x The value to check

   231

 * @param y The position of the bit to check, started from the LSB

   232

 * @return True if the bit is set, false else.

   233

 */

   234

template<typename T> static inline bool HASBIT(const T x, const uint8 y)

   235

{

   236

	return (x & ((T)1U << y)) != 0;

   237

}

   238

   239

/**

   240

 * Set a bit in a variable.

   241

 *

   242

 * This function sets a bit in a variable. The variable is changed

   243

 * and the value is also returned. Parameter y defines the bit and

   244

 * starts at the LSB with 0.

   245

 *

   246

 * @param x The variable to set a bit

   247

 * @param y The bit position to set

   248

 * @return The new value of the old value with the bit set

   249

 */

   250

template<typename T> static inline T SETBIT(T& x, const uint8 y)

   251

{

   252

	return x |= (T)1U << y;

   253

}

   254

   255

/**

   256

 * Clears a bit in a variable.

   257

 *

   258

 * This function clears a bit in a variable. The variable is

   259

 * changed and the value is also returned. Parameter y defines the bit

   260

 * to clear and starts at the LSB with 0.

   261

 *

   262

 * @param x The variable to clear the bit

   263

 * @param y The bit position to clear

   264

 * @return The new value of the old value with the bit cleared

   265

 */

   266

template<typename T> static inline T CLRBIT(T& x, const uint8 y)

   267

{

   268

	return x &= ~((T)1U << y);

   269

}

   270

   271

/**

   272

 * Toggles a bit in a variable.

   273

 *

   274

 * This function toggles a bit in a variable. The variable is

   275

 * changed and the value is also returned. Parameter y defines the bit

   276

 * to toggle and starts at the LSB with 0.

   277

 *

   278

 * @param x The varliable to toggle the bit

   279

 * @param y The bit position to toggle

   280

 * @return The new value of the old value with the bit toggled

   281

 */

   282

template<typename T> static inline T TOGGLEBIT(T& x, const uint8 y)

   283

{

   284

	return x ^= (T)1U << y;

   285

}

   286

   287

   288

/* checking more bits. Maybe unneccessary, but easy to use */

   289

/**

   290

 * Check several bits in a value.

   291

 *

   292

 * This macro checks if a value contains at least one bit of an other

   293

 * value.

   294

 *

   295

 * @param x The first value

   296

 * @param y The second value

   297

 * @return True if at least one bit is set in both values, false else.

   298

 */

   299

#define HASBITS(x, y) ((x) & (y))

   300

   301

/**

   302

 * Sets several bits in a variable.

   303

 *

   304

 * This macro sets several bits in a variable. The bits to set are provided

   305

 * by a value. The new value is also returned.

   306

 *

   307

 * @param x The variable to set some bits

   308

 * @param y The value with set bits for setting them in the variable

   309

 * @return The new value of x

   310

 */

   311

#define SETBITS(x, y) ((x) |= (y))

   312

   313

/**

   314

 * Clears several bits in a variable.

   315

 *

   316

 * This macro clears several bits in a variable. The bits to clear are

   317

 * provided by a value. The new value is also returned.

   318

 *

   319

 * @param x The variable to clear some bits

   320

 * @param y The value with set bits for clearing them in the variable

   321

 * @return The new value of x

   322

 */

   323

#define CLRBITS(x, y) ((x) &= ~(y))

   324

   325

#define GENERAL_SPRITE_COLOR(color) ((color) + PALETTE_RECOLOR_START)

   326

#define PLAYER_SPRITE_COLOR(owner) (GENERAL_SPRITE_COLOR(_player_colors[owner]))

   327

   328

/**

   329

 * Whether a sprite comes from the original graphics files or a new grf file

   330

 * (either supplied by OpenTTD or supplied by the user).

   331

 *

   332

 * @param sprite The sprite to check

   333

 * @return True if it is a new sprite, or false if it is original.

   334

 */

   335

#define IS_CUSTOM_SPRITE(sprite) ((sprite) >= SPR_SIGNALS_BASE)

   336

   337

extern const byte _ffb_64[64];

   338

   339

/**

   340

 * Returns the first occure of a bit in a 6-bit value (from right).

   341

 *

   342

 * Returns the position of the first bit that is not zero, counted from the

   343

 * LSB. Ie, 110100 returns 2, 000001 returns 0, etc. When x == 0 returns

   344

 * 0.

   345

 *

   346

 * @param x The 6-bit value to check the first zero-bit

   347

 * @return The first position of a bit started from the LSB or 0 if x is 0.

   348

 */

   349

#define FIND_FIRST_BIT(x) _ffb_64[(x)]

   350

   351

/**

   352

 * Finds the position of the first bit in an integer.

   353

 *

   354

 * This function returns the position of the first bit set in the

   355

 * integer. It does only check the bits of the bitmask

   356

 * 0x3F3F (0011111100111111) and checks only the

   357

 * bits of the bitmask 0x3F00 if and only if the

   358

 * lower part 0x00FF is 0. This results the bits at 0x00C0 must

   359

 * be also zero to check the bits at 0x3F00.

   360

 *

   361

 * @param value The value to check the first bits

   362

 * @return The position of the first bit which is set

   363

 * @see FIND_FIRST_BIT

   364

 */

   365

static inline int FindFirstBit2x64(int value)

   366

{

   367

	if ((value & 0xFF) == 0) {

   368

		return FIND_FIRST_BIT((value >> 8) & 0x3F) + 8;

   369

	} else {

   370

		return FIND_FIRST_BIT(value & 0x3F);

   371

	}

   372

}

   373

   374

/**

   375

 * Clear the first bit in an integer.

   376

 *

   377

 * This function returns a value where the first bit (from LSB)

   378

 * is cleared.

   379

 * So, 110100 returns 110000, 000001 returns 000000, etc.

   380

 *

   381

 * @param value The value to clear the first bit

   382

 * @return The new value with the first bit cleared

   383

 */

   384

template<typename T> static inline T KillFirstBit(T value)

   385

{

   386

	return value &= (T)(value - 1);

   387

}

   388

   389

/**

   390

 * Counts the number of set bits in a variable.

   391

 *

   392

 * @param value the value to count the number of bits in.

   393

 * @return the number of bits.

   394

 */

   395

template<typename T> static inline uint CountBits(T value)

   396

{

   397

	uint num;

   398

   399

	/* This loop is only called once for every bit set by clearing the lowest

   400

	 * bit in each loop. The number of bits is therefore equal to the number of

   401

	 * times the loop was called. It was found at the following website:

   402

	 * http://graphics.stanford.edu/~seander/bithacks.html */

   403

   404

	for (num = 0; value != 0; num++) {

   405

		value &= (T)(value - 1);

   406

	}

   407

   408

	return num;

   409

}

   410

   411

/**

   412

 * Checks if a value is between a window started at some base point.

   413

 *

   414

 * This function checks if the value x is between the value of base

   415

 * and base+size. If x equals base this returns true. If x equals

   416

 * base+size this returns false.

   417

 *

   418

 * @param x The value to check

   419

 * @param base The base value of the interval

   420

 * @param size The size of the interval

   421

 * @return True if the value is in the interval, false else.

   422

 */

   423

template<typename T> static inline bool IS_INSIDE_1D(const T x, const int base, const uint size)

   424

{

   425

	return (uint)(x - base) < size;

   426

}

   427

   428

/**

   429

 * Checks if a byte is in an interval.

   430

 *

   431

 * This macro returns true if a byte value is in the interval of [min, max).

   432

 *

   433

 * @param a The byte value to check

   434

 * @param min The minimum of the interval

   435

 * @param max The maximum of the interval

   436

 * @see IS_INSIDE_1D

   437

 */

   438

#define IS_BYTE_INSIDE(a, min, max) ((byte)((a) - (min)) < (byte)((max) - (min)))

   439

   440

/**

   441

 * Checks if an int is in an interval.

   442

 *

   443

 * This macro returns true if a integer value is in the interval of [min, max).

   444

 *

   445

 * @param a The integer value to check

   446

 * @param min The minimum of the interval

   447

 * @param max The maximum of the interval

   448

 * @see IS_INSIDE_1D

   449

 */

   450

#define IS_INT_INSIDE(a, min, max) ((uint)((a) - (min)) < (uint)((max) - (min)))

   451

   452

/**

   453

 * Flips a coin with a given probability.

   454

 *

   455

 * This macro can be used to get true or false randomized according to a

   456

 * given probability. The parameter a and b create a percent value with

   457

 * (a/b). The macro returns true in (a/b) percent.

   458

 *

   459

 * @param a The numerator of the fraction

   460

 * @param b The denominator of the fraction, must of course not be null

   461

 * @return True in (a/b) percent

   462

 */

   463

#define CHANCE16(a, b) CHANCE16I(a, b, Random())

   464

   465

/**

   466

 * Flips a coin with a given probability and saves the randomize-number in a variable.

   467

 *

   468

 * This macro uses the same parameters as the CHANCE16 marco. The third parameter

   469

 * must be a variable the randomize-number from Random() is saved in.

   470

 *

   471

 * The low 16 bits of r will already be used and can therefor not be passed to

   472

 * CHANCE16I. One can only send the high 16 bits to CHANCE16I.

   473

 *

   474

 * @param a The numerator of the fraction, see CHANCE16

   475

 * @param b The denominator of the fraction, see CHANCE16

   476

 * @param r The variable to save the randomize-number from Random()

   477

 * @return True in (a/b) percent

   478

 */

   479

#define CHANCE16R(a, b, r) CHANCE16I(a, b, r = Random())

   480

   481

/**

   482

 * Checks if a given randomize-number is below a given probability.

   483

 *

   484

 * This macro is used to check if the given probability by the fraction of (a/b)

   485

 * is greater than low 16 bits of the given randomize-number v.

   486

 *

   487

 * Do not use this function twice on the same random 16 bits as it will yield

   488

 * the same result. One can use a random number for two calls to CHANCE16I,

   489

 * where one call sends the low 16 bits and the other the high 16 bits.

   490

 *