Paint

Keyword	Abbreviation	Token (hex)	Version(s)	Classification
PAINT	P{Shift+A}	DF	3.5, 7.0	Command and Statement
KEY	K{Shift+E}	DF	4.7	Command and Statement

Syntax

PAINT [ colorSource ] [ , { [ + | - ] xVal [ , [ + | - ] yVal ] | distance ; angle } [ , stopMode ] ] ...

Parameters	Type	Legal Value(s)	Default Value	Note(s)
colorSource	Integer	0 or 1 (high-res) 0 to 3 (multi-color)	1	The actual color on-screen depends on the colorSource assignment by COLOR
xVal	Integer*	-32768 to +32767	pixel cursor X	rectangular X ordinate or offset for a point
yVal	Integer*	-32768 to +32767	pixel cursor Y	rectangular Y ordinate or offset for a point
distance	Integer*	-32768 to +32767	0	polar distance for a point
angle	Unsigned Integer	0 to 65535	undefined	polar angle for a point
stopMode	Integer	0 or 1	0	0 = must match colorSource; 1 = any non-background

Purpose

Fill an enclosed region of the bitmap.

Remarks

All parameters are optional. Without any parameters, PAINT begins at the pixel cursor (the last pixel updated by the previous bitmap command).

Following the optional colorSource is the optional (but recommended) starting point for PAINT. If the point is not specified, it defaults to the pixel cursor. A specified coordinate will be effected by SCALE if it is active. The resulting value may be off-screen (in which case PAINT does nothing), but is acceptable as long as it is "legal" as shown above.

A point specified as a polar coordinate will always be relative to the pixel cursor. A point specified in rectangular form will normally be an absolute coordinate (independ of the pixel cursor), but using a + or - in front of the xVal or yVal will make that ordinate relative to the pixel cursor. The x and y ordinates are processed independantly; either, neither, or both ordinates of the rectangular coordinate may be in relative form (whichever use a leading + or -). Note these must be literal + and - characters in the command/statement. So if you have a variable X with a negative value (like -10) then it will be used an absolute coordinate unless you preced it with + or - sign. You normally wouldn't put a - sign unless you want to reverse the direction of the variable. So, for this example, use +X for a relative ordinate. As opposed to a variable, if you want to enter a literal negative value (for an absolute ordinate), you must enclose it in parentheses; otherwise it would interpreted as a relative ordinate. Sorry if that is confusing! If so, you need to play with relative and absolute coordinates to see clearly what I mean.

PAINT will fill an area of the bitmap until it matches the "stopping color source". By default, this is the same as colorSource. If you specfiy a value of 1 for stopMode, instead of the default of 0, then PAINT will stop at any non-background color instead. This alternate stopMode only makes sense for multi-color mode (because there is only 1 non-background color for high-resolution bitmap mode).

If the initial point already matches the "stopping color source" then PAINT does nothing. Otherwise it calls the BASIC garbage collection routine to discard all temporary strings before it begins. Once it starts, it follows this (not quite accurate) algorithm:

sets the current (non-stopping) pixel to the specified (or default) colorSource
essentially tests the four surrounding pixels (above, below, left, and right); any that match the "stopping color source" or is off-screen will be ignored
If any of those are non-stopping pixels, it saves the coordinate on a temporary "paint stack", moves to the non-stopping pixel, and repeats (if the "paint stack" is full, an OUT OF MEMORY ERROR occurs).
If all of those are the "stopping color source" or off-screen, then PAINT pulls the last coordinate off the "paint stack", moves to that location, and repeats (if the "paint stack" is empty, then PAINT is done)

The above just gives you an idea how it works. The actual algorithm is a bit more sophisticated; for example it doesn't test the direction it just came from. It also doesn't push a coordinate onto the "paint stack" until it finds a "stopping color source" in the direction it is heading. Nonetheless, because of multiple tests at each point, it can take quite a while to paint a large area. Alternatives include the use of CHAR, GSHAPE, and BOX (with fill option), but these are only practical if you want to fill a (rotated) rectangular area. It also important to be sure the starting point is really inside an enclosed area. If there are any gaps in the boundry, PAINT will "leak out" and produce undesirable results, perhaps even filling the whole screen!

Any floating-point numbers will first be converted to integers (see INT). If any value is out-of-range (see above) an ILLEGAL QUANTITY ERROR is generated. If no bitmap has been setup (see GRAPHIC), a NO GRAPHICS AREA is generated.

Example of optional colorSource and optional point:

PAINT 1 : REM begin filling at the pixel cursor

READY.
PAINT , 60,60 : REM paint with colorSource 1 beginning at point (60,60)

READY.

Example of relative rectangular and polar coordinate:

DRAW 1,60,60: PAINT 1, +10,-10 : REM PAINT 1, 70,50 = 60+10, 60-10

READY.
PAINT 1, (+10),(-10) : REM PAINT starting at absolute coordinate (10,-10)

READY.
DRAW 1,60,60: PAINT 1, 20; 30 : REM PAINT 1, 70,43 = 60+20*SIN(30), 60-20*COS(30)

Example of stopModes:

PAINT 0, 60,60    : REM stop at selected colorSource (background) using colorSource 0

READY.
PAINT 0, 60,60, 1 : REM does nothing! 

READY.
PAINT 1, 60,60    : REM stop at selected colorSource only, using colorSource 1

READY.
PAINT 1, 60,60, 1 : REM stop at any non-background colorSource, using colorSource 1

Compare With

BOX, CHAR, DRAW, GSHAPE

See Also

COLOR, GRAPHIC, LOCATE, SCALE