HueAdjustEffectLib — Plan9Basic Documentation

HueAdjustEffectLib — Hue Rotation

Shifts the hue (colour) of all pixels around the colour wheel. Wraps FireMonkey’s THueAdjustEffect. Use for colour correction, creative colour themes, or dynamic colour cycling. 12 functions.

Category	Count	Description
Error Handling	4	hueadjust_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	hueadjust# (create), hueadjust_free (destroy)
Properties	2	hue (get/set)
Effect Control	4	enabled, trigger (get/set)

Colour Wheel & Hue Values

Hue is a rotation around the colour wheel. Value -1.0 to 1.0 maps to a full 360° rotation. At 0.0 colours are unchanged; at ±1.0 they wrap back to the original.

Hue Value	Degrees	Effect on Red	Description
0.0	0°	Red stays Red	No change (original colours)
0.17	~60°	Red → Yellow	Warm shift
0.33	~120°	Red → Green	One-third rotation
0.5	180°	Red → Cyan	Complementary colours
0.66	~240°	Red → Blue	Two-thirds rotation
-0.33	~-120°	Red → Blue	Reverse rotation
1.0 / -1.0	360°	Red stays Red	Full circle = original

ⓘ Complementary colours: Setting hue to 0.5 (180°) produces complementary colours — the opposite of each colour on the wheel.

Cross-Platform Support

Platform	Status
Windows	✅ Full Support
Linux	✅ Full Support
Android	✅ Full Support

Error Handling

Function	Signature	Description
`hueadjust_error()`	`hueadjust_error@`	Returns last error code (0 = no error)
`hueadjust_errormsg$()`	`hueadjust_errormsg$@`	Returns last error message
`hueadjust_strerror$(code)`	`hueadjust_strerror$@n`	Converts error code to text
`hueadjust_clearerror()`	`hueadjust_clearerror@`	Clears error state

Creation & Destruction

Function	Signature	Description
`hueadjust#(parent#)`	`hueadjust#@#`	Creates hue adjust effect. Returns pointer. Default hue: 0.0
`hueadjust_free(effect#)`	`hueadjust_free@#`	Destroys effect

Hue

Controls rotation around the colour wheel. Range -1.0 to 1.0, default 0.0 (no change).

Function	Signature	Description
`hueadjust_hue#(effect#, value)`	`hueadjust_hue#@#n`	Sets hue shift (-1.0 to 1.0)
`hueadjust_hue(effect#)`	`hueadjust_hue@#`	Gets current hue value

Effect Control

Function	Signature	Description
`hueadjust_enabled#(effect#, value)`	`hueadjust_enabled#@#n`	Enables (1) or disables (0)
`hueadjust_enabled(effect#)`	`hueadjust_enabled@#`	Gets enabled state
`hueadjust_trigger#(effect#, trigger$)`	`hueadjust_trigger#@#$`	Sets trigger string
`hueadjust_trigger$(effect#)`	`hueadjust_trigger$@#`	Gets trigger string

Complete Examples

Basic Hue Shift

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

frm# = form#("Hue Adjust Demo", 400, 300)

rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 100, 80, 200, 120)
rectangle_fill#(rect#, "Red")

hue# = hueadjust#(rect#)
hueadjust_hue#(hue#, 0.33)  ' Red becomes Green

form_show(frm#)

Hue Presets

╯ hue-presets.bas─◻✕
let frm# = Pointer#(0)
let rect# = Pointer#(0)
let hue# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Hue Control", 500, 320)

rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 150, 40, 200, 100)
rectangle_fill#(rect#, "Red")

hue# = hueadjust#(rect#)
lbl# = label#(frm#, "Hue: 0 (Original)", 170, 160)

let btn1# = button#(frm#, "Original")
button_bounds#(btn1#, 30, 200, 85, 30)
button_onclick#(btn1#, "SetOriginal")

let btn2# = button#(frm#, "+0.17")
button_bounds#(btn2#, 125, 200, 85, 30)
button_onclick#(btn2#, "SetHue1")

