feat: new ITextureProvider, ITextureSubstitutionProvider, TextureManager services

Ref-counts textures and evicts when not used

Dalamud/Plugin/Services/IDataManager.cs

@@ -1,4 +1,5 @@
-using System.Collections.ObjectModel;
+using System;
+using System.Collections.ObjectModel;
 
 using ImGuiScene;
 using Lumina;
@@ -91,6 +92,7 @@ public interface IDataManager
     /// <param name="iconId">The icon ID.</param>
     /// <param name="highResolution">Return high resolution version.</param>
     /// <returns>The <see cref="TexFile"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TexFile? GetIcon(uint iconId, bool highResolution = false);
 
     /// <summary>
@@ -100,6 +102,7 @@ public interface IDataManager
     /// <param name="iconId">The icon ID.</param>
     /// <param name="highResolution">Return high resolution version.</param>
     /// <returns>The <see cref="TexFile"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TexFile? GetIcon(ClientLanguage iconLanguage, uint iconId, bool highResolution = false);
 
     /// <summary>
@@ -109,6 +112,7 @@ public interface IDataManager
     /// <param name="iconId">The icon ID.</param>
     /// <param name="highResolution">Return high resolution version.</param>
     /// <returns>The <see cref="TexFile"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TexFile? GetIcon(string? type, uint iconId, bool highResolution = false);
     
     /// <summary>
@@ -117,6 +121,7 @@ public interface IDataManager
     /// <param name="iconId">The icon ID.</param>
     /// <param name="highResolution">Return the high resolution version.</param>
     /// <returns>The <see cref="TextureWrap"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TextureWrap? GetImGuiTextureIcon(uint iconId, bool highResolution = false);
 
     /// <summary>
@@ -125,6 +130,7 @@ public interface IDataManager
     /// <param name="isHq">A value indicating whether the icon should be HQ.</param>
     /// <param name="iconId">The icon ID.</param>
     /// <returns>The <see cref="TexFile"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TexFile? GetIcon(bool isHq, uint iconId);
     
     /// <summary>
@@ -132,6 +138,7 @@ public interface IDataManager
     /// </summary>
     /// <param name="iconId">The icon ID.</param>
     /// <returns>The <see cref="TexFile"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TexFile? GetHqIcon(uint iconId);
 
     /// <summary>
@@ -139,6 +146,7 @@ public interface IDataManager
     /// </summary>
     /// <param name="tex">The Lumina <see cref="TexFile"/>.</param>
     /// <returns>A <see cref="TextureWrap"/> that can be used to draw the texture.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TextureWrap? GetImGuiTexture(TexFile? tex);
 
     /// <summary>
@@ -146,6 +154,7 @@ public interface IDataManager
     /// </summary>
     /// <param name="path">The internal path to the texture.</param>
     /// <returns>A <see cref="TextureWrap"/> that can be used to draw the texture.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TextureWrap? GetImGuiTexture(string path);
 
     /// <summary>
@@ -154,6 +163,7 @@ public interface IDataManager
     /// <param name="isHq">A value indicating whether the icon should be HQ.</param>
     /// <param name="iconId">The icon ID.</param>
     /// <returns>The <see cref="TextureWrap"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TextureWrap? GetImGuiTextureIcon(bool isHq, uint iconId);
 
     /// <summary>
@@ -162,6 +172,7 @@ public interface IDataManager
     /// <param name="iconLanguage">The requested language.</param>
     /// <param name="iconId">The icon ID.</param>
     /// <returns>The <see cref="TextureWrap"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TextureWrap? GetImGuiTextureIcon(ClientLanguage iconLanguage, uint iconId);
 
     /// <summary>
@@ -170,6 +181,7 @@ public interface IDataManager
     /// <param name="type">The type of the icon (e.g. 'hq' to get the HQ variant of an item icon).</param>
     /// <param name="iconId">The icon ID.</param>
     /// <returns>The <see cref="TextureWrap"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TextureWrap? GetImGuiTextureIcon(string type, uint iconId);
 
     /// <summary>
