MysticCoder
MysticThumbs

Plugins

Add new image formats to MysticThumbs

Download example plugin here (Visual Studio 2008 and 2010 projects included)
Note: The VS projects are quite old now but can easily be imported into a newer version of Visual Studio and upgraded for use.

How to use

Use this example project as a template to make your own.

Visual Studio 2008/2010 projects are supplied for convenience. Newer versions can easily upgrade the project.

Visual Studio Express for Desktop is available FREE from Microsoft here.

Make one plugin project for each file type. If you require different file types create new plugins for each. You register each file format extension necessary for the file format, so you can for example register multiple extensions such as JPEG has with .jpg, .jpeg etc.

The core interface that must be implemented is the IMysticThumbsPlugin interface. In this example the class CExamplePlugin implements this.

MysticThumbs can request any number of these objects so it is very important that you do not use any static variables that could cause conflicts amongst concurrent running objects. Encapsulate everything in your class.

The documentation and comments in the MysticThumbsPlugin.h header file specify all the required information that you will need to successfully implement your own plugin.

For the purposes of the example, we use the .mtp extension (which is actually the plugin extension for MysticThumbs plugins) and generate a test pattern image dynamically of the requested thumbnail size.

IMysticThumbsPlugin::GenerateImage method

This is the meat of the plugin.

In a typical plugin you will read from the passed IStream interface pointer that points to the head of the file being thumbnailed. This method parses the file and generates the thumbnail and returns the image data un-scaled. It is not usually necessary to scale your image, and you can simply read and pass the full image back, this will yield the fastest and best results. MysticThumbs and Explorer will take care of scaling appropriate to control panel and operating system requirements. The desiredSize and flags parameters are merely hints should you require them.

If however, you are generating a thumbnail of an abstract nature, say for example a sound waveform similar to the existing .wav format produces, then your image could be of any arbitary size, and the desiredSize parameter can be used to determine the best size to render to.

The desiredSize parameter represents the size of the thumbnail that Explorer is requesting at the time, this could be for example 32, 48, 96, 256 or even very large if requesting for QuickView purposes. It is the width in pixels of the requested thumbnail.
The flags parameter gives you hints as to what the control panel settings are for your file extension, such as transparency, embedded thumbnail and scaling settings. This may be expanded upon in future releases.

Building

Ensure you build for x86 and x64 platforms. The example project already has the required projects set up and ready to modify.

The x86 plugin should end with 32.mtp and the x64 plugin should end with 64.mtp, for example ExamplePlugin32.mtp and ExamplePlugin64.mtp.

Place the plugin output files in a plugins folder in the MysticThumbs install directory, eg. "C:\Program Files\MysticCoder\MysticThumbs\plugins\ExamplePlugin32.mtp"

Restart Explorer and they will be automatically loaded by MysticThumbs.

Register the plugin in the MysticThumbs control panel. Use the "Plugins" button, where you can register and unregister plugins. Register will install the required Explorer hooks for the file extensions assigned to the plugin and Unregister will remove the hooks.

Using

If the plugin loads successfully you will find it in the MysticThumbs control panel under an entry corresponding to the name you return in the method IMysticThumbsPlugin::GetName().
You can now use it just as you would any other natively supported file format with all the benefits of the control panel options.

To test the example plugin

  • Build Win32 and x64 Release configurations and place the resulting .mtp files in the MysticThumbs plugin folder.
  • Create a dummy, empty file on your desktop called test.mtp
  • Restart Explorer, for example using the MysticThumbs tray icon or task manager.
  • Provided the plugin loaded you should see the test pattern display for your test.mtp file that looks like this:

Test thumbnail


Now modify the test project to suit your needs and file formats and see your images with all the MysticThumbs thumbnail configuration options available for your file format.