PAINT

• Source: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgPaint
• Last revised: 2023-07-09

---

PAINT — Flood-fill a bounded region

Syntax

Paint [target,] [STEP] (x, y) [, [paint] [, [border_color]]]

Parameters

Parameter	Description
target	Optional. A Get/Put buffer to paint into. If omitted, the current work page is used.
STEP	Optional. Indicates that (x, y) coordinates are relative to the last graphics cursor position.
(x, y)	The pixel coordinate at which flooding starts.
paint	Optional. A numeric color value, or a string specifying a tile pattern. Defaults to the current foreground color.
border_color	Optional. The boundary color at which flooding stops. Defaults to the current background color.

Description

PAINT is a graphics command that performs a flood-fill (also known as a "paint bucket" operation). It fills an area bounded by a specified color.

Filling starts at (x, y). If STEP is specified, coordinates are relative to the last graphics cursor position. Coordinates are also affected by any custom coordinate system set by Window and/or View (Graphics); clipping set by View is applied.

Numeric paint value:
If paint is a number, it is treated as a color in the same format as the Color statement, and a solid flood-fill is performed using that color.

String paint value (tile pattern):
If paint is a string, the area is filled with a repeating 8×8 pixel tile pattern. The string must contain raw pixel data whose size depends on the current color depth:

Color depth	Required string size
1, 2, 4, 8 bpp	8 × 8 = 64 bytes
15 or 16 bpp	(8 × 8) × 2 = 128 bytes
24 or 32 bpp	(8 × 8) × 4 = 256 bytes

Pixels are stored row by row. If the string is shorter than required, the missing pixels are treated as 0.

Boundary behavior:
Flooding continues until a pixel matching border_color is encountered. If border_color is omitted, the current background color is used.

Warning: If the boundary was drawn with a transparent color (using the GFX_ALPHA_PRIMITIVES flag), the blended final color of boundary pixels may create "leak points" where the fill escapes the boundary. It is not recommended to draw boundaries using transparent colors.

Examples

Example 1 — Simple flood fill

' Draw a white circle and fill its interior with blue
Screen 13
Circle (160, 100), 30, 15
Paint (160, 100), 1, 15
Sleep

Example 2 — Tile pattern fill

' Select screen bit depth (try 8, 16, or 32)
Const bit_depth = 8

' Helper: return one pixel as a string for the current bit depth
Function paint_pixel( ByVal c As ULong, ByVal bit_depth_ As Integer ) As String
    If bit_depth_ <= 8 Then
        Function = Chr( CUByte(c) )
    ElseIf bit_depth_ <= 16 Then
        Function = MKShort( c Shr 3 And &h1f Or _
                            c Shr 5 And &h7e0 Or _
                            c Shr 8 And &hf800 )
    ElseIf bit_depth_ <= 32 Then
        Function = MKL(c)
    End If
End Function

ScreenRes 320, 200, bit_depth

Dim As ULong c, c1, c2, cb

Dim As String paint_pattern = ""

If bit_depth <= 8 Then
    c1 = 7   ' pattern color 1 (light gray)
    c2 = 8   ' pattern color 2 (dark gray)
    cb = 15  ' border color (white)
Else
    c1 = RGB(192, 192, 192)
    c2 = RGB(128, 128, 128)
    cb = RGB(255, 255, 255)
End If

' Build an 8x8 checkerboard pattern
For y As UInteger = 0 To 7
    For x As UInteger = 0 To 7
        If (x \ 4 + y \ 4) Mod 2 > 0 Then
            c = c1
        Else
            c = c2
        End If
        paint_pattern = paint_pattern + paint_pixel(c, bit_depth)
    Next x
Next y

' Draw a circle with the border color
Circle (160, 100), 50, cb, , , 1.0

' Flood-fill the circle with the tile pattern
Paint (160, 100), paint_pattern, cb

Sleep

Differences from QB

• The target parameter is a FreeBASIC extension.
• In QB, a fill pattern is always 8 bits wide and up to 64 bytes tall. In FreeBASIC, a pattern is always 8 pixels wide (independent of color depth) and always 8 pixels tall.
• The background-color parameter supported in QB is not supported in FreeBASIC.

See Also

• KeyPgScreengraphics — Screen (Graphics)
• KeyPgCircle — Circle
• KeyPgPset — PSet