Arduboy2 Library
Arduboy2 Class Reference

The main functions provided for writing sketches for the Arduboy, including text output. More...

#include <Arduboy2.h>

+ Inheritance diagram for Arduboy2:
+ Collaboration diagram for Arduboy2:

Public Member Functions

void bootLogoText ()
 Display the boot logo sequence using printed text instead of a bitmap. More...
 
virtual void bootLogoExtra ()
 Show the unit name at the bottom of the boot logo screen. More...
 
virtual size_t write (uint8_t)
 Write a single ASCII character at the current text cursor location. More...
 
void drawChar (int16_t x, int16_t y, unsigned char c, uint8_t color, uint8_t bg, uint8_t size)
 Draw a single ASCII character at the specified location in the screen buffer. More...
 
void setCursor (int16_t x, int16_t y)
 Set the location of the text cursor. More...
 
int16_t getCursorX ()
 Get the X coordinate of the current text cursor position. More...
 
int16_t getCursorY ()
 Get the Y coordinate of the current text cursor position. More...
 
void setTextColor (uint8_t color)
 Set the text foreground color. More...
 
uint8_t getTextColor ()
 Get the currently set text foreground color. More...
 
void setTextBackground (uint8_t bg)
 Set the text background color. More...
 
uint8_t getTextBackground ()
 Get the currently set text background color. More...
 
void setTextSize (uint8_t s)
 Set the text character size. More...
 
uint8_t getTextSize ()
 Get the currently set text size. More...
 
void setTextWrap (bool w)
 Set or disable text wrap mode. More...
 
bool getTextWrap ()
 Get the currently set text wrap mode. More...
 
void clear ()
 Clear the display buffer and set the text cursor to location 0, 0.
 
void begin ()
 Initialize the hardware, display the boot logo, provide boot utilities, etc. More...
 
void flashlight ()
 Turn the RGB LED and display fully on to act as a small flashlight/torch. More...
 
void systemButtons ()
 Handle buttons held on startup for system control. More...
 
void bootLogo ()
 Display the boot logo sequence using drawBitmap(). More...
 
void bootLogoCompressed ()
 Display the boot logo sequence using drawCompressed(). More...
 
void bootLogoSpritesSelfMasked ()
 Display the boot logo sequence using Sprites::drawSelfMasked(). More...
 
void bootLogoSpritesOverwrite ()
 Display the boot logo sequence using Sprites::drawOverwrite(). More...
 
void bootLogoSpritesBSelfMasked ()
 Display the boot logo sequence using SpritesB::drawSelfMasked(). More...
 
void bootLogoSpritesBOverwrite ()
 Display the boot logo sequence using SpritesB::drawOverwrite(). More...
 
void bootLogoShell (void(*drawLogo)(int16_t))
 Display the boot logo sequence using the provided function. More...
 
void waitNoButtons ()
 Wait until all buttons have been released. More...
 
void display ()
 Copy the contents of the display buffer to the display. More...
 
void display (bool clear)
 Copy the contents of the display buffer to the display. The display buffer can optionally be cleared. More...
 
uint8_t getPixel (uint8_t x, uint8_t y)
 Returns the state of the given pixel in the screen buffer. More...
 
void drawCircle (int16_t x0, int16_t y0, uint8_t r, uint8_t color=WHITE)
 Draw a circle of a given radius. More...
 
void fillCircle (int16_t x0, int16_t y0, uint8_t r, uint8_t color=WHITE)
 Draw a filled-in circle of a given radius. More...
 
void drawLine (int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint8_t color=WHITE)
 Draw a line between two specified points. More...
 
void drawRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a rectangle of a specified width and height. More...
 
void drawFastVLine (int16_t x, int16_t y, uint8_t h, uint8_t color=WHITE)
 Draw a vertical line. More...
 
void drawFastHLine (int16_t x, int16_t y, uint8_t w, uint8_t color=WHITE)
 Draw a horizontal line. More...
 
void fillRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a filled-in rectangle of a specified width and height. More...
 
void fillScreen (uint8_t color=WHITE)
 Fill the screen buffer with the specified color. More...
 
void drawRoundRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t r, uint8_t color=WHITE)
 Draw a rectangle with rounded corners. More...
 
void fillRoundRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t r, uint8_t color=WHITE)
 Draw a filled-in rectangle with rounded corners. More...
 
void drawTriangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color=WHITE)
 Draw a triangle given the coordinates of each corner. More...
 
void fillTriangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color=WHITE)
 Draw a filled-in triangle given the coordinates of each corner. More...
 
