This recipe will show you how to load images from various file formats. SDL_image supports the file formats BMP, CUR, GIF, ICO, JPG, LBM, PCX, PNG, PNM, TGA, TIF, XCF, XPM, and XV. SDL_image is a part of the LuaSDL module.
All images are loaded into the new surface object. File formats with support for transparent pixels (it's not the same as the alpha channel) would have set the color key attribute on the surface.
The SDL_image library depends on third-party libraries to load JPEG and PNG files. Make sure that you have the libjpeg, libpng, and zlib libraries installed. SDL_image doesn't require any additional initialization. LuaSDL handles this internally.
There are two ways of loading images:
- Loading an image file directly to surface: This method uses the
SDL.SDL_IMG_Loadfunction, where the only parameter is the image filename. If there is such a file and it is accessible to the application,SDL.SDL_IMG_Loadwill try to guess a file format by its extension. Finally, if everything goes well, it'll return a surface object with the image. Otherwise, it'll return a nil value.However, there's a downside because you can't detect whether the file doesn't exist or is unreadable. Another thing is that if the extension doesn't correspond with the file format, this function will fail.
The following code shows you how to use this function to load an image file:
local surface = assert(SDL.SDL_IMG_Load("image.png")) - Loading an image file with the use of RWop: RWop is a form of file I/O abstraction offered by libSDL. This means libSDL offers you a way to load files regardless of the platform. Another thing to mention is that you can easily load file content from the text string or system memory.
The SDL_image library supports loading image files with the RWop file object and also encourages users to use this way because it's much safer and you can also detect specific problems when something fails during image loading.
To load an image file, you need to create the RWop file object with the
SDL.SDL_RWFromFilefunction. The following example shows you how to do this:local image_file = assert(SDL.SDL_RWFromFile("image.png", "rb"))
The first parameter is the file path and the second is a string representing the mode to be used for opening the file. The mode is usually rb, which means that you are using the file for reading binary data. After this step, you can load an image from the RWop object provided with the SDL.IMG_Load_RW or SDL.IMG_LoadTyped_RW function. While the first function will always try to detect the image format, the second one accepts an image format specification. Both these functions use the second parameter to determine whether the submitted RWop object can be closed automatically. This is especially useful if you don't plan to read that file again. These functions will return the surface object with the image upon success. The image type can specified by one of these strings in uppercase BMP, CUR, GIF, ICO, JPG, LBM, PCX, PNG, PNM, TGA, TIF, XCF, XPM, and XV.
The following example shows how to use these functions to load the image from the RWop object:
local image_auto = assert(SDL.IMG_Load_RW(image_file, 1)) local image_png = assert(SDL.IMG_LoadTyped_RW(image_file, 1, "PNG"))
Even if you choose to load the image file with the SDL.SDL_IMG_Load function, it uses the RWop object internally. If an error occurs, you can rely only on the SDL.SDL_GetError function to get a better view on what went wrong.
The resulting image will be stored into a new surface object with the corresponding pixel format. Always check for the pixel format of the resulting surface to avoid confusion later. A typical example can be a PNG file, which supports 1, 2, 4, 8, 16, 24, and 32-bit color depth with or without palette, grayscale with the alpha channel or even 64-bit color depth.