Class ReferenceGraphicsDevice

Namespace: MicroEngine.Graphics.Devices
Assembly: MicroEngine.Graphics.dll
Guide: The graphics device

The CPU reference device: a tier-0 implementation of the graphics device contract that executes every written rule literally, in managed code, the same on every machine. It is the oracle the device conformance suite holds backends to and the device headless runs draw with. It favours clarity over speed.

C#

public sealed class ReferenceGraphicsDevice : GraphicsDeviceBase, IGraphicsDevice, IDisposable

Inheritance

object ← GraphicsDeviceBase ← ReferenceGraphicsDevice

Implements

IGraphicsDevice, IDisposable

Inherited Members

GraphicsDeviceBase.CreateTexture(in TextureDescription, ReadOnlySpan<byte>), GraphicsDeviceBase.CreateRenderTarget(in RenderTargetDescription), GraphicsDeviceBase.GetSampler(in SamplerDescription), GraphicsDeviceBase.CreateBuffer(in BufferDescription), GraphicsDeviceBase.CreateShader(in ShaderDescription), GraphicsDeviceBase.CreatePipeline(PipelineDescription), GraphicsDeviceBase.GetBuiltInPipeline(BuiltInPipeline, BlendState, TextureFormat, TextureFormat?), GraphicsDeviceBase.BeginCommands(), GraphicsDeviceBase.Submit(CommandList), GraphicsDeviceBase.ReadPixels(RenderTarget, RectI), GraphicsDeviceBase.TryAcquireSurfaceTarget(out RenderTarget?), GraphicsDeviceBase.Present(), GraphicsDeviceBase.Dispose(), GraphicsDeviceBase.TryGetResource<T>(Handle<GraphicsResource>, out T?), GraphicsDeviceBase.Capabilities, GraphicsDeviceBase.IsDisposed, GraphicsDeviceBase.Counters, GraphicsDeviceBase.PendingReleases, GraphicsDeviceBase.DeviceLost, object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

