Class Surface

Namespace: Sdl3Sharp.Video

Assembly: Sdl3Sharp.dll

Represents a buffer of pixels in memory, used for software rendering and as a source for textures

public class Surface : IDisposable

Inheritance: object

Surface

Implements: IDisposable

Derived: WindowSurface

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Surfaces make serious efforts to manage images in various formats, and provide a reasonable toolbox for transforming the data, including copying between Surfaces, filling rectangles in the image data, etc.

Constructors

Surface(Stream, bool)

Creates a new Surface by loading a BMP or PNG image from the specified stream

public Surface(Stream source, bool closeAfterwards = false)

Parameters

source Stream: The stream to load the image from
closeAfterwards bool: A value indicating whether the source stream should be closed before this method returns (even in case of an error)

Remarks

The format of the data in the source stream must be BMP or PNG, otherwise this constructor will fail.

Remember to dispose of the resulting surface when you are done with it. Not doing so will result in a memory leak.

Exceptions

SdlException: The Surface could not be created (check TryGet(out string?) for more information)

Surface(int, int, PixelFormat)

Creates a new Surface with the specified width, height and pixel format

public Surface(int width, int height, PixelFormat format)

Parameters

width int: The width of the surface
height int: The height of the surface
format PixelFormat: The pixel format of the surface

Remarks

The pixel memory of the newly created surface is initialized to all zeroes.

Exceptions

SdlException: The Surface could not be created (check TryGet(out string?) for more information)

Surface(int, int, PixelFormat, NativeMemory, int)

Creates a new Surface with the specified width, height, pixel format and pre-allocated pixel memory

public Surface(int width, int height, PixelFormat format, NativeMemory pixels, int pitch)

Parameters

width int: The width of the surface
height int: The height of the surface
format PixelFormat: The pixel format of the surface
pixels NativeMemory: The pre-allocated pixel memory
pitch int: The pitch of the surface, in bytes

Remarks

No copy is made of the pixels, instead it's referenced directly as the pixel memory of the newly created surface. That also means that pixels must remain valid and alive for the lifetime of the surface. This is not handled automatically for you!

The pitch is the offset in bytes between each vertical pixel row in the pixels memory, e.g. 4 * width for a Rgba8888 format.

Exceptions

ArgumentException

pixels is invalid

or - pixels is too small

Surface(int, int, PixelFormat, Memory<byte>, int)

Creates a new Surface with the specified width, height, pixel format and pre-allocated pixel memory

public Surface(int width, int height, PixelFormat format, Memory<byte> pixels, int pitch)

Parameters

width int: The width of the surface
height int: The height of the surface
format PixelFormat: The pixel format of the surface
pixels Memory<byte>: The pre-allocated pixel memory
pitch int: The pitch of the surface, in bytes

Remarks

The pitch is the offset in bytes between each vertical pixel row in the pixels memory, e.g. 4 * width for a Rgba8888 format.

Exceptions

ArgumentException: pixels is too small

Surface(int, int, PixelFormat, void*, int)

Creates a new Surface with the specified width, height, pixel format and pre-allocated pixel memory

public Surface(int width, int height, PixelFormat format, void* pixels, int pitch)

Parameters

width int: The width of the surface
height int: The height of the surface
format PixelFormat: The pixel format of the surface
pixels void*: A pointer to the pre-allocated pixel memory
pitch int: The pitch of the surface, in bytes

Remarks

The pitch is the offset in bytes between each vertical pixel row in the pixels memory, e.g. 4 * width for a Rgba8888 format.

Exceptions

SdlException: The Surface could not be created (check TryGet(out string?) for more information)

Surface(string)

Creates a new Surface by loading a BMP or PNG image from the specified file

public Surface(string file)

Parameters

file string: A file path to the image

Remarks

The format of the file must be BMP or PNG, otherwise this constructor will fail.

Remember to dispose of the resulting surface when you are done with it. Not doing so will result in a memory leak.

Exceptions

SdlException: The Surface could not be created (check TryGet(out string?) for more information)

Properties

AlphaMod

Gets or sets the alpha modulation value used in blit operations

public byte AlphaMod { get; set; }

Property Value

byte: The alpha modulation value used in blit operations

Remarks

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

BlendMode

Gets or sets the blend mode used for blit operations

public BlendMode BlendMode { get; set; }

Property Value

BlendMode: The blend mode used for blit operations

Remarks

To copy a surface to another surface without blending with the existing data, the BlendMode of the source surface should be set to None.

Exceptions

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

ClippingRect

Gets or sets the clipping rectangle for the surface

public Rect<int> ClippingRect { get; set; }

Property Value

Rect<int>: The clipping rectangle for the surface

Remarks

When this surface is blitted onto, only the area within the clipping rectangle is drawn into. Note that blits are automatically clipped to the edges of the source and destination surfaces.

If the value of this property is equal to the surface's bounds, clipping is effectively disabled.

Alternatively, you can use the methods ResetClippingRect() and SetClippingRect(in Rect<int>) to manipulate the clipping rectangle. The latter returns a value indicating whether the set clipping rectangle intersects the surface area.

ColorKey

Gets or sets the color key (transparent pixel value) in the surface

public uint? ColorKey { get; set; }

Property Value

uint?: The color key (transparent pixel value) in the surface, as an encoded pixel value used by the surface, or null if color keying is disabled

Remarks

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.

The value of this property uses the encoded pixel value format used by the surface, as generated by MapColor(byte, byte, byte).

Alternatively, if you just want to check whether color keying is enabled, you can use the HasColorKey property instead.

Exceptions

SdlException: When setting this property, the specified color key is invalid for the surface's pixel format (check TryGet(out string?) for more information). For example, this can happen when the key is out of range for palettized formats.

ColorMod

Gets or sets the color modulation values used in blit operations

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

Property Value

(byte r, byte g, byte b): The color modulation values used in blit operations

Remarks

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

ColorSpace

Gets or sets the color space of the surface

public ColorSpace ColorSpace { get; set; }

Property Value

ColorSpace: The color space of the surface

Remarks

The color space defaults to SrgbLinear for floating point formats, Hdr10 for 10-bit formats, Srgb for other RGB surfaces and Bt709Full for YUV textures.

Setting the color space doesn't change the pixels, only how they are interpreted in color operations. If you want to convert the pixels to a different color space, use an appropriate one of the TryConvert* methods.

Flags

Gets the surface flags

public SurfaceFlags Flags { get; }

Property Value

SurfaceFlags: The surface flags

Remarks

Instead of examining the flags directly, you can use the specific properties IsLocked, IsPreAllocated, IsSimdAligned, and MustLock to check for particular surface characteristics.

Format

Gets the pixel format of the surface

public PixelFormat Format { get; }

Property Value

PixelFormat: The pixel format of the surface

HasAlternateImages

Gets a value indicating whether the surface has alternate images

public bool HasAlternateImages { get; }

Property Value

bool: true, if alternate versions of the surface are available; otherwise, false

HasColorKey

Gets a value indicating whether the surface has a color key (transparent pixel value) set

public bool HasColorKey { get; }

Property Value

bool: true, if the surface has a color key set; otherwise, false

HdrHeadroom

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

public float HdrHeadroom { get; set; }

Property Value

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

Remarks

This property is used for HDR10 and floating point Surfaces.

The value of this property defines the maximum dynamic range used by the content, in terms of the SDR white point.

The value defaults to 0.0, which disables tone mapping.

Height

Gets the height of the surface, in pixels

public int Height { get; }

Property Value

int: The height of the surface, in pixels

HotspotX

Gets or sets the hotspot pixel offset from the left edge for a cursor

public long HotspotX { get; set; }

Property Value

long: The hotspot pixel offset from the left edge for a cursor

Remarks

The value of this property defines the pixel offset to the hotspot from the left edge of the Surface used as a cursor.

HotspotY

Gets or sets the hotspot pixel offset from the top edge for a cursor

public long HotspotY { get; set; }

Property Value

long: The hotspot pixel offset from the top edge for a cursor

Remarks

The value of this property defines the pixel offset to the hotspot from the top edge of the Surface used as a cursor.

Images

Gets a list of all versions of the surface

public Surface[] Images { get; }

Property Value

Surface[]: A list of all versions of the surface, including itself

Remarks

The returned array includes all alternate images of the surface, including itself as the first element.

