Funciones y constantes
de Geobuino

(Geobuino API reference)

Principales (Core)

Constantes

Pantalla (General)

Pantalla (Texto)

Pantalla (Gráficos)

Botones

Colisión

Sonido (General)

Sonido monofónico (GeoSound)

Sonido polifónico (GeoMusic)

A partir de versión 1.1.0 de Geobuino

Pantalla (Sprites)

  • drawExternalMask(int16_t x, int16_t y, const uint8_t *bitmap, const uint8_t *mask, uint8_t frame, uint8_t mask_frame)
  • drawPlusMask(int16_t x, int16_t y, const uint8_t *bitmap, uint8_t frame)
  • drawOverwrite(int16_t x, int16_t y, const uint8_t *bitmap, uint8_t frame)
  • drawErase(int16_t x, int16_t y, const uint8_t *bitmap, uint8_t frame)
  • drawSelfMasked(int16_t x, int16_t y, const uint8_t *bitmap, uint8_t frame)

void begin()

Descripción: Inicializa Geobuino. Debería invocarse al principio de la función setup(), antes del llamado a cualquier otra función de la clase Geobuino. Inicializa la pantalla, los botones, el sonido y los cuadros por segundo (60).

Parámetros: Ninguno

Retorno: Nada

Volver

void setFrameRate(uint8_t fps)

Descripción: Cambia los cuadros por segundo el los que corre el juego. Por defecto, un juego corre a 60 cuadros por segundo.

Parámetros:

  • fps: cuadros por segundo

Retorno: Nada

Volver

void waitFrame(bool automaticUpdate = true)

Descripción: Espera hasta que sea el momento de ejecutar el próximo cuadro, de acuerdo a la cantidad de cuadros por segundo especificada (por defecto 60). Se la invoca normalmente al principio del la función loop().

Parámetros:

  • automaticUpdate(opcional): Indica si se invoca automáticamente a la lectura de los botones y actualización de la pantalla

Retorno: Nada

Volver

long randomNumber(long howsmall, long howbig)

Descripción: Retorna un valor aleatorio comprendido entre min(inclusive) y max(exclusive).

Parámetros:

  • min: Límite inferior del valor aleatorio (inclusive)
  • max: Límite superor del valor aleatorio (exclusive)

Retorno: Valor numérico (long)

Volver

bool framesElapsed(uint8_t frames)

Descripción: Devuelve true cada vez que se ejecuta el número especificado de cuadros. Devuelve false en caso contrario.

Parámetros:

  • frames: El numero deseado de cuadros que deben transcurrir

Retorno: Valor booleano

Volver

Constantes

WHITE: Color que representa el pixel encendido en pantalla (1).

BLACK: Color que representa el pixel apagado en pantalla (0).

DISPLAY_WIDTH: Ancho de la pantalla en píxeles (128).

DISPLAY_HEIGHT: Alto de la pantalla en píxeles (64) .

BTN_UP, BTN_RIGHT, BTN_DOWN, BTN_LEFT: Identificadores de los botones Arriba,Derecha,Abajo,Izquierda.

BTN_A, BTN_B, BTN_C: Identificadores de los botones A,B,C.

 

Volver

void clearDisplay()

Descripción: Limpia el buffer de la pantalla y posiciona el cursor en la esquina superior izquierda (0,0).

Parámetros: Ninguno

Retorno: Nada

Volver

void updateDisplay()

Descripción: Envía el buffer de la pantalla a la pantalla. Sólo es necesario invocarlo si no se usa waitFrame() o si dicha función es usada con el parámetro «automaticUpdate» en falso: waitFrame(false).

Parámetros: Ninguno

Retorno: Nada

Volver

void invertDisplay(bool inverse)

Descripción: Invierte los colores de la pantalla. Esto se mantiene hasta que se invoca a la función con inverse=false.

Parámetros:

  • inverse: True invierte la pantalla. False la vuelve a la normalidad

Retorno: Nada

Volver

void drawPixel(int16_t x, int16_t y, uint8_t color = WHITE)

Descripción: Dibuja un punto en las coordenadas dadas.

Parámetros:

  • x,y: coordenadas del punto a graficar
  • color: color del punto (opcional, por defecto WHITE)

Retorno: Nada

Volver

uint8_t getPixel( uint8_t x, uint8_t y )

