Módulo Bitmap

El módulo Bitmap proporciona funciones para cargar y manipular imágenes de mapa de bits (BMP) en JARU. Este módulo es esencial para trabajar con gráficos e imágenes en tus aplicaciones, tanto en la VM de Windows como en dispositivos ESP32.

Los bitmaps cargados pueden utilizarse posteriormente con el módulo Draw para renderizarlos en pantalla, crear interfaces gráficas, mostrar sprites de juegos, o cualquier otra aplicación que requiera visualización de imágenes.

Uso

use Bitmap

Funciones

load

La función load(archivo, [colorTransparente]) carga un archivo de imagen BMP desde el sistema de archivos y devuelve un objeto bitmap que puede ser utilizado para renderizar la imagen en pantalla.

Parámetros

Parámetro	Tipo	Descripción
archivo	string	Ruta relativa al archivo BMP a cargar
colorTransparente	integer	(Opcional) Color que se tratará como transparente en formato hexadecimal. Por defecto es 0x000000 (negro)

Retorno

Devuelve un objeto Bitmap con las siguientes propiedades:

Propiedad	Tipo	Descripción
width	integer	Ancho de la imagen en píxeles
height	integer	Alto de la imagen en píxeles
bpp	integer	Bits por píxel (profundidad de color)
size	integer	Tamaño del bitmap en bytes
transparent	integer	Color transparente asignado

Ejemplo básico

use Bitmap
use Display

// Abrir la pantalla
Display.open(320, 240)

// Cargar un bitmap
var imagen = Bitmap.load("logo.bmp")

// Mostrar información del bitmap
println("Ancho: ", imagen.width)
println("Alto: ", imagen.height)
println("Profundidad: ", imagen.bpp, " bits")

Ejemplo con color transparente

use Bitmap
use Display

Display.open(320, 240)

// Cargar bitmap con magenta (0xFF00FF) como color transparente
var sprite = Bitmap.load("personaje.bmp", 0xFF00FF)

// El color magenta no se dibujará, permitiendo ver el fondo

Ubicación de archivos

Los archivos BMP deben colocarse en el directorio Data/ de tu proyecto:

• ESP32: Los archivos se cargan desde /Data/ en LittleFS o tarjeta SD
• Windows: Los archivos se cargan desde el directorio Data/ del proyecto

Formato soportado

El módulo Bitmap soporta archivos en formato BMP (Windows Bitmap). Para mejores resultados en ESP32, se recomienda usar imágenes de 16 bits de profundidad de color.

Uso con el módulo Draw

Una vez cargado un bitmap, puedes renderizarlo en pantalla utilizando las funciones del módulo Draw:

use Bitmap
use Display

Display.open(320, 240)
var draw = Display.draw

// Cargar el bitmap
var fondo = Bitmap.load("fondo.bmp")
var personaje = Bitmap.load("hero.bmp", 0xFF00FF)

// Dibujar el fondo en la posición (0, 0)
draw.bitmap(fondo, 0, 0)

// Dibujar el personaje centrado
var x = (Display.width - personaje.width) / 2
var y = (Display.height - personaje.height) / 2
draw.bitmap(personaje, x, y)

// Actualizar la pantalla
Display.redraw()

Ejemplo completo: Galería de imágenes

use Bitmap
use Display
use GPIO

Display.open(320, 240)
var draw = Display.draw

// Cargar varias imágenes
var imagenes = [
    Bitmap.load("foto1.bmp"),
    Bitmap.load("foto2.bmp"),
    Bitmap.load("foto3.bmp")
]

var indice = 0
var total = len(imagenes)

// Configurar botón para cambiar imagen
GPIO.pinmode(15, GPIO.IN)

while (true)
    // Limpiar pantalla
    draw.cls(0x000000)
    
    // Dibujar imagen actual centrada
    var img = imagenes[indice]
    var x = (Display.width - img.width) / 2
    var y = (Display.height - img.height) / 2
    draw.bitmap(img, x, y)
    
    // Mostrar número de imagen
    var numImg = indice + 1
    draw.setcolor(0xFFFFFF)
    draw.text(10, 10, "Imagen " + numImg.toString() + "/" + total.toString())
    
    Display.redraw()
    
    // Cambiar imagen con botón
    if (GPIO.read(15) == GPIO.HIGH) then
        indice = (indice + 1) % total
        pause(300)  // Debounce
    end
    
    pause(50)
end

Ejemplo: Animación con sprites

use Bitmap
use Display

Display.open(320, 240)
var draw = Display.draw

// Cargar frames de animación con transparencia
var frames = [
    Bitmap.load("walk1.bmp", 0xFF00FF),
    Bitmap.load("walk2.bmp", 0xFF00FF),
    Bitmap.load("walk3.bmp", 0xFF00FF),
    Bitmap.load("walk4.bmp", 0xFF00FF)
]

var frameActual = 0
var numFrames = len(frames)
var x = 0

while (true)
    // Limpiar pantalla
    draw.cls(0x87CEEB)  // Color cielo
    
    // Dibujar suelo
    draw.rectfill(0, 200, 320, 240, 0x228B22)
    
    // Dibujar sprite actual
    draw.bitmap(frames[frameActual], x, 160)
    
    Display.redraw()
    
    // Avanzar animación
    frameActual = (frameActual + 1) % numFrames
    x = (x + 2) % Display.width
    
    pause(100)
end

Consideraciones de memoria

Uso de memoria

Los bitmaps ocupan memoria significativa, especialmente en dispositivos ESP32 con recursos limitados. Ten en cuenta:

• Un bitmap de 100x100 píxeles a 16 bits ocupa aproximadamente 20 KB
• Un bitmap de 320x240 píxeles a 16 bits ocupa aproximadamente 150 KB

Usa memFree() para monitorear la memoria disponible antes de cargar imágenes grandes.

use Bitmap

// Verificar memoria antes de cargar
println("Memoria libre: ", memFree(), " bytes")

var imagen = Bitmap.load("grande.bmp")

println("Memoria después de cargar: ", memFree(), " bytes")
println("Tamaño del bitmap: ", imagen.size, " bytes")

Plataformas soportadas

Plataforma	Soporte	Notas
Windows (SDL2)	✅	Carga desde directorio Data/ del proyecto
ESP32	✅	Carga desde LittleFS o tarjeta SD
Emscripten (Web)	✅	Carga desde directorio virtual Data/
SiFive	🚧	En desarrollo