void drawSlowXYBitmap (int16_t x, int16_t y, const uint8_t *bitmap, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a bitmap from a horizontally oriented array in program memory. More...
 
uint8_t * getBuffer ()
 Get a pointer to the display buffer in RAM. More...
 
unsigned long generateRandomSeed ()
 Create a seed suitable for use with a random number generator. More...
 
void initRandomSeed ()
 Seed the random number generator with a random value. More...
 
void setFrameRate (uint8_t rate)
 Set the frame rate used by the frame control functions. More...
 
void setFrameDuration (uint8_t duration)
 Set the frame rate, used by the frame control functions, by giving the duration of each frame. More...
 
bool nextFrame ()
 Indicate that it's time to render the next frame. More...
 
bool nextFrameDEV ()
 Indicate that it's time to render the next frame, and visually indicate if the code is running slower than the desired frame rate. FOR USE DURING DEVELOPMENT More...
 
bool everyXFrames (uint8_t frames)
 Indicate if the specified number of frames has elapsed. More...
 
int cpuLoad ()
 Return the load on the CPU as a percentage. More...
 
bool pressed (uint8_t buttons)
 Test if the specified buttons are pressed. More...
 
bool notPressed (uint8_t buttons)
 Test if the specified buttons are not pressed. More...
 
void pollButtons ()
 Poll the buttons and track their state over time. More...
 
bool justPressed (uint8_t button)
 Check if a button has just been pressed. More...
 
bool justReleased (uint8_t button)
 Check if a button has just been released. More...
 
uint16_t readUnitID ()
 Read the unit ID from system EEPROM. More...
 
void writeUnitID (uint16_t id)
 Write a unit ID to system EEPROM. More...
 
uint8_t readUnitName (char *name)
 Read the unit name from system EEPROM. More...
 
void writeUnitName (char *name)
 Write a unit name to system EEPROM. More...
 
bool readShowBootLogoFlag ()
 Read the "Show Boot Logo" flag in system EEPROM. More...
 
void writeShowBootLogoFlag (bool val)
 Write the "Show Boot Logo" flag in system EEPROM. More...
 
bool readShowUnitNameFlag ()
 Read the "Show Unit Name" flag in system EEPROM. More...
 
void writeShowUnitNameFlag (bool val)
 Write the "Show Unit Name" flag in system EEPROM. More...
 
bool readShowBootLogoLEDsFlag ()
 Read the "Show LEDs with boot logo" flag in system EEPROM. More...
 
void writeShowBootLogoLEDsFlag (bool val)
 Write the "Show LEDs with boot logo" flag in system EEPROM. More...
 

Static Public Member Functions

static void drawPixel (int16_t x, int16_t y, uint8_t color=WHITE)
 Set a single pixel in the display buffer to the specified color. More...
 
static void drawBitmap (int16_t x, int16_t y, const uint8_t *bitmap, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a bitmap from an array in program memory. More...
 
static void drawCompressed (int16_t sx, int16_t sy, const uint8_t *bitmap, uint8_t color=WHITE)
 Draw a bitmap from an array of compressed data. More...
 
static bool collide (Point point, Rect rect)
 Test if a point falls within a rectangle. More...
 
static bool collide (Rect rect1, Rect rect2)
 Test if a rectangle is intersecting with another rectangle. More...
 
static void idle ()
 Idle the CPU to save power. More...
 
static void LCDDataMode ()
 Put the display into data mode. More...
 
static void LCDCommandMode ()
 Put the display into command mode. More...
 
static void SPItransfer (uint8_t data)
 Transfer a byte to the display. More...
 
static void displayOff ()
 Turn the display off. More...
 
static void displayOn ()
 Turn the display on. More...
 
static uint8_t width ()
 Get the width of the display in pixels. More...
 
static uint8_t height ()
 Get the height of the display in pixels. More...
 
static uint8_t buttonsState ()
 Get the current state of all buttons as a bitmask. More...
 
static void paint8Pixels (uint8_t pixels)
 Paint 8 pixels vertically to the display. More...
 
static void paintScreen (const uint8_t *image)
 Paints an entire image directly to the display from program memory. More...
 
static void paintScreen (uint8_t image[], bool clear=false)
 Paints an entire image directly to the display from an array in RAM. More...
 
static void blank ()
 Blank the display screen by setting all pixels off. More...
 
static void invert (bool inverse)
 Invert the entire display or set it back to normal. More...
 
static void allPixelsOn (bool on)
 Turn all display pixels on or display the buffer contents. More...
 
static void flipVertical (bool flipped)
 Flip the display vertically or set it back to normal. More...
 
static void flipHorizontal (bool flipped)
 Flip the display horizontally or set it back to normal. More...
 
static void sendLCDCommand (uint8_t command)
 Send a single command byte to the display. More...
 
static void setRGBled (uint8_t red, uint8_t green, uint8_t blue)
 Set the light output of the RGB LED. More...
 
static void setRGBled (uint8_t color, uint8_t val)
 Set the brightness of one of the RGB LEDs without affecting the others. More...
 
static void freeRGBled ()
 Relinquish analog control of the RGB LED. More...
 
static void digitalWriteRGB (uint8_t red, uint8_t green, uint8_t blue)
 Set the RGB LEDs digitally, to either fully on or fully off. More...
 
static void digitalWriteRGB (uint8_t color, uint8_t val)
 Set one of the RGB LEDs digitally, to either fully on or fully off. More...
 
static void boot ()
 Initialize the Arduboy's hardware. More...
 
static void safeMode ()
 Allow upload when the bootloader "magic number" could be corrupted. More...
 
static void delayShort (uint16_t ms) __attribute__((noinline))
 Delay for the number of milliseconds, specified as a 16 bit value. More...
 
static void exitToBootloader ()
 Exit the sketch and start the bootloader. More...
 

Public Attributes

Arduboy2Audio audio
 An object created to provide audio control functions within this class. More...
 
uint16_t frameCount
 A counter which is incremented once per frame. More...
 

Static Public Attributes

static uint8_t sBuffer [(HEIGHT *WIDTH)/8]
 The display buffer array in RAM. More...
 

Detailed Description

The main functions provided for writing sketches for the Arduboy, including text output.

This class is derived from Arduboy2Base. It provides text output functions in addition to all the functions inherited from Arduboy2Base.

Note
A friend class named Arduboy2Ex is declared by this class. The intention is to allow a sketch to create an Arduboy2Ex class which would have access to the private and protected members of the Arduboy2 class. It is hoped that this may eliminate the need to create an entire local copy of the library, in order to extend the functionality, in most circumstances.
See also
Arduboy2Base

Definition at line 1357 of file Arduboy2.h.

Member Function Documentation

void Arduboy2Core::allPixelsOn ( bool  on)
staticinherited

Turn all display pixels on or display the buffer contents.

Parameters
ontrue turns all pixels on. false displays the contents of the hardware display buffer.

Calling this function with a value of true will override the contents of the hardware display buffer and turn all pixels on. The contents of the hardware buffer will remain unchanged.

Calling this function with a value of false will set the normal state of displaying the contents of the hardware display buffer.

Note
All pixels will be lit even if the display is in inverted mode.
See also
invert()

Definition at line 416 of file Arduboy2Core.cpp.

void Arduboy2Base::begin ( )
inherited

Initialize the hardware, display the boot logo, provide boot utilities, etc.

This function should be called once near the start of the sketch, usually in setup(), before using any other functions in this class. It initializes the display, displays the boot logo, provides "flashlight" and system control features and initializes audio control.

Note
To free up some code space for use by the sketch, boot() can be used instead of begin() to allow the elimination of some of the things that aren't really required, such as displaying the boot logo.
See also
boot()

Definition at line 48 of file Arduboy2.cpp.

void Arduboy2Core::blank ( )
staticinherited

Blank the display screen by setting all pixels off.

All pixels on the screen will be written with a value of 0 to turn them off.

Definition at line 394 of file Arduboy2Core.cpp.

void Arduboy2Core::boot ( )
staticinherited

Initialize the Arduboy's hardware.

This function initializes the display, buttons, etc.

This function is called by begin() so isn't normally called within a sketch. However, in order to free up some code space, by eliminating some of the start up features, it can be called in place of begin(). The functions that begin() would call after boot() can then be called to add back in some of the start up features, if desired. See the README file or documentation on the main page for more details.

See also
Arduboy2Base::begin()

Definition at line 78 of file Arduboy2Core.cpp.

void Arduboy2Base::bootLogo ( )
inherited

Display the boot logo sequence using drawBitmap().

This function is called by begin() and can be called by a sketch after boot().

The Arduboy logo scrolls down from the top of the screen to the center while the RGB LEDs light in sequence.

The bootLogoShell() helper function is used to perform the actual sequence. The documentation for bootLogoShell() provides details on how it operates.

See also
begin() boot() bootLogoShell() Arduboy2::bootLogoText()

Definition at line 120 of file Arduboy2.cpp.

void Arduboy2Base::bootLogoCompressed ( )
inherited

Display the boot logo sequence using drawCompressed().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses drawCompressed().

See also
bootLogo() begin() boot()

Definition at line 130 of file Arduboy2.cpp.

void Arduboy2::bootLogoExtra ( )
virtual

Show the unit name at the bottom of the boot logo screen.

This function is called by bootLogoShell() and bootLogoText().

If a unit name has been saved in system EEPROM, it will be displayed at the bottom of the screen. This function pauses for a short time to allow the name to be seen.

If the SYS_FLAG_UNAME flag in system EEPROM is cleared, this function will return without showing the unit name or pausing.

Note
This function would not normally be called directly from within a sketch itself.
See also
readUnitName() writeUnitName() bootLogo() bootLogoShell() bootLogoText() writeShowUnitNameFlag() begin()

Reimplemented from Arduboy2Base.

Definition at line 1241 of file Arduboy2.cpp.

void Arduboy2Base::bootLogoShell ( void(*)(int16_t)  drawLogo)
inherited

Display the boot logo sequence using the provided function.

Parameters
drawLogoA reference to a function which will draw the boot logo at the given Y position.

This common function executes the sequence to display the boot logo. It is called by bootLogo() and other similar functions which provide it with a reference to a function which will do the actual drawing of the logo.

This function calls bootLogoExtra() after the logo stops scrolling down, which derived classes can implement to add additional information to the logo screen. The Arduboy2 class uses this to display the unit name.

If the RIGHT button is pressed while the logo is scrolling down, the boot logo sequence will be aborted. This can be useful for developers who wish to quickly start testing, or anyone else who is impatient and wants to go straight to the actual sketch.

If the SYS_FLAG_SHOW_LOGO_LEDS flag in system EEPROM is cleared, the RGB LEDs will not be flashed during the logo display sequence.

If the SYS_FLAG_SHOW_LOGO flag in system EEPROM is cleared, this function will return without executing the logo display sequence.

The prototype for the function provided to draw the logo is:

void drawLogo(int16_t y);

The y parameter is the Y offset for the top of the logo. It is expected that the logo will be 16 pixels high and centered horizontally. This will result in the logo stopping in the middle of the screen at the end of the sequence. If the logo height is not 16 pixels, the Y value can be adjusted to compensate.

See also
bootLogo() boot() Arduboy2::bootLogoExtra()

Definition at line 182 of file Arduboy2.cpp.

void Arduboy2Base::bootLogoSpritesBOverwrite ( )
inherited

Display the boot logo sequence using SpritesB::drawOverwrite().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses SpritesB class functions.

See also
bootLogo() begin() boot() SpritesB

Definition at line 170 of file Arduboy2.cpp.

void Arduboy2Base::bootLogoSpritesBSelfMasked ( )
inherited

Display the boot logo sequence using SpritesB::drawSelfMasked().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses SpritesB class functions.

See also
bootLogo() begin() boot() SpritesB

Definition at line 160 of file Arduboy2.cpp.

void Arduboy2Base::bootLogoSpritesOverwrite ( )
inherited

Display the boot logo sequence using Sprites::drawOverwrite().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses Sprites class functions.

See also
bootLogo() begin() boot() Sprites

Definition at line 150 of file Arduboy2.cpp.

void Arduboy2Base::bootLogoSpritesSelfMasked ( )
inherited

Display the boot logo sequence using Sprites::drawSelfMasked().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses Sprites class functions.

See also
bootLogo() begin() boot() Sprites

Definition at line 140 of file Arduboy2.cpp.

void Arduboy2::bootLogoText ( )

Display the boot logo sequence using printed text instead of a bitmap.

This function can be called by a sketch after boot() as an alternative to bootLogo().

The Arduboy logo scrolls down from the top of the screen to the center while the RGB LEDs light in sequence.

This function is the same as bootLogo() except the logo is printed as text instead of being rendered as a bitmap. It can be used to save some code space in a case where the sketch is using the Print class functions to display text. However, the logo will not look as good when printed as text as it does with the bitmap used by bootLogo().

If the RIGHT button is pressed while the logo is scrolling down, the boot logo sequence will be aborted. This can be useful for developers who wish to quickly start testing, or anyone else who is impatient and wants to go straight to the actual sketch.

If the SYS_FLAG_SHOW_LOGO_LEDS flag in system EEPROM is cleared, the RGB LEDs will not be flashed during the logo display sequence.

If the SYS_FLAG_SHOW_LOGO flag in system EEPROM is cleared, this function will return without executing the logo display sequence.

See also
bootLogo() boot() Arduboy2::bootLogoExtra()

Definition at line 1196 of file Arduboy2.cpp.

uint8_t Arduboy2Core::buttonsState ( )
staticinherited

Get the current state of all buttons as a bitmask.

Returns
A bitmask of the state of all the buttons.

The returned mask contains a bit for each button. For any pressed button, its bit will be 1. For released buttons their associated bits will be 0.

The following defined mask values should be used for the buttons:

LEFT_BUTTON, RIGHT_BUTTON, UP_BUTTON, DOWN_BUTTON, A_BUTTON, B_BUTTON

Definition at line 530 of file Arduboy2Core.cpp.

bool Arduboy2Base::collide ( Point  point,
Rect  rect 
)
staticinherited

Test if a point falls within a rectangle.

Parameters
pointA structure describing the location of the point.
rectA structure describing the location and size of the rectangle.
Returns
true if the specified point is within the specified rectangle.

This function is intended to detemine if an object, whose boundaries are are defined by the given rectangle, is in contact with the given point.

See also
Point Rect

Definition at line 1071 of file Arduboy2.cpp.

bool Arduboy2Base::collide ( Rect  rect1,
Rect  rect2 
)
staticinherited

Test if a rectangle is intersecting with another rectangle.

Parameters
rect1,rect2Structures describing the size and locations of the rectangles.
Returns
true if the first rectangle is intersecting the second.

This function is intended to detemine if an object, whose boundaries are are defined by the given rectangle, is in contact with another rectangular object.

See also
Rect

Definition at line 1077 of file Arduboy2.cpp.

int Arduboy2Base::cpuLoad ( )
inherited

Return the load on the CPU as a percentage.

Returns
The load on the CPU as a percentage of the total frame time.

The returned value gives the time spent processing a frame as a percentage the total time allotted for a frame, as determined by the frame rate.

This function normally wouldn't be used in the final program. It is intended for use during program development as an aid in helping with frame timing.

Note
The percentage returned can be higher than 100 if more time is spent processing a frame than the time allotted per frame. This would indicate that the frame rate should be made slower or the frame processing code should be optimized to run faster.
See also
setFrameRate() nextFrame()

Definition at line 291 of file Arduboy2.cpp.

void Arduboy2Core::delayShort ( uint16_t  ms)
staticinherited

Delay for the number of milliseconds, specified as a 16 bit value.

Parameters
msThe delay in milliseconds.

This function works the same as the Arduino delay() function except the provided value is 16 bits long, so the maximum delay allowed is 65535 milliseconds (about 65.5 seconds). Using this function instead of Arduino delay() will save a few bytes of code.

Definition at line 559 of file Arduboy2Core.cpp.

void Arduboy2Core::digitalWriteRGB ( uint8_t  red,
uint8_t  green,
uint8_t  blue 
)
staticinherited

Set the RGB LEDs digitally, to either fully on or fully off.

Parameters
red,green,blueUse value RGB_ON or RGB_OFF to set each LED.

The RGB LED is actually individual red, green and blue LEDs placed very close together in a single package. This 3 parameter version of the function will set each LED either on or off, to set the RGB LED to 7 different colors at their highest brightness or turn it off.

The colors are as follows:

RED LED   GREEN_LED   BLUE_LED   COLOR
-------   ---------  --------    -----
RGB_OFF    RGB_OFF    RGB_OFF    OFF
RGB_OFF    RGB_OFF    RGB_ON     Blue
RGB_OFF    RGB_ON     RGB_OFF    Green
RGB_OFF    RGB_ON     RGB_ON     Cyan
RGB_ON     RGB_OFF    RGB_OFF    Red
RGB_ON     RGB_OFF    RGB_ON     Magenta
RGB_ON     RGB_ON     RGB_OFF    Yellow
RGB_ON     RGB_ON     RGB_ON     White
Note
Using the RGB LED in analog mode will prevent digital control of the LED. To restore the ability to control the LED digitally, use the freeRGBled() function.
Note
Many of the Kickstarter Arduboys were accidentally shipped with the RGB LED installed incorrectly. For these units, the green LED cannot be lit. As long as the green led is set to off, turning on the red LED will actually light the blue LED and turning on the blue LED will actually light the red LED. If the green LED is turned on, none of the LEDs will light.
See also
digitalWriteRGB(uint8_t, uint8_t) setRGBled() freeRGBled()

Definition at line 490 of file Arduboy2Core.cpp.

void Arduboy2Core::digitalWriteRGB ( uint8_t  color,
uint8_t  val 
)
staticinherited

Set one of the RGB LEDs digitally, to either fully on or fully off.

Parameters
colorThe name of the LED to set. The value given should be one of RED_LED, GREEN_LED or BLUE_LED.
valIndicates whether to turn the specified LED on or off. The value given should be RGB_ON or RGB_OFF.

This 2 parameter version of the function will set a single LED within the RGB LED either fully on or fully off. See the description of the 3 parameter version of this function for more details on the RGB LED.

See also
digitalWriteRGB(uint8_t, uint8_t, uint8_t) setRGBled() freeRGBled()

Definition at line 504 of file Arduboy2Core.cpp.

void Arduboy2Base::display ( )
inherited

Copy the contents of the display buffer to the display.

The contents of the display buffer in RAM are copied to the display and will appear on the screen.

See also
display(bool)

Definition at line 1030 of file Arduboy2.cpp.

void Arduboy2Base::display ( bool  clear)
inherited

Copy the contents of the display buffer to the display. The display buffer can optionally be cleared.

Parameters
clearIf true the display buffer will be cleared to zero. The defined value CLEAR_BUFFER should be used instead of true to make it more meaningful.

Operation is the same as calling display() without parameters except additionally the display buffer will be cleared if the parameter evaluates to true. (The defined value CLEAR_BUFFER can be used for this)

Using display(CLEAR_BUFFER) is faster and produces less code than calling display() followed by clear().

See also
display() clear()

Definition at line 1035 of file Arduboy2.cpp.

void Arduboy2Core::displayOff ( )
staticinherited

Turn the display off.

The display will clear and be put into a low power mode. This can be used to extend battery life when a game is paused or when a sketch doesn't require anything to be displayed for a relatively long period of time.

See also
displayOn()

Definition at line 285 of file Arduboy2Core.cpp.

void Arduboy2Core::displayOn ( )
staticinherited

Turn the display on.

Used to power up and reinitialize the display after calling displayOff().

Note
The previous call to displayOff() will have caused the display's buffer contents to be lost. The display will have to be re-painted, which is usually done by calling display().
See also
displayOff()

Definition at line 296 of file Arduboy2Core.cpp.

void Arduboy2Base::drawBitmap ( int16_t  x,
int16_t  y,
const uint8_t *  bitmap,
uint8_t  w,
uint8_t  h,
uint8_t  color = WHITE 
)
staticinherited

Draw a bitmap from an array in program memory.

Parameters
xThe X coordinate of the top left pixel affected by the bitmap.
yThe Y coordinate of the top left pixel affected by the bitmap.
bitmapA pointer to the bitmap array in program memory.
wThe width of the bitmap in pixels.
hThe height of the bitmap in pixels.
colorThe color of pixels for bits set to 1 in the bitmap. If the value is INVERT, bits set to 1 will invert the corresponding pixel. (optional; defaults to WHITE).

Bits set to 1 in the provided bitmap array will have their corresponding pixel set to the specified color. For bits set to 0 in the array, the corresponding pixel will be left unchanged.

Each byte in the array specifies a vertical column of 8 pixels, with the least significant bit at the top.

The array must be located in program memory by using the PROGMEM modifier.

Definition at line 838 of file Arduboy2.cpp.

void Arduboy2::drawChar ( int16_t  x,
int16_t  y,
unsigned char  c,
uint8_t  color,
uint8_t  bg,
uint8_t  size 
)

Draw a single ASCII character at the specified location in the screen buffer.

Parameters
xThe X coordinate, in pixels, for where to draw the character.
yThe Y coordinate, in pixels, for where to draw the character.
cThe ASCII value of the character to be drawn.
colorthe forground color of the character.
bgthe background color of the character.
sizeThe size of the character to draw.

The specified ASCII character is drawn starting at the provided coordinate. The point specified by the X and Y coordinates will be the top left corner of the character.

Note
This is a low level function used by the write() function to draw a character. Although it's available as a public function, it wouldn't normally be used. In most cases the Arduino Print class should be used for writing text.
See also
Print write() setTextColor() setTextBackground() setTextSize()

Definition at line 1296 of file Arduboy2.cpp.

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

Draw a circle of a given radius.

Parameters
x0The X coordinate of the circle's center.
y0The Y coordinate of the circle's center.
rThe radius of the circle in pixels.
colorThe circle's color (optional; defaults to WHITE).

Definition at line 396 of file Arduboy2.cpp.

void Arduboy2Base::drawCompressed ( int16_t  sx,
int16_t  sy,
const uint8_t *  bitmap,
uint8_t  color = WHITE 
)
staticinherited

Draw a bitmap from an array of compressed data.

Parameters
sxThe X coordinate of the top left pixel affected by the bitmap.
syThe Y coordinate of the top left pixel affected by the bitmap.
bitmapA pointer to the compressed bitmap array in program memory.
colorThe color of pixels for bits set to 1 in the bitmap. (optional; defaults to WHITE).

Draw a bitmap starting at the given coordinates from an array that has been compressed using an algorthm implemented by Team A.R.G. For more information see: https://github.com/TEAMarg/drawCompressed https://github.com/TEAMarg/Cabi

Bits set to 1 in the provided bitmap array will have their corresponding pixel set to the specified color. For bits set to 0 in the array, the corresponding pixel will be left unchanged.

The array must be located in program memory by using the PROGMEM modifier.

Definition at line 935 of file Arduboy2.cpp.

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

Draw a horizontal line.

Parameters
xThe X coordinate of the left start point.
yThe Y coordinate of the left start point.
wThe width of the line.
colorThe color of the line (optional; defaults to WHITE).

Definition at line 592 of file Arduboy2.cpp.

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

Draw a vertical line.

Parameters
xThe X coordinate of the upper start point.
yThe Y coordinate of the upper start point.
hThe height of the line.
colorThe color of the line (optional; defaults to WHITE).

Definition at line 582 of file Arduboy2.cpp.

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

Draw a line between two specified points.

Parameters
x0,x1The X coordinates of the line ends.
y0,y1The Y coordinates of the line ends.
colorThe line's color (optional; defaults to WHITE).

Draw a line from the start point to the end point using Bresenham's algorithm. The start and end points can be at any location with respect to the other.

Definition at line 522 of file Arduboy2.cpp.

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

Set a single pixel in the display buffer to the specified color.

Parameters
xThe X coordinate of the pixel.
yThe Y coordinate of the pixel.
colorThe color of the pixel (optional; defaults to WHITE).

The single pixel specified location in the display buffer is set to the specified color. The values WHITE or BLACK can be used for the color. If the color parameter isn't included, the pixel will be set to WHITE.

Definition at line 325 of file Arduboy2.cpp.

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

Draw a rectangle of a specified width and height.

Parameters
xThe X coordinate of the upper left corner.
yThe Y coordinate of the upper left corner.
wThe width of the rectangle.
hThe height of the rectangle.
colorThe color of the pixel (optional; defaults to WHITE).

Definition at line 573 of file Arduboy2.cpp.

void Arduboy2Base::drawRoundRect ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  r,
uint8_t  color = WHITE 
)
inherited

Draw a rectangle with rounded corners.

Parameters
xThe X coordinate of the left edge.
yThe Y coordinate of the top edge.
wThe width of the rectangle.
hThe height of the rectangle.
rThe radius of the semicircles forming the corners.
colorThe color of the rectangle (optional; defaults to WHITE).

Definition at line 701 of file Arduboy2.cpp.

void Arduboy2Base::drawSlowXYBitmap ( int16_t  x,
int16_t  y,
const uint8_t *  bitmap,
uint8_t  w,
uint8_t  h,
uint8_t  color = WHITE 
)
inherited

Draw a bitmap from a horizontally oriented array in program memory.

Parameters
xThe X coordinate of the top left pixel affected by the bitmap.
yThe Y coordinate of the top left pixel affected by the bitmap.
bitmapA pointer to the bitmap array in program memory.
wThe width of the bitmap in pixels.
hThe height of the bitmap in pixels.
colorThe color of pixels for bits set to 1 in the bitmap. (optional; defaults to WHITE).

Bits set to 1 in the provided bitmap array will have their corresponding pixel set to the specified color. For bits set to 0 in the array, the corresponding pixel will be left unchanged.

Each byte in the array specifies a horizontal row of 8 pixels, with the most significant bit at the left end of the row.

The array must be located in program memory by using the PROGMEM modifier.

Note
This function requires a lot of additional CPU power and will draw images slower than drawBitmap(), which uses bitmaps that are stored in a format that allows them to be directly written to the screen. It is recommended you use drawBitmap() when possible.

Definition at line 884 of file Arduboy2.cpp.

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

Draw a triangle given the coordinates of each corner.

Parameters
x0,x1,x2The X coordinates of the corners.
y0,y1,y2The Y coordinates of the corners.
colorThe triangle's color (optional; defaults to WHITE).

A triangle is drawn by specifying each of the three corner locations. The corners can be at any position with respect to the others.

Definition at line 727 of file Arduboy2.cpp.

bool Arduboy2Base::everyXFrames ( uint8_t  frames)
inherited

Indicate if the specified number of frames has elapsed.

Parameters
framesThe desired number of elapsed frames.
Returns
true if the specified number of frames has elapsed.

This function should be called with the same value each time for a given event. It will return true if the given number of frames has elapsed since the previous frame in which it returned true.

For example, if you wanted to fire a shot every 5 frames while the A button is being held down:

if (arduboy.everyXFrames(5)) {
if arduboy.pressed(A_BUTTON) {
fireShot();
}
}
See also
setFrameRate() nextFrame()

Definition at line 245 of file Arduboy2.cpp.

void Arduboy2Core::exitToBootloader ( )
staticinherited

Exit the sketch and start the bootloader.

The sketch will exit and the bootloader will be started in command mode. The effect will be similar to pressing the reset button.

This function is intended to be used to allow uploading a new sketch, when the USB code has been removed to gain more code space. Ideally, the sketch would present a "New Sketch Upload" menu or prompt telling the user to "Press and hold the DOWN button when the procedure to upload a new sketch has been initiated". The sketch would then wait for the DOWN button to be pressed and then call this function.

See also
ARDUBOY_NO_USB

Definition at line 564 of file Arduboy2Core.cpp.

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

Draw a filled-in circle of a given radius.

Parameters
x0The X coordinate of the circle's center.
y0The Y coordinate of the circle's center.
rThe radius of the circle in pixels.
colorThe circle's color (optional; defaults to WHITE).

Definition at line 478 of file Arduboy2.cpp.

void Arduboy2Base::fillRect ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  color = WHITE 
)
inherited