let btn3# = button#(frm#, "+0.33")
button_bounds#(btn3#, 220, 200, 85, 30)
button_onclick#(btn3#, "SetHue2")

let btn4# = button#(frm#, "+0.5")
button_bounds#(btn4#, 315, 200, 85, 30)
button_onclick#(btn4#, "SetHue3")

let btn5# = button#(frm#, "-0.33")
button_bounds#(btn5#, 410, 200, 85, 30)
button_onclick#(btn5#, "SetHue4")

form_show(frm#)

function SetOriginal(sender#)
  hueadjust_hue#(hue#, 0)
  label_text#(lbl#, "Hue: 0 (Original)")
endfunction
function SetHue1(sender#)
  hueadjust_hue#(hue#, 0.17)
  label_text#(lbl#, "Hue: +0.17")
endfunction
function SetHue2(sender#)
  hueadjust_hue#(hue#, 0.33)
  label_text#(lbl#, "Hue: +0.33")
endfunction
function SetHue3(sender#)
  hueadjust_hue#(hue#, 0.5)
  label_text#(lbl#, "Hue: +0.5 (Complementary)")
endfunction
function SetHue4(sender#)
  hueadjust_hue#(hue#, -0.33)
  label_text#(lbl#, "Hue: -0.33")
endfunction

Colour Shift Gallery

╯ hue-gallery.bas─◻✕
let frm# = form#("Color Shift Gallery", 500, 280)

' Original
let rect1# = rectangle#(frm#)
rectangle_bounds#(rect1#, 40, 60, 120, 100)
rectangle_fill#(rect1#, "Red")
let lbl1# = label#(frm#, "Original", 70, 170)

' +0.33 shift
let rect2# = rectangle#(frm#)
rectangle_bounds#(rect2#, 190, 60, 120, 100)
rectangle_fill#(rect2#, "Red")
let hue2# = hueadjust#(rect2#)
hueadjust_hue#(hue2#, 0.33)
let lbl2# = label#(frm#, "Hue +0.33", 215, 170)

' +0.66 shift
let rect3# = rectangle#(frm#)
rectangle_bounds#(rect3#, 340, 60, 120, 100)
rectangle_fill#(rect3#, "Red")
let hue3# = hueadjust#(rect3#)
hueadjust_hue#(hue3#, 0.66)
let lbl3# = label#(frm#, "Hue +0.66", 365, 170)

form_show(frm#)

Best Practices

Practice	Why
Use 0.5 for complementary colours	Creates the exact opposite on the colour wheel
Use thirds (0.33, 0.66) for triadic schemes	Produces harmonious colour combinations
Animate hue with FloatAnimationLib	Creates psychedelic colour cycling effects
Works best on colourful content	Gray/white/black have no hue to shift
Combine with ContrastEffectLib	Enhance shifted colours with contrast boost

Quick Reference

Function	Signature	Description
ERROR HANDLING
`hueadjust_error()`	`hueadjust_error@`	Last error code
`hueadjust_errormsg$()`	`hueadjust_errormsg$@`	Last error message
`hueadjust_strerror$(code)`	`hueadjust_strerror$@n`	Error code to text
`hueadjust_clearerror()`	`hueadjust_clearerror@`	Clear error state
CREATION & DESTRUCTION
`hueadjust#(parent#)`	`hueadjust#@#`	Create effect on control
`hueadjust_free(effect#)`	`hueadjust_free@#`	Destroy effect
PROPERTIES
`hueadjust_hue#(e#, val)`	`hueadjust_hue#@#n`	Set hue (-1.0 to 1.0)
`hueadjust_hue(e#)`	`hueadjust_hue@#`	Get hue
EFFECT CONTROL
`hueadjust_enabled#(e#, val)`	`hueadjust_enabled#@#n`	Enable (1) / disable (0)
`hueadjust_enabled(e#)`	`hueadjust_enabled@#`	Get enabled state
`hueadjust_trigger#(e#, str$)`	`hueadjust_trigger#@#$`	Set trigger string
`hueadjust_trigger$(e#)`	`hueadjust_trigger$@#`	Get trigger string

12 functions. Part of the Plan9Basic visual effects library system.