Skip to content

TSdlSurface

A collection of pixels used in software blitting.

Pixels are arranged in memory in rows, with the top row first. Each row occupies an amount of memory given by the pitch (sometimes known as the row stride in non-SDL APIs).

Within each row, pixels are arranged from left to right until the width is reached. Each pixel occupies a number of bits appropriate for its format, with most formats representing each pixel as one or more whole bytes (in some indexed formats, instead multiple pixels are packed into each byte), and a byte order given by the format. After encoding all pixels, any remaining bytes to reach the pitch are used as padding to reach a desired alignment, and have undefined contents.

When a surface holds YUV format data, the planes are assumed to be contiguous without padding between them, e.g. a 32x32 surface in NV12 format with a pitch of 32 would consist of 32x32 bytes of Y plane followed by 32x16 bytes of UV plane.

When a surface holds MJPG format data, pixels points at the compressed JPEG image and pitch is the length of that data.

Definition

Unit: Neslib.Sdl3.Video

type TSdlSurface = record ... end;

Properties

Name Description
AlphaMod An additional alpha value used in blit operations.
BlendMode The blend mode used for blit operations.
ClipRect The clipping rectangle for a surface.
ColorKey The color key (transparent pixel) in the surface.
ColorMod An additional color value multiplied into blit operations.
Colorspace The colorspace used by the surface.
Flags The flags of the surface, read-only
Format The format of the surface, read-only
H The height of the surface, read-only.
HasAlternateImages Whether the surface has alternate versions available.
HasColorKey Whether the surface has a color key.
Images Get an array including all versions of this surface.
MustLock Whether the surface needs to be locked before access.
Palette The palette used by a surface, or nil if there is no palette used.
Pitch The distance in bytes between rows of pixels, read-only
Pixel The pixels of the surface.
PixelFloat The pixels of the surface, as floating-point colors.
Pixels A pointer to the pixels of the surface, the pixels are writeable if non-nil
Properties The properties associated with a surface.
UseRle Whether to use RLE acceleration for the surface.
W The width of the surface, read-only.

Constructors

Name Description
Create(Integer, Integer, TSdlPixelFormat, Pointer, Integer) Create a new surface with a specific pixel format and existing pixel data.
Create(Integer, Integer, TSdlPixelFormat) Create a new surface with a specific pixel format.
LoadBmp(String) Create a surface from a BMP image from a file.
LoadBmp(TSdlIOStream, Boolean) Create a surface from a BMP image from a seekable SDL data stream.

Operators

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

Methods

Name Description
AddAlternateImage Add an alternate version of a surface.
Blit Performs a fast blit from this surface to a destination surface with clipping.
Blit9Grid Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.
BlitScaled Perform a scaled blit to a destination surface, which may be of a different format.
BlitScaledUnchecked Perform low-level surface scaled blitting only.
BlitTiled(PSdlRect, Single, TSdlScaleMode, TSdlSurface, PSdlRect) Perform a scaled and tiled blit to a destination surface, which may be of a different format.
BlitTiled(PSdlRect, TSdlSurface, PSdlRect) Perform a tiled blit to a destination surface, which may be of a different format.
BlitUnchecked Perform low-level surface blitting only.
Clear(TSdlColorF) Clear the surface with a specific color, with floating point precision.
Clear(Single, Single, Single, Single) Clear the surface with a specific color, with floating point precision.
Convert(TSdlPixelFormat, TSdlPalette, TSdlColorspace, TSdlProperties) Copy the existing surface to a new surface of the specified format and colorspace.
Convert(TSdlPixelFormat, TSdlColorspace) Copy the existing surface to a new surface of the specified format and colorspace.
Convert(TSdlPixelFormat) Copy the surface to a new surface of the specified format.
CreatePalette Create a palette and associate it with this surface.
DisableClipping Disables clipping. Set the ClipRect property to enable clipping again.
Duplicate Creates a new surface identical to the existing surface.
Fill Perform a fast fill of the entire surface with a specific color, taking the clip rectangle into account.
FillRect Perform a fast fill of a rectangle with a specific color.
FillRects(TSdlRect[], Cardinal) Perform a fast fill of a set of rectangles with a specific color.
FillRects(TArray<TSdlRect>, Cardinal) Perform a fast fill of a set of rectangles with a specific color.
Flip Flip the surface vertically or horizontally.
Free Free the surface.
Lock Set up the surface for directly accessing the pixels.
MapRgb Map an RGB triple to an opaque pixel value for the surface.
MapRgba Map an RGBA quadruple to a pixel value for the surface.
PremultiplyAlpha Premultiply the alpha.
RemoveAlternateImages Remove all alternate versions of this surface.
SaveBmp(String) Save the surface to a file in BMP format.
SaveBmp(TSdlIOStream, Boolean) Save the surface to a seekable SDL data stream in BMP format.
Scale Creates a new surface identical to the existing surface, scaled to the desired size.
Stretch Perform a stretched pixel copy from this surface surface to another.
Unlock Release the surface after directly accessing the pixels.

