Skip to content

Commit 3edd99a

Browse files
karlsoderbykarlsoderby
authored
Merge pull request #529 from arduino/karlsoderby/gds-gfx
Karlsoderby/gds gfx
2 parents 812a52e + 027a778 commit 3edd99a

File tree

1 file changed

+232
-0
lines changed
  • content/hardware/10.mega/shields/giga-display-shield/tutorials/gfx-guide

1 file changed

+232
-0
lines changed

‎content/hardware/10.mega/shields/giga-display-shield/tutorials/gfx-guide/gfx-guide.md

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: 'GIGA Display Shield GFX Guide'
3+
description: 'Learn how to draw shapes, print text and other useful methods with the GFX library.'
4+
author: 'Karl Söderby'
5+
tags: [Displays, GIGA, GFX]
6+
---
7+
8+
The [GIGA Display Shield](/hardware/giga-display-shield) is compatible with the [Adafruit_GFX](https://github.com/adafruit/Adafruit-GFX-Library) graphics core library.
9+
10+
To access it, we can use a layer library called [Arduino_GigaDisplay_GFX](https://github.com/arduino-libraries/Arduino_GigaDisplay_GFX) designed specifically for the shield. In this guide, we will get started with some of the essential methods of the library, that will allow us to e.g. print values, text, draw shapes.
11+
12+
## Goals
13+
14+
In this guide we will cover:
15+
- Learn how to draw and print to the display,
16+
- how to draw basic shapes (circles, rectangles etc)
17+
- how to update values on the screen,
18+
19+
## Hardware & Software Needed
20+
21+
- [GIGA R1 WiFi](/hardware/giga-r1).
22+
- [GIGA Display Shield](/hardware/giga-display-shield)
23+
- [Arduino IDE](https://www.arduino.cc/en/software)
24+
25+
## Installation
26+
27+
To install the library, open the Arduino IDE and search for the **Arduino_GigaDisplay_GFX** library in the **Library Manager**.
28+
29+
You can also manually download the library in the official GitHub repository. For any issues with the libraries, please report them here as well.
30+
- [Arduino_GigaDisplay_GFX](https://github.com/arduino-libraries/Arduino_GigaDisplay_GFX)
31+
32+
## Basic Example
33+
34+
The [Arduino_GigaDisplay_GFX](https://github.com/arduino-libraries/Arduino_GigaDisplay_GFX) is a layer library for the [Adafruit_GFX](https://github.com/adafruit/Adafruit-GFX-Library) library that's been around for some years now. The full documentation for this library can be found [here](https://learn.adafruit.com/adafruit-gfx-graphics-library).
35+
36+
The library provides graphic functions for drawing individual pixels, rectangles, circles, lines and other geometrical shapes. It also provides support for printing numeric values & strings directly on the display.
37+
38+
To use the library, we simply need to create a display object, initialize the library, change something and print it on the display. See this minimal example below:
39+
40+
```arduino
41+
#include "Arduino_GigaDisplay_GFX.h"
42+
43+
GigaDisplay_GFX display; // create the object
44+
45+
void setup() {
46+
display.begin(); //init library
47+
48+
display.setCursor(10,10); //x,y
49+
display.setTextSize(5); //adjust text size
50+
display.print("Hello World!"); //print
51+
}
52+
void loop(){}
53+
```
54+
55+
The above example will simply print `Hello World!` at the `x` and `y` coordinates (10,10). Simple as that.
56+
57+
## Methods Overview
58+
59+
There are several methods available. In this section, we will list out a number of useful ones. To see the full list, check out Adafruit's documentation of this library in [this page](https://learn.adafruit.com/adafruit-gfx-graphics-library).
60+
61+
### Coordinates
62+
63+
The coordinates in the GFX library is easy to work with. Most methods have the coordinates as parameters (x,y). To set the cursor (position) on the display, you can utilize the following method:
64+
65+
- `setCursor(x, y)` - set the cursor on the display.
66+
67+
### Color
68+
69+
To change color of text, pixels, background etc, you can first define the color using the RGB565 format:
70+
71+
- `#define YELLOW 0xFFE0`
72+
73+
Then use it anywhere in the code for coloring, such as:
74+
- `fillScreen(YELLOW)` - sets the background color for the display.
75+
- `drawPixel(x, y, YELLOW)` - color a single pixel.
76+
- `setTextColor(YELLOW)` - color the text.
77+
- `fillRect(x, y, width, height, YELLOW)` color a rectangle.
78+
79+
Read more about the color format and generate the colors your want at the following page:
80+
- [RGB Color Picker](https://rgbcolorpicker.com/565) (external link)
81+
82+
### Text
83+
84+
To display text on the screen, use the following methods:
85+
86+
- `setTextSize(size)` - set the size for the text. Any number between `1` (very small) to `80` (one digit covers the screen) works on this display.
87+
- `setTextColor(color,background_color)` - sets color and optionally background color. This is useful when overwriting an existing number (like printing sensor values continuously).
88+
- `print(content)` print something to the screen.
89+
90+
A minimal example for using text methods can be found below:
91+
92+
```arduino
93+
#include "Arduino_GigaDisplay_GFX.h"
94+
95+
GigaDisplay_GFX display; // create the object
96+
97+
#define BLACK 0x0000
98+
99+
void setup() {
100+
display.begin();
101+
display.fillScreen(BLACK);
102+
display.setCursor(10,10); //x,y
103+
display.setTextSize(5); //adjust text size
104+
display.print("Hello World!"); //print
105+
}
106+
void loop(){}
107+
```
108+
109+
### Pixels & Shapes
110+
111+
To draw pixels and shapes, use the following methods.
112+
113+
- `drawPixel(x, y, color)` - draws a pixel at the coordinates specified.
114+
- `drawRect(x, y, height, width, color)` - draws a rectangle at the coordinates with the height and width & color specified.
115+
- `drawRoundRect(x, y, height, width, border-radius, color)` - rounded rectangle with the border-radius specified.
116+
- `drawTriangle(x0, y0, x1, y1, x2, y2, color)` - draws a triangle at the coordinates specified.
117+
- `drawCircle(x, y, radius, color)` - draws a circle with specified radius.
118+
119+
The above methods will draw the desired shape's outline, but it will not fill it. To do so, simply use `fillRect()`, `fillTriangle()` etc.
120+
121+
A minimal example for drawing geometrical shapes can be seen below:
122+
123+
```arduino
124+
#include "Arduino_GigaDisplay_GFX.h"
125+
126+
GigaDisplay_GFX display;
127+
128+
#define WHITE 0xffff
129+
#define BLACK 0x0000
130+
131+
void setup() {
132+
display.begin();
133+
display.fillScreen(WHITE);
134+
display.drawTriangle(100, 200, 300, 400, 300, 600, BLACK);
135+
display.drawCircle(100, 100, 50, BLACK);
136+
display.drawRect(10, 650, 300, 80, BLACK);
137+
display.drawRoundRect(300, 50, 100, 100, 30, BLACK);
138+
}
139+
void loop() {}
140+
```
141+
142+
## GFX & Touch Example
143+
144+
The GFX library can be used together with the [Arduino_GigaDisplay_Touch](https://github.com/arduino-libraries/Arduino_GigaDisplayTouch) library. The below example demonstrates how to read a touch point and trigger a function, using a simple if statement.
145+
146+
The example below is very minimal, and it simply switches on and off a boolean whenever the screen is touched. But it is a good example to get started with if you plan to build your own UI with a touch interface.
147+
148+
```arduino
149+
#include "Arduino_GigaDisplay_GFX.h"
150+
#include "Arduino_GigaDisplayTouch.h"
151+
152+
Arduino_GigaDisplayTouch touchDetector;
153+
GigaDisplay_GFX display;
154+
155+
#define WHITE 0xffff
156+
#define BLACK 0x0000
157+
158+
#define screen_size_x 480
159+
#define screen_size_y 800
160+
161+
int touch_x;
162+
int touch_y;
163+
164+
//increase or decrease the sensitivity of the touch.
165+
int trigger_sensitivity = 5;
166+
bool switch_1;
167+
int counter;
168+
169+
void setup() {
170+
// put your setup code here, to run once:
171+
Serial.begin(9600);
172+
display.begin();
173+
174+
if (touchDetector.begin()) {
175+
Serial.print("Touch controller init - OK");
176+
} else {
177+
Serial.print("Touch controller init - FAILED");
178+
while (1)
179+
;
180+
}
181+
}
182+
183+
void loop() {
184+
uint8_t contacts;
185+
GDTpoint_t points[5];
186+
contacts = touchDetector.getTouchPoints(points);
187+
188+
if (contacts > 0) {
189+
Serial.print("Contacts: ");
190+
Serial.println(contacts);
191+
192+
counter++;
193+
194+
//record the x,y coordinates
195+
for (uint8_t i = 0; i < contacts; i++) {
196+
touch_x = points[i].x;
197+
touch_y = points[i].y;
198+
}
199+
200+
//as the display is 480x800, any time you touch the screen it will trigger
201+
//the trigger sensitivity is set to "5".
202+
if (touch_x < screen_size_x && touch_y < screen_size_y && counter > trigger_sensitivity) {
203+
switch_1 = !switch_1;
204+
Serial.println("switched");
205+
changeSwitch();
206+
delay(250);
207+
}
208+
}
209+
}
210+
211+
void changeSwitch() {
212+
if (switch_1) {
213+
display.fillScreen(BLACK);
214+
display.setTextColor(WHITE);
215+
} else {
216+
display.fillScreen(WHITE);
217+
display.setTextColor(BLACK);
218+
}
219+
display.setCursor(50, screen_size_y/2);
220+
display.setTextSize(5);
221+
display.print("Switched");
222+
counter = 0;
223+
}
224+
```
225+
226+
***Learn more about the Giga Display's touch interface in the [Touch Interface Guide](/tutorials/giga-display-shield/basic-touch).***
227+
228+
## Summary
229+
230+
In this guide we have covered some basic methods of the GFX library, such as writing text, drawing rectangles and changing colors & text sizes. The GFX library is easy to get started with for beginners, but can also be used to build sophisticated and powerful UIs with advanced usage.
231+
232+
For more tutorials, visit the [documentation page for GIGA Display Shield](/hardware/giga-display-shield).

0 commit comments

Comments
 (0)