NeoVerticalSpriteSheet object

NeoVerticalSpriteSheet object API

The NeoVerticalSpriteSheet is sprite strip image storage object. Based upon the "method" object it is defined with, it can store the sprite strip data in RAM or reference image data stored in PROGMEM.

A vertical sprite strip is one image that represents a vertical column of equal sized sub images or sprites.

It provides direct x,y access to get and set pixels on each sprite along with a render method Blt() that will copy bits to the NeoPixelBus or other Raster objects.

How to construct one

The important part of creating one is to match the "ColorFeature" between your NeoPixelBus and the buffer since the buffer will store/reference data in the same format as the bus.

Here you can see that they both are defined with NeoGrbwFeature.

NeoPixelBus<NeoGrbwFeature, Neo800KbpsMethod> strip(PixelCount, PixelPin);
NeoVerticalSpriteSheet<NeoBufferProgmemMethod<NeoGrbwFeature>> spriteSheet(
        myImageWidth, // image width and sprite width since its vertical sprite sheet
        myImageHeight,  // image height
        8, // sprite is eight pixels high
        myImage);

There are two template "Method" objects that used in the construction of the NeoVerticalSpriteSheet that define where the data for the image is stored. There is no need to call these objects directly and they should just be used to construct the two raster objects..

• NeoBufferMethod - This method object will define the raster object so that it uses RAM to store the image.
• NeoBufferProgmemMethod - This method object will define the raster object so that it uses PROGMEM to store the image.

If you plan to dynamically modify the image through source code, then you have to define it to use RAM by using NeoBufferMethod . You can still initialize the RAM stored image from PROGMEM.
If you plan to just consume the image and never modify it, your best approach is to use PROGMEM by using NeoBufferProgmemMethod as it will store in flash like source code and save precious RAM for your sketch.

// stored in RAM, but initialized by the "myImage" from PROGMEM
NeoVerticalSpriteSheet<NeoBufferMethod<NeoGrbwFeature>> spriteSheet(myImageWidth, myImageHeight, 8, myImage);
// stored in PROGMEM
NeoVerticalSpriteSheet<NeoBufferProgmemMethod<NeoGrbwFeature>> spriteSheet(myImageWidth, myImageHeight, 8, myImage);

How to render the image

To render the buffer image you use one of the BLT (block transfer) methods. They will copy the image data from the buffer to the target.

Targets of Rendering

The BLT methods all take a generic target for the first parameter as a NeoBufferContext<>. This buffer context is a mechanism to allow for different types of targets to be used. You can pass the NeoPixelBus directly for this. You may also pass any of the other Raster objects that allow writing to.

Rendering to a string of pixels

If you have both a "sprite" that is one pixel high, and you have just a string of pixels on your NeoPixelBus, and you want speed; then you can use Blt(dest, destIndex, spriteIndex) method. The image can contain multiple sprites, but the sprite has to be only one pixel in height. This method is very quick.

Rendering to a matrix of pixels

If your image has more than one row or column of pixels and/or your pixels are arranged in a matrix, then can use Blt(dest, xDest, yDest, spriteIndex, layoutMap).

The complexity with this method is that the target buffer doesn't explicitly know how you have them laid out. You maybe using NeoTopology or maybe NeoMosaic. To solve this you need to pass a callback as the "layoutMap" that will be called so you can provide the mapping. Inside this you can provide your custom layout mapping or you can use the MapProbe() method of any of the matrix panel support objects like NeoTopology, NeoTiles, or NeoMosaic.
If you are providing your own mapping; you must return PixelIndex_OutOfBounds if the coordinate is outside the range you support.

NeoTopology<RowMajorLayout> topo(16,16);

uint16_t LayoutMap(int16_t x, int16_t y)
{
  return topo.MapProbe(x, y);
}

Once of you have defined this callback, then you can use to render parts of the image.

image.Blt(strip, 4, 4, 0, LayoutMap);

This will render the first sprite to the strip at location (4,4).