Descripción: Lee el color de un punto (del buffer de la pantalla) en las coordenadas dadas.

Parámetros:

  • x,y: coordenadas del punto a graficar

Retorno: Valor numérico (WHITE o BLACK)

Volver

void drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint8_t color = WHITE)

Descripción: Dibuja una línea recta entre 2 puntos de la pantalla. Por defecto utiliza el color WHITE.

Parámetros:

  • x0,y0: Coordenadas del punto origen
  • x1,y1: Coordenadas del punto destino
  • color: color de la línea (opcional, por defecto WHITE)

Retorno: Nada

Volver

void drawFastVLine ( int16_t x, int16_t y, uint8_t h, uint8_t color = WHITE )

Descripción: Dibuja una línea recta vertical a partir del punto superior. Por defecto utiliza el color WHITE.

Parámetros:

  • x,y: Coordenadas del punto superior(origen)
  • h: Altura de la línea
  • color: color de la línea (opcional, por defecto WHITE)

Retorno: Nada

Volver

void drawFastHLine(int16_t x, int16_t y, uint8_t w, uint8_t color = WHITE)

Descripción: Dibuja una línea recta horizontal a partir del punto de la izquierda. Por defecto utiliza el color WHITE.

Parámetros:

  • x,y: Coordenadas del punto de la izquierda(origen)
  • w: Ancho de la línea
  • color: color de la línea (opcional, por defecto WHITE)

Retorno: Nada

Volver

void drawRect(int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color = WHITE)

Descripción: Dibuja un rectángulo de un ancho y altura determinados, a partir del punto correspondiente a la esquina superior izquierda.

Parámetros:

  • x,y: Coordenadas del punto de la esquina superior izquierda(origen)
  • w: Ancho del rectángulo
  • h: Altura del rectángulo
  • color: Color de la línea (opcional, por defecto WHITE)

Retorno: Nada

Volver

void fillRect(int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color)

Descripción: Dibuja un rectángulo relleno, de un ancho y altura determinados, a partir del punto correspondiente a la esquina superior izquierda.

Parámetros:

  • x,y: Coordenadas del punto de la esquina superior izquierda(origen)
  • w: Ancho del rectángulo
  • h: Altura del rectángulo
  • color: Color del rectángulo y relleno (opcional, por defecto WHITE)

Retorno: Nada

Volver

void drawCircle(int16_t x0, int16_t y0, uint8_t r, uint8_t color = WHITE)

Descripción: Dibuja una circunferencia de centro y radios dados.

Parámetros:

  • x0,y0: Coordenadas del centro de la circunferencia
  • r: radio de la circunferencia
  • color: Color de la circunferencia (opcional, por defecto WHITE)

Retorno: Nada

Volver

void fillCircle(int16_t x0, int16_t y0, uint8_t r, uint8_t color = WHITE)

Descripción: Dibuja una circunferencia de centro y radios dados.

Parámetros:

  • x0,y0: Coordenadas del centro de la circunferencia
  • r: radio de la circunferencia
  • color: color de la circunferencia y relleno (opcional, por defecto WHITE)

Retorno: Nada

Volver

void drawTriangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color=WHITE)

Descripción: Dibuja un triángulo, dadas las coordenadas de cada vértice.

Parámetros:

  • x0,y0: Coordenadas del vértice 1
  • x1,y1: Coordenadas del vértice 2
  • x2,y2: Coordenadas del vértice 3
  • color: Color del triángulo (opcional, por defecto WHITE)

Retorno: Nada

Volver

void fillTriangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color=WHITE)

Descripción: Dibuja un triángulo relleno, dadas las coordenadas de cada vértice.

Parámetros:

  • x0,y0: Coordenadas del vértice 1
  • x1,y1: Coordenadas del vértice 2
  • x2,y2: Coordenadas del vértice 3
  • color: Color del triángulo y relleno (opcional, por defecto WHITE)

Retorno: Nada

Volver

void drawRoundRect(int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color = WHITE)

Descripción: Dibuja un rectángulo con las esquinas redondeadas, de un ancho y altura determinados, a partir del punto correspondiente a la esquina superior izquierda.

 

Parámetros:

  • x,y: Coordenadas del punto de la esquina superior izquierda(origen)
  • w: Ancho del rectángulo
  • h: Altura del rectángulo
  • r: Radio de las semicircunferencias que forman las esquinas
  • color: Color del rectángulo (opcional, por defecto WHITE)

