PixelateEffectLib — Plan9Basic Documentation

Overview

PixelateEffectLib creates a pixelation (mosaic) effect on visual controls, wrapping the FireMonkey TPixelateEffect component. The effect reduces image detail by grouping pixels into larger blocks — perfect for retro game aesthetics, privacy censoring, or stylized transitions.

Property	Details
Library	`PixelateEffectLib`
Prefix	`pixelate_`
Wraps	`TPixelateEffect`
Functions	12
Type	Visual effect (stylistic)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Block Count	2	Get/set pixelation level
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🎮 Retro Vibes: Lower block count = larger blocks = more pixelated. Think of it as reducing the "resolution" of the image — great for 8-bit retro game aesthetics or privacy blurring.

Cross-Platform Support

Platform	Support
Windows	✅ Full support
Linux	✅ Full support
Android	✅ Full support

Creation & Destruction

pixelate#(parent#)

Creates a new pixelate effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control
Returns	Pointer	Effect handle, or 0 on failure

pixelate_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`pixelate_error()`	`pixelate_error@`	Returns last error code (0 = none)
`pixelate_errormsg$()`	`pixelate_errormsg$@`	Returns last error message
`pixelate_strerror$(code)`	`pixelate_strerror$@n`	Converts error code to text
`pixelate_clearerror()`	`pixelate_clearerror@`	Clears the error state

Block Count

Controls the number of pixel blocks the image is divided into. Lower values create larger blocks (more pixelated); higher values retain more detail.

Function	Signature	Description
`pixelate_blockcount#(effect#, value)`	`pixelate_blockcount#@#n`	Set block count (1–100)
`pixelate_blockcount(effect#)`	`pixelate_blockcount@#`	Get block count

Value	Effect	Use Case
`5–10`	Very pixelated (large blocks)	Heavy censoring, retro 8-bit look
`15–25`	Moderately pixelated	Stylized mosaic, privacy blur
`30–50`	Lightly pixelated	Subtle retro effect
`60–100`	Nearly original detail	Minimal effect, slight texture

Effect Control

Function	Signature	Description
`pixelate_enabled#(effect#, value)`	`pixelate_enabled#@#n`	Enable (1) or disable (0)
`pixelate_enabled(effect#)`	`pixelate_enabled@#`	Gets enabled state
`pixelate_trigger#(effect#, trigger$)`	`pixelate_trigger#@#$`	Sets trigger string
`pixelate_trigger$(effect#)`	`pixelate_trigger$@#`	Gets trigger string

Complete Examples

Example 1: Pixelation Presets

╯ pixelate-presets.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let pix# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Pixelation Control", 450, 380)

img# = image#(frm#)
image_bounds#(img#, 125, 30, 200, 150)
image_load#(img#, "https://picsum.photos/200/150")

pix# = pixelate#(img#)
pixelate_blockcount#(pix#, 50)

lbl# = label#(frm#, "Blocks: 50", 180, 200)

let btn1# = button#(frm#, "5")
button_bounds#(btn1#, 50, 240, 70, 30)
button_onclick#(btn1#, "SetBlocks5")

let btn2# = button#(frm#, "15")
button_bounds#(btn2#, 130, 240, 70, 30)
button_onclick#(btn2#, "SetBlocks15")

let btn3# = button#(frm#, "30")
button_bounds#(btn3#, 210, 240, 70, 30)
button_onclick#(btn3#, "SetBlocks30")

let btn4# = button#(frm#, "50")
button_bounds#(btn4#, 290, 240, 70, 30)
button_onclick#(btn4#, "SetBlocks50")

form_show(frm#)

function SetBlocks5(sender#)
  pixelate_blockcount#(pix#, 5)
  label_text#(lbl#, "Blocks: 5 (Very pixelated)")
endfunction

function SetBlocks15(sender#)
  pixelate_blockcount#(pix#, 15)
  label_text#(lbl#, "Blocks: 15 (Pixelated)")
endfunction

function SetBlocks30(sender#)
  pixelate_blockcount#(pix#, 30)
  label_text#(lbl#, "Blocks: 30 (Moderate)")
endfunction

function SetBlocks50(sender#)
  pixelate_blockcount#(pix#, 50)
  label_text#(lbl#, "Blocks: 50 (Light)")
endfunction

Example 2: Toggle Pixelation

╯ toggle-pixelate.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let pix# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Toggle Pixelate", 400, 340)

img# = image#(frm#)
image_bounds#(img#, 100, 40, 200, 150)
image_load#(img#, "https://picsum.photos/200/150")

pix# = pixelate#(img#)
pixelate_blockcount#(pix#, 10)

lbl# = label#(frm#, "Pixelation: ON", 150, 210)

let btn# = button#(frm#, "Toggle Pixelate")
button_bounds#(btn#, 120, 250, 140, 35)
button_onclick#(btn#, "OnToggle")

form_show(frm#)

function OnToggle(sender#)
  if pixelate_enabled(pix#) = 1 then
    pixelate_enabled#(pix#, 0)
    label_text#(lbl#, "Pixelation: OFF")
  else
    pixelate_enabled#(pix#, 1)
    label_text#(lbl#, "Pixelation: ON")
  endif
endfunction

Example 3: Basic Pixelate

╯ basic-pixelate.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let pix# = Pointer#(0)

frm# = form#("Pixelate Demo", 400, 320)

img# = image#(frm#)
image_bounds#(img#, 100, 40, 200, 150)
image_load#(img#, "https://picsum.photos/200/150")

pix# = pixelate#(img#)
pixelate_blockcount#(pix#, 15)

form_show(frm#)

Best Practices

Practice	Why
Use on images with details	Solid color shapes won't show visible change
Lower block count = more pixelation	Counter-intuitive: fewer blocks means bigger blocks
Block count 5–15 for heavy censoring	Effectively hides image details
Block count 30–50 for retro aesthetics	Recognizable image with retro game feel
Combine with PixelateTransition for animations	Animated pixelation creates retro video game transitions

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`pixelate#(parent#)`	`pixelate#@#`	Create effect
`pixelate_free(effect#)`	`pixelate_free@#`	Destroy effect
BLOCK COUNT
`pixelate_blockcount#(effect#, value)`	`pixelate_blockcount#@#n`	Set block count
`pixelate_blockcount(effect#)`	`pixelate_blockcount@#`	Get block count
EFFECT CONTROL
`pixelate_enabled#(effect#, value)`	`pixelate_enabled#@#n`	Enable/disable
`pixelate_enabled(effect#)`	`pixelate_enabled@#`	Get enabled state
`pixelate_trigger#(effect#, trigger$)`	`pixelate_trigger#@#$`	Set trigger
`pixelate_trigger$(effect#)`	`pixelate_trigger$@#`	Get trigger
ERROR HANDLING
`pixelate_error()`	`pixelate_error@`	Last error code
`pixelate_errormsg$()`	`pixelate_errormsg$@`	Last error message
`pixelate_strerror$(code)`	`pixelate_strerror$@n`	Code to text
`pixelate_clearerror()`	`pixelate_clearerror@`	Clear error state

Library	Description
`PixelateTransitionEffectLib`	Pixelated transition between images
`BlurEffectLib`	Blur effects
`ToonEffectLib`	Cartoon/cel-shaded effect