Drawing

The Drawing built-in functions give you full access to the display/LED-matrix. This is nice to have in most cases and becomes a requirement in some, like when creating video games.

Prerequisite

This lesson assumes you have completed the Built-in Function lesson.

Intro

Until now in C#, we have been working with the required ‘using static BrainPad.Controller;’. However, the Drawing Functions in C# use a different namespace and requires adding ‘using static BrainPad.Display’. Python users only need to add ‘from BrainPad import *‘ as usual since the drawing library is built-in.

using static BrainPad.Controller;
using static BrainPad.Display;
 
Text("Hello World",30,30);
Show();

from BrainPad import *

Text("Hello World",30,30)
Show()

Graphical Memory

On computer systems, it is standard to handle all the “drawing” in memory, not on the display/monitor. Only when drawing elements of the memory is complete does the memory transfer to the display as a whole. Similar to the way our own brain works, we think about what we’re going to draw in our mind and then we draw it.

Even when clearing the screen, Clear() will only clear the graphics memory internally. This has no effect on the display. But then Show() will transfer whatever is in the graphical memory to the screen.

Note how Print() updates the screen without Show(). This is because of extra code built into the Print() function to make it easier to use. However, this makes Print() slower than the other drawing functions. Once you have decided you will use the display API on this page, you should not use Print() to eliminate confusion.

X and Y coordinates

X and Y coordinates inside code refers to an exact pixel location on the screen. This is often used to set the position of where something will appear on the screen.

Unlike vectors in math where x/y origin start at the lower left corner, computer graphics start at the top left corner.

With origin starting at the top left corner, X values run left to right starting at 0 on the very left., while Y values run top to bottom starting with 0 at the very top. This means the top left X and Y coordinate is 0,0. The BrainPad Pulse has 128 pixels across (X) by 64 pixels down (Y), making the bottom right corner 127,63 (remember 0 is the first pixel, not 1).

Show()

This function will transfer the graphical memory to the display as explained above. All methods below only affect the graphical memory and do not affect the display at all.

Circle()

Circle() generates a circle in memory, remember we must call Show() to actually see the circle on the display. The Circle(x, y, r) function requires 3 arguments: an x and y position on the display, and the r is the radius of the circle.

Circle(60,32,25);
Show();

Circle(60,32,25)
Show()

Line()

Line() does exactly as its name suggests. It creates a line from one point to another point. The Line(x1, y1, x2, y2) function requires 4 arguments: the x and y starting position followed by the x and y finishing position. Like all other drawing methods you’ll still need to call Show() to actually display the line on the screen.

Line(25,21,100,50);
Show();

Line(25,21,100,50)
Show()

Text()

This is similar to the basic Print() function, but Text() gives you better control as to where the text is placed on the screen. The Text(text, x, y) function takes 3 arguments: first is the text to be displayed followed by its x and y location on the screen. Unlike the Print() function , you’ll have to follow with the Show() function to display.

Text("Hello Brain",30,30);
Show();

Text("Hello Brain",30,30)
Show()

TextEx()

TextEx() function works like the Text() method except it adds scaling so you can make larger text or tall skinny text, depending on how you change the scale. The TextEx(text, x, y, scaleWidth, scaleHeight) function takes 5 arguments. The first three are exactly the same as the Text() function . The last two arguments set the scale width and scale height. Scale 1 is the standard size, 2 is double the size and so on.

TextEx("Large Text",0,30,2,2);
Show();

TextEx("Large Text",0,30,2,2)
Show()

Rect()

The Rect() function Draws a rectangle on the screen. Rect(x, y, w, h) requires 4 arguments: x coordinate, y coordinate, width, and then height.

Rect(40,10,50,50);
Show();

Rect(40,10,50,50)
Show()

How do you draw a Rect() that sets a border on the very edges of the screen? If the display is 128×64 in size and the screen starts at 0x0, what would the last pixel be, 127×63 or 128×64?

FillRect()

Works just like Rect() function, but this one will fill the rectangle: FillRect(x, y, w, h).

FillRect(40, 10, 50, 50);
Show();

FillRect(40, 10, 50, 50)
Show()

This is also useful to clear part of the screen by setting Color() to black, and then FillRect() over the area you want to “clear”. Naturally if the area you want to clear is white, they you use a white filled rectangle. Let’s continue to learn about more about color from here.

Color()

Sets the color of all the following drawing calls, until Color() is set again. An example can be to draw a white filled rectangle FillRect(), and then draw black text inside it.

To make things a bit easier, we have predefined some built-in color variables: Black, White, Red, Green, Blue, Yellow, Magenta and Cyan. Note that devices like BrainPad Pulse and BrainPad Tick have no color. The Pulse is always Black and White and the Tick has Orange LEDs. In this case, Color() will treat any color as active and only black will be inactive. An active LED on Pulse is White and an active LED on Tick is Orange.

Color(White);
FillRect(15, 10, 100, 50);
Color(Black);
Text("Hello World", 30, 30);
Show();

Color(White);
FillRect(15, 10, 100, 50)
Color(Black)
Text("Hello World", 30, 30)
Show()

The Color() function also accepts a HEX value. This is commonly used to set color. HEX numbers always start with 0x followed by the color value. WHITE would be 0xFFFFF while BLACK would be 0x0000. There are many places on the Internet to find specific color values. Just google “Color Picker” and you will find many options. Note, however, that some places use # symbol before the color instead of 0x. For example, the BrainPad orange color is #F08000 on the web, but in coding it is 0xF08000.

var black = 0x00000;
FillRect(15,10,100,50);
Color(black);
Text("Hello World", 30, 30);
Show();

black = 0x00000
FillRect(15,10,100,50)
Color(black)
Text("Hello World", 30, 30)
Show()

Point()

Draws a point (a pixel) on the screen. The Point() function requires 3 arguments. First is the x coordinate on the display, second is the y coordinate. The last is the color. Note that Point() is the only function not affected by Color(), and instead needs color as the last argument.

Point(64,32,White);
Show();

Point(64,32,White)
Show()

You may have to look VERY closely to see the pixel on the screen. The BrainPad Pulse in particular has 8,192 of them that make up the entire screen.

A single point is not much fun. We need to try something more interesting! Let’s get a random number to use as a random location on where the next point should be. We think you will like the results.

var rnd = new System.Random();

Clear();
while(true){
    var x = rnd.Next(127);
    var y = rnd.Next(63);
    Point(x, y, White);
    Show();
}

import random

Clear()
while True:
    x = random.randint(0,127)
    y = random.randint(0,64)
    Point(x, y, White)
    Show()
   

Clear()

Clears the screen. Remember, this clears the graphical memory and not the display. Show() is needed to transfer the graphical memory to the display. For the sake of demonstration, we will draw a line on the screen, then Clear() the screen, then draw a circle. Running the code below will result in a circle on the screen but not the line. Why? The line was drawn on the graphical memory, which got cleared using Clear(). Then the circle was drawn on the graphical memory and then show transferred the memory to the display.

Line(20,30, 88, 44);
Clear();
Circle(60,32,25);
Show();

Line(20,30, 88, 44)
Clear()
Circle(60,32,25)
Show()

A better example would be to move a Circle() on the screen. The circle will move on the x axis from 10 to 100 with 3 steps in each loop. Note that the Circle() is NOT moving! Your eyes see it moving, but it is actually just a new circle that is getting drawn on a new location while clearing the old one.

var x = 10;
while(x<100){
    Clear();
    Circle(x, 32, 10);
    Show();
    x = x + 3;
}

x = 10
while x<100:
    Clear()
    Circle(x,32,10)
    Show()
    x = x + 3
   

Try removing the Clear() function from the code above and try again. What do you think the screen would look like?

CreateImage()

CreateImage() function is used to create an image that we’ll then later use with the Image() function to actually position it on the screen. One of the arguments required for the CreateImage() function can take either a string or an array. Let’s make the image inside the array first.

You can use any color in the array (White, Red, 0xF0800 …etc.), but it is easier to just use 0 for black and 1 to activate the point. This is okay on BrainPad Pulse as it is black and white and treats any color, including 1, as White.

var alien = new byte[] {
0, 0, 0, 1, 1, 0, 0, 0,
0, 0, 1, 1, 1, 1, 0, 0,
0, 1, 1, 1, 1, 1, 1, 0,
1, 1, 0, 1, 1, 0, 1, 1,
1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 1, 0, 0, 1, 0, 0,
0, 1, 0, 1, 1, 0, 1, 0,
1, 0, 1, 0, 0, 1, 0, 1};

