Class GraphicsDeviceBase

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

Core half of every device: validates each call against the written rules and the declared capabilities, then hands the backend a call it can execute. Backends derive from it and implement only the *Core members, so ownership, disposal, ranges and capability errors behave identically on every tier.

C#

public abstract class GraphicsDeviceBase : IGraphicsDevice, IDisposable

Inheritance

object ← GraphicsDeviceBase

Derived

ReferenceGraphicsDevice

Implements

IGraphicsDevice, IDisposable

Constructors

GraphicsDeviceBase()

C#

protected GraphicsDeviceBase()

Properties

Capabilities

Declared capabilities.

C#

public abstract GraphicsCapabilities Capabilities { get; }

Property Value

GraphicsCapabilities

CompletedSubmissions

The number of submitted command lists the backend has finished executing. Resources disposed after the n-th submission are released once this reaches n. The default, the number of lists submitted, suits devices that execute a list completely inside Submit; a device that executes later overrides it and calls CollectRetired when work completes.

C#

protected virtual long CompletedSubmissions { get; }

Property Value

long

Counters

Deterministic counts of the work submitted to this device since it was created.

C#

public GraphicsCounters Counters { get; }

Property Value

GraphicsCounters

IsDisposed

True after Dispose.

C#

public bool IsDisposed { get; }

Property Value

bool

PendingReleases

Disposed resources whose backend release still waits for submitted work.

C#

public int PendingReleases { get; }

Property Value

int

Methods

BeginCommands()

Starts an empty command list for this device.

C#

public CommandList BeginCommands()

Returns

CommandList

CollectRetired()

Releases the disposed resources no submitted work uses any more (see CompletedSubmissions).

C#

protected void CollectRetired()

CreateBuffer(in BufferDescription)

C#

public GpuBuffer CreateBuffer(in BufferDescription description)

Parameters

description BufferDescription

Returns

GpuBuffer

CreateBufferCore(in BufferDescription)

Backend: create a validated buffer.

C#

protected abstract 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 abstract Pipeline CreateBuiltInPipelineCore(BuiltInPipeline kind, BlendState blend, TextureFormat colorFormat, TextureFormat? depthFormat)

Parameters

kind BuiltInPipeline

blend BlendState

colorFormat TextureFormat

depthFormat TextureFormat?

Returns

Pipeline

CreatePipeline(PipelineDescription)

Creates a custom pipeline; requires Shaders, and DepthBuffer for depth.

C#

public Pipeline CreatePipeline(PipelineDescription description)

Parameters

description PipelineDescription

Returns

Pipeline

CreatePipelineCore(PipelineDescription)

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

C#

protected abstract Pipeline CreatePipelineCore(PipelineDescription description)

Parameters

description PipelineDescription

Returns

Pipeline

CreateRenderTarget(in RenderTargetDescription)

C#

public RenderTarget CreateRenderTarget(in RenderTargetDescription description)

Parameters

description RenderTargetDescription

Returns

RenderTarget

CreateRenderTargetCore(in RenderTargetDescription)

Backend: create a validated render target.

C#

protected abstract RenderTarget CreateRenderTargetCore(in RenderTargetDescription description)

Parameters

description RenderTargetDescription

Returns

RenderTarget

CreateSamplerCore(in SamplerDescription)

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

C#

protected abstract Sampler CreateSamplerCore(in SamplerDescription description)

Parameters

description SamplerDescription

Returns

Sampler

CreateShader(in ShaderDescription)

C#

public Shader CreateShader(in ShaderDescription description)

Parameters

description ShaderDescription

Returns

Shader

CreateShaderCore(in ShaderDescription)

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

C#

protected abstract Shader CreateShaderCore(in ShaderDescription description)

Parameters

description ShaderDescription

Returns

Shader

CreateTexture(in TextureDescription, ReadOnlySpan<byte>)

C#

public Texture CreateTexture(in TextureDescription description, ReadOnlySpan<byte> initialData = default)

Parameters

description TextureDescription

initialData ReadOnlySpan<byte>

