Programmer's Reference Manual

Contents

basics

PixelNote programs are sequences of commands; each command either does something (like paint on the screen) or controls the commands after it (like making them loop). Commands are combined with ":" characters, and can be grouped with "(" and ")":

command
command:command:command
command:(command:command):command

For example:

cls:txt "\hHello from PixelNote"

This runs the cls command and then the txt command.

anim n:cls:disk n mod 40

This runs the anim command. anim controls any commands after it, making them repeat, so the cls and disk commands are run over and over.

cls:(anim n=1..10:disk n mod 40):cls

This runs the cls command, then runs an animated loop for 10 steps, then runs cls again. Since the anim is in parentheses, it doesn't apply to the second cls, which is outside those parentheses.

Command names, variable names, and other names are always alphabetic, and never contain numbers. PixelNote does not require spaces between letters, numbers, and symbols if it's clear what you mean. For example,

anim n:pix 10 * cos n, 10 * sin n, 5

may be written as

anim n:pix10*cos n,10*sin n,5

since the only necessary spaces are those which separate letters.

the screen

PixelNote presents you with a 101×101 square pixel "screen". Each pixel has an integer "pixel color" value. 0 is white, 1 is black, 2 through 15 are bright colors, and 16 through 255 are variations on those colors. You can set each pixel independently with the pix command; you can read the current value of each pixel with the pix function; and you can use commands such as disk, box, and txt to draw shapes and text made out of pixels.

Each pixel has an X and Y coordinate. Location (0,0) is the center of the screen; increasing X goes to the right and increasing Y goes up. So the top left is at (-50,50), and the bottom right is at (50,-50).

If you'd like to use words instead of numbers, the symbols xmin, xmax, ymin, and ymax are defined, and are equal to -50, 50, -50, and 50, respectively.

cls command - clear (or fill) the screen

cls
cls color

Fills the entire screen with a color, overwriting anything which is already there. If color is not given, defaults to 0 (which is white).

pix command - set individual pixels

pix x,y,color
pix x1,y1;x2,y2;;xN,yN,color
pix color

In the first form, sets the individual pixel at (x, y) to color. In the second form, sets multiple pixels at (x1, y1), (x2, y2), to color. In the third form, sets the pixel at the current default location (see the at command) to color.

In any of the three forms, color may be omitted (in this case also omit the comma before color), to default to color 1 (black).

line command - draws a line

line x1,y1,x2,y2,color
line x1,y1,x2,y2
line x2,y2,color
line x2,y2

Draws a line from (x1,y1) to (x2,y2).

If x1 and y1 are not given, the line starts at the current default location (see the at command). After the line command completes, the current default location is updated to (x2,y2), so a sequence of line commands can be used to draw a connected path or polygon.

box command - fills in a rectangle on the screen

box x,y,w,h,color
box x,y,w,h
box w,h,color
box w,h

Fills in a rectangle with one corner at (x,y) and another corner at (x+w,y+h) with color color. w and h may be negative if needed. If x and y are omitted, uses the current default location (see the at command).

disk command - fills in a circle on the screen

disk x,y,r,color
disk x,y,r
disk r,color
disk r

Fills in a circle with center (x,y) and radius r with color color. If x and y are omitted, uses the current default location (see the at command).

exdisk command - fills outside a circle on the screen

exdisk x,y,r,color
exdisk x,y,r
exdisk r,color
exdisk r

Sets every pixel ouside a circle with center (x,y) and radius r.

This is basically the inverse of the disk command.

photo command - get an image from the camera or photo library

photo

