View source for GBDK set sprite prop

== Introduction ==
This tutorial seeks to describe, with examples, how to make precise changes to a sprite's state, without requiring any previous knowledge of binary or bitwise operators.
The <code>set_sprite_prop</code> function, found in [[gb.h]], sets properties of a sprite.

== TL;DR: ==
The property argument is a byte and can be combined using bitwise operators to pass several properties at once: <code>property1 | property2 | ... | propertyn</code> to send multiple properties, <code>existingProperties | property<code> to leave everything the same but turn property on, <code>existingProperties & ~property<code> to leave everything the same but turn property off.

== Definitions ==
<code>gb.h</code> includes some property definitions:
* #define S_PALETTE    0x10U
* #define S_FLIPX      0x20U
* #define S_FLIPY      0x40U
* #define S_PRIORITY   0x80U

The problem with setting these is that any will obliterate any other properties. 

== Sprite property flags ==
The flags are stored in binary like this:

{| class="wikitable"
|Bit
|0 
|0
|0
|0
|0
|0
|0
|0
|-
|Feature
|Relative to background
|Flip Y
|Flip X
|DMG palette
|GBC Tile bank
|Color
|Color
|Color
|-
|0
|In front
|Don't flip
|Don't flip
|Monochrome palette 0
|Bank 0
|0+
|0+
|0
|-
|1
|Behind
|Flip vertically
|Flip horizontally
|Monochrome palette 1
|Bank 1
|1+
|1+
|1
|}

== set_sprite_prop ==
Using the defined shorthand, you can call

<code>set_sprite_prop(spriteNumber, S_FLIPY);</code>

which sets the properties to <code>01000000</code> (40 in hexadecimal, 64 in decimal), and

<code>set_sprite_prop(spriteNumber, S_FLIPX);</code>

which sets the properties to <code>00100000</code> (20 in hexadecimal, 32 in decimal)

but if you do both, the entire set is overwritten with the latest set, so the bit that is flipped gets flipped back.

== Bitwise operators ==
So how do you do both? With bitwise operators! We're specifically interested in <code>&</code> (and), <code>|</code> (or), and <code>~</code> complement. <code>&</code> adds two bit sets together but only carries over 1s that existed in both previous sets (1100 & 1011 is 1000). <code>|</code> carries over any 1s that existed in either (1000 | 1011 is 1011). <code>~</code> gives the complement of a single set, effectively flipping each bit to its opposite, regardless of its position (~1011 is 0100).

So how do we put this into practice?

== OR ==
Well, we know that <code>S_FLIPY</code> is <code>01000000</code> and <code>S_FLIPX</code> is <code>00100000</code>. To turn both on in one move, you'd use OR: <code>|</code>, and get <code>01100000</code>:

<code>set_sprite_prop(spriteNumber, S_FLIPY | S_FLIPX);</code>

=== get_sprite_prop ===
That's great! But it ignores the existing states of the other bits, for example a color palette, or priority relative to the background. Perhaps you want to flip the sprite on its axes independently of each other. For that, you can feed <code>get_sprite_prop</code> directly into <code>set_sprite_prop</code> (or set it to a variable and feed that in) and use the <code>|</code> operator:

<code>set_sprite_prop(spriteNumber, get_sprite_prop(spriteNumber) | newProp);</code>

A real example: <code>set_sprite_prop(0, get_sprite_prop(0) | S_FLIPX);</code>

== AND and NOT ==
Now how do you switch a bit off? Here's where the <code>&</code> and <code>~</code> operators come into play. 

With <code>&</code>, we know that only 1s found in both sets get carried over. Any set <code>&</code> a set full of 1s will result in that set. Any 0 in either set will result in a 0 in the resulting set. So we need to <code>&</code> combine the existing property set with a set full of 1s and a 0 in the position of the bit we want to switch off. We can get the latter with the complement operator <code>~</code> and any single or collective setting we want turned off.

An example:

The existing state of properties on a sprite is <code>00100011</code> (see [[#get_sprite_prop]])(flipped horizontally, set to color palette 3), and we want to revert the mirrored effect. So:

<code>00100011</code> & ~<code>00100000</code>

Breaking this down completely, let's apply the NOT first and flip the latter set:

<code>11011111</code>

Now let's combine them using AND:

<code>001000'''11'''</code>

<code>110111'''11'''</code>

making:

<code>00000011</code>

We've successfully retained all previous bit states except for the one we switched off.

Here's a real-world example:

<code>set_sprite_prop(0, get_sprite_prop(0) & ~S_FLIPX);</code>

== Takeaway ==
Hopefully you can now apply any changes to a sprite's properties without a lot of hassle or trial and error.