Table of Contents

Class Texture

Namespace
Sdl3Sharp.Video.Rendering
Assembly
Sdl3Sharp.dll

Represents a texture, created by an Renderer

public abstract class Texture : IDisposable
Inheritance
Texture
Implements
Derived
Texture<TDriver>
Inherited Members

Remarks

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

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

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

Textures are not driver-agnostic! Most of the time instance of this abstract class are of the concrete Texture<TDriver> type with a specific rendering driver as the type argument. However, the Texture type exists as an abstraction to use them in common rendering operations with the Renderer instance that created them.

To specify a concrete texture type, use Texture<TDriver> with a rendering driver that implements the IRenderingDriver interface (e.g. Texture<OpenGL>).

Properties

Access

Gets the access mode of the texture

public TextureAccess Access { get; }

Property Value

TextureAccess

The access mode of the texture

Remarks

The value of this property determines whether the texture is lockable and/or can be used as a render target.

AlphaMod

Gets or sets the additional alpha modulation value multiplied into render copy operations

public byte AlphaMod { get; set; }

Property Value

byte

The additional alpha modulation value multiplied into render copy operations, in the range 0 to 255, where 0 is fully transparent and 255 is fully opaque

Remarks

When this texture is rendered, during the copy operation the source alpha value is modulated by this alpha value according to the following formula: 

srcA = srcA * (alpha / 255)

Alpha modulation is not always supported by the renderer.

The value of this property is equivalent to AlphaModFloat * 255, rounded to the nearest integer.

This property should only be accessed from the main thread.

AlphaModFloat

Gets or sets the additional alpha modulation value multiplied into render copy operations

public float AlphaModFloat { get; set; }

Property Value

float

The additional alpha modulation value multiplied into render copy operations, in the range 0.0 to 1.0, where 0.0 is fully transparent and 1.0 is fully opaque

Remarks

When this texture is rendered, during the copy operation the source alpha value is modulated by this alpha value according to the following formula: 

srcA = srcA * alpha

Alpha modulation is not always supported by the renderer.

The value of this property is equivalent to AlphaMod / 255.

This property should only be accessed from the main thread.

BlendMode

Gets or sets the blend mode used for texture copy operations

public BlendMode BlendMode { get; set; }

Property Value

BlendMode

The blend mode used for texture copy operations

Remarks

This property should only be accessed from the main thread.

Exceptions

SdlException

When setting this property, the specified blend is Invalid or not supported by the renderer (check TryGet(out string?) for more information)

ColorMod

Gets or sets the additional color modulation value multiplied into render copy operations

public (byte R, byte G, byte B) ColorMod { get; set; }

Property Value

(byte r, byte g, byte b)

The additional color modulation value multiplied into render copy operations

Remarks

When this texture is rendered, during the copy operation each source color channel is modulated by the appropriate color value according to the following formula: 

srcC = srcC * (color / 255)

Color modulation is not always supported by the renderer.

The value of this property is equivalent to (ColorModFloat.R * 255, ColorModFloat.G * 255, ColorModFloat.B * 255), each component rounded to the nearest integer.

This property should only be accessed from the main thread.

ColorModFloat

Gets or sets the additional color modulation value multiplied into render copy operations

public (float R, float G, float B) ColorModFloat { get; set; }

Property Value

(float R, float G, float B)

The additional color modulation value multiplied into render copy operations

Remarks

When this texture is rendered, during the copy operation each source color channel is modulated by the appropriate color value according to the following formula: 

srcC = srcC * color

Color modulation is not always supported by the renderer.

The value of this property is equivalent to (ColorMod.R / 255, ColorMod.G / 255, ColorMod.B / 255).

This property should only be accessed from the main thread.

ColorSpace

Gets the color space of the texture

public ColorSpace ColorSpace { get; }

Property Value

ColorSpace

The color space of the texture

Format

Gets the pixel format of the texture

public PixelFormat Format { get; }

Property Value

PixelFormat

The pixel format of the texture

HdrHeadroom

Gets the maximum dynamic range, in terms of the SDR white point

public float HdrHeadroom { get; }

Property Value

float

The maximum dynamic range, in terms of the SDR white point

