Arduboy2 - The now recommended alternative to the Arduboy Library


(Scott) #22

Maybe it would make more sense if the library and class were named ArduboyAPI2 ?
But also consider that ArduboyAPI2 might be harder to remember than just Arduboy2, especially for those who don’t know what API stands for.

I’m open to changing it, though.


(Tomi) #23

I think ArduboyLib2 would be a lot better than ArduboyAPI2, and this is from a person that knows what API stands for. API sounds more like there will be more than one of these libraries.


(Andrew Dent) #24

Deja Vu! We’ve ended back in the same recursive loop of the last thread :slight_smile:
As I’ve said repeatedly: the legacy of existing code is tiny. Rip it off like a Bandaid, break the API. Keep the current Arduboy Lib as nothing Major has changed- really! No one will care (sorry @MLXXXp!). No one is doing decent audio yet anyway… Then build from 1.2. and with 100+ developers locking down the API seems reasonable .

  • or -
    Actually do something major to justify this new Lib. Like split into two separate flavours: e.g. ‘WiseOwl’ (well commented and full featured C lib for education), ‘SwiftEagle’ (ASM optimised for speed and size).

Ciao :wink:


(Art McBain) #25

Hmm. Point. I’d forgotten about the ISR for the tunes stuff. Plus it was broken out for potential license reasons, wasn’t it?

At the very least though even if we do move to an Arduboy2 library, does the rest of my post contain any validity? (The parts about going to a lean core and using more wrapper classes.) It would in theory help lengthen the ability to stay using the Arduboy2 library before needing an Arduboy3, assuming we didn’t need to jettison any more ISRs. However if we kept such things to a minimum in the core and left it to other libraries, like ArduboyTunes, then that’d be much less of an issue.


(Scott) #26

Possibly, but it’s not something I’m thinking about. My Arduboy2 library is simply meant to quickly get something out there that is as close as possible to Arduboy API V1 but solves the issues that are described in my initial post in this topic.

The code currently on the master branch of the Arduboy Library, being referred to as V1.2, which I forked from, has been sitting in a mostly completed state for about 4 months, mainly waiting on the decision “Should we release this and break existing sketches which use the things that have changed and are no longer compatible, forcing these sketches to need updating?”.

Meanwhile, all this time developers have been asking and wishing for ways to make more code space available for their sketches. Arduboy2 addresses this, and a few other things, without having to deal with the issue of broken sketches because we can now leave the Arduboy library at API V1 and it can happily coexist in the IDE allongside Arduboy2.

Do you now want to spend more time, of an unknown duration, reworking Arduboy2 as you’ve suggested, while developers still keep asking how they can make more code space available for their sketches, and aren’t able to take advantage of any of the new features currently in Arduboy2? Why not accept Arduboy2 as is, and then continue to work on your proposals without pressure, eventually to be released as Arduboy API V3?


(Scott) #27

And how does ArduboyLib2 not sound like there will be more than one of these libraries?

The bottom line is, no matter what it’s called, it’s likely to be confusing to some people. That being the case, Arduboy2 is the simplest and easiest to remember, and easiest to change from Arduboy.

Experienced developers will read the second paragraph of the README.md file, and other places where it’s described, and then understand the reason for the name.

Beginners will use examples, templates, tutorials and help from others, which will tell them to use Arduboy2 and they probably won’t care why.


(Pharap) #28

I’m going to be branded a heretic and a lunatic for even joking about this:

// Disclaimer: I have no idea if this would actually compile
// Non-compiling base template
template < int versionID > class Arduboy;
// Version 1
template <> class ArduboyImpl<1> { /* ... */ };
// Abuse private inheritance and method hiding to share behaviour
template <> class ArduboyImpl<2> : ArduboyImpl<1> { /* ... */ }; 

#define Version 1
// Alternatively constexpr static const int Version = 1;

using Arduboy = ArduboyImpl<Version>;

Templates, son.


(Scott) #29

Yes, I’ve considered that, but it’s still going to require a change to existing sketches, which is what having a new separate library attempts to avoid. As far as I see it, it really doesn’t gain you much over just providing another library whenever the API changes.

After this version, I don’t think the API is likely to change in a way that breaks backwards compatibility, anyway, since all the problems causing unused code to be included, and interrupts being owned, have been resolved. From this point forward we can just add new functions and features, without changing the existing ones.

Also, the development going on in the original Arduboy library seems to be leaning towards it becoming almost exactly the same as Arduboy2 and just accepting the fact that existing sketches may break.


(Pharap) #30

Again, it wasn’t really a serious suggestion, even if trait templates are pretty handy.
That reminds me, I need to put updating to the newer Arduboy library on my agenda.
I keep putting it off because of the introduction of the printer.


(Scott) #31

Yes, templates can be handy, which is why they were invented, but I don’t think they’re something that we want to be confusing beginning developers with.

Unless you mean the latest released V1.1 of the library, you shouldn’t be updating to anything newer (unless it’s just for experimental purposes). Anything on the head of the master or develop branches on GitHub is currently in a state of flux.


(Pharap) #32

Firstly, if they’re only using the library and not trying to investigate the insides then the templates can be easily hidden, especially with constexpr and using statements. If they are trying to look on the inside, it would make sense that there would be stuff a beginner wouldn’t comprehend. If potentially better approaches are discarded because they’ll frighten beginners, the library will almost certainly be unable to reach its full potential. Personally though, I don’t think generic programming is a particularly hard topic if someone is only using pre-existing classes and not writing their own. I remember first encountering it in either the latter half of my first year of programming or the early half of my second year and not finding it to be too troublesome.

