Magnum::Trade::BasisImporter class new in 2019.10

Basis Universal importer plugin.

Supports Basis Universal (*.basis) compressed images by parsing and transcoding files into an explicitly specified GPU format (see Target format). You can use BasisImageConverter to transcode images into this format.

This plugin depends on the Trade and Basis Universal libraries and is built if WITH_BASISIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, you need to load the "BasisImporter" plugin from MAGNUM_PLUGINS_IMPORTER_DIR. To use as a static plugin or as a dependency of another plugin with CMake, you need to request the BasisImporter component of the MagnumPlugins package and link to the MagnumPlugins::BasisImporter target. See Downloading and building plugins, Loading and using plugins for more information.

This plugin provides BasisImporterEacR, BasisImporterEacRG, BasisImporterEtc1RGB, BasisImporterEtc2RGBA, BasisImporterBc1RGB, BasisImporterBc3RGBA, BasisImporterBc4R, BasisImporterBc5RG, BasisImporterBc7RGB, BasisImporterBc7RGBA, BasisImporterPvrtc1RGB4bpp, BasisImporterPvrtc1RGBA4bpp, BasisImporterAstc4x4RGBA, BasisImporterRGBA8.

Plugin-specific configuration

Basis allows configuration of the format of loaded compressed data. The full form of the configuration is shown below:

[configuration]

# No format is specified by default and you have to choose one either
# by changing this value or by loading the plugin under an alias. See
# class documentation for more information.
format=

Target format

Basis is a compressed format that is transcoded into a compressed GPU format. With BasisImporter, this format can be chosen in different ways:

/* Choose ETC2 target format */
Containers::Pointer<Trade::AbstractImporter> importerEtc2 =
    manager.instantiate("BasisImporterEtc2");

/* Choose BC5 target format */
Containers::Pointer<Trade::AbstractImporter> importerBc5 =
    manager.instantiate("BasisImporterBc5");

The list of valid suffixes is equivalent to enum value names in TargetFormat. If you want to be able to change the target format dynamically, you may want to set the format configuration of the plugin, as shown below. If you instantiate this class directly without a plugin manager, you may also use setTargetFormat().

/* Instantiate the plugin under its default name. At this point, the plugin
   would decompress to full RGBA8, which is usually not what you want. */
Containers::Pointer<Trade::AbstractImporter> importer =
    manager.instantiate("BasisImporter");
importer->openFile("mytexture.basis");

/* Transcode the image to BC5 */
importer->configuration().setValue("format", "Bc5");
image = importer->image2D(0);
// ...

/* Transcode the same image, but to ETC2 now */
importer->configuration().setValue("format", "Etc2");
image = importer->image2D(0);
// ...

There's many options and you should be generally striving for highest-quality format available on given platform. Detailed description of the choices is in Basis Universal README. As an example, the following code is a decision making used by magnum-player based on availability of corresponding OpenGL, OpenGL ES and WebGL extensions, in its full ugly glory:

if(PluginManager::PluginMetadata* metadata = manager.metadata("BasisImporter")) {
    GL::Context& context = GL::Context::current();
    using namespace GL::Extensions;
    #ifdef MAGNUM_TARGET_WEBGL
    if(context.isExtensionSupported<WEBGL::compressed_texture_astc>())
    #else
    if(context.isExtensionSupported<KHR::texture_compression_astc_ldr>())
    #endif
    {
        metadata->configuration().setValue("format", "Astc4x4RGBA");
    }
    #ifdef MAGNUM_TARGET_GLES
    else if(context.isExtensionSupported<EXT::texture_compression_bptc>())
    #else
    else if(context.isExtensionSupported<ARB::texture_compression_bptc>())
    #endif
    {
        metadata->configuration().setValue("format", "Bc7RGBA");
    }
    #ifdef MAGNUM_TARGET_WEBGL
    else if(context.isExtensionSupported<WEBGL::compressed_texture_s3tc>())
    #elif defined(MAGNUM_TARGET_GLES)
    else if(context.isExtensionSupported<EXT::texture_compression_s3tc>() ||
            context.isExtensionSupported<ANGLE::texture_compression_dxt5>())
    #else
    else if(context.isExtensionSupported<EXT::texture_compression_s3tc>())
    #endif
    {
        metadata->configuration().setValue("format", "Bc3RGBA");
    }
    #ifndef MAGNUM_TARGET_GLES2
    else
    #ifndef MAGNUM_TARGET_GLES
    if(context.isExtensionSupported<ARB::ES3_compatibility>())
    #endif
    {
        metadata->configuration().setValue("format", "Etc2RGBA");
    }
    #else /* For ES2, fall back to PVRTC as ETC2 is not available */
    else
    #ifdef MAGNUM_TARGET_WEBGL
    if(context.isExtensionSupported<WEBGL::compressed_texture_pvrtc>())
    #else
    if(context.isExtensionSupported<IMG::texture_compression_pvrtc>())
    #endif
    {
        metadata->configuration().setValue("format", "PvrtcRGBA4bpp");
    }
    #endif
    #if defined(MAGNUM_TARGET_GLES2) || !defined(MAGNUM_TARGET_GLES)
    else /* ES3 has ETC2 always */
    {
        /* Fall back to uncompressed if nothing else is supported */
        metadata->configuration().setValue("format", "RGBA8");
    }
    #endif
}