Remarks

This property is used for HDR10 and floating point textures.

The value of this property defaults to 1.0 for SDR textures, 4.0 for HDR10 textures, and has no default for floating point textures.

Height

Gets the height of the texture

public int Height { get; }

Property Value

int

The height of the texture, in pixels

Palette

Gets or sets the palette used by the texture

public Palette? Palette { get; set; }

Property Value

Palette

The palette used by the texture, or null if the texture doesn't use a palette

Remarks

A palette is only used by textures with an indexed pixel format.

A single Palette can be shared between multiple textures.

Exceptions

SdlException

When setting this property, the specified palette doesn't match the texture's pixel format (check TryGet(out string?) for more information)

Properties

Gets the properties associated with the texture

public Properties? Properties { get; }

Property Value

Properties

The properties associated with the texture, or null if the properties could not be retrieved successfully (check TryGet(out string?) for more information)

Renderer

Gets the renderer that created the texture

public Renderer? Renderer { get; }

Property Value

Renderer

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

ScaleMode

Gets or sets the scale mode used for texture scale operations

public ScaleMode ScaleMode { get; set; }

Property Value

ScaleMode

The scale mode used for texture scale operations

Remarks

The default value of this property is Linear.

This property should only be accessed from the main thread.

Exceptions

SdlException

When setting this property, the specified scale is Invalid or none of the defined scale modes in ScaleMode

SdrWhitePoint

Gets the defining value for 100% white

public float SdrWhitePoint { get; }

Property Value

float

The defining value for 100% white

Remarks

This property is used for HDR10 and floating point textures.

The value of this property defines the value of 100% diffuse white, with higher values being displayed in the High Dynamic Range headroom.

The value defaults to 100 for HDR textures and 1.0 for other textures.

Size

Gets the size of the texture as floating point values

public (float Width, float Height) Size { get; }

Property Value

(float Integer, float Fractional)

The size (width, height) of the texture as floating point values, in pixels

Remarks

This property should only be accessed from the main thread.

Width

Gets the width of the texture

public int Width { get; }

Property Value

int

The width of the texture, in pixels

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

~Texture() 

protected ~Texture()

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

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? pixelManager)

Parameters

rect Rect<int>

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

pixelManager TexturePixelMemoryManager

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?)

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

public bool TryLock(out TexturePixelMemoryManager? pixelManager)

Parameters

pixelManager TexturePixelMemoryManager

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?)

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? surfaceManager)

Parameters

rect Rect<int>

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

surfaceManager TextureSurfaceManager

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?)

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

public bool TryLockToSurface(out TextureSurfaceManager? surfaceManager)

Parameters

surfaceManager TextureSurfaceManager

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.

TryUnsafeLock(out NativeMemory, out int)

Tries to lock the entire texture for write-only pixel access

public bool TryUnsafeLock(out NativeMemory pixels, out int pitch)

Parameters

pixels NativeMemory

The pixel memory of the texture, if this method returns true

pitch int

The pitch of the texture, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the width of the texture, expressed in bytes)

Returns

bool

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

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLock(out NativeMemory pixels, out var pitch))
{
	// Write-only access to the pixel memory using 'pitch'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLock(out TexturePixelMemoryManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUnsafeLock(in Rect<int>, out NativeMemory, out int)

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

public bool TryUnsafeLock(in Rect<int> rect, out NativeMemory pixels, out int pitch)

Parameters

rect Rect<int>

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

pixels NativeMemory

The pixel memory of the locked area, if this method returns true

pitch int

The pitch of the locked area, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the width of the locked area, expressed in bytes)

Returns

bool

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

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLock(in rect, out NativeMemory pixels, out var pitch))
{
	// Write-only access to the pixel memory using 'pitch'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLock(in Rect<int>, out TexturePixelMemoryManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUnsafeLock(in Rect<int>, out Span<byte>, out int)

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

public bool TryUnsafeLock(in Rect<int> rect, out Span<byte> pixels, out int pitch)

Parameters

rect Rect<int>

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

pixels Span<byte>

The pixel memory of the locked area, if this method returns true

pitch int

The pitch of the locked area, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the width of the locked area, expressed in bytes)