Property Descriptions

AlphaMod

An additional alpha value used in blit operations.

When this surface is blitted, during the blit operation the source alpha value is modulated by this alpha value according to the following formula:

SrcA = SrcA * (Alpha div 255)

property AlphaMod: Byte read GetAlphaMod write SetAlphaMod

Type: Byte

Exceptions

ESdlError: Raised on failure.

See Also

BlendMode

The blend mode used for blit operations.

To copy a surface to another surface (or texture) without blending with the existing data, the blendmode of the source surface should be set to TSdlBlendMode.None.

property BlendMode: TSdlBlendMode read GetBlendMode write SetBlendMode

Type: TSdlBlendMode

Exceptions

ESdlError: Raised on failure.

ClipRect

The clipping rectangle for a surface.

When the surface is the destination of a blit, only the area within the clip rectangle is drawn into.

Note that blits are automatically clipped to the edges of the source and destination surfaces.

property ClipRect: TSdlRect read GetClipRect write SetClipRect

Type: TSdlRect

Exceptions

ESdlError: Raised on failure.

See Also

ColorKey

The color key (transparent pixel) in the surface.

The color key defines a pixel value that will be treated as transparent in a blit. For example, one can use this to specify that cyan pixels should be considered transparent, and therefore not rendered.

It is a pixel of the format used by the surface, as generated by TSdlPixelFormatDetails.MapRgb.

Set to SDL_NO_COLOR_KEY to disable the color key.

property ColorKey: Cardinal read GetColorKey write SetColorKey

Type: Cardinal

Exceptions

ESdlError: Raised on failure.

See Also

ColorMod

An additional color value multiplied into blit operations.

When this surface is blitted, during the blit operation each source color channel is modulated by the appropriate color value according to the following formula:

SrcC := SrcC * (Color div 255)

The Alpha value of the color is ignored. Use AlphaMod for alpha modulation.

property ColorMod: TSdlColor read GetColorMod write SetColorMod

Type: TSdlColor

Exceptions

ESdlError: Raised on failure.

See Also

Colorspace

The colorspace used by the surface.

The colorspace defaults to TSdlColorspace.SrgbLinear for floating point formats, TSdlColorspace.Hdr10 for 10-bit formats, TSdlColorspace.Srgb for other RGB surfaces and TSdlColorspace.BT709Full for YUV textures.

Setting the colorspace doesn't change the pixels, only how they are interpreted in color operations.

property Colorspace: TSdlColorspace read GetColorspace write SetColorspace

Type: TSdlColorspace

Exceptions

ESdlError: Raised on failure.

Flags

The flags of the surface, read-only

property Flags: TSdlSurfaceFlags read GetFlags

Type: TSdlSurfaceFlags

Format

The format of the surface, read-only

property Format: TSdlPixelFormat read GetFormat

Type: TSdlPixelFormat

H

The height of the surface, read-only.

property H: Integer read GetH

Type: Integer

HasAlternateImages

Whether the surface has alternate versions available.

property HasAlternateImages: Boolean read GetHasAlternateImages

Type: Boolean

See Also

HasColorKey

Whether the surface has a color key.

property HasColorKey: Boolean read GetHasColorKey

Type: Boolean

See Also

Images

Get an array including all versions of this surface.

This returns all versions of a surface, with this surface as the first element in the returned array.