Draw a filled-in rectangle of a specified width and height.

Parameters
xThe X coordinate of the upper left corner.
yThe Y coordinate of the upper left corner.
wThe width of the rectangle.
hThe height of the rectangle.
colorThe color of the pixel (optional; defaults to WHITE).

Definition at line 643 of file Arduboy2.cpp.

void Arduboy2Base::fillRoundRect ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  r,
uint8_t  color = WHITE 
)
inherited

Draw a filled-in rectangle with rounded corners.

Parameters
xThe X coordinate of the left edge.
yThe Y coordinate of the top edge.
wThe width of the rectangle.
hThe height of the rectangle.
rThe radius of the semicircles forming the corners.
colorThe color of the rectangle (optional; defaults to WHITE).

Definition at line 716 of file Arduboy2.cpp.

void Arduboy2Base::fillScreen ( uint8_t  color = WHITE)
inherited

Fill the screen buffer with the specified color.

Parameters
colorThe fill color (optional; defaults to WHITE).

Definition at line 652 of file Arduboy2.cpp.

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

Draw a filled-in triangle given the coordinates of each corner.

Parameters
x0,x1,x2The X coordinates of the corners.
y0,y1,y2The Y coordinates of the corners.
colorThe triangle's color (optional; defaults to WHITE).