Reading this property can be very expensive, you should consider caching it's value and reusing it as long as you're sure that the alternate images of the surface don't change.

You can manipulate the list of alternate images of a surface using the TryAddAlternateImage(Surface) and ClearAlternateImages() methods.

IsLocked

Gets a value indicating whether the surface is currently locked

public bool IsLocked { get; }

Property Value

bool: true, if the surface is currently locked; otherwise, false

Remarks

It's safe to access UnsafePixels only if this property is true.

This property is meant to be used as part of the MustLock - IsLocked - TryUnsafeLock() - UnsafePixels - UnsafeUnlock() pattern, if you want to access the surface's pixel memory directly in a faster and more efficient way. If you're looking for a simpler and safer way to access the pixel memory, consider using TryLock(out SurfacePixelMemoryManager?) instead.

IsPreAllocated

Gets a value indicating whether the surface uses pre-allocated pixel memory

public bool IsPreAllocated { get; }

Property Value

bool: true, if the surface uses pre-allocated pixel memory; otherwise, false

Remarks

A surface uses pre-allocated pixel memory, for example, when it was created using Surface(int, int, PixelFormat, NativeMemory, int), Surface(int, int, PixelFormat, Memory<byte>, int), or Surface(int, int, PixelFormat, void*, int).

IsRle

Gets or sets a value indicating whether the surface uses run-length encoding

public bool IsRle { get; set; }

Property Value

bool: true, if the surface uses run-length encoding; otherwise, false

Remarks

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

When setting this property, it silently fails if the surface's pixel format is a FourCC format.

IsSimdAligned

Gets a value indicating whether the surface uses pixel memory that's aligned for SIMD operations

public bool IsSimdAligned { get; }

Property Value

bool: true, if the surface uses pixel memory that's aligned for SIMD operations; otherwise, false

MustLock

Gets a value indicating whether the surface must be locked before accessing it's pixel memory

public bool MustLock { get; }

Property Value

bool: true, if the surface must be locked before accessing it's pixel memory; otherwise, false

Examples

Example usage:

Surface surface;

...

if (surface.MustLock && surface.TryUnsafeLock())
{
	// It's safe to access surface.UnsafePixels here

	...

	surface.UnsafeUnlock(); 
}

Remarks

Not all surfaces require locking. If the value of this property is false, then you can read and write to the surface at any time, and the pixel format of the surface will not change.

Palette

Gets or sets the palette used by the surface

public Palette? Palette { get; set; }

Property Value

Palette: The palette used by the surface, or null if the surface doesn't use a palette

Remarks

A single Palette can be shared between multiple Surfaces.

Exceptions

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

Pitch

Gets the pitch of the surface, in bytes

public int Pitch { get; }

Property Value

int: The pitch of the surface, in bytes

Remarks

The pitch is the length of a single row of pixels in bytes. This value may be different from the width of the surface times the number of bytes per pixel for packing and alignment purposes.

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").

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 32⨯32 surface in NV12 format with a pitch of 32 would consist of 32⨯32 bytes of Y plane followed by 32⨯16 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.

Properties

Gets the properties associated with the surface

public Properties? Properties { get; }

Property Value

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

Rotation

Gets or sets the rotation angle, in degrees, for the surface

public float Rotation { get; set; }

Property Value

float: The rotation angle, in clockwise degrees, for the surface

Remarks

The value of this property defines the number of degrees the surface's pixel data is meant to be rotated clockwise to make it right-side up.

This is used by the camera API, if a mobile device is oriented differently than what its camera provides (i.e. the camera always provides portrait images but the phone is being held in landscape orientation).

The value defaults to 0.0.

SdrWhitePoint

Gets or sets the defining value for 100% white

public float SdrWhitePoint { get; set; }

Property Value

float: The defining value for 100% white

Remarks

This property is used by HDR10 and floating point Surfaces.

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

The value defaults to 203 for HDR10 surfaces and 1.0 for floating point surfaces.

TonemapOperator

Gets or sets the expression of the tonemap operator to used when compressing from a higher dynamic range to a lower dynamic range

public string TonemapOperator { get; set; }

Property Value

string: The expression of the tonemap operator to used when compressing from a higher dynamic range to a lower dynamic range

Remarks

The value of this property defines the tone mapping operator used when compressing from a Surface with high dynamic range to another with lower dynamic range. Currently this supports the following values:

"chrome"The same tone mapping that Chrome uses for HDR content
"*=N" where N is a floating point numberN is a floating point scale factor applied in linear. E.g. "*=0.5".
"none"Tone mapping is disabled

The value defaults to "chrome".

UnsafePixels

Gets the underlying pixel memory of the surface

public NativeMemory UnsafePixels { get; }

Property Value

NativeMemory: The underlying pixel memory of the surface

Examples

Example usage:

Surface surface;

...

if (surface.MustLock && surface.TryUnsafeLock())
{
	// It's safe to access surface.UnsafePixels here

	...

	surface.UnsafeUnlock(); 
}

Remarks

It's unsafe to access this property for surfaces that must be locked and are not currently locked.

Width

Gets the width of the surface, in pixels

public int Width { get; }

Property Value

int: The width of the surface, in pixels

Methods

ClearAlternateImages()

Removes all alternate versions associated with the surface

public void ClearAlternateImages()

Dispose()

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

public void Dispose()

Dispose(bool, bool)

Disposes the surface

protected virtual void Dispose(bool disposing, bool forget)

Parameters

disposing bool: A value indicating whether the call came from a call to Dispose() or from the finalizer
forget bool: A value indicating whether to forget the managed surface

Remarks

This unpins any NativeMemory instances or Memory<T> instances used to create the surface.

~Surface()

protected ~Surface()

MapColor(Color<byte>)

Maps a Color<byte> to an encoded pixel value for the surface

public uint MapColor(Color<byte> color)

Parameters

color Color<byte>: The Color<byte> to encoded

Returns

uint: An encoded pixel value in the pixel format of the surface

Remarks

This method maps the Color<byte> to the surface's pixel format and returns the encoded pixel value best approximating the given Color<byte> for the pixel format.

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

If the pixel format has no alpha component, the given alpha component value will be ignored (as it will be in indexed formats with a Palette).

If the pixel format's bits-per-pixel value (color depth) is less than 32-bits per pixel then the unused upper bits of the returned encoded pixel value can safely be ignored (e.g., with a 16-bits per pixel format the returned encoded pixel value can be safely cast (truncated) to an ushort value, and similarly to a byte value for an 8-bits per pixel formats).

MapColor(byte, byte, byte)

Maps RGB component values to an opaque encoded pixel value for the surface

public uint MapColor(byte r, byte g, byte b)

Parameters

r byte: The red component value to encode
g byte: The green component value to encode
b byte: The blue component value to encode

Returns

uint: An encoded pixel value in the pixel format of the surface

Remarks

This method maps the RGB color value to the surface's pixel format and returns the encoded pixel value best approximating the given RGB color value for the pixel format.

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

If the pixel format has an alpha component, the encoded pixel value's alpha component value will be set to be fully opaque.

MapColor(byte, byte, byte, byte)

Maps RGBA component values to an encoded pixel value for the surface

public uint MapColor(byte r, byte g, byte b, byte a)

Parameters

r byte: The red component value to encode
g byte: The green component value to encode
b byte: The blue component value to encode
a byte: The alpha component value to encode

Returns

uint: An encoded pixel value in the pixel format of the surface

Remarks

This method maps the RGBA color value to the surface's pixel format and returns the encoded pixel value best approximating the given RGBA color value for the pixel format.

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

If the pixel format has no alpha component, the given alpha component value will be ignored (as it will be in indexed formats with a Palette).

ResetClippingRect()

Disables the clipping rectangle for the surface

public void ResetClippingRect()

Remarks

This method disables clipping for the surface, essentially setting the clipping rectangle to the surface's bounds.

SetClippingRect(in Rect<int>)

Sets the clipping rectangle for the surface

public bool SetClippingRect(in Rect<int> rect)

Parameters

rect Rect<int>: The clipping rectangle to set

Returns

bool: true, if the clipping rectangle set intersects with the surface area; otherwise, false

Remarks

Alternatively, you can set ClippingRect instead, if you're not interested in whether the new clipping rectangle intersects with the surface area.

TryAddAlternateImage(Surface)