On reflection I think I’m in agreement with @acedent. If the intention is for beginners to attempt to investigate and pull apart the arduboy library then It would be good to have a properly optimised library using advanced techniques separate from a simflified library targeted less experienced programmers who want to reverse engineer how the Arduboy works.

If the printer stuff is from the development branch rather than the stable branch then I have been accidentally misinformed by the person I usually program alongside. In which case that’s going to make our job much easier, so no harm done.


(Scott) #33

In case anyone is interested:

To help test the additions and changes that I made for Arduboy2 V2.1.0 that I just released, I modified a few Team A.R.G games to use the Arduboy2 and ArduboyTones libraries in place of Arglib. I figure it took me an average of about 15 minutes or so per game to port one. As far as I can tell, all games run identically to the originals.

Using Arduboy2 and ArduboyTones, the games all compile to a smaller code size. This is using begin(), which includes the ARDUBOY logo that scrolls down, “flashlight” mode and system mute control, so they could be made even smaller by removing these features using boot(). System mute control, especially, could be removed because all these games can set and save the mute mode themselves.

The games ended up smaller by the following number of bytes:

Virus LQP-79 - 200
Sirène - 436
Blob Attack - 450
Mystic Balloon - 536


Mystic Balloon - 9th TEAM a.r.g. game w +10 levels & SAVE/LOAD
(Holmes) #34

Thanks for posting your test results!


(Scott) #35

I’ve added and update to the original post indicating that the Arduboy2 library can now be installed using the Arduino IDE Library Manager.


(Ignacio Viña) #36

Thanks Scott!
Your optimized library is amazing, I have reduced 2KB the size of the sketch, also I get a little more fps versus the standard Arduboy lib. This is great for managing real-time compressed bitmaps and audios. :wink:


(Scott) #37

Version 3.0.0 of the Arduboy2 library has been released. There are only a few changes but I’ve spent a lot of time formatting and adding the details of the API in the source comments, so that documentation can be generated using Doxygen. The HTML files generated can be found at:

https://MLXXXp.github.io/documents/Arduino/libraries/Arduboy2/Doxygen/html/index.html

A generated PDF file can be found at:

Any feedback on this documentation is welcome.

The actual changes to the code are:

  • Renamed class ArduboyCore to Arduboy2Core and class ArduboyAudio to Arduboy2Audio, to make things more consistent and avoid possible future conflicts with the original Arduboy library. This is the reason for bumping up the major version number from 2 to 3, since any current sketch using ArduboyCore or ArduboyAudio directly will be broken (although there probably aren’t any).
  • Added the ability to optionally clear the RAM buffer after updating the display for functions display() and paintScreen().
  • Classes Arduboy2, Arduboy2Base, Arduboy2Core and Arduboy2Audio all declare friend class Arduboy2Ex. Sketches can create a local Arduboy2Ex class that will have access to protected and private members of these classes, for advanced situations where this ability would be helpful.

Do You Remember Love? - a horizontally scrolling shooter
(Ignacio Viña) #38

Thanks for your work. Really great!
I have almost finished my bitmap compressor, it would be great to include the decoder in the Arduboy2 library.
I’m not sure if 2 drawDecompressed functions are a good idea, I would prefer to work with @TEAMarg to create an unified solution. :sweat:
Also, I’m working on a voice player/decoder, maybe this could also be integrated in the audio part of your library.


(Scott) #39

Keep in mind:

  1. If a library function isn’t used by a sketch (or by another used function in the library), the compiler won’t compile it in, so it won’t take up any code space.
  • It’s unlikely that the existing drawCompressed() and your new technique will both be used in the same sketch.
  • The purpose of these functions is to minimise code size.

Therefore, if a unified function creates more code (due to needing conditional statements, extra parameters, etc.) than using only one of two separate ones, then it’s probably better to have two functions and accept the downside of requiring two different function names. This is true even if much of the code between the functions is identical.

The philosophy of the Arduboy2 library is that sound generating code is contained in a separate library. If sound code uses an interrupt, it prevents other code from using the same interrupt. Besides, there are so many ways to generate sound that I don’t think we want to clutter up the library with many different ones or dictate a preferred one.

You should write you voice player/decoder as a separate library but integrate it with the Arduboy2 library’s mute control functionality, as the existing ArduboyTones and ArduboyPlaytune libraries do.


(Ignacio Viña) #40

Thanks for the info. I’m now working on optimizing draw speed as much as I can. Also I have another function to draw the image downscaled (not as fast) but maybe good enough for some real-time zoom.
I have included some parameters to support image mirroring and alignment. Please, send me a private message if you want to discuss the naming and parameters to include on each method. Thanks!

Perfect. I understand. I will check this external libs to do a similar library to be compatible with Arduboy’s library. :slight_smile:


#41

@igvina Somebody called me ? :smiley:

Like @MLXXXp says, just keep both. Or if yours makes ours absolute, ditch ours. We made drawCompressed because we needed something, but if you created a better function, PLEASE replace ours with yours. If both have there specific advantage, well no problem in keeping both functions.

For your voice function: if you decide to put your work into a library with examples, you could pre-record a lot of words (like numbers) and put those in examples. :smiley: gives people usable data for their game, without the need to convert everything their selves. Or you could provide those on your own website.