A triangle is drawn by specifying each of the three corner locations. The corners can be at any position with respect to the others.

Definition at line 735 of file Arduboy2.cpp.

void Arduboy2Base::flashlight ( )
inherited

Turn the RGB LED and display fully on to act as a small flashlight/torch.

Checks if the UP button is pressed and if so turns the RGB LED and all display pixels fully on. If the UP button is detected, this function does not exit. The Arduboy must be restarted after flashlight mode is used.

This function is called by begin() and can be called by a sketch after boot().

Note

This function also contains code to address a problem with uploading a new sketch, for sketches that interfere with the bootloader "magic number". This problem occurs with certain sketches that use large amounts of RAM. Being in flashlight mode when uploading a new sketch can fix this problem.

Therefore, for sketches that potentially could cause this problem, and use boot() instead of begin(), it is recommended that a call to flashlight() be included after calling boot(). If program space is limited, safeMode() can be used instead of flashlight().

See also
begin() boot() safeMode()

Definition at line 73 of file Arduboy2.cpp.

void Arduboy2Core::flipHorizontal ( bool  flipped)
staticinherited

Flip the display horizontally or set it back to normal.

Parameters
flippedtrue will set horizontal flip mode. false will set normal horizontal orientation.

Calling this function with a value of true will cause the X coordinate to start at the left edge of the display instead of the right, effectively flipping the display horizontally.

