GraphicsAPI reference
Class DeviceCanvas
Namespace: MicroEngine.Graphics
Assembly: MicroEngine.dll
Guide: The 2D batcher and the camera
A game’s canvas on a graphics device, as backends built on the device contract use it: the canvas render target, the textures (Graphics) and the drawing API (Renderer) over the 2D batcher, the composition of the canvas into the window as the presentation says, and captures read back from the canvas.
public sealed class DeviceCanvas : IDisposableInheritance
Implements
Constructors
DeviceCanvas(IGraphicsDevice, int, int)
Creates a canvas of width × height pixels on device.
public DeviceCanvas(IGraphicsDevice device, int width, int height)Parameters
device IGraphicsDevice
width int
height int
Properties
Device
The device everything is drawn with.
public IGraphicsDevice Device { get; }Property Value
Graphics
The textures of the drawing API, on Device.
public DeviceGraphics Graphics { get; }Property Value
Renderer
The drawing API over the batcher, drawing into Target.
public DeviceRenderer Renderer { get; }Property Value
Target
The canvas: the render target the game draws into.
public RenderTarget Target { get; }Property Value
UiRenderer
The UI view’s renderer of the frame being drawn, or of the last one.
public DeviceRenderer? UiRenderer { get; }Property Value
UiTarget
The UI view’s target (window pixels) once a frame drew a UI; null before.
public RenderTarget? UiTarget { get; }Property Value
Methods
BeginFrame()
Starts drawing a frame into the canvas.
public IRenderer BeginFrame()Returns
BeginUi(int, int, float)
Starts the frame’s UI view: a transparent target of the window’s size in pixels, drawn in UI units of
scale pixels, composited over the world by Compose. Call it after
BeginFrame, at most once per frame.
public IRenderer BeginUi(int pixelWidth, int pixelHeight, float scale)Parameters
pixelWidth int
pixelHeight int
scale float
Returns
Exceptions
The size or the scale is not positive.
Capture()
The canvas as a capture stores it: every pixel opaque (alpha 255), the colour channels as stored.
public PixelImage Capture()Returns
CaptureUi()
The UI view of the last frame as stored (premultiplied, transparent where nothing was drawn), or null.
public PixelImage? CaptureUi()Returns
Compose(Presentation, RectF, Color)
Draws the canvas into the window’s target: the window cleared to letterbox (opaque), then the
canvas copied (its alpha ignored, so a translucent canvas never darkens) into frame with the
presentation’s upscale sampler. Returns false, drawing nothing, when the window has no target this frame
(minimised); the caller then skips presenting.
public bool Compose(Presentation presentation, RectF frame, Color letterbox)Parameters
presentation Presentation
frame RectF
letterbox Color
Returns
Dispose()
Releases the canvas, the batchers and every texture made with Graphics.
public void Dispose()EndFrame()
Submits the frame drawn into the canvas (and the UI view, when the frame drew one).
public void EndFrame()EnsureSize(int, int)
Makes the canvas width × height pixels (an expanding presentation grows it
with the window); a new canvas starts black. Call it between frames.
public bool EnsureSize(int width, int height)Parameters
width int
height int
Returns
Whether the size changed.
SaveCapture(string, int)
Writes Capture as a PNG, each canvas pixel repeated scale times per axis.
public void SaveCapture(string path, int scale)Parameters
path string
scale int