Image manipulation tutorial

The Developer's Image Library (or DevIL for short) offers extended functionality for loading, saving, converting, filtering and manipulating image files. It supports a wide variety of image formats many of which are not natively supported by the engine. Notice that if you just want to load and render a texture (without manipulating it) you probably won't need DevIL all: the image object can load .png and .bmp files in a much simpler way.

Loading images with DevIL

As a standalone Lua extension, DevIL can load and manipulate almost any image file. To render that image however, we have to transfer it to the engine. In this example, we will load a .jpg image, covert it to a proper format and render it on the screen. In addition to .jpg, DevIL also supports .bmp, .cut, .dds, .doom, .exr, .hdr, .ico, .jp2, .jpg,.lbm, .mdl, .mng, .pal, .pbm, .pcd, .pcx, .pgm, .pic, .png, .ppm, .psd, .psp, .raw, .sgi, .tga and .tif files.

require ( 'Devil' )

display:create ( "DevIL", 800, 600, 32, true )

-- initialize DevIL
devil.ilInit ( )
devil.iluInit ( )

-- load an image file and convert it to a format supported by the engine
devil.ilLoadImage ( "Tutorials/kitten.jpg" )
devil.ilConvertImage ( devil.IL_BGRA, devil.IL_UNSIGNED_BYTE )

-- transfer our image to the engine
local info = devil.ILinfo ( )
devil.iluGetImageInfo ( info )

local image = Image ( )
image:load_memory ( IMG_FORMAT_A8R8G8B8, info.Width, info.Height, devil.ilGetData ( ) )

-- release DevIL
devil.ilShutDown ( )

-- draw the image
sprite = Sprite ( )
sprite.canvas:set_source_image ( image )
sprite.canvas:paint ( )
display.viewport:add_child ( sprite )
Download:  devil.lua
kitten.jpg


Filters

One of the many features of DevIL is the option to filter loaded images. You can try some of the following filters before loading an image into the engine. Please refer to the official DevIL documentation for a full list.

-- blur/sharpen filters:
iluBlurAvg ( iterations )
iluBlurGaussian ( iterations )
iluSharpen ( factor, iterations )

-- color/contrast filters:
iluContrast ( contrast )
iluEqualize ( )
iluGammaCorrect ( gamma )
iluInvertAlpha ( )
iluReplaceColour ( red, green, blue, tolerance )
iluSwapColours ( )

-- effect filters:
iluAlienify ( )
iluEdgeDetectE ( )
iluEdgeDetectP ( )
iluEdgeDetectS ( )
iluEmboss ( )
iluNoisify ( tolerance )

devil.iluBlurAvg ( 20 )

devil.iluBlurGaussian ( 20 )

devil.iluSharpen ( 2, 5 )

devil.iluContrast ( 5 )

devil.iluEqualize ( )

devil.iluGammaCorrect ( 2 )

devil.iluSwapColours ( )

devil.iluAlienify ( )

devil.iluNoisify ( 5 )