Tries to add an alternate version of the surface

public bool TryAddAlternateImage(Surface image)

Parameters

image Surface: The alternate version to associate with the surface

Returns

bool: true, if the alternate version was added successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method 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.

TryBlit(in Rect<int>, Surface)

Tries to perform a fast blit from a specified source surface to this surface with clipping

public bool TryBlit(in Rect<int> destinationRect, Surface source)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto. The width and the height are ignored and taken from source instead.
source Surface: The source surface to blit from

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method blits the entire source surface to this surface at the position defined by destinationRect while ensuring clipping by ClippingRect. The width and the height of destinationRect are ignored and taken from the source instead. If you want to specify width and height for the destination rectangle, consider using TryBlitScaled(in Rect<int>, Surface, ScaleMode) instead.

Neither this surface nor the source surface must be locked when calling this method!

The blitting semantics for surfaces with and without blending and color keying are defined as follows:

RGBA 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB, set destination alpha to source per-surface alpha value; if the source's ColorKey is set, only copy pixels that do not match the color key
RGBA 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy all of RGBA; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key

TryBlit(in Rect<int>, Surface, in Rect<int>)

Tries to perform a fast blit from a specified source surface to this surface with clipping

public bool TryBlit(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto. The width and the height are ignored and taken from sourceRect instead.
source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method blits a portion of the source surface defined by sourceRect to this surface at the position defined by destinationRect while ensuring clipping by ClippingRect. The width and the height of destinationRect are ignored and taken from sourceRect instead. If you want to specify width and height for the destination rectangle, consider using TryBlitScaled(in Rect<int>, Surface, in Rect<int>, ScaleMode) instead.

Neither this surface nor the source surface must be locked when calling this method!

The blitting semantics for surfaces with and without blending and color keying are defined as follows:

RGBA 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB, set destination alpha to source per-surface alpha value; if the source's ColorKey is set, only copy pixels that do not match the color key
RGBA 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy all of RGBA; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key

TryBlit(Surface)

Tries to perform a fast blit from a specified source surface to this surface with clipping

public bool TryBlit(Surface source)

Parameters

source Surface: The source surface to blit from

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method blits the entire source surface to this surface at the position (0, 0) while ensuring clipping by ClippingRect. The width and the height of the destination blit area are taken from the source. If you want to specify width and height for the blit area, consider using TryBlitScaled(Surface, ScaleMode) instead.

Neither this surface nor the source surface must be locked when calling this method!

The blitting semantics for surfaces with and without blending and color keying are defined as follows:

RGBA 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB, set destination alpha to source per-surface alpha value; if the source's ColorKey is set, only copy pixels that do not match the color key
RGBA 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy all of RGBA; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key

TryBlit(Surface, in Rect<int>)

Tries to perform a fast blit from a specified source surface to this surface with clipping

public bool TryBlit(Surface source, in Rect<int> sourceRect)

Parameters

source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method blits a portion of the source surface defined by sourceRect to this surface at the position (0, 0) while ensuring clipping by ClippingRect. The width and the height of the destination blit area are taken from sourceRect. If you want to specify width and height for the destination blit area, consider using TryBlitScaled(Surface, in Rect<int>, ScaleMode) instead.

Neither this surface nor the source surface must be locked when calling this method!

The blitting semantics for surfaces with and without blending and color keying are defined as follows:

RGBA 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB, set destination alpha to source per-surface alpha value; if the source's ColorKey is set, only copy pixels that do not match the color key
RGBA 🡒 RGBA
- source's BlendMode is Blend alpha-blend (using the source alpha-channel and per-surface alpha); the source's ColorKey is ignored
- source's BlendMode is None copy all of RGBA; if the source's ColorKey is set, only copy pixels that do not match the color key, ignoring alpha in the comparison
RGB 🡒 RGB
- source's BlendMode is Blend alpha-blend (using the source per-surface alpha); if the source's ColorKey is set, only copy pixels that do not match the color key
- source's BlendMode is None copy RGB; if the source's ColorKey is set, only copy pixels that do not match the color key

TryBlit9Grid(in Rect<int>, Surface, in Rect<int>, int, int, int, int, float, ScaleMode)

Tries to perform a 9-grid scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlit9Grid(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect, int leftWidth, int rightWidth, int topHeight, int bottomHeight, float scale, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit
leftWidth int: The width, in pixels, of the left corners in sourceRect
rightWidth int: The width, in pixels, of the right corners in sourceRect
topHeight int: The height, in pixels, of the top corners in sourceRect
bottomHeight int: The height, in pixels, of the bottom corners in sourceRect
scale float: The scale to use to transform the corners of sourceRect into the corners of destinationRect, or 0 for an unscaled blit
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the source surface are split into a 3⨯3 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 scale and fit into the corners of the destinationRect. The sides and center are then stretched into place to cover the remaining portion of the destinationRect.

The region specified by sourceRect from the source surface is used as the 9-grid source and scaled to fit into the region specified by destinationRect on this surface.

TryBlit9Grid(in Rect<int>, Surface, int, int, int, int, float, ScaleMode)

Tries to perform a 9-grid scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlit9Grid(in Rect<int> destinationRect, Surface source, int leftWidth, int rightWidth, int topHeight, int bottomHeight, float scale, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
leftWidth int: The width, in pixels, of the left corners in the source
rightWidth int: The width, in pixels, of the right corners in the source
topHeight int: The height, in pixels, of the top corners in the source
bottomHeight int: The height, in pixels, of the bottom corners in the source
scale float: The scale to use to transform the corners of the source into the corners of destinationRect, or 0 for an unscaled blit
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The entire source surface is used as the 9-grid source and scaled to fit into the region specified by destinationRect on this surface.

TryBlit9Grid(Surface, in Rect<int>, int, int, int, int, float, ScaleMode)

Tries to perform a 9-grid scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlit9Grid(Surface source, in Rect<int> sourceRect, int leftWidth, int rightWidth, int topHeight, int bottomHeight, float scale, ScaleMode scaleMode)

Parameters

source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit
leftWidth int: The width, in pixels, of the left corners in sourceRect
rightWidth int: The width, in pixels, of the right corners in sourceRect
topHeight int: The height, in pixels, of the top corners in sourceRect
bottomHeight int: The height, in pixels, of the bottom corners in sourceRect
scale float: The scale to use to transform the corners of sourceRect into the corners of this surface, or 0 for an unscaled blit
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the source surface are split into a 3⨯3 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 scale and fit into the corners of this surface. The sides and center are then stretched into place to cover the remaining portion of this surface.

The region specified by sourceRect from the source surface is used as the 9-grid source and scaled to fit into the entire area of this surface.

TryBlit9Grid(Surface, int, int, int, int, float, ScaleMode)

Tries to perform a 9-grid scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlit9Grid(Surface source, int leftWidth, int rightWidth, int topHeight, int bottomHeight, float scale, ScaleMode scaleMode)

Parameters

source Surface: The source surface to blit from
leftWidth int: The width, in pixels, of the left corners in the source
rightWidth int: The width, in pixels, of the right corners in the source
topHeight int: The height, in pixels, of the top corners in the source
bottomHeight int: The height, in pixels, of the bottom corners in the source
scale float: The scale to use to transform the corners of the source into the corners of this surface, or 0 for an unscaled blit
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixels in the source surface are split into a 3⨯3 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 scale and fit into the corners of this surface. The sides and center are then stretched into place to cover the remaining portion of this surface.

The entire source surface is used as the 9-grid source and scaled to fit into the entire area of this surface.

TryBlitScaled(in Rect<int>, Surface, in Rect<int>, ScaleMode)

Tries to perform a scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitScaled(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The region specified by sourceRect from the source surface is used and scaled to fit into the region specified by destinationRect on this surface.

TryBlitScaled(in Rect<int>, Surface, ScaleMode)

Tries to perform a scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitScaled(in Rect<int> destinationRect, Surface source, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The entire source surface is used and scaled to fit into the region specified by destinationRect on this surface.

TryBlitScaled(Surface, in Rect<int>, ScaleMode)

Tries to perform a scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitScaled(Surface source, in Rect<int> sourceRect, ScaleMode scaleMode)

Parameters

source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The region specified by sourceRect from the source surface is used and scaled to fit into the entire area of this surface.

TryBlitScaled(Surface, ScaleMode)

Tries to perform a scaled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitScaled(Surface source, ScaleMode scaleMode)

Parameters

source Surface: The source surface to blit from
scaleMode ScaleMode: The scale mode to use for the blit

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The entire source surface is used and scaled to fit into the entire area of this surface.

TryBlitTiled(in Rect<int>, Surface)

Tries to perform a tiled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitTiled(in Rect<int> destinationRect, Surface source)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The entire source surface is used and repeated as many times as needed to completely fill the region specified by destinationRect on this surface.

TryBlitTiled(in Rect<int>, Surface, in Rect<int>)

Tries to perform a tiled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitTiled(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit from

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The region specified by sourceRect from the source surface is used and repeated as many times as needed to completely fill the region specified by destinationRect on this surface.

TryBlitTiled(Surface)

Tries to perform a tiled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitTiled(Surface source)

Parameters

source Surface: The source surface to blit from

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The entire source surface is used and repeated as many times as needed to completely fill the entire area of this surface.

TryBlitTiled(Surface, in Rect<int>)

Tries to perform a tiled blit from a specified source surface to this surface, which maybe of a different format

public bool TryBlitTiled(Surface source, in Rect<int> sourceRect)

Parameters

source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit from

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The region specified by sourceRect from the source surface is used and repeated as many times as needed to completely fill the entire area of this surface.

TryBlitTiledWithScale(in Rect<int>, Surface, in Rect<int>, float, ScaleMode)

Tries to perform a tiled and scaled blit from a specified source surface to this surface with scaling, which maybe of a different format

public bool TryBlitTiledWithScale(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect, float scale, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit from
scale float: The scale to transform the sourceRect into the destinationRect
scaleMode ScaleMode: The scale mode to use

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The scale is applied to the region specified by sourceRect from the source surface, e.g. a 32⨯32 region with a scale of 2 would become a 64⨯64 region. That scaled region is then used and repeated as many times as needed to completely fill the region specified by destinationRect on this surface.

TryBlitTiledWithScale(in Rect<int>, Surface, float, ScaleMode)

Tries to perform a tiled and scaled blit from a specified source surface to this surface with scaling, which maybe of a different format

public bool TryBlitTiledWithScale(in Rect<int> destinationRect, Surface source, float scale, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
scale float: The scale to transform the source into the destinationRect
scaleMode ScaleMode: The scale mode to use

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The scale is applied to the entire source surface, e.g. a 32⨯32 surface with a scale of 2 would become a 64⨯64 region. That scaled region is then used and repeated as many times as needed to completely fill the region specified by destinationRect on this surface.

TryBlitTiledWithScale(Surface, in Rect<int>, float, ScaleMode)

Tries to perform a tiled and scaled blit from a specified source surface to this surface with scaling, which maybe of a different format

public bool TryBlitTiledWithScale(Surface source, in Rect<int> sourceRect, float scale, ScaleMode scaleMode)

Parameters

source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit from
scale float: The scale to transform the sourceRect into this surface
scaleMode ScaleMode: The scale mode to use

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

TryBlitTiledWithScale(Surface, float, ScaleMode)

Tries to perform a tiled and scaled blit from a specified source surface to this surface with scaling, which maybe of a different format

public bool TryBlitTiledWithScale(Surface source, float scale, ScaleMode scaleMode)

Parameters

source Surface: The source surface to blit from
scale float: The scale to transform the source into this surface
scaleMode ScaleMode: The scale mode to use

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

TryBlitUnchecked(in Rect<int>, Surface, in Rect<int>)

Tries to perform a low-level blit from a specified source surface to this surface

public bool TryBlitUnchecked(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit from

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

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

TryBlitUncheckedScaled(in Rect<int>, Surface, in Rect<int>, ScaleMode)

Tries to perform a low-level scaled blit from a specified source surface to this surface

public bool TryBlitUncheckedScaled(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to blit onto
source Surface: The source surface to blit from
sourceRect Rect<int>: The source rectangle on the source surface to blit from
scaleMode ScaleMode: The scale mode to use

Returns

bool: true, if the blit was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

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

TryClear(Color<float>)

Tries to clear the entire surface to the specified color

public bool TryClear(Color<float> color)

Parameters

color Color<float>: The color to clear the surface to. Usually the range for each component is from 0 to 1.

Returns

bool: true, if the surface was successfully cleared; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method handles all surface formats, and ignores any ClippingRect.

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.

TryClear(float, float, float, float)

Tries to clear the entire surface to the specified color

public bool TryClear(float r, float g, float b, float a)

Parameters

r float: The red component value of the color to clear to surface to. Usually in the range from 0 to 1.
g float: The green component value of the color to clear to surface to. Usually in the range from 0 to 1.
b float: The blue component value of the color to clear to surface to. Usually in the range from 0 to 1.
a float: The alpha component value of the color to clear to surface to. Usually in the range from 0 to 1.

Returns

bool: true, if the surface was successfully cleared; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method handles all surface formats, and ignores any ClippingRect.

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.

TryConvert(PixelFormat, Palette?, ColorSpace, Properties?, out Surface?)

Tries to create a copy of this surface converted to the specified format, using the specified palette, color space, and properties

public bool TryConvert(PixelFormat format, Palette? palette, ColorSpace colorSpace, Properties? properties, out Surface? result)

Parameters

format PixelFormat: The pixel format to convert the surface to
palette Palette: An optional palette used for indexed surfaces, or null
colorSpace ColorSpace: The color space to convert the surface to
properties Properties: Additional color properties to use for the converted surface, or null
result Surface: The converted surface, if this method returns true; otherwise, null

Returns

bool: true, if the surface was successfully converted; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method converts an existing surface to a new format and color space and returns the new surface. This will perform any pixel format and color space conversions as needed.

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

TryConvert(PixelFormat, out Surface?)

Tries to create a copy of this surface converted to the specified format

public bool TryConvert(PixelFormat format, out Surface? result)

Parameters

format PixelFormat: The pixel format to convert the surface to
result Surface: The converted surface, if this method returns true; otherwise, null

Returns

bool: true, if the surface was successfully converted; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method 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 you are converting to an indexed surface and want to map colors to a palette, you can use TryConvert(PixelFormat, Palette?, ColorSpace, Properties?, out Surface?) instead.

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

TryConvert(int, int, PixelFormat, ReadOnlyNativeMemory, int, PixelFormat, NativeMemory, int)

Tries to convert a block of pixels to a specified format

public static bool TryConvert(int width, int height, PixelFormat sourceFormat, ReadOnlyNativeMemory source, int sourcePitch, PixelFormat destinationFormat, NativeMemory destination, int destinationPitch)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
source ReadOnlyNativeMemory: The source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The desired pixel format of the destination data
destination NativeMemory: The destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes

Returns

bool: true, if the pixel data was successfully converted; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method additionally returns false if either source or destination are invalid, source.Length is less than; height * sourcePitch, or destination.Length is less than height * destinationPitch.

TryConvert(int, int, PixelFormat, ColorSpace, Properties?, ReadOnlyNativeMemory, int, PixelFormat, ColorSpace, Properties?, NativeMemory, int)

Tries to convert a block of pixels to a specified format, using the specified palette, color space, and properties

public static bool TryConvert(int width, int height, PixelFormat sourceFormat, ColorSpace sourceColorSpace, Properties? sourceProperties, ReadOnlyNativeMemory source, int sourcePitch, PixelFormat destinationFormat, ColorSpace destinationColorSpace, Properties? destinationProperties, NativeMemory destination, int destinationPitch)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
sourceColorSpace ColorSpace: The color space of the source data
sourceProperties Properties: Additional color properties to use for the source data, or null
source ReadOnlyNativeMemory: The source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The desired pixel format of the destination data
destinationColorSpace ColorSpace: The color space of the destination data
destinationProperties Properties: Additional color properties to use for the destination data, or null
destination NativeMemory: The destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes

Returns

bool: true, if the pixel data was successfully converted; otherwise, false (check TryGet(out string?) for more information)

Remarks

TryConvert(int, int, PixelFormat, ColorSpace, Properties?, ReadOnlySpan<byte>, int, PixelFormat, ColorSpace, Properties?, Span<byte>, int)

Tries to convert a block of pixels to a specified format, using the specified palette, color space, and properties

public static bool TryConvert(int width, int height, PixelFormat sourceFormat, ColorSpace sourceColorSpace, Properties? sourceProperties, ReadOnlySpan<byte> source, int sourcePitch, PixelFormat destinationFormat, ColorSpace destinationColorSpace, Properties? destinationProperties, Span<byte> destination, int destinationPitch)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
sourceColorSpace ColorSpace: The color space of the source data
sourceProperties Properties: Additional color properties to use for the source data, or null
source ReadOnlySpan<byte>: The source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The desired pixel format of the destination data
destinationColorSpace ColorSpace: The color space of the destination data
destinationProperties Properties: Additional color properties to use for the destination data, or null
destination Span<byte>: The destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes

Returns

bool: true, if the pixel data was successfully converted; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method additionally returns false if source.Length is less than; height * sourcePitch, or destination.Length is less than height * destinationPitch.

TryConvert(int, int, PixelFormat, ColorSpace, Properties?, void, int, PixelFormat, ColorSpace, Properties?, void, int)

Tries to convert a block of pixels to a specified format, using the specified palette, color space, and properties

public static bool TryConvert(int width, int height, PixelFormat sourceFormat, ColorSpace sourceColorSpace, Properties? sourceProperties, void* source, int sourcePitch, PixelFormat destinationFormat, ColorSpace destinationColorSpace, Properties? destinationProperties, void* destination, int destinationPitch)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
sourceColorSpace ColorSpace: The color space of the source data
sourceProperties Properties: Additional color properties to use for the source data, or null
source void*: A pointer to the source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The desired pixel format of the destination data
destinationColorSpace ColorSpace: The color space of the destination data
destinationProperties Properties: Additional color properties to use for the destination data, or null
destination void*: A pointer to the destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes

Returns

bool: true, if the pixel data was successfully converted; otherwise, false (check TryGet(out string?) for more information)

TryConvert(int, int, PixelFormat, ReadOnlySpan<byte>, int, PixelFormat, Span<byte>, int)

Tries to convert a block of pixels to a specified format

public static bool TryConvert(int width, int height, PixelFormat sourceFormat, ReadOnlySpan<byte> source, int sourcePitch, PixelFormat destinationFormat, Span<byte> destination, int destinationPitch)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
source ReadOnlySpan<byte>: The source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The desired pixel format of the destination data
destination Span<byte>: The destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes

Returns

bool: true, if the pixel data was successfully converted; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method additionally returns false if source.Length is less than; height * sourcePitch, or destination.Length is less than height * destinationPitch.

TryConvert(int, int, PixelFormat, void, int, PixelFormat, void, int)

Tries to convert a block of pixels to a specified format

public static bool TryConvert(int width, int height, PixelFormat sourceFormat, void* source, int sourcePitch, PixelFormat destinationFormat, void* destination, int destinationPitch)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
source void*: A pointer to the source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The desired pixel format of the destination data
destination void*: A pointer to the destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes

Returns

bool: true, if the pixel data was successfully converted; otherwise, false (check TryGet(out string?) for more information)

TryCopyStretched(in Rect<int>, Surface, in Rect<int>, ScaleMode)

Tries to perform a stretched pixel copy from a specified source surface onto this surface

public bool TryCopyStretched(in Rect<int> destinationRect, Surface source, in Rect<int> sourceRect, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to copy onto
source Surface: The source surface to copy from
sourceRect Rect<int>: The source rectangle on the source surface to copy
scaleMode ScaleMode: The scale mode to use for the copy

Returns

bool: true, if the copy was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The region specified by sourceRect from the source surface is copied and stretched to fit into the region specified by destinationRect on this surface.

TryCopyStretched(in Rect<int>, Surface, ScaleMode)

Tries to perform a stretched pixel copy from a specified source surface onto this surface

public bool TryCopyStretched(in Rect<int> destinationRect, Surface source, ScaleMode scaleMode)

Parameters

destinationRect Rect<int>: The destination rectangle on this surface to copy onto
source Surface: The source surface to copy from
scaleMode ScaleMode: The scale mode to use for the copy

Returns

bool: true, if the copy was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The entire source surface is copied and stretched to fit into the region specified by destinationRect on this surface.

TryCopyStretched(Surface, in Rect<int>, ScaleMode)

Tries to perform a stretched pixel copy from a specified source surface onto this surface

public bool TryCopyStretched(Surface source, in Rect<int> sourceRect, ScaleMode scaleMode)

Parameters

source Surface: The source surface to copy from
sourceRect Rect<int>: The source rectangle on the source surface to copy
scaleMode ScaleMode: The scale mode to use for the copy

Returns

bool: true, if the copy was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The region specified by sourceRect from the source surface is copied and stretched to fit into the entire area of this surface.

TryCopyStretched(Surface, ScaleMode)

Tries to perform a stretched pixel copy from a specified source surface onto this surface

public bool TryCopyStretched(Surface source, ScaleMode scaleMode)

Parameters

source Surface: The source surface to copy from
scaleMode ScaleMode: The scale mode to use for the copy

Returns

bool: true, if the copy was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The entire source surface is copied and stretched to fit into the entire area of this surface.

TryCreatePalette(out Palette?)

Tries to create a new Palette for this surface

public bool TryCreatePalette(out Palette? palette)

Parameters

palette Palette: The newly created palette, if this method returns true; otherwise, null

Returns

bool: true, if the palette was created successfully; otherwise, false (e.g. if the surface didn't have an index format, check TryGet(out string?) for more information)

Remarks

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.

Bitmap surfaces (with format Index1Lsb or 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 method is called for on surface that already has a palette, a new palette will be created to replace it.

TryCreateRenderer(out Renderer<Software>?)

Tries to create a new software renderer for this surface

public bool TryCreateRenderer(out Renderer<Software>? renderer)

Parameters

renderer Renderer<Software>: The resulting software renderer, if the method returns true; otherwise, null

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method creates a software renderer that renders directly to this surface.

As such, the resulting renderer won't be associated with any window. You can also create software renderers for Windows using the appropriate methods on a Window instance.

This method should only be called from the main thread.

TryCreateRenderer(out Renderer<Software>?, ColorSpace?, Properties?)

Tries to create a new software renderer for this surface

public bool TryCreateRenderer(out Renderer<Software>? renderer, ColorSpace? outputColorSpace = null, Properties? properties = null)

Parameters

renderer Renderer<Software>: The resulting software renderer, if the method returns true; otherwise, null
outputColorSpace ColorSpace?: The color space to be used by renderer for presenting the output. The Direct3D 11, Direct3D 12, and Metal renderers support SrgbLinear, which is a linear color space and supports HDR output. In that case, drawing still uses the sRGB color space, but individual values can go beyond 1.0 and floating point textures can be used for HDR content. If this parameter is null (the default), the output color space defaults to Srgb.
properties Properties: Additional properties to use when creating the renderer

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method creates a software renderer that renders directly to this surface.

As such, the resulting renderer won't be associated with any window. You can also create software renderers for Windows using the appropriate methods on a Window instance.

This method should only be called from the main thread.

TryDuplicate(out Surface?)

Tries to duplicate this surface

public bool TryDuplicate(out Surface? duplicate)

Parameters

duplicate Surface: The duplicated surface, if this method returns true; otherwise, null

Returns

bool: true, if the surface was duplicated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

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

TryFill(Color<byte>)

Tries to perform a fast fill of the entire surface with the specified color

public bool TryFill(Color<byte> color)

Parameters

color Color<byte>: The color to fill the rectangle with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

surface is simply filled with the A information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the ClippingRect.

TryFill(in Rect<int>, Color<byte>)

Tries to perform a fast fill of a rectangle on this surface with the specified color

public bool TryFill(in Rect<int> destinationRect, Color<byte> color)

Parameters

destinationRect Rect<int>: The rectangle to fill
color Color<byte>: The color to fill the rectangle with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The destinationRect is simply filled with the A information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersection of the ClippingRect and the destinationRect.

TryFill(in Rect<int>, byte, byte, byte)

Tries to perform a fast fill of a rectangle on this surface with the specified color

public bool TryFill(in Rect<int> destinationRect, byte r, byte g, byte b)

Parameters

destinationRect Rect<int>: The rectangle to fill
r byte: The red component value of the color to fill the rectangle with
g byte: The green component value of the color to fill the rectangle with
b byte: The blue component value of the color to fill the rectangle with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The destinationRect is simply filled fully opaque, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersection of the ClippingRect and the destinationRect.

TryFill(in Rect<int>, byte, byte, byte, byte)

Tries to perform a fast fill of a rectangle on this surface with the specified color

public bool TryFill(in Rect<int> destinationRect, byte r, byte g, byte b, byte a)

Parameters

destinationRect Rect<int>: The rectangle to fill
r byte: The red component value of the color to fill the rectangle with
g byte: The green component value of the color to fill the rectangle with
b byte: The blue component value of the color to fill the rectangle with
a byte: The alpha component value of the color to fill the rectangle with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The destinationRect is simply filled with the alpha information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersection of the ClippingRect and the destinationRect.

TryFill(in Rect<int>, uint)

Tries to perform a fast fill of a rectangle on this surface with the specified pixel value

public bool TryFill(in Rect<int> destinationRect, uint pixelValue)

Parameters

destinationRect Rect<int>: The rectangle to fill
pixelValue uint: The pixel value to fill the rectangle with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixelValue argument should be a pixel value of the format used by the surface, and can be generated by MapColor(byte, byte, byte), MapColor(byte, byte, byte, byte), or MapColor(Color<byte>). Alternatively, you can use the TryFill(in Rect<int>, byte, byte, byte), TryFill(in Rect<int>, byte, byte, byte, byte), or TryFill(in Rect<int>, Color<byte>) overloads which will do the mapping for you.

If the color value contains an alpha component then the destinationRect is simply filled with that alpha information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersection of the ClippingRect and the destinationRect.

TryFill(byte, byte, byte)

Tries to perform a fast fill of the entire surface with the specified color

public bool TryFill(byte r, byte g, byte b)

Parameters

r byte: The red component value of the color to fill the surface with
g byte: The green component value of the color to fill the surface with
b byte: The blue component value of the color to fill the surface with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The surface is simply filled fully opaque, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the ClippingRect.

TryFill(byte, byte, byte, byte)

Tries to perform a fast fill of the entire surface with the specified color

public bool TryFill(byte r, byte g, byte b, byte a)

Parameters

r byte: The red component value of the color to fill the surface with
g byte: The green component value of the color to fill the surface with
b byte: The blue component value of the color to fill the surface with
a byte: The alpha component value of the color to fill the surface with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The surface is simply filled with the alpha information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the ClippingRect.

TryFill(ReadOnlySpan<Rect<int>>, Color<byte>)

Tries to perform a fast fill of multiple rectangles on this surface with the specified color

public bool TryFill(ReadOnlySpan<Rect<int>> destinationRects, Color<byte> color)

Parameters

destinationRects ReadOnlySpan<Rect<int>>: The list of rectangles to fill
color Color<byte>: The color to fill the rectangles with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangles in destinationRects are simply filled with the A information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersections of the ClippingRect and each rectangle in destinationRects.

TryFill(ReadOnlySpan<Rect<int>>, byte, byte, byte)

Tries to perform a fast fill of multiple rectangles on this surface with the specified color

public bool TryFill(ReadOnlySpan<Rect<int>> destinationRects, byte r, byte g, byte b)

Parameters

destinationRects ReadOnlySpan<Rect<int>>: The list of rectangles to fill
r byte: The red component value of the color to fill the rectangle with
g byte: The green component value of the color to fill the rectangle with
b byte: The blue component value of the color to fill the rectangle with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangles in destinationRects are simply filled fully opaque, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersections of the ClippingRect and each rectangle in destinationRects.

TryFill(ReadOnlySpan<Rect<int>>, byte, byte, byte, byte)

Tries to perform a fast fill of multiple rectangles on this surface with the specified color

public bool TryFill(ReadOnlySpan<Rect<int>> destinationRects, byte r, byte g, byte b, byte a)

Parameters

destinationRects ReadOnlySpan<Rect<int>>: The list of rectangles to fill
r byte: The red component value of the color to fill the rectangles with
g byte: The green component value of the color to fill the rectangles with
b byte: The blue component value of the color to fill the rectangles with
a byte: The alpha component value of the color to fill the rectangles with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The rectangles in destinationRects are simply filled with the alpha information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersections of the ClippingRect and each rectangle in destinationRects.

TryFill(ReadOnlySpan<Rect<int>>, uint)

Tries to perform a fast fill of multiple rectangles on this surface with the specified pixel value

public bool TryFill(ReadOnlySpan<Rect<int>> destinationRects, uint pixelValue)

Parameters

destinationRects ReadOnlySpan<Rect<int>>: The list of rectangles to fill
pixelValue uint: The pixel value to fill the rectangles with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixelValue argument should be a pixel value of the format used by the surface, and can be generated by MapColor(byte, byte, byte), MapColor(byte, byte, byte, byte), or MapColor(Color<byte>). Alternatively, you can use the TryFill(ReadOnlySpan<Rect<int>>, byte, byte, byte), TryFill(ReadOnlySpan<Rect<int>>, byte, byte, byte, byte), or TryFill(ReadOnlySpan<Rect<int>>, Color<byte>) overloads which will do the mapping for you.

If the color value contains an alpha component then the rectangles in destinationRects are simply filled with that alpha information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the intersections of the ClippingRect and each rectangle in destinationRects.

TryFill(uint)

Tries to perform a fast fill of the entire surface with the specified pixel value

public bool TryFill(uint pixelValue)

Parameters

pixelValue uint: The pixel value to fill the surface with

Returns

bool: true, if the fill operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

The pixelValue argument should be a pixel value of the format used by the surface, and can be generated by MapColor(byte, byte, byte), MapColor(byte, byte, byte, byte), or MapColor(Color<byte>). Alternatively, you can use the TryFill(byte, byte, byte), TryFill(byte, byte, byte, byte), or TryFill(Color<byte>) overloads which will do the mapping for you.

If the color value contains an alpha component then the surface is simply filled with that alpha information, no blending takes place.

If there is a ClippingRect set, then this method will fill based on the ClippingRect.

TryFlip(FlipMode)

Tries to flip the surface according to the specified flip mode

public bool TryFlip(FlipMode flipMode)

Parameters

flipMode FlipMode: The direction to flip the surface

Returns

bool: true, if the surface was flipped successfully; otherwise, false (check TryGet(out string?) for more information)

TryLoadBmp(Stream, out Surface?, bool)

Tries to load a BMP image from a specified stream into a new surface

public static bool TryLoadBmp(Stream source, out Surface? surface, bool closeAfterwards = false)

Parameters

source Stream: The stream to load the BMP image from
surface Surface: The loaded surface, if this method returns true; otherwise, null
closeAfterwards bool: A value indicating whether the source stream should be closed before this method returns (even in case of an error)

Returns

bool: true, if the BMP image was loaded successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The format of the data in the source stream must be BMP, otherwise this method will fail.

Remember to dispose of the resulting surface when you are done with it. Not doing so will result in a memory leak.

TryLoadBmp(string, out Surface?)

Tries to load a BMP image from a specified file into a new surface

public static bool TryLoadBmp(string file, out Surface? surface)

Parameters

file string: A file path to the BMP image to load
surface Surface: The loaded surface, if this method returns true; otherwise, null

Returns

bool: true, if the BMP image was loaded successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The format of the file must be BMP, otherwise this method will fail.

Remember to dispose of the resulting surface when you are done with it. Not doing so will result in a memory leak.

TryLoadPng(Stream, out Surface?, bool)

Tries to load a PNG image from a specified stream into a new surface

public static bool TryLoadPng(Stream source, out Surface? surface, bool closeAfterwards = false)

Parameters

source Stream: The stream to load the PNG image from
surface Surface: The loaded surface, if this method returns true; otherwise, null
closeAfterwards bool: A value indicating whether the source stream should be closed before this method returns (even in case of an error)

Returns

bool: true, if the PNG image was loaded successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The format of the data in the source stream must be PNG, otherwise this method will fail.

This method is intended as a convenience method for loading images from trusted sources. If you want to load arbitrary images you should use an image loading library designed with security in mind.

Remember to dispose of the resulting surface when you are done with it. Not doing so will result in a memory leak.

TryLoadPng(string, out Surface?)

Tries to load a PNG image from a specified file into a new surface

public static bool TryLoadPng(string file, out Surface? surface)

Parameters

file string: A file path to the PNG image to load
surface Surface: The loaded surface, if this method returns true; otherwise, null

Returns

bool: true, if the PNG image was loaded successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The format of the file must be PNG, otherwise this method will fail.

This method is intended as a convenience method for loading images from trusted sources. If you want to load arbitrary images you should use an image loading library designed with security in mind.

Remember to dispose of the resulting surface when you are done with it. Not doing so will result in a memory leak.

TryLock(out SurfacePixelMemoryManager?)

Tries to set up a pixel memory manager for direct pixel access

public bool TryLock(out SurfacePixelMemoryManager? pixelManager)

Parameters

pixelManager SurfacePixelMemoryManager: The pixel memory manager meant to be used to access the surface's pixel memory, if this method returns true; otherwise, null

Returns

bool: true, if the surface was locked successfully and the pixelManager was created; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Surface surface;

...

if (surface.TryLock(out var pixelManager))
{
	using (pixelManager)
	{
		// You can use pixelManager.Memory here to access the surface's pixel memory here

		...
	}
}

Remarks

This method is meant to be used as a simpler and safer alternative to the MustLock - IsLocked - TryUnsafeLock() - UnsafePixels - UnsafeUnlock() pattern.

If the pixelManager was created successfully, you can use its Memory property to read and write the pixel memory of this surface, using this surface's Format. Once you are done accessing the pixel memory, you should dispose the pixelManager to release the surface.

TryPremultiplyAlpha(bool)

Tries to premultiply the alpha channel into the color channels of this surface

public bool TryPremultiplyAlpha(bool linear)

Parameters

linear bool: A value indicating whether to convert from sRGB into linear space to do the alpha multiplication, or to do the multiplication in sRGB space

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

TryPremultiplyAlpha(int, int, PixelFormat, ReadOnlyNativeMemory, int, PixelFormat, NativeMemory, int, bool)

Tries to premultiply the alpha channel into the color channels on a block of pixels

public static bool TryPremultiplyAlpha(int width, int height, PixelFormat sourceFormat, ReadOnlyNativeMemory source, int sourcePitch, PixelFormat destinationFormat, NativeMemory destination, int destinationPitch, bool linear)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
source ReadOnlyNativeMemory: The source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The pixel format of the destination data
destination NativeMemory: The destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes
linear bool: A value indicating whether to convert from sRGB into linear space to do the alpha multiplication, or to do the multiplication in sRGB space

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is safe to use when the source pixel data and the destination pixel data start at the same memory location, but they cannot overlap otherwise.

TryPremultiplyAlpha(int, int, PixelFormat, ReadOnlySpan<byte>, int, PixelFormat, Span<byte>, int, bool)

Tries to premultiply the alpha channel into the color channels on a block of pixels

public static bool TryPremultiplyAlpha(int width, int height, PixelFormat sourceFormat, ReadOnlySpan<byte> source, int sourcePitch, PixelFormat destinationFormat, Span<byte> destination, int destinationPitch, bool linear)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
source ReadOnlySpan<byte>: The source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The pixel format of the destination data
destination Span<byte>: The destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes
linear bool: A value indicating whether to convert from sRGB into linear space to do the alpha multiplication, or to do the multiplication in sRGB space

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is safe to use when the source pixel data and the destination pixel data start at the same memory location, but they cannot overlap otherwise.

This method additionally returns false if source.Length is less than; height * sourcePitch, or destination.Length is less than height * destinationPitch.

TryPremultiplyAlpha(int, int, PixelFormat, void, int, PixelFormat, void, int, bool)

Tries to premultiply the alpha channel into the color channels on a block of pixels

public static bool TryPremultiplyAlpha(int width, int height, PixelFormat sourceFormat, void* source, int sourcePitch, PixelFormat destinationFormat, void* destination, int destinationPitch, bool linear)

Parameters

width int: The width of the block to convert, in pixels
height int: The height of the block to convert, in pixels
sourceFormat PixelFormat: The pixel format of the source data
source void*: A pointer to the source pixel data
sourcePitch int: The pitch of the source pixel data, in bytes
destinationFormat PixelFormat: The pixel format of the destination data
destination void*: A pointer to the destination pixel data
destinationPitch int: The pitch of the destination pixel data, in bytes
linear bool: A value indicating whether to convert from sRGB into linear space to do the alpha multiplication, or to do the multiplication in sRGB space

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is safe to use when the source pixel data and the destination pixel data start at the same memory location, but they cannot overlap otherwise.

TryReadPixel(int, int, out Color<byte>)

Tries to read a single pixel from the surface at the specified coordinates

public bool TryReadPixel(int x, int y, out Color<byte> color)

Parameters

x int: The X coordinate. Must be 0 ≤ x < Width.
y int: The Y coordinate. Must be 0 ≤ y < Height.
color Color<byte>: The color of the pixel, if this method returns true. Uses the entire range from 0 to 255 for each component.

Returns

bool: true, if the pixel was read successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

Like GetColor(uint, Palette?, out Color<byte>), this method uses the entire 8-bit (0-255) range when converting color components from pixel formats with less than 8 bits per RGB component (e.g., a completely white pixel in 16-bit Rgb565 format would return (R, G, B) = (0xff, 0xff, 0xff), not (0xf8, 0xfc, 0xf8))

If the surface has no alpha component, the A value will be returned as 0xff (fully opaque).

TryReadPixel(int, int, out Color<float>)

Tries to read a single pixel from the surface at the specified coordinates

public bool TryReadPixel(int x, int y, out Color<float> color)

Parameters

x int: The X coordinate. Must be 0 ≤ x < Width.
y int: The Y coordinate. Must be 0 ≤ y < Height.
color Color<float>: The color of the pixel, if this method returns true. Usually the range for each component is from 0 to 1.

Returns

bool: true, if the pixel was read successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

If the surface has no alpha component, the A value will be returned as 1 (fully opaque).

TryReadPixel(int, int, out byte, out byte, out byte, out byte)

Tries to read a single pixel from the surface at the specified coordinates

public bool TryReadPixel(int x, int y, out byte r, out byte g, out byte b, out byte a)

Parameters

x int: The X coordinate. Must be 0 ≤ x < Width.
y int: The Y coordinate. Must be 0 ≤ y < Height.
r byte: The red component value of the pixel, if this method returns true. Uses the entire range from 0 to 255.
g byte: The green component value of the pixel, if this method returns true. Uses the entire range from 0 to 255.
b byte: The blue component value of the pixel, if this method returns true. Uses the entire range from 0 to 255.
a byte: The alpha component value of the pixel, if this method returns true. Uses the entire range from 0 to 255.

Returns

bool: true, if the pixel was read successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

Like GetColor(uint, Palette?, out byte, out byte, out byte, out byte), this method uses the entire 8-bit (0-255) range when converting color components from pixel formats with less than 8 bits per RGB component (e.g., a completely white pixel in 16-bit Rgb565 format would return (r, g, b) = (0xff, 0xff, 0xff), not (0xf8, 0xfc, 0xf8)).

If the surface has no alpha component, the alpha component value will be returned as 0xff (fully opaque).

TryReadPixel(int, int, out float, out float, out float, out float)

Tries to read a single pixel from the surface at the specified coordinates

public bool TryReadPixel(int x, int y, out float r, out float g, out float b, out float a)

Parameters

x int: The X coordinate. Must be 0 ≤ x < Width.
y int: The Y coordinate. Must be 0 ≤ y < Height.
r float: The red component value of the pixel, if this method returns true. Usually in the range from 0 to 1.
g float: The green component value of the pixel, if this method returns true. Usually in the range from 0 to 1.
b float: The blue component value of the pixel, if this method returns true. Usually in the range from 0 to 1.
a float: The alpha component value of the pixel, if this method returns true. Usually in the range from 0 to 1.

Returns

bool: true, if the pixel was read successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

If the surface has no alpha component, the alpha component value will be returned as 1 (fully opaque).

TryRotate(float, out Surface?)

Tries to create a copy of this surface rotated clockwise by the specified angle

public bool TryRotate(float angle, out Surface? rotatedSurface)

Parameters

angle float: The angle to rotate the surface clockwise, in degrees
rotatedSurface Surface: The rotated surface, if this method returns true; otherwise, null

Returns

bool: true, if the surface was rotated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The angle of rotation can be negative for counter-clockwise rotation.

When the rotation isn't a multiple of 90°, the resulting surface is larger than the original, with the background filled in with the ColorKey, if available, or the color (R = 255, G = 255, B = 255, A = 0) if not.

If surface has the Rotation property (RotationFloat) set on it, the new copy will have the adjusted value set: if the value of the Rotation property is 90 and angle was 30, the new surface will have a Rotation property value of 60 (that is: to be upright vs. gravity, the surface needs to rotate 60° more). However, note that further rotations on the new surface in this example will produce unexpected results, since the image will have resized and padded to accommodate the not-90° angle.

TrySaveBmp(Stream, bool)

Tries to save the surface as a BMP image to the specified stream

public bool TrySaveBmp(Stream destination, bool closeAfterwards = false)

Parameters

destination Stream: The stream to save the BMP image to
closeAfterwards bool: A value indicating whether the destination stream should be closed before this method returns (even in case of an error)

Returns

bool: true, if the surface was saved successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

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.

TrySaveBmp(string)

Tries to save the surface as a BMP image to the specified file

public bool TrySaveBmp(string file)

Parameters

file string: A file path to save the BMP image

Returns

bool: true, if the surface was saved successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

YUV and paletted 1-bit and 4-bit formats are not supported.

TrySavePng(Stream, bool)

Tries to save the surface as a PNG image to the specified stream

public bool TrySavePng(Stream destination, bool closeAfterwards = false)

Parameters

destination Stream: The stream to save the PNG image to
closeAfterwards bool: A value indicating whether the destination stream should be closed before this method returns (even in case of an error)

Returns

bool: true, if the surface was saved successfully; otherwise, false (check TryGet(out string?) for more information)

TrySavePng(string)

Tries to save the surface as a PNG image to the specified file

public bool TrySavePng(string file)

Parameters

file string: A file path to save the PNG image

Returns

bool: true, if the surface was saved successfully; otherwise, false (check TryGet(out string?) for more information)

TryScale(int, int, ScaleMode, out Surface?)

Tries to create a copy of this surface scaled to the specified width and height

public bool TryScale(int width, int height, ScaleMode scaleMode, out Surface? scaledSurface)

Parameters

width int: The desired width of the scaled surface
height int: The desired height of the scaled surface
scaleMode ScaleMode: The scaling mode to use
scaledSurface Surface: The scaled surface, if this method returns true; otherwise, null

Returns

bool: true if the surface was scaled successfully; otherwise, false

TryUnsafeLock()

Tries to set up the surface for direct pixel access

public bool TryUnsafeLock()

Returns

bool: true, if the surface was locked successfully; otherwise, false (check TryGet(out string?) for more information)

Examples

Example usage:

Surface surface;

...

if (surface.MustLock && surface.TryUnsafeLock())
{
	// It's safe to access surface.UnsafePixels here

	...

	surface.UnsafeUnlock(); 
}

Remarks

It's unsafe to access the UnsafePixels property for surfaces that must be locked and are not currently locked. And it's only safe to do so, if this method returned true.

Between calls to TryUnsafeLock() / UnsafeUnlock(), you can write to and read from UnsafePixels, using the surface's Format. Once you are done accessing the surface, you should use UnsafeUnlock() to release it.

This method is meant to be used as part of the MustLock - IsLocked - TryUnsafeLock() - UnsafePixels - UnsafeUnlock() pattern, if you want to access the surface's pixel memory directly in a faster and more efficient way. If you're looking for a simpler and safer way to access the pixel memory, consider using TryLock(out SurfacePixelMemoryManager?) instead.

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

TryWritePixel(int, int, Color<byte>)

Tries to write a single pixel to the surface at the specified coordinates

public bool TryWritePixel(int x, int y, Color<byte> color)

Parameters

x int: The X coordinate of the pixel. Must be 0 ≤ x < Width.
y int: The Y coordinate of the pixel. Must be 0 ≤ y < Height.
color Color<byte>: The color of the pixel. Uses the entire range from 0 to 255 for each component.

Returns

bool: true, if the pixel was written successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

Like MapColor(Palette?, Color<byte>), this method best approximates a color in the surface's pixel format for the Color<byte>.

If the pixel format has no alpha component, the given A value will be ignored (as it will be in indexed formats with a Palette).

TryWritePixel(int, int, Color<float>)

Tries to write a single pixel to the surface at the specified coordinates

public bool TryWritePixel(int x, int y, Color<float> color)

Parameters

x int: The X coordinate of the pixel. Must be 0 ≤ x < Width.
y int: The Y coordinate of the pixel. Must be 0 ≤ y < Height.
color Color<float>: The color of the pixel. Usually the range for each component is from 0 to 1.

Returns

bool: true, if the pixel was written successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

If the pixel format has no alpha component, the given A value will be ignored (as it will be in indexed formats with a Palette).

TryWritePixel(int, int, byte, byte, byte, byte)

Tries to write a single pixel to the surface at the specified coordinates

public bool TryWritePixel(int x, int y, byte r, byte g, byte b, byte a)

Parameters

x int: The X coordinate of the pixel. Must be 0 ≤ x < Width.
y int: The Y coordinate of the pixel. Must be 0 ≤ y < Height.
r byte: The red component value of the pixel. Uses the entire range from 0 to 255.
g byte: The green component value of the pixel. Uses the entire range from 0 to 255.
b byte: The blue component value of the pixel. Uses the entire range from 0 to 255.
a byte: The alpha component value of the pixel. Uses the entire range from 0 to 255.

Returns

bool: true, if the pixel was written successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

Like MapColor(Palette?, byte, byte, byte, byte), this method best approximates a color in the surface's pixel format for the given RGBA color value.

If the pixel format has no alpha component, the given alpha component value will be ignored (as it will be in indexed formats with a Palette).

TryWritePixel(int, int, float, float, float, float)

Tries to write a single pixel to the surface at the specified coordinates

public bool TryWritePixel(int x, int y, float r, float g, float b, float a)

Parameters

x int: The X coordinate of the pixel. Must be 0 ≤ x < Width.
y int: The Y coordinate of the pixel. Must be 0 ≤ y < Height.
r float: The red component value of the pixel. Usually in the range from 0 to 1.
g float: The green component value of the pixel. Usually in the range from 0 to 1.
b float: The blue component value of the pixel. Usually in the range from 0 to 1.
a float: The alpha component value of the pixel. Usually in the range from 0 to 1.

Returns

bool: true, if the pixel was written successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method prioritizes correctness over speed: it is suitable for unit tests, but is not intended to be used in game engines.

If the pixel format has no alpha component, the given alpha component value will be ignored (as it will be in indexed formats with a Palette).

UnsafeUnlock()

Releases the surface after direct pixel access

public void UnsafeUnlock()

Examples

Example usage:

Surface surface;

...

if (surface.MustLock && surface.TryUnsafeLock())
{
	// It's safe to access surface.UnsafePixels here

	...

	surface.UnsafeUnlock(); 
}

Table of Contents

Class Surface

Remarks

Constructors

Surface(Stream, bool)

Parameters

Remarks

Exceptions

Surface(int, int, PixelFormat)

Parameters

Remarks

Exceptions

Surface(int, int, PixelFormat, NativeMemory, int)

Parameters

Remarks

Exceptions

Surface(int, int, PixelFormat, Memory<byte>, int)

Parameters

Remarks

Exceptions

Surface(int, int, PixelFormat, void*, int)

Parameters

Remarks

Exceptions

Surface(string)

Parameters

Remarks

Exceptions

Properties

AlphaMod

Property Value

Remarks

BlendMode

Property Value

Remarks

Exceptions

ClippingRect

Property Value

Remarks

ColorKey

Property Value

Remarks

Exceptions

ColorMod

Property Value

Remarks

ColorSpace

Property Value

Remarks

Flags

Property Value

Remarks

Format

Property Value

HasAlternateImages

Property Value

HasColorKey

Property Value

HdrHeadroom

Property Value

Remarks

Height

Property Value

HotspotX

Property Value

Remarks

HotspotY

Property Value

Remarks

Images

Property Value

Remarks

IsLocked

Property Value

Remarks

IsPreAllocated

Property Value

Remarks

IsRle

Property Value