@@ -177,5 +189,6 @@ public interface IDataManager
     /// </summary>
     /// <param name="iconId">The icon ID.</param>
     /// <returns>The <see cref="TextureWrap"/> containing the icon.</returns>
+    [Obsolete("Use ITextureManager instead")]
     public TextureWrap? GetImGuiTextureHqIcon(uint iconId);
 }

Dalamud/Plugin/Services/ITextureProvider.cs

@@ -0,0 +1,69 @@
+using System;
+
+using Dalamud.Interface.Internal;
+using Lumina.Data.Files;
+
+namespace Dalamud.Plugin.Services;
+
+/// <summary>
+/// Service that grants you access to textures you may render via ImGui.
+/// </summary>
+public interface ITextureProvider
+{
+    /// <summary>
+    /// Flags describing the icon you wish to receive.
+    /// </summary>
+    [Flags]
+    public enum IconFlags
+    {
+        /// <summary>
+        /// Low-resolution, standard quality icon.
+        /// </summary>
+        None = 0,
+        
+        /// <summary>
+        /// If this icon is an item icon, and it has a high-quality variant, receive the high-quality version.
+        /// Null if the item does not have a high-quality variant.
+        /// </summary>
+        ItemHighQuality = 1 << 0,
+        
+        /// <summary>
+        /// Get the hi-resolution version of the icon, if it exists.
+        /// </summary>
+        HiRes = 1 << 1,
+    }
+    
+    /// <summary>
+    /// Get a texture handle for a specific icon.
+    /// </summary>
+    /// <param name="iconId">The ID of the icon to load.</param>
+    /// <param name="flags">Options to be considered when loading the icon.</param>
+    /// <param name="language">
+    /// The language to be considered when loading the icon, if the icon has versions for multiple languages.
+    /// If null, default to the game's current language.
+    /// </param>
+    /// <param name="keepAlive">
+    /// Prevent Dalamud from automatically unloading this icon to save memory. Usually does not need to be set.
+    /// </param>
+    /// <returns>
+    /// Null, if the icon does not exist in the specified configuration, or a texture wrap that can be used
+    /// to render the icon.
+    /// </returns>
+    public IDalamudTextureWrap? GetIcon(uint iconId, IconFlags flags = IconFlags.HiRes, ClientLanguage? language = null, bool keepAlive = false);
+
+    /// <summary>
+    /// Get a texture handle for the texture at the specified path.
+    /// You may only specify paths in the game's VFS.
+    /// </summary>
+    /// <param name="path">The path to the texture in the game's VFS.</param>
+    /// <param name="keepAlive">Prevent Dalamud from automatically unloading this texture to save memory. Usually does not need to be set.</param>
+    /// <returns>Null, if the icon does not exist, or a texture wrap that can be used to render the texture.</returns>
+    public IDalamudTextureWrap? GetTextureFromGamePath(string path, bool keepAlive = false);
+    
+    /// <summary>
+    /// Get a texture handle for the specified Lumina TexFile.
+    /// </summary>
+    /// <param name="file">The texture to obtain a handle to.</param>
+    /// <returns>A texture wrap that can be used to render the texture.</returns>
+    public IDalamudTextureWrap GetTexture(TexFile file);
+}

Dalamud/Plugin/Services/ITextureSubstitutionProvider.cs

@@ -0,0 +1,21 @@
+namespace Dalamud.Plugin.Services;
+
+/// <summary>
+/// Service that grants you the ability to replace texture data that is to be loaded by Dalamud.
+/// </summary>
+public interface ITextureSubstitutionProvider
+{
+    /// <summary>
+    /// Delegate describing a function that may be used to intercept and replace texture data.
+    /// </summary>
+    /// <param name="path">The path to the texture that is to be loaded.</param>
+    /// <param name="data">The texture data. Null by default, assign something if you wish to replace the data from the game dats.</param>
+    public delegate void TextureDataInterceptorDelegate(string path, ref byte[]? data);
+    
+    /// <summary>
+    /// Event that will be called once Dalamud wants to load texture data.
+    /// If you have data that should replace the data from the game dats, assign it to the
+    /// data argument.
+    /// </summary>
+    public event TextureDataInterceptorDelegate? InterceptTexDataLoad;
+}