# player_face.h File Reference

Functionality related to the player's face. More...

`#include "core/random_func.hpp"`
`#include "core/bitmath_func.hpp"`

Go to the source code of this file.

## Data Structures
struct | PlayerFaceBitsInfo
| Information about the valid values of PlayerFace bitgroups as well as the sprites to draw. More...
## Enumerations
enum | GenderEthnicity { GENDER_FEMALE = 0, ETHNICITY_BLACK = 1, GE_WM = 0, GE_WF = 1 << GENDER_FEMALE, GE_BM = 1 << ETHNICITY_BLACK, GE_BF = 1 << ETHNICITY_BLACK | 1 << GENDER_FEMALE, GE_END }
| The gender/race combinations that we have faces for. More...
enum | PlayerFaceVariable { PFV_GENDER, PFV_ETHNICITY, PFV_GEN_ETHN, PFV_HAS_MOUSTACHE, PFV_HAS_TIE_EARRING, PFV_HAS_GLASSES, PFV_EYE_COLOUR, PFV_CHEEKS, PFV_CHIN, PFV_EYEBROWS, PFV_MOUSTACHE, PFV_LIPS, PFV_NOSE, PFV_HAIR, PFV_JACKET, PFV_COLLAR, PFV_TIE_EARRING, PFV_GLASSES, PFV_END }
| Bitgroups of the PlayerFace variable.
## Functions
| DECLARE_ENUM_AS_BIT_SET (GenderEthnicity)
| See GenderRace as a bitset.
| DECLARE_POSTFIX_INCREMENT (PlayerFaceVariable)
| assert_compile (lengthof(_pf_info)==PFV_END)
static uint | GetPlayerFaceBits (PlayerFace pf, PlayerFaceVariable pfv, GenderEthnicity ge)
| Gets the player's face bits for the given player face variable.
static void | SetPlayerFaceBits (PlayerFace &pf, PlayerFaceVariable pfv, GenderEthnicity ge, uint val)
| Sets the player's face bits for the given player face variable.
static void | IncreasePlayerFaceBits (PlayerFace &pf, PlayerFaceVariable pfv, GenderEthnicity ge, int8 amount)
| Increase/Decrease the player face variable by the given amount.
static bool | ArePlayerFaceBitsValid (PlayerFace pf, PlayerFaceVariable pfv, GenderEthnicity ge)
| Checks whether the player bits have a valid range.
static uint | ScalePlayerFaceValue (PlayerFaceVariable pfv, GenderEthnicity ge, uint val)
| Scales a player face bits variable to the correct scope.
static void | ScaleAllPlayerFaceBits (PlayerFace &pf)
| Scales all player face bits to the correct scope.
static void | RandomPlayerFaceBits (PlayerFace &pf, GenderEthnicity ge, bool adv)
| Make a random new face.
static SpriteID | GetPlayerFaceSprite (PlayerFace pf, PlayerFaceVariable pfv, GenderEthnicity ge)
| Gets the sprite to draw for the given player face variable.
void | DrawPlayerFace (PlayerFace face, int color, int x, int y)
| Draws the face of a player.
PlayerFace | ConvertFromOldPlayerFace (uint32 face)
| Converts an old player face format to the new player face format.
bool | IsValidPlayerFace (PlayerFace pf)
| Checks whether a player's face is a valid encoding.
void | DrawFaceStringLabel (const Window *w, byte widget_index, StringID str, uint8 val, bool is_bool_widget)
| Draw dynamic a label to the left of the button and a value in the button.
## Variables
static const PlayerFaceBitsInfo | _pf_info []
| Lookup table for indices into the PlayerFace, valid ranges and sprites.

## Detailed Description

Functionality related to the player's face.

Definition in file player_face.h.

## Enumeration Type Documentation

enum GenderEthnicity

The gender/race combinations that we have faces for.

Enumerator:

  GENDER_FEMALE | This bit set means a female, otherwise male.
  ETHNICITY_BLACK | This bit set means black, otherwise white.
  GE_WM | A male of Caucasian origin (white).
  GE_WF | A female of Caucasian origin (white).
  GE_BM | A male of African origin (black).
  GE_BF | A female of African origin (black).

Definition at line 12 of file player_face.h.

## Function Documentation

static bool ArePlayerFaceBitsValid | ( | PlayerFace | pf,
|  | PlayerFaceVariable | pfv,
|  | GenderEthnicity | ge |
| ) |  |  | `[inline, static]`

Checks whether the player bits have a valid range.

Parameters:

  | pf | the face to extract the bits from
  | pfv | the face variable to get the data of
  | ge | the gender and ethnicity of the face

Returns:
  true if and only if the bits are valid

Definition at line 143 of file player_face.h.

References GB(), and PlayerFaceBitsInfo::valid_values.

Referenced by IsValidPlayerFace().

PlayerFace ConvertFromOldPlayerFace | ( | uint32 | face | ) |

