====== draw_direct.h ======

draw_direct.h provides macros and functions to support setting up draw operations by direct manipulation of blitter registers. The functions and macros are largely convenience functions for setting up the control registers for common operations, like drawing sprites or colored boxes.

===== Drawing Semantics =====
These are actually defined in gametank.h but are used for direct drawing
<code C>
#define vram ((volatile char *) 0x4000)

#define VX 0
#define VY 1
#define GX 2
#define GY 3
#define WIDTH 4
#define HEIGHT 5
#define START 6
#define COLOR 7
</code>
`vram` points to the memory range that is alternately used for the Frame Buffer, the Sprite RAM, and the Blitter Control Registers. If the blitter is enabled (as done by calling one of the direct_prepare_ functions below) the first eight addresses in the VRAM range will map to the Blitter Control Registers.

  *  VX and VY, as in "Video" set the position in the frame buffer pointed to (destination)

  * GX and GX, as in "Graphics" set the position in the Sprite RAM pointed to (source data)

  * WIDTH and HEIGHT set the width and height of a drawing operation. Range 0-127 supported, the high bit is used for reversing the direction of blitting (sprite flipping)

  * START is a location that will start a blit if you write a 1 to it, but you should use the DIRECT_DRAW_START so that the draw_busy flag will be set.

  * COLOR sets the color for solid colored box mode, bitwise inverted

===== Functions =====
==== direct_prepare_sprite_mode ====
<code C>
void direct_prepare_sprite_mode(SpriteSlot sprite);
</code>
Setup registers to draw sprites in direct mode
Also checks for and awaits queued drawing operations
==== direct_quick_select_sprite ====
<code C>
void direct_quick_select_sprite(SpriteSlot sprite);
</code>
Both this and direct_prepare_sprite_mode select the sprite slot to use
but this skips other register settings and ONLY selects the sprite slot
==== direct_prepare_box_mode ====
<code C>
void direct_prepare_box_mode();
</code>
Setup registers to draw colored boxes in direct mode
Also checks for and awaits queued drawing operations
==== direct_tiled_mode ====
<code C>
void direct_tiled_mode(bool enabled);
</code>
If enabled, sprite draws will repeat the same 16x16 grid from the source data
==== direct_transparent_mode ====
<code C>
void direct_transparent_mode(bool enabled);
</code>
If enabled, sprite draws will treat color 0 as transparent instead of black
==== direct_clip_mode====
<code C>
void direct_clip_mode(clip_mode_t mode);
</code>
Set whether drawings will be clipped at screen edges or wrap around
==== direct_draw_sprite_frame ====
<code C>
void direct_draw_sprite_frame(SpriteSlot sprite, char x, char y, char frame, char flip);
</code>
Draws a packed sprite as exported from Aseprite with a given X,Y position and frame number. A SpriteSlot is a handle given by allocate_sprite in sprites.h
===== Macros =====
==== DIRECT_DRAW_START ====
<code C>
DIRECT_DRAW_START()
</code>
Use DIRECT_DRAW_START() to start a draw operation after setting the blit registers. This macro includes setting the draw_busy flag so that await_drawing() from gfx_sys.h works properly.
==== DIRECT_DRAW_CLEAR_IRQ ====
<code C>
DIRECT_DRAW_CLEAR_IRQ()
</code>
Clears the IRQ flag that is set by the blitter when it completes a draw operation.
==== DIRECT_DRAW_SPRITE ====
<code C>
DIRECT_DRAW_SPRITE(dst_x, dst_y, w, h, src_gx, src_gy)
</code>
Convenience macro for drawing a sprite, assuming that the sprite mode has already been set with direct_prepare_sprite_mode
==== DIRECT_DRAW_SPRITE ====
<code C>
DIRECT_DRAW_SPRITE(dst_x, dst_y, w, h, c)
</code>
Convenience macro for drawing a colored box, assuming that the box mode has already been set with direct_prepare_box_mode

===== Examples =====

A basic tilemap drawing routine using Direct Draws
<code C>
void draw_tile_map() {
    static char x, y, i, t;
    direct_prepare_sprite_mode(map_tile_gfx);
    direct_transparent_mode(false);
    push_rom_bank();
    change_rom_bank(ASSET__gfx__test1_bin_bank);

    x = 0;
    y = 0;
    i = 0;
    vram[VY] = 0;
    vram[WIDTH] = 16;
    vram[HEIGHT] = 16;
    while(i < 64) {
        t = ASSET__gfx__test1_bin_ptr[i];
        await_drawing();
        vram[VX] = x;
        vram[GX] = t << 4;
        vram[GY] = t & ~15;
        DIRECT_DRAW_START();
        ++i;
        x += 16;
        if(x == 128) {
            x = 0;
            y += 16;
            vram[VY] = y; //Incidentally, VY, GY, and Height are safe to set while a blit is still running.
        }
    }
    await_drawing();

    pop_rom_bank();
}
</code>