[Main]
Name=Sprite8
Type=Function
Subtype=tigcc.a
Header Files=sprites.h
Definition=void Sprite8 (short x, short y, short height, const unsigned char *sprite, void *vm_addr, short mode);

[Description]
Draws a sprite with a width of 8 pixels or less on the screen.

[Explanation]
Sprite8 draws a sprite with a width of 8 pixels or less on the screen.
Use <A HREF="$$LINK(sprites.h/Sprite16)">Sprite16</A> or <A HREF="$$LINK(sprites.h/Sprite32)">Sprite32</A> for wider sprites.
This routine is many times faster than TIOS routines like
<A HREF="$$LINK(graph.h/DrawIcon)">DrawIcon</A>, <A HREF="$$LINK(graph.h/BitmapPut)">BitmapPut</A>, etc.
<I>x</I> and <I>y</I> are the coordinates of the upper left corner of the sprite.
<I>height</I> is the height of the sprite. <I>sprite</I> is a pointer to the array of
unsigned characters which define the shape of the sprite (line by line). <I>vm_addr</I> is the pointer
to the video plane; it should be <A HREF="$$LINK(graph.h/LCD_MEM)">LCD_MEM</A> if you are not using
grayscale or the <A HREF="$$LINK(graph.h/PortSet)">PortSet</A> function. <I>mode</I> is the drawing
mode, and it may have one of the following values (these constants are defined in the enum
<A HREF="$$LINK(sprites.h/SprtModes)">SprtModes</A>):
<BR><BR>
<TABLE BORDER CELLPADDING="3">
<TR>
<TD VALIGN="TOP">SPRT_XOR</TD>
<TD>XOR the sprite into a background. This is used only for non-masked sprites.
XOR mode switches every pixel with a corresponding '1' bit in the <I>sprite</I> array from white to black and verse vica.</TD>
</TR>
<TR>
<TD VALIGN="TOP">SPRT_OR</TD>
<TD>OR the sprite into a background. This is mainly used for masked sprites together with SPRT_AND.
OR means that every pixel with a corresponding '1' bit in the <I>sprite</I> array will be set to black, but all other pixels stay the same.
If you want to turn all other pixels to white instead, use SPRT_RPLC.</TD>
</TR>
<TR>
<TD VALIGN="TOP">SPRT_AND</TD>
<TD>AND the sprite into a background. This is used for masked sprites together with SPRT_OR.
AND turns off every pixel with a corresponding '0' bit in the <I>sprite</I> array, but all other pixels remain untouched.
If you want to turn all other pixels to black instead, use SPRT_RPLC.</TD>
</TR>
<TR>
<TD VALIGN="TOP">SPRT_RPLC</TD>
<TD>RePLaCe the sprite into a background.
RPLC sets every pixel with a corresponding '1' bit to black and every pixel with a corresponding '0' bit to white.
This is equivalent to calling <CODE>Sprite8(x,y,h,sprite,plane,SPRT_AND); Sprite8(x,y,h,sprite,plane,SPRT_OR);</CODE>.</TD>
</TR>
</TABLE>
<BR>
In fact, you can use one of two techniques to draw sprites:
<UL>
<LI>
<B>Non-masked sprites.</B> Using this method, the sprites are simply XORed into the background. This
technique was popular in many games on old 8-bit computers. To erase the sprite, it is
enough to call the routine again on the same position.
</LI>
<LI>
<B>Masked sprites.</B> This is the more advanced method, which needs more programming practice,
but produces much better results. Using this method, you first need to erase a
part of the background which occupies a space where the sprite need to be displayed,
then to draw the actual sprite shape. To do this, AND the inverse of the sprite mask
to the background, then OR the sprite at the same location. However, it is not so
easy to restore the background later. For solving this problem, a lot of advanced
methods are developed (like "double-buffering", etc.). These methods are quite
common in advanced ASM games, and they are explained in many ASM tutorials.
</LI>
</UL>
Here is a simple example (called "Masked Sprite"), which first draws a simple "background", then draws a "masked"
sprite (which is a simple 8x8 square with solid edges and blank interior) at (30,30):
$$EXAMPLE(Masked Sprite.c)
Here the sprite mask is <CODE>{0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}</CODE>, but it needs to
be inverted before passing it to the Sprite8 function. For this purpose, the operator '~' may be
very useful. Note that '~' is "bitwise NOT". Of course, ~0xFF is the same as 0x00, but this notation
makes the program more clear (and it does not increase the code size, because the inverting will
be performed at compilation time). And if you want to use <A HREF="$$LINK(sprites.h/Sprite16)">Sprite16</A> or
<A HREF="$$LINK(sprites.h/Sprite32)">Sprite32</A>, the notation ~0xFF will still be valid in a short int array, or in a long int array
if you add the <B>'L'</B> suffix (see the respective info about <A HREF="$$LINK(sprites.h/Sprite32)">Sprite32</A>).
Without this notation, you must use 0x00 in Sprite8, but 0xFF00 in <A HREF="$$LINK(sprites.h/Sprite16)">Sprite16</A>, and
0xFFFFFF00 in <A HREF="$$LINK(sprites.h/Sprite32)">Sprite32</A>. This is why a notation like ~0xFF is more universal.
<BR><BR>
Starting from TIGCC v0.91, you can use binary numbers to define your sprites. On the one hand,
it makes the program incompatible with other C dialects as well as previous (ancient) versions of
TIGCC. On the other hand, it makes designing a sprite much easier
and also allows for editing the sprite at a later time without having to reconvert it.
The binary representation of the sprite presented above would look like this:
<PRE>static const unsigned char sprite[]={
0b11111111,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b11111111};
</PRE>