Converts an old player face format to the new player face format.

Meaning of the bits in the old face (some bits are used in several times):

- 4 and 5: chin
- 6 to 9: eyebrows
- 10 to 13: nose
- 13 to 15: lips (also moustache for males)
- 16 to 19: hair
- 20 to 22: eye color
- 20 to 27: tie, ear rings etc.
- 28 to 30: glasses
- 19, 26 and 27: race (bit 27 set and bit 19 equal to bit 26 = black, otherwise white)
- 31: gender (0 = male, 1 = female)

Parameters:

  | face | the face in the old format

Returns:
  the face in the new format

Definition at line 109 of file players.cpp.

References ClampU(), ETHNICITY_BLACK, GB(), GE_WF, GE_WM, GENDER_FEMALE, HasBit(), max(), ScalePlayerFaceValue(), SetBit(), and SetPlayerFaceBits().

void DrawFaceStringLabel | ( | const Window * | w,
|  | byte | widget_index,
|  | StringID | str,
|  | uint8 | val,
|  | bool | is_bool_widget |
| ) |  |  |

Draw dynamic a label to the left of the button and a value in the button.

Parameters:

  | w | Window on which the widget is located
  | widget_index | index of this widget in the window
  | str | the label which will be draw
  | val | the value which will be draw
  | is_bool_widget | is it a bool button

Definition at line 681 of file player_gui.cpp.

Referenced by SelectPlayerFaceWndProc().

void DrawPlayerFace | ( | PlayerFace | pf,
|  | int | color,
|  | int | x,
|  | int | y |
| ) |  |  |

Draws the face of a player.

Parameters:

  | pf | the player's face
  | color | the (background) color of the gradient
  | x | x-position to draw the face
  | y | y-position to draw the face

Definition at line 512 of file player_gui.cpp.

References _pf_info, GE_WM, GENDER_FEMALE, GetPlayerFaceBits(), GetPlayerFaceSprite(), and HasBit().

Referenced by PlayerCompanyWndProc(), and SelectPlayerFaceWndProc().

static uint GetPlayerFaceBits | ( | PlayerFace | pf,
|  | PlayerFaceVariable | pfv,
|  | GenderEthnicity | ge |
| ) |  |  | `[inline, static]`

Gets the player's face bits for the given player face variable.

Parameters:

  | pf | the face to extract the bits from
  | pfv | the face variable to get the data of
  | ge | the gender and ethnicity of the face

Precondition:
  _pf_info[pfv].valid_values[ge] != 0

Returns:
  the requested bits

Definition at line 88 of file player_face.h.

References GB().

Referenced by DrawPlayerFace(), IncreasePlayerFaceBits(), IsValidPlayerFace(), ScaleAllPlayerFaceBits(), and SelectPlayerFaceWndProc().

static SpriteID GetPlayerFaceSprite | ( | PlayerFace | pf,
|  | PlayerFaceVariable | pfv,
|  | GenderEthnicity | ge |
| ) |  |  | `[inline, static]`

Gets the sprite to draw for the given player face variable.

Parameters:

  | pf | the face to extract the data from
  | pfv | the face variable to get the sprite of
  | ge | the gender and ethnicity of the face

Precondition:
  _pf_info[pfv].valid_values[ge] != 0

Returns:
  sprite to draw

Definition at line 223 of file player_face.h.

References PlayerFaceBitsInfo::first_sprite, and GB().

Referenced by DrawPlayerFace().

static void IncreasePlayerFaceBits | ( | PlayerFace & | pf,
|  | PlayerFaceVariable | pfv,
|  | GenderEthnicity | ge,
|  | int8 | amount |
| ) |  |  | `[inline, static]`

Increase/Decrease the player face variable by the given amount.

If the new value greater than the max value for this variable it will be set to 0. Or is it negativ (< 0) it will be set to max value.

Parameters:

  | pf | the player face to write the bits to
  | pfv | the player face variable to write the data of
  | ge | the gender and ethnicity of the player face
  | amount | the amount which change the value

Precondition:
  0 <= val < _pf_info[pfv].valid_values[ge]

Definition at line 122 of file player_face.h.

References GetPlayerFaceBits(), SetPlayerFaceBits(), and PlayerFaceBitsInfo::valid_values.

Referenced by ScaleAllPlayerFaceBits(), and SelectPlayerFaceWndProc().

bool IsValidPlayerFace | ( | PlayerFace | pf | ) |

Checks whether a player's face is a valid encoding.

Unused bits are not enforced to be 0.

Parameters:

  | pf | the fact to check

Returns:
  true if and only if the face is valid

Definition at line 165 of file players.cpp.

References ArePlayerFaceBitsValid(), GE_WM, GENDER_FEMALE, GetPlayerFaceBits(), and HasBit().

Referenced by CmdSetPlayerFace().

static void RandomPlayerFaceBits | ( | PlayerFace & | pf,
|  | GenderEthnicity | ge,
|  | bool | adv |
| ) |  |  | `[inline, static]`

