Magnum::Trade::DevIlImageImporter class
#include <MagnumPlugins/DevIlImageImporter/DevIlImageImporter.h>

DevIL Image importer plugin.

Imports a large variety of image file types using the DevIL library, including (note that the list is incomplete):

  • Windows Bitmap (*.bmp)
  • Dr. Halo (*.cut)
  • Multi-PCX (*.dcx)
  • Dicom (*.dicom, *.dcm)
  • DirectDraw Surface (*.dds), details
  • OpenEXR (*.exr), details
  • Flexible Image Transport System (*.fits, *.fit)
  • Heavy Metal: FAKK 2 (*.ftx)
  • Graphics Interchange Format (*.gif), details
  • Radiance HDR (*.hdr)
  • Macintosh icon (*.icns)
  • Windows icon/cursor (*.ico, *.cur), details
  • Interchange File Format (*.iff)
  • Infinity Ward Image (*.iwi)
  • JPEG (*.jpg, *.jpe, *.jpeg)
  • JPEG 2000 (*.jp2)
  • Interlaced Bitmap (*.lbm)
  • Homeworld texture (*.lif)
  • Half-Life Model (*.mdl)
  • Multiple-image Network Graphics (*.mng)
  • MPEG-1 Audio Layer 3 (*.mp3)
  • PaintShop Pro Palette (*.pal)
  • Halo Palette (*.pal)
  • Kodak PhotoCD (*.pcd)
  • ZSoft PCX (*.pcx)
  • Softimage PIC (*.pic)
  • Portable Network Graphics (*.png), details
  • Portable Anymap (*.pbm, *.pgm, *.ppm, *.pnm)
  • Alias PIX (*.pix)
  • Adobe Photoshop (*.psd), details
  • PaintShop Pro (*.psp)
  • Pixar (*.pxr)
  • Raw data (*.raw)
  • Homeworld 2 Texture (*.rot)
  • Silicon Graphics (*.sgi, *.bw, *.rgb, *.rgba)
  • Creative Assembly Texture (*.texture)
  • Truevision TGA (*.tga, *.vda, *.icb, *.vst)
  • Tagged Image File Format (*.tif, *.tiff)
  • Gamecube Texture (*.tpl)
  • Unreal Texture (*.utx)
  • Quake 2 Texture (*.wal)
  • Valve Texture Format (*.vtf)
  • HD Photo (*.wdp, *.hdp)
  • X Pixel Map (*.xpm)
  • Doom graphics

This plugins provides BmpImporter, DdsImporter, OpenExrImporter, GifImporter, HdrImporter, IcoImporter, JpegImporter, Jpeg2000Importer, MngImporter, PcxImporter, PbmImporter, PgmImporter, PicImporter, PngImporter, PnmImporter, PpmImporter, PsdImporter, SgiImporter, TgaImporter and TiffImporter plugins.

Usage

This plugin depends on the Trade and DevIL libraries and is built if MAGNUM_WITH_DEVILIMAGEIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "DevIlImageImporter" via Corrade::PluginManager::Manager.

Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins repository and do the following. Using DevIL itself as a CMake subproject isn't tested at the moment, so you need to provide it as a system dependency and point CMAKE_PREFIX_PATH to its installation dir if necessary.

set(MAGNUM_WITH_DEVILIMAGEIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the dynamically loaded plugin gets built implicitly
add_dependencies(your-app MagnumPlugins::DevIlImageImporter)

To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake and FindDevIL.cmake into your modules/ directory, request the DevIlImageImporter component of the MagnumPlugins package in CMake and link to the MagnumPlugins::DevIlImageImporter target:

find_package(MagnumPlugins REQUIRED DevIlImageImporter)

# ...
target_link_libraries(your-app PRIVATE MagnumPlugins::DevIlImageImporter)

See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins and File format support for more information.

Behavior and limitations

The images are imported as PixelFormat::R8Unorm, PixelFormat::RG8Unorm, PixelFormat::RGB8Unorm and PixelFormat::RGBA8Unorm. BGR/BGRA will be converted to PixelFormat::RGB8Unorm / PixelFormat::RGBA8Unorm, all other formats to PixelFormat::RGBA8Unorm. Images are imported with default PixelStorage parameters except for alignment, which may be changed to 1 if the data require it.

Compressed DDS files

DDS files with BCn compression are always decompressed to RGBA on input.

OpenEXR files

Although DevIL advertises OpenEXR support, when trying any file it either complained about an invalid extension (0x50b) or, when specifying type=0x0442 in the configuration, failed with an invalid enum error (0x501). Since DevIL internally uses OpenEXR anyway, you'll have a much better luck with OpenExrImporter.

Animated GIFs

In case the file is an animated GIF, the importer will report frame count in image2DCount() and you can then import each frame separately. Unfortunately, GIF transitions are not supported properly and some GIFs can fail to load or crash the library. See StbImageImporter for an alternative.

ICO files

DevIL is able to load ICO files with embedded BMPs, unfortunately it crashes for some ICOs with embedded PNGs and doesn't correctly import alpha for others — use IcoImporter in that case instead. Note that for proper file format auto-detection you either need to load them via openFile() or set the type configuration option to (hexadecimal) 0x0424. Compared to IcoImporter the icon sizes are reported as separate images instead of image levels.

Apple CgBI PNGs

CgBI is a proprietary Apple-specific extension to PNG (details here). DevIL doesn't support these, use StbImageImporter for loading these instead.

PSD files

Based on the source it seems that DevIL parses only the composited view, importing individual layers is not possible.

Plugin-specific configuration

It's possible to tune various output options through configuration(). See below for all options and their default values:

[configuration]
# Override file type when loading the file, one of the hex values from
# https://github.com/DentonW/DevIL/blob/v1.8.0/DevIL/include/IL/il.h#L190-L244
#
# By default set to 0, which is IL_TYPE_UNKNOWN. Useful with openData() and
# formats that have no magic header and can be usually detected only from
# file extension (such as *.ico or *.raw).
type=0x0000

See Editing plugin-specific configuration for more information and an example showing how to edit the configuration values.

Base classes

class AbstractImporter
Base for importer plugins.

Public static functions

static void initialize()
Initialize DevIL library.

Constructors, destructors, conversion operators

DevIlImageImporter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit
Plugin manager constructor.