PAINT

Syntax: paint [step] (x, y)[, [paint color][, [border color][, background]]]
Type: statement
Category: Gfx

Graphics command to fill an area with a color touching the borders. Also known as 'flood-fill' or 'paint bucket'.

If the 'paint' argument is a number, it is assumed a color in the same format used by the COLOR statement, and the region is flood-filled using that color. If 'paint' is a string, the region will be filled using a pattern; the pattern is always 8x8 pixels, and the passed string must hold pixels data in a format dependent on the current color depth. The string holds pattern pixels row by row, and its size should be as follows:

If the passed string is smaller, missing pixels will be 0. Flood-filling continues until pixels of the specified border color are found.

e.g. to draw a white circle painted blue inside, then waits 3 seconds.

dim t as single

screen 13
circle (160, 100), 30, 15
paint (160, 100), 1, 15

t = timer
do
loop until timer > t + 3

Differences:
Between QB:
The QB additional background parameter is not supported.

PALETTE

PALETTE can now be called with 4 parameters, specifying new color red/green/blue components directly (lillo)

Statement to customize current palette.

'index' is the index of the color to be customized.

'color' is the new color RGB value for specified index.

'arrayname(idx)' is the array of color values to be set.

The PALETTE statement is used to customize the current palette for gfx modes with a color depth of up to 8bpp; using PALETTE while in a mode with a higher color depth will have no effect. Calling PALETTE with no argument restores the default palette for current gfx mode.

If you specify index and color, these are dependent on the current mode:

In screen modes 1, 2, 7, 8 and 9 you can assign to each color index one of the colors in the available range. In other screen modes, the color must be specified in the form &hBBGGRR, where BB, GG and RR are the blue, green and red components ranging &h0-&h3F in hexadecimal (0-63 in decimal). If you don't like hexadecimal form, you can use the following formula to compute the integer value to pass to this parameter:

color = red or (green shl 8) or (blue shl 16)

Where red, green and blue must range 0-63. The available colors are reset by the SCREEN (graphics) statement to a default palette; see appendix B for details. You can alter the contents of the current palette using the PALETTE statement for modes with a color depth higher or equal to 8, or by using the OUT statement in lower depth modes. Calling PALETTE USING allows to set a list of color values all at once; you should pass an array holding enough elements as the color indices available for your current gfx mode color depth (2 for 1bpp, 4 for 2bpp, 16 for 4bpp or 256 for 8bpp). The array elements must be integer color values in the form described above. The colors stored into arrayname starting with given idx index are then assigned to each palette index, starting with index 0. Any change to the palette is immediately visible on screen.

See also SCREEN (graphics), COLOR, OUT, Default palettes.

pascal

Forces the standard pascal calling convention when calling a sub/function.

This exists for compadibility with pascal libraries, so that they can be used with FreeBasic.

See also declare, cdecl, pascal, stdcall.

PCOPY

Copies one video page to another. Useful for drawing all graphics on one invisible page and copying it to the active visible page - creating smooth graphics and animation. Known as 'double buffering' or 'page flipping'.

'source' and 'destination' refer to page numbers. The 'source' page is copied over the 'destination' page when pcopy is called.

See also FLIP, SCREENCOPY.

PEEK

Syntax:
peek(address) as byte (8bit)
peeks(address) as short (16bit)
peeki(address) as integer (32bit)

Peek (in all forms: peek, peeks, and peeki) return the value in memory given by a memory address. This was how pointer features were coded in the old basic dialects.
PEEK and POKE now accept STRING and UDT's as data type (v1c)

e.g. of getting the address of a variable and reading its contents by its address:

dim x as byte, addr as integer
addr = varptr(x)
x = 5
print x
print peek(addr)

peeki

peeks

PMAP

Function to map coordinates between view and physical mapping.

'coord' is an expression indicating the coordinate to be mapped.

'func' is the mapping function number to be applied to given coordinate.

This function allows to convert a coordinate between view (as defined by the WINDOW statement) and physical (as set by the VIEW (graphics) statement) mappings. Depending on the value of func, expr is used to compute a different mapping to be returned by PMAP:

POINT

Function to read a pixel color or coordinate.

Syntax:
POINT(x, y)
POINT(func)

'(x, y)' are coordinates of the pixel.

