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 macro 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

#define GB(x, s, n) (((x) >> (s)) & ((1U << (n)) - 1))

    25

    26

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

    27

 *

    28

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

    29

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

    30

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

    31

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

    32

 * This is not a bug, its a feature.

    33

 *

    34

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

    35

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

    36

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

    37

 * @param x The variable to change some bits

    38

 * @param s The startposition for the new bits

    39

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

    40

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

    41

 * @return The new value of x

    42

 */

    43

#define SB(x, s, n, d) ((x) = ((x) & ~(((1U << (n)) - 1) << (s))) | ((d) << (s)))

    44

    45

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

    46

 *

    47

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

    48

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

    49

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

    50

 * bit window and is simply ignored.

    51

 *

    52

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

    53

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

    54

 * @param s The startposition of the addition

    55

 * @param n The size/window for the addition

    56

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

    57

 * @return The new value of x

    58

 */

    59

#define AB(x, s, n, i) ((x) = ((x) & ~(((1U << (n)) - 1) << (s))) | (((x) + ((i) << (s))) & (((1U << (n)) - 1) << (s))))

    60

    61

#ifdef min

    62

#undef min

    63

#endif

    64

    65

#ifdef max

    66

#undef max

    67

#endif

    68

    69

/**

    70

 * Returns the maximum of two values.

    71

 *

    72

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

    73

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

    74

 *

    75

 * @param a The first value

    76

 * @param b The second value

    77

 * @return The greater value or a if equals

    78

 */

    79

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

    80

{

    81

	return a >= b ? a : b;

    82

}

    83

    84

/**

    85

 * Returns the minimum of two values.

    86

 *

    87

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

    88

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

    89

 *

    90

 * @param a The first value

    91

 * @param b The second value

    92

 * @return The smaller value or b if equals

    93

 */

    94

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

    95

{

    96

	return a < b ? a : b;

    97

}

    98

    99

/**

   100

 * Returns the minimum of two integer.

   101

 *

   102

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

   103

 *

   104

 * @param a The first integer

   105

 * @param b The second integer

   106

 * @return The smaller value

   107

 */

   108

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

   109

{

   110

	return a <= b ? a : b;

   111

}

   112

   113

/**

   114

 * Returns the minimum of two unsigned integers.

   115

 *

   116

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

   117

 *

   118

 * @param a The first unsigned integer

   119

 * @param b The second unsigned integer

   120

 * @return The smaller value

   121

 */

   122

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

   123

{

   124

	return a <= b ? a : b;

   125

}

   126

   127

/**

   128

 * Clamp an integer between an interval.

   129

 *

   130

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

   131

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

   132

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

   133

 * which side of the interval was 'left'.

   134

 *

   135

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

   136

 *       unexpected results.

   137

 * @param a The value to clamp/truncate.

   138

 * @param min The minimum of the interval.

   139

 * @param max the maximum of the interval.

   140

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

   141

 * @see clampu(uint, uint, uint)

   142

 */

   143

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

   144

{

   145

	if (a <= min) return min;

   146

	if (a >= max) return max;

   147

	return a;

   148

}

   149

   150

/**

   151

 * Clamp an unsigned integer between an interval.

   152

 *

   153

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

   154

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

   155

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

   156

 * which side of the interval was 'left'.

   157

 *

   158

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

   159

 *       unexpected results.

   160

 * @param a The value to clamp/truncate.

   161

 * @param min The minimum of the interval.

   162

 * @param max the maximum of the interval.

   163

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

   164

 * @see clamp(int, int, int)

   165

 */

   166

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

   167

{

   168

	if (a <= min) return min;

   169

	if (a >= max) return max;

   170

	return a;

   171

}

   172

   173

/**

   174

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

   175

 *

   176

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

   177

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

   178

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

   179

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

   180

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

   181

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

   182

 *

   183

 * @param a The 64-bit value to clamps

   184

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

   185

 * @see clamp(int, int, int)

   186

 */

   187

static inline int32 ClampToI32(const int64 a)

   188

{

   189

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

   190

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

   191

	return (int32)a;

   192

}

   193

   194

/**

   195

 * Multiply two integer values and shift the results to right.

   196

 *

   197

 * This function multiplies two integer values. The result is

   198

 * shifted by the amount of shift to right.

   199

 *

   200

 * @param a The first integer

   201

 * @param b The second integer

   202

 * @param shift The amount to shift the value to right.

   203

 * @return The shifted result

   204

 */

   205

static inline int32 BIGMULSS(const int32 a, const int32 b, const uint8 shift)

   206

{

   207

	return (int32)((int64)a * (int64)b >> shift);

   208

}

   209

   210

/**

   211

 * Multiply two unsigned integers and shift the results to right.

   212

 *

   213

 * This function multiplies two unsigned integers. The result is

   214

 * shifted by the amount of shift to right.

   215

 *

   216

 * @param a The first unsigned integer

   217

 * @param b The second unsigned integer

   218

 * @param shift The amount to shift the value to right.

   219

 * @return The shifted result

   220

 */

   221

static inline uint32 BIGMULUS(const uint32 a, const uint32 b, const uint8 shift)

   222

{

   223

	return (uint32)((uint64)a * (uint64)b >> shift);

   224

}

   225

   226

   227

/**

   228

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

   229

 *

   230

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

   231

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

   232

 * base+size this returns false.

   233

 *

   234

 * @param x The value to check

   235

 * @param base The base value of the interval

   236

 * @param size The size of the interval

   237

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

   238

 */

   239

/* OPT: optimized into an unsigned comparison */

   240

//#define IS_INSIDE_1D(x, base, size) ((x) >= (base) && (x) < (base) + (size))

   241

