love-snippets: small bits of useful functionality

[slime]

I have a GitHub repository containing some small bits of code useful in LÖVE projects. Many of the snippets use LuaJIT's FFI either to replace existing LÖVE functions with better performing versions, or to expose functionality in libraries LÖVE uses which LÖVE itself doesn't expose right now.

Here is the repository: https://github.com/slime73/love-snippets

Currently it contains these snippets:

ImageData-FFI (link)

Replaces several ImageData methods with LuaJIT FFI-enhanced versions. The FFI versions can often perform many times faster than LÖVE's regular versions (up to 100x in some cases), except when your code around those methods would have caused LuaJIT to fall back to interpreted mode instead of JIT mode anyway.
The FFI code was written specifically for LÖVE 0.9.0 and 0.9.1, and is not guaranteed to work in future versions!

Code: Select all

-- Replaces these methods with FFI-enhanced versions:
ImageData:mapPixel(mapfunction)
ImageData:getPixel(x, y)
ImageData:setPixel(x, y, r, g, b, a)
ImageData:getWidth()
ImageData:getHeight()
ImageData:getDimensions()

SoundData-FFI (link)

Replaces several SoundData methods with LuaJIT FFI-enhanced versions. The FFI versions can often perform several times faster than LÖVE's versions, except when your code around those methods would have caused LuaJIT to fall back to interpreted mode instead of JIT mode anyway.
The FFI code was written specifically for LÖVE 0.9.0 and 0.9.1, and is not guaranteed to work in future versions!

Code: Select all

-- Replaces these methods with FFI-enhanced versions:
SoundData:getSample(sample)
SoundData:setSample(sample, value)
SoundData:getSampleCount()
SoundData:getChannels()

FilesystemSymlinks (link)

Functions to let you use symlinked files in love.filesystem. It's still up to you to make sure everything works properly on other people's systems.
It adds these global functions:

Code: Select all

-- Toggles whether symlinks in love.filesystem are enabled.
EnableSymbolicLinks(enable)

-- Returns true if symlinks in love.filesystem are currently enabled.
local enabled = SymbolicLinksEnabled()

-- Returns true if a filepath in love.filesystem is really a symbolic link.
local status = IsSymbolicLink(filename)

OpenSaveFolder (link)

A simple function to open the game's save folder (or a sub-folder inside) with the user's file browser. Mari0 and Snayke both use something like this.

Code: Select all

-- subfolder can be nil
OpenSaveFolder(subfolder)

MessageBox (link)

Adds a function to pop up a simple message box with a title, some text, and a close button. The function doesn't return until the user closes the message box.
This uses LuaJIT's FFI to access a function available in SDL not exposed with LÖVE normally.

Code: Select all

--[[
Arguments:
	mtype (string): The type of message box: "info", "warning", or "error".
	title (string): The title of the message box.
	message (string): The text in the main message area of the message box.
	standalone (boolean): Whether the message box is a standalone window or attached to the game's main window.
	NOTE: using a standalone message box while in fullscreen can cause a hard lock in Mac OS X!
]]
ShowSimpleMessageBox(mtype, title, message, standalone)

Touch (link)

Adds an API for multi-touch capabilities (when using a graphics tablet or a MacBook's trackpad, for example.)
This uses LuaJIT's FFI to access functions available in SDL not exposed with LÖVE normally.

Currently it does not have event callback functions, just an API for getting touches.

The API mirrors my love.touch experimental branch of LÖVE, which is also used in fysx' Android port, but this version does not use the love namespace.

Code: Select all

local touch = require("touch")

-- Gets the number of currently active touches.
local count = touch.getTouchCount()

-- Gets information about a currently active touch. Note that indices are *not stable*, they should only be used in a for-loop with getTouchCount.
-- Returns an ID, normalized x and y coordinates in the range of [0, 1], and the pressure of the touch.
-- The ID is only guaranteed to be unique for the duration of the touch press.
local id, x, y, pressure = touch.getTouch(index)

[Snuux]

Very Cool!

[Ref]

Thanks Slime!
Does SDL provide any facilities to create a DialogBox like iup.ListDialog? - doesn't seem to.
Tested imagedata_ffi.lua on a simple HDR photography script (loads three images and combines) and got ~6% speed increase - not much but better than nothing.
Thanks again.

[slime]

Does SDL provide any facilities to create a DialogBox like iup.ListDialog? - doesn't seem to.

SDL isn't a GUI library, so no.

Tested imagedata_ffi.lua on a simple HDR photography script (loads three images and combines) and got ~6% speed increase - not much but better than nothing.

Make sure your code you use around the ImageData functions isn't causing LuaJIT to fall back to interpreted mode.

[Ref]

Make sure your code you use around the ImageData functions isn't causing LuaJIT to fall back to interpreted mode.

Not sure how to determine if "LuaJIT has fallen back to interpreted mode".
Test script only averaged the r,g,b data of three jpg images and recorded the result to a forth image. Wouldn't expect any problems for LuaJIT but probably wrong again.

[Tanner]

This is great stuff! Could you explain the logic behind this line?

Code: Select all

local sdl = jit.os == "Windows" and ffi.load("SDL2") or ffi.C

It's fairly obvious what it does but can you comment on why it's necessary?

[slime]

Because of the differences between dynamically loaded/linked libraries on Windows vs. OSX/Linux. It's explained a bit here: http://luajit.org/ext_ffi_api.html#ffi_C

On POSIX systems, this binds to symbols in the default or global namespace. This includes all exported symbols from the executable and any libraries loaded into the global namespace. This includes at least libc, libm, libdl (on Linux), libgcc (if compiled with GCC), as well as any exported symbols from the Lua/C API provided by LuaJIT itself.

On Windows systems, this binds to symbols exported from the *.exe, the lua51.dll (i.e. the Lua/C API provided by LuaJIT itself), the C runtime library LuaJIT was linked with (msvcrt*.dll), kernel32.dll, user32.dll and gdi32.dll.

[Tanner]

Ah, interesting. Thanks for the link.