PluginLuaModules

Introduction

lua modules are like a library that can be loaded using the command 'require' This module can consist of a number of functions and variables.

While modules make for easy programming lua has no functionality to remove unused functions
therefore, modules can waste quite a bit of ram so use them for getting a script built quickly or small scripts but employ other tactics with large scripts.

Such as.. Copy and paste the functions you need to your program or set a local variable to your needed functions/variable and unload the module or set the table to nil

Library	Description
rb_defines	Rockbox defines -- Loaded on startup automatically [auto generated]
actions	Rockbox action defines [auto generated]
buttons	Rockbox button defines [auto generated]
audio	conversion to old style audio_ functions
pcm	conversion to old style pcm_ functions
sound_defines	Rockbox sound settings [auto generated]
sound	conversion to old style sound_ functions
playlist	conversion to old style playlist_ functions & playlist to lua table function
rbcompat	compatibility with old rocklua functions
settings	Rockbox global settings [auto generated]
color	universal color functions for color and non-color targets
blit	image copy blitter operations
draw	advanced shape drawing
draw_floodfill	flood fills an area with color
draw_poly	draws closed and open polygons based on table of points
draw_text	draws text onto an image
image	advanced image manipulation
image_save	Save images as bitmap
lcd	handy lcd functions
math_ex	Missing math functions
print	printf functionality
printtable	Prints lua tables to screen with configurable formatting
timer	simple timers -- no callbacks

Modules:

rb_defines

[auto generated] .. contents varies by target

actions

[auto generated] .. contents varies by target

buttons

[auto generated] .. contents varies by target

audio

The audio functions in Rocklua have been consolidated under a single function 'audio()'.
However, require "audio" allows use of the old convention

This Module	Rocklua
rb.audio_status	rb.audio("status")
	rb.audio("play",)
rb.audio_stop	rb.audio("stop")
rb.audio_pause	rb.audio("pause")
rb.audio_resume	rb.audio("resume")
rb.audio_next	rb.audio("next")
rb.audio_prev	rb.audio("prev")
rb.audio_ff_rewind	rb.audio("ff_rewind",)
rb.audio_flush_and_reload_tracks	rb.audio("flush_and_reload_tracks")
rb.audio_get_file_pos	rb.audio("get_file_pos")

pcm

The pcm functions in Rocklua have been consolidated under a single function 'pcm()'.
However, require "pcm" allows use of the old convention
Note: Not all devices provide pcm functions

This Module	Rocklua
rb.pcm_apply_settings	rb.pcm("apply_settings")
	rb.pcm("calculate_peaks")
rb.pcm_play_stop	rb.pcm("play_stop")
rb.pcm_play_pause	rb.pcm("play_pause", )
rb.pcm_play_lock	rb.pcm("play_lock")
rb.pcm_play_unlock	rb.pcm("play_unlock")
rb.pcm_is_playing	rb.pcm("is_playing")
rb.pcm_is_paused	rb.pcm("is_paused",)
rb.pcm_get_bytes_waiting	rb.pcm("get_bytes_waiting")
rb.pcm_set_frequency	rb.pcm("set_frequency", )

sound_defines

[auto generated] .. contents varies by target

sound

The sound functions in Rocklua have been consolidated under a single function 'sound()'.
However, require "sound" allows use of the old convention

This Module	Rocklua
sound_set	sound("set", setting, value)
sound_current	sound("current", setting)
sound_default	sound("default", setting)
sound_min	sound("min", setting)
sound_max	sound("max", setting)
sound_unit	sound("unit", setting)
sound_pitch	sound("pitch", setting)
sound_val2phys	sound("val2phys", setting, value)

playlist

The playlist functions in Rocklua have been consolidated under a single function 'playlist()'.
However, require "playlist" allows use of the old convention

This Module	Rocklua
rb.playlist_amount	rb.playlist("amount")
rb.playlist_add	rb.playlist("add",)
rb.playlist_create	rb.playlist("create",)
rb.playlist_start	rb.playlist("start",)
rb.playlist_resume_track	rb.playlist("resume_track",)
rb.playlist_resume	rb.playlist("resume")
rb.playlist_shuffle	rb.playlist("shuffle",)
rb.playlist_sync	rb.playlist("sync")
rb.playlist_remove_all_tracks	rb.playlist("remove_all_tracks")
rb.playlist_insert_track	rb.playlist("insert_track",)
rb.playlist_insert_directory	rb.playlist("insert_directory",)
rb.playlist_tracks(dir, filename)	Provided only by this module