Alternatively, 'func' specify which coordinate mapping to return.

When called with two arguments, the specified (x,y) coordinates are affected by the most recent WINDOW and VIEW (graphics) statements; if the pixel lies out of the current clipping region, POINT returns -1, otherwise a color number in the same format as used by the COLOR statement. When called with one argument, this function allows to retrieve the current gfx cursor position; POINT returns a value dependent on the func argument:

pointer

POKE

Type: statement
PEEK and POKE now accept STRING and UDT's as data type (v1c)
PEEKS, PEEKI, POKES, POKEI keywords removed, use now the new syntax as "PEEK( data type, expression )" or
"POKE data ype, expression, expression" to peek/poke different data types than BYTE, that's the default one (v1c)
-

Syntax:
poke address, value as byte '(8bit)
pokes address, value as short '(16bit)
pokei address, value as integer '(32bit)

Poke (in all forms: poke, pokes, and pokei) changes the value in memory given by a memory address. This was how pointer features were coded in the old basic dialects.

e.g. of getting the address of a variable and changing its contents by its address:

dim x as byte, addr as integer
addr = varptr(x)
x = 5
poke addr, 10
print x

pokei

pokes

POS

Returns the horizontal (left-right) position of the text cursor. 1 means the very left.

e.g.

print "position: "; pos
print "hello world";
print "position: "; pos

preserve

Used with redim so that when an array is resized, data is not reset but is preserved. This means when the array is enlarged that only new data is reset, while the old data remains the same.

e.g. (v1c, too lazy to see if/how it works :p).

'$dynamic
dim array(1 to 3) as integer
array(1) = 10
array(2) = 5
array(3) = 8
redim preserve array(2 to 10) as integer
for i = 2 to 10
print "array("; i; ") = "; array(i)
next

PRESET

PRESET works exactly like PSET, except that if the color is not specified,
the background color is selected.

Displays text on the screen (or console output).
Print handles complex, specific syntax to handle string constants (like "hello"), number constants (eg 101), string or number variables (eg x or name$), and punctuation symbols like a join (;), or tab space (,).

Using a join allows two items to be printed in one statement like the following:

name$ = "Linus"
print "Name: "; name$

If a print expression ends with a join, the next print statement will be joined beside the last one. for example:

print "Hello ";
print "world";
print "!"

x = 30
print "x is ",
print x
print "hello", "world", "and", "goodbye"

If a print expression doesn't end with a comma or a join then a new line is inserted. If there is no print expression then print simply makes a new line.

e.g.

print "Welcome"
print
print "...and goodbye!"

Simple hello world example:
[code]
PRINT "Hello World!"

PRINT #

Type: statement
Category: File

PRINT # writes data to a sequential device or file.
PRINT #filenumber%, [USING formatstring$;] expressionlist[{,|;}]
_ filenumber% The number used to open the sequential file.
_ expressionlist Numeric or string expressions to be written to
the file.
_ formatstring$ Specifies the exact format in which values
are written to the file. See Details for the
meaning of characters in formatstring.

PRINT #filenumber%, [USING formatstring$;] expressionlist[{,|;}]
_ The arguments filenumber% and expressionlist are described
on the Syntax Screen.
_ Characters in formatstring$ have the following meaning:

-------------------Characters Used to Format a Numeric Expression-------------
# Digit position ¦ - Placed after digit positions,
. Decimal point position ¦ prints trailing sign for
, Placed left of the decimal point, ¦ negative numbers only
prints a comma every third digit ¦ $$ Prints leading $
+ Position of number's sign ¦ ** Fills leading spaces with *
^^^^ Prints number in exponential format¦ **$ Combines ** and $
--------------------Characters Used to Format a String Expression-------------
& Prints entire string ¦ \ \ Prints first 'n' characters,
! Prints only the first character ¦ where n is the number of
of the string ¦ blanks between slashes + 2

PRINT USING

private

Explicitly sets an individual sub/function to be private (instead of public by default). This means the sub/function is only accessible within the module and is hidden to other modules. This means two subs/functions can have the same name, as long as they are private and are in seperate modules.

Subs/functions are private by default if the command option private is used, otherwise they are public by default.

e.g.

private sub i_am_private
end sub

sub i_am_public
end sub

procptr

PSET

Statement to plot a single pixel.

The 'STEP' option specify that 'x' and 'y' are offsets relative to the current graphics cursor position.

'(x, y)' are coordinates of the pixel.

'color' is the color attribute. This is mode specific, see COLOR and SCREEN (graphics) for details.

This function plots a single pixel on the screen. The x and y coordinates are affected by the last call to the VIEW (graphics) and WINDOW statements, and respect the current clipping region as set by the VIEW (graphics) statement. If you do not specify color, current foreground color is used.

See also point, VIEW (graphics), WINDOW.

ptr

pointers to pointers *MUST* now be declared as "ptr ptr ...", multiple dereferencing are only allowed on those (v1c)
pointer indexing support, as in "myptr[idx]" (v1c)

public

Explicitly sets an individual sub/function to be public. This means the sub/function is freely accessible between other modules.

The only reason one needs to use the public prefix on subs/functions is if they are private by default (using option private), because subs/functions are public by default normally.

e.g.

option private
sub i_am_private
end sub

public sub i_am_public
end sub

PUT (File I/O)

Writes data to a file in binary mode. Put will write any data type to the file in pure binary mode, making it a very versatile data writing command.

e.g.

dim buffer as string
f = freefile
open "file.ext" for binary as #f
buffer = "hello world within a file."
put #f, , buffer
close #f

PUT (Graphics)

Syntax: PUT [STEP] (x, y), arrayname[(idx)][,mode]
Type: statement
Category: Gfx

Statement to draw a block of pixels previously saved by GET.
Gfx GET and PUT now support both arrays and generic pointers as data holders (lillo)

The 'STEP' option specify that 'x' and 'y' are offsets relative to
the current graphics cursor position.

(x, y) are coordinates where to place the top-left corner of the block to be drawn.

'arrayname' is the array holding saved block pixels data.

'idx' is an Index into arrayname where data is assumed to start. If 'idx' is omitted, it is assumed to be 0.

'mode' is one of PSET, PRESET, AND, OR, XOR or TRANS; see below. If omitted, this defaults to XOR.

PUT can be used to draw images previously saved by the GET (graphics) statement. The 'x' and 'y' coordinates are affected by the last call to the VIEW (graphics) and WINDOW statements, and plotted image respects the current clipping region set by last call to the VIEW (graphics) statement. Pixels stored in given array (source pixels) are drawn on the screen interacting with the pixels onto which they are going to be drawn (destination pixels); the interaction depends on the mode parameter:

The AND, OR and XOR modes produce different results depending on the current color depth, as pixels are stored in different formats; see Internal pixel formats for details. If the TRANS mode is used, pixels using the mask color are not drawn. The mask color depends on the current color depth: in paletted modes (up to 8 bpp) it is equal to color index 0, while on hi/truecolor modes (15, 16, 24 and 32 bpp) it is equal to color &hFF00FF (bright pink). The pixels data stored in given array must be compatible with current gfx mode color depth; that is, if you acquire an image using GET and you later change screen mode via SCREEN (graphics), the image data may not be valid in the new gfx mode, making PUT to behave badly.

Example:

' Set 320x240 mode using 16bpp color depth
SCREEN 14, 16
' Let's allocate space for a 32x32 sprite
DIM sprite((32 * 32 * 2) + 4)
' Let's prepare our sprite
LINE (0,0)-(31,31), &hFF0000, BF
LINE (0,0)-(31,31), &h00FF00, B
LINE (8,8)-(23,23), &hFF00FF, BF
LINE (1,1)-(30,30), &h0000FF
LINE (30,1)-(1,30), &h0000FF
GET (0,0)-(31,31), sprite
' Showtime!
CLS
FOR i = 0 TO 63
LINE (0,i)-(319,i), RGB(i * 4, i * 4, i * 4)
NEXT i
PUT (19, 16), sprite, PSET
PUT (69, 16), sprite, PRESET
PUT (119, 16), sprite, AND
PUT (169, 16), sprite, OR
PUT (219, 16), sprite, XOR
PUT (269, 16), sprite, TRANS
SLEEP

Differences:
Between QB:
FB version supports hi/truecolor sprites, transparency and clipping. For modes with color depth up to 8bpp, it always assumes 1 byte equals 1 pixel into arrayname, whereas QB packs more pixels per byte if color depth is less than 8bpp.