copy optimized blitSprite impl to grabSprite, add simple docs

examples/include/microw8-api.cwa

@@ -30,8 +30,8 @@ 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;

examples/include/microw8-api.wat

@@ -30,8 +30,8 @@
 (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)))

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);
@@ -377,30 +377,42 @@ export fn blitSprite(sprite: i32, size: i32, x: i32, y: i32, control: i32) {
         sprite += (height - 1) * width;
     }
 
-    let srcRow = sprite + x0 * flip_x + y0 * flip_y * width;
+    let spriteRow = sprite + x0 * flip_x + y0 * flip_y * width;
-    let dstRow = x + x0 + (y + y0) * 320;
+    let screenRow = x + x0 + (y + y0) * 320;
 
     loop yloop {
         let lx = 0;
         loop xloop {
-            let lazy col = (srcRow + lx * flip_x)?0;
+            let lazy col = (spriteRow + lx * flip_x)?0;
             if col != trans {
-                (dstRow + lx)?120 = col;
+                (screenRow + lx)?120 = col;
             }
             branch_if (lx +:= 1) < numCols: xloop;
         }
-        srcRow += width * flip_y;
+        spriteRow += width * flip_y;
-        dstRow += 320;
+        screenRow += 320;
         branch_if numRows -:= 1: yloop;
     }
 }
 
 export fn grabSprite(sprite: i32, size: i32, x: i32, y: i32, control: i32) {
-    let width = size & 65535;
+    let lazy width = size & 65535;
-    let height = select(size >> 16, size >> 16, width);
+    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 flip_x = 1 - ((control >> 8) & 2);
+    let lazy flip_x = 1 - ((control >> 8) & 2);
-    let flip_y = 1 - ((control >> 9) & 2);
+    let lazy flip_y = 1 - ((control >> 9) & 2);
     if flip_x < 0 {
         sprite += width - 1;
     }
@@ -408,17 +420,21 @@ export fn grabSprite(sprite: i32, size: i32, x: i32, y: i32, control: i32) {
         sprite += (height - 1) * width;
     }
 
-    let ly = 0;
+    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 col = getPixel(x + lx, y + ly);
+            let lazy col = (screenRow + lx)?120;
             if col != trans {
-                (sprite + lx * flip_x + ly * flip_y * height)?0 = col;
+                (spriteRow + lx * flip_x)?0 = col;
             }
-            branch_if (lx +:= 1) < width: xloop;
+            branch_if (lx +:= 1) < numCols: xloop;
         }
-        branch_if (ly +:= 1) < height: yloop;
+        spriteRow += width * flip_y;
+        screenRow += 320;
+        branch_if numRows -:= 1: yloop;
     }
 }
 

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,
         );