docs: Document @micropython.native usage policy. (#406)

* docs: Document @micropython.native usage policy.

Closes #405.

Add a guideline to CONTRIBUTING.md: @micropython.native must not be used
in driver code (I2C/SPI bus time dominates, native compilation gains
nothing) but may be used in examples on rendering hot-paths where a
measurable speedup is expected.

Remove the unnecessary @micropython.native from compute_display() in
radar_screen.py — the function does 3 comparisons with no loop, so
native compilation provides no benefit. Also remove the now-unused
`import micropython`.

* perf: Add @micropython.native to rendering hot-paths in examples.

Apply the policy documented in this PR to the three examples with
tight pixel loops:

- tamagotchi.py: draw_character() — 4 nested loops, pixel by pixel
- spirit_level.py: fill_circle() — double loop with x*x + y*y test
- maze_game.py: draw_maze() — double loop over 11x11 grid

* perf(ssd1327): Add @micropython.native to draw_cube() in 3D cube example.

draw_cube() runs 12 math.sin/cos calls + floating-point arithmetic per
frame in a tight animation loop. Native compilation reduces the per-frame
overhead significantly on the STM32WB55.

Author: nedseb

CONTRIBUTING.md

@@ -35,6 +35,7 @@ lib/<component>/
 - **Time**: use `from time import sleep_ms` (not `utime`, not `sleep()` with float seconds).
 - **Exceptions**: use `except Exception:` instead of bare `except:`. Enforced by ruff (E722).
 - **No debug `print()`** in production driver code. Enforced by ruff (T20, examples and tests excluded).
+- **`@micropython.native`**: do **not** use in driver code (`device.py`) — methods are dominated by I2C/SPI bus time, so native compilation gains nothing and reduces debuggability. In **examples**, it may be used on rendering hot-paths (tight pixel loops, math-heavy drawing functions) where a measurable speedup is expected. Do not apply it to functions with only a few comparisons or I/O calls. Note: the native emitter does not support generators, closures, or `with` statements.
 
 ## Driver API conventions
 

lib/bq27441/examples/tamagotchi.py

@@ -13,6 +13,7 @@
 import random
 from time import sleep_ms, ticks_diff, ticks_ms
 
+import micropython
 import ssd1327
 from bq27441 import BQ27441
 from machine import I2C, SPI, Pin
@@ -227,6 +228,7 @@ def wait_for_button():
     return None
 
 
+@micropython.native
 def draw_character(cx, cy, scale, sprite):
     """Draw a scaled pixel-art sprite on the display framebuf."""
     fb = display.framebuf

lib/ism330dl/examples/maze_game.py

@@ -18,6 +18,7 @@
 import random
 from time import sleep_ms
 
+import micropython
 import ssd1327
 from ism330dl import ISM330DL
 from machine import I2C, SPI, Pin
@@ -183,6 +184,7 @@ def cell_to_pixel(row, col):
     return SAFE_X + col * CELL_SIZE, SAFE_Y + row * CELL_SIZE
 
 
+@micropython.native
 def draw_maze(maze):
     """Draw all maze walls as filled rectangles."""
     for row in range(len(maze)):

lib/ism330dl/examples/spirit_level.py

@@ -9,6 +9,7 @@
 
 from time import sleep_ms
 
+import micropython
 import ssd1327
 from ism330dl import ISM330DL
 from machine import I2C, SPI, Pin
@@ -38,6 +39,7 @@
 POLL_RATE_MS = 20
 
 
+@micropython.native
 def fill_circle(fbuf, x0, y0, r, c):
     """Helper to draw a filled circle since framebuf lacks it natively."""
     for y in range(-r, r + 1):

lib/ssd1327/examples/rotating_3d_cube.py

@@ -1,5 +1,6 @@
 import math
 
+import micropython
 import ssd1327
 from machine import SPI, Pin
 
@@ -27,6 +28,7 @@
 r = [0, 0, 0]
 
 
+@micropython.native
 def draw_cube():
     r[0] = r[0] + pi / 180.0
     r[1] = r[1] + pi / 180.0

lib/vl53l1x/examples/radar_screen.py

@@ -7,7 +7,6 @@
 
 from time import sleep_ms
 
-import micropython
 import ssd1327
 from machine import I2C, SPI, Pin
 from steami_screen import DARK, GRAY, LIGHT, RED, Screen, SSD1327Display
@@ -29,7 +28,6 @@
 tof = VL53L1X(i2c)
 
 
-@micropython.native
 def compute_display(distance):
     """Compute proximity and color from distance value.