Once in horizontal flip mode, it will remain this way until normal horizontal mode is set by calling this function with a value of false.

See also
flipVertical()

Definition at line 428 of file Arduboy2Core.cpp.

void Arduboy2Core::flipVertical ( bool  flipped)
staticinherited

Flip the display vertically or set it back to normal.

Parameters
flippedtrue will set vertical flip mode. false will set normal vertical orientation.

Calling this function with a value of true will cause the Y coordinate to start at the bottom edge of the display instead of the top, effectively flipping the display vertically.

Once in vertical flip mode, it will remain this way until normal vertical mode is set by calling this function with a value of false.

See also
flipHorizontal()

Definition at line 422 of file Arduboy2Core.cpp.

void Arduboy2Core::freeRGBled ( )
staticinherited

Relinquish analog control of the RGB LED.

Using the RGB LED in analog mode prevents further use of the LED in digital mode. This function will restore the pins used for the LED, so it can be used in digital mode.

See also
digitalWriteRGB() setRGBled()

Definition at line 481 of file Arduboy2Core.cpp.

unsigned long Arduboy2Base::generateRandomSeed ( )
inherited

Create a seed suitable for use with a random number generator.

Returns
A random value that can be used to seed a random number generator.

The returned value will be a random value derived from entropy from an ADC reading of a floating pin combined with the microseconds since boot.

This method is still most effective when called after a semi-random time, such as after a user hits a button to start a game or other semi-random event.

See also
initRandomSeed()

Definition at line 296 of file Arduboy2.cpp.

uint8_t * Arduboy2Base::getBuffer ( )
inherited

Get a pointer to the display buffer in RAM.

Returns
A pointer to the display buffer array in RAM.

The location of the display buffer in RAM, which is displayed using display(), can be gotten using this function. The buffer can then be read and directly manipulated.

Note
The display buffer array, sBuffer, is public. A sketch can access it directly. Doing so may be more efficient than accessing it via the pointer returned by getBuffer().
See also
sBuffer

Definition at line 1040 of file Arduboy2.cpp.

int16_t Arduboy2::getCursorX ( )

Get the X coordinate of the current text cursor position.

Returns
The X coordinate of the current text cursor position.

The X coordinate returned is a pixel location with 0 indicating the leftmost column.

See also
getCursorY() setCursor()

Definition at line 1340 of file Arduboy2.cpp.

int16_t Arduboy2::getCursorY ( )

Get the Y coordinate of the current text cursor position.

Returns
The Y coordinate of the current text cursor position.

The Y coordinate returned is a pixel location with 0 indicating the topmost row.

See also
getCursorX() setCursor()

Definition at line 1345 of file Arduboy2.cpp.

uint8_t Arduboy2Base::getPixel ( uint8_t  x,
uint8_t  y 
)
inherited

Returns the state of the given pixel in the screen buffer.

Parameters
xThe X coordinate of the pixel.
yThe Y coordinate of the pixel.
Returns
WHITE if the pixel is on or BLACK if the pixel is off.

Definition at line 389 of file Arduboy2.cpp.

uint8_t Arduboy2::getTextBackground ( )

Get the currently set text background color.

Returns
The background color that will be used to display any following text.
See also
setTextBackground()

Definition at line 1365 of file Arduboy2.cpp.

uint8_t Arduboy2::getTextColor ( )

Get the currently set text foreground color.

Returns
The color that will be used to display any following text.
See also
setTextColor()

Definition at line 1355 of file Arduboy2.cpp.

uint8_t Arduboy2::getTextSize ( )

Get the currently set text size.

Returns
The size that will be used for any following text.
See also
setTextSize()

Definition at line 1376 of file Arduboy2.cpp.

bool Arduboy2::getTextWrap ( )

Get the currently set text wrap mode.

Returns
true if text wrapping is on, false if wrapping is off.
See also
setTextWrap()

Definition at line 1386 of file Arduboy2.cpp.

uint8_t Arduboy2Core::height ( )
staticinherited

Get the height of the display in pixels.

Returns
The height of the display in pixels.
Note
In most cases, the defined value HEIGHT would be better to use instead of this function.

Definition at line 303 of file Arduboy2Core.cpp.

void Arduboy2Core::idle ( )
staticinherited

Idle the CPU to save power.

This puts the CPU in idle sleep mode. You should call this as often as you can for the best power savings. The timer 0 overflow interrupt will wake up the chip every 1ms, so even at 60 FPS a well written app should be able to sleep maybe half the time in between rendering it's own frames.

Definition at line 268 of file Arduboy2Core.cpp.

void Arduboy2Base::initRandomSeed ( )
inherited

Seed the random number generator with a random value.

The Arduino random number generator is seeded with a random value derived from entropy from an ADC reading of a floating pin combined with the microseconds since boot. The seed value is provided by calling the generateRandomSeed() function.

This method is still most effective when called after a semi-random time, such as after a user hits a button to start a game or other semi-random event.

See also
generateRandomSeed()

Definition at line 313 of file Arduboy2.cpp.

void Arduboy2Core::invert ( bool  inverse)
staticinherited

Invert the entire display or set it back to normal.

Parameters
inversetrue will invert the display. false will set the display to no-inverted.

Calling this function with a value of true will set the display to inverted mode. A pixel with a value of 0 will be on and a pixel set to 1 will be off.

Once in inverted mode, the display will remain this way until it is set back to non-inverted mode by calling this function with false.

Definition at line 409 of file Arduboy2Core.cpp.

bool Arduboy2Base::justPressed ( uint8_t  button)
inherited

Check if a button has just been pressed.

Parameters
buttonThe button to test for. Only one button should be specified.
Returns
true if the specified button has just been pressed.