property Images: TArray<TSdlSurface> read GetImages

Type: TArray<TSdlSurface>

See Also

MustLock

Whether the surface needs to be locked before access.

property MustLock: Boolean read GetMustLock

Type: Boolean

Palette

The palette used by a surface, or nil if there is no palette used.

A single palette can be shared with many surfaces.

property Palette: TSdlPalette read GetPalette write SetPalette

Type: TSdlPalette

Exceptions

ESdlError: Raised on failure.

Pitch

The distance in bytes between rows of pixels, read-only

property Pitch: Integer read GetPitch

Type: Integer

Pixel

The pixels of the surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

This uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

property Pixel[const AX, AY: Integer]: TSdlColor read GetPixel write SetPixel

Type: TSdlColor

PixelFloat

The pixels of the surface, as floating-point colors.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

This uses the entire 0..1 range when converting color components from pixel formats with less than 8 bits per RGB component.

property PixelFloat[const AX, AY: Integer]: TSdlColorF read GetPixelFloat write SetPixelFloat

Type: TSdlColorF

Pixels

A pointer to the pixels of the surface, the pixels are writeable if non-nil

property Pixels: Pointer read GetPixels write SetPixels

Type: Pointer

Properties

The properties associated with a surface.

The following properties are understood by SDL:

  • TSdlProperty.SurfaceSdrWhitePoint: for HDR10 and floating point surfaces, this defines the value of 100% diffuse white, with higher values being displayed in the High Dynamic Range headroom. This defaults to 203 for HDR10 surfaces and 1.0 for floating point surfaces.
  • TSdlProperty.SurfaceHdrHeadroom: for HDR10 and floating point surfaces, this defines the maximum dynamic range used by the content, in terms of the SDR white point. This defaults to 0.0, which disables tone mapping.
  • TSdlProperty.SurfaceTonemapOperator: the tone mapping operator used when compressing from a surface with high dynamic range to another with lower dynamic range. Currently this supports 'chrome', which uses the same tone mapping that Chrome uses for HDR content, the form '*=N', where N is a floating point scale factor applied in linear space, and 'none', which disables tone mapping. This defaults to 'chrome'.
  • TSdlProperty.SurfaceHotspotX: the hotspot pixel offset from the left edge of the image, if this surface is being used as a cursor.
  • TSdlProperty.SurfaceHotspotY: the hotspot pixel offset from the top edge of the image, if this surface is being used as a cursor.

property Properties: TSdlProperties read GetProperties

Type: TSdlProperties

Exceptions

ESdlError: Raised on failure.

UseRle

Whether to use RLE acceleration for the surface.

If RLE is enabled, color key and alpha blending blits are much faster, but the surface must be locked before directly accessing the pixels.

property UseRle: Boolean read GetUseRle write SetUseRle

Type: Boolean

Exceptions

ESdlError: Raised on failure.

See Also

W

The width of the surface, read-only.

property W: Integer read GetW

Type: Integer

Constructor Descriptions

Create

Create a new surface with a specific pixel format and existing pixel data.

No copy is made of the pixel data. Pixel data is not managed automatically; you must free the surface before you free the pixel data.

Pitch is the offset in bytes from one row of pixels to the next, e.g. AWidth * 4 for TSdlPixelFormat.Rgba8888.

You may pass nil for pixels and 0 for pitch to create a surface that you will fill in with valid values later.

constructor Create(const AWidth, AHeight: Integer; const AFormat: TSdlPixelFormat; const APixels: Pointer; const APitch: Integer); overload

Parameters

AWidth: Integer : The width of the surface.

AHeight: Integer : The height of the surface.

AFormat: TSdlPixelFormat : The pixel format for the new surface.

APixels: Pointer : A pointer to existing pixel data.

APitch: Integer : The number of bytes between each row, including padding.

Exceptions

ESdlError: Raised on failure.

See Also

Create

Create a new surface with a specific pixel format.

The pixels of the new surface are initialized to zero.

constructor Create(const AWidth, AHeight: Integer; const AFormat: TSdlPixelFormat); overload

Parameters

AWidth: Integer : The width of the surface.

AHeight: Integer : The height of the surface.

AFormat: TSdlPixelFormat : The pixel format for the new surface.

Exceptions

ESdlError: Raised on failure.

See Also

LoadBmp

Create a surface from a BMP image from a file.

constructor LoadBmp(const AFilename: String); overload

Parameters

AFilename: String : The name of the BMP file to load.

Exceptions

ESdlError: Raised on failure.

See Also

LoadBmp

Create a surface from a BMP image from a seekable SDL data stream.

constructor LoadBmp(const ASrc: TSdlIOStream; const ACloseIO: Boolean); overload

Parameters

ASrc: TSdlIOStream : The data stream for the surface.

ACloseIO: Boolean : If True, calls ASrc.Close before returning, even in the case of an error.

Exceptions

ESdlError: Raised on failure.

See Also

Operator Descriptions

Equal(TSdlSurface, TSdlSurface)

Used to compare against another TSdlSurface.

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

Parameters

ALeft: TSdlSurface

ARight: TSdlSurface

Returns

Boolean

Equal(TSdlSurface, Pointer)

Used to compare against nil.

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

Parameters

ALeft: TSdlSurface

ARight: Pointer

Returns

Boolean

Implicit(Pointer)

Used to set the value to nil.

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

Parameters

AValue: Pointer

Returns

TSdlSurface

NotEqual(TSdlSurface, TSdlSurface)

Used to compare against another TSdlSurface.

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

Parameters

ALeft: TSdlSurface

ARight: TSdlSurface

Returns

Boolean

NotEqual(TSdlSurface, Pointer)

Used to compare against nil.

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

Parameters

ALeft: TSdlSurface

ARight: Pointer

Returns

Boolean

Method Descriptions

AddAlternateImage(TSdlSurface)

Add an alternate version of a surface.

This function adds an alternate version of this surface, usually used for content with high DPI representations like cursors or icons. The size, format, and content do not need to match the original surface, and these alternate versions will not be updated when the original surface changes.

This function adds a reference to the alternate version, so you should call AImage.Free after this call.

procedure AddAlternateImage(const AImage: TSdlSurface); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AImage: TSdlSurface : The alternate surface to associate with this surface.

See Also

Blit(PSdlRect, TSdlSurface, PSdlRect)

Performs a fast blit from this surface to a destination surface with clipping.

If either ASrcRect or ADstRect are nil, the entire surface is copied while ensuring clipping to ADst.ClipRect.

The final blit rectangles are saved in ASrcRect and ADstRect after all clipping is performed.

The blit function should not be called on a locked surface.

The blit semantics for surfaces with and without blending and colorkey are defined as follows:

RGBA->RGB: Source surface blend mode set to TSdlBlendMode.Blend: alpha-blend (using the source alpha-channel and per-surface alpha). source color key ignored. Source surface blend mode set to TSdlBlendMode.None: copy RGB. if source color key set, only copy the pixels that do not match the RGB values of the source color key, ignoring alpha in the comparison.

RGB->RGBA: Source surface blend mode set to TSdlBlendMode.Blend: alpha-blend (using the source per-surface alpha). Source surface blend mode set to TSdlBlendMode.None: copy RGB, set destination alpha to source per-surface alpha value. both: if source color key set, only copy the pixels that do not match the source color key.

RGBA->RGBA: Source surface blend mode set to TSdlBlendMode.Blend: alpha-blend (using the source alpha-channel and per-surface alpha). source color key. Source surface blend mode set to TSdlBlendMode.None: copy all of RGBA to the destination. if source color key set, only copy the pixels that do not match the RGB values of the source color key, ignoring alpha in the comparison.

RGB->RGB: Source surface blend mode set to TSdlBlendMode.Blend: alpha-blend (using the source per-surface alpha). Source surface blend mode set to TSdlBlendMode.None: copy RGB. both: if source color key set, only copy the pixels that do not match the source color key.

procedure Blit(const ASrcRect: PSdlRect; const ADst: TSdlSurface; const ADstRect: PSdlRect); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: PSdlRect : The rectangle to be copied, or nil to copy the entire surface.

ADst: TSdlSurface : The blit target surface.

ADstRect: PSdlRect : The rectangle representing the X and Y position in the destination surface, or nil for (0,0). The width and height are ignored, and are copied from ASrcRect. If you want a specific width and height, you should use BlitScaled.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

Blit9Grid(PSdlRect, Integer, Integer, Integer, Integer, Single, TSdlScaleMode, TSdlSurface, PSdlRect)

Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.

The pixels in the source surface are split into a 3x3 grid, using the different corner sizes for each corner, and the sides and center making up the remaining pixels. The corners are then scaled using AScale and fit into the corners of the destination rectangle. The sides and center are then stretched into place to cover the remaining destination rectangle.

procedure Blit9Grid(const ASrcRect: PSdlRect; const ALeftWidth, ARightWidth, ATopHeight, ABottomHeight: Integer; const AScale: Single; const AScaleMode: TSdlScaleMode; const ADst: TSdlSurface; const ADstRect: PSdlRect); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: PSdlRect : The rectangle to be used for the 9-grid, or nil to use the entire surface.

ALeftWidth: Integer : The width, in pixels, of the left corners in ASrcRect.

ARightWidth: Integer : The width, in pixels, of the right corners in ASrcRect.

ATopHeight: Integer : The height, in pixels, of the top corners in ASrcRect.

ABottomHeight: Integer : The height, in pixels, of the bottom corners in ASrcRect.

AScale: Single : The scale used to transform the corner of ASrcRect into the corner of ADstRect, or 0.0 for an unscaled blit.

AScaleMode: TSdlScaleMode : Scale algorithm to be used.

ADst: TSdlSurface : The blit target surface.

ADstRect: PSdlRect : The target rectangle in the destination surface, or nil to fill the entire surface.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

BlitScaled(PSdlRect, TSdlSurface, PSdlRect, TSdlScaleMode)

Perform a scaled blit to a destination surface, which may be of a different format.

procedure BlitScaled(const ASrcRect: PSdlRect; const ADst: TSdlSurface; const ADstRect: PSdlRect; const AScaleMode: TSdlScaleMode); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: PSdlRect : The rectangle to be copied, or nil to copy the entire surface.

ADst: TSdlSurface : The blit target surface.

ADstRect: PSdlRect : The rectangle representing the X and Y position in the destination surface, or nil to fill the entire destination surface.

AScaleMode: TSdlScaleMode : The scale mode to be used.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

BlitScaledUnchecked(TSdlRect, TSdlSurface, TSdlRect, TSdlScaleMode)

Perform low-level surface scaled blitting only.

This is a semi-private function and it performs low-level surface blitting, assuming the input rectangles have already been clipped.

procedure BlitScaledUnchecked(const ASrcRect: TSdlRect; const ADst: TSdlSurface; const ADstRect: TSdlRect; const AScaleMode: TSdlScaleMode); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: TSdlRect : The rectangle to be copied.

ADst: TSdlSurface : The blit target surface.

ADstRect: TSdlRect : The target rectangle in the destination surface.

AScaleMode: TSdlScaleMode : The TSdlScaleMode to be used.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

BlitTiled(PSdlRect, Single, TSdlScaleMode, TSdlSurface, PSdlRect)

Perform a scaled and tiled blit to a destination surface, which may be of a different format.

The pixels in ASrcRect will be repeated as many times as needed to completely fill ADstRect.

procedure BlitTiled(const ASrcRect: PSdlRect; const AScale: Single; const AScaleMode: TSdlScaleMode; const ADst: TSdlSurface; const ADstRect: PSdlRect); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: PSdlRect : The rectangle to be copied, or nil to copy the entire surface.

AScale: Single : The scale used to transform ASrcRect into the destination rectangle, e.g. a 32x32 texture with a scale of 2 would fill 64x64 tiles.

AScaleMode: TSdlScaleMode : Scale algorithm to be used.

ADst: TSdlSurface : The blit target surface.

ADstRect: PSdlRect : The rectangle representing the X and Y position in the destination surface, or nil to fill the entire destination surface.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

BlitTiled(PSdlRect, TSdlSurface, PSdlRect)

Perform a tiled blit to a destination surface, which may be of a different format.

The pixels in ASrcRect will be repeated as many times as needed to completely fill ADstRect.

procedure BlitTiled(const ASrcRect: PSdlRect; const ADst: TSdlSurface; const ADstRect: PSdlRect); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: PSdlRect : The rectangle to be copied, or nil to copy the entire surface.

ADst: TSdlSurface : The blit target surface.

ADstRect: PSdlRect : The target rectangle in the destination surface, or nil to fill the entire surface.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

BlitUnchecked(TSdlRect, TSdlSurface, TSdlRect)

Perform low-level surface blitting only.

This is a semi-private blit function and it performs low-level surface blitting, assuming the input rectangles have already been clipped.

procedure BlitUnchecked(const ASrcRect: TSdlRect; const ADst: TSdlSurface; const ADstRect: TSdlRect); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: TSdlRect : The rectangle to be copied.

ADst: TSdlSurface : The blit target surface.

ADstRect: TSdlRect : The target rectangle in the destination surface.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

Clear(TSdlColorF)

Clear the surface with a specific color, with floating point precision.

This function handles all surface formats, and ignores any clip rectangle.

If the surface is YUV, the color is assumed to be in the sRGB colorspace, otherwise the color is assumed to be in the colorspace of the suface.

procedure Clear(const AColor: TSdlColorF); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AColor: TSdlColorF : The color.

See Also

Clear(Single, Single, Single, Single)

Clear the surface with a specific color, with floating point precision.

This function handles all surface formats, and ignores any clip rectangle.

If the surface is YUV, the color is assumed to be in the sRGB colorspace, otherwise the color is assumed to be in the colorspace of the suface.

procedure Clear(const AR, AG, AB: Single; const AA: Single = 1); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AR: Single : The red component of the pixel, normally in the range 0-1.

AG: Single : The green component of the pixel, normally in the range 0-1.

AB: Single : The blue component of the pixel, normally in the range 0-1.

AA: Single = 1 : (Optional) alpha component of the pixel, normally in the range 0-1.

See Also

Convert(TSdlPixelFormat, TSdlPalette, TSdlColorspace, TSdlProperties)

Copy the existing surface to a new surface of the specified format and colorspace.

This function converts an existing surface to a new format and colorspace and returns the new surface. This will perform any pixel format and colorspace conversion needed.

If the original surface has alternate images, the new surface will have a reference to them as well.

function Convert(const AFormat: TSdlPixelFormat; const APalette: TSdlPalette; const AColorspace: TSdlColorspace; const AProps: TSdlProperties): TSdlSurface; overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AFormat: TSdlPixelFormat : The new pixel format.

APalette: TSdlPalette : A palette to use for indexed formats.

AColorspace: TSdlColorspace : The new colorspace.

AProps: TSdlProperties : Additional color properties.

Returns

TSdlSurface

Convert(TSdlPixelFormat, TSdlColorspace)

Copy the existing surface to a new surface of the specified format and colorspace.

This function converts an existing surface to a new format and colorspace and returns the new surface. This will perform any pixel format and colorspace conversion needed.

If the original surface has alternate images, the new surface will have a reference to them as well.

function Convert(const AFormat: TSdlPixelFormat; const AColorspace: TSdlColorspace): TSdlSurface; overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AFormat: TSdlPixelFormat : The new pixel format.

AColorspace: TSdlColorspace : The new colorspace.

Returns

TSdlSurface

Convert(TSdlPixelFormat)

Copy the surface to a new surface of the specified format.

This function is used to optimize images for faster repeat blitting. This is accomplished by converting the original and storing the result as a new surface. The new, optimized surface can then be used as the source for future blits, making them faster.

If the original surface has alternate images, the new surface will have a reference to them as well.

function Convert(const AFormat: TSdlPixelFormat): TSdlSurface; overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AFormat: TSdlPixelFormat : The new pixel format.

Returns

TSdlSurface: Thne new SDL surface.

CreatePalette

Create a palette and associate it with this surface.

This function creates a palette compatible with the surface. The palette is then returned for you to modify, and the surface will automatically use the new palette in future operations. You do not need to destroy the returned palette, it will be freed when the reference count reaches 0, usually when the surface is destroyed.

Bitmap surfaces (with format TSdlPixelFormat.Index1Lsb or TSdlPixelFormat.Index1Msb) will have the palette initialized with 0 as white and 1 as black. Other surfaces will get a palette initialized with white in every entry.

If this function is called for a surface that already has a palette, a new palette will be created to replace it.

function CreatePalette: TSdlPalette; inline

Exceptions

ESdlError: Raised on failure (e.g. if the surface didn't have an index format).

Returns

TSdlPalette: A new palette.

DisableClipping

Disables clipping. Set the ClipRect property to enable clipping again.

procedure DisableClipping; inline

See Also

Duplicate

Creates a new surface identical to the existing surface.

If the original surface has alternate images, the new surface will have a reference to them as well.

The returned surface should be freed with Free.

function Duplicate: TSdlSurface; inline

Exceptions

ESdlError: Raised on failure.

Returns

TSdlSurface: A copy of the surface.

See Also

Fill(Cardinal)

Perform a fast fill of the entire surface with a specific color, taking the clip rectangle into account.

AColor should be a pixel of the format used by the surface, and can be generated by TSdlPixelFormatDetails.MapRgb or TSdlPixelFormatDetails.MapRgba. If the color value contains an alpha component then the destination is simply filled with that alpha information, no blending takes place.

If there is a clip rectangle set on the destination (set via ClipRect), then this function will fill the clip rectangle.

procedure Fill(const AColor: Cardinal); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AColor: Cardinal : The color to fill with.

See Also

FillRect(TSdlRect, Cardinal)

Perform a fast fill of a rectangle with a specific color.

AColor should be a pixel of the format used by the surface, and can be generated by TSdlPixelFormatDetails.MapRgb or TSdlPixelFormatDetails.MapRgba. If the color value contains an alpha component then the destination is simply filled with that alpha information, no blending takes place.

If there is a clip rectangle set on the destination (set via ClipRect), then this function will fill based on the intersection of the clip rectangle and ARect.

procedure FillRect(const ARect: TSdlRect; const AColor: Cardinal); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ARect: TSdlRect : The rectangle to fill.

AColor: Cardinal : The color to fill with.

See Also

FillRects(TSdlRect[], Cardinal)

Perform a fast fill of a set of rectangles with a specific color.

AColor should be a pixel of the format used by the surface, and can be generated by TSdlPixelFormatDetails.MapRgb or TSdlPixelFormatDetails.MapRgba. If the color value contains an alpha component then the destination is simply filled with that alpha information, no blending takes place.

If there is a clip rectangle set on the destination (set via ClipRect), then this function will fill based on the intersection of the clip rectangle and the given rectangles.

procedure FillRects(const ARects: array of TSdlRect; const AColor: Cardinal); overload

Exceptions

ESdlError: Raised on failure.

Parameters

ARects: array of TSdlRect : An array rectangles to fill.

AColor: Cardinal : The color to fill with.

See Also

FillRects(TArray<TSdlRect>, Cardinal)

Perform a fast fill of a set of rectangles with a specific color.

AColor should be a pixel of the format used by the surface, and can be generated by TSdlPixelFormatDetails.MapRgb or TSdlPixelFormatDetails.MapRgba. If the color value contains an alpha component then the destination is simply filled with that alpha information, no blending takes place.

If there is a clip rectangle set on the destination (set via ClipRect), then this function will fill based on the intersection of the clip rectangle and the given rectangles.

procedure FillRects(const ARects: TArray<TSdlRect>; const AColor: Cardinal); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ARects: TArray<TSdlRect> : An array rectangles to fill.

AColor: Cardinal : The color to fill with.

See Also

Flip(TSdlFlipMode)

Flip the surface vertically or horizontally.

procedure Flip(const AFlip: TSdlFlipMode); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AFlip: TSdlFlipMode : The direction(s) to flip.

Free

Free the surface.

procedure Free; inline

Lock

Set up the surface for directly accessing the pixels.

Between calls to Lock / Unlock, you can write to and read from Pixels, using the pixel format in Format. Once you are done accessing the surface, you should use Unlock to release it.

Not all surfaces require locking. If MustLock returns False, then you can read and write to the surface at any time, and the pixel format of the surface will not change.

procedure Lock; inline

Exceptions

ESdlError: Raised on failure.

See Also

MapRgb(Byte, Byte, Byte)

Map an RGB triple to an opaque pixel value for the surface.

This function maps the RGB color value to the specified pixel format and returns the pixel value best approximating the given RGB color value for the given pixel format.

If the surface has a palette, the index of the closest matching color in the palette will be returned.

If the surface pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a UInt16, and similarly a UInt8 for an 8-bpp format).