Returns

Texture

CreateTextureCore(in TextureDescription, ReadOnlySpan<byte>)

Backend: create a validated texture.

C#

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

Parameters

description TextureDescription

initialData ReadOnlySpan<byte>

Returns

Texture

Dispose()

Releases backend objects (waiting for the GPU first). Resources disposed later are ignored by the backend.

C#

public void Dispose()

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

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

C#

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

Parameters

builtIns IReadOnlyList<Pipeline>

samplers IReadOnlyList<Sampler>

GetBuiltInPipeline(BuiltInPipeline, BlendState, TextureFormat, TextureFormat?)

Returns the device-owned built-in pipeline for a kind, a blend state and the attachment formats it renders to (every tier; the 2D batcher needs nothing else). A blend state outside BuiltInBlendStates requires CustomBlend.

C#

public Pipeline GetBuiltInPipeline(BuiltInPipeline kind, BlendState blend, TextureFormat colorFormat, TextureFormat? depthFormat = null)

Parameters

kind BuiltInPipeline

blend BlendState

colorFormat TextureFormat

depthFormat TextureFormat?

Returns

Pipeline

GetSampler(in SamplerDescription)

C#

public Sampler GetSampler(in SamplerDescription description)

Parameters

description SamplerDescription

Returns

Sampler

Present()

Presents the acquired surface target (no-op when none was acquired) and expires it.

C#

public void Present()

PresentCore(RenderTarget)

Backend: present and expire the surface target.

C#

protected abstract void PresentCore(RenderTarget surfaceTarget)

Parameters

surfaceTarget RenderTarget

RaiseDeviceLost(DeviceLostReason)

For backends that detect loss.

C#

protected void RaiseDeviceLost(DeviceLostReason reason)

Parameters

reason DeviceLostReason

ReadPixels(RenderTarget, RectI)

Starts reading region of an offscreen target; completes through the returned fence. Surface targets cannot be read: captures render offscreen, read back, then draw the target to the surface.

C#

public ReadbackRequest ReadPixels(RenderTarget target, RectI region)

Parameters

target RenderTarget

region RectI

Returns

ReadbackRequest

ReadPixelsCore(RenderTarget, RectI)

Backend: start a validated readback.

C#

protected abstract ReadbackRequest ReadPixelsCore(RenderTarget target, RectI region)

Parameters

target RenderTarget

region RectI

Returns

ReadbackRequest

Submit(CommandList)

Executes a finished list (no open pass) after every list submitted before it. A list is submitted once.

C#

public void Submit(CommandList commands)

Parameters

commands CommandList

SubmitCore(CommandList)

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

C#

protected abstract void SubmitCore(CommandList commands)

Parameters

commands CommandList

TryAcquireSurfaceTarget(out RenderTarget?)

Acquires this frame’s surface target. False when there is nothing to present to (no surface, minimised, zero size): the frame then skips its surface passes and presentation. The target expires at Present. Its ColorFormat is the format pipelines in its passes must declare; a tier-0 backend, whose built-in pipelines do not depend on the format, reports the nominal format of its back buffer.

C#

public bool TryAcquireSurfaceTarget(out RenderTarget? target)

Parameters

target RenderTarget?

Returns

bool

TryAcquireSurfaceTargetCore()

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

C#

protected abstract RenderTarget? TryAcquireSurfaceTargetCore()

Returns

RenderTarget?

TryGetResource<T>(Handle<GraphicsResource>, out T?)

Finds a live resource of this device by its handle: false once the resource was disposed, even when a new resource reuses its slot, or when it is not a T.

C#

public bool TryGetResource<T>(Handle<GraphicsResource> handle, out T? resource) where T : GraphicsResource

Parameters

handle Handle<GraphicsResource>

resource T?

Returns

bool

Type Parameters

T

DeviceLost

Optional: raised only by backends that can detect loss (SDL_GPU never raises it); resources are marked IsLost.

C#

public event Action<DeviceLostReason>? DeviceLost

Event Type

Action<DeviceLostReason>?