diff --git a/NeoVerticalSpriteSheet-object-API.md b/NeoVerticalSpriteSheet-object-API.md new file mode 100644 index 0000000..4e645b2 --- /dev/null +++ b/NeoVerticalSpriteSheet-object-API.md @@ -0,0 +1,68 @@ +NeoVerticalSpriteSheet represents a image container object that stores the data in a NeoPixel native format for faster rendering. The primary use of this class is to contain an vertical series of sprites as one image and have it rendered to a NeoPixelBus. + +## Constructors + +### NeoVerticalSpriteSheet\(uint16_t width, uint16_t height, uint16_t spriteHeight, PGM_VOID_P pixels) +This will define the object with the given Method, construct it to the width and height, and define the sprite height. +Valid Method objects are the NeoBufferMethod and NeoBufferProgmemMethod. +The optional pixels will either be copied into the Ram buffer (for NeoBufferMethod) or become the referenced data (NeoBufferProgmemMethod). + +``` +NeoVerticalSpriteSheet> spriteSheet(myImageWidth, myImageHeight, mySpriteHeight, myImage); + +``` + +## Methods +### uint16_t SpriteCount() const +This will return the number of sprites in the sheet. + +### uint16_t SpriteWidth() const +This will return the width in pixels of a single sprite. + +### uint16_t SpriteHeight() const +This will return the height in pixels of a single sprite. + +### void SetPixelColor(uint16_t indexSprite, int16_t x, int16_t y, ColorObject color) +This will set the color of the given pixel on the given sprite + indexSprite - the sprite to write to + x - the horizontal pixel position + y - the vertical pixel position + color - a color object to use, RgbColor, HslColor, and HsbColor will all work and if the NeoPixelBus object was created with the NeoRgbwFeature the RgbwColor will also work. + +### ColorObject GetPixelColor(uint16_t indexSprite, int16_t x, int16_t y) +This will return the color of the given pixel from the given sprite + indexSprite - the sprite to read from + x - the horizontal pixel position + y - the vertical pixel position + \, a color object, RgbColor or RgbwColor. + +### void ClearTo(ColorObject color) +This will clear all pixels on all sprites to the given color. + color - a color object to use, RgbColor, HslColor, and HsbColor will all work and if the NeoPixelBus object was created with the NeoRgbwFeature the RgbwColor will also work. + +### void Blt(NeoBufferContext destBuffer, uint16_t indexPixel, uint16_t indexSprite) +This will render the sprite to the destBuffer at indexPixel. This is a linear rendering, not a 2D image rendering. + destBuffer - Another NeoBuffer or NeoPixelBus. + indexPixel - the location to start the render at + indexSprite - the sprite to Blt from + +### void Blt(NeoBufferContext destBuffer, int16_t xDest, int16_t yDest, uint16_t indexSprite, LayoutMapCallback layoutMap) +This will render all of a sprite to the destBuffer at given location. This is a 2d image rendering. + destBuffer - Another NeoBuffer or NeoPixelBus. + xDest - the upper left location in the destination to render to + yDest - the upper left location in the destination to render to + indexSprite - the sprite to Blt from + layoutMap - a layoutMap callback that implements the destinations mapping routine (see below) + +## Callbacks +### uint16_t LayoutMapCallback(int16_t x, int16_t y) +As the consumer of certain methods, you will need to implement this and pass it into those methods. You are expected to translate the x,y location of the destination to a linear index value. If you have implemented `NeoTopology`, `NeoTiles`, or `NeoMosaic`; you can just call the `MapProbe()` method on them and return what they provide. +``` +NeoTopology topo(16,16); // 16x16 matrix panel + +uint16_t MyLayoutMap(int16_t x, int16_t y) +{ + return topo.MapProbe(x, y); +} +``` +If you implement your own, make sure to handle out of range values beyond your edges including negative values and return `PixelIndex_OutOfBounds` for these cases. \ No newline at end of file