rbcompat

A number of functions in Rocklua have been changed or consolidated
However, require "rbcompat" allows use of the old convention
Note: REMOVED functions have no replacement

This Module	Rocklua
rb.strcasecmp	rb.strncasecmp(s1, s2)
backlight_set_brightness	rb.backlight_brightness_set(brightness)
rb.backlight_brightness_use_setting	rb.backlight_brightness_set()
buttonlight_set_brightness	rb.buttonlight_brightness_set(brightness)
rb.buttonlight_brightness_use_setting	rb.buttonlight_brightness_set()
rb.mixer_set_frequency	rb.mixer_frequency(freq)
rb.mixer_get_frequency	rb.mixer_frequency()
rb.backlight_on	rb.backlight_onoff(true)
rb.backlight_off	rb.backlight_onoff(false)
rb.touchscreen_set_mode	rb.touchscreen_mode(mode)
rb.touchscreen_get_mode	rb.touchscreen_mode()
rb.trigger_cpu_boost	rb.schedule_cpu_boost(true)
rb.cancel_cpu_boost	rb.schedule_cpu_boost(false)
rb.utf16*	REMOVED
rb.iso_decode	REMOVED

settings

[auto generated] .. contents varies by target

color

The color module provides universal color functions for color and non-color targets
This allows you to set / increment colors for monochrome and color devices with a single function

Function	Arguments	Description
set	(mono, r, g, b)	mono is for monochrome targets 0 is dark 1 is light provide both and the one applicable to the target will be used Note any one of r,g,b can be defined the others will be assumed as '0'
inc	(current, inc, r, g, b)	increments/decrements current color by inc -- optionally color targets by r,g,b excluding r,g,b on color targets will use inc Note any one of r,g,b can be defined the others will be assumed as '0'

blit

The blit module provides definitions for image copy blitter operations

Blit Operation	Description
CUSTOM	user defined blit function func(dst_val, x, y, src_val, x, y)
BCOPY	copy
BOR	OR source and dest pixels
BXOR	XOR(^) source and dest pixels
BNOR	(NOT)(~) (source OR dest pixels)
BSNOR	(NOT source) OR dest pixels
BAND	AND(&) source and dest pixels
BNAND	(NOT) AND source and dest pixels
BNOT	NOT source and dest pixels
Blit functions for masks
BSAND	copy color to dest if source pixel <> 0
BSNOT	copy color to dest if source pixel == 0
Blit functions for masks with colors
BSORC	copy source pixel or color
BSXORC	copy source pixel xor color
BNSORC	copy (NOT)(src_val OR clr)
BSORNC	copy src_val OR (~clr)
BSANDC	copy src_val & clr
BNSANDC	copy (~src_val) & clr
BDORNSORC	copy dst OR (~src_val) OR clr
BXORSADXORC	copy dst ^ (src_val & (dst_val ^ clr))
BSNEC	copy source pixel if source <> color
BSEQC	copy source pixel if source == color
BSGTC	copy source pixel if source > color
BSLTC	copy source pixel if source < color
BDNEC	copy source pixel if dest <> color
BDEQC	copy source pixel if dest == color
BDGTC	copy source pixel if dest > color
BDLTC	copy source pixel if dest < color
BDNES	copy color to dest if dest <> source pixel
BDEQS	copy color to dest if dest == source pixel
BDGTS	copy color to dest if dest > source pixel
BDLTS	copy color to dest if dest < source pixel
Source independent
BCOPYC	copy color
BORC	OR dest AND color
BXORC	XOR dest AND color
BNDORC	(NOT)(dst_val OR clr)
BDORNC	dst_val OR (~clr)
BANDC	dest AND color
BNDANDC	copy (~dst_val) & clr
BDLTS	dest NOT color

draw

