Preface
This is the reference manual of MoonSOIL, which is a Lua binding library for the Simple OpenGL Image Library (SOIL). [1]
It is assumed that the reader is familiar with both SOIL and the Lua programming language.
For convenience of reference, this document contains external (deep) links to the Lua Reference Manual.
Getting and installing
For installation intructions, refer to the README file in the MoonSOIL official repository on GitHub.
Module organization
The MoonSOIL module is loaded using Lua’s require() and returns a table containing the functions it provides (as usual with Lua modules). This manual assumes that such table is named soil, i.e. that it is loaded with:
soil = require("moonsoil")but nothing forbids the use of a different name.
Examples
A few examples can be found in the examples/ directory of the release package.
License
MoonSOIL is released under the MIT/X11 license (same as Lua, and with the same only requirement to give proper credits to the original author). The copyright notice is in the LICENSE file in the base directory of the official repository on GitHub.
SOIL bindings
All the functions listed here are members of the soil table.
-
string = last_result( )
-
n = channels(channels)
Returns the number of channels corresponding to the given channels string. -
data, width, height, channels = load_image(filename, forcechannels)
-
data, width, height, channels = load_image_from_memory(buffer, forcechannels)
-
boolean, errmsg = save_image(filename, imagetype, width, height, channels, data)
-
boolean, errmsg = save_screenshot(filename, imagetype, x, y, width, height)
|
Note
|
The following functions require OpenGL. In order to use them, you can create a GL context using a windowing library such as MoonGLFW, and initialize it with MoonGL (see the examples for more details). |
-
texid = load_texture(filename, forcechannels, texid, flags)
-
texid = load_cubemap(xposfilename, xnegfilename, yposfilename, ynegfilename, zposfilename, znegfilename, forcechannels, texid, flags)
-
texid = load_single_cubemap(filename, faceorder, forcechannels, texid, flags)
-
texid = load_hdr_texture(filename, fakehdr, rescaletomax, texid, flags)
-
texid = load_texture_from_memory(buffer, forcechannels, texid, flags)
-
texid = load_cubemap_from_memory(xposbuffer, xnegbuffer, yposbuffer, ynegbuffer, zposbuffer, znegbuffer, forcechannels, texid, flags)
-
texid = load_single_cubemap_from_memory(buffer, faceorder, forcechannels, texid, flags)
-
texid = create_texture(data, width, height, channels, texid, flags)
-
texid = create_single_cubemap(data, width, height, channels, faceorder, texid, flags)
buffer, xposbuffer, xnegbuffer, …: binary string.
channels: 'luminous' (greyscale), 'luminous/alpha', 'rgb', 'rgba'.
data: binary string.
faceorder: a permutation of the string 'ESWNUD' (East, South, West, North, Up, Down).
fakehdr: 'rgbe', 'rgbdiva', 'rgbdiva2'.
flags: a bitfield. May be passed either as an integer code obtained by combining
soil.FLAG_XXX values (corresponding to SOIL_FLAG_XXX defines) or as a sequence of literals
from the set listed below.
Values: 'power of two', 'mipmaps', 'texture repeats', 'multiply alpha', 'invert y', 'compress to dxt', 'dds load direct', 'ntsc safe rgb', 'ycocg', 'texture rectangle'.
forcechannels: 'auto', or one of channels.
imagetype: 'tga', 'bmp', 'dds'.
rescaletomax: boolean.
texid id of OpenGL texture to reuse (=0 or nil to create a new texture).
KTX functions
This section describes MoonSOIL additions to handle textures in the KTX File Format.
(Note that these are MoonSOIL additions, i.e. not bindings to SOIL.)
-
ktxtexture = load_ktx(filename)
Loads a texture from a KTX file and returns its contents in a table.
This function raises a Lua error if an error occurs while parsing the file. -
data = ktx_data(ktxtexture)
Returns a binary string obtained by concatenating the data fields of all the levels in the given ktxtexture (i.e., the whole texture data, padding included). -
string = ktx_tostring(ktxtexture)
Returns a printable string with the contents of the given ktxtexture.
ktxtexture = {
filename: string,
little_endian: boolean,
texture_type: texturetype,
gl_type: gltype,
gl_format: glformat,
gl_internal_format: glinternalformat,
gl_base_internal_format: glformat,
array_elements: integer,
faces: integer,
mipmap_levels: integer,
key_value_data: binary string,
levels: {mipmaplevel},
} (rfr: KTF File Format Specification)
mipmaplevel = {
width: integer,
height: integer,
depth: integer,
size: integer (image size or face size, see note below),
padding: integer (mip padding or cube padding, see note below),
data: binary string (see note below),
}
Note: the meaning of the size and padding fields and the composition of the data field
depend on the texture_type this mipmap_level belongs to. In particular:
- if texture_type is 'cube map', then size and padding refer to a single face, and data contains 6*(size + padding) bytes concatenating the data for the 6 faces, in order from the first to the sixth;
- for all other texture types, data contains size + padding bytes, and is composed of the image of this level followed by the mip padding;
- for array textures (including 'cube map array'), the level image is the concatenation of the images for all the array elements, each composed of size/array_elements bytes.
texturetype: string literal
Values: '1d', '1d array', '2d', '2d array', '3d', 'cube map', 'cube map array'.
gltype: string literal
Values:@@TODO.
glformat: string literal
Values:@@TODO.
glinternalformat: string literal
Values:@@TODO.