Differences

This shows you the differences between two versions of the page.

--- development:csdk:2.0:headers:draw_direct [2024/11/22 08:52] – clyde
+++ development:csdk:2.0:headers:draw_direct [2024/11/22 09:07] (current) – clyde
@@ Line 2: / Line 2: @@
 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.
+In general the flow of Direct Drawing is:
+  - Set up either sprite or box mode with ''direct_prepare_sprite_mode'' or ''direct_prepare_box_mode''
+  - Set values for the blitter parameters using the ''DIRECT_SET_'' macros for ''SOURCE_X'', ''SOURCE_Y'', ''DEST_X'', ''DEST_Y'', ''WIDTH'' and ''HEIGHT''
+  - Start the blitter with ''DIRECT_DRAW_START();''
+  - Before modifying parameters to prepare the next drawing, ensure that the last drawing is finished with ''await_drawing();''
 ===== Drawing Semantics =====
-==== By indexing the hardware registers ===
-These are actually defined in gametank.h but are used for direct drawing
-<code C>
 <code C>
 #define DIRECT_SET_DEST_X(x) vram[VX] = (x);
@@ Line 15: / Line 19: @@
 #define DIRECT_SET_HEIGHT(h) vram[HEIGHT] = (h);
 #define DIRECT_SET_COLOR(c) vram[COLOR] = ~(c);
-</code>
 </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.
@@ Line 29: / Line 32: @@
   * COLOR sets the color for solid colored box mode, bitwise inverted
+Before using these, you'll need to call either ''direct_prepare_sprite_mode'' or ''direct_prepare_box_mode'' to ensure that the blitter control registers are ready to accept these parameters. (See below)
 ===== Functions =====
 ==== direct_prepare_sprite_mode ====
@@ Line 70: / Line 74: @@
 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_SET_DEST_X====
+<code C>
+DIRECT_SET_DEST_X(x)
+</code>
+Sets the X position of the blitter's cursor into the framebuffer.
+==== DIRECT_SET_DEST_Y====
+<code C>
+DIRECT_SET_DEST_Y(y)
+</code>
+Sets the Y position of the blitter's cursor into the framebuffer. Safe to modify during blits.
+==== DIRECT_SET_SOURCE_X====
+<code C>
+DIRECT_SET_SOURCE_X(x)
+</code>
+Sets the X position of the blitter's cursor in the selected Sprite RAM page.
+This macro also factors in the X offset bit, which is set or cleared by ''direct_prepare_sprite_mode'' or ''direct_quick_select_sprite'' based on the location of the selected SpriteSlot in Sprite RAM.
+==== DIRECT_SET_SOURCE_Y====
+<code C>
+DIRECT_SET_SOURCE_Y(y)
+</code>
+Sets the Y position of the blitter's cursor in the selected Sprite RAM page. Safe to modify during blits.
+This macro also factors in the Y offset bit, which is set or cleared by ''direct_prepare_sprite_mode'' or ''direct_quick_select_sprite'' based on the location of the selected SpriteSlot in Sprite RAM.
+==== DIRECT_SET_WIDTH====
+<code C>
+DIRECT_SET_WIDTH(w)
+</code>
+Sets the width of the next blitter operation.
+==== DIRECT_SET_HEIGHT====
+<code C>
+DIRECT_SET_HEIGHT(h)
+</code>
+Sets the height of the next blitter operation. Safe to modify during blits.
+==== DIRECT_SET_COLOR====
+<code C>
+DIRECT_SET_COLOR(c)
+</code>
+Sets the color that will be used if the blitter is in solid color mode, as set by ''direct_prepare_box_mode''.
 ==== DIRECT_DRAW_START ====
 <code C>