Base classes

class AbstractImporter
Base for importer plugins.

Public types

enum class TargetFormat: UnsignedInt { Etc1RGB = 0, Etc2RGBA = 1, Bc1RGB = 2, Bc3RGBA = 3, Bc4R = 4, Bc5RG = 5, Bc7RGB = 6, Bc7RGBA = 7, PvrtcRGB4bpp = 8, PvrtcRGBA4bpp = 9, Astc4x4RGBA = 10, RGBA8 = 13, EacR = 20, EacRG = 21 }
Type to transcode to.

Public static functions

static void initialize()
Initialize Basis transcoder.

Constructors, destructors, conversion operators

BasisImporter() explicit
Default constructor.
BasisImporter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.

Public functions

auto targetFormat() const -> TargetFormat
Target format.
void setTargetFormat(TargetFormat format)
Set the target format.

Enum documentation

enum class Magnum::Trade::BasisImporter::TargetFormat: UnsignedInt

Type to transcode to.

If the image does not contain an alpha channel and the target format has it, alpha will be set to opaque. Conversely, for output formats without alpha the channel will be dropped.

Enumerators
Etc1RGB

ETC1 RGB. Loaded as CompressedPixelFormat::Etc2RGB8Unorm (which ETC1 is a subset of). If the image contains an alpha channel, it will be dropped since ETC1 alone doesn't support alpha.

Etc2RGBA

ETC2 RGBA. Loaded as CompressedPixelFormat::Etc2RGBA8Unorm.

Bc1RGB

BC1 RGB. Loaded as CompressedPixelFormat::Bc1RGBUnorm. Punchthrough alpha mode of CompressedPixelFormat::Bc1RGBAUnorm is not supported.

Bc3RGBA

BC2 RGBA. Loaded as CompressedPixelFormat::Bc3RGBAUnorm.

Bc4R

BC4 R. Loaded as CompressedPixelFormat::Bc4RUnorm.

Bc5RG

BC5 RG. Loaded as CompressedPixelFormat::Bc5RGUnorm.

Bc7RGB

BC7 RGB (mode 6). Loaded as CompressedPixelFormat::Bc7RGBAUnorm, but with alpha values set to opaque.

Bc7RGBA

BC7 RGBA (mode 5). Loaded as CompressedPixelFormat::Bc7RGBAUnorm.

PvrtcRGB4bpp

PVRTC1 RGB 4 bpp. Loaded as CompressedPixelFormat::PvrtcRGB4bppUnorm.

PvrtcRGBA4bpp

PVRTC1 RGBA 4 bpp. Loaded as CompressedPixelFormat::PvrtcRGBA4bppUnorm.

Astc4x4RGBA

ASTC 4x4 RGBA. Loaded as CompressedPixelFormat::Astc4x4RGBAUnorm.

RGBA8

Uncompressed 32-bit RGBA. Loaded as PixelFormat::RGBA8Unorm. If no concrete format is specified, the importer will fall back to this.

EacR

EAC unsigned red component. Loaded as CompressedPixelFormat::EacR11Unorm.

EacRG

EAC unsigned red and green component. Loaded as CompressedPixelFormat::EacRG11Unorm.

Function documentation

static void Magnum::Trade::BasisImporter::initialize()

Initialize Basis transcoder.

If the class is instantiated directly (not through a plugin manager), this function has to be called explicitly before using any instance.

void Magnum::Trade::BasisImporter::setTargetFormat(TargetFormat format)

Set the target format.

See Target format for more information.