Returns

bool

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

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLock(in rect, out Span<byte> pixels, out var pitch))
{
	// Write-only access to the pixel memory using 'pitch'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLock(in Rect<int>, out TexturePixelMemoryManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUnsafeLock(in Rect<int>, out void*, out int)

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

public bool TryUnsafeLock(in Rect<int> rect, out void* pixels, out int pitch)

Parameters

rect Rect<int>

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

pixels void*

The pixel memory of the locked area, if this method returns true

pitch int

The pitch of the locked area, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the width of the locked area, expressed in bytes)

Returns

bool

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

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLock(in rect, out void* pixels, out var pitch))
{
	// Write-only access to the pixel memory using 'pitch'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLock(in Rect<int>, out TexturePixelMemoryManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUnsafeLock(out Span<byte>, out int)

Tries to lock the entire texture for write-only pixel access

public bool TryUnsafeLock(out Span<byte> pixels, out int pitch)

Parameters

pixels Span<byte>

The pixel memory of the texture, if this method returns true

pitch int

The pitch of the texture, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the width of the texture, expressed in bytes)

Returns

bool

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

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLock(out Span<byte> pixels, out var pitch))
{
	// Write-only access to the pixel memory using 'pitch'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLock(out TexturePixelMemoryManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUnsafeLock(out void*, out int)

Tries to lock the entire texture for write-only pixel access

public bool TryUnsafeLock(out void* pixels, out int pitch)

Parameters

pixels void*

The pixel memory of the texture, if this method returns true

pitch int

The pitch of the texture, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the width of the texture, expressed in bytes)

Returns

