lcd.loadMask

since 1.1.0

Load a mask from a file. Allowed formats are BMP / JPG / PNG, 8-bit/color, RGB.

local maskHandle = lcd.loadMask(path[, lazy])

Parameters

Name	Type	Required	Description
path	string	yes	mask path
lazy	boolean	optional (default true)	lazy load (only loaded when needed)

Returns

maskHandle (userdata): mask handle

Examples

-- load once, at file level (relative paths only resolve while main.lua loads)
local ICON = lcd.loadMask("gfx/warning.png")

local function paint(widget)
  if ICON then
    lcd.color(widget.alarm and lcd.RGB(230, 50, 50) or lcd.themeColor(THEME_DEFAULT_COLOR))
    lcd.drawMask(4, 4, ICON)
  end
end

Mask images: black on white

In a mask, dark pixels are drawn (in the current color) and white is transparent. Verified in the Ethos 26.1 simulator. Draw icons as black shapes on a white background.

Loading is lazy by default (lazy = true): the image is decoded on first draw. The simulator console then logs Bitmap ... loaded, RAM used: N bytes.

Used in

• System tool with a form
• bluetooth
• tool-form
• tool-servo
• widget-lcddemo
• wizard

Real-world usage

Called 252 times across 6 open-source Ethos Lua projects. A few short excerpts:

Example 1Example 2Example 3

local icon = lcd.loadMask("srx.png")

lua/frsky/SR6MiniE_Cali/main.lua:113

local folderIcon = lcd.loadMask("app/gfx/logs_folder.png")

src/rfsuite/app/pages/logs.lua:15

local mask = lcd and lcd.loadMask and lcd.loadMask(path) or nil

src/rfsuite/app/app.lua:657