function MapRgb(const AR, AG, AB: Byte): Cardinal; inline

Parameters

AR: Byte : The red component of the pixel in the range 0-255.

AG: Byte : The green component of the pixel in the range 0-255.

AB: Byte : The blue component of the pixel in the range 0-255.

Returns

Cardinal: A pixel value.

See Also

MapRgba(Byte, Byte, Byte, Byte)

Map an RGBA quadruple to a pixel value for the surface.

This function maps the RGBA color value to the specified pixel format and returns the pixel value best approximating the given RGBA color value for the given pixel format.

If the surface pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette).

If the surface has a palette, the index of the closest matching color in the palette will be returned.

If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a UInt16, and similarly a UInt8 for an 8-bpp format).

function MapRgba(const AR, AG, AB, AA: Byte): Cardinal; inline

Parameters

AR: Byte : The red component of the pixel in the range 0-255.

AG: Byte : The green component of the pixel in the range 0-255.

AB: Byte : The blue component of the pixel in the range 0-255.

AA: Byte : The alpha component of the pixel in the range 0-255.

Returns

Cardinal: A pixel value.

See Also

PremultiplyAlpha(Boolean)

Premultiply the alpha.

procedure PremultiplyAlpha(const ALinear: Boolean); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ALinear: Boolean : True to convert from sRGB to linear space for the alpha multiplication, False to do multiplication in sRGB space.

RemoveAlternateImages

Remove all alternate versions of this surface.

This function removes a reference from all the alternative versions, destroying them if this is the last reference to them.

procedure RemoveAlternateImages; inline

See Also

SaveBmp(String)

Save the surface to a file in BMP format.

Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the BMP directly. Other RGB formats with 8-bit or higher get converted to a 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit surface before they are saved. YUV and paletted 1-bit and 4-bit formats are not supported.

procedure SaveBmp(const AFilename: String); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AFilename: String : Name of the file to save to.

See Also

SaveBmp(TSdlIOStream, Boolean)

Save the surface to a seekable SDL data stream in BMP format.

Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the BMP directly. Other RGB formats with 8-bit or higher get converted to a 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit surface before they are saved. YUV and paletted 1-bit and 4-bit formats are not supported.

procedure SaveBmp(const ADst: TSdlIOStream; const ACloseIO: Boolean); overload; inline

Exceptions

ESdlError: Raised on failure.

Parameters

ADst: TSdlIOStream : A data stream to save to.

ACloseIO: Boolean : If true, calls ADst.Close before returning, even in the case of an error.

See Also

Scale(Integer, Integer, TSdlScaleMode)

Creates a new surface identical to the existing surface, scaled to the desired size.

The returned surface should be freed with Free.

function Scale(const AWidth, AHeight: Integer; const AScaleMode: TSdlScaleMode): TSdlSurface; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AWidth: Integer : The width of the new surface.

AHeight: Integer : The height of the new surface.

AScaleMode: TSdlScaleMode : The scale mode to be used.

Returns

TSdlSurface

See Also

Stretch(TSdlRect, TSdlSurface, TSdlRect, TSdlScaleMode)

Perform a stretched pixel copy from this surface surface to another.

procedure Stretch(const ASrcRect: TSdlRect; const ADst: TSdlSurface; const ADstRect: TSdlRect; const AScaleMode: TSdlScaleMode); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ASrcRect: TSdlRect : The rectangle to be copied.

ADst: TSdlSurface : The blit target surface.

ADstRect: TSdlRect : The target rectangle in the destination surface.

AScaleMode: TSdlScaleMode : The TSdlScaleMode to be used.

See Also

Remarks

The same destination surface should not be used from two threads at once. It is safe to use the same source surface from multiple threads.

Unlock

Release the surface after directly accessing the pixels.

procedure Unlock; inline

See Also