1 /** 2 * \file 3 * 4 * \brief Monochrome graphic library API header file 5 * 6 * Copyright (c) 2011-2015 Atmel Corporation. All rights reserved. 7 * 8 * \asf_license_start 9 * 10 * \page License 11 * 12 * Redistribution and use in source and binary forms, with or without 13 * modification, are permitted provided that the following conditions are met: 14 * 15 * 1. Redistributions of source code must retain the above copyright notice, 16 * this list of conditions and the following disclaimer. 17 * 18 * 2. Redistributions in binary form must reproduce the above copyright notice, 19 * this list of conditions and the following disclaimer in the documentation 20 * and/or other materials provided with the distribution. 21 * 22 * 3. The name of Atmel may not be used to endorse or promote products derived 23 * from this software without specific prior written permission. 24 * 25 * 4. This software may only be redistributed and used in connection with an 26 * Atmel microcontroller product. 27 * 28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 38 * POSSIBILITY OF SUCH DAMAGE. 39 * 40 * \asf_license_stop 41 * 42 */ 43 /* 44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> 45 */ 46 #ifndef GFX_MONO_H 47 #define GFX_MONO_H 48 49 #include <stdint.h> 50 51 #include "compiler.h" 52 53 #ifndef PROGMEM_DECLARE 54 # define PROGMEM_DECLARE(type, name) const type name 55 # define PROGMEM_T const 56 # define PROGMEM_PTR_T const * 57 # define PROGMEM_READ_BYTE(x) *(x) 58 # define PROGMEM_STRING_T const char* 59 #endif 60 61 /** 62 * \defgroup asfdoc_common2_gfx_mono Monochrome graphical display system 63 * 64 * See \ref asfdoc_common2_gfx_mono_quickstart. 65 * 66 * This library provides an interface to drawing graphics on monochrome 67 * graphical displays 68 * 69 * The graphics drivers consists of the following: 70 * - Display driver interface (gfx_mono.h) 71 * - General graphics drawing primitives (gfx_mono_generic.h) 72 * - Display specific implementation (ex. gfx_mono_ug_2832hsweg04.h) 73 * 74 * The generic drawing primitives is a library of functions for drawing 75 * graphics primitives such as lines, rectangles and circles. It uses other 76 * functions implemented by the display driver for drawing the primitives. The 77 * implementation of these functions can optionally be used by a display 78 * driver, but if the hardware of the display allows faster handling of any of 79 * the primitives, the display driver can implement it directly. 80 * 81 * The display specific drivers provides an interface to the graphical display. 82 * It implements the low level communication with the display hardware, putting 83 * pixels on the display and drawing primitives such as lines, circles and 84 * rectangles. Depending on the display driver implementation, drawing the 85 * graphics primitives might be handled by the generic graphics drawing 86 * primitives rather than the display driver itself. 87 * 88 * \section asfdoc_common2_gfx_mono_examples Examples 89 * The following examples are available for the driver: 90 * - \ref asfdoc_common2_gfx_mono_quickstart 91 * - \ref asfdoc_common2_gfx_mono_sysfont_example 92 * - \ref asfdoc_common2_gfx_mono_spinner_example 93 * 94 * \section asfdoc_common2_gfx_mono_api_overview API Overview 95 * 96 * \note The functions in the library are not interrupt safe. 97 * @{ 98 */ 99 100 typedef uint8_t gfx_mono_color_t; 101 typedef uint8_t gfx_coord_t; 102 103 /** Pixel operations */ 104 enum gfx_mono_color { 105 /** Pixel is cleared */ 106 GFX_PIXEL_CLR = 0, 107 /** Pixel is set on screen (OR) */ 108 GFX_PIXEL_SET = 1, 109 /** Pixel is XORed */ 110 GFX_PIXEL_XOR = 2, 111 }; 112 113 /** Bitmap types */ 114 enum gfx_mono_bitmap_type { 115 /** Bitmap stored in SRAM */ 116 GFX_MONO_BITMAP_RAM, 117 /** Bitmap stored in progmem */ 118 GFX_MONO_BITMAP_PROGMEM 119 }; 120 121 /* Cannot be moved to top, as they use the bitmap and color enums. */ 122 #ifdef USE_SDL 123 # include "gfx_mono_sdl.h" 124 #elif defined(GFX_MONO_C12832_A1Z) 125 # include "gfx_mono_c12832_a1z.h" 126 #elif defined(GFX_MONO_UG_2832HSWEG04) 127 # include "gfx_mono_ug_2832hsweg04.h" 128 #else 129 /* NULL driver by default */ 130 # include "gfx_mono_null.h" 131 #endif 132 #include "gfx_mono_generic.h" 133 134 /** \name Circle Sector Definitions */ 135 /** @{ */ 136 137 /** Bitmask for drawing circle octant 0. */ 138 #define GFX_OCTANT0 (1 << 0) 139 /** Bitmask for drawing circle octant 1. */ 140 #define GFX_OCTANT1 (1 << 1) 141 /** Bitmask for drawing circle octant 2. */ 142 #define GFX_OCTANT2 (1 << 2) 143 /** Bitmask for drawing circle octant 3. */ 144 #define GFX_OCTANT3 (1 << 3) 145 /** Bitmask for drawing circle octant 4. */ 146 #define GFX_OCTANT4 (1 << 4) 147 /** Bitmask for drawing circle octant 5. */ 148 #define GFX_OCTANT5 (1 << 5) 149 /** Bitmask for drawing circle octant 6. */ 150 #define GFX_OCTANT6 (1 << 6) 151 /** Bitmask for drawing circle octant 7. */ 152 #define GFX_OCTANT7 (1 << 7) 153 154 /** Bitmask for drawing circle quadrant 0. */ 155 #define GFX_QUADRANT0 (GFX_OCTANT0 | GFX_OCTANT1) 156 /** Bitmask for drawing circle quadrant 1. */ 157 #define GFX_QUADRANT1 (GFX_OCTANT2 | GFX_OCTANT3) 158 /** Bitmask for drawing circle quadrant 2. */ 159 #define GFX_QUADRANT2 (GFX_OCTANT4 | GFX_OCTANT5) 160 /** Bitmask for drawing circle quadrant 3. */ 161 #define GFX_QUADRANT3 (GFX_OCTANT6 | GFX_OCTANT7) 162 163 /** Bitmask for drawing left half of circle. */ 164 #define GFX_LEFTHALF (GFX_QUADRANT3 | GFX_QUADRANT0) 165 /** Bitmask for drawing top half of circle. */ 166 #define GFX_TOPHALF (GFX_QUADRANT0 | GFX_QUADRANT1) 167 /** Bitmask for drawing right half of circle. */ 168 #define GFX_RIGHTHALF (GFX_QUADRANT1 | GFX_QUADRANT2) 169 /** Bitmask for drawing bottom half of circle. */ 170 #define GFX_BOTTOMHALF (GFX_QUADRANT2 | GFX_QUADRANT3) 171 172 /** Bitmask for drawing whole circle. */ 173 #define GFX_WHOLE 0xFF 174 175 /** @} */ 176 177 /** \name Graphic Drawing Primitives */ 178 /** @{ */ 179 180 /** 181 * \def gfx_mono_draw_horizontal_line(x, y, length, color) 182 * \brief Draw a horizontal line, one pixel wide. 183 * 184 * \param[in] x X coordinate of leftmost pixel. 185 * \param[in] y Y coordinate of the line. 186 * \param[in] length Length of the line in pixels. 187 * \param[in] color Pixel operation of the line. 188 */ 189 190 /** 191 * \def gfx_mono_draw_vertical_line(x, y, length, color) 192 * \brief Draw a vertical line, one pixel wide. 193 * 194 * \param[in] x X coordinate of the line. 195 * \param[in] y Y coordinate of the topmost pixel. 196 * \param[in] length Length of the line in pixels. 197 * \param[in] color Pixel operation of the line. 198 */ 199 200 /** 201 * \def gfx_mono_draw_line(x1, y1, x2, y2, color) 202 * \brief Draw a line between two arbitrary points. 203 * 204 * \param[in] x1 Start X coordinate. 205 * \param[in] y1 Start Y coordinate. 206 * \param[in] x2 End X coordinate. 207 * \param[in] y2 End Y coordinate. 208 * \param[in] color Pixel operation of the line. 209 */ 210 211 /** 212 * \def gfx_mono_draw_rect(x, y, width, height, color) 213 * \brief Draw an outline of a rectangle. 214 * 215 * \param[in] x X coordinate of the left side. 216 * \param[in] y Y coordinate of the top side. 217 * \param[in] width Width of the rectangle. 218 * \param[in] height Height of the rectangle. 219 * \param[in] color Pixel operation of the line. 220 */ 221 222 /** 223 * \def gfx_mono_draw_filled_rect(x, y, width, height, color) 224 * \brief Draw a filled rectangle. 225 * 226 * \param[in] x X coordinate of the left side. 227 * \param[in] y Y coordinate of the top side. 228 * \param[in] width Width of the rectangle. 229 * \param[in] height Height of the rectangle. 230 * \param[in] color Pixel operation of the line 231 */ 232 233 /** 234 * \def gfx_mono_draw_circle(x, y, radius, color, octant_mask) 235 * \brief Draw an outline of a circle or arc. 236 * 237 * The radius is the distance from the center to the circumference, 238 * which means that the total width or height of a circle will be 239 * (radius*2+1). 240 * 241 * The octant_mask parameter is a bitmask that decides which octants of 242 * the circle to draw. Use the GFX_OCTANTn, GFX_QUADRANTn, GFX_xHALF and 243 * GFX_WHOLE constants and OR them together if required. Radius equal to 244 * zero gives a single pixel. 245 * 246 * \param[in] x X coordinate of center. 247 * \param[in] y Y coordinate of center. 248 * \param[in] radius Circle radius in pixels. 249 * \param[in] color Pixel operation. 250 * \param[in] octant_mask Bitmask indicating which octants to draw. 251 */ 252 253 /** 254 * \def gfx_mono_draw_filled_circle(x, y, radius, color, quadrant_mask) 255 * \brief Draw a filled circle or sector. 256 * 257 * The radius is the distance from the center to the circumference, 258 * which means that the total width or height of a circle will be 259 * (radius*2+1). 260 * 261 * The quadrant_mask parameter is a bitmask that decides which quadrants 262 * of the circle to draw. Use the GFX_QUADRANTn, GFX_xHALF and 263 * GFX_WHOLE constants and OR them together if required. Radius equal to 264 * zero gives a single pixel. 265 * 266 * \note This function only supports quadrants while gfx_draw_circle() 267 * supports octants. This is to improve performance on drawing 268 * filled circles. 269 * 270 * \param[in] x X coordinate of center. 271 * \param[in] y Y coordinate of center. 272 * \param[in] radius Circle radius in pixels. 273 * \param[in] color Pixel operation. 274 * \param[in] quadrant_mask Bitmask indicating which quadrants to draw. 275 */ 276 277 /** @} */ 278 279 /** @} */ 280 281 /** 282 * \page asfdoc_common2_gfx_mono_quickstart Quick Start Guide for the mono graphics service 283 * 284 * This is the quick start guide for the \ref asfdoc_common2_gfx_mono "Monochrome Graphics service", 285 * with step-by-step instructions on how to configure and use it for a specific 286 * use case. 287 * 288 * \section asfdoc_common2_gfx_mono_quickstart_basic Basic usage of the graphics service 289 * This use case will demonstrate initializing the mono graphics service and 290 * then draw a black line on the screen from coordinates X=10, Y=10 to X=20, 291 * Y=20. 292 * 293 * \section asfdoc_common2_gfx_mono_basic_usage Usage steps 294 * \subsection asfdoc_common2_gfx_mono_basic_usage_code Example code 295 * Add to, e.g., the main function in the application C-file: 296 * \code 297 system_init(); 298 gfx_mono_init(); 299 gfx_mono_draw_line(10, 10, 20, 20, GFX_PIXEL_SET); 300 \endcode 301 * 302 * \subsection gfx_mono_basic_usage_workflow Workflow 303 * -# Initialize system: 304 * - \code system_init(); \endcode 305 * -# Initialize monochrome graphics service 306 * - \code gfx_mono_init(); \endcode 307 * - \note This will call the init function for the low level display 308 * controller driver and intialize the screen to a cleared background. 309 * -# Draw a line from 10,10 to 20,20: 310 * - \code gfx_mono_draw_line(10, 10, 20, 20, GFX_PIXEL_SET); \endcode 311 * - \note This uses GFX_PIXEL_SET to set the display pixels on the line; 312 * other options can be found in \ref gfx_mono_color. 313 */ 314 315 /** 316 * \page asfdoc_common2_gfx_mono_exqsg Examples for GFX Mono Library 317 * 318 * This is a list of the available Quick Start guides (QSGs) and example applications 319 * for \ref asfdoc_common2_gfx_mono. QSGs are simple examples with step-by-step instructions 320 * to configure and use this driver in a selection of use cases. Note that QSGs can be compiled as 321 * a standalone application or be added to the user application. 322 * - \subpage asfdoc_common2_gfx_mono_quickstart 323 * - \subpage asfdoc_common2_gfx_mono_font_quickstart 324 * - \subpage asfdoc_common2_gfx_mono_sysfont_example 325 * - \subpage asfdoc_common2_gfx_mono_spinner_example 326 * 327 */ 328 329 330 #endif /* GFX_MONO_H */ 331