Function	Arguments	Description
circle	(img, cx, cy, radius, color, bClip)	draw a circle
circle_filled	(img, cx, cy, radius, color, fillcolor, bClip)	draw a filled circle fillcolor is color if left empty
ellipse	(img, cx, cy, a, b, color, bClip)	draw ellipse cx, cy define center point; a, b the major/minor axis
ellipse_filled	(img, cx, cy, a, b, color, fillcolor, bClip)	draw ellipse cx, cy define center point; a, b the major/minor axis fillcolor is color if left empty
ellipse_rect	(img, x1, y1, x2, y2, color, bClip)	draw ellipse that fits into defined rect
ellipse_rect_filled	(img, x1, y1, x2, y2, color, fillcolor, bClip)	draw ellipse that fits into defined rect fillcolor is color if left empty
hline	(img, x, y , length, color, bClip)	draw a horizontal line
image	(dst, src, x, y, bClip)	draw an image at xy coord in dest image
line	(img, x1, y1, x2, y2, color, bClip)	draw a line
rect	(img, x, y, width, height, color, bClip)	draw a rectangle
rect_filled	(img, x, y, width, height, color, fillcolor, bClip)	draw a filled rectangle fillcolor is color if left empty
rounded_rect	(img, x, y, w, h, radius, color, bClip)	draw rounded rectangle
rounded_rect_filled	(img, x, y, w, h, radius, color, fillcolor, bClip)	draw filled rounded rectangle fillcolor is color if left empty
vline	(img, x, y , length, color, bClip)	draw a vertical line

bClip [true/false] turns bounds clipping on or off Default = false

draw_floodfill

Function	Arguments	Description
anonymous	(img, x, y, targetclr, fillclr)	floods an area of targetclr with fillclr x, y specifies the start seed

draw_poly

Function	Arguments	Description
polygon	(img, x, y, t_points, color, fillcolor, bClip)	draws a closed figure based on points in t_points fillcolor is color if left empty
polyline	(img, x, y, t_points, color, bClosed, bClip)	draws a non-filled figure based on points in t-points bClosed = true will close the figure (line from first point to last point)

bClip [true/false] turns bounds clipping on or off Default = false

draw_text

Function	Arguments	Description
anonymous	(img, x, y, width, height, font, color, text)	draw text onto image if width/height are supplied text is centered

image

Function	Arguments	Description
load	(filename)	returns new image -of- file: name (_NIL if error)
new	(w, h)	creates a new rbimage size w x h
resize	(dst, src)	resize src to size of dst
rotate	(img, degrees)	return new image -of- img rotated in whole degrees 0 - 360
search	(img, x1, y1, x2, y2, targetclr, variation, stepx, stepy)	search an image for target color
tile	(img, w, h)	return new image -of- img sized to fit w/h tiling to fit if needed

Variable	Description
RLI_INFO_ALL	img:__tostring(RLI_INFO_ALL) Same as tostring(img)
RLI_INFO_ADDRESS	img:__tostring(RLI_INFO_ADDRESS)
RLI_INFO_BYTES	img:__tostring(RLI_INFO_BYTES)
RLI_INFO_DEPTH	img:__tostring(RLI_INFO_DEPTH)
RLI_INFO_ELEMS	img:__tostring(RLI_INFO_ELEMS)
RLI_INFO_FORMAT	img:__tostring(RLI_INFO_FORMAT)
RLI_INFO_HEIGHT	img:__tostring(RLI_INFO_HEIGHT)
RLI_INFO_TYPE	img:__tostring(RLI_INFO_TYPE)
RLI_INFO_WIDTH	img:__tostring(RLI_INFO_WIDTH)

image_save

Function	Arguments	Description
anonymous	(img, path/name)	save as bitmap, bitdepth is limited by the device

lcd

Function	Arguments	Description
_LCD:clear	(clr, ...)	clear lcd, optional.. ([color, x1, y1, x2, y2, clip])
_LCD:duplicate	([img])	return a copy of lcd screen
_LCD:image	(src, x, y)	load an image to screen
_LCD:set_viewport	(vp)	Set viewport size etc.
_LCD:splashf	(timeout, ...)	Formattable version of splash
_LCD:text_extent	(msg, [font])	get w, h of text
_LCD:update	()	update screen Same as rb.lcd_update()
_LCD:update_rect	(x, y, w, h)	update screen in specified rectangle

Variable	Description
CX	Center of screen width
CY	Center of screen height
DEPTH	screen depth in bits
H	screen height
W	screen width

math_ex

The math_ex module provides some math functions missing from Rocklua

Function	Arguments	Description
clamp	(iVal, iMin, iMax)	clamps value to >= min and <= max
clamp_roll	(iVal, iMin, iMax)	clamps value to >= min and <= max rolls over to opposite
d_sin	(iDeg, bExtraPrecision)	sine is multiplied by 10000 since no Floating Point support
d_cos	(iDeg, bExtraPrecision)	cosine is multiplied by 10000 since no Floating Point support
d_tan	(iDeg, bExtraPrecision)	tangent is multiplied by 10000 since no Floating Point support
i_sqrt	(num)	Newtons square root approximation

print

printtable

timer

-- WilliamWilgus - 02 Aug 2019