Return true if the given button was pressed between the latest call to pollButtons() and previous call to pollButtons(). If the button has been held down over multiple polls, this function will return false.

There is no need to check for the release of the button since it must have been released for this function to return true when pressed again.

This function should only be used to test a single button.

See also
pollButtons() justReleased()

Definition at line 1061 of file Arduboy2.cpp.

bool Arduboy2Base::justReleased ( uint8_t  button)
inherited

Check if a button has just been released.

Parameters
buttonThe button to test for. Only one button should be specified.
Returns
true if the specified button has just been released.

Return true if the given button, having previously been pressed, was released between the latest call to pollButtons() and previous call to pollButtons(). If the button has remained released over multiple polls, this function will return false.

There is no need to check for the button having been pressed since it must have been previously pressed for this function to return true upon release.

This function should only be used to test a single button.

Note
There aren't many cases where this function would be needed. Wanting to know if a button has been released, without knowing when it was pressed, is uncommon.
See also
pollButtons() justPressed()

Definition at line 1066 of file Arduboy2.cpp.

void Arduboy2Core::LCDCommandMode ( )
staticinherited

Put the display into command mode.

When placed in command mode, data that is sent to the display will be treated as commands.

See the SSD1306 controller and OLED display documents for available commands and command sequences.

Links:

Note
This is a low level function that is not intended for general use in a sketch. It has been made public and documented for use by derived classes.
See also
LCDDataMode() sendLCDCommand() SPItransfer()

Definition at line 222 of file Arduboy2Core.cpp.

void Arduboy2Core::LCDDataMode ( )
staticinherited

Put the display into data mode.

When placed in data mode, data that is sent to the display will be considered as data to be displayed.

Note
This is a low level function that is not intended for general use in a sketch. It has been made public and documented for use by derived classes.
See also
LCDCommandMode() SPItransfer()

Definition at line 217 of file Arduboy2Core.cpp.

bool Arduboy2Base::nextFrame ( )
inherited

Indicate that it's time to render the next frame.

Returns
true if it's time for the next frame.

When this function returns true, the amount of time has elapsed to display the next frame, as specified by setFrameRate().

This function will normally be called at the start of the rendering loop which would wait for true to be returned before rendering and displaying the next frame.

example:

void loop() {
if (!arduboy.nextFrame()) {
return; // go back to the start of the loop
}
// render and display the next frame
}
See also
setFrameRate() setFrameDuration() nextFrameDEV()

Definition at line 250 of file Arduboy2.cpp.

bool Arduboy2Base::nextFrameDEV ( )
inherited

Indicate that it's time to render the next frame, and visually indicate if the code is running slower than the desired frame rate. FOR USE DURING DEVELOPMENT

Returns
true if it's time for the next frame.

This function is intended to be used in place of nextFrame() during the development of a sketch. It does the same thing as nextFrame() but additionally will light the yellow TX LED (at the bottom, to the left of the USB connector) whenever a frame takes longer to generate than the time allotted per frame, as determined by the setFrameRate() function.

Therefore, whenever the TX LED comes on (while not communicating over USB), it indicates that the sketch is running slower than the desired rate set by setFrameRate(). In this case the developer may wish to set a slower frame rate, or reduce or optimize the code for such frames.

Note
Once a sketch is ready for release, it would be expected that nextFrameDEV() calls be restored to nextFrame().
See also
nextFrame() cpuLoad() setFrameRate()

Definition at line 278 of file Arduboy2.cpp.

bool Arduboy2Base::notPressed ( uint8_t  buttons)
inherited

Test if the specified buttons are not pressed.

Parameters
buttonsA bit mask indicating which buttons to test. (Can be a single button)
Returns
true if all buttons in the provided mask are currently released.

Read the state of the buttons and return true if all the buttons in the specified mask are currently released.

Example: if (notPressed(UP_BUTTON))

Note
This function does not perform any button debouncing.

Definition at line 1050 of file Arduboy2.cpp.

void Arduboy2Core::paint8Pixels ( uint8_t  pixels)
staticinherited

Paint 8 pixels vertically to the display.

Parameters
pixelsA byte whose bits specify a vertical column of 8 pixels.

A byte representing a vertical column of 8 pixels is written to the display at the current page and column address. The address is then incremented. The page/column address will wrap to the start of the display (the top left) when it increments past the end (lower right).

The least significant bit represents the top pixel in the column. A bit set to 1 is lit, 0 is unlit.

Example:

X = lit pixels, . = unlit pixels

blank()                          paint8Pixels() 0xFF, 0, 0xF0, 0, 0x0F
v TOP LEFT corner (8x9)          v TOP LEFT corner
. . . . . . . . (page 1)         X . . . X . . . (page 1)
. . . . . . . .                  X . . . X . . .
. . . . . . . .                  X . . . X . . .
. . . . . . . .                  X . . . X . . .
. . . . . . . .                  X . X . . . . .
. . . . . . . .                  X . X . . . . .
. . . . . . . .                  X . X . . . . .
. . . . . . . . (end of page 1)  X . X . . . . . (end of page 1)
. . . . . . . . (page 2)         . . . . . . . . (page 2)

Definition at line 308 of file Arduboy2Core.cpp.

void Arduboy2Core::paintScreen ( const uint8_t *  image)
staticinherited

Paints an entire image directly to the display from program memory.

Parameters
imageA byte array in program memory representing the entire contents of the display.

The contents of the specified array in program memory is written to the display. Each byte in the array represents a vertical column of 8 pixels with the least significant bit at the top. The bytes are written starting at the top left, progressing horizontally and wrapping at the end of each row, to the bottom right. The size of the array must exactly match the number of pixels in the entire display.

See also
paint8Pixels()

Definition at line 313 of file Arduboy2Core.cpp.

void Arduboy2Core::paintScreen ( uint8_t  image[],
bool  clear = false 
)
staticinherited

Paints an entire image directly to the display from an array in RAM.

Parameters
imageA byte array in RAM representing the entire contents of the display.
clearIf true the array in RAM will be cleared to zeros upon return from this function. If false the RAM buffer will remain unchanged. (optional; defaults to false)

The contents of the specified array in RAM is written to the display. Each byte in the array represents a vertical column of 8 pixels with the least significant bit at the top. The bytes are written starting at the top left, progressing horizontally and wrapping at the end of each row, to the bottom right. The size of the array must exactly match the number of pixels in the entire display.

If parameter clear is set to true the RAM array will be cleared to zeros after its contents are written to the display.

See also
paint8Pixels()

Definition at line 327 of file Arduboy2Core.cpp.

void Arduboy2Base::pollButtons ( )
inherited

Poll the buttons and track their state over time.

Read and save the current state of the buttons and also keep track of the button state when this function was previouly called. These states are used by the justPressed() and justReleased() functions to determine if a button has changed state between now and the previous call to pollButtons().

This function should be called once at the start of each new frame.

The justPressed() and justReleased() functions rely on this function.

example:

void loop() {
if (!arduboy.nextFrame()) {
return;
}
arduboy.pollButtons();
// use justPressed() as necessary to determine if a button was just pressed
Note
As long as the elapsed time between calls to this function is long enough, buttons will be naturally debounced. Calling it once per frame at a frame rate of 60 or lower (or possibly somewhat higher), should be sufficient.
See also
justPressed() justReleased()

Definition at line 1055 of file Arduboy2.cpp.

bool Arduboy2Base::pressed ( uint8_t  buttons)
inherited

Test if the specified buttons are pressed.

Parameters
buttonsA bit mask indicating which buttons to test. (Can be a single button)
Returns
true if all buttons in the provided mask are currently pressed.

Read the state of the buttons and return true if all the buttons in the specified mask are being pressed.

Example: if (pressed(LEFT_BUTTON + A_BUTTON))

Note
This function does not perform any button debouncing.

Definition at line 1045 of file Arduboy2.cpp.

bool Arduboy2Base::readShowBootLogoFlag ( )
inherited

Read the "Show Boot Logo" flag in system EEPROM.

Returns
true if the flag is set to indicate that the boot logo sequence should be displayed. false if the flag is set to not display the boot logo sequence.

The "Show Boot Logo" flag is used to determine whether the system boot logo sequence is to be displayed when the system boots up. This function returns the value of this flag.

See also
writeShowBootLogoFlag() bootLogo()

Definition at line 1133 of file Arduboy2.cpp.

bool Arduboy2Base::readShowBootLogoLEDsFlag ( )
inherited

Read the "Show LEDs with boot logo" flag in system EEPROM.

Returns
true if the flag is set to indicate that the RGB LEDs should be flashed. false if the flag is set to leave the LEDs off.

The "Show LEDs with boot logo" flag is used to determine whether the RGB LEDs should be flashed in sequence while the boot logo is being displayed. This function returns the value of this flag.

See also
writeShowBootLogoLEDsFlag()

Definition at line 1159 of file Arduboy2.cpp.

bool Arduboy2Base::readShowUnitNameFlag ( )
inherited

Read the "Show Unit Name" flag in system EEPROM.

Returns
true if the flag is set to indicate that the unit name should be displayed. false if the flag is set to not display the unit name.

The "Show Unit Name" flag is used to determine whether the system unit name is to be displayed at the end of the boot logo sequence. This function returns the value of this flag.

See also
writeShowUnitNameFlag() writeUnitName() readUnitName() Arduboy2::bootLogoExtra()

Definition at line 1146 of file Arduboy2.cpp.

uint16_t Arduboy2Base::readUnitID ( )
inherited

Read the unit ID from system EEPROM.

Returns
The value of the unit ID stored in system EEPROM.

This function reads the unit ID that has been set in system EEPROM. The ID can be any value. It is intended to allow different units to be uniquely identified.

See also
writeUnitID() readUnitName()

Definition at line 1085 of file Arduboy2.cpp.

uint8_t Arduboy2Base::readUnitName ( char *  name)
inherited

Read the unit name from system EEPROM.

Parameters
nameA pointer to a string array variable where the unit name will be placed. The string will be up to 6 characters and terminated with a null (0x00) character, so the provided array must be at least 7 bytes long.
Returns
The length of the string (0-6).

This function reads the unit name that has been set in system EEPROM. The name is in ASCII and can contain any values except 0xFF and the null (0x00) terminator value.

The name can be used for any purpose. It could identify the owner or give the unit itself a nickname. A sketch could use it to automatically fill in a name or initials in a high score table, or display it as the "player" when the opponent is the computer.

Note
Sketches can use the defined value ARDUBOY_UNIT_NAME_LEN instead of hard coding a 6 when working with the unit name. For example, to allocate a buffer and read the unit name into it:
// Buffer for maximum name length plus the terminator
char unitName[ARDUBOY_UNIT_NAME_LEN + 1];
// The actual name length
byte unitNameLength;
unitNameLength = arduboy.readUnitName(unitName);
See also
writeUnitName() readUnitID() Arduboy2::bootLogoExtra()

Definition at line 1097 of file Arduboy2.cpp.

void Arduboy2Core::safeMode ( )
staticinherited

Allow upload when the bootloader "magic number" could be corrupted.

If the UP button is held when this function is entered, the RGB LED will be lit and timer 0 will be disabled, then the sketch will remain in a tight loop. This is to address a problem with uploading a new sketch, for sketches that interfere with the bootloader "magic number". The problem occurs with certain sketches that use large amounts of RAM.

This function should be called after boot() in sketches that potentially could cause the problem.

It is intended to replace the flashlight() function when more program space is required. If possible, it is more desirable to use flashlight(), so that the actual flashlight feature isn't lost.

See also
Arduboy2Base::flashlight() boot()

Definition at line 249 of file Arduboy2Core.cpp.

void Arduboy2Core::sendLCDCommand ( uint8_t  command)
staticinherited

Send a single command byte to the display.

Parameters
commandThe command byte to send to the display.

The display will be set to command mode then the specified command byte will be sent. The display will then be set to data mode. Multi-byte commands can be sent by calling this function multiple times.

Note
Sending improper commands to the display can place it into invalid or unexpected states, possibly even causing physical damage.

Definition at line 400 of file Arduboy2Core.cpp.

void Arduboy2::setCursor ( int16_t  x,
int16_t  y 
)

Set the location of the text cursor.

Parameters
xThe X coordinate, in pixels, for the new location of the text cursor.
yThe Y coordinate, in pixels, for the new location of the text cursor.

The location of the text cursor is set the the specified coordinates. The coordinates are in pixels. Since the coordinates can specify any pixel location, the text does not have to be placed on specific rows. As with all drawing functions, location 0, 0 is the top left corner of the display. The cursor location will be the top left corner of the next character written.

See also
getCursorX() getCursorY()

Definition at line 1334 of file Arduboy2.cpp.

void Arduboy2Base::setFrameDuration ( uint8_t  duration)
inherited

Set the frame rate, used by the frame control functions, by giving the duration of each frame.

Parameters
durationThe desired duration of each frame in milliseconds.

Set the frame rate by specifying the duration of each frame in milliseconds. This is used by nextFrame() to update frames at a given rate. If this function or setFrameRate() isn't used, the default will be 16ms per frame.

Normally, the frame rate would be set to the desired value once, at the start of the game, but it can be changed at any time to alter the frame update rate.

See also
nextFrame() setFrameRate()

Definition at line 240 of file Arduboy2.cpp.

void Arduboy2Base::setFrameRate ( uint8_t  rate)
inherited

Set the frame rate used by the frame control functions.

Parameters
rateThe desired frame rate in frames per second.

Set the frame rate, in frames per second, used by nextFrame() to update frames at a given rate. If this function or setFrameDuration() isn't used, the default rate will be 60 (actually 62.5, see note below).

Normally, the frame rate would be set to the desired value once, at the start of the game, but it can be changed at any time to alter the frame update rate.

Note

The given rate is internally converted to a frame duration in milliseconds, rounded down to the nearest integer. Therefore, the actual rate will be equal to or higher than the rate given.

For example, 60 FPS would be 16.67ms per frame. This will be rounded down to 16ms, giving an actual frame rate of 62.5 FPS.

See also
nextFrame() setFrameDuration()

Definition at line 235 of file Arduboy2.cpp.

void Arduboy2Core::setRGBled ( uint8_t  red,
uint8_t  green,
uint8_t  blue 
)
staticinherited

Set the light output of the RGB LED.

Parameters
red,green,blueThe brightness value for each LED.

The RGB LED is actually individual red, green and blue LEDs placed very close together in a single package. By setting the brightness of each LED, the RGB LED can show various colors and intensities. The brightness of each LED can be set to a value from 0 (fully off) to 255 (fully on).

Note
Certain libraries that take control of the hardware timers may interfere with the ability of this function to properly control the RGB LED. ArduboyPlaytune is one such library known to do this. The digitalWriteRGB() function will still work properly in this case.
Note
Many of the Kickstarter Arduboys were accidentally shipped with the RGB LED installed incorrectly. For these units, the green LED cannot be lit. As long as the green led is set to off, setting the red LED will actually control the blue LED and setting the blue LED will actually control the red LED. If the green LED is turned fully on, none of the LEDs will light.
See also
setRGBled(uint8_t, uint8_t) digitalWriteRGB() freeRGBled()

Definition at line 435 of file Arduboy2Core.cpp.

void Arduboy2Core::setRGBled ( uint8_t  color,
uint8_t  val 
)
staticinherited

Set the brightness of one of the RGB LEDs without affecting the others.

Parameters
colorThe name of the LED to set. The value given should be one of RED_LED, GREEN_LED or BLUE_LED.
valThe brightness value for the LED, from 0 to 255.
Note
In order to use this function, the 3 parameter version must first be called at least once, in order to initialize the hardware.

This 2 parameter version of the function will set the brightness of a single LED within the RGB LED without affecting the current brightness of the other two. See the description of the 3 parameter version of this function for more details on the RGB LED.

See also
setRGBled(uint8_t, uint8_t, uint8_t) digitalWriteRGB() freeRGBled()

Definition at line 457 of file Arduboy2Core.cpp.

void Arduboy2::setTextBackground ( uint8_t  bg)

Set the text background color.

Parameters
bgThe background color to be used for following text.
See also
setTextColor() getTextBackground()

Definition at line 1360 of file Arduboy2.cpp.

void Arduboy2::setTextColor ( uint8_t  color)

Set the text foreground color.

Parameters
colorThe color to be used for following text.
See also
setTextBackground() getTextColor()

Definition at line 1350 of file Arduboy2.cpp.

void Arduboy2::setTextSize ( uint8_t  s)

Set the text character size.

Parameters
sThe text size multiplier. Must be 1 or higher.

Setting a text size of 1 will result in standard size characters which occupy 6x8 pixels (the result of 5x7 characters with spacing on the right and bottom edges).

The value specified is a multiplier. A value of 2 will double the size so they will occupy 12x16 pixels. A value of 3 will result in 18x24, etc.

See also
getTextSize()

Definition at line 1370 of file Arduboy2.cpp.

void Arduboy2::setTextWrap ( bool  w)

Set or disable text wrap mode.

Parameters
wtrue enables text wrap mode. false disables it.

Text wrap mode is enabled by specifying true. In wrap mode, the text cursor will be moved to the start of the next line (based on the current text size) if the following character wouldn't fit entirely at the end of the current line.

If wrap mode is disabled, characters will continue to be written to the same line. A character at the right edge of the screen may only be partially displayed and additional characters will be off screen.

See also
getTextWrap()

Definition at line 1381 of file Arduboy2.cpp.

void Arduboy2Core::SPItransfer ( uint8_t  data)
staticinherited

Transfer a byte to the display.

Parameters
dataThe byte to be sent to the display.

Transfer one byte to the display over the SPI port and wait for the transfer to complete. The byte will either be interpreted as a command or as data to be placed on the screen, depending on the command/data mode.

See also
LCDDataMode() LCDCommandMode() sendLCDCommand()

Definition at line 236 of file Arduboy2Core.cpp.

void Arduboy2Base::systemButtons ( )
inherited

Handle buttons held on startup for system control.

This function is called by begin() and can be called by a sketch after boot().

Hold the B button when booting to enter system control mode. The B button must be held continuously to remain in this mode. Then, pressing other buttons will perform system control functions:

  • UP: Set "sound enabled" in EEPROM
  • DOWN: Set "sound disabled" (mute) in EEPROM
See also
begin() boot()

Definition at line 94 of file Arduboy2.cpp.

void Arduboy2Base::waitNoButtons ( )
inherited

Wait until all buttons have been released.

This function is called by begin() and can be called by a sketch after boot().

It won't return unless no buttons are being pressed. A short delay is performed each time before testing the state of the buttons to do a simple button debounce.

This function is called at the end of begin() to make sure no buttons used to perform system start up actions are still being pressed, to prevent them from erroneously being detected by the sketch code itself.

See also
begin() boot()

Definition at line 227 of file Arduboy2.cpp.

uint8_t Arduboy2Core::width ( )
staticinherited

Get the width of the display in pixels.

Returns
The width of the display in pixels.
Note
In most cases, the defined value WIDTH would be better to use instead of this function.

Definition at line 301 of file Arduboy2Core.cpp.

size_t Arduboy2::write ( uint8_t  c)
virtual

Write a single ASCII character at the current text cursor location.

Parameters
cThe ASCII value of the character to be written.
Returns
The number of characters written (will always be 1).

This is the Arduboy implemetation of the Arduino virtual write() function. The single ASCII character specified is written to the the screen buffer at the current text cursor. The text cursor is then moved to the next character position in the screen buffer. This new cursor position will depend on the current text size and possibly the current wrap mode.

Two special characters are handled:

  • The newline character \n. This will move the text cursor to the start of the next line based on the current text size.
  • The carriage return character \r. This character will be ignored.
Note
This function is rather low level and, although it's available as a public function, it wouldn't normally be used. In most cases the Arduino Print class should be used for writing text.
See also
Print setTextSize() setTextWrap()

Definition at line 1270 of file Arduboy2.cpp.

void Arduboy2Base::writeShowBootLogoFlag ( bool  val)
inherited

Write the "Show Boot Logo" flag in system EEPROM.

Parameters
valIf true the flag is set to indicate that the boot logo sequence should be displayed. If false the flag is set to not display the boot logo sequence.

The "Show Boot Logo" flag is used to determine whether the system boot logo sequence is to be displayed when the system boots up. This function allows the flag to be saved with the desired value.

See also
readShowBootLogoFlag() bootLogo()

Definition at line 1138 of file Arduboy2.cpp.

void Arduboy2Base::writeShowBootLogoLEDsFlag ( bool  val)
inherited

Write the "Show LEDs with boot logo" flag in system EEPROM.

Parameters
valIf true the flag is set to indicate that the RGB LEDs should be flashed. If false the flag is set to leave the LEDs off.

The "Show LEDs with boot logo" flag is used to determine whether the RGB LEDs should be flashed in sequence while the boot logo is being displayed. This function allows the flag to be saved with the desired value.

See also
readShowBootLogoLEDsFlag()

Definition at line 1164 of file Arduboy2.cpp.

void Arduboy2Base::writeShowUnitNameFlag ( bool  val)
inherited

Write the "Show Unit Name" flag in system EEPROM.

Parameters
valIf true the flag is set to indicate that the unit name should be displayed. If false the flag is set to not display the unit name.

The "Show Unit Name" flag is used to determine whether the system unit name is to be displayed at the end of the boot logo sequence. This function allows the flag to be saved with the desired value.

See also
readShowUnitNameFlag() writeUnitName() readUnitName() Arduboy2::bootLogoExtra()

Definition at line 1151 of file Arduboy2.cpp.

void Arduboy2Base::writeUnitID ( uint16_t  id)
inherited

Write a unit ID to system EEPROM.

Parameters
idThe value of the unit ID to be stored in system EEPROM.

This function writes a unit ID to a reserved location in system EEPROM. The ID can be any value. It is intended to allow different units to be uniquely identified.

See also
readUnitID() writeUnitName()

Definition at line 1091 of file Arduboy2.cpp.

void Arduboy2Base::writeUnitName ( char *  name)
inherited

Write a unit name to system EEPROM.

Parameters
nameA pointer to a string array variable containing the unit name to be saved. The string can be up to 6 characters and must be terminated with a null (0x00) character. It can contain any values except 0xFF.

This function writes a unit name to a reserved area in system EEPROM. The name is in ASCII and can contain any values except 0xFF and the null (0x00) terminator value. The newline character (LF, \n, 0x0A) and carriage return character (CR, \r, 0x0D) should also be avoided.

The name can be used for any purpose. It could identify the owner or give the unit itself a nickname. A sketch could use it to automatically fill in a name or initials in a high score table, or display it as the "player" when the opponent is the computer.

Note
Sketches can use the defined value ARDUBOY_UNIT_NAME_LEN instead of hard coding a 6 when working with the unit name.
See also
readUnitName() writeUnitID() Arduboy2::bootLogoExtra()

Definition at line 1117 of file Arduboy2.cpp.

Member Data Documentation

Arduboy2Audio Arduboy2Base::audio
inherited

An object created to provide audio control functions within this class.

This object is created to eliminate the need for a sketch to create an Arduboy2Audio class object itself.

See also
Arduboy2Audio

Definition at line 218 of file Arduboy2.h.

uint16_t Arduboy2Base::frameCount
inherited

A counter which is incremented once per frame.

This counter is incremented once per frame when using the nextFrame() function. It will wrap to zero when it reaches its maximum value.

It could be used to have an event occur for a given number of frames, or a given number of frames later, in a way that wouldn't be quantized the way that using everyXFrames() might.

example:

// move for 10 frames when right button is pressed, if not already moving
if (!moving) {
if (arduboy.justPressed(RIGHT_BUTTON)) {
endMoving = arduboy.frameCount + 10;
moving = true;
}
} else {
movePlayer();
if (arduboy.frameCount == endMoving) {
moving = false;
}
}

This counter could also be used to determine the number of frames that have elapsed between events but the possibility of the counter wrapping would have to be accounted for.

See also
nextFrame() everyXFrames()

Definition at line 1296 of file Arduboy2.h.

uint8_t Arduboy2Base::sBuffer
staticinherited

The display buffer array in RAM.

The display buffer (also known as the screen buffer) contains an image bitmap of the desired contents of the display, which is written to the display using the display() function. The drawing functions of this library manipulate the contents of the display buffer. A sketch can also access the display buffer directly.

See also
getBuffer()

Definition at line 1310 of file Arduboy2.h.


The documentation for this class was generated from the following files: