Interface ISharedImmediateTexture

A texture with a backing instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap that is shared across multiple requesters.

Remarks

<p>Dalamud.Interface.Textures.ISharedImmediateTexture.GetWrapOrEmpty() and Dalamud.Interface.Textures.ISharedImmediateTexture.TryGetWrap(Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap@,System.Exception@) may stop returning the intended texture at any point. Use Dalamud.Interface.Textures.ISharedImmediateTexture.RentAsync(System.Threading.CancellationToken) to lock the texture for use in any thread for any duration.</p>

Assembly: Dalamud.dll

Declaration

public interface ISharedImmediateTexture

Derived:
Dalamud.Interface.Textures.ForwardingSharedImmediateTexture

Methods

GetWrapOrEmpty()

Gets the texture for use with the current frame, or an empty texture if unavailable.

Declaration

IDalamudTextureWrap GetWrapOrEmpty()

Returns

Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap: An instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap that is guaranteed to be available for the current frame being drawn.

Remarks

<p>Do not cache the result of this function across draw calls for different frames. Dalamud.Interface.Textures.ISharedImmediateTextures may be cached, but the performance benefit will be minimal.</p> <p>Calling outside the main thread will fail.</p> <p>This function does not throw.</p> <p>System.IDisposable.Dispose will be ignored, including the cases when the returned texture wrap is passed to a function with leaveWrapOpen parameter.</p> <p>If the texture is unavailable for any reason, then the returned instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap will point to an empty texture instead.</p>

GetWrapOrDefault(IDalamudTextureWrap?)

Gets the texture for use with the current frame, or a default value specified via <code class="paramref">defaultWrap</code> if unavailable.

Declaration

IDalamudTextureWrap? GetWrapOrDefault(IDalamudTextureWrap? defaultWrap = null)

Returns

Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap: An instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap that is guaranteed to be available for the current frame being drawn.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap	defaultWrap	The default wrap to return if the requested texture was not immediately available.

Remarks

<p>Do not cache the result of this function across draw calls for different frames. Dalamud.Interface.Textures.ISharedImmediateTextures may be cached, but the performance benefit will be minimal.</p> <p>Calling outside the main thread will fail.</p> <p>This function does not throw.</p> <p>System.IDisposable.Dispose will be ignored, including the cases when the returned texture wrap is passed to a function with leaveWrapOpen parameter.</p> <p>If the texture is unavailable for any reason, then <code class="paramref">defaultWrap</code> will be returned.</p>

TryGetWrap(out IDalamudTextureWrap?, out Exception?)

Attempts to get the texture for use with the current frame.

Declaration

bool TryGetWrap(out IDalamudTextureWrap? texture, out Exception? exception)

Returns

System.Boolean: true if <code class="paramref">texture</code> points to the loaded texture; false if the texture is still being loaded, or the load has failed.

Parameters

Type	Name	Description
Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap	texture	An instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap that is guaranteed to be available for

        the current frame being drawn, or `null` if texture is not loaded (yet). |

| System.Exception | exception | The load exception, if any. |

Exceptions

System.InvalidOperationException
Thrown when called outside the UI thread.

Remarks

<p>Do not cache the result of this function across draw calls for different frames. Dalamud.Interface.Textures.ISharedImmediateTextures may be cached, but the performance benefit will be minimal.</p> <p>Calling outside the main thread will fail.</p> <p>This function does not throw.</p> <p>System.IDisposable.Dispose on the returned <code class="paramref">texture</code> will be ignored, including the cases when the returned texture wrap is passed to a function with leaveWrapOpen parameter.</p>

RentAsync(CancellationToken)

<p> Creates a new instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap holding a new reference to this texture. The returned texture is guaranteed to be available until System.IDisposable.Dispose is called. </p> <p> WARNING! Usually, this method should be a "last resort"/compatibility wrapper for old code that does not directly support Dalamud.Interface.Textures.ISharedImmediateTexture directly. Prefer using any of the other methods if possible, and DO NOT CACHE the resulting texture wrap from those functions. </p>

Declaration

Task<IDalamudTextureWrap> RentAsync(CancellationToken cancellationToken = default)

Returns

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

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	The cancellation token.

Remarks

System.IDisposable.Dispose must be called on the resulting instance of Dalamud.Interface.Textures.TextureWraps.IDalamudTextureWrap from the returned System.Threading.Tasks.Task1after use. Consider usingDalamud.Utility.DisposeSafety.ToContentDisposedTask1(System.Threading.Tasks.Task<0>,System.Boolean)` to dispose the result automatically according to the state of the task.