copy optimized blitSprite impl to grabSprite, add simple docs

examples/curlywas/sprites.cwa

@@ -0,0 +1,21 @@
+include "../include/microw8-api.cwa"
+
+const SPRITE = 0x20000;
+
+export fn upd() {
+	cls(0);
+	let t = time();
+	let i: i32;
+	loop spriteLoop {
+		let inline x = sin(t * -1.3 + i as f32 / 8_f) * 180_f + 160_f;
+		let inline y = sin(t * 1.7 + i as f32 / 9_f) * 140_f + 120_f;
+		blitSprite(SPRITE, 16, x as i32, y as i32, 0x100);
+		branch_if (i +:= 1) < 200: spriteLoop;
+	}
+}
+
+start fn start() {
+	printChar('OO');
+	circle(8_f, 8_f, 6_f, 75);
+	grabSprite(SPRITE, 16, 0, 0, 0);
+}

examples/include/microw8-api.cwa

@@ -30,11 +30,13 @@ import "env.printInt" fn printInt(i32);
 import "env.setTextColor" fn setTextColor(i32);
 import "env.setBackgroundColor" fn setBackgroundColor(i32);
 import "env.setCursorPosition" fn setCursorPosition(i32, i32);
-import "env.rectangle_outline" fn rectangle_outline(f32, f32, f32, f32, i32);
+import "env.rectangleOutline" fn rectangleOutline(f32, f32, f32, f32, i32);
-import "env.circle_outline" fn circle_outline(f32, f32, f32, i32);
+import "env.circleOutline" fn circleOutline(f32, f32, f32, i32);
 import "env.exp" fn exp(f32) -> f32;
 import "env.playNote" fn playNote(i32, i32);
 import "env.sndGes" fn sndGes(i32) -> f32;
+import "env.blitSprite" fn blitSprite(i32, i32, i32, i32, i32);
+import "env.grabSprite" fn grabSprite(i32, i32, i32, i32, i32);
 
 const TIME_MS = 0x40;
 const GAMEPAD = 0x44;

examples/include/microw8-api.wat

@@ -30,11 +30,13 @@
 (import "env" "setTextColor" (func $setTextColor (param i32)))
 (import "env" "setBackgroundColor" (func $setBackgroundColor (param i32)))
 (import "env" "setCursorPosition" (func $setCursorPosition (param i32) (param i32)))
-(import "env" "rectangle_outline" (func $rectangle_outline (param f32) (param f32) (param f32) (param f32) (param i32)))
+(import "env" "rectangleOutline" (func $rectangleOutline (param f32) (param f32) (param f32) (param f32) (param i32)))
-(import "env" "circle_outline" (func $circle_outline (param f32) (param f32) (param f32) (param i32)))
+(import "env" "circleOutline" (func $circleOutline (param f32) (param f32) (param f32) (param i32)))
 (import "env" "exp" (func $exp (param f32) (result f32)))
 (import "env" "playNote" (func $playNote (param i32) (param i32)))
 (import "env" "sndGes" (func $sndGes (param i32) (result f32)))
+(import "env" "blitSprite" (func $blitSprite (param i32) (param i32) (param i32) (param i32) (param i32)))
+(import "env" "grabSprite" (func $grabSprite (param i32) (param i32) (param i32) (param i32) (param i32)))
 
 ;; to use defines, include this file with a preprocessor
 ;; like gpp (https://logological.org/gpp).

platform/src/platform.cwa

@@ -171,7 +171,7 @@ export fn rectangle(x: f32, y: f32, w: f32, h: f32, col: i32) {
     }
 }
 
