TSdlTexture

An efficient driver-specific representation of pixel data. To create a texture, use TSdlRenderer.CreateTexture.

Definition

Unit: Neslib.Sdl3.Video

type TSdlTexture = record ... end;

Properties

Name	Description
AlphaMod	An additional alpha value multiplied into render copy operations.
AlphaModFloat	An additional alpha value multiplied into render copy operations.
BlendMode	The blend mode for a texture, used by TSdlRenderer.DrawTexture.
ColorMod	An additional color value multiplied into render copy operations.
ColorModFloat	An additional color value multiplied into render copy operations.
Format	The format of the texture, read-only
H	The height of the texture, read-only.
Properties	The properties associated with a texture.
Renderer	The renderer that created the texture.
ScaleMode	The scale mode used for texture scale operations.
Size	The size of a texture, as floating point values.
W	The width of the texture, read-only.

Operators

Name	Description
Equal(TSdlTexture, TSdlTexture)	Used to compare against another TSdlTexture.
Equal(TSdlTexture, Pointer)	Used to compare against nil.
Implicit	Used to set the value to nil.
NotEqual(TSdlTexture, TSdlTexture)	Used to compare against another TSdlTexture.
NotEqual(TSdlTexture, Pointer)	Used to compare against nil.

Methods

Name	Description
Free	Destroy the texture.
Lock(TSdlRect, Pointer, Integer)	Lock a portion of the texture for write-only pixel access.
Lock(Pointer, Integer)	Lock the entire texture for write-only pixel access.
LockToSurface(TSdlRect)	Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface.
LockToSurface	Lock a the entire texture for write-only pixel access, and expose it as a SDL surface.
Unlock	Unlock the texture, uploading the changes to video memory, if needed.
Update(TSdlRect, Pointer, Integer)	Update the given texture rectangle with new pixel data.
Update(Pointer, Integer)	Update the entire texture with new pixel data.
UpdateNV(TSdlRect, Pointer, Integer, Pointer, Integer)	Update a rectangle within a planar NV12 or NV21 texture with new pixels.
UpdateNV(Pointer, Integer, Pointer, Integer)	Update the entire planar NV12 or NV21 texture with new pixels.
UpdateYuv(TSdlRect, Pointer, Integer, Pointer, Integer, Pointer, Integer)	Update a rectangle within a planar YV12 or IYUV texture with new pixel data.
UpdateYuv(Pointer, Integer, Pointer, Integer, Pointer, Integer)	Update the entire planar YV12 or IYUV texture with new pixel data.

Property Descriptions

AlphaMod

An additional alpha value multiplied into render copy operations.

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 div 255)

Alpha modulation is not always supported by the renderer; it will raise an error if color modulation is not supported.

property AlphaMod: Byte read GetAlphaMod write SetAlphaMod

Type: Byte

Exceptions

ESdlError: Raised on failure.

See Also

• AlphaModFloat
• ColorMod

Remarks

This property should only be used on the main thread.

---

AlphaModFloat

An additional alpha value multiplied into render copy operations.

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; it will raise an error if color modulation is not supported.

property AlphaModFloat: Single read GetAlphaModFloat write SetAlphaModFloat

Type: Single

Exceptions

ESdlError: Raised on failure.

See Also

• AlphaMod
• ColorModFloat

Remarks

This property should only be used on the main thread.

---

BlendMode

The blend mode for a texture, used by TSdlRenderer.DrawTexture.

If the blend mode is not supported, the closest supported mode is chosen.

property BlendMode: TSdlBlendMode read GetBlendMode write SetBlendMode

Type: TSdlBlendMode

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

ColorMod

An additional color value multiplied into render copy operations.

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 div 255)

Color modulation is not always supported by the renderer; it will raise an error if color modulation is not supported.

property ColorMod: TSdlColor read GetColorMod write SetColorMod

Type: TSdlColor

Exceptions

ESdlError: Raised on failure.

See Also

• AlphaMod
• ColorModFloat

Remarks

The Alpha value of the color is ignored (or set to 255).

This property should only be used on the main thread.

---

ColorModFloat

An additional color value multiplied into render copy operations.

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; it will raise an error if color modulation is not supported.

property ColorModFloat: TSdlColorF read GetColorModFloat write SetColorModFloat

Type: TSdlColorF

Exceptions

ESdlError: Raised on failure.

See Also

• AlphaModFloat
• ColorMod

Remarks

The Alpha value of the color is ignored (or set to 1.0).

This property should only be used on the main thread.

---

Format

The format of the texture, read-only

property Format: TSdlPixelFormat read GetFormat

Type: TSdlPixelFormat

---

H

The height of the texture, read-only.

property H: Integer read GetH

Type: Integer

---

Properties

The properties associated with a texture.

The following read-only properties are provided by SDL:

• TSdlProperty.TextureColorspace: a TSdlColorspace value describing the texture colorspace.
• TSdlProperty.TextureFormat: one of the enumerated values in TSdlPixelFormat.
• TSdlProperty.TextureAccess: one of the enumerated values in TSdlTextureAccess.
• TSdlProperty.TextureWidth: the width of the texture in pixels.
• TSdlProperty.TextureHeight: the height of the texture in pixels.
• TSdlProperty.TextureSdrWhitePoint: for HDR10 and floating point textures, this defines the value of 100% diffuse white, with higher values being displayed in the High Dynamic Range headroom. This defaults to 100 for HDR10 textures and 1.0 for other textures.
• TSdlProperty.TextureHdrHeadroom: for HDR10 and floating point textures, this defines the maximum dynamic range used by the content, in terms of the SDR white point. If this is defined, any values outside the range supported by the display will be scaled into the available HDR headroom, otherwise they are clipped. This defaults to 1.0 for SDR textures, 4.0 for HDR10 textures, and no default for floating point textures.

With the Direct3D11 renderer:

• TSdlProperty.TextureD3D11Texture: the ID3D11Texture2D associated with the texture
• TSdlProperty.TextureD3D11TextureU: the ID3D11Texture2D associated with the U plane of a YUV texture
• TSdlProperty.TextureD3D11TextureV: the ID3D11Texture2D associated with the V plane of a YUV texture

With the Direct3D12 renderer:

• TSdlProperty.TextureD3D12Texture: the ID3D12Resource associated with the texture
• TSdlProperty.TextureD3D12TextureU: the ID3D12Resource associated with the U plane of a YUV texture
• TSdlProperty.TextureD3D12TextureV: the ID3D12Resource associated with the V plane of a YUV texture

With the Vulkan renderer:

• TSdlProperty.TextureVulkanTexture: the VkImage associated with the texture

With the OpenGL renderer:

• TSdlProperty.TextureOpenGLTexture: the GLuint texture associated with the texture
• TSdlProperty.TextureOpenGLTextureUV: the GLuint texture associated with the UV plane of an NV12 texture
• TSdlProperty.TextureOpenGLTextureU: the GLuint texture associated with the U plane of a YUV texture
• TSdlProperty.TextureOpenGLTextureV: the GLuint texture associated with the V plane of a YUV texture
• TSdlProperty.TextureOpenGLTextureTarget: the GLenum for the texture target (GL_TEXTURE_2D, GL_TEXTURE_RECTANGLE_ARB, etc)
• TSdlProperty.TextureOpenGLTexW: the texture coordinate width of the texture (0.0 - 1.0)
• TSdlProperty.TextureOpenGLTexH: the texture coordinate height of the texture (0.0 - 1.0)

With the OpenGL-ES2 renderer:

• TSdlProperty.TextureOpenGles2Texture: the GLuint texture associated with the texture
• TSdlProperty.TextureOpenGles2TextureUV: the GLuint texture associated with the UV plane of an NV12 texture
• TSdlProperty.TextureOpenGles2TextureU: the GLuint texture associated with the U plane of a YUV texture
• TSdlProperty.TextureOpenGles2TextureV: the GLuint texture associated with the V plane of a YUV texture
• TSdlProperty.TextureOpenGles2TextureTarget: the GLenum for the texture target (GL_TEXTURE_2D, GL_TEXTURE_EXTERNAL_OES, etc)

property Properties: TSdlProperties read GetProperties

Type: TSdlProperties

Exceptions

ESdlError: Raised on failure.

Remarks

It is safe to use this property from any thread.

---

Renderer

The renderer that created the texture.

property Renderer: TSdlRenderer read GetRenderer

Type: TSdlRenderer

Remarks

Raised on failure.It is safe to use this property from any thread.

---

ScaleMode

The scale mode used for texture scale operations.

The default texture scale mode is TSdlScaleMode.Linear.

If the scale mode is not supported, the closest supported mode is chosen.

property ScaleMode: TSdlScaleMode read GetScaleMode write SetScaleMode

Type: TSdlScaleMode

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

Size

The size of a texture, as floating point values.

property Size: TSdlSizeF read GetSize

Type: TSdlSizeF

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

W

The width of the texture, read-only.

property W: Integer read GetW

Type: Integer

---

Operator Descriptions

Equal(TSdlTexture, TSdlTexture)

Used to compare against another TSdlTexture.

class operator Equal(const ALeft, ARight: TSdlTexture): Boolean; inline; static

Parameters

ALeft: TSdlTexture

ARight: TSdlTexture

Returns

Boolean

---

Equal(TSdlTexture, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlTexture; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlTexture

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlTexture; inline; static

Parameters

AValue: Pointer

Returns

TSdlTexture

---

NotEqual(TSdlTexture, TSdlTexture)

Used to compare against another TSdlTexture.

class operator NotEqual(const ALeft, ARight: TSdlTexture): Boolean; inline; static

Parameters

ALeft: TSdlTexture

ARight: TSdlTexture

Returns

Boolean

---

NotEqual(TSdlTexture, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlTexture; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlTexture

ARight: Pointer

Returns

Boolean

---

Method Descriptions

Free

Destroy the texture.

procedure Free; inline

See Also

• TSdlRenderer.CreateTexture

Remarks

This method should only be called on the main thread.

---

Lock(TSdlRect, Pointer, Integer)

Lock a portion of the texture for write-only pixel access.

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.

You must use Unlock to unlock the pixels and apply any changes.

procedure Lock(const ARect: TSdlRect; out APixels: Pointer; out APitch: Integer); overload

Exceptions

ESdlError: Raised on failure (eg. if the texture is not valid or was not created with TSdlTextureAccess.Streaming.

Parameters

ARect: TSdlRect : The area to lock for access.

APixels: Pointer : This is set to a pointer to the locked pixels, appropriately offset by the locked area.

APitch: Integer : This is set to the pitch of the locked pixels; the pitch is the length of one row in bytes.

See Also

• LockToSurface
• Unlock

Remarks

This method should only be called on the main thread.

---

Lock(Pointer, Integer)

Lock the entire texture for write-only pixel access.

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.

You must use Unlock to unlock the pixels and apply any changes.

procedure Lock(out APixels: Pointer; out APitch: Integer); overload

Exceptions

ESdlError: Raised on failure (eg. if the texture is not valid or was not created with TSdlTextureAccess.Streaming.

Parameters

APixels: Pointer : This is set to a pointer to the locked pixels, appropriately offset by the locked area.

APitch: Integer : This is set to the pitch of the locked pixels; the pitch is the length of one row in bytes.

See Also

• LockToSurface
• Unlock

Remarks

This method should only be called on the main thread.

---

LockToSurface(TSdlRect)

Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface.

Besides providing an TSdlSurface instead of raw pixel data, this function operates like Lock.

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.

You must use Unlock to unlock the pixels and apply any changes.

The returned surface is freed internally after calling Unlock or when freeing the texture. The caller should not free it.

function LockToSurface(const ARect: TSdlRect): TSdlSurface; overload

Exceptions

ESdlError: Raised on failure.

Parameters

ARect: TSdlRect : The rectangle to lock for access.

Returns

TSdlSurface: A SDL surface of size ARect. Don't assume any specific pixel content.

See Also

• Lock
• Unlock

Remarks

This method should only be called on the main thread.

---

LockToSurface

Lock a the entire texture for write-only pixel access, and expose it as a SDL surface.

Besides providing an TSdlSurface instead of raw pixel data, this function operates like Lock.

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.

You must use Unlock to unlock the pixels and apply any changes.

The returned surface is freed internally after calling Unlock or when freeing the texture. The caller should not free it.

function LockToSurface: TSdlSurface; overload

Exceptions

ESdlError: Raised on failure.

Returns

TSdlSurface: A SDL surface of the same size as this texture. Don't assume any specific pixel content.

See Also

• Lock
• Unlock

Remarks

This method should only be called on the main thread.

---

Unlock

Unlock the texture, uploading the changes to video memory, if needed.

Warning: Please note that Lock 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 lock before unlocking it, as the pixels might otherwise be uninitialized memory.

Which is to say: locking and immediately unlocking a texture can result in corrupted textures, depending on the renderer in use.

procedure Unlock; inline

See Also

• Lock

Remarks

This method should only be called on the main thread.

---

Update(TSdlRect, Pointer, Integer)

Update the given texture rectangle with new pixel data.

The pixel data must be in the pixel format of the texture, which can be queried using the TSdlProperty.TextureFormat property.

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

If the texture is intended to be updated often, it is preferred to create the texture as streaming and use the locking functions referenced below. While this function will work with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

procedure Update(const ARect: TSdlRect; const APixels: Pointer; const APitch: Integer); overload

Exceptions

ESdlError: Raised on failure.

Parameters

ARect: TSdlRect : The area to update.

APixels: Pointer : The raw pixel data in the format of the texture.

APitch: Integer : The number of bytes in a row of pixel data, including padding between lines.

See Also

• Lock
• Unlock
• UpdateNV
• UpdateYuv

Remarks

This method should only be called on the main thread.

---

Update(Pointer, Integer)

Update the entire texture with new pixel data.

The pixel data must be in the pixel format of the texture, which can be queried using the TSdlProperty.TextureFormat property.

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

If the texture is intended to be updated often, it is preferred to create the texture as streaming and use the locking functions referenced below. While this function will work with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

procedure Update(const APixels: Pointer; const APitch: Integer); overload

Exceptions

ESdlError: Raised on failure.

Parameters

APixels: Pointer : The raw pixel data in the format of the texture.

APitch: Integer : The number of bytes in a row of pixel data, including padding between lines.

See Also

• Lock
• Unlock
• UpdateNV
• UpdateYuv

Remarks

This method should only be called on the main thread.

---

UpdateNV(TSdlRect, Pointer, Integer, Pointer, Integer)

Update a rectangle within a planar NV12 or NV21 texture with new pixels.

You can use Update as long as your pixel data is a contiguous block of NV12/21 planes in the proper order, but this function is available if your pixel data is not contiguous.

procedure UpdateNV(const ARect: TSdlRect; const AYPlane: Pointer; const AYPitch: Integer; const AUVPlane: Pointer; const AUVPitch: Integer); overload

Exceptions

ESdlError: Raised on failure.

Parameters

ARect: TSdlRect : The rectangle of pixels to update.

AYPlane: Pointer : The raw pixel data for the Y plane.

AYPitch: Integer : The number of bytes between rows of pixel data for the Y plane.

AUVPlane: Pointer : The raw pixel data for the UV plane.

AUVPitch: Integer : The number of bytes between rows of pixel data for the UV plane.

See Also

• Update
• UpdateYuv

Remarks

This method should only be called on the main thread.

---

UpdateNV(Pointer, Integer, Pointer, Integer)

Update the entire planar NV12 or NV21 texture with new pixels.

You can use Update as long as your pixel data is a contiguous block of NV12/21 planes in the proper order, but this function is available if your pixel data is not contiguous.

procedure UpdateNV(const AYPlane: Pointer; const AYPitch: Integer; const AUVPlane: Pointer; const AUVPitch: Integer); overload

Exceptions

ESdlError: Raised on failure.

Parameters

AYPlane: Pointer : The raw pixel data for the Y plane.

AYPitch: Integer : The number of bytes between rows of pixel data for the Y plane.

AUVPlane: Pointer : The raw pixel data for the UV plane.

AUVPitch: Integer : The number of bytes between rows of pixel data for the UV plane.

See Also

• Update
• UpdateYuv

Remarks

This method should only be called on the main thread.

---

UpdateYuv(TSdlRect, Pointer, Integer, Pointer, Integer, Pointer, Integer)

Update a rectangle within a planar YV12 or IYUV texture with new pixel data.

You can use Update as long as your pixel data is a contiguous block of Y and U/V planes in the proper order, but this function is available if your pixel data is not contiguous.

procedure UpdateYuv(const ARect: TSdlRect; const AYPlane: Pointer; const AYPitch: Integer; const AUPlane: Pointer; const AUPitch: Integer; const AVPlane: Pointer; const AVPitch: Integer); overload

Exceptions

ESdlError: Raised on failure.

Parameters

ARect: TSdlRect : The rectangle of pixels to update.

AYPlane: Pointer : The raw pixel data for the Y plane.

AYPitch: Integer : The number of bytes between rows of pixel data for the Y plane.

AUPlane: Pointer : The raw pixel data for the U plane.

AUPitch: Integer : The number of bytes between rows of pixel data for the U plane.

AVPlane: Pointer : The raw pixel data for the V plane.

AVPitch: Integer : The number of bytes between rows of pixel data for the V plane.

See Also

• UpdateNV
• Update

Remarks

This method should only be called on the main thread.

---

UpdateYuv(Pointer, Integer, Pointer, Integer, Pointer, Integer)

Update the entire planar YV12 or IYUV texture with new pixel data.

You can use Update as long as your pixel data is a contiguous block of Y and U/V planes in the proper order, but this function is available if your pixel data is not contiguous.

procedure UpdateYuv(const AYPlane: Pointer; const AYPitch: Integer; const AUPlane: Pointer; const AUPitch: Integer; const AVPlane: Pointer; const AVPitch: Integer); overload

Exceptions

ESdlError: Raised on failure.

Parameters

AYPlane: Pointer : The raw pixel data for the Y plane.

AYPitch: Integer : The number of bytes between rows of pixel data for the Y plane.

AUPlane: Pointer : The raw pixel data for the U plane.

AUPitch: Integer : The number of bytes between rows of pixel data for the U plane.

AVPlane: Pointer : The raw pixel data for the V plane.

AVPitch: Integer : The number of bytes between rows of pixel data for the V plane.

See Also

• UpdateNV
• Update

Remarks

This method should only be called on the main thread.

---