alien =  [
0, 0, 0, 1, 1, 0, 0, 0,
0, 0, 1, 1, 1, 1, 0, 0,
0, 1, 1, 1, 1, 1, 1, 0,
1, 1, 0, 1, 1, 0, 1, 1,
1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 1, 0, 0, 1, 0, 0,
0, 1, 0, 1, 1, 0, 1, 0,
1, 0, 1, 0, 0, 1, 0, 1]

The above array is laid out as 8 columns with 8 rows. Meaning our image will ultimately be 8×8 points.

It can be tricky to see the image using the array. Now let’s try the same art but with a string this time. Using a string makes the image we’re creating a bit easier to visualize in code. To do this we use spaces to represent blank areas and then any character to create a white pixel. Note that you can’t set colors when using strings, but this is not an issue if your device is black and white anyway.

Pick a character that is easy for you to see. We’ll us X in our example. You can also use O instead.

var alien = 
"   XX   " +
"  XXXX  " +
" XXXXXX " +
"XX XX XX" +
"XXXXXXXX" +
"  X  X  " +
" X XX X " +
"X X  X X" ;

alien = (
"   XX   " +
"  XXXX  " +
" XXXXXX " +
"XX XX XX" +
"XXXXXXXX" +
"  X  X  " +
" X XX X " +
"X X  X X" )

See how using a string makes the image a bit easier to visualize?

Now that we’ve created the array we can use the CreateImage() function, which requires 6 arguments. The first two are the size of the image. We know our image is 8×8, so these are the first 2 arguments for the size. The 3rd argument is the alien we created first. The 4th and 5th arguments are used to scale the image horizontally and vertically. The final argument is the transformation of the image, covered in the table below.

var alien = 
"   XX   " +
"  XXXX  " +
" XXXXXX " +
"XX XX XX" +
"XXXXXXXX" +
"  X  X  " +
" X XX X " +
"X X  X X" ;

var monsterImage = CreateImage(8,8,alien,1,1,0);

alien = (
"   XX   " +
"  XXXX  " +
" XXXXXX " +
"XX XX XX" +
"XXXXXXXX" +
"  X  X  " +
" X XX X " +
"X X  X X" )
 
monsterImage = CreateImage(8,8,alien,1,1,0)

The code we above creates the image but doesn’t show it yet. We need the next function Image() to display.

Image()

Image() function requires 3 arguments: the image we created using CreateImage() and the x and y position where it will appear on the screen.

var alien = 
"   XX   " +
"  XXXX  " +
" XXXXXX " +
"XX XX XX" +
"XXXXXXXX" +
"  X  X  " +
" X XX X " +
"X X  X X" ;

var monsterImage = CreateImage(8,8,alien,1,1,0);

Image(monsterImage,55,30);
Show();

alien = (
"   XX   " +
"  XXXX  " +
" XXXXXX " +
"XX XX XX" +
"XXXXXXXX" +
"  X  X  " +
" X XX X " +
"X X  X X" )
 
monsterImage = CreateImage(8,8,alien,1,1,0)

Image(monsterImage,55,30)
Show()

What is the easiest way to make the alien larger? Remember there are scale arguments in CreateImage(). Go back to the previous example and change the one line below.

var monsterImage = CreateImage(8,8,alien,2,3,0);

monsterImage = CreateImage(8,8,alien,2,3,0)

Can you now move the Alien across the screen like we did with the Circle()? Or make him show everywhere randomly like we did with the Point()?

Brightness()

Brightness() function is BrainPad Tick specific and used to set the brightness of the LEDs. The Brightness() function takes 1 argument: the level of brightness from 0-100. The LEDs on the BrainPad Tick are very bright. Keep them at about 1/2 (50%) or less. Note how Show() is not needed with Brightness().

Print("T");
Brightness(20);

Print("T")
Brightness(20)

What’s Next?

Draw on the screen, and have fun! Trying changing the different values inside the Line() function to see what kind of math art you can create.

var x = 0;
var y = 0;
 
while (true){ 
    Line(0,0,x,63);
    Show();
    x = x + 15;
}

x = 0
y = 0
 
while True: 
    Line(0,0,x,63)
    Show()
    x = x + 15

Try to put everything together from loops and variables. From here you can jump right to the Math Art lesson.

BrainStorm

Why do buttons on PC applications look similar? That is because Windows has a built-in “Button()” that developers typically use. Can you create a method that draws a “button”? Hint: This is nothing more than a Rect() with Text() in it. For extra credit, can you make the button scale automatically to the text length?