Retorno: Nada

Volver

void fillRoundRect(int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color = WHITE)

Descripción: Dibuja un rectángulo relleno con las esquinas redondeadas, de un ancho y altura determinados, a partir del punto correspondiente a la esquina superior izquierda.

Parámetros:

  • x,y: Coordenadas del punto de la esquina superior izquierda(origen)
  • w: Ancho del rectángulo
  • h: Altura del rectángulo
  • r: Radio de las semicircunferencias que forman las esquinas
  • color: Color del rectángulo y relleno (opcional, por defecto WHITE)

Retorno: Nada

Volver

void drawBitmap(int16_t x, int16_t y, const uint8_t * bitmap)

Descripción: Dibuja un mapa de bits (bitmap) desde un arreglo ubicado en la memoria de programa (PROGMEM).

Parámetros:

  • x,y: Coordenadas del pixel de la esquina superior izquierda del bitmap
  • bitmap: Un puntero al arreglo que contiene la imagen

Retorno: Nada

Volver

void setCursor(int16_t x, int16_t y)

Descripción: Establece la posición del cursor de texto. Los parámetros x,y corresponden a las coordenadas de la pantalla en pixeles. La ubicación del cursor corresponde a la esquina superior izquierda del próximo caracter escrito.

Parámetros:

  • x,y: Coordenadas del cursor

Retorno: Nada

Volver

int16_t getCursorX()

Descripción: Devuelve la coordenada X de la posición del cursor de texto.

Parámetros: Ninguno

Retorno: Valor numérico

Volver

int16_t getCursorY()

Descripción: Devuelve la coordenada Y de la posición del cursor de texto.

Parámetros: Ninguno

Retorno: Valor numérico

Volver

void setTextBackgroundColor(uint8_t color )

Descripción: Establece el color de fondo del texto.

Parámetros:

  • color: Color del fondo

Retorno: Nada

Volver

uint8_t getTextBackgroundColor()

Descripción: Devuelve el color de fondo del texto actualmente establecido.

Parámetros: Ninguno

Retorno: Valor numérico (WHITE o BLACK)

Volver

void setTextColor( uint8_t color )

Descripción: Establece el color del texto.

Parámetros:

  • color: Color del texto

Retorno: Nada

Volver

uint8_t getTextColor()

Descripción: Devuelve el color del texto actualmente establecido.

Parámetros: Ninguno

Retorno: Valor numérico (WHITE o BLACK)

Volver

void setTextSize(uint8_t size)

Descripción: Cambia el tamaño de la fuente. El parámetro s es un multiplicador de tamaño. Debe ser 1 o superior. El tamaño por defecto de la fuente es 1.

Parámetros:

  • size: Tamaño de la fuente

Retorno: Nada

Volver

uint8_t getTextSize()

Descripción: Devuelve el tamaño de fuente actualmente establecido.

Parámetros: Ninguno

Retorno: Valor numérico

Volver

void print(val)

Descripción: Imprime datos en pantalla como texto ASCII. Acepta caracteres, cadenas de caracteres y números. Para establecer la ubicación del texto, debe usarse setCursor() (por defecto es la esquina superior izquierda de la pantalla). Luego de imprimir el cursor queda al final de lo último impreso en pantalla. El tamaño de la fuente puede cambiarse usando setTextSize(). El color de fondo y del texto pueden cambiarse con setTextBackgroundColor() y setTextColor() respectivamente. Para realizar un salto de línea luego de la impresión, puede utilizarse el caracter ‘\n’ al final de la cadena a imprimir. Se utliza una fuente de 5×7 pixeles.

Parámetros:

  • val: valor a imprimir

Retorno: Nada

Volver

bool pressedButton(uint8_t button)

Descripción: Chequea si un determinado botón está siendo presionado.

Parámetros:

  • button: Identificador del botón (BTN_A, BTN_B, BTN_C, BTN_UP, BTN_RIGHT, BTN_DOWN o BTN_LEFT)

Retorno: Valor booleano

Volver

bool justPressedButton(uint8_t button)

Descripción: Chequea si un determinado botón acaba de ser presionado.

Parámetros:

  • button: Identificador del botón (BTN_A, BTN_B, BTN_C, BTN_UP, BTN_RIGHT, BTN_DOWN o BTN_LEFT)

