ImageGlass.SDK 1.0.100266

ImageGlass SDK

The official development kit for extending ImageGlass 10. ImageGlass.SDK is a single .NET 10 class library that defines the public contracts for the two ways you can extend ImageGlass.

What you can build

A few concrete examples of what the SDK makes possible:

• A codec that decodes a custom or rare image format and renders it like any built-in format — still or animated.
• A color picker that reports the RGBA value under the user's click.
• A batch/automation tool that watches photo navigation and runs actions against the current image, selection, or theme.

The two surfaces are independent — pick the one that matches what you want to build. See Samples for working, end-to-end examples of each.

Installation

Install the package from NuGet:

dotnet add package ImageGlass.SDK

The library targets net10.0 and depends only on SkiaSharp. It is AOT- and trim-compatible, so your plugin or tool can publish with Native AOT.

Building this repository

Requires the .NET 10 SDK.

dotnet build source/ImageGlass.SDK.slnx

Supported platforms: x64, ARM64, AnyCPU.

Samples

The samples/ folder contains complete, runnable projects — the fastest way to see each extension surface end to end. Each sample has its own README with build, install, and registration steps.

🟢 Building a Codec Plugin

Plugins run in-process and communicate with the host through function-pointer tables (a C ABI), so they can be written in any language that can export a C entry point and produce a native shared library.

A plugin ships as a folder containing the native library plus an igplugin.json manifest:

{
  "id": "Plugin_MyCodec",
  "name": "My Codec",
  "version": "1.0.0",
  "author": "You",
  "kind": "Codec",
  "executable": "MyCodec.dll",        // MyCodec.so / MyCodec.dylib on other platforms
  "supportedExtensions": ".foo;.bar"   // optional; overrides the plugin-reported list
}

The host loads the library and calls the single required export:

const IGPluginApi* ig_plugin_get_api(int hostAbiVersion, const IGHostApi* hostApi);

It returns an IGPluginApi table (plugin identity + GetCodec/Initialize/Shutdown/SelfTest). Each codec then exposes an IGCodecApi table: capability reporting, extension/signature matching, LoadMetadata, DecodeStaticRaster, and optional animation entry points.

Key contracts to honor:

• ABI version — encoded as MAJOR * 1_000_000 + MINOR * 1_000 + PATCH (IGNativeAbi.IG_PLUGIN_ABI_VERSION). The host rejects plugins whose major version does not match.
• Memory ownership — the plugin allocates pixel/animation buffers; the host calls back into the plugin's FreePixelBuffer / FreeAnimationInfo to release them. FreePixelBuffer must be thread-safe — it may be invoked from any thread when the host disposes the image.
• Animation — decoded animation frames must be fully composed RGBA at full canvas size. The host does not perform sub-rect composition or disposal/blend replay, so codecs like GIF/APNG must composite internally.
• Cancellation — long operations receive an opaque cancellation token; poll IGHostCoreApi.IsCancellationRequested and return IGStatus.Canceled when set.

🟢 Building a Tool

Tools run out-of-process. Subclass ToolBase, then start it from your program's entry point:

using ImageGlass.SDK.Tools;

public sealed class MyTool : ToolBase
{
    public override string ToolId => "MyTool";   // must match igconfig.json

    protected override Task OnExecuteAsync(CancellationToken ct)
    {
        // Triggered by the host. Talk back through HostApi.
        return Task.CompletedTask;
    }

    protected override void OnPhotoChanged(PhotoChangedEventArgs e)
    {
        // React to the user navigating to another photo.
    }
}

public static class Program
{
    public static Task Main(string[] args) => new MyTool().RunAsync(args);
}

ImageGlass launches the tool with a --pipe <name> argument; RunAsync connects to the host and runs the message loop until shutdown.

• Host → tool events arrive as OnXxx overrides (OnInitializedAsync, OnExecuteAsync, OnPhotoChanged, OnThemeChanged, OnSelectionChanged, …).
• Tool → host calls go through HostApi (IToolHostProxy): read pixels, get the full pixel buffer (via a memory-mapped file), query photo metadata and the photo list, get/set the selection, run named ImageGlass API methods, and read theme info.
• Real-time pointer/selection/frame events are opt-in via HostApi.SubscribeEventsAsync.
• Register the tool with ImageGlass through an igconfig.json entry whose ToolId matches your ToolBase.ToolId.

Passing the current file to the tool

In the Arguments field of the igconfig.json entry you can use the <file> macro. ImageGlass replaces it with the full path of the currently viewed image when it launches the tool:

"Tools": [
  {
    "ToolId": "Tool_MyTool",
    "ToolName": "My Tool",
    "Executable": "C:\\path\\to\\MyTool.exe",
    "Arguments": "--input \"<file>\"",   // expands to: --input "C:\Photos\my image.png"
    "IsIntegrated": true,
    "Hotkeys": ["Alt+1"]
  }
]

• IsIntegrated — true makes this an SDK tool: ImageGlass launches the process with the --pipe <name> argument and wires up the two-way HostApi proxy, so the tool can use ToolBase/HostApi to talk to the host. Set it false (or omit it) for a plain external program that is just launched with its arguments and gets no pipe connection.
• Hotkeys — an array of key-combination strings that run the tool when pressed in ImageGlass (e.g. ["Alt+1"], ["K"]). Use an empty array [] if you don't want a shortcut.

<file> expands to the path without quotes — wrap it yourself as "<file>" when the path may contain spaces. The expanded value arrives in your tool's args (the string[] passed to Main / RunAsync).

Set EnableDebug = true and provide a DebugLog sink before calling RunAsync to trace pipe connection and message dispatch when a tool appears to "do nothing".

License

MIT © 2026 Duong Dieu Phap