Class HeadlessRenderer

Namespace: MicroEngine.Core
Assembly: MicroEngine.dll
Guide: Game lifecycle and time

Counts draw calls and tracks camera balance so tests can assert rendering ran correctly. Created with a graphics device, it also rasterizes: it records each draw as a line of text (Commands) and draws it on Frame with the CPU reference rasterizer, which follows the engine’s rendering rules exactly.

C#

public sealed class HeadlessRenderer : IRenderer

Inheritance

object ← HeadlessRenderer

Implements

IRenderer

Constructors

HeadlessRenderer(int, int)

A counting renderer: nothing is drawn, every texture of any headless device is accepted.

C#

public HeadlessRenderer(int width, int height)

Parameters

width int

height int

HeadlessRenderer(int, int, HeadlessGraphicsDevice)

A rasterizing renderer for device: it draws only that device’s textures, which must keep their pixels (KeepsPixels).

C#

public HeadlessRenderer(int width, int height, HeadlessGraphicsDevice device)

Parameters

width int

height int

device HeadlessGraphicsDevice

Exceptions

ArgumentException

device does not keep pixels.

Properties

CameraDepth

Cameras pushed and not yet popped.

C#

public int CameraDepth { get; }

Property Value

int

Commands

This frame’s draws as text, one line per call, in screen pixels after the camera offset (a backend-neutral form tests can compare exactly): clear, rect, sprite, circle, triangle, line, blend, clip, camera. Empty when the renderer does not rasterize.

C#

public IReadOnlyList<string> Commands { get; }

Property Value

IReadOnlyList<string>

DrawCalls

Draw calls since the frame began (cleared by Reset).

C#

public int DrawCalls { get; }

Property Value

int

Frame

A copy of the canvas as a capture stores it (opaque), or null when the renderer does not rasterize. The canvas keeps its pixels between frames, as a backend’s does.

C#

public PixelImage? Frame { get; }

Property Value

PixelImage?

Height

Height of the virtual canvas in pixels.

C#

public int Height { get; }

Property Value

int

Rasterizes

Whether this renderer rasterizes (it was created with a graphics device).

C#

public bool Rasterizes { get; }

Property Value

bool

Width

Width of the virtual canvas in pixels.

C#

public int Width { get; }

Property Value

int

Methods

Clear(Color)

Replaces every pixel of the canvas with color, alpha included, whatever the clip (SetClip) and blend mode, and replaces what was drawn before it in the frame. The clip still applies to the draws after it. The game clears to its settings’ Background colour before the scenes draw.

C#

public void Clear(Color color)

Parameters

color Color

Draw(Texture, RectF, Vector2, Color, in DrawOptions)

Counts the call (and rasterizes it); throws ObjectDisposedException for a disposed texture and, when rasterizing, ArgumentException for another device’s texture.

C#

public void Draw(Texture texture, RectF source, Vector2 position, Color tint, in DrawOptions options = default)

Parameters

texture Texture

source RectF

position Vector2

tint Color

options DrawOptions

DrawLine(Vector2, Vector2, float, Color)

Draws a straight line thickness pixels wide. A zero-length line draws nothing.

C#

public void DrawLine(Vector2 from, Vector2 to, float thickness, Color color)

Parameters

from Vector2

to Vector2

thickness float

color Color

DrawStretched(Texture, RectF, RectF, Color)

Counts the call (and rasterizes it), with the checks of Draw.

C#

public void DrawStretched(Texture texture, RectF source, RectF destination, Color tint)

Parameters

texture Texture

source RectF

destination RectF

tint Color

FillCircle(Vector2, float, Color)

Fills a circle; radius is in pixels.

C#

public void FillCircle(Vector2 center, float radius, Color color)

Parameters

center Vector2

radius float

color Color

FillRect(RectF, Color)

Fills a rectangle: the pixels whose centre lies inside it (see the rules of IRenderer). A fully transparent colour draws nothing.

C#

public void FillRect(RectF rect, Color color)

Parameters

rect RectF

color Color

FillTriangle(Vector2, Vector2, Vector2, Color)

Fills a triangle.

C#

public void FillTriangle(Vector2 a, Vector2 b, Vector2 c, Color color)

Parameters

a Vector2

b Vector2

c Vector2

color Color

PopCamera()

Returns to the coordinates in use before the last PushCamera.

C#

public void PopCamera()

Exceptions

InvalidOperationException

No camera was pushed.

PushCamera(Camera2D)

Draws in the world coordinates of camera until PopCamera: its RenderOffset replaces the current offset (cameras do not combine). Every push needs a pop in the same frame.

C#

public void PushCamera(Camera2D camera)

Parameters

camera Camera2D

Reset()

Starts a new frame: clears DrawCalls and Commands, blending returns to Alpha and the clip is removed.

C#

public void Reset()

Exceptions

InvalidOperationException

The previous frame pushed a camera it did not pop.

SetBlendMode(BlendMode)

Sets how later draws combine with the canvas. Every frame starts with Alpha. With source colour s (after the tint), its alpha a and canvas colour d: Alpha writes s·a + d·(1 − a), Additive s·a + d, Multiply s·a·d + d·(1 − a) (the colour multiplies the canvas in proportion to its opacity), each channel clamped to 0..1.

C#

public void SetBlendMode(BlendMode mode)

Parameters

mode BlendMode

SetClip(RectF?)

Restricts drawing to a screen-space rectangle (the camera does not move it); pass null to remove. X, Y, Width and Height are truncated to whole pixels. Clear ignores the clip.

C#

public void SetClip(RectF? screenRect)

Parameters

screenRect RectF?