• Command lists execute completely inside [Submit](/docs/api/microengine.graphics.devices.igraphicsdevice/#MicroEngine_Graphics_Devices_IGraphicsDevice_Submit_MicroEngine_Graphics_Devices_CommandList_); readbacks complete at once.
• Targets store 8-bit channels; every blended value is computed in floating point from the stored 8-bit values, clamped to 0..1 and rounded to the nearest 8-bit value, as GPUs write UNORM targets.
• Coverage follows the top-left rule at pixel centres, with vertex positions snapped to 1/256 pixel (the sub-pixel precision of Direct3D and Vulkan rasterizers).
• Texture coordinates and colours are interpolated linearly (2D: no perspective) at pixel centres. Nearest sampling takes the texel containing the sample point; linear sampling mixes the four nearest texel centres with the sampler's address mode. Minification (more than one texel per pixel along either axis) uses the sampler's minification filter, magnification its magnification filter.
• The surface target, when the device has a non-minimised surface, is a [Bgra8Unorm](/docs/api/microengine.graphics.devices.textureformat/) target of the surface's pixel size; [Present](/docs/api/microengine.graphics.devices.igraphicsdevice/#MicroEngine_Graphics_Devices_IGraphicsDevice_Present) keeps its pixels as [PresentedFrame](/docs/api/microengine.graphics.devices.referencegraphicsdevice/#MicroEngine_Graphics_Devices_ReferenceGraphicsDevice_PresentedFrame).

Declared features: render targets, repeat and mirror addressing, custom blend states and separate filters; no mipmaps, shaders, depth or instancing.

Constructors

ReferenceGraphicsDevice(ISurface?, GraphicsDeviceOptions?)

Creates a reference device, with a surface or offscreen only (surface null).

C#

public ReferenceGraphicsDevice(ISurface? surface = null, GraphicsDeviceOptions? options = null)

Parameters

surface ISurface?

options GraphicsDeviceOptions?

Exceptions

GraphicsCapabilityException

options asks for a present mode it lacks (Mailbox).

Fields

BackendName

The backend name.

C#

public const string BackendName = "reference"

Field Value

string

DeclaredFeatures

The features the reference device declares.

C#

public const GraphicsFeatures DeclaredFeatures = RenderTargets | AddressRepeat | AddressMirror | CustomBlend | SeparateFilters

Field Value

GraphicsFeatures

Properties

Capabilities

Declared capabilities.

C#

public override GraphicsCapabilities Capabilities { get; }

Property Value

GraphicsCapabilities

PresentMode

The present mode chosen at creation (presenting never waits: there is no display).

C#

public PresentMode PresentMode { get; }

Property Value

PresentMode

PresentedFrame

The pixels of the last presented surface target: width, height and tightly packed RGBA bytes (opaque or not, as drawn); null before the first present. Not part of the device contract (surfaces are not read back): headless hosts use it to capture what a window would have shown.

C#

public (int Width, int Height, byte[] Rgba)? PresentedFrame { get; }

Property Value

(int Width, int Height, byte[] Rgba)?

Methods

CreateBufferCore(in BufferDescription)

Backend: create a validated buffer.

C#

protected override GpuBuffer CreateBufferCore(in BufferDescription description)

Parameters

description BufferDescription

Returns

GpuBuffer

CreateBuiltInPipelineCore(BuiltInPipeline, BlendState, TextureFormat, TextureFormat?)

Backend: create a built-in pipeline variant (core caches it).

C#

protected override Pipeline CreateBuiltInPipelineCore(BuiltInPipeline kind, BlendState blend, TextureFormat colorFormat, TextureFormat? depthFormat)

Parameters

kind BuiltInPipeline

blend BlendState

colorFormat TextureFormat

depthFormat TextureFormat?

Returns

Pipeline

CreatePipelineCore(PipelineDescription)

Backend: create a validated custom pipeline (tier 0 is never called: core refuses first).

C#

protected override Pipeline CreatePipelineCore(PipelineDescription description)

Parameters

description PipelineDescription

Returns

Pipeline

CreateRenderTargetCore(in RenderTargetDescription)

Backend: create a validated render target.

C#

protected override RenderTarget CreateRenderTargetCore(in RenderTargetDescription description)

Parameters

description RenderTargetDescription

Returns

RenderTarget

CreateSamplerCore(in SamplerDescription)

Backend: create a validated sampler (core caches it).

C#

protected override Sampler CreateSamplerCore(in SamplerDescription description)

Parameters

description SamplerDescription

Returns

Sampler

CreateShaderCore(in ShaderDescription)

Backend: create a validated shader (tier 0 is never called: core refuses first).

C#

protected override Shader CreateShaderCore(in ShaderDescription description)

Parameters

description ShaderDescription

Returns

Shader

CreateTextureCore(in TextureDescription, ReadOnlySpan<byte>)

Backend: create a validated texture.

C#

protected override Texture CreateTextureCore(in TextureDescription description, ReadOnlySpan<byte> initialData)

Parameters

description TextureDescription

initialData ReadOnlySpan<byte>

Returns

Texture

DisposeCore(IReadOnlyList<Pipeline>, IReadOnlyList<Sampler>)

Backend: release everything, the device-owned built-ins and samplers included.

C#

protected override void DisposeCore(IReadOnlyList<Pipeline> builtIns, IReadOnlyList<Sampler> samplers)

Parameters

builtIns IReadOnlyList<Pipeline>

samplers IReadOnlyList<Sampler>

PresentCore(RenderTarget)

Backend: present and expire the surface target.

C#

protected override void PresentCore(RenderTarget surfaceTarget)

Parameters

surfaceTarget RenderTarget

ReadPixelsCore(RenderTarget, RectI)

Backend: start a validated readback.

C#

protected override ReadbackRequest ReadPixelsCore(RenderTarget target, RectI region)

Parameters

target RenderTarget

region RectI

Returns

ReadbackRequest

SubmitCore(CommandList)

Backend: execute a validated, sealed list after everything submitted before it.

C#

protected override void SubmitCore(CommandList commands)

Parameters

commands CommandList

TryAcquireSurfaceTargetCore()

Backend: acquire this frame’s surface target or return null.

C#

protected override RenderTarget? TryAcquireSurfaceTargetCore()

Returns

RenderTarget?