#define IS_INSIDE_1D(x, base, size) ( (uint)((x) - (base)) < ((uint)(size)) )

   242

   243

/**

   244

 * Checks if a bit in a value is set.

   245

 *

   246

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

   247

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

   248

 * LSB and count from 0.

   249

 *

   250

 * @param x The value to check

   251

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

   252

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

   253

 */

   254

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

   255

{

   256

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

   257

}

   258

   259

/**

   260

 * Set a bit in a variable.

   261

 *

   262

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

   263

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

   264

 * starts at the LSB with 0.

   265

 *

   266

 * @param x The variable to set a bit

   267

 * @param y The bit position to set

   268

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

   269

 */

   270

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

   271

{

   272

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

   273

}

   274

   275

/**

   276

 * Clears a bit in a variable.

   277

 *

   278

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

   279

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

   280

 * to clear and starts at the LSB with 0.

   281

 *

   282

 * @param x The variable to clear the bit

   283

 * @param y The bit position to clear

   284

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

   285

 */

   286

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

   287

{

   288

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

   289

}

   290

   291

/**

   292

 * Toggles a bit in a variable.

   293

 *

   294

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

   295

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

   296

 * to toggle and starts at the LSB with 0.

   297

 *

   298

 * @param x The varliable to toggle the bit

   299

 * @param y The bit position to toggle

   300

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

   301

 */

   302

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

   303

{

   304

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

   305

}

   306

   307

   308

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

   309

/**

   310

 * Check several bits in a value.

   311

 *

   312

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

   313

 * value.

   314

 *

   315

 * @param x The first value

   316

 * @param y The second value

   317

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

   318

 */

   319

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

   320

   321

/**

   322

 * Sets several bits in a variable.

   323

 *

   324

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

   325

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

   326

 *

   327

 * @param x The variable to set some bits

   328

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

   329

 * @return The new value of x

   330

 */

   331

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

   332

   333

/**

   334

 * Clears several bits in a variable.

   335

 *

   336

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

   337

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

   338

 *

   339

 * @param x The variable to clear some bits

   340

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

   341

 * @return The new value of x

   342

 */

   343

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

   344

   345

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

   346

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

   347

   348

/**

   349

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

   350

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

   351

 *

   352

 * @param sprite The sprite to check

   353

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

   354

 */

   355

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

   356

   357

extern const byte _ffb_64[128];

   358

   359

/**

   360

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

   361

 *

   362

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

   363

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

   364

 * 0.

   365

 *

   366

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

   367

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

   368

 */

   369

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

   370

   371

/**

   372

 * Returns a value with the first occured of a bit set to zero.

   373

 *

   374

 * Returns x with the first bit from LSB that is not zero set

   375

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

   376

 *

   377

 * @param x The value to returned a new value

   378

 * @return The value which the first bit is set to zero

   379

 */

   380

#define KILL_FIRST_BIT(x) _ffb_64[(x) + 64]

   381

   382

/**

   383

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

   384

 *

   385

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

   386

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

   387

 * 0x3F3F (0011111100111111) and checks only the

   388

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

   389

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

   390

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

   391

 *

   392

 * @param value The value to check the first bits

   393

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

   394

 * @see FIND_FIRST_BIT

   395

 */

   396

static inline int FindFirstBit2x64(int value)

   397

{

   398

/*

   399

	int i = 0;

   400

	if ( (byte) value == 0) {

   401

		i += 8;

   402

		value >>= 8;

   403

	}

   404

	return i + FIND_FIRST_BIT(value & 0x3F);

   405

   406

Faster ( or at least cleaner ) implementation below?

   407

*/

   408

	if (GB(value, 0, 8) == 0) {

   409

		return FIND_FIRST_BIT(GB(value, 8, 6)) + 8;

   410

	} else {

   411

		return FIND_FIRST_BIT(GB(value, 0, 6));

   412

	}

   413

}

   414

   415

/**

   416

 * Clear the first bit in an integer.

   417

 *

   418

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

   419

 * is cleared. This function checks only the bits of 0x3F3F!

   420

 *

   421

 * @param value The value to clear the first bit

   422

 * @return The new value with the first bit cleared

   423

 */

   424

static inline uint KillFirstBit2x64(uint value)

   425

{

   426

	return value &= (uint)(value - 1) | 0x3FFFC0C0;

   427

}

   428

   429

/**

   430

 * Counts the number of set bits in a variable.

   431

 *

   432

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

   433

 * @return the number of bits.

   434

 */

   436

{

   437

	register uint num;

   438

   439

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

   440

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

   441

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

   442

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

   443

   444

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

   445

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

   446

	}

   447

   448

	return num;

   449

}

   450

   451

/**

   452

 * Checks if a byte is in an interval.

   453

 *

   454

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

   455

 *

   456

 * @param a The byte value to check

   457

 * @param min The minimum of the interval

   458

 * @param max The maximum of the interval

   459

 * @see IS_INSIDE_1D

   460

 */

   461

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

   462

   463

/**

   464

 * Checks if an int is in an interval.

   465

 *

   466

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

   467

 *

   468

 * @param a The integer value to check

   469

 * @param min The minimum of the interval

   470

 * @param max The maximum of the interval

   471

 * @see IS_INSIDE_1D

   472

 */

   473

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

   474

   475

/**

   476

 * Flips a coin with a given probability.

   477

 *

   478

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

   479

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

   480

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

   481

 *

   482

 * @param a The numerator of the fraction

   483

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

   484

 * @return True in (a/b) percent

   485

 */

   486

#define CHANCE16(a, b) ((uint16)Random() <= (uint16)((65536 * (a)) / (b)))

   487

   488

/**

   489

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

   490

 *

   491

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