Retorno: Valor booleano

Volver

bool justReleasedButton(uint8_t button)

Descripción: Chequea si un determinado botón acaba de ser soltado.

Parámetros:

  • button: Identificador del botón (BTN_A, BTN_B, BTN_C, BTN_UP, BTN_RIGHT, BTN_DOWN o BTN_LEFT)

Retorno: Valor booleano

Volver

void readButtons()

Descripción: Lee y guarda el estado de los botones, para luego poder utilizar las funciones pressedButton, justPressedButton y justReleasedButton. Es invocada automáticamente al utilzar waitFrame(). En caso de no usarse waitFrame() o usarse waitFrame(false), readButtons() debería ser invocada al inicio de cada nuevo frame.

Parámetros: Ninguno

Retorno: Nada

Volver

boolean collidePointRect(int16_t x1, int16_t y1 ,int16_t x2 ,int16_t y2, int16_t w, int16_t h)

Descripción: Chequea la colisión entre un punto y un rectángulo. Retorna true si los rectángulos colisionan y false en caso contrario.

Parámetros: 

  • x1,y1: Coordenadas del punto
  • x2,y2: Coordenadas del punto de la esquina superior izquierda del rectángulo (origen)
  • w2: Ancho del rectángulo
  • h2: Altura del rectángulo

Retorno: Valor booleano

Volver

boolean collideRectRect(int16_t x1, int16_t y1, int16_t w1, int16_t h1 ,int16_t x2 ,int16_t y2, int16_t w2, int16_t h2)

Descripción: Chequea la colisión entre dos rectángulos. Retorna true si los rectángulos colisionan y false en caso contrario.

Parámetros: 

  • x1,y1: Coordenadas del punto de la esquina superior izquierda del primer rectángulo (origen)
  • w1: Ancho del primer rectángulo
  • h1: Altura del primer rectángulo
  • x2,y2: Coordenadas del punto de la esquina superior izquierda del segundo rectángulo (origen)
  • w2: Ancho del segundo rectángulo
  • h2: Altura del segundo rectángulo

Retorno: Valor booleano

Volver

boolean collideBitmapBitmap(int16_t x1, int16_t y1, const uint8_t* b1, int16_t x2, int16_t y2, const uint8_t* b2)

Descripción: Chequea píxel por píxel la colisión entre dos mapas de bits (bitmaps). Retorna true si los bitmaps colisionan y false en caso contrario.

Parámetros: 

  • x1,y1: Coordenadas del píxel de la esquina superior izquierda del bitmap
  • b1: Un puntero al arreglo que contiene la imagen del primer bitmap
  • x2,y2: Coordenadas del píxel de la esquina superior izquierda del segundo bitmap
  • b2: Un puntero al arreglo que contiene la imagen del segundo bitmap

Retorno: Valor booleano

Volver

bool soundEnabled()

Descripción: Devuelve el estado actual del sonido.

Parámetros: Ninguno

Retorno: Valor booleano (True: Sonido hablitado, False: Sonido silenciado)

Volver

void soundOff()

Descripción: Deshabilita el sonido en la consola (silenciamiento).

Parámetros: Ninguno

Retorno: Nada

Volver

void soundOn()

Descripción: Habilita el sonido en la consola.

Parámetros: Ninguno

Retorno: Nada

Volver

GeoSound(boolean (*enabled)())

Descripción: Constructor de la clase GeoSound. Debe invocarse antes de llamar a cualquier otra función de GeoSound.

Parámetros:

  • enabled: Función que devuelve ‘true’ si el sonido debería estar habilitado, o ‘false’ si el sonido debería ser silenciado.

Ejemplo: GeoSound sound(geo.soundEnabled);

Volver

void playNote(uint16_t freq, uint16_t dur = 0)

Descripción: Hace sonar un tono en una frecuencia y con una duración determinada.

Parámetros:

  • freq: Frecuencia del tono en hertz
  • dur: Duración del tono en milisegundos. Si se provee una duración de 0 o ninguna, el sonido se reproducirá para siempre, o hasta que se llame a stopNote() o se comience a reproducir otro sonido o secuencia.

Retorno: Nada

Volver

void playNotes(const uint16_t tones[])

