Cefn Hoile / microbit-dal

Attempting to publish a tree

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal by Lancaster University

inc/types/MicroBitImage.h@18:ce4dd8fcdf4f, 2016-06-01 (annotated)

Committer:
cefn
Date:
Wed Jun 01 17:43:26 2016 +0000
Revision:
18:ce4dd8fcdf4f
Parent:
1:8aa5cdb4ab67 
Attempting to publish a tree

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jonathan Austin 1:8aa5cdb4ab67 1 /*
Jonathan Austin 1:8aa5cdb4ab67 2 The MIT License (MIT)
Jonathan Austin 1:8aa5cdb4ab67 3
Jonathan Austin 1:8aa5cdb4ab67 4 Copyright (c) 2016 British Broadcasting Corporation.
Jonathan Austin 1:8aa5cdb4ab67 5 This software is provided by Lancaster University by arrangement with the BBC.
Jonathan Austin 1:8aa5cdb4ab67 6
Jonathan Austin 1:8aa5cdb4ab67 7 Permission is hereby granted, free of charge, to any person obtaining a
Jonathan Austin 1:8aa5cdb4ab67 8 copy of this software and associated documentation files (the "Software"),
Jonathan Austin 1:8aa5cdb4ab67 9 to deal in the Software without restriction, including without limitation
Jonathan Austin 1:8aa5cdb4ab67 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
Jonathan Austin 1:8aa5cdb4ab67 11 and/or sell copies of the Software, and to permit persons to whom the
Jonathan Austin 1:8aa5cdb4ab67 12 Software is furnished to do so, subject to the following conditions:
Jonathan Austin 1:8aa5cdb4ab67 13
Jonathan Austin 1:8aa5cdb4ab67 14 The above copyright notice and this permission notice shall be included in
Jonathan Austin 1:8aa5cdb4ab67 15 all copies or substantial portions of the Software.
Jonathan Austin 1:8aa5cdb4ab67 16
Jonathan Austin 1:8aa5cdb4ab67 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Jonathan Austin 1:8aa5cdb4ab67 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Jonathan Austin 1:8aa5cdb4ab67 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
Jonathan Austin 1:8aa5cdb4ab67 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
Jonathan Austin 1:8aa5cdb4ab67 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 23 DEALINGS IN THE SOFTWARE.
Jonathan Austin 1:8aa5cdb4ab67 24 */
Jonathan Austin 1:8aa5cdb4ab67 25
Jonathan Austin 1:8aa5cdb4ab67 26 #ifndef MICROBIT_IMAGE_H
Jonathan Austin 1:8aa5cdb4ab67 27 #define MICROBIT_IMAGE_H
Jonathan Austin 1:8aa5cdb4ab67 28
Jonathan Austin 1:8aa5cdb4ab67 29 #include "mbed.h"
Jonathan Austin 1:8aa5cdb4ab67 30 #include "MicroBitConfig.h"
Jonathan Austin 1:8aa5cdb4ab67 31 #include "ManagedString.h"
Jonathan Austin 1:8aa5cdb4ab67 32 #include "RefCounted.h"
Jonathan Austin 1:8aa5cdb4ab67 33
Jonathan Austin 1:8aa5cdb4ab67 34 struct ImageData : RefCounted
Jonathan Austin 1:8aa5cdb4ab67 35 {
Jonathan Austin 1:8aa5cdb4ab67 36 uint16_t width; // Width in pixels
Jonathan Austin 1:8aa5cdb4ab67 37 uint16_t height; // Height in pixels
Jonathan Austin 1:8aa5cdb4ab67 38 uint8_t data[0]; // 2D array representing the bitmap image
Jonathan Austin 1:8aa5cdb4ab67 39 };
Jonathan Austin 1:8aa5cdb4ab67 40
Jonathan Austin 1:8aa5cdb4ab67 41 /**
Jonathan Austin 1:8aa5cdb4ab67 42 * Class definition for a MicroBitImage.
Jonathan Austin 1:8aa5cdb4ab67 43 *
Jonathan Austin 1:8aa5cdb4ab67 44 * An MicroBitImage is a simple bitmap representation of an image.
Jonathan Austin 1:8aa5cdb4ab67 45 * n.b. This is a mutable, managed type.
Jonathan Austin 1:8aa5cdb4ab67 46 */
Jonathan Austin 1:8aa5cdb4ab67 47 class MicroBitImage
Jonathan Austin 1:8aa5cdb4ab67 48 {
Jonathan Austin 1:8aa5cdb4ab67 49 ImageData *ptr; // Pointer to payload data
Jonathan Austin 1:8aa5cdb4ab67 50
Jonathan Austin 1:8aa5cdb4ab67 51
Jonathan Austin 1:8aa5cdb4ab67 52 /**
Jonathan Austin 1:8aa5cdb4ab67 53 * Internal constructor which provides sanity checking and initialises class properties.
Jonathan Austin 1:8aa5cdb4ab67 54 *
Jonathan Austin 1:8aa5cdb4ab67 55 * @param x the width of the image
Jonathan Austin 1:8aa5cdb4ab67 56 *
Jonathan Austin 1:8aa5cdb4ab67 57 * @param y the height of the image
Jonathan Austin 1:8aa5cdb4ab67 58 *
Jonathan Austin 1:8aa5cdb4ab67 59 * @param bitmap an array of integers that make up an image.
Jonathan Austin 1:8aa5cdb4ab67 60 */
Jonathan Austin 1:8aa5cdb4ab67 61 void init(const int16_t x, const int16_t y, const uint8_t *bitmap);
Jonathan Austin 1:8aa5cdb4ab67 62
Jonathan Austin 1:8aa5cdb4ab67 63 /**
Jonathan Austin 1:8aa5cdb4ab67 64 * Internal constructor which defaults to the Empty Image instance variable
Jonathan Austin 1:8aa5cdb4ab67 65 */
Jonathan Austin 1:8aa5cdb4ab67 66 void init_empty();
Jonathan Austin 1:8aa5cdb4ab67 67
Jonathan Austin 1:8aa5cdb4ab67 68 public:
Jonathan Austin 1:8aa5cdb4ab67 69 static MicroBitImage EmptyImage; // Shared representation of a null image.
Jonathan Austin 1:8aa5cdb4ab67 70
Jonathan Austin 1:8aa5cdb4ab67 71 /**
Jonathan Austin 1:8aa5cdb4ab67 72 * Get current ptr, do not decr() it, and set the current instance to empty image.
Jonathan Austin 1:8aa5cdb4ab67 73 *
Jonathan Austin 1:8aa5cdb4ab67 74 * This is to be used by specialized runtimes which pass ImageData around.
Jonathan Austin 1:8aa5cdb4ab67 75 */
Jonathan Austin 1:8aa5cdb4ab67 76 ImageData *leakData();
Jonathan Austin 1:8aa5cdb4ab67 77
Jonathan Austin 1:8aa5cdb4ab67 78 /**
Jonathan Austin 1:8aa5cdb4ab67 79 * Return a 2D array representing the bitmap image.
Jonathan Austin 1:8aa5cdb4ab67 80 */
Jonathan Austin 1:8aa5cdb4ab67 81 uint8_t *getBitmap()
Jonathan Austin 1:8aa5cdb4ab67 82 {
Jonathan Austin 1:8aa5cdb4ab67 83 return ptr->data;
Jonathan Austin 1:8aa5cdb4ab67 84 }
Jonathan Austin 1:8aa5cdb4ab67 85
Jonathan Austin 1:8aa5cdb4ab67 86 /**
Jonathan Austin 1:8aa5cdb4ab67 87 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 88 * Create an image from a specially prepared constant array, with no copying. Will call ptr->incr().
Jonathan Austin 1:8aa5cdb4ab67 89 *
Jonathan Austin 1:8aa5cdb4ab67 90 * @param ptr The literal - first two bytes should be 0xff, then width, 0, height, 0, and the bitmap. Width and height are 16 bit. The literal has to be 4-byte aligned.
Jonathan Austin 1:8aa5cdb4ab67 91 *
Jonathan Austin 1:8aa5cdb4ab67 92 * @code
Jonathan Austin 1:8aa5cdb4ab67 93 * static const uint8_t heart[] __attribute__ ((aligned (4))) = { 0xff, 0xff, 10, 0, 5, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 94 * MicroBitImage i((ImageData*)(void*)heart);
Jonathan Austin 1:8aa5cdb4ab67 95 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 96 */
Jonathan Austin 1:8aa5cdb4ab67 97 MicroBitImage(ImageData *ptr);
Jonathan Austin 1:8aa5cdb4ab67 98
Jonathan Austin 1:8aa5cdb4ab67 99 /**
Jonathan Austin 1:8aa5cdb4ab67 100 * Default Constructor.
Jonathan Austin 1:8aa5cdb4ab67 101 * Creates a new reference to the empty MicroBitImage bitmap
Jonathan Austin 1:8aa5cdb4ab67 102 *
Jonathan Austin 1:8aa5cdb4ab67 103 * @code
Jonathan Austin 1:8aa5cdb4ab67 104 * MicroBitImage i(); //an empty image instance
Jonathan Austin 1:8aa5cdb4ab67 105 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 106 */
Jonathan Austin 1:8aa5cdb4ab67 107 MicroBitImage();
Jonathan Austin 1:8aa5cdb4ab67 108
Jonathan Austin 1:8aa5cdb4ab67 109
Jonathan Austin 1:8aa5cdb4ab67 110 /**
Jonathan Austin 1:8aa5cdb4ab67 111 * Copy Constructor.
Jonathan Austin 1:8aa5cdb4ab67 112 * Add ourselves as a reference to an existing MicroBitImage.
Jonathan Austin 1:8aa5cdb4ab67 113 *
Jonathan Austin 1:8aa5cdb4ab67 114 * @param image The MicroBitImage to reference.
Jonathan Austin 1:8aa5cdb4ab67 115 *
Jonathan Austin 1:8aa5cdb4ab67 116 * @code
Jonathan Austin 1:8aa5cdb4ab67 117 * MicroBitImage i("0,1,0,1,0\n");
Jonathan Austin 1:8aa5cdb4ab67 118 * MicroBitImage i2(i); //points to i
Jonathan Austin 1:8aa5cdb4ab67 119 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 120 */
Jonathan Austin 1:8aa5cdb4ab67 121 MicroBitImage(const MicroBitImage &image);
Jonathan Austin 1:8aa5cdb4ab67 122
Jonathan Austin 1:8aa5cdb4ab67 123 /**
Jonathan Austin 1:8aa5cdb4ab67 124 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 125 * Create a blank bitmap representation of a given size.
Jonathan Austin 1:8aa5cdb4ab67 126 *
Jonathan Austin 1:8aa5cdb4ab67 127 * @param s A text based representation of the image given whitespace delimited numeric values.
Jonathan Austin 1:8aa5cdb4ab67 128 *
Jonathan Austin 1:8aa5cdb4ab67 129 * @code
Jonathan Austin 1:8aa5cdb4ab67 130 * MicroBitImage i("0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n"); // 5x5 image
Jonathan Austin 1:8aa5cdb4ab67 131 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 132 */
Jonathan Austin 1:8aa5cdb4ab67 133 explicit MicroBitImage(const char *s);
Jonathan Austin 1:8aa5cdb4ab67 134
Jonathan Austin 1:8aa5cdb4ab67 135 /**
Jonathan Austin 1:8aa5cdb4ab67 136 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 137 * Create a blank bitmap representation of a given size.
Jonathan Austin 1:8aa5cdb4ab67 138 *
Jonathan Austin 1:8aa5cdb4ab67 139 * @param x the width of the image.
Jonathan Austin 1:8aa5cdb4ab67 140 *
Jonathan Austin 1:8aa5cdb4ab67 141 * @param y the height of the image.
Jonathan Austin 1:8aa5cdb4ab67 142 *
Jonathan Austin 1:8aa5cdb4ab67 143 * Bitmap buffer is linear, with 8 bits per pixel, row by row,
Jonathan Austin 1:8aa5cdb4ab67 144 * top to bottom with no word alignment. Stride is therefore the image width in pixels.
Jonathan Austin 1:8aa5cdb4ab67 145 * in where w and h are width and height respectively, the layout is therefore:
Jonathan Austin 1:8aa5cdb4ab67 146 *
Jonathan Austin 1:8aa5cdb4ab67 147 * |[0,0]...[w,o][1,0]...[w,1] ... [[w,h]
Jonathan Austin 1:8aa5cdb4ab67 148 *
Jonathan Austin 1:8aa5cdb4ab67 149 * A copy of the image is made in RAM, as images are mutable.
Jonathan Austin 1:8aa5cdb4ab67 150 */
Jonathan Austin 1:8aa5cdb4ab67 151 MicroBitImage(const int16_t x, const int16_t y);
Jonathan Austin 1:8aa5cdb4ab67 152
Jonathan Austin 1:8aa5cdb4ab67 153 /**
Jonathan Austin 1:8aa5cdb4ab67 154 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 155 * Create a bitmap representation of a given size, based on a given buffer.
Jonathan Austin 1:8aa5cdb4ab67 156 *
Jonathan Austin 1:8aa5cdb4ab67 157 * @param x the width of the image.
Jonathan Austin 1:8aa5cdb4ab67 158 *
Jonathan Austin 1:8aa5cdb4ab67 159 * @param y the height of the image.
Jonathan Austin 1:8aa5cdb4ab67 160 *
Jonathan Austin 1:8aa5cdb4ab67 161 * @param bitmap a 2D array representing the image.
Jonathan Austin 1:8aa5cdb4ab67 162 *
Jonathan Austin 1:8aa5cdb4ab67 163 * @code
Jonathan Austin 1:8aa5cdb4ab67 164 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 165 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 166 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 167 */
Jonathan Austin 1:8aa5cdb4ab67 168 MicroBitImage(const int16_t x, const int16_t y, const uint8_t *bitmap);
Jonathan Austin 1:8aa5cdb4ab67 169
Jonathan Austin 1:8aa5cdb4ab67 170 /**
Jonathan Austin 1:8aa5cdb4ab67 171 * Destructor.
Jonathan Austin 1:8aa5cdb4ab67 172 *
Jonathan Austin 1:8aa5cdb4ab67 173 * Removes buffer resources held by the instance.
Jonathan Austin 1:8aa5cdb4ab67 174 */
Jonathan Austin 1:8aa5cdb4ab67 175 ~MicroBitImage();
Jonathan Austin 1:8aa5cdb4ab67 176
Jonathan Austin 1:8aa5cdb4ab67 177 /**
Jonathan Austin 1:8aa5cdb4ab67 178 * Copy assign operation.
Jonathan Austin 1:8aa5cdb4ab67 179 *
Jonathan Austin 1:8aa5cdb4ab67 180 * Called when one MicroBitImage is assigned the value of another using the '=' operator.
Jonathan Austin 1:8aa5cdb4ab67 181 *
Jonathan Austin 1:8aa5cdb4ab67 182 * Decrement our reference count and free up the buffer as necessary.
Jonathan Austin 1:8aa5cdb4ab67 183 *
Jonathan Austin 1:8aa5cdb4ab67 184 * Then, update our buffer to refer to that of the supplied MicroBitImage,
Jonathan Austin 1:8aa5cdb4ab67 185 * and increase its reference count.
Jonathan Austin 1:8aa5cdb4ab67 186 *
Jonathan Austin 1:8aa5cdb4ab67 187 * @param s The MicroBitImage to reference.
Jonathan Austin 1:8aa5cdb4ab67 188 *
Jonathan Austin 1:8aa5cdb4ab67 189 * @code
Jonathan Austin 1:8aa5cdb4ab67 190 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 191 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 192 * MicroBitImage i1();
Jonathan Austin 1:8aa5cdb4ab67 193 * i1 = i; // i1 now references i
Jonathan Austin 1:8aa5cdb4ab67 194 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 195 */
Jonathan Austin 1:8aa5cdb4ab67 196 MicroBitImage& operator = (const MicroBitImage& i);
Jonathan Austin 1:8aa5cdb4ab67 197
Jonathan Austin 1:8aa5cdb4ab67 198
Jonathan Austin 1:8aa5cdb4ab67 199 /**
Jonathan Austin 1:8aa5cdb4ab67 200 * Equality operation.
Jonathan Austin 1:8aa5cdb4ab67 201 *
Jonathan Austin 1:8aa5cdb4ab67 202 * Called when one MicroBitImage is tested to be equal to another using the '==' operator.
Jonathan Austin 1:8aa5cdb4ab67 203 *
Jonathan Austin 1:8aa5cdb4ab67 204 * @param i The MicroBitImage to test ourselves against.
Jonathan Austin 1:8aa5cdb4ab67 205 *
Jonathan Austin 1:8aa5cdb4ab67 206 * @return true if this MicroBitImage is identical to the one supplied, false otherwise.
Jonathan Austin 1:8aa5cdb4ab67 207 *
Jonathan Austin 1:8aa5cdb4ab67 208 * @code
Jonathan Austin 1:8aa5cdb4ab67 209 * MicroBitDisplay display;
Jonathan Austin 1:8aa5cdb4ab67 210 * MicroBitImage i();
Jonathan Austin 1:8aa5cdb4ab67 211 * MicroBitImage i1();
Jonathan Austin 1:8aa5cdb4ab67 212 *
Jonathan Austin 1:8aa5cdb4ab67 213 * if(i == i1) //will be true
Jonathan Austin 1:8aa5cdb4ab67 214 * display.scroll("true");
Jonathan Austin 1:8aa5cdb4ab67 215 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 216 */
Jonathan Austin 1:8aa5cdb4ab67 217 bool operator== (const MicroBitImage& i);
Jonathan Austin 1:8aa5cdb4ab67 218
Jonathan Austin 1:8aa5cdb4ab67 219 /**
Jonathan Austin 1:8aa5cdb4ab67 220 * Resets all pixels in this image to 0.
Jonathan Austin 1:8aa5cdb4ab67 221 *
Jonathan Austin 1:8aa5cdb4ab67 222 * @code
Jonathan Austin 1:8aa5cdb4ab67 223 * MicroBitImage i("0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n"); // 5x5 image
Jonathan Austin 1:8aa5cdb4ab67 224 * i.clear();
Jonathan Austin 1:8aa5cdb4ab67 225 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 226 */
Jonathan Austin 1:8aa5cdb4ab67 227 void clear();
Jonathan Austin 1:8aa5cdb4ab67 228
Jonathan Austin 1:8aa5cdb4ab67 229 /**
Jonathan Austin 1:8aa5cdb4ab67 230 * Sets the pixel at the given co-ordinates to a given value.
Jonathan Austin 1:8aa5cdb4ab67 231 *
Jonathan Austin 1:8aa5cdb4ab67 232 * @param x The co-ordinate of the pixel to change.
Jonathan Austin 1:8aa5cdb4ab67 233 *
Jonathan Austin 1:8aa5cdb4ab67 234 * @param y The co-ordinate of the pixel to change.
Jonathan Austin 1:8aa5cdb4ab67 235 *
Jonathan Austin 1:8aa5cdb4ab67 236 * @param value The new value of the pixel (the brightness level 0-255)
Jonathan Austin 1:8aa5cdb4ab67 237 *
Jonathan Austin 1:8aa5cdb4ab67 238 * @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 239 *
Jonathan Austin 1:8aa5cdb4ab67 240 * @code
Jonathan Austin 1:8aa5cdb4ab67 241 * MicroBitImage i("0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n"); // 5x5 image
Jonathan Austin 1:8aa5cdb4ab67 242 * i.setPixelValue(0,0,255);
Jonathan Austin 1:8aa5cdb4ab67 243 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 244 *
Jonathan Austin 1:8aa5cdb4ab67 245 * @note all coordinates originate from the top left of an image.
Jonathan Austin 1:8aa5cdb4ab67 246 */
Jonathan Austin 1:8aa5cdb4ab67 247 int setPixelValue(int16_t x , int16_t y, uint8_t value);
Jonathan Austin 1:8aa5cdb4ab67 248
Jonathan Austin 1:8aa5cdb4ab67 249 /**
Jonathan Austin 1:8aa5cdb4ab67 250 * Retreives the value of a given pixel.
Jonathan Austin 1:8aa5cdb4ab67 251 *
Jonathan Austin 1:8aa5cdb4ab67 252 * @param x The x co-ordinate of the pixel to read. Must be within the dimensions of the image.
Jonathan Austin 1:8aa5cdb4ab67 253 *
Jonathan Austin 1:8aa5cdb4ab67 254 * @param y The y co-ordinate of the pixel to read. Must be within the dimensions of the image.
Jonathan Austin 1:8aa5cdb4ab67 255 *
Jonathan Austin 1:8aa5cdb4ab67 256 * @return The value assigned to the given pixel location (the brightness level 0-255), or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 257 *
Jonathan Austin 1:8aa5cdb4ab67 258 * @code
Jonathan Austin 1:8aa5cdb4ab67 259 * MicroBitImage i("0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n1,0,1,0,1\n0,1,0,1,0\n"); // 5x5 image
Jonathan Austin 1:8aa5cdb4ab67 260 * i.getPixelValue(0,0); //should be 0;
Jonathan Austin 1:8aa5cdb4ab67 261 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 262 */
Jonathan Austin 1:8aa5cdb4ab67 263 int getPixelValue(int16_t x , int16_t y);
Jonathan Austin 1:8aa5cdb4ab67 264
Jonathan Austin 1:8aa5cdb4ab67 265 /**
Jonathan Austin 1:8aa5cdb4ab67 266 * Replaces the content of this image with that of a given 2D array representing
Jonathan Austin 1:8aa5cdb4ab67 267 * the image.
Jonathan Austin 1:8aa5cdb4ab67 268 *
Jonathan Austin 1:8aa5cdb4ab67 269 * @param x the width of the image. Must be within the dimensions of the image.
Jonathan Austin 1:8aa5cdb4ab67 270 *
Jonathan Austin 1:8aa5cdb4ab67 271 * @param y the width of the image. Must be within the dimensions of the image.
Jonathan Austin 1:8aa5cdb4ab67 272 *
Jonathan Austin 1:8aa5cdb4ab67 273 * @param bitmap a 2D array representing the image.
Jonathan Austin 1:8aa5cdb4ab67 274 *
Jonathan Austin 1:8aa5cdb4ab67 275 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 276 *
Jonathan Austin 1:8aa5cdb4ab67 277 * @code
Jonathan Austin 1:8aa5cdb4ab67 278 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 279 * MicroBitImage i();
Jonathan Austin 1:8aa5cdb4ab67 280 * i.printImage(0,0,heart);
Jonathan Austin 1:8aa5cdb4ab67 281 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 282 *
Jonathan Austin 1:8aa5cdb4ab67 283 * @note all coordinates originate from the top left of an image.
Jonathan Austin 1:8aa5cdb4ab67 284 */
Jonathan Austin 1:8aa5cdb4ab67 285 int printImage(int16_t x, int16_t y, const uint8_t *bitmap);
Jonathan Austin 1:8aa5cdb4ab67 286
Jonathan Austin 1:8aa5cdb4ab67 287 /**
Jonathan Austin 1:8aa5cdb4ab67 288 * Pastes a given bitmap at the given co-ordinates.
Jonathan Austin 1:8aa5cdb4ab67 289 *
Jonathan Austin 1:8aa5cdb4ab67 290 * Any pixels in the relvant area of this image are replaced.
Jonathan Austin 1:8aa5cdb4ab67 291 *
Jonathan Austin 1:8aa5cdb4ab67 292 * @param image The MicroBitImage to paste.
Jonathan Austin 1:8aa5cdb4ab67 293 *
Jonathan Austin 1:8aa5cdb4ab67 294 * @param x The leftmost X co-ordinate in this image where the given image should be pasted. Defaults to 0.
Jonathan Austin 1:8aa5cdb4ab67 295 *
Jonathan Austin 1:8aa5cdb4ab67 296 * @param y The uppermost Y co-ordinate in this image where the given image should be pasted. Defaults to 0.
Jonathan Austin 1:8aa5cdb4ab67 297 *
Jonathan Austin 1:8aa5cdb4ab67 298 * @param alpha set to 1 if transparency clear pixels in given image should be treated as transparent. Set to 0 otherwise. Defaults to 0.
Jonathan Austin 1:8aa5cdb4ab67 299 *
Jonathan Austin 1:8aa5cdb4ab67 300 * @return The number of pixels written.
Jonathan Austin 1:8aa5cdb4ab67 301 *
Jonathan Austin 1:8aa5cdb4ab67 302 * @code
Jonathan Austin 1:8aa5cdb4ab67 303 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 304 * MicroBitImage i(10,5,heart); // a big heart
Jonathan Austin 1:8aa5cdb4ab67 305 * i.paste(i, -5, 0); // a small heart
Jonathan Austin 1:8aa5cdb4ab67 306 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 307 */
Jonathan Austin 1:8aa5cdb4ab67 308 int paste(const MicroBitImage &image, int16_t x = 0, int16_t y = 0, uint8_t alpha = 0);
Jonathan Austin 1:8aa5cdb4ab67 309
Jonathan Austin 1:8aa5cdb4ab67 310 /**
Jonathan Austin 1:8aa5cdb4ab67 311 * Prints a character to the display at the given location
Jonathan Austin 1:8aa5cdb4ab67 312 *
Jonathan Austin 1:8aa5cdb4ab67 313 * @param c The character to display.
Jonathan Austin 1:8aa5cdb4ab67 314 *
Jonathan Austin 1:8aa5cdb4ab67 315 * @param x The x co-ordinate of on the image to place the top left of the character. Defaults to 0.
Jonathan Austin 1:8aa5cdb4ab67 316 *
Jonathan Austin 1:8aa5cdb4ab67 317 * @param y The y co-ordinate of on the image to place the top left of the character. Defaults to 0.
Jonathan Austin 1:8aa5cdb4ab67 318 *
Jonathan Austin 1:8aa5cdb4ab67 319 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 320 *
Jonathan Austin 1:8aa5cdb4ab67 321 * @code
Jonathan Austin 1:8aa5cdb4ab67 322 * MicroBitImage i(5,5);
Jonathan Austin 1:8aa5cdb4ab67 323 * i.print('a');
Jonathan Austin 1:8aa5cdb4ab67 324 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 325 */
Jonathan Austin 1:8aa5cdb4ab67 326 int print(char c, int16_t x = 0, int16_t y = 0);
Jonathan Austin 1:8aa5cdb4ab67 327
Jonathan Austin 1:8aa5cdb4ab67 328 /**
Jonathan Austin 1:8aa5cdb4ab67 329 * Shifts the pixels in this Image a given number of pixels to the left.
Jonathan Austin 1:8aa5cdb4ab67 330 *
Jonathan Austin 1:8aa5cdb4ab67 331 * @param n The number of pixels to shift.
Jonathan Austin 1:8aa5cdb4ab67 332 *
Jonathan Austin 1:8aa5cdb4ab67 333 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 334 *
Jonathan Austin 1:8aa5cdb4ab67 335 * @code
Jonathan Austin 1:8aa5cdb4ab67 336 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 337 * MicroBitImage i(10,5,heart); // a big heart
Jonathan Austin 1:8aa5cdb4ab67 338 * i.shiftLeft(5); // a small heart
Jonathan Austin 1:8aa5cdb4ab67 339 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 340 */
Jonathan Austin 1:8aa5cdb4ab67 341 int shiftLeft(int16_t n);
Jonathan Austin 1:8aa5cdb4ab67 342
Jonathan Austin 1:8aa5cdb4ab67 343 /**
Jonathan Austin 1:8aa5cdb4ab67 344 * Shifts the pixels in this Image a given number of pixels to the right.
Jonathan Austin 1:8aa5cdb4ab67 345 *
Jonathan Austin 1:8aa5cdb4ab67 346 * @param n The number of pixels to shift.
Jonathan Austin 1:8aa5cdb4ab67 347 *
Jonathan Austin 1:8aa5cdb4ab67 348 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 349 *
Jonathan Austin 1:8aa5cdb4ab67 350 * @code
Jonathan Austin 1:8aa5cdb4ab67 351 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 352 * MicroBitImage i(10,5,heart); // a big heart
Jonathan Austin 1:8aa5cdb4ab67 353 * i.shiftLeft(5); // a small heart
Jonathan Austin 1:8aa5cdb4ab67 354 * i.shiftRight(5); // a big heart
Jonathan Austin 1:8aa5cdb4ab67 355 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 356 */
Jonathan Austin 1:8aa5cdb4ab67 357 int shiftRight(int16_t n);
Jonathan Austin 1:8aa5cdb4ab67 358
Jonathan Austin 1:8aa5cdb4ab67 359 /**
Jonathan Austin 1:8aa5cdb4ab67 360 * Shifts the pixels in this Image a given number of pixels to upward.
Jonathan Austin 1:8aa5cdb4ab67 361 *
Jonathan Austin 1:8aa5cdb4ab67 362 * @param n The number of pixels to shift.
Jonathan Austin 1:8aa5cdb4ab67 363 *
Jonathan Austin 1:8aa5cdb4ab67 364 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 365 *
Jonathan Austin 1:8aa5cdb4ab67 366 * @code
Jonathan Austin 1:8aa5cdb4ab67 367 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 368 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 369 * i.shiftUp(1);
Jonathan Austin 1:8aa5cdb4ab67 370 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 371 */
Jonathan Austin 1:8aa5cdb4ab67 372 int shiftUp(int16_t n);
Jonathan Austin 1:8aa5cdb4ab67 373
Jonathan Austin 1:8aa5cdb4ab67 374 /**
Jonathan Austin 1:8aa5cdb4ab67 375 * Shifts the pixels in this Image a given number of pixels to downward.
Jonathan Austin 1:8aa5cdb4ab67 376 *
Jonathan Austin 1:8aa5cdb4ab67 377 * @param n The number of pixels to shift.
Jonathan Austin 1:8aa5cdb4ab67 378 *
Jonathan Austin 1:8aa5cdb4ab67 379 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
Jonathan Austin 1:8aa5cdb4ab67 380 *
Jonathan Austin 1:8aa5cdb4ab67 381 * @code
Jonathan Austin 1:8aa5cdb4ab67 382 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 383 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 384 * i.shiftDown(1);
Jonathan Austin 1:8aa5cdb4ab67 385 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 386 */
Jonathan Austin 1:8aa5cdb4ab67 387 int shiftDown(int16_t n);
Jonathan Austin 1:8aa5cdb4ab67 388
Jonathan Austin 1:8aa5cdb4ab67 389 /**
Jonathan Austin 1:8aa5cdb4ab67 390 * Gets the width of this image.
Jonathan Austin 1:8aa5cdb4ab67 391 *
Jonathan Austin 1:8aa5cdb4ab67 392 * @return The width of this image.
Jonathan Austin 1:8aa5cdb4ab67 393 *
Jonathan Austin 1:8aa5cdb4ab67 394 * @code
Jonathan Austin 1:8aa5cdb4ab67 395 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 396 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 397 * i.getWidth(); // equals 10...
Jonathan Austin 1:8aa5cdb4ab67 398 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 399 */
Jonathan Austin 1:8aa5cdb4ab67 400 int getWidth() const
Jonathan Austin 1:8aa5cdb4ab67 401 {
Jonathan Austin 1:8aa5cdb4ab67 402 return ptr->width;
Jonathan Austin 1:8aa5cdb4ab67 403 }
Jonathan Austin 1:8aa5cdb4ab67 404
Jonathan Austin 1:8aa5cdb4ab67 405 /**
Jonathan Austin 1:8aa5cdb4ab67 406 * Gets the height of this image.
Jonathan Austin 1:8aa5cdb4ab67 407 *
Jonathan Austin 1:8aa5cdb4ab67 408 * @return The height of this image.
Jonathan Austin 1:8aa5cdb4ab67 409 *
Jonathan Austin 1:8aa5cdb4ab67 410 * @code
Jonathan Austin 1:8aa5cdb4ab67 411 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 412 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 413 * i.getHeight(); // equals 5...
Jonathan Austin 1:8aa5cdb4ab67 414 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 415 */
Jonathan Austin 1:8aa5cdb4ab67 416 int getHeight() const
Jonathan Austin 1:8aa5cdb4ab67 417 {
Jonathan Austin 1:8aa5cdb4ab67 418 return ptr->height;
Jonathan Austin 1:8aa5cdb4ab67 419 }
Jonathan Austin 1:8aa5cdb4ab67 420
Jonathan Austin 1:8aa5cdb4ab67 421 /**
Jonathan Austin 1:8aa5cdb4ab67 422 * Gets number of bytes in the bitmap, ie., width * height.
Jonathan Austin 1:8aa5cdb4ab67 423 *
Jonathan Austin 1:8aa5cdb4ab67 424 * @return The size of the bitmap.
Jonathan Austin 1:8aa5cdb4ab67 425 *
Jonathan Austin 1:8aa5cdb4ab67 426 * @code
Jonathan Austin 1:8aa5cdb4ab67 427 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 428 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 429 * i.getSize(); // equals 50...
Jonathan Austin 1:8aa5cdb4ab67 430 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 431 */
Jonathan Austin 1:8aa5cdb4ab67 432 int getSize() const
Jonathan Austin 1:8aa5cdb4ab67 433 {
Jonathan Austin 1:8aa5cdb4ab67 434 return ptr->width * ptr->height;
Jonathan Austin 1:8aa5cdb4ab67 435 }
Jonathan Austin 1:8aa5cdb4ab67 436
Jonathan Austin 1:8aa5cdb4ab67 437 /**
Jonathan Austin 1:8aa5cdb4ab67 438 * Converts the bitmap to a csv ManagedString.
Jonathan Austin 1:8aa5cdb4ab67 439 *
Jonathan Austin 1:8aa5cdb4ab67 440 * @code
Jonathan Austin 1:8aa5cdb4ab67 441 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 442 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 443 * uBit.serial.printString(i.toString()); // "0,1,0,1,0,0,0,0,0,0\n..."
Jonathan Austin 1:8aa5cdb4ab67 444 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 445 */
Jonathan Austin 1:8aa5cdb4ab67 446 ManagedString toString();
Jonathan Austin 1:8aa5cdb4ab67 447
Jonathan Austin 1:8aa5cdb4ab67 448 /**
Jonathan Austin 1:8aa5cdb4ab67 449 * Crops the image to the given dimensions.
Jonathan Austin 1:8aa5cdb4ab67 450 *
Jonathan Austin 1:8aa5cdb4ab67 451 * @param startx the location to start the crop in the x-axis
Jonathan Austin 1:8aa5cdb4ab67 452 *
Jonathan Austin 1:8aa5cdb4ab67 453 * @param starty the location to start the crop in the y-axis
Jonathan Austin 1:8aa5cdb4ab67 454 *
Jonathan Austin 1:8aa5cdb4ab67 455 * @param width the width of the desired cropped region
Jonathan Austin 1:8aa5cdb4ab67 456 *
Jonathan Austin 1:8aa5cdb4ab67 457 * @param height the height of the desired cropped region
Jonathan Austin 1:8aa5cdb4ab67 458 *
Jonathan Austin 1:8aa5cdb4ab67 459 * @code
Jonathan Austin 1:8aa5cdb4ab67 460 * const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; // a cute heart
Jonathan Austin 1:8aa5cdb4ab67 461 * MicroBitImage i(10,5,heart);
Jonathan Austin 1:8aa5cdb4ab67 462 * i.crop(0,0,2,2).toString() // "0,1\n1,1\n"
Jonathan Austin 1:8aa5cdb4ab67 463 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 464 */
Jonathan Austin 1:8aa5cdb4ab67 465 MicroBitImage crop(int startx, int starty, int finx, int finy);
Jonathan Austin 1:8aa5cdb4ab67 466
Jonathan Austin 1:8aa5cdb4ab67 467 /**
Jonathan Austin 1:8aa5cdb4ab67 468 * Check if image is read-only (i.e., residing in flash).
Jonathan Austin 1:8aa5cdb4ab67 469 */
Jonathan Austin 1:8aa5cdb4ab67 470 bool isReadOnly();
Jonathan Austin 1:8aa5cdb4ab67 471
Jonathan Austin 1:8aa5cdb4ab67 472 /**
Jonathan Austin 1:8aa5cdb4ab67 473 * Create a copy of the image bitmap. Used particularly, when isReadOnly() is true.
Jonathan Austin 1:8aa5cdb4ab67 474 *
Jonathan Austin 1:8aa5cdb4ab67 475 * @return an instance of MicroBitImage which can be modified independently of the current instance
Jonathan Austin 1:8aa5cdb4ab67 476 */
Jonathan Austin 1:8aa5cdb4ab67 477 MicroBitImage clone();
Jonathan Austin 1:8aa5cdb4ab67 478 };
Jonathan Austin 1:8aa5cdb4ab67 479
Jonathan Austin 1:8aa5cdb4ab67 480 #endif