PencilStrokeEffectLib — Plan9Basic Documentation

Overview

PencilStrokeEffectLib transforms an image to look like it was drawn with bold pencil strokes, wrapping the FireMonkey TPencilStrokeEffect component. Unlike the softer PaperSketch effect, PencilStroke produces darker, more defined strokes with higher contrast — ideal for comic-style art or dramatic artistic transformations.

Property	Details
Library	`PencilStrokeEffectLib`
Prefix	`pencilstroke_`
Wraps	`TPencilStrokeEffect`
Functions	12
Type	Visual effect (artistic)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Brush Size	2	Get/set stroke thickness
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

✏ Bold Drawing Style: PencilStroke produces darker, more pronounced strokes compared to PaperSketch. It works best with images that have clear edges and high contrast — perfect for portrait and architectural subjects.

PencilStroke vs PaperSketch

Plan9Basic offers two complementary sketch effects. Both share the same API pattern (BrushSize property) but produce distinctly different visual results:

Feature	PencilStroke	PaperSketch
Visual style	Bold pencil strokes — darker, more defined	Pencil on paper — lighter, softer
Background	Darker, higher contrast	Light paper-like appearance
Edge detection	Sharper, more pronounced edges	Softer edges
Best for	Bold drawings, comic-style art	Soft sketches, watercolor feel
Parameters	BrushSize only	BrushSize only

💡 Tip: Try both effects on the same image side by side to decide which artistic style fits your applet best. They share identical API patterns so switching is easy.

Cross-Platform Support

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

Creation & Destruction

pencilstroke#(parent#)

Creates a new pencil stroke effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control (e.g., image)
Returns	Pointer	Effect handle, or 0 on failure