First, if you have drawn on the screen, the screen is updated and an animation frame is captured. The app then pops up a menu allowing the user to take a photo, pick from their photo library, reuse the last photo (if this isn't the first time), or cancel. If the user cancels this menu, PixelNote stops the program; otherwise, the photo is loaded, converted into PixelNote's color codes and resolutions, and copied into the screen. The photo pixels always cover the entire screen.

This does not change PixelNote's resolution--the image will come out a little blocky looking!

anim command - animated loop

anim:commands
anim variable:commands
anim variable=start..end:commands

Animates. This sets up a loop which runs commands, pauses, then runs it again. The pause defaults to 1/10 of a second, but you can control this by putting a pause command at the end of commands.

The first version just loops forever. The second version also loops forever, but assigns variable (which may be any alphabetic name you choose) to the loop counter, starting at 1. The third version starts variable to start, then adds or subtracts 1 each loop, stopping after it reaches end.

loop (non-animated)

variable=start..end:commands

Loops. This sets variable to start, executes commands, increments or decrements variable by 1 in the direction of end, and repeats until variable passes end.

If you loop from 1 to 5, it runs 5 times; if you loop from 1 to 1, it runs once.

Note that this does not pause between loops and therefore does not animate. Any drawing commands in commands are executed all within the same animation frame unless you place an explicit pause command in there.

eachp command - loop over pixels

eachp xname, yname:commands
eachp xname, yname shape:commands

Executes commands for every pixel on the screen, or for every pixel in the given shape (where shape is a box, disk, exdisk, or line command).

xname and yname may be any alphabetic variable names you choose. For each pixel, xname and yname are set to the X and Y coordinate, and the commands are executed.

Note that, for example,

eachp x,y:

does exactly the same thing as

x=xmin..xmax:y=ymin..ymax:

but is more compact.

case command - select commands based on conditions

case test1(commands),test2(commands),
case test1(commands),test2(commands),,(commands)

Checks each of test1, test2, etc., in order; the first one which succeeds causes its corresponding commands to execute. If none of the tests succeed, but a commands is given at the end of the list with no test, then it is run as an alternative.

Each test must compare two numeric values and may be any of the following:

x<y
x<=y
x=y
x>=y
x>y
x/=y

for less-than, less-than-or-equal, equal, greater-than-or-equal, greater-than, or not-equal, respectively.

pause command

pause
pause ms

Pauses. This simply stops and waits. If you have drawn on the screen, the screen is updated now, and if you are capturing an animation, the current screen is treated as a frame. The first version pauses for one second; the second version pauses for ms milliseconds, approximately.

copy command - copy pixels into a buffer

copy
copy box x,y,w,h
copy disk x,y,r
copy buffer box x,y,w,h
copy buffer disk x,y,r

Saves the pixel colors in a given region to a background buffer; use paste to paste them back on the screen later.

The box and disk options are exactly as in the box and disk commands. In this case, the copied shape has an "anchor point" at (x,y). This is the point used to position the shape when doing a paste.

If no box or disk is given, the entire screen is copied, and the anchor point is set to (0,0). Thus, if you run

copy:paste

then the entire screen is copied and then pasted right back on top of itself. This is useless. It is not useless, however, if you are animating or doing other work where you need to at some point restore an earlier screen.

If buffer is not given, this uses the default copy buffer; this is normally what you want to use. If buffer is given, it must be a small integer and can be used to copy multiple sets of data for later use.

paste command - paste pixels from a buffer

paste x,y
paste buffer,x,y
paste *magnification,x,y
paste *magnification,buffer,x,y

Pastes pixels copied using the copy command back onto the screen. The anchor point from the copied pixels is moved to (x,y) (this is the center of the disk, or the first corner of the box, specified in the copy command).

If buffer is not given, this uses the default copy buffer; if it is given, it must be a small integer and must match a copy buffer created by the copy command.

If magnification is given, it can be any positive number; the pixels will be scaled up (if greater than 1) or down (if less than 1) before pasting.

txt command - draw text and symbols

txt string
txt x,y,string
txt string,color
txt x,y,string,color

Draws string on the screen at (x, y), with the given color, using the current font. Use the font command to select a font (there are only a couple).

If (x,y) are omitted, the current default location is used (see the at command). After drawing a string, the default location is moved to the upper right corner of the drawn string, so that if you draw another string, it reads left to right.

If color is not given, it defaults to 1 (black).

Each font has a fixed character size, e.g. 3x5 or 5x7, in pixels. Every character in the font takes up this much space. By default, a single pixel padding is placed between each character by this command.

string may contain a variety of special codes starting with a backslash (\):

\h - Home: Moves up to the upper-left corner of the screen

\n - Newline: Moves down one line and back to the left

\w, \a, \s, \d - Move up, left, down, or right one character size

\t - Tight: Toggles off/on the single-pixel padding between characters

\1, \2, , \9: Inserts an N-pixel horizontal gap at this point in the string

font command - set current font

font n

Selects font n for subsequent txt commands.

The default font is font 1, which is a 3x5 alphanumeric font. For slightly larger text, font 2 offers 5x7 characters. Font 3 defines a variety of symbols as 7x7 characters; for example, letters A-D are the four poker suits (spade, heart, club, and diamond).

These fonts are hand-crafted, not very good, and do not define many characters. Fonts 1 and 2 cover uppercase English letters, digits, and some punctuation and other Latin-based characters. If you use a character that is not defined, it prints as a ?. This program is for graphics, not really for text.

at command - update default X, Y location

at x,y

Most commands which take X and Y coordinates allow you to omit them, in which case they use the so-called "default location". This starts out at (0,0) when you first run a program, and gets updated by drawing commands. For example, the line command updates it to the end of the line, while the txt command updates it to the upper right corner of the text string.

Use the at command to explicitly set this if needed. You will rarely need to, but it can sometimes simplify your code.

axes command - draw axes on the screen

axes

This just draws and labels the X and Y axes. This can be helpful when designing a new program, or learning PixelNote.

assignment of variable names

name=value:commands

Computes value and assigns the result to name while executing commands.

Within commands, you cannot change the value of name.

arithmetic

x+y
x-y
x*y
x/y
x div y
x mod y
-x

Addition (+), subtraction (-), multiplication (*), and division (/) are all defined as usual. Division also offers two special operators: x div y is the integer quotient of x and y, and x mod y is the integer remainder.

Normal arithmetic precedence rules are followed: a+b*c means a+(b*c). Parentheses may be used to clarify.

random selection

?start..end?
?val1,val2,val3,?

Randomly picks a value. In the first form, the value is any floating-point number in the given range (inclusive). In the second form, you list out all the values and one of them is randomly picked. The first form always operates on numbers; the second form may use strings as well. The second form may have duplicates to increase the likelihood of a given value.

magnitude (absolute value)

|number|
|x,y|

The first form computes the absolute value of number. This just makes negative numbers positive; another way of looking at it is that it just computes the distance from 0 to number.

The second form computes the distance from (0,0) to (x,y) in a 2-dimensional plane.

angle to point

<x,y>

Computes the angle, in degrees, from the positive X axis to the line from (0,0) to (x,y), counterclockwise. (x and y may be any numbers; they need not be on-screen pixel coordinates.)

For example, <1,1> is 45, <0,1> is 90, <-1,0> is 180, and <0,-1> is 270.

The value of <0,0> is defined to be 0.

rounding functions - round fractional numbers to integers

round x

Rounds x to the nearest integer, so that 1.2 becomes 1 and 1.8 becomes 2. 1.5 rounds up to 2 as well.

int x

Chops off the fractional part of x, so that 1.2, 1.8, and 1.5 all become 1, and -1.2, -1.8, and -1.5 all become -1.

ceiling x

Rounds x up to the next larger integer, so that 1.2, 1.8, and 1.5 all become 2, and -1.2, -1.8, and -1.5 all become -1.

floor x

Rounds x down to the next lower integer, so that 1.2, 1.8, and 1.5 all become 1, and -1.2, -1.8, and -1.5 all become -2.

sqrt function - square root

sqrt value

Returns the square root of value. If value is negative, ends the program with an error.

curt function - cube root

curt x

Computes the cube root of x.

sgn function - get the sign of a number

sgn x

Returns -1 if x is less than zero, 0 if x is equal to zero, or 1 if x is greater than zero.

exp function - exponential growth

exp x

Returns e raised to the power of x, where e is Euler's constant, roughly equal to 2.71828. This is the opposite of ln.

ln function - natural logarithm

ln x

Returns the natural logarithm of x. Causes an error if x is less than or equal to zero. This is the opposite of exp.

trigonometry

sin angle
cos angle
tan angle
cotan angle
sec angle
cosec angle

Returns the sine, cosine, tangent, cotangent, secant, or cosecant of angle, which must be given in degrees.

Note these identities:

tan a = sin a / cos a
cotan a = cos a / sin a
sec a = 1 / cos a
cosec a = 1 / sin a

Since both cosine and sine functions can be 0, the tangent, cotangent, secant, and cosecant functions can each create a division-by-zero error at the appropriate place. PixelNote comes with a demo program which shows all six of its trigonometric functions; that program simply skips every multiple of 90 degrees, avoiding these problems.

pix function - get current pixel color

pix(x,y)
pix(buffer, x, y)

Returns the current pixel color at (x,y). If no buffer is given, this refers to the current screen. If a buffer is given, this refers to the pixels copied into that buffer by a copy command.

If (x,y) lies outside the visible screen, this function returns 0.

last function - get pixel color from previous frame

last(x,y)

While animating, returns the pixel color at (x,y) within the previous frame. (For example, prior to the last pause or photo command, or from the last loop through an anim command.) If this is the first frame, returns 0.

relative values

~value

Computes a value relative to its context. If you say ~1 for an X coordinate, it uses the current default location's X plus 1; if you say ~-3 for a Y coordinate, it uses the current default location's Y minus 3, and if you put ~1 as the color value for a pix command, it adds 1 to the color currently in that location.