Descripción: Ejecuta una secuencia de tonos (pares frecuencia/duración) desde un arreglo en la memoria de programa (PROGMEM). Una frecuencia de 0 significa un silencio musical. El último elemento del arreglo debe ser «TONES_END» o «TONES_REPEAT».

Parámetros:

  • tones: Un puntero a un arreglo de pares frecuencia/duración. El arreglo debe estar ubicado en la memoria de programa, usando «PROGMEM» 

Retorno: Nada

Ejemplo de secuencia:

const uint16_t INIT_SONG[] PROGMEM = { NOTE_E4,500,NOTE_E4,500,NOTE_F4,500,NOTE_G4,500,NOTE_G4,500,TONES_END};

Volver

void stopNote()

Descripción: Detiene la ejecución de cualquier tono o secuencia.

Parámetros: Ninguno

Retorno: Nada

 

Volver

boolean playing()

Descripción: Chequea si se está ejecutando un tono o secuencia.

Parámetros: Ninguno

Retorno: Valor booleano

Volver

Constantes de Sonido

Ejemplos de constantes de notas:

  • NOTE_C2 : Do en octava 2
  • NOTE_DS3: Re sostenido en octava 3
  • NOTE_REST: Frecuencia 0 (Silencio)

TONES_REPEAT: La secuencia se repite indefinidamente

TONES_END: La secuencia termina

Volver

GeoMusic(boolean (*enabled)())

Descripción: Constructor de la clase GeoMusic. Debe invocarse antes de llamar a cualquier otra función de GeoMusic.

Parámetros:

  • enabled: Función que devuelve ‘true’ si el sonido debería estar habilitado, o ‘false’ si el sonido debería ser silenciado.

Ejemplo: GeoMusic music(geo.soundEnabled);

Volver

void initChannel(byte pin)

Descripción: Inicializa un canal asignando un pin de salida cada vez que es invocado. Esta función debe ser llamada una o dos veces.

Parámetros:

  • pin: Pin a utilizar para el canal. Como en Geobuino hay un único pin para sonido, siempre debe invocarse con la constante PIN_SPEAKER_1.

Retorno: Nada

Ejemplo:

music.initChannel(PIN_SPEAKER_1); //canal para la primera linea de melodía del Score

music.initChannel(PIN_SPEAKER_1);//canal para la segunda linea de melodía del Score o para la ejecución de tonos

Volver

void closeChannels()

Descripción:Cierra todos los canales inicializados

Parámetros: Ninguno

Retorno: Nada

 

Volver

void playScore(const byte *score)

Descripción:Comienza la ejecución de una partitura (score)

Parámetros:

  • score: Un puntero al arreglo que contiene la partitura. El arreglo debe estar almacenado en la memoria de programa (PROGMEM). Una partitura es una secuencia de comandos que arrancan tonos, detienen tonos o generan un período de espera en un determinado canal de audio.
Retorno: Nada
 
Comandos de una partitura en formato hexadecimal:
 
  • 9c nn: Comienza a ejecutar la nota nn en el canal c (0 o 1). Las notas corresponden los números de la escala cromática MIDI siendo, 60 un Do central, y 69 un La central en 440 Hz. La nota más alta corresponde a 127 (12,544 Hz).
  • 8c: Detiene la nota en el canal c.
  • F0: Indica el final de la partitura.
  • E0: Indica el final de la partitura, arrancando nuevamente desde el principio.
  • Si el bit más significativo del byte es 0, se trata de un comando de espera. Los otros 7 bits y los 8 bits del byte siguiente son interpretados como un entero (big-endian) que indica la cantidad de milisegundos a esperar antes de procesar el siguiente comando.
Es posible generar la secuencias de comandos de una partitura a partir de un archivo MIDI. Para ello se utiliza la herramienta midi2tones, creada por Len Shustek y Scott Allen.
Volver

void stopScore()

Descripción: Si existe una partitura en ejecución, la detiene.

Parámetros: Ninguno

Retorno: Nada

Volver

void playTone(unsigned int frequency, unsigned long duration)

Descripción:Ejecuta un tono de una determinada frecuencia y duración en el segundo canal.

Parámetros:

  • frequency: Frecuencia del tono en hertz (ciclos por segundo).
  • duration: Duración del tono en milisegundos.

Retorno: Nada

 

Volver

boolean playing()

Descripción: Chequea si se está ejecutando una partitura.

Parámetros: Ninguno

Retorno: Valor Booleano

Volver