bool

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

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLock(out void* pixels, out var pitch))
{
	// Write-only access to the pixel memory using 'pitch'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLock(out TexturePixelMemoryManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUnsafeLockToSurface(in Rect<int>, out Surface?)

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

public bool TryUnsafeLockToSurface(in Rect<int> rect, out Surface? surface)

Parameters

rect Rect<int>

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

surface Surface

The surface 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 and the Surface was created; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLockToSurface(in rect, out var surface))
{
	// Write-only access to the pixel memory using 'surface'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLockToSurface(in Rect<int>, out TextureSurfaceManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUnsafeLockToSurface(out Surface?)

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

public bool TryUnsafeLockToSurface(out Surface? surface)

Parameters

surface Surface

The surface 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 and the Surface was created; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLockToSurface(out var surface))
{
	// Write-only access to the pixel memory using 'surface'
	// Make sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with UnsafeUnlock(), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using TryLockToSurface(out TextureSurfaceManager?) instead.

Once you're done accessing the pixel memory, you should call UnsafeUnlock() to unlock the texture and apply the changes.

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

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, 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.

TryUpdate(ReadOnlyNativeMemory, int)

Tries to update the entire texture with new pixel data

public bool TryUpdate(ReadOnlyNativeMemory pixels, int pitch)

Parameters

pixels ReadOnlyNativeMemory

The new pixel data to be copied into the entirety of the texture, in the pixel format of the texture

pitch int

The pitch used in the given pixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given pixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

The given pixels data must be in the pixel format of the texture.

This is a fairly slow operation, intended for use with static textures that do not change often.

If the texture is intended to be updated often, you should prefer to create the texture as streaming and use one of the locking mechanisms to manipulate the texture's pixels (e.g. TryLock(out TexturePixelMemoryManager?)) instead. While this method still works with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

Using this method for NV12, NV21, YV12 or IYUV textures is perfectly fine as long as the given pixels data is a contiguous block of NV12/N21 planes or Y and UV planes, respectively, in the proper order. If not, you should use TryUpdateNv(ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int) or TryUpdateYuv(ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int), respectively, instead.

This method should only be called from the main thread.

TryUpdate(in Rect<int>, ReadOnlyNativeMemory, int)

Tries to update an area of the texture with new pixel data

public bool TryUpdate(in Rect<int> rect, ReadOnlyNativeMemory pixels, int pitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

pixels ReadOnlyNativeMemory

The new pixel data to be copied into the specified area of the texture, in the pixel format of the texture

pitch int

The pitch used in the given pixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given pixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

The given pixels data must be in the pixel format of the texture.

This is a fairly slow operation, intended for use with static textures that do not change often.

If the texture is intended to be updated often, you should prefer to create the texture as streaming and use one of the locking mechanisms to manipulate the texture's pixels (e.g. TryLock(in Rect<int>, out TexturePixelMemoryManager?)) instead. While this method still works with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

Using this method for NV12, NV21, YV12 or IYUV textures is perfectly fine as long as the given pixels data is a contiguous block of NV12/N21 planes or Y and UV planes, respectively, in the proper order. If not, you should use TryUpdateNv(in Rect<int>, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int) or TryUpdateYuv(in Rect<int>, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int), respectively, instead.

This method should only be called from the main thread.

TryUpdate(in Rect<int>, ReadOnlySpan<byte>, int)

Tries to update an area of the texture with new pixel data

public bool TryUpdate(in Rect<int> rect, ReadOnlySpan<byte> pixels, int pitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

pixels ReadOnlySpan<byte>

The new pixel data to be copied into the specified area of the texture, in the pixel format of the texture

pitch int

The pitch used in the given pixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given pixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

The given pixels data must be in the pixel format of the texture.

This is a fairly slow operation, intended for use with static textures that do not change often.

If the texture is intended to be updated often, you should prefer to create the texture as streaming and use one of the locking mechanisms to manipulate the texture's pixels (e.g. TryLock(in Rect<int>, out TexturePixelMemoryManager?)) instead. While this method still works with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

Using this method for NV12, NV21, YV12 or IYUV textures is perfectly fine as long as the given pixels data is a contiguous block of NV12/N21 planes or Y and UV planes, respectively, in the proper order. If not, you should use TryUpdateNv(in Rect<int>, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int) or TryUpdateYuv(in Rect<int>, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int), respectively, instead.

This method should only be called from the main thread.

TryUpdate(in Rect<int>, void*, int)

Tries to update an area of the texture with new pixel data

public bool TryUpdate(in Rect<int> rect, void* pixels, int pitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

pixels void*

The new pixel data to be copied into the specified area of the texture, in the pixel format of the texture

pitch int

The pitch used in the given pixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given pixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

The given pixels data must be in the pixel format of the texture.

This is a fairly slow operation, intended for use with static textures that do not change often.

If the texture is intended to be updated often, you should prefer to create the texture as streaming and use one of the locking mechanisms to manipulate the texture's pixels (e.g. TryLock(in Rect<int>, out TexturePixelMemoryManager?)) instead. While this method still works with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

Using this method for NV12, NV21, YV12 or IYUV textures is perfectly fine as long as the given pixels data is a contiguous block of NV12/N21 planes or Y and UV planes, respectively, in the proper order. If not, you should use TryUpdateYuv(in Rect<int>, byte*, int, byte*, int, byte*, int) or TryUpdateYuv(in Rect<int>, byte*, int, byte*, int, byte*, int), respectively, instead.

This method should only be called from the main thread.

TryUpdate(ReadOnlySpan<byte>, int)

Tries to update the entire texture with new pixel data

public bool TryUpdate(ReadOnlySpan<byte> pixels, int pitch)

Parameters

pixels ReadOnlySpan<byte>

The new pixel data to be copied into the entirety of the texture, in the pixel format of the texture

pitch int

The pitch used in the given pixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given pixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

The given pixels data must be in the pixel format of the texture.

This is a fairly slow operation, intended for use with static textures that do not change often.

If the texture is intended to be updated often, you should prefer to create the texture as streaming and use one of the locking mechanisms to manipulate the texture's pixels (e.g. TryLock(out TexturePixelMemoryManager?)) instead. While this method still works with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

Using this method for NV12, NV21, YV12 or IYUV textures is perfectly fine as long as the given pixels data is a contiguous block of NV12/N21 planes or Y and UV planes, respectively, in the proper order. If not, you should use TryUpdateNv(ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int) or TryUpdateYuv(ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int), respectively, instead.

This method should only be called from the main thread.

TryUpdate(void*, int)

Tries to update the entire texture with new pixel data

public bool TryUpdate(void* pixels, int pitch)

Parameters

pixels void*

The new pixel data to be copied into the entirety of the texture, in the pixel format of the texture

pitch int

The pitch used in the given pixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given pixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

The given pixels data must be in the pixel format of the texture.

This is a fairly slow operation, intended for use with static textures that do not change often.

If the texture is intended to be updated often, you should prefer to create the texture as streaming and use one of the locking mechanisms to manipulate the texture's pixels (e.g. TryLock(out TexturePixelMemoryManager?)) instead. While this method still works with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

Using this method for NV12, NV21, YV12 or IYUV textures is perfectly fine as long as the given pixels data is a contiguous block of NV12/N21 planes or Y and UV planes, respectively, in the proper order. If not, you should use TryUpdateNv(byte*, int, byte*, int) or TryUpdateYuv(byte*, int, byte*, int, byte*, int), respectively, instead.

This method should only be called from the main thread.

TryUpdateNv(ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int)

Tries to update an entire planar NV12 or NV21 texture with new pixel data

public bool TryUpdateNv(ReadOnlyNativeMemory<byte> yPixels, int yPitch, ReadOnlyNativeMemory<byte> uvPixels, int uvPitch)

Parameters

yPixels ReadOnlyNativeMemory<byte>

The new pixel data for the Y plane of the texture, to be copied into the entirety of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uvPixels ReadOnlyNativeMemory<byte>

The new pixel data for the UV plane of the texture, to be copied into the entirety of the texture

uvPitch int

The pitch used in the given uvPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uvPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(ReadOnlyNativeMemory, int) for planar NV12 or NV21 textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(ReadOnlyNativeMemory, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateNv(in Rect<int>, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int)

Tries to update an area of a planar NV12 or NV21 texture with new pixel data

public bool TryUpdateNv(in Rect<int> rect, ReadOnlyNativeMemory<byte> yPixels, int yPitch, ReadOnlyNativeMemory<byte> uvPixels, int uvPitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

yPixels ReadOnlyNativeMemory<byte>

The new pixel data for the Y plane of the texture, to be copied into the specified area of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uvPixels ReadOnlyNativeMemory<byte>

The new pixel data for the UV plane of the texture, to be copied into the specified area of the texture

uvPitch int

The pitch used in the given uvPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uvPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(in Rect<int>, ReadOnlyNativeMemory, int) for planar NV12 or NV21 textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(in Rect<int>, ReadOnlyNativeMemory, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateNv(in Rect<int>, byte*, int, byte*, int)

Tries to update an area of a planar NV12 or NV21 texture with new pixel data

public bool TryUpdateNv(in Rect<int> rect, byte* yPixels, int yPitch, byte* uvPixels, int uvPitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

yPixels byte*

The new pixel data for the Y plane of the texture, to be copied into the specified area of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uvPixels byte*

The new pixel data for the UV plane of the texture, to be copied into the specified area of the texture

uvPitch int

The pitch used in the given uvPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uvPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(in Rect<int>, void*, int) for planar NV12 or NV21 textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(in Rect<int>, void*, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateNv(in Rect<int>, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int)

Tries to update an area of a planar NV12 or NV21 texture with new pixel data

public bool TryUpdateNv(in Rect<int> rect, ReadOnlySpan<byte> yPixels, int yPitch, ReadOnlySpan<byte> uvPixels, int uvPitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

yPixels ReadOnlySpan<byte>

The new pixel data for the Y plane of the texture, to be copied into the specified area of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uvPixels ReadOnlySpan<byte>

The new pixel data for the UV plane of the texture, to be copied into the specified area of the texture

uvPitch int

The pitch used in the given uvPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uvPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(in Rect<int>, ReadOnlySpan<byte>, int) for planar NV12 or NV21 textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(in Rect<int>, ReadOnlySpan<byte>, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateNv(byte*, int, byte*, int)

Tries to update an entire planar NV12 or NV21 texture with new pixel data

public bool TryUpdateNv(byte* yPixels, int yPitch, byte* uvPixels, int uvPitch)

Parameters

yPixels byte*

The new pixel data for the Y plane of the texture, to be copied into the entirety of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uvPixels byte*

The new pixel data for the UV plane of the texture, to be copied into the entirety of the texture

uvPitch int

The pitch used in the given uvPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uvPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(void*, int) for planar NV12 or NV21 textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(void*, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateNv(ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int)

Tries to update an entire planar NV12 or NV21 texture with new pixel data

public bool TryUpdateNv(ReadOnlySpan<byte> yPixels, int yPitch, ReadOnlySpan<byte> uvPixels, int uvPitch)

Parameters

yPixels ReadOnlySpan<byte>

The new pixel data for the Y plane of the texture, to be copied into the entirety of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uvPixels ReadOnlySpan<byte>

The new pixel data for the UV plane of the texture, to be copied into the entirety of the texture

uvPitch int

The pitch used in the given uvPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uvPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(ReadOnlySpan<byte>, int) for planar NV12 or NV21 textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(ReadOnlySpan<byte>, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateYuv(ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int)

Tries to update an entire planar YV12 or IYUV texture with new pixel data

public bool TryUpdateYuv(ReadOnlyNativeMemory<byte> yPixels, int yPitch, ReadOnlyNativeMemory<byte> uPixels, int uPitch, ReadOnlyNativeMemory<byte> vPixels, int vPitch)

Parameters

yPixels ReadOnlyNativeMemory<byte>

The new pixel data for the Y plane of the texture, to be copied into the entirety of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uPixels ReadOnlyNativeMemory<byte>

The new pixel data for the U plane of the texture, to be copied into the entirety of the texture

uPitch int

The pitch used in the given uPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uPixels data, expressed in bytes)

vPixels ReadOnlyNativeMemory<byte>

The new pixel data for the V plane of the texture, to be copied into the entirety of the texture

vPitch int

The pitch used in the given vPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given vPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(ReadOnlyNativeMemory, int) for planar YV12 or IYUV textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(ReadOnlyNativeMemory, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateYuv(in Rect<int>, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int, ReadOnlyNativeMemory<byte>, int)

Tries to update an area of a planar YV12 or IYUV texture with new pixel data

public bool TryUpdateYuv(in Rect<int> rect, ReadOnlyNativeMemory<byte> yPixels, int yPitch, ReadOnlyNativeMemory<byte> uPixels, int uPitch, ReadOnlyNativeMemory<byte> vPixels, int vPitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

yPixels ReadOnlyNativeMemory<byte>

The new pixel data for the Y plane of the texture, to be copied into the specified area of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uPixels ReadOnlyNativeMemory<byte>

The new pixel data for the U plane of the texture, to be copied into the specified area of the texture

uPitch int

The pitch used in the given uPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uPixels data, expressed in bytes)

vPixels ReadOnlyNativeMemory<byte>

The new pixel data for the V plane of the texture, to be copied into the specified area of the texture

vPitch int

The pitch used in the given vPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given vPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(in Rect<int>, ReadOnlyNativeMemory, int) for planar YV12 or IYUV textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(in Rect<int>, ReadOnlyNativeMemory, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateYuv(in Rect<int>, byte*, int, byte*, int, byte*, int)

Tries to update an area of a planar YV12 or IYUV texture with new pixel data

public bool TryUpdateYuv(in Rect<int> rect, byte* yPixels, int yPitch, byte* uPixels, int uPitch, byte* vPixels, int vPitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

yPixels byte*

The new pixel data for the Y plane of the texture, to be copied into the specified area of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uPixels byte*

The new pixel data for the U plane of the texture, to be copied into the specified area of the texture

uPitch int

The pitch used in the given uPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uPixels data, expressed in bytes)

vPixels byte*

The new pixel data for the V plane of the texture, to be copied into the specified area of the texture

vPitch int

The pitch used in the given vPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given vPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(in Rect<int>, void*, int) for planar YV12 or IYUV textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(in Rect<int>, void*, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateYuv(in Rect<int>, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int)

Tries to update an area of a planar YV12 or IYUV texture with new pixel data

public bool TryUpdateYuv(in Rect<int> rect, ReadOnlySpan<byte> yPixels, int yPitch, ReadOnlySpan<byte> uPixels, int uPitch, ReadOnlySpan<byte> vPixels, int vPitch)

Parameters

rect Rect<int>

The area of the texture to update with the new pixel data

yPixels ReadOnlySpan<byte>

The new pixel data for the Y plane of the texture, to be copied into the specified area of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uPixels ReadOnlySpan<byte>

The new pixel data for the U plane of the texture, to be copied into the specified area of the texture

uPitch int

The pitch used in the given uPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uPixels data, expressed in bytes)

vPixels ReadOnlySpan<byte>

The new pixel data for the V plane of the texture, to be copied into the specified area of the texture

vPitch int

The pitch used in the given vPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given vPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(in Rect<int>, ReadOnlySpan<byte>, int) for planar YV12 or IYUV textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(in Rect<int>, ReadOnlySpan<byte>, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateYuv(byte*, int, byte*, int, byte*, int)

Tries to update an entire planar YV12 or IYUV texture with new pixel data

public bool TryUpdateYuv(byte* yPixels, int yPitch, byte* uPixels, int uPitch, byte* vPixels, int vPitch)

Parameters

yPixels byte*

The new pixel data for the Y plane of the texture, to be copied into the entirety of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uPixels byte*

The new pixel data for the U plane of the texture, to be copied into the entirety of the texture

uPitch int

The pitch used in the given uPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uPixels data, expressed in bytes)

vPixels byte*

The new pixel data for the V plane of the texture, to be copied into the entirety of the texture

vPitch int

The pitch used in the given vPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given vPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(void*, int) for planar YV12 or IYUV textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(void*, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

TryUpdateYuv(ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int, ReadOnlySpan<byte>, int)

Tries to update an entire planar YV12 or IYUV texture with new pixel data

public bool TryUpdateYuv(ReadOnlySpan<byte> yPixels, int yPitch, ReadOnlySpan<byte> uPixels, int uPitch, ReadOnlySpan<byte> vPixels, int vPitch)

Parameters

yPixels ReadOnlySpan<byte>

The new pixel data for the Y plane of the texture, to be copied into the entirety of the texture

yPitch int

The pitch used in the given yPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given yPixels data, expressed in bytes)

uPixels ReadOnlySpan<byte>

The new pixel data for the U plane of the texture, to be copied into the entirety of the texture

uPitch int

The pitch used in the given uPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given uPixels data, expressed in bytes)

vPixels ReadOnlySpan<byte>

The new pixel data for the V plane of the texture, to be copied into the entirety of the texture

vPitch int

The pitch used in the given vPixels data, in bytes; that is the length between the start of a row of pixels and the start of the next row of pixels (which may be greater than the pixel width of the given vPixels data, expressed in bytes)

Returns

bool

true, if the texture was successfully updated with the new pixel data; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is meant as an alternative to TryUpdate(ReadOnlySpan<byte>, int) for planar YV12 or IYUV textures when your pixel data for the individual planes is not stored as a contiguous block or you need to specify different pitch values for the individual planes. Please see the documentation of TryUpdate(ReadOnlySpan<byte>, int) for more general information about update operations, as the details mentioned there also apply to this method.

This method should only be called from the main thread.

UnsafeUnlock()

Unlocks the texture after write-only pixel access

public void UnsafeUnlock()

Examples

Example usage:

Texture texture;

...

if (texture.TryUnsafeLock(out NativeMemory pixels, out var pitch))
{
	// Write-only access to the pixel memory using 'pitch'
	// Be sure to fully initialize ALL the pixels locked

	...

	texture.UnsafeUnlock();
}

Remarks

This method is meant to be used in conjuction with any of the "TryUnsafeLock" or "TryUnsafeLockToSurface" methods (e.g. TryUnsafeLock(in Rect<int>, out NativeMemory, out int)), if you want to access the texture's pixels directly in a faster and more efficient way. If you're locking for a simpler and safer way to access the texture's pixels, consider using any of the "TryLock" or "TryLockToSurface" methods (e.g. TryLock(in Rect<int>, out TexturePixelMemoryManager?)) instead.

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, 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.