Table of Contents

Class Texture<TDriver>

Namespace
Sdl3Sharp.Video.Rendering
Assembly
Sdl3Sharp.dll

Represents a texture, created by a Renderer<TDriver>

public sealed class Texture<TDriver> : Texture, IDisposable where TDriver : notnull, IRenderingDriver

Type Parameters

TDriver

The rendering driver type associated with this texture

Inheritance
Texture<TDriver>
Implements
Inherited Members

Remarks

This is an efficient driver-specific representation of pixel data.

You can create new textures using the TryCreateTexture(PixelFormat, TextureAccess, int, int, out Texture<TDriver>?), TryCreateTexture(out Texture<TDriver>?, ColorSpace?, PixelFormat?, TextureAccess?, int?, int?, Palette?, float?, float?, Properties?), or TryCreateTextureFromSurface(Surface, out Texture<TDriver>?) instance methods on a Renderer<TDriver> instance.

Additionally, there are some driver-specific methods for creating textures, such as Direct3D 11, Direct3D 12, GPU, Metal, OpenGL, OpenGL ES 2, and Vulkan.

Please remember to dispose Texture<TDriver>s before disposing the Renderer<TDriver> that created them! Using an Texture<TDriver> after its associated Renderer<TDriver> has been disposed can lead to undefined behavior, including corruption and crashes.

Texture<TDriver>s are concrete texture types, associated with a specific rendering driver. They are used in driver-specific rendering operations with the Renderer<TDriver> that created them.

If you want to use them in a more general way, you can use them as Texture instances, which serve as abstractions to use them in common rendering operations with the Renderer instance that created them.

Properties

Renderer

Gets the renderer that created the texture

public Renderer<TDriver>? Renderer { get; }

Property Value

Renderer<TDriver>

The renderer that created the texture, or null if the renderer could not be retrieved successfully (check TryGet(out string?) for more information)

Methods

TryLock(in Rect<int>, out TexturePixelMemoryManager<TDriver>?)

Tries to lock an area of the texture for write-only pixel access and set up a pixel memory manager

public bool TryLock(in Rect<int> rect, out TexturePixelMemoryManager<TDriver>? pixelManager)

Parameters

rect Rect<int>

The area of the texture to lock for write-only pixel access

pixelManager TexturePixelMemoryManager<TDriver>

The pixel memory manager meant to be used to access the texture's pixels, if this method returns true; otherwise, null

Returns

bool

true, if the texture was successfully locked for write-only pixel access successfully and the pixelManager was created; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Texture texture;

...

if (texture.TryLock(in rect, out var pixelManager))
{
	using (pixelManager)
	{
		// Write-only access to the texture's pixels as a Surface through 'pixelManager.Memory' using 'pixelManager.Pitch'
		// Make sure to fully initialize ALL the pixels locked

		...
	}
}

Remarks

This method is meant to be used as a simpler and safer alternative to using TryUnsafeLock(in Rect<int>, out NativeMemory, out int) and UnsafeUnlock().

This method fails and returns false if the texture's Access is not Streaming.

If the pixelManager was created successfully, you can use its Memory property to write the pixel memory of the locked area, using this texture's Format. Once you're done accessing the pixel memory, you should dispose the pixelManager to unlock the texture and apply the changes.

As an optimization, the pixels made available for editing don't necessarily contain the old texture data. This is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level.

Warning: Please note that locking a texture is intended to be write-only; it will not guarantee the previous contents of the texture will be provided. You must fully initialize any area of a texture that you locked before unlocking it (disposing the pixelManager), as the pixels might otherwise be uninitialized memory. E.g., if you locked a texture and immediately unlocked it again without writing any pixel data, the texture could end up in a corrupted state, depending on the renderer in use.

This method should only be called from the main thread.

TryLock(out TexturePixelMemoryManager<TDriver>?)

Tries to lock the entire texture for write-only pixel access and set up a pixel memory manager

public bool TryLock(out TexturePixelMemoryManager<TDriver>? pixelManager)

Parameters

pixelManager TexturePixelMemoryManager<TDriver>

The pixel memory manager meant to be used to access the texture's pixels, if this method returns true; otherwise, null

Returns

bool

true, if the texture was successfully locked for write-only pixel access successfully and the pixelManager was created; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Texture texture;

...

if (texture.TryLock(out var pixelManager))
{
	using (pixelManager)
	{
		// Write-only access to the texture's pixels as a Surface through 'pixelManager.Memory' using 'pixelManager.Pitch'
		// Make sure to fully initialize ALL the pixels locked

		...
	}
}

