Mod Loader/Reference/Texture API

Use ModTextureApi when your plugin displays a loader-managed texture in its own material, renderer, or UI. A managed texture can change resolution while keeping the same Unity object. These APIs tell the loader when the texture is in use or when your code needs the original pixels immediately.

Call these methods on Unity's main thread. To load an image from your plugin folder, use mod.Textures.Load; see plugin texture loading. The examples here target Mod Loader 0.7.8.

Choose tracking or a pin

You need to...	Use
Keep textures in use while a custom preview is open	`RegisterMaterial` or `RegisterRenderer`. Use Pin when the original pixels are needed immediately.
Read original pixels or capture an image before the next line of code	`Pin`. It loads the original synchronously and prevents eviction until disposed.
Tell the loader a renderer or UI image changed	`NotifyChanged`. It queues another check for a later update.

Track a preview material

Keep one registration while the preview exists. Dispose it when you close the preview, before destroying its material. Put these members inside your plugin class:

private System.IDisposable previewTextures;

private void OpenPreview(UnityEngine.Material material)
{
    previewTextures?.Dispose();
    previewTextures = ModTextureApi.RegisterMaterial(material);
}

private void ClosePreview()
{
    previewTextures?.Dispose();
    previewTextures = null;
}

Call ClosePreview from your plugin's OnDestroy too. By default, the material is treated as in use until you dispose the registration or destroy the material. For a persistent preview, pass () => previewIsOpen as the second argument and maintain that boolean when the window opens or closes.

Track a renderer or update a UI image

System.IDisposable usage = ModTextureApi.RegisterRenderer(renderer);

// After assigning a different texture or material:
ModTextureApi.NotifyChanged(renderer);

// When your preview is removed:
usage.Dispose();

The default renderer check uses its enabled, active, and visible state. A supplied predicate replaces those checks. Use one when an instancing or custom drawing system renders a material without enabling the original renderer. Keep predicates short; a throwing predicate is logged and its registration is stopped.

NotifyChanged(rawImage) also accepts a Unity UI graphic. It asks the loader to inspect its current material and texture. Checks share a frame budget and may take more than one frame. Use Pin when you need the original image before continuing.

Read the original image

using (ModTextureApi.Pin(texture))
{
    // Read or capture the full-resolution texture here.
}

A pin can cause disk work and temporarily exceed the texture budget. Keep it only as long as the operation needs it. Pins apply to loader-managed textures; check IsManaged first. Reading pixels also requires a readable Unity texture.

API reference

Member	Behaviour
`bool IsManaged(Texture texture)`	Whether the loader manages this image's resolution.
`IDisposable RegisterMaterial(Material material, Func<bool> isInUse = null)`	Track the material's current textures. By default, it is always in use.
`IDisposable RegisterRenderer(Renderer renderer, Func<bool> isInUse = null)`	Track current renderer materials. A predicate replaces the default visibility checks.
`void NotifyChanged(Component component)`	Request another material/texture check for a renderer or UI graphic.
`IDisposable Pin(Texture texture)`	Restore a managed texture's original resolution and prevent eviction until disposed.
`long ResidentBytes`	Estimated GPU bytes for managed images. Excludes CPU copies and temporary loads.
`long BudgetBytes`	Soft GPU budget. Visible or pinned images can exceed it.

Your plugin owns its Unity materials, renderers, and texture handles. Keep them alive while they are used, then release them when the preview closes. You can hand an IDisposable registration to mod.Track for cleanup with your plugin context.

Back to the Mod Loader guide