Some of the documentation about the new SDK 3.0 is a bit thin, particularly the ways in which Basalt and Aplite builds can be made to play together nicely. I figured out the following with a bit of digging.Tip 1: Having both color and B&W versions of your resource images.
The documentation tells us we can use #ifdef
PBL_APLITE and similar macros to switchably build our code two different ways, for Basalt and Aplite. Great! But it doesn't mention how to have two different versions of a particular resource image. You're very likely, for instance, to want to have all of your bitmaps in black-and-white and color versions, for the two different builds. But there's only one filename in appinfo.json, so how to have it load the right file for each version?
The undocumented trick is to name your two different versions "foo~bw.png" and "foo~color.png", and then in appinfo.json you just reference "foo.png" and it will pull in the correct version for each build. (If the specific name isn't found, it falls back to looking for "foo.png", so if you are updating an existing Aplite project you can just add "foo~color.png" for your Basalt version; the existing "foo.png" is automatically the Aplite version. Or you can do it the other way around.)Tip 2: Controlling whether or not your images are stored compressed in the resource file.
The documentation tells us that the Basalt builds treat type "png" differently in the appinfo.json file. Instead of converting it automatically to Pebble's internal pbi format, it stores it directly as an encoded png file, and the watch decodes it automatically when you load the resource. That's a nifty feature; it allows the resource file to stay relatively small (because png files are compressed) even though the color bitmap images are 8 times larger than the original black&white resources. But the downside to this is, it can require a fair amount of free RAM to decode them at runtime, especially for full-screen (or otherwise large) images. If your program is pushing the limits of RAM, you may not be able to load your images. It also requires a fair amount of CPU, which translates to heavy battery usage if you are loading images in a tight loop (for instance, during animation). So there may be certain images that you want to store uncompressed in Pebble's native format, so they can be loaded quickly and reliably, even though it makes the resource file bigger.
To do this, instead of type "png", specify type "pbi8" in appinfo.json. This means to load the png file in Pebble's native 8-bit uncompressed form. It can then be loaded with much less CPU and RAM requirements at runtime, but it will be considerably larger in your resource file. Note that this has no effect on the Aplite build, which treats both of these types the same (and loads them in Pebble's native 1-bit uncompressed form, the only form Aplite can render.)Tip 3: Getting back GCompOp masking.
In Aplite, there is no explicit transparency and you have to use the GCompOp modes to simulate this. You can also use GCompOp to do a number of other useful bitmap-based techniques, like inverse color, masking, negative images, and so on. In Basalt, we have explicit transparency, but we lost the ability to use GCompOp. If you load an image in either "png" or "pbi8" format, it's an 8-bit image with an alpha channel, and the only GCompOp operations you can use are GCompOpAssign or GCompOpSet, which control whether you want to use the alpha channel or not. All of the other GCompOp operations are broken. (I think this is a terrible shame, since we could still do useful things with these operations, even with 8-bit color. But for whatever reason, we can't any more.)
The GCompOp operations do
still work in Basalt if you have a 1-bit B&W image, though. You can get this with type "png-trans" in appinfo.json, as always; but if you tried to specify type "png", it won't work, because that creates an 8-bit color image (even if you gave it a B&W png file). If you have a resource image that you want to load specifically as a 1-bit B&W image to perform your GCompOp masking tricks, you can specify type "pbi" in appinfo.json, which means to load the png file in the original 1-bit uncompressed form. As above, this setting has no effect on the Aplite build, which will do this anyway.