GraphicsAPI reference
Class PixelImage
Namespace: MicroEngine.Graphics
Assembly: MicroEngine.Graphics2D.dll
Guide: Graphics
A CPU-side RGBA image. Games author procedural art with it and hand it to CreateTexture; it also backs the built-in font.
public sealed class PixelImageInheritance
Remarks
Drawing methods change this image and return it, so calls chain; methods that build a new image (Clone, FlipX, Crop…) leave it unchanged. Coordinates outside the image are ignored when writing and read as transparent. Drawing methods alpha-blend unless they say otherwise.
Constructors
PixelImage(int, int)
Creates a fully transparent image.
public PixelImage(int width, int height)Parameters
width int
height int
Exceptions
width or height is not positive.
Properties
Height
Height in pixels.
public int Height { get; }Property Value
Pixels
The pixels, row by row from the top-left.
public ReadOnlySpan<Color> Pixels { get; }Property Value
Width
Width in pixels.
public int Width { get; }Property Value
this[int, int]
The pixel at (x, y). Reading outside the image returns Transparent; writing outside does nothing. Writing replaces the pixel without blending.
public Color this[int x, int y] { get; set; }Property Value
Methods
Blend(int, int, Color)
Alpha-blends color over the existing pixel.
public void Blend(int x, int y, Color color)Parameters
x int
y int
color Color
Blit(PixelImage, int, int, bool)
Copies another image (alpha-blended) with optional horizontal flip.
public PixelImage Blit(PixelImage source, int dx, int dy, bool flipX = false)Parameters
source PixelImage
dx int
dy int
flipX bool
Returns
Blit(PixelImage, int, int, int, int, int, int)
Blends the w × h region of source at (sx, sy) onto this image at (dx, dy).
public PixelImage Blit(PixelImage source, int sx, int sy, int w, int h, int dx, int dy)Parameters
source PixelImage
sx int
sy int
w int
h int
dx int
dy int
Returns
Clear(Color)
Sets every pixel to color, without blending.
public PixelImage Clear(Color color)Parameters
color Color
Returns
ClearRect(int, int, int, int)
Makes a rectangle fully transparent (unlike FillRect, which blends).
public PixelImage ClearRect(int x, int y, int w, int h)Parameters
x int
y int
w int
h int
Returns
Clone()
Returns an independent copy.
public PixelImage Clone()Returns
Crop(int, int, int, int)
Copies a rectangle into a new image; areas outside the source become transparent.
public PixelImage Crop(int x, int y, int width, int height)Parameters
x int
y int
width int
height int
Returns
Decode(ReadOnlySpan<byte>)
Decodes an image file held in memory: PNG (any variant), JPEG (baseline and progressive), BMP, TGA, GIF (its first frame) or PSD (the composited image), recognised by its content rather than a name.
public static PixelImage Decode(ReadOnlySpan<byte> data)Parameters
data ReadOnlySpan<byte>
Returns
Exceptions
The data is not an image in one of those formats.
DrawRect(int, int, int, int, Color)
Draws the one-pixel outline of a rectangle.
public PixelImage DrawRect(int x, int y, int w, int h, Color color)Parameters
x int
y int
w int
h int
color Color
Returns
FillCircle(float, float, float, Color)
Filled circle centred on a pixel-space coordinate (half-pixel centres allowed).
public PixelImage FillCircle(float cx, float cy, float radius, Color color)Parameters
cx float
cy float
radius float
color Color
Returns
FillEllipse(float, float, float, float, Color)
Fills an ellipse centred on (cx, cy) with radii rx and ry.
public PixelImage FillEllipse(float cx, float cy, float rx, float ry, Color color)Parameters
cx float
cy float
rx float
ry float
color Color
Returns
FillRect(int, int, int, int, Color)
Blends color over a w × h rectangle whose top-left is (x, y).
public PixelImage FillRect(int x, int y, int w, int h, Color color)Parameters
x int
y int
w int
h int
color Color
Returns
FitInside(int, int)
The largest size of this image that fits inside maxWidth by maxHeight, keeping its shape (at least 1 by 1).
public (int Width, int Height) FitInside(int maxWidth, int maxHeight)Parameters
maxWidth int
maxHeight int
Returns
FlipX()
Returns a copy mirrored horizontally.
public PixelImage FlipX()Returns
FlipY()
Returns a copy mirrored vertically.
public PixelImage FlipY()Returns
FromMap(IReadOnlyDictionary<char, Color>, params string[])
Creates an image from a character map; the image size is the map size.
public static PixelImage FromMap(IReadOnlyDictionary<char, Color> palette, params string[] rows)Parameters
palette IReadOnlyDictionary<char, Color>
rows string[]
Returns
FromPng(ReadOnlySpan<byte>)
Decodes a PNG: any colour type and bit depth, interlaced or not.
public static PixelImage FromPng(ReadOnlySpan<byte> data)Parameters
data ReadOnlySpan<byte>
Returns
Exceptions
The data is not a PNG the engine can read.
InBounds(int, int)
Whether (x, y) is inside the image.
public bool InBounds(int x, int y)Parameters
x int
y int
Returns
Line(int, int, int, int, Color)
Draws a one-pixel line between two pixels, both included.
public PixelImage Line(int x0, int y0, int x1, int y1, Color color)Parameters
x0 int
y0 int
x1 int
y1 int
color Color
Returns
Load(string)
Loads an image file in any format Decode reads; the message names the path when decoding fails.
public static PixelImage Load(string path)Parameters
path string
Returns
Exceptions
The file does not exist.
The file is not an image the engine can read.
Map(Func<int, int, Color, Color>)
Replaces each pixel with transform(x, y, pixel).
public PixelImage Map(Func<int, int, Color, Color> transform)Parameters
transform Func<int, int, Color, Color>
Returns
OpaqueBounds()
Smallest rectangle containing every pixel with alpha above zero; null when fully transparent.
public (int X, int Y, int Width, int Height)? OpaqueBounds()Returns
(int X, int Y, int Width, int Height)?
Outline(Color, bool)
Adds a 1px outline of color around every opaque region (4-neighbourhood).
public PixelImage Outline(Color color, bool diagonals = false)Parameters
color Color
diagonals bool
Returns
Paint(int, int, IReadOnlyDictionary<char, Color>, params string[])
Paints a character map. Each row is a string; each char is looked up in palette.
Characters missing from the palette (conventionally ‘.’ or ’ ’) are left untouched.
public PixelImage Paint(int dx, int dy, IReadOnlyDictionary<char, Color> palette, params string[] rows)Parameters
dx int
dy int
palette IReadOnlyDictionary<char, Color>
rows string[]
Returns
Recolor(Color, Color)
Replaces every exact from pixel with to.
public PixelImage Recolor(Color from, Color to)Parameters
from Color
to Color
Returns
Resized(int, int)
A copy at width by height pixels. Whole-number enlargements repeat pixels,
so pixel art stays sharp; other sizes average the source area under each pixel (weighted by opacity, so
transparent pixels do not darken edges), so a 1024-pixel icon reduced for a launcher or a start screen keeps its
detail instead of dropping rows.
public PixelImage Resized(int width, int height)Parameters
width int
height int
Returns
Exceptions
A size is not positive.
Rotate90()
Returns a copy rotated 90 degrees clockwise (width and height swap).
public PixelImage Rotate90()Returns
Rotated(float, float, float)
Returns a same-size copy rotated by radians (clockwise on screen) around a pivot,
sampling nearest neighbours so the palette stays intact. Content leaving the canvas is clipped.
Useful for deriving extra poses (e.g. aiming arms) from authored frames.
public PixelImage Rotated(float radians, float pivotX, float pivotY)Parameters
radians float
pivotX float
pivotY float
Returns
Scale2x()
Doubles the image with the Scale2x (EPX) rule: flat areas stay flat while one-pixel stair steps become slopes, so small sprites can be shown at twice the size without looking blocky. Pixels beyond the edge count as copies of the edge pixel.
public PixelImage Scale2x()Returns
Silhouette(Color)
Returns a copy where every visible pixel becomes color (hit flashes, shadows).
public PixelImage Silhouette(Color color)Parameters
color Color
Returns
ToRgba()
Raw RGBA8 bytes, row-major, for backends.
public byte[] ToRgba()Returns
byte[]