Interface ITextureProvider

Service that grants you access to textures you may render via ImGui.

Remarks

<p> Create functions will return a new texture, and the returned instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap must be disposed after use. </p> <p> Get functions will return a shared texture, and the returnd instance of Dalamud.Interface.Textures.ISharedImmediateTexture do not require calling System.IDisposable.Dispose, unless a new reference has been created by calling Dalamud.Interface.Textures.ISharedImmediateTexture.RentAsync(System.Threading.CancellationToken).

Use Dalamud.Interface.Textures.ISharedImmediateTexture.TryGetWrap(Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap@,System.Exception@) and alike to obtain a reference of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap that will stay valid for the rest of the frame. </p> <p> debugName parameter can be used to name your textures, to aid debugging resource leaks using Dalamud.Interface.Internal.Windows.Data.Widgets.TexWidget. </p>

Assembly: Dalamud.dll

Declaration

public interface ITextureProvider : IDalamudService

Methods

CreateEmpty(RawImageSpecification, bool, bool, string?)

Creates an empty texture.

Declaration

IDalamudTextureWrap CreateEmpty(RawImageSpecification specs, bool cpuRead, bool cpuWrite, string? debugName = null)

Returns

Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap: A new empty texture.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.RawImageSpecification	specs	Texture specifications.
System.Boolean	cpuRead	Whether to support reading from CPU, while disabling reading from GPU.
System.Boolean	cpuWrite	Whether to support writing from CPU, while disabling writing from GPU.
System.String	debugName	Name for debug display purposes.

CreateDrawListTexture(string?)

Creates a texture that can be drawn from an Dalamud.Bindings.ImGui.ImDrawList or an Dalamud.Bindings.ImGui.ImDrawData.

Declaration

IDrawListTextureWrap CreateDrawListTexture(string? debugName = null)

Returns

Dalamud.Interface.Textures.TextureWraps.IDrawListTextureWrap: A new draw list texture.

Parameters

Type	Name	Description
System.String	debugName	Name for debug display purposes.

Remarks

No new resource is allocated upfront; it will be done when Dalamud.Interface.Textures.TextureWraps.IDrawListTextureWrap.Size is set with positive values for both components.

CreateFromExistingTextureAsync(IDalamudTextureWrap, TextureModificationArgs, bool, string?, CancellationToken)

Creates a texture from the given existing texture, cropping and converting pixel format as needed.

Declaration

