MoonSOIL: Lua bindings for SOIL

*** This project is discontinued, superseded by MoonImage. ***

---

MoonSOIL is a Lua binding library for the Simple OpenGL Image Library (SOIL).

It runs on GNU/Linux and on Windows (MSYS2/MinGW) and requires Lua (>=5.3).

SOIL itself is not required because MoonSOIL includes its sources.

Authored by: Stefano Trettel

License

MIT/X11 license (same as Lua). See LICENSE.

Documentation, Getting and installing, etc.

See the Reference Manual.

Getting and installing

Setup the build environment as described here, then:

$ git clone https://github.com/stetre/moonsoil
$ cd moonsoil
moonsoil$ make
moonsoil$ make install # or 'sudo make install' (Ubuntu)

Examples

The script below loads an image from file.

-- MoonSOIL example: load_image.lua

soil = require("moonsoil")

-- Load an image from a file. The image is returned as a binary string.
data, w, h, channels = soil.load_image("dice6.png", 'rgb')
-- Check if an error occurred:
assert(data, soil.last_result())

print(string.format("Loaded %dx%d %s image (%d bytes)", w, h, channels, #data))

The script can be executed at the shell prompt with the standard Lua interpreter:

$ lua load_image.lua

The script below loads an image from file directly into an OpenGL texture.

Since SOIL uses OpenGL functions for this purpose, the script also uses MoonGLFW and MoonGL to create a GL context and properly initialize it.

-- MoonSOIL example: load_texture.lua

gl = require("moongl")
glfw = require("moonglfw")
soil = require("moonsoil")

-- SOIL functions create OpenGL textures using OpenGL functions, so
-- prior to use them we need to ensure that OpenGL is initialized.
-- For this purpose, we use MoonGLFW to create a window and make its
-- GL context current. Then we call MoonGL's gl.Init() - which is
-- essentially glewInit() - to initialize OpenGL.
window = glfw.create_window(100, 100)
glfw.make_context_current(window)
gl.init() -- i.e. glewInit()

-- Now OpenGL's function pointers should be properly initialized, and
-- SOIL can use them without causing segmentation faults.

-- Load an image file directly as a new OpenGL texture:
texid, errmsg = soil.load_texture("dice6.png", 'auto', nil, 
   'mipmaps', 'invert y', 'ntsc safe rgb', 'compress to dxt');
assert(texid, errmsg)
print(string.format("Loaded texture %d (should be 1)", texid))

Other examples can be found in the examples/ directory.

See also

• MoonLibs - Graphics and Audio Lua Libraries.