Make a random new face.

If it is for the advanced player face window then the new face have the same gender and ethnicity as the old one, else the gender is equal and the ethnicity is random.

Parameters:

  | pf | the player face to write the bits to
  | ge | the gender and ethnicity of the old player face
  | adv | if it for the advanced player face window

Precondition:
  scale 'ge' to a valid gender/ethnicity combination

Definition at line 197 of file player_face.h.

References GENDER_FEMALE, HasBit(), ScaleAllPlayerFaceBits(), and SetPlayerFaceBits().

Referenced by DoStartupNewPlayer(), and SelectPlayerFaceWndProc().

static void ScaleAllPlayerFaceBits | ( | PlayerFace & | pf | ) | `[inline, static]`

Scales all player face bits to the correct scope.

Parameters:

  | pf | the player face to write the bits to

Definition at line 168 of file player_face.h.

References GB(), GE_WM, GENDER_FEMALE, GetPlayerFaceBits(), HasBit(), and IncreasePlayerFaceBits().

Referenced by RandomPlayerFaceBits(), and SelectPlayerFaceWndProc().

static uint ScalePlayerFaceValue | ( | PlayerFaceVariable | pfv,
|  | GenderEthnicity | ge,
|  | uint | val |
| ) |  |  | `[inline, static]`

Scales a player face bits variable to the correct scope.

Parameters:

  | pfv | the face variable to write the data of
  | ge | the gender and ethnicity of the face
  | val | the to value to scale

Precondition:
  val < (1U << _pf_info[pfv].length), i.e. val has a value of 0..2^(bits used for this variable)-1

Returns:
  the scaled value

Definition at line 156 of file player_face.h.

References PlayerFaceBitsInfo::length.

Referenced by ConvertFromOldPlayerFace().

static void SetPlayerFaceBits | ( | PlayerFace & | pf,
|  | PlayerFaceVariable | pfv,
|  | GenderEthnicity | ge,
|  | uint | val |
| ) |  |  | `[inline, static]`

Sets the player's face bits for the given player face variable.

Parameters:

  | pf | the face to write the bits to
  | pfv | the face variable to write the data of
  | ge | the gender and ethnicity of the face
  | val | the new value

Precondition:
  val < _pf_info[pfv].valid_values[ge]

Definition at line 103 of file player_face.h.

References SB().

Referenced by ConvertFromOldPlayerFace(), IncreasePlayerFaceBits(), RandomPlayerFaceBits(), and SelectPlayerFaceWndProc().

## Variable Documentation

const PlayerFaceBitsInfo _pf_info[]`[static]`

Initial value:

     {

       {  0, 1, {  2,  2,  2,  2 }, {     0,     0,     0,     0 } },
       {  1, 2, {  2,  2,  2,  2 }, {     0,     0,     0,     0 } },
       {  0, 3, {  4,  4,  4,  4 }, {     0,     0,     0,     0 } },
       {  3, 1, {  2,  0,  2,  0 }, {     0,     0,     0,     0 } },
       {  3, 1, {  0,  2,  0,  2 }, {     0,     0,     0,     0 } },
       {  4, 1, {  2,  2,  2,  2 }, {     0,     0,     0,     0 } },
       {  5, 2, {  3,  3,  1,  1 }, {     0,     0,     0,     0 } },
       {  0, 0, {  1,  1,  1,  1 }, { 0x325, 0x326, 0x390, 0x3B0 } },
       {  7, 2, {  4,  1,  2,  2 }, { 0x327, 0x327, 0x391, 0x3B1 } },
       {  9, 4, { 12, 16, 11, 16 }, { 0x32B, 0x337, 0x39A, 0x3B8 } },
       { 13, 2, {  3,  0,  3,  0 }, { 0x367,     0, 0x397,     0 } },
       { 13, 4, { 12, 10,  9,  9 }, { 0x35B, 0x351, 0x3A5, 0x3C8 } },
       { 17, 3, {  8,  4,  4,  5 }, { 0x349, 0x34C, 0x393, 0x3B3 } },
       { 20, 4, {  9,  5,  5,  4 }, { 0x382, 0x38B, 0x3D4, 0x3D9 } },
       { 24, 2, {  3,  3,  3,  3 }, { 0x36B, 0x378, 0x36B, 0x378 } },
       { 26, 2, {  4,  4,  4,  4 }, { 0x36E, 0x37B, 0x36E, 0x37B } },
       { 28, 3, {  6,  3,  6,  3 }, { 0x372, 0x37F, 0x372, 0x3D1 } },
       { 31, 1, {  2,  2,  2,  2 }, { 0x347, 0x347, 0x3AE, 0x3AE } }
    }

Lookup table for indices into the PlayerFace, valid ranges and sprites.

Definition at line 57 of file player_face.h.

Referenced by DrawPlayerFace(), and SelectPlayerFaceWndProc().