Task<IDalamudTextureWrap> CreateFromExistingTextureAsync(IDalamudTextureWrap wrap, TextureModificationArgs args = default, bool leaveWrapOpen = false, string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A System.Threading.Tasks.Task1` containing the copied texture on success. Dispose after use.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap	wrap	The source texture wrap. The passed value may be disposed once this function returns,

        without having to wait for the completion of the returned `System.Threading.Tasks.Task`1`. |

| Dalamud.Interface.Textures.TextureModificationArgs | args | The texture modification arguments. | | System.Boolean | leaveWrapOpen | Whether to leave <code class="paramref">wrap</code> non-disposed when the returned System.Threading.Tasks.Task1completes. | |System.String| *debugName* | Name for debug display purposes. | |System.Threading.CancellationToken` | cancellationToken | The cancellation token. |

Remarks

<p>This function may throw an exception.</p>

CreateFromImGuiViewportAsync(ImGuiViewportTextureArgs, string?, CancellationToken)

Creates a texture from an ImGui viewport.

Declaration

Task<IDalamudTextureWrap> CreateFromImGuiViewportAsync(ImGuiViewportTextureArgs args, string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A System.Threading.Tasks.Task1` containing the copied texture on success. Dispose after use.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.ImGuiViewportTextureArgs	args	The arguments for creating a texture.
System.String	debugName	Name for debug display purposes.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p>Use ImGui.GetMainViewport().ID to capture the game screen with Dalamud rendered.</p> <p>This function may throw an exception.</p>

CreateFromImageAsync(ReadOnlyMemory<byte>, string?, CancellationToken)

Gets a texture from the given bytes, trying to interpret it as a .tex file or other well-known image files, such as .png.

Declaration

Task<IDalamudTextureWrap> CreateFromImageAsync(ReadOnlyMemory<byte> bytes, string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A System.Threading.Tasks.Task1` containing the loaded texture on success. Dispose after use.

Parameters

Type	Name	Description
System.ReadOnlyMemory<System.Byte>	bytes	The bytes to load.
System.String	debugName	Name for debug display purposes.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p>This function may throw an exception.</p>

CreateFromImageAsync(Stream, bool, string?, CancellationToken)

Gets a texture from the given stream, trying to interpret it as a .tex file or other well-known image files, such as .png.

Declaration

Task<IDalamudTextureWrap> CreateFromImageAsync(Stream stream, bool leaveOpen = false, string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A System.Threading.Tasks.Task1` containing the loaded texture on success. Dispose after use.

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream to load data from.
System.Boolean	leaveOpen	Whether to leave the stream open once the task completes, sucessfully or not.
System.String	debugName	Name for debug display purposes.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p><code class="paramref">stream</code> will be closed or not only according to <code class="paramref">leaveOpen</code>; <code class="paramref">cancellationToken</code> is irrelevant in closing the stream.</p> <p>This function may throw an exception.</p>

CreateFromRaw(RawImageSpecification, ReadOnlySpan<byte>, string?)

Gets a texture from the given bytes, interpreting it as a raw bitmap.

Declaration

IDalamudTextureWrap CreateFromRaw(RawImageSpecification specs, ReadOnlySpan<byte> bytes, string? debugName = null)

Returns

Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap: The texture loaded from the supplied raw bitmap. Dispose after use.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.RawImageSpecification	specs	The specifications for the raw bitmap.
System.ReadOnlySpan<System.Byte>	bytes	The bytes to load.
System.String	debugName	Name for debug display purposes.

Remarks

<p>This function may throw an exception.</p>

CreateFromRawAsync(RawImageSpecification, ReadOnlyMemory<byte>, string?, CancellationToken)

Gets a texture from the given bytes, interpreting it as a raw bitmap.

Declaration

Task<IDalamudTextureWrap> CreateFromRawAsync(RawImageSpecification specs, ReadOnlyMemory<byte> bytes, string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A System.Threading.Tasks.Task1` containing the loaded texture on success. Dispose after use.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.RawImageSpecification	specs	The specifications for the raw bitmap.
System.ReadOnlyMemory<System.Byte>	bytes	The bytes to load.
System.String	debugName	Name for debug display purposes.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p>This function may throw an exception.</p>

CreateFromRawAsync(RawImageSpecification, Stream, bool, string?, CancellationToken)

Gets a texture from the given stream, interpreting the read data as a raw bitmap.

Declaration

Task<IDalamudTextureWrap> CreateFromRawAsync(RawImageSpecification specs, Stream stream, bool leaveOpen = false, string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A System.Threading.Tasks.Task1` containing the loaded texture on success. Dispose after use.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.RawImageSpecification	specs	The specifications for the raw bitmap.
System.IO.Stream	stream	The stream to load data from.
System.Boolean	leaveOpen	Whether to leave the stream open once the task completes, sucessfully or not.
System.String	debugName	Name for debug display purposes.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p><code class="paramref">stream</code> will be closed or not only according to <code class="paramref">leaveOpen</code>; <code class="paramref">cancellationToken</code> is irrelevant in closing the stream.</p> <p>This function may throw an exception.</p>

CreateFromTexFile(TexFile)

Get a texture handle for the specified Lumina Lumina.Data.Files.TexFile. Alias for fetching System.Threading.Tasks.Task1.ResultfromDalamud.Plugin.Services.ITextureProvider.CreateFromTexFileAsync(Lumina.Data.Files.TexFile,System.String,System.Threading.CancellationToken)`.

Declaration

IDalamudTextureWrap CreateFromTexFile(TexFile file)

Returns

Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap: A texture wrap that can be used to render the texture. Dispose after use.

Parameters

Type	Name	Description
Lumina.Data.Files.TexFile	file	The texture to obtain a handle to.

Remarks

<p>This function may throw an exception.</p>

CreateFromTexFileAsync(TexFile, string?, CancellationToken)

Get a texture handle for the specified Lumina Lumina.Data.Files.TexFile.

Declaration

Task<IDalamudTextureWrap> CreateFromTexFileAsync(TexFile file, string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A texture wrap that can be used to render the texture. Dispose after use.

Parameters

Type	Name	Description
Lumina.Data.Files.TexFile	file	The texture to obtain a handle to.
System.String	debugName	Name for debug display purposes.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

<p>This function may throw an exception.</p>

CreateFromClipboardAsync(string?, CancellationToken)

Creates a texture from clipboard.

Declaration

Task<IDalamudTextureWrap> CreateFromClipboardAsync(string? debugName = null, CancellationToken cancellationToken = default)

Returns

System.Threading.Tasks.Task<Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap>: A System.Threading.Tasks.Task representing the status of the operation.

Parameters

Type	Name	Description
System.String	debugName	Name for debug display purposes.
System.Threading.CancellationToken	cancellationToken	The cancellation token.

CreateTextureFromSeString(ReadOnlySpan<byte>, scoped in SeStringDrawParams, string?)

Creates a texture by drawing a SeString onto it.

Declaration

IDalamudTextureWrap CreateTextureFromSeString(ReadOnlySpan<byte> text, scoped in SeStringDrawParams drawParams = default, string? debugName = null)

Returns

Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap: The new texture.

Parameters

Type	Name	Description
System.ReadOnlySpan<System.Byte>	text	SeString to render.
Dalamud.Interface.ImGuiSeStringRenderer.SeStringDrawParams	drawParams	Parameters for drawing.
System.String	debugName	Name for debug display purposes.

Remarks

Can be only be used from the main thread.

GetSupportedImageDecoderInfos()

Gets the supported bitmap decoders.

Declaration

IEnumerable<IBitmapCodecInfo> GetSupportedImageDecoderInfos()

Returns

System.Collections.Generic.IEnumerable<Dalamud.Interface.Textures.IBitmapCodecInfo>: The supported bitmap decoders.

Remarks

<p>The following functions support the files of the container types pointed by yielded values.</p> <ul> <li>Dalamud.Plugin.Services.ITextureProvider.GetFromFile(string) and Dalamud.Plugin.Services.ITextureProvider.GetFromFile(System.IO.FileInfo)</li> <li>Dalamud.Plugin.Services.ITextureProvider.GetFromManifestResource(System.Reflection.Assembly,System.String)</li> <li>Dalamud.Plugin.Services.ITextureProvider.CreateFromImageAsync(System.ReadOnlyMemory<System.Byte>,System.String,System.Threading.CancellationToken)</li> <li>Dalamud.Plugin.Services.ITextureProvider.CreateFromImageAsync(System.IO.Stream,System.Boolean,System.String,System.Threading.CancellationToken)</li> </ul> <p>This function may throw an exception.</p>

GetFromGameIcon(in GameIconLookup)

Gets a shared texture corresponding to the given game resource icon specifier.

Declaration

ISharedImmediateTexture GetFromGameIcon(in GameIconLookup lookup)

Returns

Dalamud.Interface.Textures.ISharedImmediateTexture: The shared texture that you may use to obtain the loaded texture wrap and load states.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.GameIconLookup	lookup	A game icon specifier.

Remarks

<p>This function is under the effect of Dalamud.Plugin.Services.ITextureSubstitutionProvider.GetSubstitutedPath(string).</p> <p>Caching the returned object is not recommended. Performance benefit will be minimal.</p>

HasClipboardImage()

Gets a value indicating whether the current desktop clipboard contains an image that can be attempted to read using Dalamud.Plugin.Services.ITextureProvider.CreateFromClipboardAsync(System.String,System.Threading.CancellationToken).

Declaration

bool HasClipboardImage()

Returns

System.Boolean: true if it is the case.

TryGetFromGameIcon(in GameIconLookup, out ISharedImmediateTexture?)

Gets a shared texture corresponding to the given game resource icon specifier.

Declaration

bool TryGetFromGameIcon(in GameIconLookup lookup, out ISharedImmediateTexture? texture)

Returns

System.Boolean: Whether the lookup succeeded.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.GameIconLookup	lookup	A game icon specifier.
Dalamud.Interface.Textures.ISharedImmediateTexture	texture	The resulting Dalamud.Interface.Textures.ISharedImmediateTexture.

Remarks

<p>This function does not throw exceptions.</p> <p>This function is under the effect of Dalamud.Plugin.Services.ITextureSubstitutionProvider.GetSubstitutedPath(string).</p> <p>Caching the returned object is not recommended. Performance benefit will be minimal.</p>

GetFromGame(string)

Gets a shared texture corresponding to the given path to a game resource.

Declaration

ISharedImmediateTexture GetFromGame(string path)

Returns

Dalamud.Interface.Textures.ISharedImmediateTexture: The shared texture that you may use to obtain the loaded texture wrap and load states.

Parameters

Type	Name	Description
System.String	path	A path to a game resource.

Remarks

<p>This function is under the effect of Dalamud.Plugin.Services.ITextureSubstitutionProvider.GetSubstitutedPath(string).</p> <p>This function does not throw exceptions.</p> <p>Caching the returned object is not recommended. Performance benefit will be minimal.</p>

GetFromFile(string)

Gets a shared texture corresponding to the given file on the filesystem.

Declaration

ISharedImmediateTexture GetFromFile(string path)

Returns

Dalamud.Interface.Textures.ISharedImmediateTexture: The shared texture that you may use to obtain the loaded texture wrap and load states.

Parameters

Type	Name	Description
System.String	path	A path to a file on the filesystem.

Remarks

<p>This function does not throw exceptions.</p> <p>Caching the returned object is not recommended. Performance benefit will be minimal.</p>

GetFromFile(FileInfo)

Gets a shared texture corresponding to the given file on the filesystem.

Declaration

ISharedImmediateTexture GetFromFile(FileInfo file)

Returns

Dalamud.Interface.Textures.ISharedImmediateTexture: The shared texture that you may use to obtain the loaded texture wrap and load states.

Parameters

Type	Name	Description
System.IO.FileInfo	file	The file on the filesystem to load.

Remarks

<p>This function does not throw exceptions.</p> <p>Caching the returned object is not recommended. Performance benefit will be minimal.</p>

GetFromFileAbsolute(string)

Gets a shared texture corresponding to the given file on the filesystem.

Declaration

ISharedImmediateTexture GetFromFileAbsolute(string fullPath)

Returns

Dalamud.Interface.Textures.ISharedImmediateTexture: The shared texture that you may use to obtain the loaded texture wrap and load states.

Parameters

Type	Name	Description
System.String	fullPath	The file on the filesystem to load. Requires a full path.

Remarks

<p>This function does not throw exceptions.</p> <p>Caching the returned object is not recommended. Performance benefit will be minimal.</p>

GetFromManifestResource(Assembly, string)

Gets a shared texture corresponding to the given file of the assembly manifest resources.

Declaration

ISharedImmediateTexture GetFromManifestResource(Assembly assembly, string name)

Returns

Dalamud.Interface.Textures.ISharedImmediateTexture: The shared texture that you may use to obtain the loaded texture wrap and load states.

Parameters

Type	Name	Description
System.Reflection.Assembly	assembly	The assembly containing manifest resources.
System.String	name	The case-sensitive name of the manifest resource being requested.

Remarks

<p>This function does not throw exceptions.</p> <p>Caching the returned object is not recommended. Performance benefit will be minimal.</p>

GetIconPath(in GameIconLookup)

Get a path for a specific icon's .tex file.

Declaration

string GetIconPath(in GameIconLookup lookup)

Returns

System.String: The path to the icon.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.GameIconLookup	lookup	The icon lookup.

Exceptions

System.IO.FileNotFoundException
If a corresponding file could not be found.

TryGetIconPath(in GameIconLookup, out string?)

Gets the path of an icon.

Declaration

bool TryGetIconPath(in GameIconLookup lookup, out string? path)

Returns

System.Boolean: true if the corresponding file exists and <code class="paramref">path</code> has been set.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.GameIconLookup	lookup	The icon lookup.
System.String	path	The resolved path.

Remarks

<p>This function does not throw exceptions.</p>

IsDxgiFormatSupported(int)

Determines whether the system supports the given DXGI format. For use with Dalamud.Interface.Textures.RawImageSpecification.DxgiFormat.

Declaration

bool IsDxgiFormatSupported(int dxgiFormat)

Returns

System.Boolean: true if supported.

Parameters

Type	Name	Description
System.Int32	dxgiFormat	The DXGI format.

Remarks

<p>This function does not throw exceptions.</p>

IsDxgiFormatSupportedForCreateFromExistingTextureAsync(int)

Determines whether the system supports the given DXGI format for use with Dalamud.Plugin.Services.ITextureProvider.CreateFromExistingTextureAsync(Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap,Dalamud.Interface.Textures.TextureModificationArgs,System.Boolean,System.String,System.Threading.CancellationToken).

Declaration

bool IsDxgiFormatSupportedForCreateFromExistingTextureAsync(int dxgiFormat)

Returns

System.Boolean: true if supported.

Parameters

Type	Name	Description
System.Int32	dxgiFormat	The DXGI format.

Remarks

<p>This function does not throw exceptions.</p>

ConvertToKernelTexture(IDalamudTextureWrap, bool)

Converts an existing Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap instance to a new instance of FFXIVClientStructs.FFXIV.Client.Graphics.Kernel.Texture which can be used to supply a custom texture onto an in-game addon (UI element.)

Declaration

nint ConvertToKernelTexture(IDalamudTextureWrap wrap, bool leaveWrapOpen = false)

Returns

System.IntPtr: Address of the new FFXIVClientStructs.FFXIV.Client.Graphics.Kernel.Texture.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap	wrap	Instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap to convert.
System.Boolean	leaveWrapOpen	Whether to leave <code class="paramref">wrap</code> non-disposed when the returned

        `System.Threading.Tasks.Task`1` completes. |

Remarks

<p>If the returned kernel texture is to be destroyed, call the fourth function in its vtable, by calling FFXIVClientStructs.FFXIV.Client.Graphics.Kernel.Texture.DecRef or ((delegate* unmanaged<nint, void>)(*(nint**)ptr)[3](ptr).</p>

Examples

See PrintTextureInfo in Dalamud.Interface.Internal.UiDebug.Browsing.ImageNodeTree for an example of replacing the texture of an image node.