release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Search | Go
Wiki > Main > PluginIndex > PluginLua > PluginLuaModules

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
r4 - 04 Aug 2019 - 17:51:28 - WilliamWilgus?

Copyright by the contributing authors.