pencilstroke_free(effect#)

Destroys the effect and releases associated resources.

╯ create-pencilstroke.bas─◻✕
let pencil# = pencilstroke#(img#)
pencilstroke_brushsize#(pencil#, 1.5)

' Clean up when done
pencilstroke_free(pencil#)

Error Handling

Function	Signature	Description
`pencilstroke_error()`	`pencilstroke_error@`	Returns last error code (0 = none)
`pencilstroke_errormsg$()`	`pencilstroke_errormsg$@`	Returns last error message
`pencilstroke_strerror$(code)`	`pencilstroke_strerror$@n`	Converts error code to text
`pencilstroke_clearerror()`	`pencilstroke_clearerror@`	Clears the error state

Brush Size

Controls the thickness of the pencil strokes. Smaller values produce finer, more detailed strokes; larger values create bolder, more pronounced lines.

Function	Signature	Description
`pencilstroke_brushsize#(effect#, value)`	`pencilstroke_brushsize#@#n`	Sets stroke size
`pencilstroke_brushsize(effect#)`	`pencilstroke_brushsize@#`	Gets brush size

Value	Description	Use Case
`0.1–0.5`	Very fine strokes	Detailed, intricate drawings
`0.5–1.0`	Fine to medium strokes	General purpose, natural look
`1.0–2.0`	Medium strokes (default range)	Balanced pencil drawing
`2.0–5.0`	Bold strokes	Comic-style, dramatic art

Effect Control

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

Complete Examples

Example 1: Basic Pencil Stroke

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

frm# = form#("Pencil Stroke Demo", 400, 350)

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

' Apply pencil stroke effect
pencil# = pencilstroke#(img#)
pencilstroke_brushsize#(pencil#, 1)

form_show(frm#)

Example 2: Adjustable Stroke Size

╯ adjustable-pencil.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let pencil# = Pointer#(0)
let trkBrush# = Pointer#(0)
let lblBrush# = Pointer#(0)

frm# = form#("Pencil Stroke Control", 450, 400)

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

pencil# = pencilstroke#(img#)
pencilstroke_brushsize#(pencil#, 1)

' Stroke size slider
lblBrush# = label#(frm#, "Stroke Size: 1.0", 160, 200)
trkBrush# = trackbar#(frm#)
trackbar_bounds#(trkBrush#, 50, 230, 350, 30)
trackbar_max#(trkBrush#, 50)
trackbar_value#(trkBrush#, 10)
trackbar_onchange#(trkBrush#, "OnBrushChange")

form_show(frm#)

function OnBrushChange(sender#) local b
  let b = trackbar_value(trkBrush#) / 10
  if b < 0.1 then
    b = 0.1
  endif
  pencilstroke_brushsize#(pencil#, b)
  label_text#(lblBrush#, "Stroke Size: " + stri$(b, 1))
endfunction

Example 3: Compare Stroke Sizes

╯ stroke-sizes.bas─◻✕
let frm# = Pointer#(0)
let img1# = Pointer#(0)
let img2# = Pointer#(0)
let img3# = Pointer#(0)
let p1# = Pointer#(0)
let p2# = Pointer#(0)
let p3# = Pointer#(0)

frm# = form#("Stroke Size Comparison", 550, 350)

' Fine strokes
img1# = image#(frm#)
image_bounds#(img1#, 30, 30, 150, 112)
image_load#(img1#, "https://picsum.photos/150/112")
p1# = pencilstroke#(img1#)
pencilstroke_brushsize#(p1#, 0.5)
let lbl1# = label#(frm#, "Size: 0.5", 75, 150)

' Medium strokes
img2# = image#(frm#)
image_bounds#(img2#, 200, 30, 150, 112)
image_load#(img2#, "https://picsum.photos/150/112")
p2# = pencilstroke#(img2#)
pencilstroke_brushsize#(p2#, 1.5)
let lbl2# = label#(frm#, "Size: 1.5", 245, 150)

' Bold strokes
img3# = image#(frm#)
image_bounds#(img3#, 370, 30, 150, 112)
image_load#(img3#, "https://picsum.photos/150/112")
p3# = pencilstroke#(img3#)
pencilstroke_brushsize#(p3#, 3.0)
let lbl3# = label#(frm#, "Size: 3.0", 415, 150)

form_show(frm#)

Best Practices

Practice	Why
Use images with clear edges and contrast	Edge detection produces best results with well-defined features
Start with BrushSize 1.0	Good default — adjust up for bolder, down for finer
Clamp minimum to 0.1	Very small values may produce minimal visible effect
Compare with PaperSketch	Try both on the same image — PencilStroke is bolder, PaperSketch is softer
Show multiple sizes side by side	Let users see the range of artistic effects available
Combine with Monochrome for pre-processing	Grayscale input can produce more consistent stroke results

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`pencilstroke#(parent#)`	`pencilstroke#@#`	Create effect
`pencilstroke_free(effect#)`	`pencilstroke_free@#`	Destroy effect
BRUSH SIZE
`pencilstroke_brushsize#(effect#, value)`	`pencilstroke_brushsize#@#n`	Set stroke size
`pencilstroke_brushsize(effect#)`	`pencilstroke_brushsize@#`	Get brush size
EFFECT CONTROL
`pencilstroke_enabled#(effect#, value)`	`pencilstroke_enabled#@#n`	Enable/disable
`pencilstroke_enabled(effect#)`	`pencilstroke_enabled@#`	Get enabled state
`pencilstroke_trigger#(effect#, trigger$)`	`pencilstroke_trigger#@#$`	Set trigger
`pencilstroke_trigger$(effect#)`	`pencilstroke_trigger$@#`	Get trigger
ERROR HANDLING
`pencilstroke_error()`	`pencilstroke_error@`	Last error code
`pencilstroke_errormsg$()`	`pencilstroke_errormsg$@`	Last error message
`pencilstroke_strerror$(code)`	`pencilstroke_strerror$@n`	Code to text
`pencilstroke_clearerror()`	`pencilstroke_clearerror@`	Clear error state

Library	Description
`PaperSketchEffectLib`	Softer pencil-on-paper sketch effect
`EmbossEffectLib`	3D embossed look
`ToonEffectLib`	Cartoon/cel-shaded effect
`MonochromeEffectLib`	Grayscale conversion