Remarks

This method is meant to be used as a simpler and safer alternative to using TryUnsafeLock(out NativeMemory, out int) and UnsafeUnlock().

This method fails and returns false if the texture's Access is not Streaming.

If the pixelManager was created successfully, you can use its Memory property to write the pixel memory of the entire texture, using this texture's Format. Once you're done accessing the pixel memory, you should dispose the pixelManager to unlock the texture and apply the changes.

As an optimization, the pixels made available for editing don't necessarily contain the old texture data. This is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level.

Warning: Please note that locking a texture is intended to be write-only; it will not guarantee the previous contents of the texture will be provided. You must fully initialize any area of a texture that you locked before unlocking it (disposing the pixelManager), as the pixels might otherwise be uninitialized memory. E.g., if you locked a texture and immediately unlocked it again without writing any pixel data, the texture could end up in a corrupted state, depending on the renderer in use.

This method should only be called from the main thread.

TryLockToSurface(in Rect<int>, out TextureSurfaceManager<TDriver>?)

Tries to lock an area of the texture for write-only pixel access and set up a surface manager

public bool TryLockToSurface(in Rect<int> rect, out TextureSurfaceManager<TDriver>? surfaceManager)

Parameters

rect Rect<int>

The area of the texture to lock for write-only pixel access

surfaceManager TextureSurfaceManager<TDriver>

The surface manager meant to be used to access the texture's pixels, if this method returns true; otherwise, null

Returns

bool

true, if the texture was successfully locked for write-only pixel access successfully and the surfaceManager was created; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Texture texture;

...

if (texture.TryLockToSurface(in rect, out var surfaceManager))
{
	using (surfaceManager)
	{
		// Write-only access to the texture's pixels as a Surface through 'surfaceManager.Surface'
		// Make sure to fully initialize ALL the pixels locked

		...
	}
}

Remarks

This method is meant to be used as a simpler and safer alternative to using TryUnsafeLockToSurface(in Rect<int>, out Surface?) and UnsafeUnlock().

This method fails and returns false if the texture's Access is not Streaming.

If the surfaceManager was created successfully, you can use its Surface property to access the pixels of the locked area as a Surface. Once you're done accessing the pixels, you should dispose the surfaceManager to unlock the texture and apply the changes.

As an optimization, the pixels made available for editing don't necessarily contain the old texture data. This is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level.

Warning: Please note that locking a texture is intended to be write-only; it will not guarantee the previous contents of the texture will be provided. You must fully initialize any area of a texture that you locked before unlocking it (disposing the surfaceManager), as the pixels might otherwise be uninitialized memory. E.g., if you locked a texture and immediately unlocked it again without writing any pixel data, the texture could end up in a corrupted state, depending on the renderer in use.

This method should only be called from the main thread.

TryLockToSurface(out TextureSurfaceManager<TDriver>?)

Tries to lock the entire texture for write-only pixel access and set up a surface manager

public bool TryLockToSurface(out TextureSurfaceManager<TDriver>? surfaceManager)

Parameters

surfaceManager TextureSurfaceManager<TDriver>

The surface manager meant to be used to access the texture's pixels, if this method returns true; otherwise, null

Returns

bool

true, if the texture was successfully locked for write-only pixel access successfully and the surfaceManager was created; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Texture texture;

...

if (texture.TryLockToSurface(out var surfaceManager))
{
	using (surfaceManager)
	{
		// Write-only access to the texture's pixels as a Surface through 'surfaceManager.Surface'
		// Make sure to fully initialize ALL the pixels locked

		...
	}
}

Remarks

This method is meant to be used as a simpler and safer alternative to using TryUnsafeLockToSurface(out Surface?) and UnsafeUnlock().

This method fails and returns false if the texture's Access is not Streaming.

If the surfaceManager was created successfully, you can use its Surface property to access the pixels of the entire texture as a Surface. Once you're done accessing the pixels, you should dispose the surfaceManager to unlock the texture and apply the changes.

As an optimization, the pixels made available for editing don't necessarily contain the old texture data. This is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level.

Warning: Please note that locking a texture is intended to be write-only; it will not guarantee the previous contents of the texture will be provided. You must fully initialize any area of a texture that you locked before unlocking it (disposing the surfaceManager), as the pixels might otherwise be uninitialized memory. E.g., if you locked a texture and immediately unlocked it again without writing any pixel data, the texture could end up in a corrupted state, depending on the renderer in use.

This method should only be called from the main thread.

Edit this page