-export fn rectangle_outline(x: f32, y: f32, w: f32, h: f32, col: i32) {
+export fn rectangleOutline(x: f32, y: f32, w: f32, h: f32, col: i32) {
     let xl = nearest(x) as i32;
     let xr = nearest(x + w) as i32;
     let yt = nearest(y) as i32;
@@ -212,7 +212,7 @@ export fn circle(cx: f32, cy: f32, radius: f32, col: i32) {
     }
 }
 
-export fn circle_outline(cx: f32, cy: f32, radius: f32, col: i32) {
+export fn circleOutline(cx: f32, cy: f32, radius: f32, col: i32) {
     let prev_w: f32;
     let y = clamp(nearest(cy - radius) as i32, -1, 241);
     let maxY = clamp(nearest(cy + radius) as i32, -1, 241);
@@ -352,6 +352,92 @@ export fn line(x1: f32, y1: f32, x2: f32, y2: f32, col: i32) {
     setPixel(i32.trunc_sat_f32_s(x1 + f * dx), i32.trunc_sat_f32_s(y1 + f * dy), col);
 }
 
+export fn blitSprite(sprite: i32, size: i32, x: i32, y: i32, control: i32) {
+    let lazy width = size & 65535;
+    let lazy height = select(size >> 16, size >> 16, width);
+
+    let lazy x0 = select(x < 0, -x, 0);
+    let lazy x1 = select(x + width > 320, 320 - x, width);
+    let lazy y0 = select(y < 0, -y, 0);
+    let lazy y1 = select(y + height > 240, 240 - y, height);
+
+    let lazy numRows = y1 - y0;
+    let lazy numCols = x1 - x0;
+    if numRows <= 0 | numCols <= 0 {
+        return;
+    }
+
+    let trans = (control & 511) - 256;
+    let lazy flip_x = 1 - ((control >> 8) & 2);
+    let lazy flip_y = 1 - ((control >> 9) & 2);
+    if flip_x < 0 {
+        sprite += width - 1;
+    }
+    if flip_y < 0 {
+        sprite += (height - 1) * width;
+    }
+
+    let spriteRow = sprite + x0 * flip_x + y0 * flip_y * width;
+    let screenRow = x + x0 + (y + y0) * 320;
+
+    loop yloop {
+        let lx = 0;
+        loop xloop {
+            let lazy col = (spriteRow + lx * flip_x)?0;
+            if col != trans {
+                (screenRow + lx)?120 = col;
+            }
+            branch_if (lx +:= 1) < numCols: xloop;
+        }
+        spriteRow += width * flip_y;
+        screenRow += 320;
+        branch_if numRows -:= 1: yloop;
+    }
+}
+
+export fn grabSprite(sprite: i32, size: i32, x: i32, y: i32, control: i32) {
+    let lazy width = size & 65535;
+    let lazy height = select(size >> 16, size >> 16, width);
+
+    let lazy x0 = select(x < 0, -x, 0);
+    let lazy x1 = select(x + width > 320, 320 - x, width);
+    let lazy y0 = select(y < 0, -y, 0);
+    let lazy y1 = select(y + height > 240, 240 - y, height);
+
+    let lazy numRows = y1 - y0;
+    let lazy numCols = x1 - x0;
+    if numRows <= 0 | numCols <= 0 {
+        return;
+    }
+
+    let trans = (control & 511) - 256;
+    let lazy flip_x = 1 - ((control >> 8) & 2);
+    let lazy flip_y = 1 - ((control >> 9) & 2);
+    if flip_x < 0 {
+        sprite += width - 1;
+    }
+    if flip_y < 0 {
+        sprite += (height - 1) * width;
+    }
+
+    let spriteRow = sprite + x0 * flip_x + y0 * flip_y * width;
+    let screenRow = x + x0 + (y + y0) * 320;
+
+    loop yloop {
+        let lx = 0;
+        loop xloop {
+            let lazy col = (screenRow + lx)?120;
+            if col != trans {
+                (spriteRow + lx * flip_x)?0 = col;
+            }
+            branch_if (lx +:= 1) < numCols: xloop;
+        }
+        spriteRow += width * flip_y;
+        screenRow += 320;
+        branch_if numRows -:= 1: yloop;
+    }
+}
+
 //////////
 // TEXT //
 //////////

site/content/docs.md

@@ -146,13 +146,13 @@ Fills the circle at `cx, cy` and with `radius` with the given color index.
 
 (Sets all pixels where the pixel center lies inside the circle.)
 
-### fn rectangle_outline(x: f32, y: f32, w: f32, h: f32, color: i32)
+### fn rectangleOutline(x: f32, y: f32, w: f32, h: f32, color: i32)
 
 Draws a one pixel outline on the inside of the given rectangle.
 
 (Draws the outermost pixels that are still inside the rectangle area.)
 
-### fn circle_outline(cx: f32, cy: f32, radius: f32, color: i32)
+### fn circleOutline(cx: f32, cy: f32, radius: f32, color: i32)
 
 Draws a one pixel outline on the inside of the given circle.
 
@@ -162,6 +162,21 @@ Draws a one pixel outline on the inside of the given circle.
 
 Draws a line from `x1,y1` to `x2,y2` in the given color index.
 
+### fn blitSprite(spriteData: i32, size: i32, x: i32, y: i32, control: i32)
+
+Copies the pixel data at `spriteData` onto the screen at `x`, `y`. The size of the sprite is passed as `width | (height << 16)`.
+If the height is given as 0, the sprite is is treated as square (width x width).
+
+The control parameter controls masking and flipping of the sprite:
+* bits 0-7: color mask index
+* bit 8: switch on masked blit (pixel with color mask index are treated as transparent)
+* bit 9: flip sprite x
+* bit 10: flip sprite y
+
+### fn grabSprite(spriteData: i32, size: i32, x: i32, y: i32, control: i32)
+
+Copies the pixel data on the screen at `x`, `y` to `spriteData`. Parameters are exactly the same as `blitSprite`.
+
 ## Input
 
 MicroW8 provides input from a gamepad with one D-Pad and 4 buttons, or a keyboard emulation thereof.

uw8-tool/src/base_module.rs

@@ -152,14 +152,14 @@ impl BaseModule {
         add_function(
             &mut functions,
             &type_map,
-            "rectangle_outline",
+            "rectangleOutline",
             &[F32, F32, F32, F32, I32],
             None,
         );
         add_function(
             &mut functions,
             &type_map,
-            "circle_outline",
+            "circleOutline",
             &[F32, F32, F32, I32],
             None,
         );
@@ -169,6 +169,21 @@ impl BaseModule {
         add_function(&mut functions, &type_map, "playNote", &[I32, I32], None);
         add_function(&mut functions, &type_map, "sndGes", &[I32], Some(F32));
 
+        add_function(
+            &mut functions,
+            &type_map,
+            "blitSprite",
+            &[I32, I32, I32, I32, I32],
+            None,
+        );
+        add_function(
+            &mut functions,
+            &type_map,
+            "grabSprite",
+            &[I32, I32, I32, I32, I32],
+            None,
+        );
+
         for i in functions.len()..64 {
             add_function(
                 &mut functions,